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):

{
  "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:

/* 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:

<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:

// 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)

--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

--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:

<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):

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.