Add Creative Mode + browser TTS + multi-day timeline + emotion heatmap + 3 new towns

SUBMISSION_BLOG.md

@@ -4,13 +4,13 @@
 
 > **Live Space:** https://huggingface.co/spaces/build-small-hackathon/analog-town
 > **Model:** `Qwen/Qwen2.5-7B-Instruct` (fallback: `Qwen/Qwen2.5-14B-Instruct`)
-> **SDK:** Gradio · CPU-basic · ~16 MB Space
+> **SDK:** Gradio · CPU-basic · browser-side TTS, no GPU required
 
 ---
 
 ## The Pitch in One Paragraph
 
-You drop a single piece of news into a fictional town — *"the old grain silo will be demolished next month"* — and the town reacts. Six residents each have their own values, fears, hopes, and grudges. Instead of chatting with them, you tune an analog radio dial through static and intercept their inner monologues one frequency at a time. That is **Analog Town**: a tabletop-style perspective-rehearsal tool dressed up as a 1970s shortwave receiver.
+You drop a single piece of news into a fictional town — *"the old grain silo will be demolished next month"* — and the town reacts. Six residents each have their own values, fears, hopes, and grudges. Instead of chatting with them, you tune an analog radio dial through static and **hear** each resident's inner monologue in a different voice. The next day, you broadcast a follow-up. The town remembers. The map slowly drifts — angry, hopeful, suspicious. That is **Analog Town**: a perspective-rehearsal tool dressed up as a 1970s shortwave receiver, run by a 7B model with a typed state machine glued behind it.
 
 ---
 
@@ -18,12 +18,13 @@ You drop a single piece of news into a fictional town — *"the old grain silo w
 
 Writers, tabletop RPG game masters, classroom debate moderators, and community planners all share the same workflow problem: when something new lands in a fictional community — a factory closing, a sacred grove being bisected, a stranger arriving — they have to **mentally simulate every stakeholder's reaction** to make the story (or the policy roleplay) feel honest.
 
-The usual fallback is to open a chat window and ask a large model to roleplay each character one by one. That works, but it has two failure modes:
+The usual fallback is to open a chat window and ask a large model to roleplay each character one by one. That works, but it has three failure modes:
 
 1. The model collapses every character into the same voice within a few turns.
 2. You get vivid prose but no **structured signal** about what each character noticed, what they feared, or which value got triggered.
+3. There's no sense of *time* — every prompt is a one-shot, never a multi-day arc.
 
-We wanted a tool that pushed in the opposite direction: **small model, structured output, whimsical interface**. A signal node, not a conversation.
+We wanted a tool that pushed in the opposite direction: **small model, structured output, whimsical interface, time built in**. A signal node, not a conversation.
 
 ---
 
@@ -32,7 +33,7 @@ We wanted a tool that pushed in the opposite direction: **small model, structure
 Under the hood, Analog Town is not roleplay. Each character is a **typed Pydantic state machine**, and the model's only job is to compute one well-defined transition:
 
 ```
-(Agent Profile + Previous Agent State + Broadcast Event)
+(Agent Profile + Previous Agent State + Broadcast Event + Day N)
         → Updated Agent State + Internal Monologue + Likely Actions
 ```
 
@@ -48,9 +49,39 @@ Every transition returns a strict JSON object (see `schemas.py`) with fields lik
 - `uncertainty` — what the model itself isn't sure about
 - `safety_note` — a fixed disclaimer that this is fictional rehearsal, not prediction
 
-The system prompt is uncompromising: *"Your job is not to produce the most dramatic answer. Your job is to produce a plausible, grounded, internally consistent state transition."* If the JSON comes back malformed, a second pass through a dedicated `REPAIR_PROMPT` rewrites it cleanly.
+The system prompt is uncompromising: *"Your job is not to produce the most dramatic answer. Your job is to produce a plausible, grounded, internally consistent state transition."* If the JSON comes back malformed, a dedicated `REPAIR_PROMPT` rewrites it cleanly.
 
-This is the design lever that lets a **7B model** carry a six-character simulation: we never ask it to generate freely, we ask it to fill a tightly-shaped form.
+This is the design lever that lets a **7B model** carry a six-character, multi-day simulation: we never ask it to generate freely, we ask it to fill a tightly-shaped form.
+
+---
+
+## What's New This Build (the headline features)
+
+The hackathon push added five differentiators on top of the original single-shot prototype.
+
+### 🔥 1. Emotion heatmap on the map
+
+After every broadcast, each sprite's avatar ring tints to that character's dominant emotion: red for anger, orange for fear, amber for hope, green for trust, blue for curiosity, purple for social energy. The map becomes a glanceable **mood report** — you can see at a single look which way each resident bent.
+
+### 📢 2. Anomaly flags
+
+If any axis of an agent's `emotion_delta` swings by more than 0.6 in a single broadcast, a pulsing 📢 badge appears on their sprite. Writers and GMs use this to spot dramatic story beats automatically — these are the residents whose minds just lurched.
+
+### 🎙 3. Browser-side TTS through the radio static
+
+Tune the dial to an agent or click their sprite, and a distinct voice **speaks their monologue aloud** through the existing ambient-static loop. The static smoothly ducks while the voice plays and swells back up when it ends. Each character gets a deterministically-picked voice from a curated pool of 30+ system voices (male/female, with pitch shifts for elder/young characters), so Margaret the retired stationmaster doesn't sound like Devon the line cook.
+
+We chose browser-side `SpeechSynthesisUtterance` over an HF Inference TTS endpoint for three reasons: zero latency, zero rate-limit risk, and zero GPU cost — true to the "build small" spirit.
+
+### 📅 4. Day-N chained broadcasts + timeline
+
+Today's most differentiating feature. Press **TRANSMIT** once for Day 1. Press it again — agents continue from their post-Day-1 emotional state, with a prompt prefix that tells the model *"this is Day 2, do not echo what they said last time."* A small horizontal **timeline strip** shows each broadcast as a clickable pill (`DAY 1 · Hotel announcement · ⚠ 2 anomalies`). The map heatmap visibly drifts day over day. Click any past pill to time-travel: the map reverts to that day's state, the slider re-tunes through that day's monologues, the day badge updates. A 🔁 **RESET** button next to TRANSMIT clears the chain back to Day 1.
+
+This turns a one-shot rehearsal into a **multi-day arc**. Day 1: "the factory will reopen." Day 3: "wages will be 30% lower than last time." Day 5: "first walkout scheduled." Watch each character's mood lurch across the map.
+
+### 🎨 5. Creative Mode — design your own town
+
+Open the **🎨 CREATIVE MODE** accordion, type a 1–3 sentence concept (*"a haunted seaside lighthouse where the keeper has vanished and the village is split on whether to investigate"*), pick how many residents you want (3–6), and hit **🪄 GENERATE WITH AI**. Qwen 2.5 7B drafts a complete, schema-validated `Town` JSON — full agent dossiers, frequencies, map positions, relationships, and a default broadcast event. You can edit the JSON inline, upload a custom map PNG, then **💾 SAVE & LOAD** to register the town and start broadcasting. Frequencies are auto-spread, sprite positions clamped, and the town gets a `custom_` prefix so it never overwrites a preset.
 
 ---
 
@@ -58,13 +89,13 @@ This is the design lever that lets a **7B model** carry a six-character simulati
 
 The interface is the point. Analog Town is built to feel like the inside of a beat-up radio van parked at the edge of a town you don't live in.
 
-**The CRT theme.** A custom Gradio CSS theme (`theme.py`) renders the whole app in amber-and-green phosphor type on pitch-black cards, with scanning-line overlays and glowing horizontal signal-strength bars. IBM Plex Mono for instrument readouts, Crimson Pro for monologues — the typography itself splits "machine talking" from "human talking".
+**The CRT theme.** A custom Gradio CSS theme renders the whole app in amber-and-green phosphor type on pitch-black cards, with scanning-line overlays and glowing horizontal signal-strength bars. IBM Plex Mono for instrument readouts, Crimson Pro for monologues — the typography itself splits "machine talking" from "human talking."
 
-**The dial.** A frequency slider runs from 87.0 to 108.0 FM. Each character lives on a fixed frequency. As you slide closer to a station, the signal-strength bar climbs and the corresponding character's dossier and monologue come into focus.
+**The dial.** A frequency slider runs from 87.0 to 108.0 FM. Each character lives on a fixed frequency. As you slide closer to a station, the signal-strength bar climbs, the corresponding character's dossier comes into focus, and their voice fades in through the static.
 
-**The static.** We loop a 15-second analog hiss and low-hum bed (`static_ambient.wav`) underneath everything. A small client-side JavaScript audio manager watches the signal-strength value and **smoothly fades the static out** when you tune into a station and **fades it back in** when you scan between them — all in the browser, no server roundtrip.
+**The static.** A loopable 15-second analog hiss bed lives under everything. A small client-side audio manager watches the signal-strength value and **smoothly fades the static out** when you tune into a station, then back in when you scan between them — and ducks further whenever a voice is speaking.
 
-**The map.** Six town presets each ship with a custom 2D isometric pixel-art background:
+**The map.** Nine town presets each ship with a custom 2D isometric pixel-art background, each representing a unique narrative conflict:
 
 - **Graybridge** — a foggy mill town arguing about a luxury hotel conversion
 - **Neighborhood Council** — a suburban block meeting about a 5G tower
@@ -72,33 +103,35 @@ The interface is the point. Analog Town is built to feel like the inside of a be
 - **Brimstone Hollow** — a desert outpost rattled by an unexplained sinkhole
 - **Echo Summit** — a polar research station picking up a strange signal
 - **Rustwood** — a rust-belt town whose factory just announced reopening
+- **Tin Lantern Junction** — a sun-bleached Route 66 stopover town facing an autonomous-truck depot
+- **Lotus Wharf** — a SE Asian floating river-market village threatened by a bridge that bypasses the market
+- **Verdant Spire** — a near-future solarpunk vertical city where a bonded municipal AI has just filed for mayor
 
-Characters are placed on the map as circular pixel-art tokens drawn from a small avatar set (`elder_man.png`, `young_woman.png`, `soldier_man.png`, …) chosen to match the persona's age and role. Clicking a token tunes the receiver to that character's frequency, swaps in their dossier, and starts streaming their latest intercepted thought.
+Characters are placed on each map as circular pixel-art tokens. Clicking a token tunes the receiver, swaps in their dossier, and starts speaking their latest intercepted thought.
 
 ---
 
-## A Walkthrough: One Broadcast, Six Reactions
+## A Walkthrough: Three Days, One Town
 
-You load **Graybridge** — six residents, one foggy map. You type into the broadcast box:
+You load **Port Whisper** — a coastal fishing village. Four residents, one foggy harbor map. The broadcast box pre-fills with the town's default scenario:
 
-> *"The old train station will be converted into a luxury hotel."*
+> *Day 1: "The state energy department has approved the construction of a 40-turbine offshore wind array, 5 miles off the Port Whisper coast."*
 
-You hit **Broadcast**. The simulator iterates through every agent, calls the model once per character with their profile and current emotional state, and parses the structured JSON back into the UI. You hear the static swell as the dial idles at 91.3 MHz.
+You hit **TRANSMIT**. Four model calls run, four typed transitions come back. The map sprites tint: Captain Arthur (the elder fisherman) goes red, Mayor Sarah (the pragmatist) goes amber, Chloe (the marine biologist) goes blue. A 📢 badge pulses on Captain Arthur — his emotional delta exceeded 0.6.
 
-You scroll the dial up to **98.7 MHz** — *Margaret, the retired stationmaster*. The static fades. Her dossier loads: 67 years old, grew up watching the trains, lost her husband the year the line was shut down. Her monologue scrolls onto the CRT panel:
+You tune to **89.1 MHz** — the static fades and Captain Arthur's voice comes through:
 
-> *"They're putting a bar where the ticket window used to be. I knew this was coming. I just didn't think they'd bother pretending it was good news."*
+> *"They're putting iron in my ocean. They didn't ask. They didn't visit. They never do."*
 
-`activated_memory`: *the night the last train left in 1998*.
-`value_conflict`: *preservation of working-class history vs. economic survival of the town*.
-`emotion_delta`: `trust: -0.15, anger: +0.20, hope: -0.10`.
-`likely_public_action`: *"Write a letter to the council. Sign it 'M. Halloran, retired.'"*
+You change the broadcast text for Day 2 to *"The state has scheduled a public hearing at the harbor next Friday and is offering union-scale jobs in turbine maintenance."* You TRANSMIT again. Now the prompt carries `DAY 2`, the temperature bumps up slightly, and the explicit instruction tells the model *don't echo prior beats.*
 
-You scan up to **102.1 MHz** — *Devon, a 24-year-old line cook*. Same broadcast, completely different read:
+The map redraws. Captain Arthur is still red but the anomaly badge is gone (his delta this round was smaller). Mayor Sarah turned green — trust climbing. A new `DAY 2` pill appears in the timeline strip and the map's day badge updates.
 
-> *"Wait, like, a real hotel? Could I get a job there? Could I stop driving 40 minutes for a kitchen shift?"*
+You tune back to Arthur:
 
-Same event. Same town. Two minds. The dial keeps going.
+> *"A hearing. I've sat through a hundred hearings. But maintenance jobs — that's the first thing they've said that sounds like remembering us."*
+
+You click the `DAY 1` pill — the map snaps back to Day 1's heatmap and Arthur's Day 1 voice returns. Click `DAY 2` to come back. Press 🔁 **RESET** to clear the chain.
 
 ---
 
@@ -106,15 +139,13 @@ Same event. Same town. Two minds. The dial keeps going.
 
 Analog Town was engineered against the **Build Small Hackathon** constraints from the first commit:
 
-1. **Models under 32B.** We use `Qwen/Qwen2.5-7B-Instruct` as the primary inference target through the Hugging Face Inference Client, with `Qwen/Qwen2.5-14B-Instruct` as an automatic fallback if rate limits hit. Both are comfortably under the 32B parameter cap. The fallback chain lives in `model_client.py` and is transparent to the rest of the app.
-
-2. **Structured generation beats brute force.** Because every model call is shaped by a Pydantic schema and a strict system prompt, we can run a full town reaction (6 characters) on a small model without losing coherence. We deliberately keep `max_tokens=900` and `temperature=0.3`.
-
-3. **Client-side audio.** The radio static fade is computed in the browser from the signal-strength value. Zero server-side audio processing, zero extra latency.
-
-4. **Static map assets.** Each town's pixel-art map is a single PNG. Character tokens are static avatars composed on top via CSS positioning. The Gradio app runs comfortably on `cpu-basic` hardware.
-
-5. **Inspectable exports.** Every simulation run can be exported as a Hugging Face-compatible dataset (`town.json`, `broadcast_event.json`, `agent_traces.jsonl`, auto-generated dataset card). Naive PII patterns are stripped during export (`export_hub.py`), and a safety note is attached to every transition.
+1. **Models under 32B.** We use `Qwen/Qwen2.5-7B-Instruct` as the primary inference target through the Hugging Face Inference Client, with `Qwen/Qwen2.5-14B-Instruct` as an automatic fallback if rate limits hit.
+2. **Structured generation beats brute force.** Because every model call is shaped by a Pydantic schema and a strict system prompt, we run a full town reaction (4–6 characters) on a small model without losing coherence. We keep `max_tokens=900` and `temperature=0.3` for Day 1, ramping to ~0.55 for chained days to encourage variation without losing JSON discipline.
+3. **Browser-side TTS.** We use `window.speechSynthesis` instead of a server-side TTS endpoint. Zero GPU, zero rate-limits, instant playback, distinct per-character voices.
+4. **Client-side audio mixing.** Static fade is computed in JavaScript from the signal-strength bars. Voice ducking is handled the same way. Zero server-side audio processing.
+5. **Static map assets.** Each town's pixel-art map is a single PNG; sprite tokens are static avatars composed on top via CSS. The Gradio app runs comfortably on `cpu-basic` hardware.
+6. **AI-generated towns reuse the same model.** Creative Mode's town generation uses the *same* `Qwen 2.5 7B` endpoint as the simulator — no separate model, no separate inference path.
+7. **Inspectable exports.** Every simulation run can be exported as a Hugging Face-compatible dataset (`town.json`, `broadcast_event.json`, `agent_traces.jsonl`, auto-generated dataset card). Naive PII patterns are stripped during export, and a safety note is attached to every transition.
 
 ---
 
@@ -122,22 +153,19 @@ Analog Town was engineered against the **Build Small Hackathon** constraints fro
 
 - **No persistent chat.** Each broadcast is one transition. The simulator is a *rehearsal*, not a relationship.
 - **No "predict the real person" mode.** The prompts explicitly forbid revealing hidden facts not in the profile, and the system prompt refuses to treat output as factual prediction.
