new Websockets from client only

LESSONSLEARNED.md

@@ -0,0 +1,38 @@
+# Lessons Learned
+
+_This document captures the key takeaways and implementation details from today's troubleshooting session._
+
+## 1. API Routing & Proxy Configuration
+- **API_BASE constant**: The frontend (`static/script.js`) uses a base path `API_BASE` (default `/api`) to prefix all HTTP and WebSocket calls. Always update this to match your proxy mount point.
+- **Nginx WebSocket forwarding**: To proxy WebSockets, you must forward the `Upgrade` and `Connection` headers:
+  ```nginx
+  proxy_set_header Upgrade    $http_upgrade;
+  proxy_set_header Connection "upgrade";
+  ```
+  Without these, the WS handshake downgrades to a normal HTTP GET, resulting in 404s.
+
+## 2. Debugging WebSocket Traffic
+- Logged all incoming WS frames in `main.py`:
+  - `[WS-PLUGIN RX] <client>: <raw>` for messages on `/ws/position`
+  - `[WS-LIVE RX]   <client>: <parsed-json>` for messages on `/ws/live`
+- These prints surface registration, telemetry, chat, and command packets, aiding root-cause analysis.
+
+## 3. Data Serialization Fix
+- Python `datetime` objects are not JSON-serializable by default. We wrapped outbound payloads via FastAPI’s `jsonable_encoder` in `_broadcast_to_browser_clients` so that:
+  ```python
+  data = jsonable_encoder(snapshot)
+  await ws.send_json(data)
+  ```
+  This ensures ISO8601 strings for timestamps and eliminates `TypeError: Object of type datetime is not JSON serializable`.
+
+## 4. Frontend Adjustments
+- **Chat input positioning**: Moved the `.chat-form` to `position: absolute; bottom: 0;` so the input always sticks to the bottom of its window.
+- **Text color**: Forced the input text and placeholder to white (`.chat-input, .chat-input::placeholder { color: #fff; }`) and forcibly set all incoming messages to white via `.chat-messages div { color: #fff !important; }`.
+- **Padding for messages**: Added `padding-bottom` to `.chat-messages` to avoid new messages being hidden behind the fixed input bar.
+
+## 5. General Best Practices
+- Clear browser cache after updating static assets to avoid stale JS/CSS.
+- Keep patches targeted: fix the source of issues (e.g., JSON encoding or missing headers) rather than applying superficial workarounds.
+- Use consistent CSS variables for theming (e.g., `--text`, `--bg-main`).
+
+By consolidating these lessons, we can onboard faster next time and avoid repeating these pitfalls.