docs/developer_implementation_guide.md

# Trans-Temporal Express — Developer Implementation Guide

> **For: AI Development Agent**
> **From: UX Design Agent**
> **Status: All visual assets generated. Audio files need sourcing. Ready for implementation.**

---

## 1. Vision & Experience Summary

You are re-skinning the "AI Time Machine" — a voice-to-voice conversation app where users travel to different historical/future eras and have live conversations with AI-generated characters. The current UI uses a dark steampunk/industrial theme with concentric rings and abstract portals. **You are replacing it entirely** with a warm, whimsical "train cab" experience called **"The Trans-Temporal Express."**

### The Core Metaphor
The user is the **engineer** of a magical time-traveling locomotive. They sit inside the cab, look out through a large arched windshield, pull a brass throttle lever, and hurtle through time — watching era signs fly past — until they brake at a destination. Steam clears to reveal the world, and a historical character walks up to the window for a voice conversation.

### Art Style
Warm, polished cartoon illustration — like a high-quality animated film. NOT photorealistic. Think Studio Ghibli meets Art Deco. Color palette: warm browns, amber brass, copper accents, cream text, cyan holographic accents.

### Reference Image
See `docs/images/Gemini_Generated_Image_6eqvyh6eqvyh6eqv(1).png` — this is the approved visual target for the cockpit view. Note the simple warm wood panels, arched window, brass throttle at center, holographic comm screen at bottom-right, and a character visible through the windshield.

---

## 2. What Already Exists (DO NOT REBUILD)

The backend is fully functional. You only need to rebuild the **frontend layer** (HTML/CSS/JS). The following work:

### Backend (Leave Untouched)
| File | What It Does |
|------|-------------|
| `app.py` | FastAPI + Gradio mount. Entry point. `/blank` → intro, `/app` → cockpit |
| `src/time_machine/ui/handlers.py` | `GradioHandlers` — `launch()`, `send_text()`, `send_audio()`, `bring_souvenir()`, `save()` |
| `src/time_machine/ui/view_models.py` | `UiRenderState` — processes events, builds `render_immersive_payload()` JSON |
| `src/time_machine/ui/realtime.py` | WebSocket realtime voice — STT/TTS pipeline |
| `src/time_machine/ui/gradio_app.py` | Gradio Blocks layout — **you WILL modify this** to inject new HTML/CSS/JS |
| `src/time_machine/domain/models.py` | Domain models (Destination, Persona, ImmersiveScene, etc.) |
| `src/time_machine/application/` | Service layer — encounter orchestration, image gen, TTS |

### Key Communication Pattern
The frontend receives state via a hidden Gradio `Textbox` with `elem_id="tm-immersive-payload"`. The JavaScript polls this every 750ms via `currentPayload()` and calls `updateCockpitState(payload)` to update the DOM.

**The payload JSON structure** (from `render_immersive_payload()` in `view_models.py`):
```json

{

  "session_id": "...",

  "encounter_id": "...",

  "machine_state": "dormant|launching|destination|persona|conversation_ready",

  "current_year": 2026,

  "target_year": 1492,

  "direction": "rewind|fast_forward|hold",

  "destination": {

    "place": "Port of Palos, Spain",

    "mode": "past",

    "atmosphere": "Salt-stung harbor at dawn...",

    "visual_preset": "harbor_dawn",

    "motifs": ["wooden_ships", "compass_roses"]

  },

  "persona": {

    "name": "Isabella",

    "role": "Harbor master's daughter",

    "situation": "Watching strange ships being loaded..."

  },

  "scene": { "image_b64": "...", "prompt": "...", "ambient_key": "ocean" },

  "portrait": { "image_b64": "...", "prompt": "..." },

  "narration": { "text": "...", "audio_path": "data:audio/wav;base64,..." },

  "artifact": { "title": "...", "kind": "...", "image_b64": "..." },

  "ambient_key": "ocean"

}

```