-- **No multi-turn drift.** Because the model never sees its own prior monologue as context — only the last *structured* state — we sidestep the slow voice-collapse problem of long roleplay sessions.
-
----
-
-## What We'd Love Feedback On
-
-- **Whimsy density.** Is the radio metaphor doing real work for you, or is it set dressing? We want it to feel like an *instrument*, not a costume.
-- **Town presets.** Which of the six conflicts pulls you in fastest? We'll lean into that one next.
-- **The structured trace panel.** We currently surface the monologue prominently and the JSON deltas in a collapsible "trace" view. Should the deltas be more visible by default for GMs / writers who want the mechanical readout?
+- **No multi-turn voice drift.** Because the model never sees its own prior monologue as direct context — only the last *structured* state — we sidestep the slow voice-collapse problem of long roleplay sessions.
 
 ---
 
 ## Try It
 
-🎙️ **Tune in:** https://huggingface.co/spaces/build-small-hackathon/analog-town
+🎙 **Tune in:** https://huggingface.co/spaces/build-small-hackathon/analog-town
 
-Pick a town. Type a piece of news. Slide the dial. Listen.
+1. Click anywhere once (unlocks ambient audio + browser TTS).
+2. Pick a town (or open **🎨 CREATIVE MODE** and generate your own).
+3. Type a broadcast.
+4. TRANSMIT. Watch the map tint.
+5. Tune the dial. Listen.
+6. TRANSMIT again. Watch the town drift.
 
 *Analog Town is not a chatbot. It's a tiny social weather station for fictional worlds.*

VIDEO_SCRIPT.md

@@ -1,21 +1,23 @@
-# Analog Town — Demo Video Script
+# Analog Town — Demo Video Script (v2, with TTS / Heatmap / Timeline / Creative Mode)
 
-**Target length:** 2 min 30 sec (hard cap 3 min)
+**Target length:** 3 min (hard cap 3 min 30 sec)
 **Tone:** Calm, slightly conspiratorial — like you really are operating a radio van. Don't oversell. Let the interface do the work.
-**Recording tip:** Use OBS or QuickTime. Capture system audio so the static loop is audible. Set browser zoom to 110% so the CRT panel reads on mobile playback.
+**Recording tip:** Use OBS or QuickTime. Capture system audio so the static loop *and the spoken monologues* are audible. Set browser zoom to 110% so the CRT panel reads on mobile playback.
 
 ---
 
 ## Pre-Recording Checklist
 
-- [ ] App is running and loaded — Space cold-starts can take 30s, warm it up first
-- [ ] Browser window sized 1440×900, zoom 110%
-- [ ] System volume on (so static fade is audible in the recording)
-- [ ] Pick the town: **Graybridge** (best demo because the conflict is instantly legible)
-- [ ] Pre-write the broadcast text in a notes window so you don't fumble typing on camera:
-      *"The old train station will be converted into a luxury hotel."*
-- [ ] Have a second pre-written broadcast ready as a backup:
-      *"The town council just approved a 5G tower on the school roof."*
+- [ ] App is running and **loaded once in this browser session** — TTS unlocks on first click, ambient audio unlocks on first interaction. Click anywhere before recording.
+- [ ] Browser window sized 1440×900, zoom 110%, DevTools closed
+- [ ] System volume on, **headphones recommended** so you can hear the static fade and voice ducking
+- [ ] Pick the town: **Port Whisper** (best demo because the wind-farm conflict has clear sides and the heatmap is dramatic)
+- [ ] Pre-write the broadcasts in a notes window — you'll paste them in:
+  - **Day 1:** *"The state energy department has approved the construction of a 40-turbine offshore wind array, 5 miles off the Port Whisper coast."*
+  - **Day 2:** *"The state has scheduled a public hearing at the harbor next Friday and is offering union-scale jobs in turbine maintenance."*
+  - **Day 3 (optional):** *"Protesters blocked the harbor entrance at dawn. Two arrested. The mayor calls for calm."*
+- [ ] Pre-write the **Creative Mode concept** for the closing demo:
+  *"A haunted seaside lighthouse where the keeper has vanished. The village is split on whether to investigate or burn it to the ground."*
 - [ ] Close all other tabs / Slack / notifications
 - [ ] Mic check — say a sentence, play it back, then start
 
@@ -27,119 +29,152 @@
 
 **You say:**
 
-> "This is Analog Town. It's a shortwave radio that picks up the inside of fictional people's heads. You drop a piece of news into a town — and you tune the dial to find out what each resident is privately thinking about it."
+> "This is Analog Town. It's a shortwave radio that picks up the inside of fictional people's heads. You drop a piece of news into a town — and you tune the dial to hear what each resident is privately thinking about it. Listen."
 
 **Action:** Slowly drag the frequency slider 1–2 ticks while talking. Let the static crackle change pitch. Don't land on a station yet.
 
 ---
 
-## Scene 2 — The Setup (0:15 – 0:35)
+## Scene 2 — Meet the Town (0:15 – 0:35)
 
-**On screen:** Open the town selector dropdown. Pause on it just long enough that the six options are readable.
+**On screen:** Open the **TOWN** dropdown. Pause on it just long enough that the nine options are readable. Pick **Port Whisper**.
 
 **You say:**
 
-> "We ship six fictional towns, each with a built-in conflict. There's a mill town arguing about gentrification, a coastal village debating an offshore wind farm, a polar research station that just picked up a strange signal. I'll load Graybridge."
+> "We ship nine towns, each with a built-in conflict. A coastal village debating a wind farm, a polar research station picking up a strange signal, a near-future vertical city where a municipal AI just filed for mayor. I'll load Port Whisper."
 
-**Action:** Click **Graybridge**. Wait for the isometric map to load with the pixel-art character tokens placed on it.
+**Action:** Click **Port Whisper**. Wait for the isometric map to load with the four pixel-art character tokens placed on it. The dossier accordion shows below the map.
 
 ---
 
-## Scene 3 — Meet the Town (0:35 – 0:55)
+## Scene 3 — Day 1 Broadcast (0:35 – 1:05)
 
-**On screen:** The Graybridge isometric map is visible. Six circular character avatars sit on it.
+**On screen:** The broadcast field has pre-filled with the default scenario. Move to it.
 
 **You say:**
 
-> "Graybridge has six residents. Each one is a typed agent with their own values, fears, hopes, and private history. They each broadcast on their own FM frequency."
+> "Day 1. A wind farm is approved off the coast. I broadcast it into the town."
 
-**Action:** Hover slowly over two or three avatars. If hovering shows a name/role tooltip, pause on each for ~1.5 seconds. Don't click yet — you're building anticipation.
+**Action:** Press **TRANSMIT**. While the progress bar runs in the status panel:
+
+**You say (~10 seconds of cover narration):**
+
+> "Behind the scenes, this is Qwen 2.5 7B through the Hugging Face Inference API. Each resident is processed as a typed state transition — not roleplay — so the model produces structured JSON: what the character noticed, which memory got triggered, which value got bruised, and how their emotional state shifted."
+
+**On screen:** Simulation completes. The four sprites visibly **tint by emotion** — red on Captain Arthur, amber on Mayor Sarah, blue on Chloe, etc. A pulsing **📢 anomaly badge** appears on at least one sprite. A `DAY 1` pill appears in the timeline strip and a `DAY 1` badge in the corner of the map.
+
+**You say:**
+
+> "The map just tinted. Red means anger, amber is hope, green is trust, blue is curiosity. That badge — the megaphone — means this character's emotional state shifted by more than 60 percent on at least one axis. Big reaction. Worth tuning in to."
 
 ---
 
-## Scene 4 — The Broadcast (0:55 – 1:15)
+## Scene 4 — Tune the Dial, Hear the Voice (1:05 – 1:35)
 
-**On screen:** Move to the broadcast input box.
+**On screen:** Move the cursor to the frequency slider.
 
 **You say:**
 
-> "I'm going to broadcast something into the town. Watch what happens."
+> "Now I tune the dial."
+
+**Action:** Slowly drag the dial up toward **Captain Arthur Vance** (around 89.1 MHz). As you approach, the **signal-strength bar climbs and the static audibly fades**. Land on his station. The dossier loads. His monologue appears in the CRT panel.
 
-**Action:** Type (or paste) the broadcast:
+**Important:** Don't read the monologue aloud yourself. **Wait.** The browser TTS will speak it in a distinct voice over the (now-quiet) static. Stay silent for the ~6 seconds it takes.
 
-> *The old train station will be converted into a luxury hotel.*
+**On screen:** The 🔊 voice LED next to the VOICE button flashes green while the voice plays. Static ducks under the voice.
 
-Click **Broadcast**.
+**After it finishes, you say:**
 
-**You say (while it's computing):**
+> "Different voice for every character. The static ducks under them. And under every monologue is the structured trace — the emotion deltas, the activated memory, the value conflict — so writers and game masters don't just get prose, they get a mechanical readout of *why* this character reacted this way."
 
-> "Behind the scenes, this is running on Qwen 2.5 7B through the Hugging Face Inference API. Each resident is processed as a typed state transition — not roleplay — so the model produces structured JSON: what the character noticed, which memory got triggered, which value got bruised, and how their emotional state shifted. Then it writes one short internal monologue in their voice."
+**Action:** Click directly on a different sprite on the map (e.g., **Chloe Chen**, the marine biologist). The dial snaps to her frequency, the dossier swaps, her voice — distinctly different from Arthur's — speaks her monologue.
+
+**You say (while her voice plays):**
+
+> "Same broadcast. Different mind."
 
 ---
 
-## Scene 5 — Tune the Dial (1:15 – 1:50)
+## Scene 5 — Day 2 Drift (1:35 – 2:20)
 
-**On screen:** The broadcast finished. The CRT panel is ready to show transitions.
+**On screen:** Move to the broadcast text box. Clear the existing content. Paste Day 2's broadcast.
 
 **You say:**
 
-> "Now I tune in."
+> "Now the second day. Same town. Different beat."
 
-**Action:** Slowly drag the frequency dial up toward Margaret's station (around 98.7 MHz, whatever the actual frequency is). As you approach, the **signal-strength bar climbs and the static audibly fades**. Stop right on her station.
+**Action:** Press **TRANSMIT**. While it runs:
 
-**On screen:** Margaret's dossier loads. Her monologue prints onto the CRT panel.
+**You say:**
 
-**You say (read the monologue out loud, or paraphrase if it's long):**
+> "The agents don't reset. Their Day 1 emotional state becomes the seed for Day 2 — the simulator carries the drift forward. And I'm telling the model explicitly: *do not echo what they said yesterday.*"
 
-> "Margaret. 67. Retired stationmaster. She remembers the night the last train left in 1998. Listen to what she heard."
+**On screen:** Simulation completes. The map sprites **re-tint**. Watch for changes — Captain Arthur may shift from red to amber, Mayor Sarah may go greener. A `DAY 2` pill joins the timeline strip; the day badge updates.
 
-(Read 1–2 lines of her monologue verbatim from the screen.)
+**You say:**
 
-**Action:** Drag the dial up further to a younger character — e.g. **Devon, the line cook**. The static swells while you scan, then fades again when you land.
+> "Watch the map. The town just drifted."
 
-**You say:**
+**Action:** Tune back to Captain Arthur. His Day 2 voice comes through with clearly different prose from Day 1. Wait for the voice to finish.
 
-> "Same broadcast. Different mind."
+**You say:**
 
-(Read 1 line of Devon's monologue verbatim — should be visibly more upbeat / opportunistic.)
+> "Day 1 he said *they're putting iron in my ocean.* Day 2 he heard about jobs and a hearing. Listen to what's softened."
 
 ---
 
-## Scene 6 — The Map Click (1:50 – 2:05)
+## Scene 6 — Time Travel (2:20 – 2:40)
 
-**On screen:** Move the cursor to the isometric map.
+**On screen:** Hover the timeline strip below the broadcast bar.
 
 **You say:**
 
-> "You can also just click someone on the map."
+> "And I can time-travel."
+
+**Action:** Click the **DAY 1** pill. The map snaps back to Day 1's heatmap, the day badge says DAY 1, Captain Arthur is red again. Tune back to him — his Day 1 voice returns.
 
-**Action:** Click a third character's avatar on the map. The dial snaps to their frequency, the dossier swaps, their monologue appears.
+**You say:**
 
-**You say (one line):**
+> "Day 1's snapshot, intact. Click Day 2 again — back to the present."
 
-> "The radio retunes itself."
+**Action:** Click the **DAY 2** pill. Map returns to Day 2 state.
 
 ---
 
-## Scene 7 — The Trace (2:05 – 2:20)
+## Scene 7 — Creative Mode (2:40 – 3:10)
 
-**On screen:** Open the **structured trace** panel (the collapsible JSON view, if present in your build).
+**On screen:** Open the **🎨 CREATIVE MODE** accordion above the map.
 
 **You say:**
 
-> "Under every monologue is the full structured trace — the emotion deltas, the activated memory, the value conflict, the likely public action. This is what makes Analog Town useful for writers and game masters: you don't just get prose, you get a readable mechanical readout of *why* this character reacted this way."
+> "And you can design your own town. Type a concept."
+
+**Action:** Paste into the concept field:
+> *A haunted seaside lighthouse where the keeper has vanished. The village is split on whether to investigate or burn it to the ground.*
+
+Set agent count to 4. Click **🪄 GENERATE WITH AI**.
+
+**You say (while it generates):**
+
+> "The same Qwen model that runs the simulator drafts a complete town: residents, frequencies, fears, hopes, relationships, even a default broadcast event. All in valid JSON. All editable."
+
+**On screen:** Generated JSON appears in the editable field below.
+
+**Action:** Click **💾 SAVE & LOAD**. The dropdown refreshes; the new town loads. The map shows the new agents.
+
+**You say:**
 
-**Action:** Scroll the trace panel briefly so the JSON fields are visible.
+> "Saved, loaded, and ready to broadcast."
 
 ---
 
-## Scene 8 — Close (2:20 – 2:30)
+## Scene 8 — Close (3:10 – 3:25)
 
-**On screen:** Pull back to a wide shot of the full interface — map, dial, monologue panel.
+**On screen:** Pull back to a wide shot of the full interface — map with the new town, dial, monologue panel, timeline strip ready to start.
 
 **You say:**
 
-> "Analog Town. A 7B model, a typed state machine, and a radio dial. Built small, on purpose. Tune in on Hugging Face Spaces."
+> "Analog Town. A 7B model, a typed state machine, a radio dial, and a town that remembers. Built small, on purpose. Tune in on Hugging Face Spaces."
 
 **Action:** Hold on the wide shot for 2 beats. Cut.
 
@@ -147,8 +182,9 @@ Click **Broadcast**.
 
 ## Backup Lines (in case something breaks)
 
-- **If the model is slow:** *"While that's computing — every state transition is one call, six characters means six small calls. That's the trade we made: small model, tight schema, no chat."*
-- **If a station produces a flat monologue:** *"Notice the model isn't being dramatic — that's deliberate. The system prompt tells it to favor plausible and grounded over interesting."*
+- **If TTS doesn't play on a sprite click:** *"On some browsers the speech engine needs a moment to wake up — there's a TEST button right here that confirms voice is ready."* (Click TEST button to demo voice independently.)
+- **If the model is slow:** *"While that's computing — every state transition is one model call, four characters means four small calls. That's the trade we made: small model, tight schema, no chat."*
+- **If a Day 2 monologue is too similar to Day 1:** *"Notice the model isn't being dramatic — that's deliberate. The system prompt tells it to favor plausible and grounded over interesting."*
 - **If the static doesn't fade audibly on recording:** *"The static you can't quite hear right now is fading out because the signal strength just climbed — it's a client-side audio effect tied to the dial."*
 
 ---
@@ -159,9 +195,10 @@ Click **Broadcast**.
 - Don't promise it predicts real people. The safety framing is part of the design.
 - Don't read JSON fields out loud word-for-word — paraphrase.
 - Don't apologize for the small model. Frame the smallness as the design choice it is.
+- Don't talk over the TTS voices — let them play. They're the demo.
 
 ---
 
 ## One-Line Elevator Pitch (for thumbnail / caption)
 
-> *"A shortwave radio for fictional minds. Drop news into a town. Tune the dial. Intercept what each resident is privately thinking."*
+> *"A shortwave radio for fictional minds. Drop news into a town. Tune the dial. Hear each resident, in their own voice, over multiple days."*

app.py

@@ -5,18 +5,21 @@ A whimsical 'shortwave radio' interface for simulating how different
 fictional personas might internally process a piece of news.
 """
 
+import base64
 import json
 import os
+import shutil
 import traceback
 from pathlib import Path
 
 import gradio as gr
 
 from schemas import Town, BroadcastEvent, AgentState, SimulationResult
-from model_client import ModelClient
+from model_client import ModelClient, synthesize_speech
 from simulator import Simulator
 from export_hub import ExportManager
 from theme import CUSTOM_CSS
+from town_generator import generate_town
 
 
 # ──────────────────────────────────────────────
@@ -53,44 +56,85 @@ def load_town(name: str) -> Town:
     return Town(**data)
 
 
-def format_town_map(town: Town, selected_agent_id: str | None = None) -> str:
+_EMOTION_COLORS = {
+    "anger": "#ff4444",
+    "fear": "#ff8c00",
+    "hope": "#ffb347",
+    "trust": "#39ff14",
+    "curiosity": "#47b3ff",
+    "social_energy": "#b347ff",
+}
+
+_EMOTION_KEYS = list(_EMOTION_COLORS.keys())
+
+
+def _dominant_emotion_color(state) -> str:
+    values = {k: getattr(state, k) for k in _EMOTION_KEYS}
+    dominant = max(values, key=values.get)
+    return _EMOTION_COLORS[dominant]
+
+
+def format_town_map(town: Town, selected_agent_id: str | None = None, sim_result=None) -> str:
     """Format the 2D interactive town map with character sprites."""
     if not town.agents:
         return "<div style='color: #5a5248; text-align: center; padding: 20px;'>No map data</div>"
 
+    transition_map = {}
+    if sim_result is not None:
+        for t in sim_result.transitions:
+            transition_map[t.agent_id] = t
+
     sprites = []
     for agent in town.agents:
         pos = agent.map_pos or {"x": 50, "y": 50}
         x = pos.get("x", 50)
         y = pos.get("y", 50)
-        
+
         selected_class = "selected-sprite" if agent.id == selected_agent_id else ""
-        
-        # Resolve avatar image path
+
         avatar_file = agent.avatar if agent.avatar else "avatars/default.png"
         avatar_path = Path(__file__).parent / avatar_file
         if not avatar_path.exists():
             avatar_path = Path(__file__).parent / "avatars/default.png"
-            
+
         avatar_url = f"/gradio_api/file={avatar_path.resolve()}"
-        
+
+        transition = transition_map.get(agent.id)
+        if transition is not None:
+            tint_color = _dominant_emotion_color(transition.updated_state)
+            avatar_style = (
+                f"background-image: url('{avatar_url}');"
+                f"border-color: {tint_color};"
+                f"box-shadow: 0 0 12px {tint_color};"
+                f"transition: border-color 0.4s ease, box-shadow 0.4s ease;"
+            )
+            has_anomaly = any(
+                abs(v) > 0.6 for v in transition.emotion_delta.values()
+            )
+        else:
+            avatar_style = f"background-image: url('{avatar_url}');"
+            has_anomaly = False
+
+        anomaly_html = '<div class="anomaly-flag">📢</div>' if has_anomaly else ""
+
         sprites.append(f"""
-        <div class="agent-sprite {selected_class}" 
-             style="left: {x}%; top: {y}%;" 
+        <div class="agent-sprite {selected_class}"
+             style="left: {x}%; top: {y}%;"
              onclick="selectAgent('{agent.id}')"
              title="{agent.name} - {agent.role}">
-            <div class="sprite-avatar" style="background-image: url('{avatar_url}');"></div>
+            <div class="sprite-avatar" style="{avatar_style}"></div>
             <div class="sprite-label">{agent.name}</div>
+            {anomaly_html}
         </div>
         """)
-    
+
     sprites_html = "\n".join(sprites)
-    
+
     map_filename = town.map_image if town.map_image else "town_map.png"
     map_image_path = Path(__file__).parent / map_filename
     if not map_image_path.exists():
         map_image_path = Path(__file__).parent / "town_map.png"
-    
+
     return f"""
     <div class="town-map-wrapper">
         <img src="/gradio_api/file={map_image_path.resolve()}" class="town-map-bg" alt="{town.name} Map" />
@@ -249,8 +293,79 @@ def format_action_display(transition) -> str:
     """
 
 
+def format_timeline_strip(timeline_json: str, active_day: int | None = None) -> str:
+    """Return a horizontal row of clickable day pills from a JSON timeline."""
+    if not timeline_json:
+        return '<div id="timeline-strip"><div class="timeline-empty">Broadcast to begin a day timeline ▸</div></div>'
+
+    try:
+        timeline = json.loads(timeline_json)
+    except Exception:
+        return '<div id="timeline-strip"><div class="timeline-empty">Broadcast to begin a day timeline ▸</div></div>'
+
+    if not timeline:
+        return '<div id="timeline-strip"><div class="timeline-empty">Broadcast to begin a day timeline ▸</div></div>'
+
+    if active_day is None:
+        active_day = timeline[-1]["day"]
+
+    pills = []
+    for entry in timeline:
+        day = entry["day"]
+        title = (entry.get("event_title") or "Broadcast")[:30]
+        if len(entry.get("event_title") or "") > 30:
+            title = title + "…"
+
+        sim = entry.get("sim_result", {})
+        transitions = sim.get("transitions", [])
+        anomaly_count = sum(
+            1 for t in transitions
+            if any(abs(v) > 0.6 for v in (t.get("emotion_delta") or {}).values())
+        )
+
+        active_class = "active" if day == active_day else ""
+        anomaly_html = f'<span class="pill-anomaly">⚠ {anomaly_count}</span>' if anomaly_count > 0 else ""
+
+        pills.append(
+            f'<div class="timeline-pill {active_class}" onclick="selectTimelineDay({day})">'
+            f'<span class="pill-day">DAY {day}</span>'
+            f'<span class="pill-title">{title}</span>'
+            f'{anomaly_html}'
+            f'</div>'
+        )
+
+    pills_html = "\n".join(pills)
+    return f'<div id="timeline-strip">{pills_html}</div>'
+
+
+def format_day_badge(day: int | None) -> str:
+    """Return an absolutely-positioned day badge HTML for the map panel."""
+    if day is None:
+        return ""
+    return f'<div class="day-badge">DAY {day}</div>'
+
+
+def _build_voice_player(monologue: str | None, agent_name: str | None = None, agent_age: str | None = None) -> str:
+    """Return a hidden div whose data attributes carry the monologue to the browser TTS poller."""
+    import html as _html
+    if not monologue:
+        return "<div id='voice-player-container' data-text='' style='display:none;'></div>"
+    clean = monologue.replace("\n", " ").replace("\r", " ").strip()
+    safe_text = _html.escape(clean, quote=True)
+    safe_name = _html.escape((agent_name or ""), quote=True)
+    safe_age = _html.escape((agent_age or ""), quote=True)
+    return (
+        f'<div id="voice-player-container" '
+        f'data-text="{safe_text}" '
+        f'data-name="{safe_name}" '
+        f'data-age="{safe_age}" '
+        f'style="display:none;"></div>'
+    )
+
+
 def tune_frequency(freq_value, sim_result_json):
     """Tune to a frequency and return the nearest agent's data."""
+    _empty_voice = _build_voice_player(None)
     if not sim_result_json:
         return (
             format_frequency_display(freq_value, None, 0),
@@ -258,6 +373,7 @@ def tune_frequency(freq_value, sim_result_json):
             format_emotion_bars(None),
             format_action_display(None),
             "",
+            _empty_voice,
         )
 
     try:
@@ -269,6 +385,7 @@ def tune_frequency(freq_value, sim_result_json):
             format_emotion_bars(None),
             format_action_display(None),
             "",
+            _empty_voice,
         )
 
     if not result.transitions:
@@ -278,6 +395,7 @@ def tune_frequency(freq_value, sim_result_json):
             format_emotion_bars(None),
             format_action_display(None),
             "",
+            _empty_voice,
         )
 
     # Load town to get agent info
@@ -313,20 +431,27 @@ def tune_frequency(freq_value, sim_result_json):
             format_emotion_bars(None),
             format_action_display(None),
             "",
+            _empty_voice,
         )
 
     # Calculate signal strength (stronger when closer)
     signal_strength = max(1, int(5 - min_dist * 4))
 
