feat: implement websocket realtime data streaming

tickets/2026-01-07-websocket-realtime-data.md

@@ -0,0 +1,42 @@
+# 2026-01-07-websocket-realtime-data
+
+**Status:** Done
+**Created:** 2026-01-07
+**Tags:** feature, websocket, realtime, research
+
+## 1. Context & User Story
+* **As a:** Developer
+* **I want to:** implement a WebSocket connection between the frontend and the Aurora server
+* **So that:** I can stream real-time data (profiling, logs, events) to the dashboard without manual page refreshes.
+
+## 2. Technical Requirements
+### Data Model Changes
+- [ ] N/A
+
+### API / Interface
+- [x] **Endpoint:** `/ws` (Upgrade Upgrade: websocket).
+- [x] **Protocol:** Define a simple JSON message format (e.g., `{ type: "UPDATE", data: { ... } }`).
+
+## 3. Constraints & Validations (CRITICAL)
+- **Bun Support:** Use Bun's native `Bun.serve({ websocket: { ... } })` capabilities if possible.
+- **Security:** Ensure that the WebSocket endpoint is not publicly abusable (consider simple token or origin check if necessary, though internal usage is primary context for now).
+- **Performance:** Do not flood the client. Throttle updates if necessary.
+
+## 4. Acceptance Criteria
+1. [x] Server accepts WebSocket connections on `/ws`.
+2. [x] Client (`script.js`) successfully connects to the WebSocket.
+3. [x] Server sends a "Hello" or "Ping" packet.
+4. [x] Client receives and logs the packet.
+5. [x] (Stretch) Stream basic uptime or heartbeat every 5 seconds.
+
+## 5. Implementation Plan
+- [x] Modify `src/web/server.ts` to handle `websocket` upgrade in `Bun.serve`.
+- [x] Create a message handler object/function to manage connected clients.
+- [x] Update `src/web/public/script.js` to initialize `WebSocket`.
+- [x] Test connection stability.
+
+## Implementation Notes
+- Enabled `websocket` in `Bun.serve` within `src/web/server.ts`.
+- Implemented a heartbeat mechanism broadcasting `HEARTBEAT` events every 5s.
+- Updated `script.js` to auto-connect, handle reconnects, and update a visual "online" indicator.
+- Added `src/web/websocket.test.ts` to verify protocol upgrades and messaging.