### Realtime Voice (Leave Untouched)
The voice system connects via WebSocket at `/realtime/voice`. The existing `cockpit.js` handles:
- Microphone capture → PCM audio → WebSocket
- WebSocket → PCM playback (character voice)
- JSON control messages for turn management
- VAD (Voice Activity Detection) with configurable thresholds

**You must preserve the realtime voice section of cockpit.js** (the `initRealtimeVoice()` IIFE starting at ~line 509). The UI just needs the toggle button and status display wired up.

---

## 3. What You Need To Build

### 3A. Intro Sequence (replaces `intro.html` + `intro.css` + `intro.js`)

**Current**: A 32-second industrial facility walkthrough (corridors, vault doors, observatory clock). Too dark/sterile.

**New**: A ~20-second magical ticket-punching sequence:

| Beat | Duration | Visual | Audio | Assets |
|------|----------|--------|-------|--------|
| **1. Ticket Appears** | 0–6s | Dark void. A brass "Temporal Ticket" materializes, floating center-screen with a gentle glow and slow rotation | Low procedural hum (Web Audio oscillator) | `static/img/intro/temporal_ticket.png` |
| **2. Conductor Box** | 6–11s | An ornate mechanical conductor box appears. Ticket slides into it. Flash of light on punch. Gears begin to grind. Energy lines ripple outward | `ticket_clang.mp3`, `charge_up.mp3`, `gears_grinding.mp3` | `static/img/intro/conductor_box.png`, `static/img/overlays/energy_lines.png` |
| **3. Train Materializes** | 11–18s | Shockwave explosion of golden energy. The Trans-Temporal Express materializes through the energy — fading from transparent to solid. Train whistle sounds. Steam billows | `shockwave.mp3`, `materialize.mp3`, `train_whistle.mp3`, `steam_burst.mp3` | `static/img/intro/train_materialization.png`, `static/img/overlays/spark_particles.png` |
| **4. Board the Train** | 18–22s | Screen flashes white, then fades into the cockpit view. Transition to `/app` | Flash transition (CSS) | None — redirect to cockpit |

**Skip button**: Preserve the existing skip-intro button behavior (click or 32s timeout → redirect to `/app`).

**Intro HTML/CSS**: Build entirely new. The current corridor/vault/clock HTML is not reused.

---

### 3B. Cockpit View (replaces `cockpit.html` + `cockpit.css` + cockpit portions of `cockpit.js`)

**Current**: Dark steampunk portal with concentric rings, timeline bar, separate portrait aperture.

**New**: First-person train cab with arched windshield. Reference: `docs/images/Gemini_Generated_Image_6eqvyh6eqvyh6eqv(1).png`

#### DOM Structure
```

#tm-cockpit  (full viewport container, carries state classes)

├── .tte-viewport  (z:10 — windshield content area)

│   ├── .tte-idle-bg  (idle_viewport.png — default tracks-to-sky)

│   ├── .tte-travel-bg  (travel_future.png or travel_past.png — during travel)

│   ├── .tte-world-scene  (#tm-world-image — AI-generated destination)

│   ├── .tte-character  (#tm-portrait-image — AI-generated character)

│   └── .tte-era-signs-container  (dynamically spawned HTML signs)

├── .tte-overlays  (z:50-90 — effect layers)

│   ├── .tte-speed-lines  (speed_lines.png, mix-blend-mode:screen)

│   ├── .tte-energy-lines  (energy_lines.png, for materialization)

│   ├── .tte-steam-cloud  (steam_cloud.png, for landing reveal)

│   ├── .tte-vignette  (CSS radial-gradient, always on)

│   └── .tte-film-grain  (CSS SVG noise, always on, very subtle)

├── .tte-cockpit-frame  (z:100 — the cab interior frame)

│   └── Built with CSS gradients (see approach below)

├── .tte-dashboard  (z:110 — bottom dashboard)

│   ├── .tte-gauges  (gauge_cluster.png — bottom-left)

│   ├── .tte-throttle  (chrono_throttle_neutral.png — bottom-center)

│   └── .tte-comm-screen  (comm_screen.png — bottom-right)

├── .tte-year-module  (z:130 — top center)

│   ├── .tte-year-label  ("DESTINATION")

│   └── .tte-year-counter  (#tm-year-counter — animated year display)

├── .tte-narration  (#tm-narration-caption — bottom text overlay)

├── .tte-live-voice  (voice toggle button + meter + status)

├── #tm-narration-audio  (hidden audio element)

├── #tm-ambient-audio  (hidden audio element)

└── #tm-artifact-panel  (artifact display, preserved from current)

```