-    # Format trace JSON
     trace_json = json.dumps(nearest_transition.model_dump(), indent=2, default=str)
 
+    agent = agent_freq_map.get(nearest_transition.agent_id)
+    nearest_age = agent.age_range if agent else ""
+    voice_html = _build_voice_player(
+        nearest_transition.internal_monologue, nearest_name, nearest_age
+    )
+
     return (
         format_frequency_display(nearest_freq, nearest_name, signal_strength),
         format_monologue(nearest_transition.internal_monologue, nearest_name),
         format_emotion_bars(nearest_transition.updated_state),
         format_action_display(nearest_transition),
         trace_json,
+        voice_html,
     )
 
 
@@ -335,42 +460,86 @@ def tune_frequency(freq_value, sim_result_json):
 # ──────────────────────────────────────────────
 
 def on_load_town(town_name):
-    """Load a preset town and return map HTML and empty profile card."""
+    """Load a preset town and reset every town-scoped surface (timeline, receiver, badges)."""
+    empty_voice = _build_voice_player(None)
+    empty_freq = format_frequency_display(88.0, None, 0)
+    empty_monologue = format_monologue(None, None)
+    empty_emotions = format_emotion_bars(None)
+    empty_actions = format_action_display(None)
+    empty_strip = format_timeline_strip("")
+    empty_profile = "<div style='color: #5a5248; text-align: center; padding: 20px;'>Select an agent on the map to inspect dossier</div>"
+
     if not town_name:
-        return "", "", "", "", ""
+        return (
+            "", empty_profile, "", "", "",
+            "", "", empty_strip, "",
+            "",
+            empty_freq, empty_monologue, empty_emotions, empty_actions, "", empty_voice,
+            gr.update(value=88.0),
+        )
 
     try:
         town = load_town(town_name)
         map_html = format_town_map(town)
-        profile_html = format_agent_profile_card(None, town)
         town_json = town.model_dump_json(indent=2)
-
-        # Pre-fill event from default
         event_title = town.default_event.title if town.default_event else ""
         event_content = town.default_event.content if town.default_event else ""
 
-        return map_html, profile_html, town_json, event_title, event_content
+        return (
+            map_html,
+            empty_profile,
+            town_json,
+            event_title,
+            event_content,
+            "",
+            "",
+            empty_strip,
+            "",
+            "",
+            empty_freq,
+            empty_monologue,
+            empty_emotions,
+            empty_actions,
+            "",
+            empty_voice,
+            gr.update(value=88.0),
+        )
     except Exception as e:
-        return f"<div style='color: #ff4444;'>Error loading town: {e}</div>", "", "", "", ""
+        return (
+            f"<div style='color: #ff4444;'>Error loading town: {e}</div>",
+            empty_profile, "", "", "",
+            "", "", empty_strip, "",
+            f"❌ {e}",
+            empty_freq, empty_monologue, empty_emotions, empty_actions, "", empty_voice,
+            gr.update(value=88.0),
+        )
 
 
 def on_select_agent(agent_id, town_json, sim_result_json):
     """Event handler when an agent is selected via map click."""
+    _empty = _build_voice_player(None)
     if not town_json:
-        return "", "", 88.0, "", "", "", "", ""
-        
+        return "", "", 88.0, "", "", "", "", "", _empty
+
     try:
         town = Town(**json.loads(town_json))
         agent = next((a for a in town.agents if a.id == agent_id), None)
         if not agent:
-            return "", "", 88.0, "", "", "", "", ""
-            
-        map_html = format_town_map(town, agent.id)
+            return "", "", 88.0, "", "", "", "", "", _empty
+
+        sim_result = None
+        if sim_result_json:
+            try:
+                sim_result = SimulationResult(**json.loads(sim_result_json))
+            except Exception:
+                sim_result = None
+
+        map_html = format_town_map(town, agent.id, sim_result)
         profile_html = format_agent_profile_card(agent, town)
-        
-        # Get simulated shortwave state (monologue, emotional bars, action)
+
+        # Get simulated shortwave state (monologue, emotional bars, action, voice)
         receiver_data = tune_frequency(agent.frequency, sim_result_json)
-        
+
         return (
             map_html,
             profile_html,
@@ -380,23 +549,24 @@ def on_select_agent(agent_id, town_json, sim_result_json):
             receiver_data[2],
             receiver_data[3],
             receiver_data[4],
+            receiver_data[5],
         )
     except Exception as e:
         traceback.print_exc()
-        return "", f"<div style='color: #ff4444;'>Error: {e}</div>", 88.0, "", "", "", "", ""
+        return "", f"<div style='color: #ff4444;'>Error: {e}</div>", 88.0, "", "", "", "", "", _empty
 
 
-def on_transmit(town_json, event_title, event_content, progress=gr.Progress()):
-    """Run the simulation for all agents."""
+def on_transmit(town_json, event_title, event_content, timeline_json, progress=gr.Progress()):
+    """Run the simulation, chaining from the last day's states if available."""
     if not town_json:
-        return "⚠ Load a town first", ""
+        return "⚠ Load a town first", "", gr.update(), timeline_json, format_timeline_strip(timeline_json), ""
     if not event_content:
-        return "⚠ Enter a broadcast event", ""
+        return "⚠ Enter a broadcast event", "", gr.update(), timeline_json, format_timeline_strip(timeline_json), ""
 
     try:
         town = Town(**json.loads(town_json))
     except Exception as e:
-        return f"❌ Invalid town data: {e}", ""
+        return f"❌ Invalid town data: {e}", "", gr.update(), timeline_json, format_timeline_strip(timeline_json), ""
 
     event = BroadcastEvent(
         title=event_title or "Broadcast Event",
@@ -404,20 +574,32 @@ def on_transmit(town_json, event_title, event_content, progress=gr.Progress()):
         source="Town Radio",
     )
 
-    # Initialize simulator
     try:
         client = ModelClient()
         simulator = Simulator(model_client=client)
     except Exception as e:
-        return f"❌ Model initialization failed: {e}", ""
+        return f"❌ Model initialization failed: {e}", "", gr.update(), timeline_json, format_timeline_strip(timeline_json), ""
+
+    previous_states = None
+    current_timeline = []
+    if timeline_json:
+        try:
+            current_timeline = json.loads(timeline_json)
+            if current_timeline:
+                last_entry = current_timeline[-1]
+                last_result = SimulationResult(**last_entry["sim_result"])
+                previous_states = {
+                    t.agent_id: t.updated_state for t in last_result.transitions
+                }
+        except Exception:
+            current_timeline = []
+
+    day = len(current_timeline) + 1
 
-    # Run simulation with progress
     status_lines = []
 
     def progress_callback(name, status, index, total):
-        emoji = {"processing": "⏳", "complete": "✅"}.get(
-            status.split(":")[0], "⚠"
-        )
+        emoji = {"processing": "⏳", "complete": "✅"}.get(status.split(":")[0], "⚠")
         line = f"{emoji} [{index+1}/{total}] {name}: {status}"
         status_lines.append(line)
         progress((index + 1) / total, desc=f"Processing {name}...")
@@ -426,12 +608,13 @@ def on_transmit(town_json, event_title, event_content, progress=gr.Progress()):
         result = simulator.run_town_simulation(
             town=town,
             event=event,
+            previous_states=previous_states,
             progress_callback=progress_callback,
+            day=day,
         )
     except Exception as e:
-        return f"❌ Simulation failed: {e}", ""
+        return f"❌ Simulation failed: {e}", "", gr.update(), timeline_json, format_timeline_strip(timeline_json), ""
 
-    # Format status
     n_success = len(result.transitions)
     n_total = len(town.agents)
 
@@ -444,10 +627,88 @@ def on_transmit(town_json, event_title, event_content, progress=gr.Progress()):
 
     status += "\n" + "\n".join(status_lines)
 
-    # Store result as JSON
+    new_entry = {
+        "day": day,
+        "event_title": event_title or "Broadcast Event",
+        "event_content": event_content,
+        "sim_result": json.loads(result.model_dump_json()),
+    }
+    current_timeline.append(new_entry)
+    new_timeline_json = json.dumps(current_timeline)
+
     result_json = result.model_dump_json(indent=2)
+    updated_map = format_town_map(town, None, result)
+    timeline_strip = format_timeline_strip(new_timeline_json, active_day=day)
+    day_badge = format_day_badge(day)
+
+    return status, result_json, updated_map, new_timeline_json, timeline_strip, day_badge
+
+
+def on_reset_timeline(town_json):
+    """Clear the entire timeline and return to Day 1 default state."""
+    empty_strip = format_timeline_strip("")
+    if not town_json:
+        return "", "", empty_strip, ""
+    try:
+        town = Town(**json.loads(town_json))
+        map_html = format_town_map(town, None, None)
+    except Exception:
+        map_html = ""
+    return "", map_html, empty_strip, ""
+
+
+def on_select_timeline_day(day_str, town_json, timeline_json):
+    """Restore the map and sim_result to a specific historical day."""
+    _empty_voice = _build_voice_player(None)
+    empty_returns = (
+        "",
+        "",
+        format_frequency_display(88.0, None, 0),
+        format_monologue(None, None),
+        format_emotion_bars(None),
+        format_action_display(None),
+        "",
+        _empty_voice,
+        format_timeline_strip(timeline_json),
+        "",
+    )
+
+    if not day_str or not timeline_json:
+        return empty_returns
+
+    try:
+        day = int(day_str)
+        timeline = json.loads(timeline_json)
+    except Exception:
+        return empty_returns
+
+    entry = next((e for e in timeline if e["day"] == day), None)
+    if not entry:
+        return empty_returns
+
+    try:
+        sim_result = SimulationResult(**entry["sim_result"])
+        town = Town(**json.loads(town_json)) if town_json else None
+    except Exception:
+        return empty_returns
 
