# Phase 5: Live Show Execution - Research

**Researched:** 2026-04-07
**Domain:** Real-time cue scheduling, canvas preview, show persistence, keyboard UX
**Confidence:** HIGH — all findings verified against existing codebase; no external library discovery needed

## Summary

Phase 5 is almost entirely an integration and wiring task on top of already-built infrastructure. The server-side scheduler slots into the existing `ws.py` `tick` branch with ~30 lines of Python. The live preview panel is a new HTML `<div>` strip that receives `preview_update` WebSocket messages and paints colored rectangles via Canvas 2D or simple DOM elements. Show persistence already works at the API level — Phase 5 connects the show selector UI to `setCurrentShowId()` and wires up a `load` message to the WebSocket so the server can acquire the cue list per connection. Keyboard shortcuts are pure `document.addEventListener('keydown')` in `app.js`.

The only non-trivial decision already made by the context session is the seek-safe cue reset: on a `seek` event the server must mark all cues with `timestamp < new_position` as already-fired, so they don't re-trigger after a backward seek. The 60ms look-ahead window eliminates missed cues at 10Hz tick rate — this is the timing contract the planner must implement faithfully.

The frontend preview panel can be fully DOM-driven (one `<div>` per device, background-color CSS updated by JS) rather than requiring a `<canvas>`. This avoids coordinate math overhead and matches the flat-rect terminal aesthetic described in the context. Canvas is also valid and may be used if the planner prefers uniform rendering with the timeline.

**Primary recommendation:** Wire scheduler into the existing `tick` branch in `ws.py`, add `preview_update` broadcast alongside each UDP send, add a minimal DOM preview strip between `.timeline-container` and `.transport-bar`, and implement 5 keyboard event listeners in `app.js`.

<user_constraints>
## User Constraints (from CONTEXT.md)

### Locked Decisions

- **D-01:** Server-side scheduling — the server fires UDP commands, not the browser. On each WebSocket `tick`, the server scans the current show's cue list and dispatches `UDPSender.send()` for any block due to fire.
- **D-02:** 60ms look-ahead window — if a block's `timestamp` is within 60ms ahead of the current tick position, fire it immediately. This prevents missed cues at 10Hz tick rate (max ~100ms tick gap). Blocks fire slightly early, never late.
- **D-03:** Seek-safe reset — on `seek` events, the server resets the "already fired" cue pointer so no cues are double-fired or skipped after a seek.
- **D-04:** The server needs the current show's cue list available per-connection. Wire this up by loading the active show from `show_store` in the WebSocket handler when a `load` message arrives (browser already sends this when audio loads).
- **D-05:** Animation color + type per device — show the active animation type and its color as a simple strip per device. No per-LED frame simulation; just which animation is active and in what color. Turns dark when no block is active on a device.
- **D-06:** Panel placement: below the timeline canvas, above the transport bar — always visible during playback. Layout: TIMELINE → LIVE PREVIEW → TRANSPORT BAR.
- **D-07:** Preview updates are driven by the same WebSocket `tick` loop — when the server fires a cue, it also broadcasts a `preview_update` message so the browser canvas reflects the new state.

### Claude's Discretion

- **Keyboard shortcuts (UI-03):** Standard DAW conventions: Space = play/pause, Left/Right arrow = seek ±5s, Ctrl+Z = undo, Ctrl+Shift+Z or Ctrl+Y = redo, Ctrl+S = explicit save. Planner decides exact key bindings but these are safe defaults.
- **Show save/load UX:** All block mutations already auto-save via CRUD API. Add Ctrl+S as an explicit "save now" shortcut that calls the existing save endpoint. Show loading: use existing show selector dropdown + a "load" button. No need to redesign.
- **Preview panel height:** Compact — 40-60px total. One row per device, enough for a labeled color strip. Collapsible if many devices.

### Deferred Ideas (OUT OF SCOPE)

- Per-LED frame simulation in the preview (see what the chase animation actually looks like moving) — v2 or Phase 6+
- Preview panel as a standalone full-screen mode — out of scope
- Keyboard shortcut customization UI — out of scope for v1
</user_constraints>

<phase_requirements>
## Phase Requirements