#### Cockpit Frame Approach (IMPORTANT)
**Do NOT use cockpit_frame.png as the main frame.** Instead, build the frame with CSS gradients:

```css

/* Top arch shadow */

radial-gradient(ellipse 120% 30% at 50% 0%, #2A1810 0%, transparent 70%),

/* Left panel */

linear-gradient(90deg, #2A1810 0%, transparent 12%),

/* Right panel */

linear-gradient(270deg, #2A1810 0%, transparent 12%),

/* Bottom dashboard */

linear-gradient(0deg, #1A0F08 0%, #2A1810 15%, transparent 35%)

```

Add a brass trim border using `::after` pseudo-element with a rounded top border-radius.



This gives full flexibility for responsive layouts and the windshield transparency.



#### State-Driven CSS Classes

The cockpit element `#tm-cockpit` should have these state classes (same pattern as current code):



| State | Class | Visual |

|-------|-------|--------|

| Dormant | `.tm-state-dormant` | Idle viewport visible, throttle neutral, gauges calm, launch pulse |

| Launching | `.tm-state-launching` | Throttle rotates, charge-up effect, energy builds |

| Traveling | `.tm-state-traveling` | Travel bg visible, speed lines rotating, screen shake, era signs flying, year counter animating |

| Braking | `.tm-state-braking` | Violent shake, sparks, speed lines intensify |

| Destination | `.tm-state-destination` | Steam cloud covers viewport |

| Persona | `.tm-state-persona` | Steam clears, world image visible |

| Conversation Ready | `.tm-state-conversation-ready` | World + character visible, cockpit frame dimmed, character breathing animation, ambient audio |



---



### 3C. Travel Sequence (NEW — no current equivalent)



When the user clicks "Launch" and the backend starts processing, you need to show a travel animation. Map the `machine_state` transitions to the visual sequence:



1. **`launching`** → Throttle rotates to PAST or FUTURE (based on `direction`). Charge-up SFX.
2. **Wait ~2s** → Transition to travel animation (CSS-driven)
3. **`destination`** → Era signs start flying. Speed lines activate. Year counter animates from `current_year` → `target_year`. Travel background visible.
4. **When world image arrives** (`scene.image_b64` populated) → Begin braking: violent shake, brake screech SFX.
5. **`persona`** → Steam cloud rises, world image loads behind it. Steam clears.
6. **`conversation_ready`** → Character visible, ambient audio playing, voice channel enabled.



#### Era Signs (HTML elements, NOT images)

During travel, spawn HTML `<div>` elements with era names that fly across the viewport:

```html

<div class="tte-era-sign future" style="--sign-speed: 1.2s">THE SPACE AGE: 1960s</div>

```

CSS animates them from right-to-left (future) or left-to-right (past). They should have:

- Dark green background with brass border

- Playfair Display font, cream text, uppercase

- Brass post extending downward (::after pseudo-element)

- Varying vertical positions (30-60% from top) for depth

- Getting faster as travel progresses



See `static/css/tte_reference.css` for the complete animation keyframes.



#### Year Counter

The existing `animateYearCounter()` function in cockpit.js already handles this — keep it.



---