-    return status, result_json
+    result_json = sim_result.model_dump_json(indent=2)
+    map_html = format_town_map(town, None, sim_result) if town else ""
+    strip_html = format_timeline_strip(timeline_json, active_day=day)
+    badge_html = format_day_badge(day)
+
+    return (
+        result_json,
+        map_html,
+        format_frequency_display(88.0, None, 0),
+        format_monologue(None, None),
+        format_emotion_bars(None),
+        format_action_display(None),
+        "",
+        _empty_voice,
+        strip_html,
+        badge_html,
+    )
 
 
 def on_export_local(sim_result_json, town_json):
@@ -482,6 +743,79 @@ def on_export_hub(sim_result_json, town_json, repo_id):
         return f"❌ Hub upload failed: {e}"
 
 
+# ──────────────────────────────────────────────
+# Creative Mode handlers
+# ──────────────────────────────────────────────
+
+def on_generate_creative_town(concept, n_agents, current_json):
+    """Generate a town JSON from concept + count. Returns (json_str, status_markdown)."""
+    if not concept or not concept.strip():
+        return current_json, "_Status: ⚠ Type a concept first_"
+    try:
+        town_dict = generate_town(concept.strip(), int(n_agents))
+        return json.dumps(town_dict, indent=2), "_Status: ✅ Town generated — review and edit the JSON below, then click Save & Load_"
+    except Exception as e:
+        return current_json, f"_Status: ❌ Generation failed: {e}_"
+
+
+def on_save_load_creative_town(json_text, map_upload_path):
+    """Validate JSON, optionally copy uploaded map image, write to sample_towns, then trigger full reset."""
+    empty_voice = _build_voice_player(None)
+    empty_freq = format_frequency_display(88.0, None, 0)
+    empty_monologue = format_monologue(None, None)
+    empty_emotions = format_emotion_bars(None)
+    empty_actions = format_action_display(None)
+    empty_strip = format_timeline_strip("")
+    empty_profile = "<div style='color: #5a5248; text-align: center; padding: 20px;'>Select an agent on the map to inspect dossier</div>"
+
+    def _error_return(msg):
+        return (
+            "", empty_profile, "", "", "",
+            "", "", empty_strip, "",
+            f"❌ {msg}",
+            empty_freq, empty_monologue, empty_emotions, empty_actions, "", empty_voice,
+            gr.update(value=88.0),
+            gr.update(),
+            f"_Status: ❌ {msg}_",
+        )
+
+    if not json_text or not json_text.strip():
+        return _error_return("No JSON to save. Generate a town first.")
+
+    try:
+        town_dict = json.loads(json_text)
+        town = Town(**town_dict)
+    except Exception as e:
+        return _error_return(f"Invalid town JSON: {e}")
+
+    project_root = Path(__file__).parent
+
+    if map_upload_path:
+        dest = project_root / f"{town.id}_map.png"
+        shutil.copy(map_upload_path, dest)
+        town.map_image = f"{town.id}_map.png"
+    else:
+        if town.map_image:
+            candidate = project_root / town.map_image
+            if not candidate.exists():
+                town.map_image = "town_map.png"
+        else:
+            town.map_image = "town_map.png"
+
+    save_path = SAMPLE_TOWNS_DIR / f"{town.id}.json"
+    SAMPLE_TOWNS_DIR.mkdir(parents=True, exist_ok=True)
+    save_path.write_text(town.model_dump_json(indent=2))
+
+    new_choices = get_available_towns()
+
+    load_tuple = on_load_town(town.id)
+
+    return load_tuple + (
+        gr.update(choices=new_choices, value=town.id),
+        f"_Status: ✅ Town '{town.name}' saved and loaded. Press TRANSMIT to run Day 1._",
+    )
+
+
 # ──────────────────────────────────────────────
 # Build UI
 # ──────────────────────────────────────────────
@@ -591,6 +925,211 @@ window.setAmbientVolume = function(val) {
     }
 };
 