| ID | Description | Research Support |
|----|-------------|------------------|
| SHW-03 | Live show execution — follow MPV position, dispatch animation commands to devices via UDP at correct timestamps | D-01 through D-04 in CONTEXT.md; `ws.py` tick branch, `UDPSender.send()`, `show_store.load()`, `encode_animation_cmd()` all in place |
| UI-03 | All primary operations accessible without mouse (keyboard shortcuts for play/pause/seek/undo) | `document.addEventListener('keydown')` in `app.js`; audio element and `timeline.history` already wired |
| UI-04 | Live preview panel — simulated LED strip visualization in browser canvas, synced to playback | New DOM strip in `index.html`, driven by `preview_update` WebSocket messages from server |
</phase_requirements>

---

## Standard Stack

### Core (no new libraries needed)

All work happens in the existing stack. No new Python packages or npm modules are required.

| Layer | Tech | Version | Purpose |
|-------|------|---------|---------|
| Backend scheduler | Python / FastAPI | 3.11 / existing | Extend `ws.py` tick handler |
| UDP dispatch | `UDPSender` + `encode_animation_cmd` | Phase 3 built | Send animation commands to devices |
| Show data | `ShowStore` + Pydantic `ShowModel` | Phase 1 built | Load cue list per connection |
| WebSocket protocol | FastAPI WebSocket | existing | Extend with `load` show_id field + `preview_update` broadcast |
| Frontend preview | Vanilla JS + CSS | existing | New `<div>` strip, no canvas required |
| Keyboard shortcuts | Browser `keydown` event | native | `document.addEventListener` in `app.js` |

**Installation:** none required.

---

## Architecture Patterns

### Recommended Project Structure (delta from current)

```
lightsync/
├── api/
│   └── ws.py                  # EXTEND: cue scheduler in tick branch
├── frontend/
│   ├── index.html             # EXTEND: add #live-preview div between canvas and transport
│   ├── style.css              # EXTEND: .live-preview, .device-strip styles
│   └── app.js                 # EXTEND: preview_update handler, keyboard shortcuts
```

No new files strictly required. The planner may choose to extract a `preview.js` module if the preview logic grows beyond ~50 lines.

### Pattern 1: Server-side Cue Scheduler

**What:** Inside the `tick` branch of `websocket_endpoint`, maintain per-connection state: the loaded `ShowModel` and a `set` of already-fired cue IDs. On each tick, iterate all tracks and cues; fire any cue whose timestamp is in `[position, position + 0.060]` and is not in `fired_ids`.

**When to use:** Every tick message while playback is active.

**Key state variables to add to `websocket_endpoint`:**

```python
# Inside websocket_endpoint, alongside existing per-connection state:
show: ShowModel | None = None
fired_ids: set[str] = set()
is_playing: bool = False
```

**Scheduler logic inside the tick branch:**

```python
elif msg_type == "tick":
    position = float(msg.get("position", 0.0))
    is_playing = True  # receiving ticks implies playing
    
    if show is not None:
        LOOKAHEAD = 0.060  # 60ms window (D-02)
        udp = websocket.app.state.udp_sender
        for track in show.tracks:
            device = next(
                (d for d in show.devices if str(d.id) == str(track.device_id)), None
            )
            if device is None:
                continue
            for cue in track.cues:
                cue_id = str(cue.id)
                if cue_id in fired_ids:
                    continue
                if cue.timestamp > position + LOOKAHEAD:
                    continue
                if cue.timestamp < position - 0.1:
                    # Too far in the past — mark fired without sending
                    fired_ids.add(cue_id)
                    continue
                # Fire this cue
                fired_ids.add(cue_id)
                if cue.animation:
                    try:
                        payload = encode_animation_cmd(cue.animation, cue.params)
                        udp.send(payload, device.ip, device.port)
                    except ValueError:
                        logger.warning("[ws] unknown animation %r", cue.animation)
                    # Broadcast preview_update to all browser clients (D-07)
                    color = cue.params.get("color", [0, 255, 180])
                    await manager.broadcast({
                        "type": "preview_update",
                        "device_id": str(track.device_id),
                        "animation": cue.animation,
                        "color": color,
                    })
```