### 3D. Audio System Enhancements



#### Current Audio

- Procedural ambient via Web Audio API oscillators (keep this as fallback)

- Narration audio via `<audio>` element

- Ambient audio via `<audio>` element with loop



#### Enhancement: SFX Playback

Add an SFX system that loads and plays one-shot sound effects:

```javascript

// Preload during init

const sfxBuffers = {};

async function preloadSFX(key, url) {

  const response = await fetch(url);

  const buffer = await audioContext.decodeAudioData(await response.arrayBuffer());

  sfxBuffers[key] = buffer;

}

function playSFX(key) {

  if (!sfxBuffers[key]) return;

  const source = audioContext.createBufferSource();

  source.buffer = sfxBuffers[key];

  source.connect(sfxGainNode);

  source.start();

}

```



#### Audio Ducking

When the character speaks (realtime voice), duck the ambient audio to ~15% volume. Unduck when the user is speaking or silence.



#### Audio Files

Sound effects are NOT yet downloaded. See `static/audio/sound_sources.md` for specific search queries to find each sound on Pixabay/Mixkit/Freesound. All must be royalty-free.



**Directory structure:**

```

static/audio/

├── sfx/

│   ├── ticket_clang.mp3

│   ├── steam_burst.mp3

│   ├── brake_screech.mp3

│   ├── gears_grinding.mp3

│   ├── train_chug.mp3

│   ├── train_whistle.mp3

│   ├── materialize.mp3

│   ├── time_warp.mp3

│   ├── charge_up.mp3

│   ├── shockwave.mp3

│   ├── chime.mp3

│   ├── lever_pull.mp3

│   └── button_click.mp3

└── ambient/

    ├── temporal_storm.mp3

    ├── rain.mp3

    ├── marketplace.mp3

    ├── fire_hearth.mp3

    ├── wind.mp3

    ├── machinery.mp3

    ├── ocean.mp3

    ├── night_insects.mp3

    ├── desert.mp3

    └── scifi_hum.mp3

```



**If audio files are not available, gracefully degrade.** The experience must work without sounds — just without audio feedback.



---



## 4. Asset Locations



### Generated Image Assets



| Category | File | Usage |

|----------|------|-------|

| **Cockpit** | `static/img/cockpit/cockpit_frame.png` | Reference only — use CSS gradients instead |

| **Cockpit** | `static/img/cockpit/chrono_throttle_neutral.png` | Throttle lever — CSS rotate: -25° FUTURE, 0° NEUTRAL, +25° PAST |
| **Cockpit** | `static/img/cockpit/comm_screen.png` | Dashboard right — pulse brightness when character speaks |
| **Cockpit** | `static/img/cockpit/gauge_cluster.png` | Dashboard left — shake during travel |
| **Cockpit** | `static/img/cockpit/idle_viewport.png` | Default windshield content — magical tracks leading to glowing sky |
| **Intro** | `static/img/intro/temporal_ticket.png` | Floating ticket prop in intro |
| **Intro** | `static/img/intro/conductor_box.png` | Ticket punch machine in intro |
| **Intro** | `static/img/intro/ticket_scene.png` | Reference composition only — do not use directly |
| **Intro** | `static/img/intro/train_materialization.png` | Train appearing with golden energy in intro |
| **Travel** | `static/img/travel/travel_future.png` | Viewport bg during future travel (cyan/blue energy tunnel) |
| **Travel** | `static/img/travel/travel_past.png` | Viewport bg during past travel (warm amber/sepia tunnel) |
| **Overlay** | `static/img/overlays/steam_cloud.png` | Landing steam reveal — normal blend, z:90 |
| **Overlay** | `static/img/overlays/energy_lines.png` | Intro shockwave — screen blend, z:80 |
| **Overlay** | `static/img/overlays/speed_lines.png` | Travel velocity — screen blend, z:50, CSS rotate |
| **Overlay** | `static/img/overlays/spark_particles.png` | Particle sprite reference — screen blend |
| **Reference** | `static/img/reference/concept_cab_interior.png` | Initial concept art — reference only |