+let voicePlaying = false;
+let voiceEnabled = true;
+let lastSpokenText = "";
+
+window.toggleVoice = function() {
+    voiceEnabled = !voiceEnabled;
+    const btn = document.getElementById("voice-toggle-btn");
+    if (voiceEnabled) {
+        if (btn) {
+            btn.innerText = "🔊 VOICE ON";
+            btn.style.background = "#39ff14";
+            btn.style.color = "#0a0e14";
+            btn.style.borderColor = "rgba(57, 255, 20, 0.4)";
+            btn.style.boxShadow = "0 0 10px rgba(57,255,20,0.4)";
+        }
+    } else {
+        if (window.speechSynthesis) window.speechSynthesis.cancel();
+        voicePlaying = false;
+        if (btn) {
+            btn.innerText = "🔇 VOICE OFF";
+            btn.style.background = "#2a3040";
+            btn.style.color = "#8a8070";
+            btn.style.borderColor = "rgba(138, 128, 112, 0.4)";
+            btn.style.boxShadow = "none";
+        }
+    }
+};
+
+window.testVoice = function() {
+    console.log("[AnalogTown] testVoice clicked");
+    if (!window.speechSynthesis) {
+        alert("Your browser does not support speechSynthesis.");
+        return;
+    }
+    voiceEnabled = true;
+    try { window.speechSynthesis.resume(); } catch (e) {}
+    const u = new SpeechSynthesisUtterance("Receiver online. This is a voice test from Analog Town.");
+    u.rate = 0.95;
+    u.pitch = 1.0;
+    u.volume = 1.0;
+    const voices = window.speechSynthesis.getVoices();
+    const enVoice = voices.find(v => v.lang && v.lang.toLowerCase().startsWith("en"));
+    if (enVoice) { u.voice = enVoice; console.log("[AnalogTown] test using voice:", enVoice.name, enVoice.lang); }
+    u.onstart = function() {
+        voicePlaying = true;
+        const led = document.getElementById("voice-status-led");
+        if (led) { led.style.background = "#39ff14"; led.style.boxShadow = "0 0 8px #39ff14"; }
+        console.log("[AnalogTown] TEST utterance STARTED");
+    };
+    u.onend = function() {
+        voicePlaying = false;
+        const led = document.getElementById("voice-status-led");
+        if (led) { led.style.background = "#2a3040"; led.style.boxShadow = "none"; }
+        console.log("[AnalogTown] TEST utterance ENDED");
+    };
+    u.onerror = function(e) {
+        console.error("[AnalogTown] TEST utterance ERROR:", e.error || e);
+        const led = document.getElementById("voice-status-led");
+        if (led) { led.style.background = "#ff4444"; led.style.boxShadow = "0 0 8px #ff4444"; }
+    };
+    window.speechSynthesis.speak(u);
+    console.log("[AnalogTown] TEST speak() invoked, pending:", window.speechSynthesis.pending, "speaking:", window.speechSynthesis.speaking, "paused:", window.speechSynthesis.paused);
+    setTimeout(function() {
+        console.log("[AnalogTown] 1s after speak — speaking:", window.speechSynthesis.speaking, "paused:", window.speechSynthesis.paused);
+        if (window.speechSynthesis.paused) {
+            console.log("[AnalogTown] engine paused, attempting resume");
+            window.speechSynthesis.resume();
+        }
+    }, 1000);
+};
+
+const FEMALE_NAME_TOKENS = [
+    "sarah","chloe","priya","maple","mei","elena","martha","leah","mara",
+    "joan","lila","mira","idell","rusty","ronnie","tiffany","margaret",
+    "auntie","sister","granny","elder martha","aria","ronnie mae","mae",
+    "elder","mira okonkwo","lila mendes","an"
+];
+const MALE_NAME_TOKENS = [
+    "arthur","toby","jesse","buck","hollis","joaquin","daniel","wade","mason",
+    "tuan","kai","engineer daniyal","daniyal","pastor","preacher","ng","martin",
+    "captain arthur","captain","gerald","silas","alistair","marcus","corporal dale",
+    "eli","theo","pastor lin","councilman","architect"
+];
+const FEMALE_VOICE_POOL = [
+    "Samantha","Victoria","Karen","Moira","Allison","Susan","Ava","Fiona","Tessa",
+    "Veena","Kate","Serena","Google UK English Female","Google US English",
+    "Microsoft Zira","Microsoft Aria"
+];
+const MALE_VOICE_POOL = [
+    "Daniel","Alex","Fred","Tom","Aaron","Lee","Oliver","Rishi","Albert","Bruce",
+    "Junior","Ralph","Google UK English Male","Microsoft David","Microsoft Mark"
+];
+
+function _stableHash(s) {
+    let h = 0;
+    for (let i = 0; i < s.length; i++) {
+        h = ((h << 5) - h + s.charCodeAt(i)) | 0;
+    }
+    return Math.abs(h);
+}
+
+function _pickVoiceForAgent(name, ageRange) {
+    const voices = window.speechSynthesis.getVoices().filter(v => v.lang && v.lang.toLowerCase().startsWith("en"));
+    if (voices.length === 0) return { voice: null, pitch: 1.0, rate: 0.95 };
+
+    const lname = (name || "").toLowerCase();
+    let isFemale = FEMALE_NAME_TOKENS.some(t => lname.includes(t));
+    let isMale = MALE_NAME_TOKENS.some(t => lname.includes(t));
+    if (isFemale && isMale) {
+        if (lname.indexOf("captain arthur") >= 0 || lname.indexOf("arthur") >= 0) { isFemale = false; isMale = true; }
+    }
+    if (!isFemale && !isMale) {
+        const h = _stableHash(lname || "x");
+        isFemale = (h % 2) === 0;
+    }
+
+    const pool = isFemale ? FEMALE_VOICE_POOL : MALE_VOICE_POOL;
+    const hash = _stableHash(lname || "x");
+    const idx = hash % pool.length;
+
+    let voice = null;
+    for (let offset = 0; offset < pool.length; offset++) {
+        const candidate = pool[(idx + offset) % pool.length];
+        voice = voices.find(v => v.name === candidate);
+        if (voice) break;
+        voice = voices.find(v => v.name.toLowerCase().includes(candidate.toLowerCase()));
+        if (voice) break;
+    }
+    if (!voice) {
+        const filtered = voices.filter(v => isFemale ? /female|woman|samantha|victoria|karen|moira|tessa|aria/i.test(v.name) : /male|man|daniel|alex|fred|tom|david|mark/i.test(v.name));
+        voice = (filtered.length > 0 ? filtered[hash % filtered.length] : voices[hash % voices.length]);
+    }
+
+    const isElder = /\\b(6[0-9]|7[0-9]|8[0-9]|elder|granny|auntie|pastor|preacher|veteran|retired)\\b/i.test((ageRange || "") + " " + (name || ""));
+    const isYoung = /\\b(1[6-9]|2[0-4]|teen|teenager|young|apprentice)\\b/i.test((ageRange || "") + " " + (name || ""));
+
+    let pitch = 1.0 + ((hash % 9) - 4) * 0.03;
+    if (isElder) pitch -= 0.12;
+    if (isYoung) pitch += 0.08;
+    pitch = Math.max(0.6, Math.min(1.4, pitch));
+
+    const rate = 0.88 + (hash % 5) * 0.03;
+
+    return { voice: voice, pitch: pitch, rate: rate, isFemale: isFemale, isElder: isElder, isYoung: isYoung };
+}
+
+window.speakMonologue = function(text, name, ageRange) {
+    console.log("[AnalogTown] speakMonologue called:", { textLen: (text||"").length, name: name, voiceEnabled: voiceEnabled });
+    if (!voiceEnabled) { console.log("[AnalogTown] voice disabled, skipping"); return; }
+    if (!window.speechSynthesis || !window.SpeechSynthesisUtterance) {
+        console.warn("[AnalogTown] Browser SpeechSynthesis not available");
+        return;
+    }
+    if (!text) { console.log("[AnalogTown] empty text, skipping"); return; }
+    if (text === lastSpokenText) { console.log("[AnalogTown] same as last spoken, skipping"); return; }
+    lastSpokenText = text;
+
+    try { window.speechSynthesis.cancel(); } catch (e) {}
+    try { window.speechSynthesis.resume(); } catch (e) {}
+
+    const utter = new SpeechSynthesisUtterance(text);
+    utter.volume = 1.0;
+
+    const choice = _pickVoiceForAgent(name, ageRange);
+    if (choice.voice) {
+        utter.voice = choice.voice;
+        console.log("[AnalogTown] voice for", name, "→", choice.voice.name, "(female=" + choice.isFemale + ", elder=" + choice.isElder + ", young=" + choice.isYoung + ")");
+    }
+    utter.pitch = choice.pitch;
+    utter.rate = choice.rate;
+    console.log("[AnalogTown] pitch=" + utter.pitch.toFixed(2) + " rate=" + utter.rate.toFixed(2));
+
+    utter.onstart = function() {
+        voicePlaying = true;
+        const led = document.getElementById("voice-status-led");
+        if (led) { led.style.background = "#39ff14"; led.style.boxShadow = "0 0 8px #39ff14"; }
+        console.log("[AnalogTown] utterance started");
+    };
+    utter.onend = function() {
+        voicePlaying = false;
+        const led = document.getElementById("voice-status-led");
+        if (led) { led.style.background = "#2a3040"; led.style.boxShadow = "none"; }
+        console.log("[AnalogTown] utterance ended");
+    };
+    utter.onerror = function(e) {
+        voicePlaying = false;
+        const led = document.getElementById("voice-status-led");
+        if (led) { led.style.background = "#ff4444"; led.style.boxShadow = "0 0 8px #ff4444"; }
+        console.error("[AnalogTown] utterance error:", e);
+    };
+
+    setTimeout(function() {
+        window.speechSynthesis.speak(utter);
+        console.log("[AnalogTown] speak() called");
+    }, 80);
+};
+
+if (window.speechSynthesis) {
+    window.speechSynthesis.getVoices();
+    window.speechSynthesis.onvoiceschanged = function() {
+        const v = window.speechSynthesis.getVoices();
+        console.log("[AnalogTown] voices loaded:", v.length);
+    };
+}
+
 window.updateAudioVolumeActual = function() {
     if (!ambientAudio) return;
     if (ambientMuted) {
@@ -600,16 +1139,19 @@ window.updateAudioVolumeActual = function() {
     // Calculate target volume based on active signal bars
     const activeBars = document.querySelectorAll(".signal-bar.active").length;
     const signalFade = 1.0 - (activeBars / 5.0);
-    targetActualVolume = ambientVolume * signalFade;
-    
+    const baseTarget = ambientVolume * signalFade;
+
+    // Duck to 15% of user ambient volume while voice is playing
+    targetActualVolume = voicePlaying ? ambientVolume * 0.15 : baseTarget;
+
     // Smoothly interpolate currentActualVolume towards targetActualVolume
     const diff = targetActualVolume - currentActualVolume;
     if (Math.abs(diff) > 0.01) {
-        currentActualVolume += diff * 0.15; // smooth transition
+        currentActualVolume += diff * 0.15;
     } else {
         currentActualVolume = targetActualVolume;
     }
-    
+
     // Set audio volume
     ambientAudio.volume = Math.max(0, Math.min(1, currentActualVolume));
 };
@@ -620,6 +1162,78 @@ document.addEventListener("keydown", window.startAmbientOnInteraction);
 
 // Polling interval for smooth fade
 setInterval(window.updateAudioVolumeActual, 100);
+
+let _voiceContainerWarned = false;
+let _voicePollTick = 0;
+setInterval(function() {
+    _voicePollTick++;
+    let c = document.getElementById("voice-player-container");
+    if (!c) {
+        c = document.querySelector("[data-text][data-name]");
+    }
+    if (!c) {
+        if (!_voiceContainerWarned && _voicePollTick % 25 === 0) {
+            console.warn("[AnalogTown] voice-player-container NOT FOUND in DOM after", _voicePollTick * 0.4, "s — sprite clicks won't trigger TTS until it appears");
+            _voiceContainerWarned = true;
+        }
+        return;
+    }
+    if (_voiceContainerWarned) {
+        console.log("[AnalogTown] voice-player-container found:", c);
+        _voiceContainerWarned = false;
+    }
+    const text = c.getAttribute("data-text") || "";
+    const name = c.getAttribute("data-name") || "";
+    const age = c.getAttribute("data-age") || "";
+    if (text && text !== lastSpokenText) {
+        console.log("[AnalogTown] poll detected new data-text:", text.slice(0, 60), "...");
+        window.speakMonologue(text, name, age);
+    }
+}, 400);
+
+// Chrome workaround: speech engine auto-pauses after ~15s of inactivity. Keep it warm.
+setInterval(function() {
+    if (window.speechSynthesis && window.speechSynthesis.speaking && window.speechSynthesis.paused) {
+        window.speechSynthesis.resume();
+    }
+}, 5000);
+
+window.selectTimelineDay = function(n) {
+    console.log("selectTimelineDay called with day:", n);
+    const container = document.getElementById("selected-day");
+    if (container) {
+        const input = container.querySelector("input") || container.querySelector("textarea");
+        if (input) {
+            let prototype = Object.getPrototypeOf(input);
+            let descriptor = Object.getOwnPropertyDescriptor(prototype, "value");
+            while (prototype && !descriptor) {
+                prototype = Object.getPrototypeOf(prototype);
+                descriptor = Object.getOwnPropertyDescriptor(prototype, "value");
+            }
+            const setter = descriptor ? descriptor.set : null;
+            if (setter) {
+                setter.call(input, String(n));
+            } else {
+                input.value = String(n);
+            }
+            input.dispatchEvent(new Event("input", { bubbles: true }));
+
+            setTimeout(() => {
+                const btn = document.getElementById("select-day-trigger");
+                if (btn) {
+                    console.log("Clicking select-day-trigger button");
+                    btn.click();
+                } else {
+                    console.error("select-day-trigger button not found");
+                }
+            }, 50);
+        } else {
+            console.error("Input/textarea not found inside #selected-day");
+        }
+    } else {
+        console.error("#selected-day container not found");
+    }
+};
 """
 
 AUDIO_PATH = Path(__file__).parent / "static_ambient.wav"
@@ -638,11 +1252,16 @@ def create_app():
         # ── State ──
         town_state = gr.State("")
         sim_result_state = gr.State("")
+        timeline_state = gr.State("")
 
         # ── Hidden Map Communication Inputs ──
         selected_agent_id = gr.Textbox(elem_id="selected-agent-id", elem_classes=["hidden-component"], visible=True)
         select_agent_trigger = gr.Button("Select Agent Trigger", elem_id="select-agent-trigger", elem_classes=["hidden-component"], visible=True)
 
+        # ── Hidden Timeline Day Bridge ──
+        selected_day = gr.Textbox(elem_id="selected-day", elem_classes=["hidden-component"], visible=True)
+        select_day_trigger = gr.Button("Select Day Trigger", elem_id="select-day-trigger", elem_classes=["hidden-component"], visible=True)
+
         # ── Header ──
         with gr.Row(elem_id="header-block"):
             with gr.Column():
@@ -691,12 +1310,21 @@ def create_app():
                     )
                 with gr.Column(scale=2, min_width=180):
                     gr.HTML('<div class="ctrl-label">▸ TRANSMIT</div>')
-                    transmit_btn = gr.Button(
-                        "🔊 TRANSMIT",
-                        variant="primary",
-                        elem_classes=["transmit-btn"],
-                        elem_id="transmit-btn",
-                    )
+                    with gr.Row(equal_height=True):
+                        transmit_btn = gr.Button(
+                            "🔊 TRANSMIT",
+                            variant="primary",
+                            elem_classes=["transmit-btn"],
+                            elem_id="transmit-btn",
+                            scale=3,
+                        )
+                        reset_timeline_btn = gr.Button(
+                            "🔁 RESET",
+                            size="sm",
+                            elem_classes=["export-btn"],
+                            elem_id="reset-timeline-btn",
+                            scale=1,
+                        )
                     sim_status = gr.Textbox(
                         show_label=False,
                         container=False,
@@ -707,12 +1335,68 @@ def create_app():
                         elem_id="sim-status",
                     )
 
+        # === TIMELINE STRIP (below control bar, full width) ===
+        timeline_strip = gr.HTML(
+            value=format_timeline_strip(""),
+            elem_id="timeline-strip-container",
+        )
+
+        # === CREATIVE MODE ACCORDION ===
+        with gr.Accordion("🎨 CREATIVE MODE — Design Your Own Town", open=False, elem_id="creative-mode"):
+            with gr.Row():
+                with gr.Column(scale=4):
+                    concept_input = gr.Textbox(
+                        label="🎨 TOWN CONCEPT",
+                        placeholder="e.g., a haunted seaside lighthouse where the keeper has gone missing and the village is split on whether to investigate or move on",
+                        lines=4,
+                        elem_id="creative-concept",
+                    )
+                with gr.Column(scale=2):
+                    agent_count_slider = gr.Slider(
+                        label="# AGENTS",
+                        minimum=3,
+                        maximum=6,
+                        step=1,
+                        value=4,
+                        elem_id="creative-agent-count",
+                    )
+                    map_upload = gr.File(
+                        label="📁 UPLOAD MAP PNG (optional)",
+                        file_types=["image"],
+                        type="filepath",
+                        elem_id="creative-map-upload",
+                    )
+            with gr.Row():
+                creative_generate_btn = gr.Button(
+                    "🪄 GENERATE WITH AI",
+                    variant="secondary",
+                    elem_classes=["export-btn"],
+                    elem_id="creative-generate-btn",
+                )
+                creative_save_btn = gr.Button(
+                    "💾 SAVE & LOAD",
+                    variant="primary",
+                    elem_classes=["transmit-btn"],
+                    elem_id="creative-save-btn",
+                )
+            town_json_code = gr.Code(
+                label="EDITABLE TOWN JSON",
+                language="json",
+                lines=14,
+                elem_id="creative-json",
+            )
+            creative_status = gr.Markdown("_Status: idle_", elem_id="creative-status")
+
         # === MAIN STAGE (map+dossier on left | receiver on right) ===
         with gr.Row(elem_id="main-stage", equal_height=True):
 
             # ── LEFT: Town Map + Agent Dossier ──
             with gr.Column(scale=6, min_width=420, elem_id="map-panel"):
                 gr.HTML('<div class="panel-header">🗺 TOWN MAP &middot; CLICK A SIGNAL NODE</div>')
+                day_badge = gr.HTML(
+                    value="",
+                    elem_id="day-badge-container",
+                )
 
                 town_map = gr.HTML(
                     value="<div style='color: #5a5248; text-align: center; padding: 20px;'>Load a town to see the map</div>",
@@ -748,6 +1432,12 @@ def create_app():
                     elem_id="monologue",
                 )
 
+                voice_player = gr.HTML(
+                    value=_build_voice_player(None),
+                    elem_id="voice-player",
+                    elem_classes=["hidden-component"],
+                )
+
                 with gr.Row(equal_height=True):
                     with gr.Column(scale=1, min_width=160):
                         gr.HTML('<div class="sub-header">🎚 EMOTIONAL STATE</div>')
@@ -764,13 +1454,20 @@ def create_app():
 
                 ambient_control = gr.HTML(
                     value=f"""
-                    <div class="ambient-control-panel" style="background: #111820; border: 1px solid #2a3040; border-radius: 8px; padding: 8px 12px; margin-top: 10px; font-family: 'IBM Plex Mono', monospace;">
+                    <div class="ambient-control-panel" style="background: #111820; border: 1px solid #2a3040; border-radius: 8px; padding: 8px 12px; margin-top: 10px; font-family: 'IBM Plex Mono', monospace; display: flex; flex-direction: column; gap: 8px;">
                         <div style="display: flex; align-items: center; gap: 10px;">
-                            <span style="font-size: 10px; color: #ffb347; letter-spacing: 1.5px; font-weight: bold; white-space: nowrap;">📻 STATIC</span>
+                            <span style="font-size: 10px; color: #ffb347; letter-spacing: 1.5px; font-weight: bold; white-space: nowrap; min-width: 60px;">📻 STATIC</span>
                             <button id="ambient-toggle-btn" class="retro-btn" onclick="toggleAmbient()" style="background: #39ff14; border: 1px solid rgba(57, 255, 20, 0.4); color: #0a0e14; padding: 2px 8px; font-family: 'IBM Plex Mono', monospace; font-size: 10px; cursor: pointer; border-radius: 4px; box-shadow: 0 0 10px rgba(57,255,20,0.4); font-weight: bold;">ON</button>
                             <input type="range" id="ambient-volume" min="0" max="1" step="0.05" value="0.15" oninput="setAmbientVolume(this.value)" style="flex-grow: 1; accent-color: #ffb347; cursor: pointer; height: 4px; background: #2a3040; border-radius: 2px; outline: none;" />
                             <span id="ambient-volume-val" style="font-size: 10px; color: #ffb347; width: 32px; text-align: right;">15%</span>
                         </div>
+                        <div style="display: flex; align-items: center; gap: 10px;">
+                            <span style="font-size: 10px; color: #ffb347; letter-spacing: 1.5px; font-weight: bold; white-space: nowrap; min-width: 60px;">🎙 VOICE</span>
+                            <button id="voice-toggle-btn" class="retro-btn" onclick="toggleVoice()" style="background: #39ff14; border: 1px solid rgba(57, 255, 20, 0.4); color: #0a0e14; padding: 2px 8px; font-family: 'IBM Plex Mono', monospace; font-size: 10px; cursor: pointer; border-radius: 4px; box-shadow: 0 0 10px rgba(57,255,20,0.4); font-weight: bold;">🔊 VOICE ON</button>
+                            <button id="voice-test-btn" class="retro-btn" onclick="testVoice()" style="background: #2a3040; border: 1px solid rgba(255, 179, 71, 0.4); color: #ffb347; padding: 2px 8px; font-family: 'IBM Plex Mono', monospace; font-size: 10px; cursor: pointer; border-radius: 4px; font-weight: bold;">TEST</button>
+                            <span id="voice-status-led" style="display: inline-block; width: 10px; height: 10px; border-radius: 50%; background: #2a3040; transition: background 0.2s, box-shadow 0.2s;"></span>
+                            <span style="font-size: 9px; color: #8a8070; flex-grow: 1; text-align: right;">click any sprite to hear</span>
+                        </div>
                     </div>
                     """,
                     elem_id="ambient-control",
@@ -824,18 +1521,36 @@ def create_app():
 
         # ── Event Handlers ──
 
-        # Load town
+        _load_outputs = [
+            town_map, agent_profile, town_state, event_title, event_content,
+            sim_result_state, timeline_state, timeline_strip, day_badge,
+            sim_status,
+            freq_display, monologue_display, emotion_display, action_display, trace_json, voice_player,
+            freq_slider,
+        ]
+
         load_btn.click(
             fn=on_load_town,
             inputs=[town_dropdown],
-            outputs=[town_map, agent_profile, town_state, event_title, event_content],
+            outputs=_load_outputs,
         )
 
-        # Also load on dropdown change
         town_dropdown.change(
             fn=on_load_town,
             inputs=[town_dropdown],
-            outputs=[town_map, agent_profile, town_state, event_title, event_content],
+            outputs=_load_outputs,
+        )
+
+        creative_generate_btn.click(
+            fn=on_generate_creative_town,
+            inputs=[concept_input, agent_count_slider, town_json_code],
+            outputs=[town_json_code, creative_status],
+        )
+
+        creative_save_btn.click(
+            fn=on_save_load_creative_town,
+            inputs=[town_json_code, map_upload],
+            outputs=_load_outputs + [town_dropdown, creative_status],
         )
 
         # Map Click Event Selector
@@ -851,21 +1566,48 @@ def create_app():
                 emotion_display,
                 action_display,
                 trace_json,
+                voice_player,
             ],
         )
 
         # Transmit
         transmit_btn.click(
             fn=on_transmit,
-            inputs=[town_state, event_title, event_content],
-            outputs=[sim_status, sim_result_state],
+            inputs=[town_state, event_title, event_content, timeline_state],
+            outputs=[sim_status, sim_result_state, town_map, timeline_state, timeline_strip, day_badge],
+            show_progress_on=[sim_status],
+        )
+
+        # Reset timeline
+        reset_timeline_btn.click(
+            fn=on_reset_timeline,
+            inputs=[town_state],
+            outputs=[sim_result_state, town_map, timeline_strip, day_badge],
+        )
+
+        # Timeline day selection bridge
+        select_day_trigger.click(
+            fn=on_select_timeline_day,
+            inputs=[selected_day, town_state, timeline_state],
+            outputs=[
+                sim_result_state,
+                town_map,
+                freq_display,
+                monologue_display,
+                emotion_display,
+                action_display,
+                trace_json,
+                voice_player,
+                timeline_strip,
+                day_badge,
+            ],
         )
 
         # Tune frequency
         freq_slider.change(
             fn=tune_frequency,
             inputs=[freq_slider, sim_result_state],
-            outputs=[freq_display, monologue_display, emotion_display, action_display, trace_json],
+            outputs=[freq_display, monologue_display, emotion_display, action_display, trace_json, voice_player],
         )
 
         # Export local
@@ -882,10 +1624,9 @@ def create_app():
             outputs=[export_status],
         )
 
-        # Auto-load first town on app start
         app.load(
-            fn=lambda: on_load_town(available_towns[0]) if available_towns else ("", "", "", "", ""),
-            outputs=[town_map, agent_profile, town_state, event_title, event_content],
+            fn=lambda: on_load_town(available_towns[0] if available_towns else None),
+            outputs=_load_outputs,
         )
 
     return app

docs/plans/2026-06-12-wave3-timeline-mode.md

@@ -0,0 +1,912 @@
+# Wave 3: Chained Broadcasts / Timeline Mode — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** After each TRANSMIT, carry the previous simulation's `updated_state` into the next run so the town drifts across days, and display a clickable horizontal timeline strip that lets the user scrub through history.
+
+**Architecture:** Extend `Simulator.run_town_simulation` with an optional `previous_states` dict; add `timeline_state` gr.State (JSON list) in `app.py`; wire `on_transmit` to build/append entries and return strip HTML; add JS bridge (`selectTimelineDay`) mirroring the existing `selectAgent` pattern; add CSS to `theme.py`.
+
+**Tech Stack:** Python 3.11, Gradio 4.x, Pydantic v2, browser SpeechSynthesis (untouched), vanilla JS bridge pattern already in place.
+
+---
+
+## File Map
+
+| File | Change |
+|---|---|
+| `simulator.py` | Add `previous_states` optional param to `run_town_simulation` |
+| `app.py` | Add `timeline_state` gr.State; add `format_timeline_strip`, `format_day_badge`, `on_reset_timeline`, `on_select_timeline_day`; rewrite `on_transmit` signature; add hidden bridge components; add `selectTimelineDay` JS; wire new event handlers |
+| `theme.py` | Append CSS for `#timeline-strip`, `.timeline-pill`, `.day-badge`, `.timeline-empty` |
+
+---
+
+### Task 1: Extend `simulator.py` with `previous_states`
+
+**Files:**
+- Modify: `/Users/quyetthang/Desktop/Desktop/project/analog_town/simulator.py:154-208`
+
+- [ ] **Step 1: Rename the existing `initial_states` param to `previous_states` and make the fallback explicit**
+
+Open `simulator.py`. The `run_town_simulation` signature already has `initial_states: dict[str, AgentState] | None = None`. Rename it and guard the per-agent lookup so callers passing nothing get the same default state as today.
+
+Replace the full method signature + per-agent state lookup block:
+
+```python
+def run_town_simulation(
+    self,
+    town: Town,
+    event: BroadcastEvent,
+    previous_states: dict[str, AgentState] | None = None,
+    progress_callback=None,
+) -> SimulationResult:
+    """Run simulation for all agents in the town.
+
+    Args:
+        town: The town with agents
+        event: The broadcast event
+        previous_states: Optional dict of agent_id -> AgentState seeded from prior run
+        progress_callback: Optional callback(agent_name, status, index, total)
+
+    Returns:
+        SimulationResult with all transitions (failed agents are skipped)
+    """
+    transitions = []
+    total = len(town.agents)
+
+    for i, agent in enumerate(town.agents):
+        agent_name = agent.name
+        try:
+            if progress_callback:
+                progress_callback(agent_name, "processing", i, total)
+
+            state = (
+                previous_states.get(agent.id, self._get_initial_state(agent))
+                if previous_states
+                else self._get_initial_state(agent)
+            )
+
+            transition = self.run_agent_transition(agent, state, event)
+            transitions.append(transition)
+
+            if progress_callback:
+                progress_callback(agent_name, "complete", i, total)
+
+        except Exception as e:
+            print(f"⚠ Agent '{agent_name}' failed: {e}")
+            traceback.print_exc()
+            if progress_callback:
+                progress_callback(agent_name, f"failed: {str(e)[:100]}", i, total)
+            continue
+
+    return SimulationResult(
+        town_id=town.id,
+        event=event,
+        transitions=transitions,
+        created_at=datetime.now().isoformat(),
+    )
+```
+
+- [ ] **Step 2: Verify the import chain still works**
+
+```bash
+cd /Users/quyetthang/Desktop/Desktop/project/analog_town && python -c "from simulator import Simulator; print('OK')"
+```
+
+Expected output: `OK`
+
+- [ ] **Step 3: Verify backwards-compatibility with a quick unit call**
+
+```bash
+cd /Users/quyetthang/Desktop/Desktop/project/analog_town && python -c "
+from simulator import Simulator
+from schemas import AgentState
+s = Simulator.__new__(Simulator)
+# should accept no previous_states
+import inspect
+sig = inspect.signature(s.run_town_simulation)
+assert 'previous_states' in sig.parameters
+print('param OK:', list(sig.parameters.keys()))
+"
+```
+
+Expected: `param OK: ['self', 'town', 'event', 'previous_states', 'progress_callback']`
+
+---
+
+### Task 2: Add CSS to `theme.py`
+
+**Files:**
+- Modify: `/Users/quyetthang/Desktop/Desktop/project/analog_town/theme.py` — append before the closing `"""`
+
+- [ ] **Step 1: Append timeline CSS**
+
+Open `theme.py`. Find the final line `"""` (closing triple-quote of `CUSTOM_CSS`). Insert the following block **before** that closing quote:
+
+```css
+
+/* ===== WAVE 3: TIMELINE STRIP ===== */
+#timeline-strip {
+    width: 100%;
+    display: flex;
+    flex-direction: row;
+    flex-wrap: nowrap;
+    overflow-x: auto;
+    gap: 8px;
+    padding: 8px 12px;
+    background: linear-gradient(180deg, #0d1219 0%, #111820 100%);
+    border: 1px solid #2a3040;
+    border-radius: 10px;
+    margin-bottom: 10px;
+    box-sizing: border-box;
+    scrollbar-width: thin;
+    scrollbar-color: #2a3040 #0a0e14;
+    min-height: 54px;
+    align-items: center;
+}
+
+.timeline-empty {
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 11px;
+    color: #5a5248;
+    letter-spacing: 1px;
+    padding: 6px 0;
+    flex: 1;
+    text-align: center;
+}
+
+.timeline-pill {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 2px;
+    background: #161d27;
+    border: 1px solid #2a3040;
+    border-radius: 8px;
+    padding: 5px 10px 5px 8px;
+    cursor: pointer;
+    min-width: 100px;
+    max-width: 160px;
+    flex-shrink: 0;
+    transition: border-color 0.2s ease, box-shadow 0.2s ease;
+    user-select: none;
+}
+
+.timeline-pill:hover {
+    border-color: #ffb34766;
+    box-shadow: 0 0 10px rgba(255, 179, 71, 0.12);
+}
+
+.timeline-pill.active {
+    background: rgba(255, 179, 71, 0.07);
+    border-color: #ffb347;
+    box-shadow: 0 0 14px rgba(255, 179, 71, 0.25);
+}
+
+.pill-day {
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 9px;
+    font-weight: 700;
+    color: #ffb347;
+    letter-spacing: 2px;
+    text-transform: uppercase;
+}
+
+.timeline-pill:not(.active) .pill-day {
+    color: #8a8070;
+}
+
+.pill-title {
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 10px;
+    color: #e0d6c8;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    max-width: 140px;
+}
+
+.timeline-pill:not(.active) .pill-title {
+    color: #5a5248;
+}
+
+.pill-anomaly {
+    position: absolute;
+    top: 3px;
+    right: 4px;
+    font-size: 8px;
+    color: #ffb347;
+    font-family: 'IBM Plex Mono', monospace;
+    font-weight: 700;
+    line-height: 1;
+}
+
+.day-badge {
+    position: absolute;
+    top: 10px;
+    right: 12px;
+    background: #0a0e14;
+    border: 1px solid #ffb347;
+    border-radius: 6px;
+    padding: 3px 10px;
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 11px;
+    font-weight: 700;
+    color: #ffb347;
+    letter-spacing: 3px;
+    text-transform: uppercase;
+    text-shadow: 0 0 10px rgba(255, 179, 71, 0.4);
+    box-shadow: 0 0 12px rgba(255, 179, 71, 0.15);
+    z-index: 20;
+    pointer-events: none;
+}
+```
+
+- [ ] **Step 2: Verify CSS import still works**
+
+```bash
+cd /Users/quyetthang/Desktop/Desktop/project/analog_town && python -c "from theme import CUSTOM_CSS; assert '#timeline-strip' in CUSTOM_CSS; print('CSS OK')"
+```
+
+Expected: `CSS OK`
+
+---
+
+### Task 3: Add helper functions to `app.py`
+
+**Files:**
+- Modify: `/Users/quyetthang/Desktop/Desktop/project/analog_town/app.py` — add two pure helper functions after `format_action_display`
+
+- [ ] **Step 1: Add `format_timeline_strip` and `format_day_badge` helpers**
+
+Open `app.py`. Find the line that starts `def _build_voice_player(` (currently around line 294). Insert the two new helpers **immediately before** that function:
+
+```python
+def format_timeline_strip(timeline_json: str, active_day: int | None = None) -> str:
+    """Return a horizontal row of clickable day pills from a JSON timeline."""
+    if not timeline_json:
+        return '<div id="timeline-strip"><div class="timeline-empty">Broadcast to begin a day timeline ▸</div></div>'
+
+    try:
+        timeline = json.loads(timeline_json)
+    except Exception:
+        return '<div id="timeline-strip"><div class="timeline-empty">Broadcast to begin a day timeline ▸</div></div>'
+
+    if not timeline:
+        return '<div id="timeline-strip"><div class="timeline-empty">Broadcast to begin a day timeline ▸</div></div>'
+
+    if active_day is None:
+        active_day = timeline[-1]["day"]
+
+    pills = []
+    for entry in timeline:
+        day = entry["day"]
+        title = (entry.get("event_title") or "Broadcast")[:30]
+        if len(entry.get("event_title") or "") > 30:
+            title = title + "…"
+
+        sim = entry.get("sim_result", {})
+        transitions = sim.get("transitions", [])
+        anomaly_count = sum(
+            1 for t in transitions
+            if any(abs(v) > 0.6 for v in (t.get("emotion_delta") or {}).values())
+        )
+
+        active_class = "active" if day == active_day else ""
+        anomaly_html = f'<span class="pill-anomaly">⚠ {anomaly_count}</span>' if anomaly_count > 0 else ""
+
+        pills.append(
+            f'<div class="timeline-pill {active_class}" onclick="selectTimelineDay({day})">'
+            f'<span class="pill-day">DAY {day}</span>'
+            f'<span class="pill-title">{title}</span>'
+            f'{anomaly_html}'
+            f'</div>'
+        )
+
+    pills_html = "\n".join(pills)
+    return f'<div id="timeline-strip">{pills_html}</div>'
+
+
+def format_day_badge(day: int | None) -> str:
+    """Return an absolutely-positioned day badge HTML for the map panel."""
+    if day is None:
+        return ""
+    return f'<div class="day-badge">DAY {day}</div>'
+
+```
+
+- [ ] **Step 2: Verify helpers import cleanly**
+
+```bash
+cd /Users/quyetthang/Desktop/Desktop/project/analog_town && python -c "
+from app import format_timeline_strip, format_day_badge
+print(format_day_badge(3))
+print(format_timeline_strip(''))
+" 
+```
+
+Expected output:
+```
+<div class="day-badge">DAY 3</div>
+<div id="timeline-strip"><div class="timeline-empty">Broadcast to begin a day timeline ▸</div></div>
+```
+
+---
+
+### Task 4: Update `on_transmit` to chain previous states
+
+**Files:**
+- Modify: `/Users/quyetthang/Desktop/Desktop/project/analog_town/app.py:469-527` (the `on_transmit` function)
+
+- [ ] **Step 1: Replace `on_transmit` with the chaining version**
+
+Find and replace the entire `on_transmit` function (from `def on_transmit(` to the final `return status, result_json, updated_map`) with:
+
+```python
+def on_transmit(town_json, event_title, event_content, timeline_json, progress=gr.Progress()):
+    """Run the simulation, chaining from the last day's states if available."""
+    if not town_json:
+        return "⚠ Load a town first", "", gr.update(), timeline_json, format_timeline_strip(timeline_json), ""
+    if not event_content:
+        return "⚠ Enter a broadcast event", "", gr.update(), timeline_json, format_timeline_strip(timeline_json), ""
+
+    try:
+        town = Town(**json.loads(town_json))
+    except Exception as e:
+        return f"❌ Invalid town data: {e}", "", gr.update(), timeline_json, format_timeline_strip(timeline_json), ""
+
+    event = BroadcastEvent(
+        title=event_title or "Broadcast Event",
+        content=event_content,
+        source="Town Radio",
+    )
+
+    try:
+        client = ModelClient()
+        simulator = Simulator(model_client=client)
+    except Exception as e:
+        return f"❌ Model initialization failed: {e}", "", gr.update(), timeline_json, format_timeline_strip(timeline_json), ""
+
+    previous_states = None
+    current_timeline = []
+    if timeline_json:
+        try:
+            current_timeline = json.loads(timeline_json)
+            if current_timeline:
+                last_entry = current_timeline[-1]
+                last_result = SimulationResult(**last_entry["sim_result"])
+                previous_states = {
+                    t.agent_id: t.updated_state for t in last_result.transitions
+                }
+        except Exception:
+            current_timeline = []
+
+    day = len(current_timeline) + 1
+
+    status_lines = []
+
+    def progress_callback(name, status, index, total):
+        emoji = {"processing": "⏳", "complete": "✅"}.get(status.split(":")[0], "⚠")
+        line = f"{emoji} [{index+1}/{total}] {name}: {status}"
+        status_lines.append(line)
+        progress((index + 1) / total, desc=f"Processing {name}...")
+
+    try:
+        result = simulator.run_town_simulation(
+            town=town,
+            event=event,
+            previous_states=previous_states,
+            progress_callback=progress_callback,
+        )
+    except Exception as e:
+        return f"❌ Simulation failed: {e}", "", gr.update(), timeline_json, format_timeline_strip(timeline_json), ""
+
+    n_success = len(result.transitions)
+    n_total = len(town.agents)
+
+    if n_success == n_total:
+        status = f"✅ Signal acquired — {n_success}/{n_total} transmissions intercepted"
+    elif n_success > 0:
+        status = f"⚠ Partial signal — {n_success}/{n_total} transmissions intercepted"
+    else:
+        status = "❌ No signal — all transmissions failed"
+
+    status += "\n" + "\n".join(status_lines)
+
+    new_entry = {
+        "day": day,
+        "event_title": event_title or "Broadcast Event",
+        "event_content": event_content,
+        "sim_result": json.loads(result.model_dump_json()),
+    }
+    current_timeline.append(new_entry)
+    new_timeline_json = json.dumps(current_timeline)
+
+    result_json = result.model_dump_json(indent=2)
+    updated_map = format_town_map(town, None, result)
+    timeline_strip = format_timeline_strip(new_timeline_json, active_day=day)
+    day_badge = format_day_badge(day)
+
+    return status, result_json, updated_map, new_timeline_json, timeline_strip, day_badge
+```
+
+- [ ] **Step 2: Verify the function signature compiles**
+
+```bash
+cd /Users/quyetthang/Desktop/Desktop/project/analog_town && python -c "
+import inspect, app
+sig = inspect.signature(app.on_transmit)
+print(list(sig.parameters.keys()))
+"
+```
+
+Expected: `['town_json', 'event_title', 'event_content', 'timeline_json', 'progress']`
+
+---
+
+### Task 5: Add `on_reset_timeline` and `on_select_timeline_day` handlers
+
+**Files:**
+- Modify: `/Users/quyetthang/Desktop/Desktop/project/analog_town/app.py` — add after `on_transmit`
+
+- [ ] **Step 1: Add the two new handlers immediately after `on_transmit`**
+
+Find the line `def on_export_local(` and insert the following two functions **before** it:
+
+```python
+def on_reset_timeline(town_json):
+    """Clear the entire timeline and return to Day 1 default state."""
+    empty_strip = format_timeline_strip("")
+    if not town_json:
+        return "", "", empty_strip, ""
+    try:
+        town = Town(**json.loads(town_json))
+        map_html = format_town_map(town, None, None)
+    except Exception:
+        map_html = ""
+    return "", map_html, empty_strip, ""
+
+
+def on_select_timeline_day(day_str, town_json, timeline_json):
+    """Restore the map and sim_result to a specific historical day."""
+    _empty_voice = _build_voice_player(None)
+    empty_returns = (
+        "",   # sim_result_state
+        "",   # town_map (will stay current if we can't parse)
+        format_frequency_display(88.0, None, 0),
+        format_monologue(None, None),
+        format_emotion_bars(None),
+        format_action_display(None),
+        "",   # trace_json
+        _empty_voice,
+        format_timeline_strip(timeline_json),
+        "",   # day_badge
+    )
+
+    if not day_str or not timeline_json:
+        return empty_returns
+
+    try:
+        day = int(day_str)
+        timeline = json.loads(timeline_json)
+    except Exception:
+        return empty_returns
+
+    entry = next((e for e in timeline if e["day"] == day), None)
+    if not entry:
+        return empty_returns
+
+    try:
+        sim_result = SimulationResult(**entry["sim_result"])
+        town = Town(**json.loads(town_json)) if town_json else None
+    except Exception:
+        return empty_returns
+
+    result_json = sim_result.model_dump_json(indent=2)
+    map_html = format_town_map(town, None, sim_result) if town else ""
+    strip_html = format_timeline_strip(timeline_json, active_day=day)
+    badge_html = format_day_badge(day)
+
+    return (
+        result_json,
+        map_html,
+        format_frequency_display(88.0, None, 0),
+        format_monologue(None, None),
+        format_emotion_bars(None),
+        format_action_display(None),
+        "",
+        _empty_voice,
+        strip_html,
+        badge_html,
+    )
+```
+
+- [ ] **Step 2: Verify both handlers are importable**
+
+```bash
+cd /Users/quyetthang/Desktop/Desktop/project/analog_town && python -c "
+from app import on_reset_timeline, on_select_timeline_day; print('OK')
+"
+```
+
+Expected: `OK`
+
+---
+
+### Task 6: Add new UI components and JS bridge to `create_app`
+
+**Files:**
+- Modify: `/Users/quyetthang/Desktop/Desktop/project/analog_town/app.py` — inside `create_app`
+
+This task has multiple sub-steps. Read all of them before editing.
+
+- [ ] **Step 1: Add `timeline_state` gr.State near the other state declarations**
+
+Find the block:
+```python
+        # ── State ──
+        town_state = gr.State("")
+        sim_result_state = gr.State("")
+```
+
+Replace with:
+```python
+        # ── State ──
+        town_state = gr.State("")
+        sim_result_state = gr.State("")
+        timeline_state = gr.State("")
+```
+
+- [ ] **Step 2: Add hidden day-bridge components after the existing agent-bridge components**
+
+Find:
+```python
+        # ── Hidden Map Communication Inputs ──
+        selected_agent_id = gr.Textbox(elem_id="selected-agent-id", elem_classes=["hidden-component"], visible=True)
+        select_agent_trigger = gr.Button("Select Agent Trigger", elem_id="select-agent-trigger", elem_classes=["hidden-component"], visible=True)
+```
+
+Replace with:
+```python
+        # ── Hidden Map Communication Inputs ──
+        selected_agent_id = gr.Textbox(elem_id="selected-agent-id", elem_classes=["hidden-component"], visible=True)
+        select_agent_trigger = gr.Button("Select Agent Trigger", elem_id="select-agent-trigger", elem_classes=["hidden-component"], visible=True)
+
+        # ── Hidden Timeline Day Bridge ──
+        selected_day = gr.Textbox(elem_id="selected-day", elem_classes=["hidden-component"], visible=True)
+        select_day_trigger = gr.Button("Select Day Trigger", elem_id="select-day-trigger", elem_classes=["hidden-component"], visible=True)
+```
+
+- [ ] **Step 3: Add RESET button next to TRANSMIT**
+
+Find the transmit column block (starts with `with gr.Column(scale=2, min_width=180):`). Replace just the contents of that column to insert the reset button:
+
+Find:
+```python
+                with gr.Column(scale=2, min_width=180):
+                    gr.HTML('<div class="ctrl-label">▸ TRANSMIT</div>')
+                    transmit_btn = gr.Button(
+                        "🔊 TRANSMIT",
+                        variant="primary",
+                        elem_classes=["transmit-btn"],
+                        elem_id="transmit-btn",
+                    )
+                    sim_status = gr.Textbox(
+                        show_label=False,
+                        container=False,
+                        lines=2,
+                        max_lines=2,
+                        interactive=False,
+                        placeholder="Awaiting broadcast...",
+                        elem_id="sim-status",
+                    )
+```
+
+Replace with:
+```python
+                with gr.Column(scale=2, min_width=180):
+                    gr.HTML('<div class="ctrl-label">▸ TRANSMIT</div>')
+                    with gr.Row(equal_height=True):
+                        transmit_btn = gr.Button(
+                            "🔊 TRANSMIT",
+                            variant="primary",
+                            elem_classes=["transmit-btn"],
+                            elem_id="transmit-btn",
+                            scale=3,
+                        )
+                        reset_timeline_btn = gr.Button(
+                            "🔁 RESET",
+                            size="sm",
+                            elem_classes=["export-btn"],
+                            elem_id="reset-timeline-btn",
+                            scale=1,
+                        )
+                    sim_status = gr.Textbox(
+                        show_label=False,
+                        container=False,
+                        lines=2,
+                        max_lines=2,
+                        interactive=False,
+                        placeholder="Awaiting broadcast...",
+                        elem_id="sim-status",
+                    )
+```
+
+- [ ] **Step 4: Add timeline strip and day badge components**
+
+After the `#control-bar` Group closes (the line `# === MAIN STAGE (map+dossier on left | receiver on right) ===`), insert the timeline strip row:
+
+Find:
+```python
+        # === MAIN STAGE (map+dossier on left | receiver on right) ===
+        with gr.Row(elem_id="main-stage", equal_height=True):
+```
+
+Replace with:
+```python
+        # === TIMELINE STRIP (below control bar, full width) ===
+        timeline_strip = gr.HTML(
+            value=format_timeline_strip(""),
+            elem_id="timeline-strip-container",
+        )
+
+        # === MAIN STAGE (map+dossier on left | receiver on right) ===
+        with gr.Row(elem_id="main-stage", equal_height=True):
+```
+
+Then, inside `#map-panel`, after the `gr.HTML('<div class="panel-header">...')` line, add the day badge:
+
+Find:
+```python
+            with gr.Column(scale=6, min_width=420, elem_id="map-panel"):
+                gr.HTML('<div class="panel-header">🗺 TOWN MAP &middot; CLICK A SIGNAL NODE</div>')
+
+                town_map = gr.HTML(
+```
+
+Replace with:
+```python
+            with gr.Column(scale=6, min_width=420, elem_id="map-panel"):
+                gr.HTML('<div class="panel-header">🗺 TOWN MAP &middot; CLICK A SIGNAL NODE</div>')
+                day_badge = gr.HTML(
+                    value="",
+                    elem_id="day-badge-container",
+                )
+
+                town_map = gr.HTML(
+```
+
+- [ ] **Step 5: Verify the UI structure compiles without error**
+
+```bash
+cd /Users/quyetthang/Desktop/Desktop/project/analog_town && python -c "from app import create_app; create_app(); print('OK')"
+```
+
+Expected: `OK` (no traceback)
+
+---
+
+### Task 7: Wire all event handlers in `create_app`
+
+**Files:**
+- Modify: `/Users/quyetthang/Desktop/Desktop/project/analog_town/app.py` — the `# ── Event Handlers ──` section
+
+- [ ] **Step 1: Update the transmit_btn.click binding**
+
+Find:
+```python
+        # Transmit
+        transmit_btn.click(
+            fn=on_transmit,
+            inputs=[town_state, event_title, event_content],
+            outputs=[sim_status, sim_result_state, town_map],
+        )
+```
+
+Replace with:
+```python
+        # Transmit
+        transmit_btn.click(
+            fn=on_transmit,
+            inputs=[town_state, event_title, event_content, timeline_state],
+            outputs=[sim_status, sim_result_state, town_map, timeline_state, timeline_strip, day_badge],
+        )
+```
+
+- [ ] **Step 2: Add reset_timeline_btn.click binding**
+
+After the transmit binding, add:
+
+```python
+        # Reset timeline
+        reset_timeline_btn.click(
+            fn=on_reset_timeline,
+            inputs=[town_state],
+            outputs=[sim_result_state, town_map, timeline_strip, day_badge],
+        )
+```
+
+Wait — `on_reset_timeline` returns 4 values: `("", map_html, empty_strip, "")`. The outputs map is:
+- `""` → `sim_result_state`
+- `map_html` → `town_map`
+- `empty_strip` → `timeline_strip`
+- `""` → `day_badge`
+
+That is correct as written above.
+
+- [ ] **Step 3: Add select_day_trigger.click binding**
+
+After the reset binding, add:
+
+```python
+        # Timeline day selection bridge
+        select_day_trigger.click(
+            fn=on_select_timeline_day,
+            inputs=[selected_day, town_state, timeline_state],
+            outputs=[
+                sim_result_state,
+                town_map,
+                freq_display,
+                monologue_display,
+                emotion_display,
+                action_display,
+                trace_json,
+                voice_player,
+                timeline_strip,
+                day_badge,
+            ],
+        )
+```
+
+- [ ] **Step 4: Verify full create_app compiles**
+
+```bash
+cd /Users/quyetthang/Desktop/Desktop/project/analog_town && python -c "from app import create_app; create_app(); print('OK')"
+```
+
+Expected: `OK`
+
+---
+
+### Task 8: Add `selectTimelineDay` JS to `CUSTOM_JS_TEMPLATE`
+
+**Files:**
+- Modify: `/Users/quyetthang/Desktop/Desktop/project/analog_town/app.py` — `CUSTOM_JS_TEMPLATE` string
+
+- [ ] **Step 1: Append the timeline JS bridge at the end of `CUSTOM_JS_TEMPLATE`**
+
+Find the last few lines of `CUSTOM_JS_TEMPLATE` (before the closing `"""`):
+
+```javascript
+// Chrome workaround: speech engine auto-pauses after ~15s of inactivity. Keep it warm.
+setInterval(function() {
+    if (window.speechSynthesis && window.speechSynthesis.speaking && window.speechSynthesis.paused) {
+        window.speechSynthesis.resume();
+    }
+}, 5000);
+```
+
+Insert **after** those lines (before the `"""`):
+
+```javascript
+
+window.selectTimelineDay = function(n) {
+    console.log("selectTimelineDay called with day:", n);
+    const container = document.getElementById("selected-day");
+    if (container) {
+        const input = container.querySelector("input") || container.querySelector("textarea");
+        if (input) {
+            let prototype = Object.getPrototypeOf(input);
+            let descriptor = Object.getOwnPropertyDescriptor(prototype, "value");
+            while (prototype && !descriptor) {
+                prototype = Object.getPrototypeOf(prototype);
+                descriptor = Object.getOwnPropertyDescriptor(prototype, "value");
+            }
+            const setter = descriptor ? descriptor.set : null;
+            if (setter) {
+                setter.call(input, String(n));
+            } else {
+                input.value = String(n);
+            }
+            input.dispatchEvent(new Event("input", { bubbles: true }));
+
+            setTimeout(() => {
+                const btn = document.getElementById("select-day-trigger");
+                if (btn) {
+                    console.log("Clicking select-day-trigger button");
+                    btn.click();
+                } else {
+                    console.error("select-day-trigger button not found");
+                }
+            }, 50);
+        } else {
+            console.error("Input/textarea not found inside #selected-day");
+        }
+    } else {
+        console.error("#selected-day container not found");
+    }
+};
+```
+
+- [ ] **Step 2: Verify JS template still contains the selectAgent function**
+
+```bash
+cd /Users/quyetthang/Desktop/Desktop/project/analog_town && python -c "
+from app import CUSTOM_JS
+assert 'selectAgent' in CUSTOM_JS
+assert 'selectTimelineDay' in CUSTOM_JS
+assert 'select-day-trigger' in CUSTOM_JS
+print('JS OK')
+"
+```
+
+Expected: `JS OK`
+
+---
+
+### Task 9: Acceptance checks
+
+- [ ] **Step 1: Verify import**
+
+```bash
+cd /Users/quyetthang/Desktop/Desktop/project/analog_town && python -c "from app import create_app; create_app(); print('OK')"
+```
+
+Expected: `OK`
+
+- [ ] **Step 2: Start server, wait, check HTTP 200**
+
+```bash
+pkill -f "python app.py" 2>/dev/null; sleep 1
+cd /Users/quyetthang/Desktop/Desktop/project/analog_town && python app.py > /tmp/analog_app.log 2>&1 &
+sleep 8
+curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:7860
+```
+
+Expected: `200`
+
+- [ ] **Step 3: Check server logs for errors**
+
+```bash
+tail -25 /tmp/analog_app.log
+```
+
+Expected: No Python tracebacks; should see Gradio startup messages.
+
+- [ ] **Step 4: Kill server**
+
+```bash
+pkill -f "python app.py"
+```
+
+---
+
+## Self-Review Checklist
+
+**Spec coverage:**
+
+| Spec requirement | Task covering it |
+|---|---|
+| `previous_states` param in `run_town_simulation` | Task 1 |
+| `timeline_state` gr.State (JSON list) | Task 6 Step 1 |
+| `on_transmit` reads timeline, seeds states, appends entry, returns 6 values | Task 4 |
+| `format_timeline_strip` helper | Task 3 |
+| `format_day_badge` helper | Task 3 |
+| RESET button + `on_reset_timeline` | Task 5 + Task 6 Step 3 + Task 7 Step 2 |
+| `on_select_timeline_day` handler | Task 5 |
+| `selected_day` + `select_day_trigger` hidden bridge components | Task 6 Step 2 |
+| `selectTimelineDay` JS function | Task 8 |
+| `select_day_trigger.click` wiring | Task 7 Step 3 |
+| `timeline_strip` HTML component in layout | Task 6 Step 4 |
+| `day_badge` HTML component in map panel | Task 6 Step 4 |
+| CSS for all new elements | Task 2 |
+| Backwards-compatibility (old callers unchanged) | Task 1 |
+| Wave 1/2 not broken (format_town_map, voice_player untouched) | No changes to those functions |
+
+**Type/signature consistency check:**
+
+- `on_transmit` returns 6-tuple: `(sim_status_str, result_json_str, map_html_str, timeline_json_str, strip_html_str, badge_html_str)` — outputs in Task 7 Step 1 list exactly 6 components matching that order. ✓
+- `on_reset_timeline` returns 4-tuple: `("", map_html, empty_strip, "")` — outputs in Task 7 Step 2 list exactly 4 components. ✓
+- `on_select_timeline_day` returns 10-tuple — outputs in Task 7 Step 3 list exactly 10 components. ✓
+- `format_timeline_strip(timeline_json, active_day=None)` called consistently throughout. ✓
+- `previous_states` param name in Task 1 matches usage in Task 4. ✓

model_client.py

@@ -1,12 +1,40 @@
 """Model client for Analog Town using Hugging Face Inference API."""
 
+import io
 import json
+import logging
 import os
 import re
 from dotenv import load_dotenv
 from huggingface_hub import InferenceClient
 from prompts import REPAIR_PROMPT
 
+logger = logging.getLogger(__name__)
+
+TTS_MODELS = [
+    "microsoft/speecht5_tts",
+    "facebook/mms-tts-eng",
+]
+
+
+def synthesize_speech(text: str, token: str | None = None) -> bytes | None:
+    """Call HF Inference TTS and return raw WAV bytes, or None on failure."""
+    _token = token or os.getenv("HF_TOKEN")
+    if not _token:
+        return None
+    client = InferenceClient(token=_token)
+    for model in TTS_MODELS:
+        try:
+            result = client.text_to_speech(text, model=model)
+            if hasattr(result, "read"):
+                return result.read()
+            if isinstance(result, (bytes, bytearray)):
+                return bytes(result)
+        except Exception as exc:
+            logger.warning("TTS model %s failed: %s", model, exc)
+            continue
+    return None
+
 load_dotenv()
 
 # Model fallback chain (ensuring all models are under 32B parameters for hackathon rules)

prompts.py

@@ -92,6 +92,68 @@ Required schema:
 {schema}"""
 
 
+TOWN_GENERATION_PROMPT = """You are a world-builder for Analog Town, a shortwave social simulator.
+
+Generate a complete fictional town with exactly {n_agents} residents based on the concept below.
+
+Return STRICT JSON ONLY — no markdown, no code fences, no commentary. The JSON must exactly match the schema shown.
+
+CONCEPT: {concept}
+
+REQUIRED JSON STRUCTURE:
+{{
+  "id": "<snake_case_slug_no_spaces>",
+  "name": "<Town Name>",
+  "description": "<1-2 sentence town description>",
+  "map_image": "town_map.png",
+  "agents": [
+    {{
+      "id": "<snake_case_agent_id>",
+      "name": "<Full Name>",
+      "frequency": <float between 87.0 and 108.0>,
+      "role": "<their role in this town>",
+      "age_range": "<XX-XX>",
+      "public_description": "<one sentence public description>",
+      "private_history": ["<sentence 1>", "<sentence 2>", "<sentence 3>"],
+      "core_values": ["<value1>", "<value2>", "<value3>"],
+      "fears": ["<fear1>", "<fear2>"],
+      "hopes": ["<hope1>", "<hope2>"],
+      "relationships": {{
+        "<other_agent_id>": "<one sentence describing this agent's view of the other>"
+      }},
+      "speaking_style": "<description of how they talk>",
+      "forbidden_assumptions": ["<what not to assume about this agent>"],
+      "map_pos": {{"x": <int 10-90>, "y": <int 10-90>}},
+      "avatar": "<one of: avatars/elder_man.png, avatars/elder_woman.png, avatars/middle_man.png, avatars/middle_woman.png, avatars/young_man.png, avatars/young_woman.png, avatars/soldier_man.png, avatars/default.png>"
+    }}
+  ],
+  "default_event": {{
+    "title": "<short event title>",
+    "content": "<2-3 sentence description of the central conflict or event in this town>",
+    "source": "<source name, e.g. town radio, local newspaper>",
+    "location": "<location name>",
+    "affected_groups": ["<group1>", "<group2>"],
+    "tone": "<neutral, tense, hopeful, alarming, or somber>"
+  }}
+}}
+
+RULES:
+- Generate exactly {n_agents} agents.
+- Each agent id must be unique snake_case (e.g., "old_miller", "young_petra").
+- Frequencies must be spread across 87.0-108.0 with at least 2.0 MHz between adjacent stations.
+- Each agent's relationships dict must reference at least 2 other agents in this town by their id.
+- private_history must have 2-3 sentences.
+- core_values must have exactly 3 items.
+- fears must have exactly 2 items.
+- hopes must have exactly 2 items.
+- forbidden_assumptions must have 1-2 items.
+- map_pos x and y must be integers between 10 and 90, spread so agents don't overlap.
+- avatar must be one of the listed paths exactly.
+- The town id must be a snake_case slug with no spaces or special characters.
+- Do not repeat the concept verbatim — build a coherent fictional world around it.
+- Return valid JSON only. No markdown. No explanation."""
+
+
 PERSONA_GENERATION_PROMPT = """Create a fictional persona for the Analog Town simulator.
 
 The persona should be a resident of a small town. Return valid JSON matching this structure:

sample_towns/custom_happy_sanctuary_town.json

@@ -0,0 +1,255 @@
+{
+  "id": "custom_happy_sanctuary_town",
+  "name": "Harmony Grove",
+  "description": "Harmony Grove is a small, close-knit community that values peace and unity above all else.",
+  "map_image": "custom_happy_sanctuary_town_map.png",
+  "agents": [
+    {
+      "id": "elder_miller",
+      "name": "Elder Miller",
+      "frequency": 87.0,
+      "role": "Community Elder",
+      "age_range": "65-75",
+      "public_description": "Elder Miller is a respected member of the community, known for his wisdom and kindness.",
+      "private_history": [
+        "He has lived in Harmony Grove for over 50 years and has seen the town grow and change.",
+        "He lost his wife to illness last year and is now more focused on helping others.",
+        "He enjoys telling stories about the old days to the younger generations."
+      ],
+      "core_values": [
+        "Peace",
+        "Unity",
+        "Community"
+      ],
+      "fears": [
+        "Conflict",
+        "Isolation"
+      ],
+      "hopes": [
+        "Prosperity",
+        "Harmony"
+      ],
+      "relationships": {
+        "young_petra": "Elder Miller looks up to Petra for her energy and enthusiasm.",
+        "middle_woman": "He values the middle woman's practical advice and support."
+      },
+      "speaking_style": "Elderly and wise, with a soft, soothing voice.",
+      "forbidden_assumptions": [
+        "He is not interested in modern technology or changes."
+      ],
+      "map_pos": {
+        "x": 20,
+        "y": 70
+      },
+      "avatar": "avatars/elder_man.png"
+    },
+    {
+      "id": "young_petra",
+      "name": "Young Petra",
+      "frequency": 91.2,
+      "role": "Youth Leader",
+      "age_range": "18-25",
+      "public_description": "Petra is a vibrant and energetic leader of the youth group in Harmony Grove.",
+      "private_history": [
+        "She moved to Harmony Grove from the city a year ago and has quickly become a beloved figure.",
+        "She dreams of starting her own business and making Harmony Grove a hub for innovation.",
+        "She is working on a community garden project to bring people together."
+      ],
+      "core_values": [
+        "Innovation",
+        "Community",
+        "Progress"
+      ],
+      "fears": [
+        "Stagnation",
+        "Discord"
+      ],
+      "hopes": [
+        "Prosperity",
+        "Unity"
+      ],
+      "relationships": {
+        "elder_miller": "Petra respects Elder Miller's wisdom and seeks his guidance.",
+        "middle_woman": "She admires the middle woman's practicality and wants to learn from her."
+      },
+      "speaking_style": "Energetic and enthusiastic, with a clear and confident voice.",
+      "forbidden_assumptions": [
+        "She is not interested in traditional values or community norms."
+      ],
+      "map_pos": {
+        "x": 50,
+        "y": 40
+      },
+      "avatar": "avatars/young_woman.png"
+    },
+    {
+      "id": "middle_woman",
+      "name": "Middle Woman",
+      "frequency": 95.4,
+      "role": "Community Organizer",
+      "age_range": "45-55",
+      "public_description": "Middle Woman is a dedicated organizer who ensures that community events run smoothly.",
+      "private_history": [
+        "She has been organizing events in Harmony Grove for over 20 years.",
+        "She lost her husband to a tragic accident last year and is now more focused on helping others.",
+        "She enjoys planning gatherings that bring people together."
+      ],
+      "core_values": [
+        "Community",
+        "Unity",
+        "Support"
+      ],
+      "fears": [
+        "Isolation",
+        "Conflict"
+      ],
+      "hopes": [
+        "Prosperity",
+        "Harmony"
+      ],
+      "relationships": {
+        "elder_miller": "Middle Woman values Elder Miller's wisdom and guidance.",
+        "young_petra": "She sees Petra as a source of energy and enthusiasm."
+      },
+      "speaking_style": "Warm and reassuring, with a gentle and comforting tone.",
+      "forbidden_assumptions": [
+        "She is not interested in new ideas or changes."
+      ],
+      "map_pos": {
+        "x": 80,
+        "y": 60
+      },
+      "avatar": "avatars/middle_woman.png"
+    },
+    {
+      "id": "soldier_man",
+      "name": "Soldier Man",
+      "frequency": 99.6,
+      "role": "Veteran",
+      "age_range": "55-65",
+      "public_description": "Soldier Man is a retired veteran who now volunteers at the local community center.",
+      "private_history": [
+        "He served in the military for 20 years and has seen his fair share of conflict.",
+        "He is grateful for the peace he now enjoys in Harmony Grove.",
+        "He enjoys sharing his experiences with the younger generation."
+      ],
+      "core_values": [
+        "Patriotism",
+        "Community",
+        "Service"
+      ],
+      "fears": [
+        "War",
+        "Conflict"
+      ],
+      "hopes": [
+        "Peace",
+        "Harmony"
+      ],
+      "relationships": {
+        "elder_miller": "Soldier Man respects Elder Miller's wisdom and seeks his guidance.",
+        "young_petra": "He admires Petra's energy and enthusiasm."
+      },
+      "speaking_style": "Strong and resolute, with a deep and commanding voice.",
+      "forbidden_assumptions": [
+        "He is not interested in peace or community."
+      ],
+      "map_pos": {
+        "x": 30,
+        "y": 30
+      },
+      "avatar": "avatars/soldier_man.png"
+    },
+    {
+      "id": "middle_man",
+      "name": "Middle Man",
+      "frequency": 103.8,
+      "role": "Local Business Owner",
+      "age_range": "45-55",
+      "public_description": "Middle Man owns the general store in Harmony Grove and is a beloved figure in the community.",
+      "private_history": [
+        "He has owned the store for 15 years and has seen the town grow and change.",
+        "He is proud of his community and wants to ensure its prosperity.",
+        "He enjoys helping his customers and making their lives easier."
+      ],
+      "core_values": [
+        "Community",
+        "Prosperity",
+        "Support"
+      ],
+      "fears": [
+        "Economic downturn",
+        "Conflict"
+      ],
+      "hopes": [
+        "Prosperity",
+        "Harmony"
+      ],
+      "relationships": {
+        "elder_miller": "Middle Man values Elder Miller's wisdom and guidance.",
+        "young_petra": "He sees Petra as a source of energy and enthusiasm."
+      },
+      "speaking_style": "Warm and friendly, with a reassuring and comforting tone.",
+      "forbidden_assumptions": [
+        "He is not interested in new ideas or changes."
+      ],
+      "map_pos": {
+        "x": 60,
+        "y": 80
+      },
+      "avatar": "avatars/middle_man.png"
+    },
+    {
+      "id": "young_man",
+      "name": "Young Man",
+      "frequency": 108.0,
+      "role": "Tech Innovator",
+      "age_range": "25-35",
+      "public_description": "Young Man is a tech innovator who is working on a project to improve communication in Harmony Grove.",
+      "private_history": [
+        "He moved to Harmony Grove a year ago to pursue his passion for technology.",
+        "He dreams of creating a platform that connects people and improves their lives.",
+        "He is working on a community garden project to bring people together."
+      ],
+      "core_values": [
+        "Innovation",
+        "Community",
+        "Progress"
+      ],
+      "fears": [
+        "Stagnation",
+        "Discord"
+      ],
+      "hopes": [
+        "Prosperity",
+        "Unity"
+      ],
+      "relationships": {
+        "elder_miller": "Young Man respects Elder Miller's wisdom and seeks his guidance.",
+        "middle_woman": "He admires the middle woman's practicality and wants to learn from her."
+      },
+      "speaking_style": "Energetic and enthusiastic, with a clear and confident voice.",
+      "forbidden_assumptions": [
+        "He is not interested in traditional values or community norms."
+      ],
+      "map_pos": {
+        "x": 90,
+        "y": 50
+      },
+      "avatar": "avatars/young_man.png"
+    }
+  ],
+  "default_event": {
+    "title": "Community Garden Opening",
+    "content": "The community garden project, led by Young Petra and supported by Middle Woman, is finally opening to the public. Elder Miller and Soldier Man will be there to celebrate.",
+    "source": "Harmony Grove Community Bulletin",
+    "location": "Harmony Grove Community Garden",
+    "affected_groups": [
+      "Youth",
+      "Community Organizers",
+      "Veterans",
+      "Business Owners"
+    ],
+    "tone": "Hopeful"
+  }
+}

simulator.py

@@ -115,6 +115,7 @@ class Simulator:
         agent: AgentProfile,
         state: AgentState,
         event: BroadcastEvent,
+        day: int = 1,
     ) -> StateTransition:
         """Run a single agent through the state transition.
 
@@ -122,6 +123,7 @@ class Simulator:
             agent: The agent's profile
             state: The agent's current state
             event: The broadcast event
+            day: 1-indexed broadcast day, used to instruct the model to vary follow-up beats
 
         Returns:
             StateTransition with updated state and monologue
@@ -129,18 +131,34 @@ class Simulator:
         Raises:
             RuntimeError: If both generation and repair fail
         """
-        # Build the prompt
         user_prompt = STATE_TRANSITION_PROMPT.format(
             agent_profile=agent.model_dump_json(indent=2),
             previous_state=state.model_dump_json(indent=2),
             broadcast_event=event.model_dump_json(indent=2),
         )
 
-        # Generate JSON from model
-        transition_data = self.model_client.generate_json(
-            system_prompt=SYSTEM_PROMPT,
-            user_prompt=user_prompt,
-        )
+        if day > 1:
+            user_prompt = (
+                f"DAY {day} OF THIS SCENARIO. "
+                f"The agent has already lived through {day - 1} previous broadcast(s). "
+                "The fields current_belief, active_memory, and unresolved_tension in 'Previous State' "
+                "capture where the agent ENDED LAST TIME — they are CONTEXT, not your script. "
+                "Write a FRESH internal_monologue that is clearly different in wording from any prior beat: "
+                "the agent has had time to process, talk to others, sleep on it, or harden their view. "
+                "Make at least one emotion_delta non-zero. Do NOT echo any sentence verbatim from current_belief.\n\n"
+                + user_prompt
+            )
+
+        original_temp = getattr(self.model_client, "temperature", 0.3)
+        try:
+            if day > 1:
+                self.model_client.temperature = min(0.85, original_temp + 0.25)
+            transition_data = self.model_client.generate_json(
+                system_prompt=SYSTEM_PROMPT,
+                user_prompt=user_prompt,
+            )
+        finally:
+            self.model_client.temperature = original_temp
 
         # Validate and fix
         is_valid, error_msg = self._validate_transition(transition_data, agent)
@@ -155,15 +173,16 @@ class Simulator:
         self,
         town: Town,
         event: BroadcastEvent,
-        initial_states: dict[str, AgentState] | None = None,
+        previous_states: dict[str, AgentState] | None = None,
         progress_callback=None,
+        day: int = 1,
     ) -> SimulationResult:
         """Run simulation for all agents in the town.
 
         Args:
             town: The town with agents
             event: The broadcast event
-            initial_states: Optional dict of agent_id -> AgentState
+            previous_states: Optional dict of agent_id -> AgentState seeded from prior run
             progress_callback: Optional callback(agent_name, status, index, total)
 
         Returns:
@@ -178,15 +197,13 @@ class Simulator:
                 if progress_callback:
                     progress_callback(agent_name, "processing", i, total)
 
-                # Get or create initial state
                 state = (
-                    initial_states.get(agent.id)
-                    if initial_states
+                    previous_states.get(agent.id, self._get_initial_state(agent))
+                    if previous_states
                     else self._get_initial_state(agent)
                 )
 
-                # Run transition
-                transition = self.run_agent_transition(agent, state, event)
+                transition = self.run_agent_transition(agent, state, event, day=day)
                 transitions.append(transition)
 
                 if progress_callback:

theme.py

@@ -550,6 +550,38 @@ input[type="range"]::-webkit-slider-thumb:hover {
     image-rendering: pixelated;
     image-rendering: crisp-edges;
     animation: pulse-radar 2s infinite;
+    transition: border-color 0.4s ease, box-shadow 0.4s ease, background-color 0.4s ease;
+}
+
+.anomaly-flag {
+    position: absolute;
+    top: -10px;
+    right: -10px;
+    width: 16px;
+    height: 16px;
+    background: #0a0e14;
+    border: 1.5px solid #ffb347;
+    border-radius: 50%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 9px;
+    line-height: 1;
+    z-index: 15;
+    box-shadow: 0 0 8px rgba(255, 179, 71, 0.7);
+    animation: anomaly-pulse 1.4s ease-in-out infinite;
+    pointer-events: none;
+}
+
+@keyframes anomaly-pulse {
+    0%, 100% {
+        transform: scale(1);
+        box-shadow: 0 0 6px rgba(255, 179, 71, 0.5);
+    }
+    50% {
+        transform: scale(1.18);
+        box-shadow: 0 0 14px rgba(255, 179, 71, 0.9);
+    }
 }
 
 .agent-sprite.selected-sprite .sprite-avatar {
@@ -831,15 +863,22 @@ input[type="range"]::-webkit-slider-thumb:hover {
 @media (min-width: 1100px) {
     #map-panel,
     #receiver-panel {
-        min-height: calc(100vh - 320px);
-        max-height: calc(100vh - 200px);
+        min-height: 620px;
     }
-    /* Map shrinks if the column is short, but never disappears */
+    /* Cap the map so the dossier always shows below it */
     #town-map,
     #town-map .town-map-wrapper,
     #town-map .town-map-bg {
-        max-height: calc(100vh - 620px) !important;
-        min-height: 280px !important;
+        max-height: 360px !important;
+        min-height: 260px !important;
+    }
+    /* Dossier always visible with a guaranteed strip below the map */
+    #dossier-accordion {
+        min-height: 220px !important;
+    }
+    #agent-profile {
+        max-height: 220px !important;
+        min-height: 160px !important;
     }
 }
 
@@ -858,4 +897,153 @@ input[type="range"]::-webkit-slider-thumb:hover {
         max-height: 320px !important;
     }
 }
+
+/* ===== WAVE 3: TIMELINE STRIP ===== */
+#timeline-strip {
+    width: 100%;
+    display: flex;
+    flex-direction: row;
+    flex-wrap: nowrap;
+    overflow-x: auto;
+    gap: 8px;
+    padding: 8px 12px;
+    background: linear-gradient(180deg, #0d1219 0%, #111820 100%);
+    border: 1px solid #2a3040;
+    border-radius: 10px;
+    margin-bottom: 10px;
+    box-sizing: border-box;
+    scrollbar-width: thin;
+    scrollbar-color: #2a3040 #0a0e14;
+    min-height: 54px;
+    align-items: center;
+}
+
+.timeline-empty {
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 11px;
+    color: #5a5248;
+    letter-spacing: 1px;
+    padding: 6px 0;
+    flex: 1;
+    text-align: center;
+}
+
+.timeline-pill {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 2px;
+    background: #161d27;
+    border: 1px solid #2a3040;
+    border-radius: 8px;
+    padding: 5px 10px 5px 8px;
+    cursor: pointer;
+    min-width: 100px;
+    max-width: 160px;
+    flex-shrink: 0;
+    transition: border-color 0.2s ease, box-shadow 0.2s ease;
+    user-select: none;
+}
+
+.timeline-pill:hover {
+    border-color: #ffb34766;
+    box-shadow: 0 0 10px rgba(255, 179, 71, 0.12);
+}
+
+.timeline-pill.active {
+    background: rgba(255, 179, 71, 0.07);
+    border-color: #ffb347;
+    box-shadow: 0 0 14px rgba(255, 179, 71, 0.25);
+}
+
+.pill-day {
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 9px;
+    font-weight: 700;
+    color: #ffb347;
+    letter-spacing: 2px;
+    text-transform: uppercase;
+}
+
+.timeline-pill:not(.active) .pill-day {
+    color: #8a8070;
+}
+
+.pill-title {
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 10px;
+    color: #e0d6c8;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    max-width: 140px;
+}
+
+.timeline-pill:not(.active) .pill-title {
+    color: #5a5248;
+}
+
+.pill-anomaly {
+    position: absolute;
+    top: 3px;
+    right: 4px;
+    font-size: 8px;
+    color: #ffb347;
+    font-family: 'IBM Plex Mono', monospace;
+    font-weight: 700;
+    line-height: 1;
+}
+
+.day-badge {
+    position: absolute;
+    top: 10px;
+    right: 12px;
+    background: #0a0e14;
+    border: 1px solid #ffb347;
+    border-radius: 6px;
+    padding: 3px 10px;
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 11px;
+    font-weight: 700;
+    color: #ffb347;
+    letter-spacing: 3px;
+    text-transform: uppercase;
+    text-shadow: 0 0 10px rgba(255, 179, 71, 0.4);
+    box-shadow: 0 0 12px rgba(255, 179, 71, 0.15);
+    z-index: 20;
+    pointer-events: none;
+}
+
+/* ===== CREATIVE MODE ===== */
+#creative-mode {
+    background: linear-gradient(180deg, #111820 0%, #0d1219 100%) !important;
+    border: 1px solid rgba(255, 179, 71, 0.35) !important;
+    border-radius: 10px !important;
+    margin-bottom: 10px !important;
+    box-shadow: 0 0 18px rgba(255, 179, 71, 0.06) !important;
+}
+
+#creative-mode > .label-wrap {
+    font-family: 'IBM Plex Mono', monospace !important;
+    font-size: 11px !important;
+    color: #ffb347 !important;
+    letter-spacing: 2px !important;
+    text-transform: uppercase !important;
+}
+
+#creative-json {
+    font-family: 'IBM Plex Mono', monospace !important;
+    font-size: 11px !important;
+    background: #0a0e14 !important;
+    border: 1px solid #2a3040 !important;
+    border-radius: 6px !important;
+}
+
+#creative-status {
+    font-family: 'IBM Plex Mono', monospace !important;
+    font-size: 11px !important;
+    color: #8a8070 !important;
+    margin-top: 4px !important;
+}
 """

town_generator.py

@@ -0,0 +1,45 @@
+"""Town generator: produces a fully-validated Town dict from a concept string."""
+
+from prompts import SYSTEM_PROMPT, TOWN_GENERATION_PROMPT
+from schemas import Town
+
+
+def generate_town(concept: str, n_agents: int, model_client=None) -> dict:
+    """Generate a town JSON from a concept string. Returns a Pydantic-validated dict.
+    Post-processes to enforce frequency spread, clamp map_pos, and namespace the id."""
+    if model_client is None:
+        from model_client import ModelClient
+        model_client = ModelClient(max_tokens=4000)
+
+    user_prompt = TOWN_GENERATION_PROMPT.format(concept=concept, n_agents=n_agents)
+    town_dict = model_client.generate_json(SYSTEM_PROMPT, user_prompt)
+
+    town = Town(**town_dict)
+
+    if len(town.agents) < n_agents:
+        raise RuntimeError(
+            f"Model returned {len(town.agents)} agents but {n_agents} were requested."
+        )
+
+    sorted_agents = sorted(town.agents, key=lambda a: a.frequency)
+    if n_agents > 1:
+        step = (108.0 - 87.0) / (n_agents - 1)
+    else:
+        step = 0.0
+    for i, agent in enumerate(sorted_agents):
+        agent.frequency = round(87.0 + i * step, 1)
+
+    for agent in town.agents:
+        pos = agent.map_pos or {"x": 50, "y": 50}
+        pos["x"] = max(10, min(90, int(pos.get("x", 50))))
+        pos["y"] = max(10, min(90, int(pos.get("y", 50))))
+        agent.map_pos = pos
+
+    if not town.id.startswith("custom_"):
+        town.id = f"custom_{town.id}"
+
+    if not town.map_image:
+        town.map_image = "town_map.png"
+
+    town = Town(**town.model_dump())
+    return town.model_dump()