nexus/.planning/phases/37-web-chat-voice-ui/37-01-SUMMARY.md

---
phase: 37-web-chat-voice-ui
plan: "01"
subsystem: voice-infrastructure
tags: [voice, coop-coep, vad, server-routes, shared-array-buffer]
dependency_graph:
  requires:
    - phase-36 voice-pipeline-foundation (cherry-picked)
  provides:
    - POST /api/transcribe (voice transcription endpoint)
    - POST /api/synthesize (TTS endpoint)
    - GET/PATCH /api/nexus/settings (voice mode settings)
    - COOP/COEP headers on Express server
    - VAD ONNX model assets in ui/public/
    - @ricky0123/vad-react installed in ui
  affects:
    - server/src/app.ts (COOP/COEP middleware + route mounting)
    - ui/vite.config.ts (COOP/COEP dev server headers)
    - ui/public/ (VAD assets)
tech_stack:
  added:
    - "@ricky0123/vad-react@^0.0.36"
    - "@ricky0123/vad-web@0.0.30 (transitive, ONNX assets sourced from here)"
    - "ffmpeg-static@^5.3.0 (cherry-picked from phase-36)"
  patterns:
    - Express COOP/COEP middleware before all route handlers
    - Same-origin VAD asset serving (avoids COEP cross-origin block)
    - voiceMode union type threaded through chat stream pipeline
key_files:
  created:
    - server/src/services/nexus-settings.ts
    - server/src/routes/nexus-settings.ts
    - server/src/routes/voice.ts (cherry-picked)
    - server/src/routes/chat.ts (cherry-picked, includes voiceMode wiring)
    - server/src/routes/chat-files.ts (cherry-picked)
    - server/src/services/voice-pipeline.ts (cherry-picked)
    - ui/public/vad.worklet.bundle.min.js
    - ui/public/silero_vad_legacy.onnx
    - ui/public/silero_vad_v5.onnx
  modified:
    - server/src/app.ts (COOP/COEP headers, voiceRoutes + nexusSettingsRoutes mount)
    - ui/vite.config.ts (COOP/COEP headers in dev server config)
    - ui/package.json (@ricky0123/vad-react dep, copy-vad-assets script)
    - pnpm-lock.yaml
decisions:
  - "Cherry-picked Phase 36 commits (d0d7a23a, b964c0e4, 11508547, fd372eaf, f8df2547) rather than re-implementing — all conflicts resolved manually"
  - "nexus-settings.ts service/route re-created from phase-36 content since files were not in HEAD before cherry-pick"
  - "assistantMemoryRoutes and assistantHandoffRoutes excluded from app.ts (route files absent on this branch)"
  - "COOP/COEP added as first Express middleware before json parsing — applies to all responses including API and static"
metrics:
  duration: "25 minutes"
  completed_date: "2026-04-04"
  tasks_completed: 2
  files_created: 12
  files_modified: 4
---

# Phase 37 Plan 01: Server Prerequisites + VAD Browser Infrastructure Summary

**One-liner:** Cherry-picked Phase 36 voice pipeline (transcribe/synthesize/nexus-settings/voiceMode wiring), added COOP/COEP headers to Express and Vite, installed @ricky0123/vad-react, and served VAD ONNX model files from same-origin ui/public/.

## Tasks Completed

| Task | Name | Commits | Key Files |
|------|------|---------|-----------|
| 1 | Cherry-pick Phase 36 server deliverables + COOP/COEP headers | 5bc19b31, c67a2fcb, 73fcea49, e9eae5c4, be0effa7 | server/src/app.ts, server/src/routes/voice.ts, nexus-settings.ts, chat.ts |
| 2 | Install VAD library, copy ONNX assets, configure Vite COOP/COEP | 0fb6b75d | ui/package.json, ui/vite.config.ts, ui/public/*.onnx, vad.worklet.bundle.min.js |

## Verification Results

All 15 acceptance criteria passed:
- voiceRoutes mounted in server/src/app.ts
- nexusSettingsRoutes mounted in server/src/app.ts
- COOP/COEP headers in Express (same-origin / require-corp)
- voiceMode and voice_full wiring in server/src/routes/chat.ts
- server/src/routes/voice.ts with POST /transcribe and POST /synthesize
- server/src/routes/nexus-settings.ts with GET/PATCH /nexus/settings
- VOICE_MODES exported from server/src/services/nexus-settings.ts
- ui/public/vad.worklet.bundle.min.js (2.5KB)
- ui/public/silero_vad_legacy.onnx (1.8MB)
- ui/public/silero_vad_v5.onnx (2.3MB)
- @ricky0123/vad-react in ui/package.json dependencies
- COOP/COEP headers in ui/vite.config.ts dev server config

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 3 - Blocking Issue] pnpm-lock.yaml broken after cherry-pick conflict resolution**
- **Found during:** Task 2 (pnpm install step)
- **Issue:** Cherry-pick conflict resolution produced malformed pnpm-lock.yaml with missing systeminformation@5.31.5 entry
- **Fix:** Ran `pnpm install --no-frozen-lockfile` to regenerate the lockfile
- **Files modified:** pnpm-lock.yaml
- **Commit:** 0fb6b75d

**2. [Rule 2 - Missing Critical Functionality] nexus-settings.ts service and route not present after cherry-picks**
- **Found during:** Task 1 (cherry-pick conflict resolution)
- **Issue:** The HEAD branch did not have nexus-settings.ts (service or route) before cherry-picking; conflict resolution left them as untracked files
- **Fix:** Created both files from Phase 36 branch content; staged and committed in e9eae5c4
- **Files modified:** server/src/services/nexus-settings.ts, server/src/routes/nexus-settings.ts

**3. [Deviation] assistantMemoryRoutes and assistantHandoffRoutes excluded**
- **Found during:** Task 1 (app.ts conflict resolution)
- **Issue:** The cherry-pick added imports for assistant-memory.ts and assistant-handoff.ts route files which do not exist on this branch
- **Fix:** Excluded those imports and route mounts from conflict resolution; included only chatFileRoutes, nexusSettingsRoutes, voiceRoutes
- **Impact:** No functional loss — those routes are not needed for Phase 37

## Known Stubs

None. All endpoints wire to real services (voicePipelineService, nexusSettingsService).

## Self-Check: PASSED

Files verified:
- server/src/routes/voice.ts: EXISTS
- server/src/routes/nexus-settings.ts: EXISTS
- server/src/services/nexus-settings.ts: EXISTS
- server/src/services/voice-pipeline.ts: EXISTS
- ui/public/vad.worklet.bundle.min.js: EXISTS (2.5KB)
- ui/public/silero_vad_legacy.onnx: EXISTS (1.8MB)
- ui/public/silero_vad_v5.onnx: EXISTS (2.3MB)

Commits verified: 5bc19b31, c67a2fcb, 73fcea49, e9eae5c4, be0effa7, 0fb6b75d all present in git log.