### Reference Code
| File | What It Contains |
|------|-----------------|
| `static/css/tte_reference.css` | Complete CSS with design tokens, layout, 15+ animation keyframes, state transitions, responsive breakpoints |
| `static/js/tte_animation_reference.js` | AudioManager class, intro orchestrator, era sign spawner, year counter, landing sequence |
| `static/asset_manifest.json` | Complete JSON manifest with all assets, timing, z-index, animation specs, state machine |

---

## 5. Design System

### Colors (CSS Custom Properties)
```css

--tte-brass: #C4943D;

--tte-amber: #D4A843;

--tte-burgundy: #6B2D3E;

--tte-copper: #B87333;

--tte-cyan: #8ED8D1;

--tte-cream: #F5E6C8;

--tte-dark: #1A0F08;

--tte-darker: #0A0605;

--tte-mahogany: #2A1810;

```

### Typography
```css

--tte-font-heading: 'Playfair Display', Georgia, serif;  /* Era signs, year counter, titles */

--tte-font-body: 'Outfit', system-ui, sans-serif;        /* Status text, captions, UI labels */

```
Add Google Fonts link in the HTML head:
```html

<link href="https://fonts.googleapis.com/css2?family=Playfair+Display:wght@600;700&family=Outfit:wght@300;400;500&display=swap" rel="stylesheet">

```

### Key Animations (see `tte_reference.css` for full keyframes)

- `tte-screen-shake` — gentle cockpit vibration

- `tte-violent-shake` — braking impact with rotation

- `tte-speed-rotate` — speed lines 360° rotation over 30s

- `tte-shockwave` — energy expanding from center

- `tte-steam-drift` — steam cloud rising and dissipating

- `tte-idle-drift` — subtle parallax on idle viewport

- `tte-sign-fly-future` / `tte-sign-fly-past` — era signs crossing viewport

- `tte-comm-pulse` — comm screen glow when speaking

- `tte-character-breathe` — subtle scale 1.0→1.008 on character portrait

- `tte-launch-pulse` — ambient glow on launch button



---



## 6. Files You Need To Modify/Create



### Files to REPLACE (new content):

| File | Action |

|------|--------|

| `src/time_machine/ui/assets/intro.html` | **Replace entirely** — new ticket/train intro |
| `src/time_machine/ui/assets/intro.css` | **Replace entirely** — new intro styling |
| `src/time_machine/ui/assets/intro.js` | **Replace entirely** — new intro sequence logic |
| `src/time_machine/ui/assets/cockpit.html` | **Replace entirely** — new train cab layout |
| `src/time_machine/ui/assets/cockpit.css` | **Replace entirely** — new train cab styling |

### Files to MODIFY (careful edits):
| File | What to Change |
|------|---------------|
| `src/time_machine/ui/assets/cockpit.js` | Replace `updateCockpitState()` and the immersive cockpit init. **PRESERVE the `initRealtimeVoice()` IIFE** (lines ~509-1031) untouched. Add travel sequence logic, era sign spawning, SFX system |
| `src/time_machine/ui/gradio_app.py` | Update CSS/HTML injection. Load new assets. Add Google Fonts. **Keep all Gradio component wiring identical** — the handler inputs/outputs must not change |
| `src/time_machine/ui/blank_app.py` | May need update for intro page if it serves the intro HTML separately |

### Files to CREATE:
| File | Purpose |
|------|---------|
| (none required — all new code goes in the existing files above) | |

### Files to LEAVE ALONE:
Everything in `src/time_machine/application/`, `src/time_machine/domain/`, `src/time_machine/ports/`, `src/time_machine/adapters/`, `src/time_machine/prompts/`, `config/`, `app.py`

---

## 7. Gradio Integration Notes

