new Websockets from client only

FIXES.md

@@ -0,0 +1,48 @@
+# Planned Fixes and Enhancements
+
+_This document captures the next set of improvements and fixes for Dereth Tracker._
+
+## 1. Chat Window Styling and Format
+- **Terminal-style chat interface**
+  - Redesign the chat window to mimic Asheron’s Call in-game chat: monospaced font, dark semi-transparent background, and text entry at the bottom.
+  - Implement timestamped message prefixes (e.g., `[12:34] character: message`).
+  - Support command- and system-level styling (e.g., whispers, party chat) with distinct color cues.
+
+## 2. Incoming Message Parsing
+- **Strip protocol overhead**
+  - Remove JSON envelope artifacts (e.g., remove quotes, braces) so only raw message text appears.
+  - Validate and sanitize incoming payloads (e.g., escape HTML, truncate length).
+  - Optionally support rich-text / emotes by parsing simple markup (e.g., `*bold*`, `/me action`).
+
+## 3. Message Color Scheme
+- **Per-character consistent colors**
+  - Map each character name to a unique, but legible, pastel or muted color.
+  - Ensure sufficient contrast with the chat background (WCAG AA compliance).
+  - Provide user override settings for theme (light/dark) and custom palettes.
+
+## 4. Command Prompt Integration
+- **Client-side command entry**
+  - Allow slash-commands in chat input (e.g., `/kick PlayerName`, `/whisper PlayerName Hello`).
+  - Validate commands before sending to `/ws/live` and route to the correct plugin WebSocket.
+  - Show feedback on command success/failure in the chat window.
+
+## 5. Security Hardening
+- **Authentication & Authorization**
+  - Enforce TLS (HTTPS/WSS) for all HTTP and WebSocket connections.
+  - Protect `/ws/position` with rotating shared secrets or token-based auth (e.g., JWT).
+  - Rate-limit incoming telemetry and chat messages to prevent flooding.
+  - Sanitize all inputs to guard against injection (SQL, XSS) and implement strict CSP headers.
+
+## 6. Performance and Scalability
+- **Throttling and Load Handling**
+  - Batch updates during high-frequency telemetry bursts to reduce WebSocket churn.
+  - Cache recent `/live` and `/trails` responses in-memory to relieve SQLite under load.
+  - Plan for horizontal scaling: stateless FastAPI behind a load balancer with shared database or in-memory pub/sub.
+
+## 7. Testing and Quality Assurance
+- **Automated Tests**
+  - Unit tests for `db.save_snapshot`, HTTP endpoints, and WebSocket handlers.
+  - E2E tests for the frontend UI (using Puppeteer or Playwright) to verify chat and map functionality.
+  - Security regression tests for input sanitization and auth enforcement.
+
+_Refer to this list when planning next development sprints. Each item should be broken down into individual tickets or pull requests._

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.