**Seek-safe reset (D-03):** On `seek`, rebuild `fired_ids` to include all cues with `timestamp < seek_position`. This prevents re-fire of past cues and ensures future cues fire correctly.

```python
elif msg_type == "seek":
    position = float(msg.get("position", 0.0))
    last_beat_reported = None
    # Rebuild fired_ids: mark everything before seek position as fired
    if show is not None:
        fired_ids = {
            str(cue.id)
            for track in show.tracks
            for cue in track.cues
            if cue.timestamp < position - 0.060
        }
```

**Load show on `load` message (D-04):** The browser already sends `{"type": "load", "path": "..."}` when audio loads. Extend this handler to also accept `show_id`:

```python
elif msg_type == "load":
    # Existing beat loading...
    show_id = msg.get("show_id")
    if show_id:
        show_store = getattr(websocket.app.state, "show_store", None)
        # show_store lives at module level in main.py
        import lightsync.main as _main
        loaded = await _main.show_store.load(show_id)
        if loaded:
            show = loaded
            fired_ids = set()
            logger.info("[ws] loaded show %s with %d tracks", show_id, len(show.tracks))
```

**Anti-pattern to avoid:** Do not load the show on every tick — load once on `load` message, cache per-connection.

### Pattern 2: Live Preview Panel (DOM-based)

**What:** A horizontal strip of `<div>` elements, one per device. Each device strip has a label and a colored fill rectangle. When a `preview_update` message arrives, update the background-color of the matching device strip. When audio pauses or ends, dim all strips.

**HTML structure:**

```html
<!-- Between <canvas id="timeline-canvas"> and <div id="block-inspector"> -->
<div id="live-preview" class="live-preview" style="display:none;">
  <!-- Populated dynamically by JS when devices load -->
</div>
```

**JS message handler:**

```javascript
// In LightSyncClient.ws.onmessage:
if (msg.type === 'preview_update') {
    updatePreviewStrip(msg.device_id, msg.animation, msg.color);
}

function updatePreviewStrip(deviceId, animation, color) {
    const strip = document.querySelector(`[data-device-id="${deviceId}"]`);
    if (!strip) return;
    const [r, g, b] = color;
    strip.style.backgroundColor = `rgb(${r},${g},${b})`;
    strip.querySelector('.strip-anim').textContent = animation.toUpperCase().replace('_', ' ');
}
```

**CSS pattern (terminal aesthetic):**

```css
.live-preview {
    border-top: 1px solid var(--border-dim);
    border-bottom: 1px solid var(--border-dim);
    background: var(--bg-panel-dark);
    display: flex;
    flex-direction: column;
    gap: 1px;
    padding: 2px 0;
    max-height: 60px;
    overflow-y: auto;
}
.device-strip {
    display: flex;
    align-items: center;
    height: 18px;
    padding: 0 4px;
    background: var(--bg-panel);
    gap: 8px;
    font-size: 11px;
    font-family: var(--font-mono);
    letter-spacing: 0.05em;
    transition: background-color 0.1s;
}
.strip-label { color: var(--text-dim); text-transform: uppercase; min-width: 80px; }
.strip-color {
    width: 40px; height: 10px;
    background: var(--text-dim);  /* inactive state */
    flex-shrink: 0;
}
.strip-anim { color: var(--text-dim); font-size: 10px; }
```

**Inactive state:** When no block is active on a device, strip background stays `var(--bg-panel)` and `.strip-color` stays `var(--text-dim)` — consistent with the UI's dim inactive visual language.

**Alternative:** The preview could use a `<canvas>` element (one per device), but DOM approach is simpler, achieves the same visual result for this fidelity level, and doesn't require coordinate mapping.

### Pattern 3: Keyboard Shortcuts

**What:** `document.addEventListener('keydown', handler)` in `app.js`, added after `wireAudio()` and `initTimeline()` are called.

