From 4406fd2045dc65f37cc8bfd09f7955905bdeec7a Mon Sep 17 00:00:00 2001 From: david raistrick <1108844+keen99@users.noreply.github.com> Date: Wed, 1 Jul 2026 19:16:12 -0400 Subject: [PATCH] docs: ENCOUNTER_BUILDER + TESTING guides for LLM session handoff MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ENCOUNTER_BUILDER.md: DM interface — entity model (campaign/encounter/ participant), build flow (campaign→chars→encounter→participants), combat controls (start/next/pause/HP/deathsaves/conditions), player display, 1-list turn order model, storage paths quick-ref. TESTING.md: test+automation ops — commands, suites (90+24+66+4), layers (L1 mock vs L2 live backend), types, TDD discipline, replay tool, analyze-turns.js, audit tools, docker stack (single caddy+node container), dev servers, storage modes, known RED backlog. Both aimed at another LLM session picking up repo. DEVELOPMENT.md cross-refs updated. --- docs/DEVELOPMENT.md | 2 + docs/ENCOUNTER_BUILDER.md | 208 +++++++++++++++++++++++++++++++++ docs/TESTING.md | 234 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 444 insertions(+) create mode 100644 docs/ENCOUNTER_BUILDER.md create mode 100644 docs/TESTING.md diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 3042fde..70d18c4 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -35,6 +35,8 @@ TTRPG Initiative Tracker — fork with self-hosted backend. Monorepo via npm wor REWORK_PLAN.md DEVELOPMENT.md # this file GLOSSARY.md # domain terms (turn vs round, etc) + ENCOUNTER_BUILDER.md # DM interface guide + TESTING.md # test + automation ops ``` ## Setup diff --git a/docs/ENCOUNTER_BUILDER.md b/docs/ENCOUNTER_BUILDER.md new file mode 100644 index 0000000..6eb5014 --- /dev/null +++ b/docs/ENCOUNTER_BUILDER.md @@ -0,0 +1,208 @@ +# Encounter Builder — DM Interface Guide + +How a DM (or LLM automating the DM role) builds and runs encounters via the UI and storage layer. Covers entity model, build flow, combat controls, and the storage paths backing each action. + +## Entity model + +Three nested entities. All stored as opaque JSON docs in the KV store (generic doc store — see `docs/DEVELOPMENT.md`). + +``` +Campaign + └─ Encounter(s) + └─ Participant(s) +``` + +Plus two global docs: +- `activeDisplay/status` — controls player view (which campaign+encounter, hide-HP flag) +- `logs/{id}` — append-only action log entries + +### Campaign + +Path: `artifacts/{APP_ID}/public/data/campaigns/{campaignId}` + +| Field | Type | Notes | +|---|---|---| +| `name` | string | | +| `playerDisplayBackgroundUrl` | string | optional, image URL for player display bg | +| `ownerId` | string | user id | +| `createdAt` | ISO string | | +| `players` | array | campaign-level character roster (templates, NOT combatants) | + +Campaign characters = reusable templates. Default HP + init mod. Added to any encounter via ParticipantManager. Not combatants themselves. + +### Encounter + +Path: `artifacts/{APP_ID}/public/data/campaigns/{campaignId}/encounters/{encounterId}` + +| Field | Type | Notes | +|---|---|---| +| `name` | string | | +| `createdAt` | ISO string | | +| `participants` | array | the combatants (see below) | +| `round` | int | 0 = not started | +| `currentTurnParticipantId` | string\|null | who acts now | +| `isStarted` | bool | combat active | +| `isPaused` | bool | frozen turn order (add/remove/edit allowed) | +| `turnOrderIds` | array | participant ids in turn order = participants[] order (1-list model) | + +### Participant + +Object in `encounter.participants[]`: + +| Field | Type | Notes | +|---|---|---| +| `id` | string | `generateId()` | +| `name` | string | | +| `type` | `'character'` \| `'monster'` | character = PC (death saves), monster = hostile/NPC | +| `originalCharacterId` | string\|null | links back to campaign character if type=character | +| `initiative` | int | rolled once at add (`rollD20() + mod`). Stored value, not re-derived. | +| `maxHp` | int | | +| `currentHp` | int | 0 = dead/dying | +| `isNpc` | bool | monster flagged NPC (display color, no death saves) | +| `conditions` | array | condition ids from `CONDITIONS` list | +| `isActive` | bool | in turn rotation? false = skipped by nextTurn | +| `deathSaves` | int | PC only, 0-3 fails | +| `isDying` | bool | death animation flag (player display) | + +## Build flow (UI) + +Admin view at `/`. Steps: + +### 1. Create campaign +- Click **Create Campaign** button +- Enter name + optional background URL +- Submits → `setDoc(campaigns/{id}, { name, playerDisplayBackgroundUrl, ownerId, createdAt, players:[] })` + +### 2. Select campaign +- Click campaign card → `setSelectedCampaignId(campaign.id)` +- Now managing: CharacterManager + EncounterManager visible + +### 3. Add campaign characters (optional templates) +CharacterManager section. Per character: +- **Name** +- **Default HP** (`DEFAULT_MAX_HP` = 10) +- **Init Mod** (`DEFAULT_INIT_MOD` = 0) + +→ `updateDoc(campaign, { players:[...existing, newChar] })` + +These are reusable across encounters. Add to encounter later (auto-rolls initiative). + +### 4. Create encounter +- Click **Create Encounter** +- Enter name +→ `setDoc(campaigns/{cid}/encounters/{eid}, { name, createdAt, participants:[], round:0, currentTurnParticipantId:null, isStarted:false, isPaused:false })` + +### 5. Add participants +ParticipantManager section. Two paths: + +**Monster/NPC:** +- **Monster Name** (`placeholder: "e.g., Dire Wolf"`) +- **Init Mod** (`MONSTER_DEFAULT_INIT_MOD` = 2) +- **Max HP** (`DEFAULT_MAX_HP` = 10) +- **Is NPC?** checkbox (flag, changes display color) +- Click **Add to Encounter** +- Initiative auto-rolled: `rollD20() + mod` + +**Character (from campaign roster):** +- Select character from dropdown +- Click **Add to Encounter** +- OR **Add All (Roll Init)** — bulk-adds all campaign chars, each rolls own initiative + +**Duplicate guard:** same `originalCharacterId` blocked (alerts "already in this encounter"). Monsters no dedup. + +Participant object added: +```js +{ id, name, type, originalCharacterId, initiative, maxHp, currentHp:maxHp, + isNpc, conditions:[], isActive:true, deathSaves:0, isDying:false } +``` + +### 6. Reorder before start (tie-break) +Pre-combat only (`!isStarted || isPaused`). Drag handles shown for **tied initiative** values only. Drop reorders `participants[]` + `turnOrderIds`. + +Post-start drag: see BUG-13/14 in `TODO.md` (cross-init + pointer semantics untested). + +## Combat flow (UI) + +InitiativeControls panel (sticky, right side). + +### Start +- **Start Combat** button (disabled if no active participants) +- Sorts ALL participants by initiative (1-list: `participants[]` = display + turn order) +- `round=1`, `currentTurnParticipantId` = first active, `isStarted=true`, `isPaused=false` +- Sets `activeDisplay` → this campaign+encounter (player display syncs) +- Initiative fixed at start. NOT re-derived from mod after. + +### Next Turn +- **Next Turn** button (disabled if paused) +- Advances to next active participant in `turnOrderIds` +- Wraps at end → `round += 1`, re-sorts active by initiative at round start +- Dead (`isActive:false`) skipped, stay in rotation + +### Pause / Resume +- **Pause Combat** → `isPaused=true`, Next Turn disabled +- While paused: add/remove participants, adjust HP, edit initiative, reorder ties +- **Resume Combat** → `isPaused=false`, no re-sort (1-list: turnOrderIds already current) + +### HP adjustments (combat only) +Per-participant input + buttons: +- Number input +- **Damage** (HeartCrack icon) — `currentHp = max(0, hp - amt)` +- **Heal** (Heart icon) — `currentHp = min(maxHp, hp + amt)` +- Death: hp→0 sets `isActive:false`, PC gets `deathSaves` tracking + +### Death saves (PC only, at 0 HP) +3 buttons. Click marks fail. 3 fails = dead. Reset on revive/heal. + +### Conditions +- Click participant → expand conditions picker (all 22 from `CONDITIONS`) +- Active conditions show as badges, click to remove + +### End combat +- **End Combat** button → resets `isStarted:false`, `round:0`, `currentTurn:null`, `turnOrderIds:[]` +- Clears `activeDisplay` (player view goes blank) + +## Player display + +Separate view at `/display` or `?playerView=true`. Read-only second screen. + +What it shows: +- Current encounter name +- Round + current turn participant +- All participants in `participants[]` order (drag order, NOT init-sorted — BUG-15 fix) +- HP bars, conditions, death saves +- Inactive monsters hidden (pre-staged reserves) + +Driven by `activeDisplay/status` doc. Controlled by **Open Player Window** button (sets active campaign+encounter) or Start Combat (auto-sets). + +## 1-list turn order model + +Key architecture. `turnOrderIds === participants.map(p => p.id)` always. Single source of truth. + +- **Display** = `participants[]` order (AdminView + DisplayView, no re-sort) +- **Turn rotation** = `turnOrderIds` (mirrors participants[]) +- **Drag** = source of truth, overrides initiative +- **Add mid-combat** = append to participants[] + sync (BUG-14: init-insert broken post-drag) +- **Toggle active** = flip `isActive` only, stay in slot +- **Remove** = drop from participants[] + sync, advance current if needed + +No re-sort after `startEncounter` except round-wrap (re-sorts active by init at top of round). + +## Storage paths quick reference + +``` +campaigns/{cid} campaign doc +campaigns/{cid}/encounters/{eid} encounter doc (participants[]) +campaigns/{cid}/encounters/{eid}/participants ❌ NOT a path — participants inline +activeDisplay/status player display control +logs/{logId} action log entry +``` + +## DM tips + +- Initiative rolled ONCE at add time. Stored. Edit via EditParticipantModal to override. +- Pause before big roster changes (adds/removes). Resume re-syncs cleanly. +- Campaign chars = templates. Edit campaign char doesn't touch encounter participants (already added). +- Dead monsters stay in rotation, skipped. Remove via trash icon to clean list. +- Player display auto-follows Start Combat. Manual control via Open Player Window. + +See `docs/GLOSSARY.md` for domain terms, `TODO.md` for known bugs. diff --git a/docs/TESTING.md b/docs/TESTING.md new file mode 100644 index 0000000..6b099a9 --- /dev/null +++ b/docs/TESTING.md @@ -0,0 +1,234 @@ +# Testing & Automation — Operating Guide + +How to run tests, demos, audits, docker stack, and understand the test layers. For any LLM session picking up this repo. + +## Test commands + +```bash +npm run test:all # shared + server (fast, ~2s) — pre-push gate +npm run shared:test # pure turn logic (shared/turn.js) +npm run server:test # ws adapter vs live backend +npm test # CRA frontend (src/tests/, slow w/ scenario) +``` + +Pre-push hook (`.githooks/pre-push`) runs `npm run test:all`. Frontend not gated (slow). Skip: `git push --no-verify`. + +Setup hook once per clone: +```bash +git config core.hooksPath .githooks +``` + +## Test suites + +| Suite | Location | What | Count | +|---|---|---|---| +| Unit (turn logic) | `shared/tests/` | pure nextTurn, rotation, pause-add, dead-skip, reorder, round, invariant, dry | 90 | +| Integration (adapter vs backend) | `server/tests/` | ws adapter through live REST/WS | 24 | +| Characterization (UI) | `src/tests/` | locks current App.js behavior | 66 | +| ESM guard | `src/tests/StorageEsm.test.js` | no CJS in adapters | 4 | + +Total: ~184. 1 known RED (BUG-4 HideHpToggle, backlog). + +### Run one file / pattern + +```bash +npm test --workspace shared -- --testPathPattern=round-rotation +npm run server:test -- tests/ws-reconnect +CI=true npx react-scripts test --watchAll=false --testPathPattern="DisplayView.drag-order" +``` + +Frontend uses `react-scripts test` (CRA). Always set `CI=true` + `--watchAll=false` for single runs. + +## Test layers (important) + +Two layers, both required: + +- **Layer 1**: App vs firebase mock (`src/__mocks__/firebase/`). Proves adapter call shape. Never exercises ws adapter. +- **Layer 2**: ws adapter vs live backend (`server/tests/`). Proves translation + path identity. + +Layer 1 alone misses adapter bugs (path mismatch, no-op players, ws event handler bugs). Layer 2 catches those. + +## Test types + +| Type | Purpose | +|---|---| +| **Unit** | pure logic, fast, no I/O. Locks single function behavior. | +| **Integration** | real backend per test (port 0 = OS picks free). Adapter translation verified. | +| **Characterization** | render App via mock, assert current UI behavior (buggy or not). NOT desired-state. | +| **Contract** | same spec run against every storage impl (memory, ws, firebase). Catches adapter drift. | +| **Scenario** | end-to-end flow through rendered App. `Combat.scenario.test.js` = 100 rounds, ~240s. Pre-existing crash (BUG-11). | + +## TDD discipline + +RED first → fix → GREEN. Never change functional code to pass tests for existing state without test driving it. + +- Find bug → write failing test (RED) +- Fix code → test passes (GREEN) +- Log confirmed bug in `TODO.md` +- One bug at a time, commit with evidence + +## Replay tool (demo, NOT unit test) + +`scripts/replay-combat.js` — drives full combat via ws adapter (same contract as App) against live backend. UI updates in real-time if frontend running. + +```bash +# start backend + frontend first +node scripts/replay-combat.js [rounds] [delayMs] +# defaults: 100 rounds, 200ms/step +# faster: 20 400 = 20 rounds, 400ms each + +# against docker stack: +BACKEND_URL=http://127.0.0.1:8080 node scripts/replay-combat.js 20 400 +``` + +Coverage per round: damage, heal, all 22 conditions, toggleActive, removeParticipant, addParticipant (reinforcements), updateParticipant, pause/resume, reorderParticipants, endEncounter. Revives dead each round to sustain count. + +Output → log file, then analyze: + +```bash +node scripts/replay-combat.js 20 400 > tmp/run.log 2>&1 +node scripts/analyze-turns.js tmp/run.log +``` + +Exit 0 = clean. Reports skips, double-acts, order shifts. + +### analyze-turns.js + +Parses replay log. Detects: +- **real skips**: active participant not acted in a round +- **double-acts**: same participant twice in a round +- **order shifts**: turnOrderIds changed unexpectedly + +Handles `[pointer X→Y wrap]` events (mutation-driven advance) and `[reorder A→before B]`. Logs `order=[Name:init,...]` + `parts=[Name:init,...]` per turn. Parser blind to DisplayView render (separate concern — FE test covers that). + +Round marker: `--- round N starting ---` (top of loop, post-fix). + +## Audit tools (NOT unit tests) + +`tests/audit/` — exploratory, `Math.random`, non-deterministic. Manual run. NOT jest. + +### audit-rotation.js +Pure turn.js simulation of replay op sequence. Detects rotation violations. Found BUG-1. + +```bash +node tests/audit/audit-rotation.js +``` + +### audit-state.js +Runs pure turn.js combat. Audits 9 invariant classes per round: +1. rotation integrity (skip/dupe) +2. HP bounds (0 ≤ hp ≤ max, no NaN) +3. isActive consistency (dead = inactive) +4. turnOrder no dup ids +5. turnOrder ids all active +6. currentTurn valid + active +7. deathSave range (0-3, reset on revive) +8. removeParticipant orphans +9. undo support + +```bash +node tests/audit/audit-state.js [rounds] # default 100 +``` + +Current state: 0 violations / 100 rounds (post BUG-1/2 fix). + +## Docker stack + +Single container: caddy (front, static + proxy) + node backend (internal :4001). + +```bash +# build + run (from repo root) +docker compose -f docker/docker-compose.yml up --build -d +# → http://127.0.0.1:8080 + +# logs +docker compose -f docker/docker-compose.yml logs app --tail 20 + +# stop +docker compose -f docker/docker-compose.yml down + +# rebuild after code change +docker compose -f docker/docker-compose.yml up -d --build +``` + +Files: +- `docker/Dockerfile` — build FE + BE, runtime caddy+node +- `docker/Caddyfile` — proxy /api + /ws to node, static SPA fallback +- `docker/entrypoint.sh` — runs node bg + caddy fg +- `docker/docker-compose.yml` — one `app` service, volume for sqlite + +### Verify docker stack + +```bash +# REST roundtrip +curl -s -X PUT http://127.0.0.1:8080/api/doc -H 'Content-Type: application/json' \ + -d '{"path":"campaigns/test","data":{"name":"X"}}' >/dev/null +curl -s "http://127.0.0.1:8080/api/doc?path=campaigns/test" + +# WS subscribe + push (node one-liner, see scripts) +# Full combat: replay against docker +BACKEND_URL=http://127.0.0.1:8080 node scripts/replay-combat.js 20 400 > tmp/docker.log 2>&1 +node scripts/analyze-turns.js tmp/docker.log +``` + +### Inspect docker sqlite + +```bash +docker exec docker-app-1 sh -c 'node -e " +const db=require(\"better-sqlite3\")(\"/data/tracker.sqlite\"); +const rows=db.prepare(\"SELECT path, substr(data,1,50) as d FROM docs\").all(); +console.log(\"count=\"+rows.length); +rows.forEach(r=>console.log(r.path+\" => \"+r.d)); +"' +``` + +## Dev servers (non-docker) + +### Backend +```bash +npm run server:dev # :4001, db: ./data/tracker.sqlite +# or: +DB_PATH=./data/tracker.sqlite PORT=4001 node server/index.js +curl http://127.0.0.1:4001/health # → {"ok":true} +``` + +Never db in `/tmp` (wipe risk). Use `./data/` (gitignored) or docker volume. + +### Frontend (ws mode) +```bash +REACT_APP_STORAGE=ws \ +REACT_APP_BACKEND_URL=http://127.0.0.1:4001 \ +REACT_APP_BACKEND_WS=ws://127.0.0.1:4001/ws \ +BROWSER=none PORT=3999 \ +npm start +``` +→ http://127.0.0.1:3999/. Admin `/`, player `/display`. + +Firebase mode (default): set `REACT_APP_FIREBASE_*` in `.env.local` (copy `env.example`). + +## Storage modes + +`STORAGE_MODE = getStorageMode()` reads `REACT_APP_STORAGE`: +- `firebase` (default) → real SDK +- `ws` → backend (docker/prod) +- `memory` → in-process (test seed) + +All adapters ESM. Adapter contract: `src/storage/contract.js` — same spec vs memory/ws/firebase. + +## Known RED / backlog + +- BUG-4: HideHpToggle RED (setDoc→updateDoc, clobbers activeDisplay) +- BUG-10: deact+reactivate double-act +- BUG-11: Combat.scenario test crash +- BUG-13: reorder cross-pointer semantics +- BUG-14: addParticipant init-insert post-drag + +See `TODO.md` for full list + status. + +## Scratch + +`scratch/` — gitignored throwaway. Repro scripts, exploration, debug. Not committed. Use freely, delete anytime. + +## Status + +See `docs/REWORK_PLAN.md` for milestones, `TODO.md` for bugs, `docs/DEVELOPMENT.md` for setup, `docs/GLOSSARY.md` for terms, `docs/ENCOUNTER_BUILDER.md` for DM interface.