From 25a71e0a77985582627812f5c3c674e2a10c7148 Mon Sep 17 00:00:00 2001 From: Jage9 Date: Mon, 9 Mar 2026 00:30:21 -0400 Subject: [PATCH] Remove tracked planning notes --- item.md | 92 ----------------------------------------------- refactor.md | 101 ---------------------------------------------------- 2 files changed, 193 deletions(-) delete mode 100644 item.md delete mode 100644 refactor.md diff --git a/item.md b/item.md deleted file mode 100644 index bd26ccc..0000000 --- a/item.md +++ /dev/null @@ -1,92 +0,0 @@ -# Chat Grid Item System Plan - -## Goals -- Add world items without hard-coding every new feature. -- Start with `radio_station` as the first real item type. -- Keep design compatible with future carry/use/object mechanics. - -## Commands (V1) -- `A`: Add-item mode. - - Opens list of available item types. - - `Enter` places selected type on current square. -- `O`: Edit item properties on current square. - - If one item on square: open property edit mode for that item. - - If multiple items: open selector first, then property edit. -- `U`: Use item on current square (or held item if carrying one). - - If multiple usable items are available, open selector first. - - V1 behavior: implemented for `dice`; `radio_station` is configurable but not "used" yet. -- `Shift+U`: List connected users (moves old `U` users-list behavior here). -- `I`: Locate nearest item (name/type, distance, direction, coordinates). -- `Shift+I`: List items mode (nearest-first; arrows navigate; `Enter` focuses/moves, same pattern as user list). -- `D`: Carry/drop toggle. - - If not carrying: pick up one item from current square. - - If carrying: drop held item on current square. - - If multiple items exist on square, open short selector first. -- `Shift+D`: Delete item on current square. - - If multiple items, open selector first, then delete selected item. - -## Add Flow Options -- Option 1: Add with required properties immediately. - - Pros: item is valid at creation time. - - Cons: slower flow due to prompts. -- Option 2: Add placeholder first, then edit with `O`. (Recommended for V1) - - Pros: faster placement, cleaner keyboard flow, scales to many item types. - - Cons: requires incomplete-item handling. - -### Recommended V1 behavior -- `A` places item immediately with defaults. -- `radio_station` defaults: - - `title`: `New station` - - `params.streamUrl`: empty string (no default URL) - - `params.enabled`: `true` - - `params.volume`: `50` -- Incomplete rule: - - Item exists in world, but does not activate until required params are set. - - `O` is the standard command to complete/update params. - -## Property Editor (`O`) Behavior -- `O` opens a property list for the selected item. -- Arrow keys move between properties. -- Focused property announces: property name + current value. -- `Enter` on a property starts edit mode for that value. -- For switch properties (V1: `radio_station.enabled`), `Enter` toggles directly between `on` and `off`. -- `Enter` saves value after validation. -- `Escape` exits edit mode or closes the property menu. -- Validation failures are announced and also pushed to message buffer. - -## Data Model - -### Global fields (all item types) -- `id`: unique item id. -- `type`: item type key (ex: `radio_station`, `dice`). -- `title`: spoken/display label. -- `x`, `y`: world position. -- `createdBy`, `createdAt`, `updatedAt`. -- `version`: schema version for migration. -- `capabilities`: list of supported actions (examples: `editable`, `carryable`, `usable`, `deletable`). -- `useSound`: optional sound path played on successful `U` use (global field, not editable in V1). -- `params`: per-type payload object. - -### Per-item fields (inside `params`) -- `radio_station` (V1): - - `streamUrl` (required for playback; may be empty until configured) - - `enabled` (boolean on/off flag) - - `volume` (number `0-100`, default `50`) - - future: `filter`. -- `dice` (V1): - - `sides` (number, default `6`, range `1-100`) - - `number` (number of dice, default `2`, range `1-100`) -- `dice` (future example): - - optional future: `lastRoll`, `rollMode`, `modifier`. - -## Networking and Authority -- Server-authoritative item state. -- Client sends intent packets (`add`, `pickup`, `drop`, `delete`, later `use`). -- Server validates and returns: - - success result + broadcast item state update, or - - reject result with reason (also added to message buffer). - -## Why this structure -- Stable global schema with extensible `params`. -- New item types can be added without changing core item pipeline. -- Supports shared multiplayer consistency and future inventory/carry rules. diff --git a/refactor.md b/refactor.md deleted file mode 100644 index 31e7bf3..0000000 --- a/refactor.md +++ /dev/null @@ -1,101 +0,0 @@ -# Rewrite Plan: Modern Cross-Browser Spatial Grid - -## What This Code Is Today -The current code is a functional prototype: one large HTML file with tightly coupled UI/game/network/audio logic, plus a single Python signaling script. It proves the concept, but it is hard to test, hard to evolve safely, and brittle across browser differences. -At its core, the product is a realtime spatial chat grid with movement and command-driven interaction. - -## Rewrite Strategy (No Backward-Compatibility Constraints) -Build a new app in parallel, then cut over once parity + quality gates pass. -V1 explicitly ships without TURN relay infrastructure. -Design the new core so future features (objects, pickups, walls, collisions, and interaction rules) can be added without architectural rework. - -## Target Architecture -- `client/`: TypeScript + Vite + Canvas renderer + state store. -- `server/`: Python signaling service using `websockets` (schema-validated). -- `shared/`: Message contracts (JSON schema + generated TS types). -- `tests/`: Unit + Playwright E2E (Chromium, Firefox, WebKit). -- `docs/`: Browser compatibility matrix and ops runbook. -- Core domain model: - - world map + tile metadata (walkable/blocked/zone) - - entities (`player`, `object`, future NPC/system entities) - - actions/commands (move, rename, locate, interact, pickup, use) - - simulation rules (movement, collision, proximity effects) - -## Technology Choices -- Client: TypeScript, Vite, ESLint, Prettier, Vitest. -- Realtime: WebSocket signaling + WebRTC media. -- Server runtime: Python + `websockets`. -- Validation: Zod/JSON Schema for all inbound/outbound messages. -- Deployability: Environment-based config only (no hardcoded cert paths). -- ICE for v1: STUN-only (`stun:stun.l.google.com:19302`) with robust retry and failure handling. - -## Phases - -### Phase 1: Parity Baseline + Browser Hardening (5-8 days) -- Scaffold monorepo structure. -- Define protocol schemas: `welcome`, `signal`, `update_position`, `update_nickname`, `user_left`. -- Implement strict server validation and structured logging. -- Rebuild current behavior with parity: - - grid render + movement + presence sync - - existing commands: `c`, `l`, `shift+l`, `u`, `n`, `m`, `escape` - - nickname flow and reconnect/disconnect behavior -- Cross-browser hardening for latest Chrome/Edge/Firefox/Safari: - - keyboard handling via `event.code` - - capability checks for `setSinkId`, `StereoPannerNode`, autoplay/permissions differences - - explicit no-TURN recovery UX and bounded retry/backoff -- Keep grid/presence functional even if voice fails on restrictive networks. -- V1 server requirements (Python-focused): - - Use Python `websockets` for signaling transport. - - Enforce strict message validation (Pydantic/JSON schema) on receive and send. - - Add structured logging and websocket behavior tests. - -### Phase 2: World + Extensibility Architecture (3-5 days) -- Introduce world + entity foundation: - - tile map abstraction with collision checks - - player entity and object entity schema - - action dispatcher for current commands and future interactions -- Keep simulation pure and testable (state in, state out). - -### Phase 3: Advanced Audio + WebRTC Robustness (2-4 days) -- Implement peer connection manager and retry/timeout policy. -- Build browser capability layer: - - `setSinkId` optional - - `StereoPannerNode` optional - - autoplay/promise failure handling -- Graceful degradation: if unsupported, keep grid/presence fully functional and reduce to basic audio. -- Implement explicit no-TURN recovery UX: - - Detect ICE `failed`/`disconnected` states and auto-retry with bounded backoff. - - Surface actionable status text (network-restricted, retrying, voice unavailable). - - Keep text/status + grid presence fully functional when voice cannot connect. - -### Phase 4: Quality Gates (2-4 days) -- Unit tests for state, protocol, input, and audio math. -- Playwright multi-user E2E in Chromium/Firefox/WebKit. -- Add CI for lint, typecheck, unit tests, and cross-browser smoke tests. -- Add world-rule tests: - - wall collision and blocked-tile movement rejection - - object pickup/use action validation - - deterministic command outcomes - -### Phase 5: Cutover (1-2 days) -- Deploy rewrite behind new route or domain. -- Run soak tests and monitor connection/error metrics. -- Decommission old prototype once stable. - -## Definition of Done -- Grid + movement + presence stable in latest Chrome, Edge, Firefox, Safari. -- Audio works where supported and degrades cleanly where not. -- Zero runtime dependence on inline scripts or CDN Tailwind runtime. -- One-command local startup and passing CI. -- Known no-TURN limitation documented: some restrictive NAT/firewall networks may not establish voice. - -## Post-v1 TURN Trigger -Add TURN when either condition is met: -- Voice connection failure rate exceeds agreed threshold in production telemetry. -- Target users include enterprise/school/mobile networks where relay need is expected. - -## Recommended First PR -Create repo skeleton + protocol schema + server validator + parity client slice that renders grid, syncs positions, and supports current commands. - -## Recommended Second PR -Add browser hardening completion (capability fallbacks, reconnect UX) and Playwright parity tests across Chromium/Firefox/WebKit.