Phase 3 — Overlay, WebSocket server, Numbering & Reveal Flow

[Swiftburn]

Phase 3 — Overlay, WebSocket server, Numbering & Reveal Flow

Purpose

Provide a browser overlay (OBS browser source) and a WebSocket server to display numbered word overlays and handle reveal actions.

Tasks

• 3.1 Create overlay static front-end

  • Files: src/overlay/static/overlay.html, overlay.js, overlay.css
  • Work: Minimal HTML/JS that opens a WebSocket, receives payload {words:[{id,number,surface,kana,romaji,confidence}], highlights:[]} and renders numbered tiles. Use CSS variables for customization.
  • DoD: overlay displays words and numbers when fed JSON; documented manual verification.

• 3.2 Implement WebSocket server (per-region)

  • File: src/overlay/server.py
  • Work: Lightweight async server using websockets or aiohttp. Endpoints: /region/{region_id}. Expose broadcast(region_id, payload).
  • Tests: tests/test_overlay_ws.py uses in-process client to verify message receipt.
  • DoD: server can push JSON updates to clients; test covers message flow.

• 3.3 Number assignment & stable numbering

  • File: src/overlay/state.py (or inside server)
  • Work: Numbering algorithm: assign numbers to words for current translation; numbers stable until a reset (new translation/region change). Provide assign_numbers(words) -> words_with_numbers.
  • Tests: tests/test_numbering.py ensuring stability across repeated calls with same inputs and reset behavior when input changes.
  • DoD: stable numbers until explicit reset.

• 3.4 Reveal API (show/hide by number)

  • File: src/overlay/server.py (API handlers)
  • Work: Add server commands to reveal(region_id, number) and hide(region_id, number) and broadcast changes to overlay clients.
  • Tests: tests/test_reveal.py verifying server state changes and broadcast payloads.
  • DoD: overlay clients update highlight state on reveal/hide.

• 3.5 Overlay config options

  • Files: src/overlay/config.py, src/overlay/static/ (CSS variables)
  • Work: Add per-region overlay config (font size, colors, transparency) and websocket message schema to pass config.
  • DoD: overlay reads config variables from initial payload and applies styles.

Notes

• Keep overlay code vanilla JS and minimal dependencies for OBS compatibility.