Remove tracked planning notes
This commit is contained in:
Jage9
92
item.md
92
item.md
@@ -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.
|
|
||||||
101
refactor.md
101
refactor.md
@@ -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.
|
|
||||||
Reference in New Issue
Block a user