**Bindings (Claude's discretion per CONTEXT.md):**

| Key | Action | Implementation |
|-----|--------|----------------|
| Space | Play/Pause | `audio.paused ? audio.play() : audio.pause()` |
| ArrowLeft | Seek -5s | `audio.currentTime = Math.max(0, audio.currentTime - 5)` |
| ArrowRight | Seek +5s | `audio.currentTime = Math.min(audio.duration, audio.currentTime + 5)` |
| Ctrl+Z | Undo | `timeline.history.undo()` |
| Ctrl+Shift+Z | Redo | `timeline.history.redo()` |
| Ctrl+Y | Redo (alt) | `timeline.history.redo()` |
| Ctrl+S | Explicit save | `fetch('/api/shows/${timeline.showId}', ...)` or no-op if no show loaded |

**Guard against input elements:** Skip shortcut if `document.activeElement` is an `<input>`, `<select>`, or `<textarea>`.

```javascript
function wireKeyboard(audio, timeline) {
    document.addEventListener('keydown', (e) => {
        const tag = document.activeElement?.tagName.toLowerCase();
        if (['input', 'select', 'textarea'].includes(tag)) return;
        
        if (e.code === 'Space') {
            e.preventDefault();
            audio.paused ? audio.play() : audio.pause();
        } else if (e.code === 'ArrowLeft') {
            e.preventDefault();
            audio.currentTime = Math.max(0, audio.currentTime - 5);
            client.send({ type: 'seek', position: audio.currentTime });
        } else if (e.code === 'ArrowRight') {
            e.preventDefault();
            audio.currentTime = Math.min(audio.duration || 0, audio.currentTime + 5);
            client.send({ type: 'seek', position: audio.currentTime });
        } else if (e.ctrlKey && !e.shiftKey && e.code === 'KeyZ') {
            e.preventDefault();
            timeline?.history.undo();
        } else if ((e.ctrlKey && e.shiftKey && e.code === 'KeyZ') || (e.ctrlKey && e.code === 'KeyY')) {
            e.preventDefault();
            timeline?.history.redo();
        } else if (e.ctrlKey && e.code === 'KeyS') {
            e.preventDefault();
            if (timeline?.showId) {
                fetch(`/api/shows/${timeline.showId}`)
                    .then(r => r.json())
                    .then(show => fetch(`/api/shows`, { 
                        method: 'POST',
                        headers: {'Content-Type': 'application/json'},
                        body: JSON.stringify(show)
                    }))
                    .catch(e => console.warn('[save]', e));
            }
        }
    });
}
```

Note: Ctrl+S save is a no-op if no show is loaded. The existing auto-save on every block mutation is the primary persistence mechanism — Ctrl+S is a manual trigger for peace of mind.

### Pattern 4: Show Persistence Round-Trip

**What:** Loading a show into the timeline editor (which re-populates `timeline.tracks` from show data) and sending `show_id` in the WebSocket `load` message so the server acquires the cue list.

**Current state:** `timeline.showId` is set when a show is explicitly loaded. The `setCurrentShowId()` function in `commands.js` ensures new block mutations auto-save to the show. The browser sends `{"type": "load", "path": "..."}` but does NOT currently send `show_id`.

**What Phase 5 must add:**
1. A show selector UI component (dropdown + "Load Show" button) in the sidebar or transport bar — calls `GET /api/shows` to list, then `GET /api/shows/{id}` to load full show including tracks.
2. When a show loads: call `timeline.loadTracksFromShow(show)` to populate `this.tracks` from `show.tracks`, call `setCurrentShowId(show.id)`, and send `{"type": "load", "show_id": show.id, "path": show.audio.path}` to the WebSocket.
3. On the server `load` handler: when `show_id` is present, load the show and set per-connection `show` state.

**`timeline.loadTracksFromShow(show)` — new method needed:**

```javascript
loadTracksFromShow(show) {
    // Merge show tracks into timeline.tracks which already has device metadata
    // Each track in show has {device_id, cues[]}
    // Each track in timeline has {device_id, device_name, strip_type, cues[]}
    for (const showTrack of show.tracks) {
        const existing = this.tracks.find(t => t.device_id === showTrack.device_id);
        if (existing) {
            existing.cues = showTrack.cues.map(cue => ({...cue}));
        } else {
            // Device not registered locally — skip or warn
            console.warn('[timeline] track for unknown device', showTrack.device_id);
        }
    }
}
```

**Alternative simpler approach:** Load devices from `show.devices` + cues in one call. This avoids the merge problem but requires `timeline.loadTracks()` to be extended to accept device config from the show snapshot rather than re-fetching from `/api/devices`.

### Pattern 5: index.html Layout Extension

**What:** The layout must accommodate the live preview panel. Current `main-area` contains only the toolbar, canvas, and block inspector. The preview panel must be inserted between canvas and inspector (or between inspector and transport).

**Existing layout order:**
```
.app-shell grid:
  header | header
  sidebar | main-area
  transport | transport

.main-area (flex column, inferred):
  #timeline-toolbar
  #timeline-canvas
  #block-inspector (hidden unless block selected)
```

**Required addition:**
```html
<main class="main-area">
    <div id="timeline-toolbar" class="timeline-toolbar">...</div>
    <canvas id="timeline-canvas"></canvas>
    <div id="live-preview" class="live-preview"></div>   <!-- NEW -->
    <div id="block-inspector" class="block-inspector" style="display:none;"></div>
</main>
```

The transport bar is already a separate `<footer>` in the grid — so the preview sits between the canvas area and the transport grid row, which matches D-06.

---

## Don't Hand-Roll

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| UDP socket pooling | Custom multi-socket manager | `UDPSender` (already built) | Single shared DatagramTransport is correct for UDP multi-device sends |
| Animation encoding | Custom binary format | `encode_animation_cmd()` (Phase 3) | Protocol already defined, tested, and firmware-compatible |
| Show serialization | Custom JSON schema | `ShowModel.model_dump_json()` + `model_validate_json()` | Pydantic handles UUID serialization, datetime, nested models |
| Beat/cue timing | Custom scheduler with asyncio.sleep | Position-driven scan in tick handler | `asyncio.sleep` timing is unreliable under load; tick-driven approach eliminates timer drift entirely |
| Multi-client WebSocket broadcast | Custom connection tracking | `manager.broadcast()` (already in `ws.py`) | Dead connection cleanup already handled |

**Key insight:** The entire cue scheduler is ~30 lines of Python inside an existing handler. There is no scheduling infrastructure to build — the 10Hz tick IS the scheduler clock.

---

## Common Pitfalls

### Pitfall 1: Double-fire on backward seek
**What goes wrong:** User seeks backward to t=10s. Cues between t=10 and previous position have `cue_id` NOT in `fired_ids` (because `fired_ids` was built forward). On the next tick they fire again.
**Why it happens:** `fired_ids` only tracks forward progress. Backward seek invalidates the set.
**How to avoid:** On `seek`, rebuild `fired_ids` = all cue IDs with `timestamp < new_position - 0.060`. This is the D-03 requirement.
**Warning signs:** Devices receive two UDP packets for the same block in quick succession.

### Pitfall 2: Cues not firing when paused then resumed
**What goes wrong:** User pauses at t=15.0s. A cue at t=15.3s was not in the 60ms window at the pause moment. User resumes — first tick arrives at t=15.1s (audio may buffer). The scheduler skips the t=15.3s cue because `fired_ids` already marks it (if marked at pause time).
**Why it happens:** Incorrectly marking cues as fired on pause.
**How to avoid:** On `pause`, do NOT add anything to `fired_ids`. Only mark cues as fired when they are actually dispatched.

### Pitfall 3: Cues firing during pause (tick leakage)
**What goes wrong:** The browser sends ticks on `timeupdate` event (line 126 in `app.js`) which fires even when audio isn't playing (e.g., during seek drag). The scheduler fires cues at the seeked-to position even before the user releases the seek bar.
**Why it happens:** `timeupdate` fires when `currentTime` changes regardless of play state. The 10Hz interval loop checks `!audio.paused` but `timeupdate` does not.
**How to avoid:** In the server `tick` handler, gate cue scheduling on an `is_playing` flag. Set to `true` on `play` message, `false` on `pause` message. Only run scheduler when `is_playing`.

### Pitfall 4: Show not loaded on server when show ID sent
**What goes wrong:** Browser sends `{"type": "load", "show_id": "...", "path": "..."}` but `show_store` is accessed as `websocket.app.state.show_store` — which doesn't exist. The show_store lives at module level in `main.py`, not on `app.state`.
**Why it happens:** `show_store` is `lightsync.main.show_store` (module-level), not `app.state.show_store`.
**How to avoid:** In `ws.py`, import `import lightsync.main as _main` and use `await _main.show_store.load(show_id)`.

### Pitfall 5: Preview strips not built until devices are loaded
**What goes wrong:** `index.html` renders the `#live-preview` div empty. If JS builds device strips at init time but devices haven't loaded yet, the preview is empty.
**Why it happens:** `loadDevices()` is async; preview strip population must happen after device list resolves.
**How to avoid:** Build preview strips inside the existing `loadDevices()` callback (or in `timeline.loadTracks()` after devices are fetched).

### Pitfall 6: Space bar triggers seek bar / button click
**What goes wrong:** Space key fires both the keyboard shortcut AND a button click (if a button has focus), causing play/pause to toggle twice.
**Why it happens:** Default browser behavior for Space on focused buttons is a click event.
**How to avoid:** Call `e.preventDefault()` in the Space keydown handler. Also check `document.activeElement` is not a `<button>` before handling Space — or always `preventDefault()` for space in this handler.

### Pitfall 7: Ctrl+S triggers browser's native save dialog
**What goes wrong:** Browser intercepts Ctrl+S and opens "Save Page As" before the JS handler runs.
**Why it happens:** Ctrl+S is a native browser shortcut. JavaScript handlers must call `e.preventDefault()` before it reaches the browser.
**How to avoid:** Always call `e.preventDefault()` first in the Ctrl+S branch.

---

## Code Examples

Verified patterns from the existing codebase:

### Access UDPSender from WebSocket handler
```python
# Source: lightsync/main.py lifespan + lightsync/api/ws.py pattern
udp = websocket.app.state.udp_sender
udp.send(payload, device.ip, device.port)
```

### Access show_store from WebSocket handler
```python
# Source: lightsync/api/shows.py — module-level ref pattern
import lightsync.main as _main
show = await _main.show_store.load(show_id)
```

### Broadcast message to all clients
```python
# Source: lightsync/api/ws.py ConnectionManager.broadcast()
await manager.broadcast({
    "type": "preview_update",
    "device_id": str(track.device_id),
    "animation": cue.animation,
    "color": cue.params.get("color", [0, 255, 180]),
})
```

### Encode animation command
```python
# Source: lightsync/protocol/animation_cmd.py
from lightsync.protocol.animation_cmd import encode_animation_cmd
payload = encode_animation_cmd(cue.animation, cue.params)
# cue.params keys: color, bg_color, speed, reverse, density/size/cooling
```

### Show load/save pattern
```python
# Source: lightsync/store/show_store.py
show: ShowModel | None = await show_store.load(show_id)  # returns None if not found
await show_store.save(show)  # writes {show_id}.json
```

### CSS variables in use
```css
/* Source: lightsync/frontend/style.css */
--bg-primary:    #0a0a0a;
--bg-panel:      #0f0f0f;
--bg-panel-dark: #080808;
--border-dim:    #1a4a4a;
--accent:        #00ffff;   /* cyan — primary highlight color */
--text-primary:  #cccccc;
--text-dim:      #555555;
--font-mono:     'JetBrains Mono', ...;
```

### CommandHistory undo/redo (existing)
```javascript
// Source: lightsync/frontend/timeline/history.js (via app.js initTimeline)
timeline.history.undo()
timeline.history.redo()
// history is a CommandHistory(50) — 50 step limit from Phase 4
```

### Sending seek + load messages from browser
```javascript
// Source: lightsync/frontend/app.js existing patterns
client.send({ type: 'seek', position: audio.currentTime });
client.send({ type: 'load', path: '/app/shows/filename.mp3' });
// Phase 5 extends load with: show_id: 'uuid-string'
```

---

## State of the Art

| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| Server-side MPV audio engine | Browser HTML5 `<audio>` element | Phase 2 redesign | Server never has authoritative play state — browser drives all timing |
| `observe_property` for position | 10Hz tick from browser | Phase 2 | Tick IS the scheduler clock; no server-side timer needed |
| `app.state.show_store` | Module-level `lightsync.main.show_store` | Phase 1 | Must import via `lightsync.main` not `websocket.app.state` |

---

## Open Questions

1. **Show selector UI placement**
   - What we know: Transport bar is already full (play, seek, time, upload, file select, load). The sidebar has two panels (DEVICES, ANIMATIONS).
   - What's unclear: Whether to add show management to the sidebar or as a new toolbar section in main-area.
   - Recommendation: Add a "SHOWS" panel to the sidebar (below ANIMATIONS), or extend the transport bar's select/load pattern — the existing `<select id="audio-select"> + <button id="btn-load">` pattern can be replicated for shows with minimal new layout.

2. **`show.devices` vs. live device registry for UDP dispatch**
   - What we know: `ShowModel.devices` is a snapshot of `DeviceConfig[]` taken when the show was created. The live registry (`registry.devices`) may differ (device IP could have changed).
   - What's unclear: Which source to use for `(ip, port)` when dispatching UDP.
   - Recommendation: Use `show.devices` for the snapshot (shows are self-contained per SHW-02). Planner can choose live registry as an alternative — both are valid.

3. **`preview_update` on cue end (block expires)**
   - What we know: The scheduler fires cues at `timestamp`. It does not currently track cue end (`timestamp + duration`).
   - What's unclear: Whether to dim the preview strip when a block ends (D-05 says "turns dark when no block is active").
   - Recommendation: In the tick handler, also check for cues whose `timestamp + duration < position` and broadcast `{"type": "preview_clear", "device_id": "..."}`. Or: the browser can derive this locally since it has `timeline.tracks` with full block data including duration.

---

## Environment Availability

Step 2.6: SKIPPED — Phase 5 is purely code changes within the existing Docker container. All dependencies (Python 3.11, FastAPI, UDPSender, browser canvas) are confirmed present from Phases 1-4.

---

## Validation Architecture

`nyquist_validation` is explicitly `false` in `.planning/config.json` — this section is skipped per instructions.

---

## Sources

### Primary (HIGH confidence)
- `lightsync/api/ws.py` — Full WebSocket handler code verified; per-connection state pattern, ConnectionManager.broadcast(), existing message types
- `lightsync/api/shows.py` — GET/POST /api/shows endpoints confirmed; show_store access via `lightsync.main` module ref
- `lightsync/store/show_store.py` — `load(show_id)`, `save(show)`, `list_ids()` confirmed
- `lightsync/models/show.py` — `ShowModel`, `TrackModel`, `CueModel` fields verified (id, timestamp, duration, animation, params)
- `lightsync/models/device.py` — `DeviceConfig` fields verified (id, name, strip_type, led_count, ip, port)
- `lightsync/protocol/udp_sender.py` — `UDPSender.send(payload, ip, port)` confirmed fire-and-forget
- `lightsync/protocol/animation_cmd.py` — `encode_animation_cmd(animation, params)`, `ANIMATION_IDS` confirmed
- `lightsync/main.py` — `app.state.udp_sender` confirmed; `show_store` is module-level, not `app.state`
- `lightsync/frontend/app.js` — 10Hz tick loop, seek/play/pause event wiring, LightSyncClient.send() confirmed
- `lightsync/frontend/index.html` — Current DOM structure confirmed; live preview insertion point identified
- `lightsync/frontend/style.css` — CSS variables confirmed; panel/border/text patterns verified
- `lightsync/frontend/timeline/timeline.js` — `this.tracks`, `this.showId`, `history` confirmed
- `lightsync/frontend/timeline/commands.js` — `setCurrentShowId()`, `currentShowId` module var confirmed
- `.planning/phases/05-live-show-execution/05-CONTEXT.md` — All locked decisions D-01 through D-07 incorporated

### Secondary (MEDIUM confidence)
- None — all findings from direct codebase inspection

### Tertiary (LOW confidence)
- None

---

## Metadata

**Confidence breakdown:**
- Standard stack: HIGH — no new libraries; all existing code verified
- Architecture: HIGH — scheduler pattern derived directly from existing `ws.py` structure
- Pitfalls: HIGH — derived from reading actual code paths (tick leakage, seek, `show_store` location)
- Preview panel: HIGH — DOM approach confirmed against existing CSS variable system

**Research date:** 2026-04-07
**Valid until:** Until code changes in ws.py, app.js, or models/show.py — this is a stable codebase at Phase 5 entry