### How the current system injects frontend code (`gradio_app.py`):

```python

css = (ASSET_DIR / "cockpit.css").read_text()

cockpit_html = (ASSET_DIR / "cockpit.html").read_text()
cockpit_js = (ASSET_DIR / "cockpit.js").read_text()

# CSS is embedded via: gr.HTML(f"<style>{css}</style>{cockpit_html}")
# JS is embedded via: gr.Blocks(head=f"<script>{cockpit_js}</script>")

```



### Image paths in CSS/HTML

Gradio serves static files from the `static/` directory. Reference images as:

```

/file=static/img/cockpit/idle_viewport.png
```

The current `bg.png` is base64-encoded and embedded in CSS by `gradio_app.py`. You can either:

1. Continue this pattern for critical images (faster load, no extra requests)

2. Use `/file=static/...` paths for non-critical images (cleaner code)



### Hidden Gradio Components (MUST PRESERVE)

These invisible components carry state between Python and JS:

- `#tm-immersive-payload` — JSON payload polled by cockpit.js every 750ms

- `#tm-realtime-session` — realtime voice config (encounter_id, ready state)

- All Gradio inputs (mode dropdown, coordinate prompt, launch button, etc.)



### The Gradio Controls Row

The current Gradio layout has visible controls (mode dropdown, coordinate prompt, launch button, send text, microphone, etc.) in `gr.Row()` blocks below the cockpit HTML. These **must remain functional** but can be visually restyled to match the new theme. Consider:

- Styling the Launch button as a brass-colored action button

- Making the control rows blend with the dark theme

- Keeping all `elem_id` values the same



---



## 8. Critical Implementation Order



1. **Cockpit HTML + CSS first** — get the static layout right

2. **State-driven CSS transitions** — wire up class toggling

3. **cockpit.js updateCockpitState()** — adapt to new DOM structure

4. **Travel sequence** — era signs, speed lines, year counter

5. **Landing/steam reveal** — test with actual launch flow

6. **Intro sequence** — ticket → conductor → materialization → redirect

7. **Audio SFX system** — layer on top of working visuals

8. **Polish** — responsive, reduced-motion, edge cases



---



## 9. Testing



### Manual Test Flow

1. Go to `/blank` → intro should play → skip or wait → redirect to `/app`

2. At `/app` → cockpit visible in dormant state (idle viewport, throttle neutral)

3. Select mode "past", type "ancient rome" → click Launch

4. Observe: launching → traveling (signs, speed lines) → destination → steam → conversation_ready

5. Click "Live voice" → speak → character responds via voice

6. Verify ambient audio matches destination (`ambient_key` from payload)



### Edge Cases

- Launch without coordinates (mode="surprise") — should still work

- Multiple rapid launches — state should reset cleanly

- No audio permission — SFX silently fails, visuals still work

- Mobile viewport — responsive layout for smaller screens

- `prefers-reduced-motion` — disable all animations



---



## 10. Asset Status Summary



| Category | Count | Status |

|----------|-------|--------|

| Cockpit images | 5 | ✅ Ready |

| Intro images | 4 | ✅ Ready (1 is reference-only) |

| Travel backgrounds | 2 | ✅ Ready |

| Overlay effects | 4 | ✅ Ready |

| Reference images | 1 | ✅ Ready |

| CSS reference | 1 | ✅ Ready (`static/css/tte_reference.css`) |

| JS reference | 1 | ✅ Ready (`static/js/tte_animation_reference.js`) |

| Asset manifest | 1 | ✅ Ready (`static/asset_manifest.json`) |

| Sound effects | 13 | ⬜ Need to download (see `static/audio/sound_sources.md`) |

| Ambient loops | 10 | ⬜ Need to download (see `static/audio/sound_sources.md`) |



> **Note**: The app must work WITHOUT audio files. Build visuals first, then layer audio on top. The SFX system should gracefully degrade if files are missing.