fix(docker): drop image: field so compose never pulls service image

Image: ttrpg-app:local named a registry image. Without --build flag,
compose tried pull first -> 'pull access denied' (private, unpublished).
Then fell back to build. Confusing error.

Removed image: field. Compose now auto-names (docker-app), always builds
local, never attempts registry pull. Base images (node/caddy) pull once
on first build, then cache. No pull_policy needed.

docker compose up (from docker/ dir) now works clean.

Caddyfile

@@ -1,36 +0,0 @@
-# Caddyfile — serve static frontend, proxy /api + /ws to backend
-# handle blocks are mutually exclusive + ordered: API/WS first, static last.
-# (try_files at site level would rewrite /api/* → /index.html before proxy.)
-
-{
-	# admin off for docker
-	admin off
-}
-
-:80 {
-	encode gzip
-
-	# REST API → backend service (path preserved: /api/doc etc.)
-	handle /api/* {
-		reverse_proxy backend:4001 {
-			header_up Host {host}
-		}
-	}
-
-	# WebSocket upgrade → backend
-	handle /ws {
-		reverse_proxy backend:4001
-	}
-
-	# Everything else: static SPA with client-side routing fallback
-	handle {
-		root * /srv
-		try_files {path} /index.html
-		file_server
-	}
-
-	# HTTP basic auth (in-house only). Uncomment + set CADDY_BASIC_AUTH env.
-	# basic_auth {
-	# 	{$CADDY_BASIC_AUTH}
-	# }
-}

Dockerfile.ws

@@ -1,29 +0,0 @@
-# Dockerfile.ws — frontend build (STORAGE=ws) served by Caddy
-# Same-origin: Caddy proxies /api + /ws to backend. No backend URL baked at build.
-
-FROM node:18-alpine AS build
-WORKDIR /app
-
-# workspaces root
-COPY package*.json ./
-COPY shared/package.json ./shared/
-COPY server/package.json ./server/
-RUN npm install --include-workspace-root
-
-COPY shared/ ./shared/
-COPY src/ ./src/
-COPY public/ ./public/
-
-# Build with ws storage (no backend URL — same-origin via Caddy proxy)
-ARG REACT_APP_TRACKER_APP_ID=ttrpg-initiative-tracker-default
-ENV REACT_APP_STORAGE=ws
-ENV REACT_APP_TRACKER_APP_ID=$REACT_APP_TRACKER_APP_ID
-RUN NODE_OPTIONS=--openssl-legacy-provider npm run build
-
-# Stage 2: Caddy serves static + proxies API/WS
-FROM caddy:2-alpine
-
-COPY --from=build /app/build /srv
-COPY Caddyfile /etc/caddy/Caddyfile
-
-EXPOSE 80

TODO.md

@@ -152,10 +152,39 @@ REWORK_PLAN.md.
 - Baseline (my changes removed) also exit=1. Pre-existing, not regression.
 - Crashes whole FE test run (process dies).
 
+### BUG-13: reorderParticipants crossing current pointer = ambiguous acted-semantics
+- Discovered 7/1 replay. `reorderParticipants` (shared/turn.js:522) = pure
+  drag, no pointer logic. Swapping two actors across current pointer mid-round
+  = ambiguous who-acted-this-round. Earlier replay arbitrary swaps showed
+  skip/double (R9 Summon3 2x, R11 Goblin1 2x) before fix restricted swaps to
+  upcoming-only.
+- Replay now avoids crossing (adjacent upcoming pair only, commit af165f4).
+  Real app untested: if DM drags actor past current pointer mid-round, skip/
+  double behavior undefined.
+- Decide: block cross-pointer reorder, or define acted-semantics. RED needed.
+
+### BUG-14: addParticipant init-insertion breaks after drag-reorder
+- Discovered 7/1 replay. `computeTurnOrderAfterAddition` scans for first id
+  with init < addedInit, assumes list init-sorted. After drag, list NOT sorted
+  → scan hits wrong slot.
+- Trace turn 30→31: list `[Goblin1:20,Goblin2:22,...]` (drag moved Goblin1
+  before Goblin2). Add Reinforce3 init 21 → scan hits Goblin1:20 (idx 0, <21)
+  first → insert at 0. Should slot after Goblin2:22. WRONG.
+- Root conflict: 1-list model = drag source of truth (no re-sort); addParticipant
+  = init-based insertion (needs sorted list). After ANY drag, add-insertion
+  meaningless.
+- Proposed fix: append to end always (option A). DM drags to position. Matches
+  drag = source of truth. Makes `computeTurnOrderAfterAddition` trivial.
+- Related: FEAT-3 (initiative first-class field).
+
 ## Pipeline (bugs only --- milestones live in REWORK_PLAN.md)
 - [ ] BUG-4: fix setDoc→updateDoc for all 5 activeDisplay sites
 - [x] BUG-5: fixed (1-list model, 500 rounds clean)
 - [x] BUG-6: fixed structurally (1-list model)
-- [ ] BUG-8: ws adapter reconnect
+- [x] BUG-12: fixed — campaign selection follows activeDisplay
+- [x] BUG-15: fixed — DisplayView no longer re-sorts (drag order preserved)
+- [x] BUG-8: ws adapter reconnect (implemented + GREEN)
 - [ ] BUG-10: deact+reactivate double-act
 - [ ] BUG-11: FE Combat.scenario crash
+- [ ] BUG-13: reorder cross-pointer semantics (RED + decide block/allow)
+- [ ] BUG-14: addParticipant init-insert breaks post-drag (append? + RED)

docker-compose.yml

@@ -1,59 +0,0 @@
-# docker-compose.yml — two profiles:
-#   firebase: existing Dockerfile (nginx + firebase build), upstream path
-#   backend:  full stack (caddy frontend + node backend + sqlite volume)
-#
-# Usage:
-#   docker compose --profile backend up --build        # full self-hosted stack
-#   docker compose --profile firebase up --build       # firebase-only (upstream)
-#
-# Run local in OrbStack; remote docker context later (just change context).
-
-services:
-  # ---- full self-hosted stack (STORAGE=ws) ----
-  backend:
-    profiles: ["backend"]
-    build:
-      context: .
-      dockerfile: server/Dockerfile
-    image: ttrpg-backend:local
-    volumes:
-      - backend-data:/data
-    environment:
-      - DB_PATH=/data/tracker.sqlite
-      - PORT=4001
-      # - CORS_ORIGIN=*   # Caddy same-origin, cors not strictly needed
-    expose:
-      - "4001"
-    restart: unless-stopped
-
-  frontend:
-    profiles: ["backend"]
-    build:
-      context: .
-      dockerfile: Dockerfile.ws
-      args:
-        - REACT_APP_TRACKER_APP_ID=${TRACKER_APP_ID:-ttrpg-initiative-tracker-default}
-    image: ttrpg-frontend:local
-    ports:
-      - "${FRONTEND_PORT:-8080}:80"
-    depends_on:
-      - backend
-    # Optional basic auth: set in .env as CADDY_BASIC_AUTH="user <hashed-pass>"
-    # Generate hash: caddy hash-password
-    environment:
-      - CADDY_BASIC_AUTH=${CADDY_BASIC_AUTH:-}
-    restart: unless-stopped
-
-  # ---- firebase-only path (upstream, existing Dockerfile) ----
-  firebase:
-    profiles: ["firebase"]
-    build:
-      context: .
-      dockerfile: Dockerfile
-    image: ttrpg-firebase:local
-    ports:
-      - "${FRONTEND_PORT:-8080}:80"
-    restart: unless-stopped
-
-volumes:
-  backend-data:

docker/Caddyfile

@@ -0,0 +1,18 @@
+# Caddyfile — single-container (caddy + node)
+# Caddy serves built frontend, proxies /api + /ws to node backend on :4001.
+# Node never exposed directly; only caddy on :80.
+
+:80 {
+	handle /api/* {
+		reverse_proxy 127.0.0.1:4001
+	}
+	handle /ws {
+		reverse_proxy 127.0.0.1:4001
+	}
+	# catch-all: static frontend (SPA fallback)
+	handle {
+		root * /srv
+		try_files {path} /index.html
+		file_server
+	}
+}

docker/Dockerfile

@@ -0,0 +1,54 @@
+# docker/Dockerfile — single container: caddy (front) + node (back).
+# Build context = repo root.
+# ---- build stage: frontend + install backend deps ----
+FROM node:18-alpine AS build
+WORKDIR /app
+
+COPY package*.json ./
+COPY shared/package.json ./shared/
+COPY server/package.json ./server/
+RUN npm install --include-workspace-root
+
+COPY shared/ ./shared/
+COPY server/ ./server/
+COPY src/ ./src/
+COPY public/ ./public/
+COPY tailwind.config.js postcss.config.js ./
+
+# better-sqlite3 native build (alpine musl)
+RUN cd server && npm rebuild better-sqlite3
+
+# build frontend (ws storage, same-origin via caddy)
+ARG REACT_APP_TRACKER_APP_ID=ttrpg-initiative-tracker-default
+ENV REACT_APP_STORAGE=ws
+ENV REACT_APP_TRACKER_APP_ID=$REACT_APP_TRACKER_APP_ID
+RUN NODE_OPTIONS=--openssl-legacy-provider npm run build
+
+# prune backend dev deps for runtime
+RUN npm prune --omit=dev
+
+# ---- runtime stage: caddy + node ----
+FROM node:18-alpine
+RUN apk add --no-cache caddy
+
+WORKDIR /app
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/shared/node_modules ./shared/node_modules
+COPY --from=build /app/server/node_modules ./server/node_modules
+COPY --from=build /app/package*.json ./
+COPY --from=build /app/shared/package.json ./shared/
+COPY --from=build /app/server/package.json ./server/
+COPY shared/ ./shared/
+COPY server/ ./server/
+# built frontend served by caddy
+COPY --from=build /app/build /srv
+COPY docker/Caddyfile /etc/caddy/Caddyfile
+COPY docker/entrypoint.sh /entrypoint.sh
+
+ENV NODE_ENV=production
+ENV PORT=4001
+ENV DB_PATH=/data/tracker.sqlite
+
+EXPOSE 80
+WORKDIR /app
+CMD ["/entrypoint.sh"]

docker/docker-compose.yml

@@ -0,0 +1,23 @@
+# docker/docker-compose.yml — single container: caddy (front) + node (back).
+# Usage (from repo root):
+#   docker compose -f docker/docker-compose.yml up --build
+services:
+  app:
+    # no image: field => compose auto-names (docker-app), never pulls,
+    # always builds local. Service image private, never published.
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+      args:
+        - REACT_APP_TRACKER_APP_ID=${TRACKER_APP_ID:-ttrpg-initiative-tracker-default}
+    ports:
+      - "${PORT:-8080}:80"
+    volumes:
+      - app-data:/data
+    environment:
+      - DB_PATH=/data/tracker.sqlite
+      - PORT=4001
+    restart: unless-stopped
+
+volumes:
+  app-data:

docker/entrypoint.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+# docker/entrypoint.sh — run node backend + caddy proxy in one container.
+# Caddy foreground (PID 1, handles signals). Node background.
+set -e
+
+# node backend (internal :4001)
+cd /app/server
+node index.js &
+NODE_PID=$!
+
+# caddy proxy (foreground, :80)
+exec caddy run --config /etc/caddy/Caddyfile --adapter caddyfile

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

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.

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.

scripts/analyze-turns.js

@@ -27,7 +27,7 @@ const ADD_RE = /^\s*\[(?:add)\s+(.+?)\]\s*$/;
 const REMOVE_RE = /^\s*\[(?:remove dead|remove)\s+(.+?)\]\s*$/;
 const PAUSE_RE = /^\s*\[pause\]\s*$/;
 const RESUME_RE = /^\s*\[resume\]\s*$/;
-const ROUND_COMPLETE_RE = /^\s*---\s*round\s+(\d+)\s+complete/;
+const ROUND_COMPLETE_RE = /^\s*---\s*round\s+(\d+)\s+(?:complete|starting)/;
 const FIRST_RE = /^combat started:\s+round\s+\d+,\s+first=(.+?)\s*$/;
 const REORDER_RE = /^\s*\[reorder\s+(.+?)→before\s+(.+?)\]\s*$/;
 const POINTER_RE = /^\s*\[pointer\s+(.+?)→(.+?)( wrap)?\]\s*$/;

scripts/replay-combat.js

@@ -157,6 +157,7 @@ async function main() {
   let lastReorder = 0;
 
   for (let roundN = 1; roundN <= ROUNDS; roundN++) {
+    console.log(`--- round ${roundN} starting ---`);
     // advance initiative until round counter ticks (full cycle done).
     const cap = (enc.participants.length + 2) * 2;
     let guard = 0;
@@ -310,25 +311,25 @@ async function main() {
         lastPaused = true;
       }
 
-      // 10. reorderParticipants: every 8 turns, drag one past next (DM reorder).
+      // 10. reorderParticipants: every 8 turns, drag one past another (DM reorder).
+      // Pick two ADJACENT UPCOMING actors (both strictly after current pointer)
+      // and swap them. Avoids crossing current pointer — crossing it creates
+      // ambiguous "who acted this round" semantics (skip/double). Swapping two
+      // upcoming actors is always safe and still exercises reorder.
       if (totalTurns % 8 === 0 && lastReorder !== totalTurns) {
-        const living = enc.participants.filter(p => p.currentHp > 0 && p.isActive !== false);
-        if (living.length >= 3) {
-          // drag first past second (same-or-cross init, exercises reorder).
-          const dragged = living[0];
-          const target = living[1];
+        const curIdx = enc.turnOrderIds.indexOf(enc.currentTurnParticipantId);
+        // upcoming = everyone after current in turn order (rest of this round)
+        const upcomingIds = enc.turnOrderIds.slice(curIdx + 1)
+          .filter(id => { const p = enc.participants.find(x => x.id === id); return p && p.currentHp > 0 && p.isActive !== false; });
+        // swap first adjacent upcoming pair (drag index1 before index0)
+        if (upcomingIds.length >= 2) {
+          const target = enc.participants.find(p => p.id === upcomingIds[0]);
+          const dragged = enc.participants.find(p => p.id === upcomingIds[1]);
           try {
             const r = reorderParticipants(enc, dragged.id, target.id);
             enc = await patch(encounterPath, enc, r, `reorder ${dragged.name}→before ${target.name}`);
             lastReorder = totalTurns;
-          } catch (e) { /* same-init only — try same-init pair */
-            const sameInit = living.find(p => p !== dragged && p.initiative === dragged.initiative);
-            if (sameInit) {
-              const r = reorderParticipants(enc, dragged.id, sameInit.id);
-              enc = await patch(encounterPath, enc, r, `reorder ${dragged.name}→before ${sameInit.name}`);
-              lastReorder = totalTurns;
-            }
-          }
+          } catch (e) { /* swap not allowed — skip this round */ }
         }
       }
 
@@ -338,8 +339,6 @@ async function main() {
     }
     if (!enc.isStarted) { console.log('combat auto-ended'); break; }
     const alive = enc.participants.filter(p => p.currentHp > 0).length;
-    console.log(`--- round ${roundN} complete (turns=${totalTurns}, alive=${alive}) ---`);
-
     // revive dead: heal to full + reactivate. Sustains combat for 100 rounds
     // and exercises toggleActive reactivate + heal-from-zero path.
     const dead = enc.participants.filter(p => p.currentHp <= 0 || p.isActive === false);

server/Dockerfile

@@ -1,23 +0,0 @@
-# server/Dockerfile — backend (Express + ws + better-sqlite3)
-FROM node:18-alpine AS build
-WORKDIR /app
-
-# workspaces root needed: shared/ is a dependency (@ttrpg/shared)
-COPY package*.json ./
-COPY shared/package.json ./shared/
-COPY server/package.json ./server/
-RUN npm install --workspaces --include-workspace-root
-
-COPY shared/ ./shared/
-COPY server/ ./server/
-
-# better-sqlite3 builds native; rebuild for alpine musl
-RUN cd server && npm rebuild better-sqlite3
-
-ENV NODE_ENV=production
-ENV PORT=4001
-ENV DB_PATH=/data/tracker.sqlite
-
-EXPOSE 4001
-WORKDIR /app/server
-CMD ["node", "index.js"]

server/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [['@babel/preset-env', { targets: { node: 'current' } }]],
+};

server/index.js

@@ -131,7 +131,11 @@ function createServer({ dbPath, port, corsOrigin } = {}) {
 
   return {
     app, server, wss, store, db,
-    close(done) { wss.close(); server.close(() => { db.close(); if (done) done(); }); },
+    close(done) {
+      wss.clients.forEach(c => { try { c.terminate(); } catch {} });
+      wss.close();
+      server.close(() => { db.close(); if (done) done(); });
+    },
   };
 }
 

server/tests/ws-contract.test.js

@@ -14,18 +14,16 @@ const { createServer } = require('../index');
 const { createWsStorage } = require('../../src/storage/ws');
 const { runStorageContract } = require('../../src/storage/contract');
 
-let nextPort = 4000 + Math.floor(Math.random() * 999);
-
 // Factory: fresh backend (unique sqlite file) + storage pointed at it.
 // Disposing the storage closes the backend so each test is fully isolated.
 async function makeStorage() {
-  const port = nextPort++;
-  const dbPath = path.join(os.tmpdir(), `ws-contract-${port}-${Date.now()}.sqlite`);
-  const handle = createServer({ dbPath, port });
+  const dbPath = path.join(os.tmpdir(), `ws-contract-${Date.now()}-${Math.random().toString(36).slice(2)}.sqlite`);
+  const handle = createServer({ dbPath, port: 0 });
   await new Promise((resolve, reject) => {
     handle.server.on('error', reject);
-    handle.server.listen(port, resolve);
+    handle.server.listen(0, resolve);
   });
+  const port = handle.server.address().port;
   const baseUrl = `http://127.0.0.1:${port}`;
   const wsUrl = `ws://127.0.0.1:${port}/ws`;
   const storage = createWsStorage({ baseUrl, wsUrl });

server/tests/ws-reconnect.test.js

@@ -12,16 +12,14 @@ const { createWsStorage } = require('../../src/storage/ws');
 
 const flush = (ms = 150) => new Promise(r => setTimeout(r, ms));
 
-let nextPort = 5000 + Math.floor(Math.random() * 999);
-
 async function makeStorage() {
-  const port = nextPort++;
-  const dbPath = path.join(os.tmpdir(), `ws-recon-${port}-${Date.now()}.sqlite`);
-  const handle = createServer({ dbPath, port });
+  const dbPath = path.join(os.tmpdir(), `ws-recon-${Date.now()}-${Math.random().toString(36).slice(2)}.sqlite`);
+  const handle = createServer({ dbPath, port: 0 });
   await new Promise((resolve, reject) => {
     handle.server.on('error', reject);
-    handle.server.listen(port, resolve);
+    handle.server.listen(0, resolve);
   });
+  const port = handle.server.address().port;
   const baseUrl = `http://127.0.0.1:${port}`;
   const wsUrl = `ws://127.0.0.1:${port}/ws`;
   const storage = createWsStorage({ baseUrl, wsUrl });

src/App.js

@@ -2500,9 +2500,10 @@ function DisplayView() {
 
   let participantsToRender = [];
   if (participants) {
-    // Hide inactive monsters (pre-staged/summoned reserves) from the player view
-    const visibleParticipants = participants.filter(p => p.isActive || p.type !== 'monster');
-    participantsToRender = sortParticipantsByInitiative(visibleParticipants, visibleParticipants);
+    // 1-list model: participants[] IS the display order (DM drag = source of
+    // truth). Do NOT re-sort by initiative — that diverges from AdminView /
+    // turnOrderIds after any cross-init drag (BUG-15).
+    participantsToRender = participants.filter(p => p.isActive || p.type !== 'monster');
   }
 
   const displayStyles = campaignBackgroundUrl

src/storage/index.js

@@ -11,6 +11,8 @@ import {
   onSnapshot, updateDoc, deleteDoc, query, orderBy, limit, writeBatch,
 } from 'firebase/firestore';
 import { initFirebase, createFirebaseStorage } from './firebase';
+import { createWsStorage } from './ws';
+import { createMemoryStorage } from './memory';
 
 let storageInstance = null;
 
@@ -23,13 +25,11 @@ export function getStorage() {
     if (!ok) throw new Error('Firebase config missing. Check REACT_APP_FIREBASE_* env.');
     storageInstance = createFirebaseStorage();
   } else if (mode === 'ws') {
-    const { createWsStorage } = require('./ws');
     storageInstance = createWsStorage({
-      baseUrl: process.env.REACT_APP_BACKEND_URL || 'http://127.0.0.1:4001',
-      wsUrl: process.env.REACT_APP_BACKEND_WS || 'ws://127.0.0.1:4001/ws',
+      baseUrl: process.env.REACT_APP_BACKEND_URL || '',
+      wsUrl: process.env.REACT_APP_BACKEND_WS || '',
     });
   } else {
-    const { createMemoryStorage } = require('./memory');
     storageInstance = createMemoryStorage();
   }
   return storageInstance;

src/storage/memory.js

@@ -4,7 +4,7 @@
 
 'use strict';
 
-const { EventEmitter } = require('events');
+import { EventEmitter } from 'events';
 
 function createMemoryStorage() {
   const docs = new Map();              // path -> data obj
@@ -137,4 +137,4 @@ function deepClone(v) {
   return JSON.parse(JSON.stringify(v));
 }
 
-module.exports = { createMemoryStorage };
+export { createMemoryStorage };

src/storage/ws.js

@@ -5,11 +5,10 @@
 'use strict';
 
 // Native browser WebSocket if present, else ws pkg (Node/jest).
+// Lazy load ws pkg so CRA prod build (ESM) doesn't choke on require().
 let WebSocketImpl;
 if (typeof WebSocket !== 'undefined') {
   WebSocketImpl = WebSocket;
-} else {
-  WebSocketImpl = require('ws').WebSocket;
 }
 
 function createWsStorage({ baseUrl, wsUrl } = {}) {
@@ -39,13 +38,59 @@ function createWsStorage({ baseUrl, wsUrl } = {}) {
   let ws = null;
   let wsReady = null;
 
+  let disposed = false;
+  let reconnectTimer = null;
+  let everConnected = false;
+  const RECONNECT_DELAY = 500;
+
   function ensureWs() {
     if (wsReady) return wsReady;
     wsReady = new Promise((resolve, reject) => {
-      ws = new WebSocketImpl(WS);
-      const onOpen = () => resolve(ws);
+      (async () => {
+        // Node/jest only: load ws pkg via dynamic import. Browser uses global
+        // WebSocket. Avoids require() in CRA prod ESM bundle (webpack crash).
+        let WsClass = WebSocketImpl;
+        if (!WsClass) {
+          const wsPkg = await import('ws');
+          WsClass = wsPkg.WebSocket;
+        }
+        ws = new WsClass(WS);
+      const onOpen = () => {
+        const isReconnect = everConnected;
+        everConnected = true;
+        // resubscribe all existing subscribers after (re)connect
+        for (const p of docSubs.keys()) {
+          ws.send(JSON.stringify({ type: 'subscribe', kind: 'doc', path: p }));
+        }
+        for (const p of collSubs.keys()) {
+          ws.send(JSON.stringify({ type: 'subscribe', kind: 'collection', path: p }));
+        }
+        // On RECONNECT only: re-fetch current values — catches writes that
+        // happened while disconnected (broadcast missed). Skip on first connect
+        // (initial REST fetch in subscribeDoc/subscribeCollection already did).
+        if (isReconnect) {
+          for (const [p, cbs] of docSubs) {
+            storage.getDoc(p).then(doc => { cbs.forEach(cb => cb(doc)); }).catch(() => {});
+          }
+          for (const [p, cbs] of collSubs) {
+            storage.getCollection(p).then(docs => { cbs.forEach(cb => cb(docs)); }).catch(() => {});
+          }
+        }
+        resolve(ws);
+      };
       const onError = (err) => { wsReady = null; reject(err instanceof Event ? new Error('ws error') : err); };
-      const onClose = () => { wsReady = null; };
+      const onClose = () => {
+        wsReady = null;
+        ws = null;
+        if (disposed) return;
+        // auto-reconnect (BUG-8): try again after delay. ensureWs() re-arms.
+        if (reconnectTimer) clearTimeout(reconnectTimer);
+        reconnectTimer = setTimeout(() => {
+          reconnectTimer = null;
+          if (!disposed) ensureWs().catch(() => {});
+        }, RECONNECT_DELAY);
+        if (reconnectTimer && typeof reconnectTimer.unref === 'function') reconnectTimer.unref();
+      };
       const onMessage = (ev) => {
         const raw = typeof ev === 'string' ? ev : (ev.data !== undefined ? ev.data : ev);
         let msg; try { msg = JSON.parse(typeof raw === 'string' ? raw : raw.toString()); } catch { return; }
@@ -61,6 +106,7 @@ function createWsStorage({ baseUrl, wsUrl } = {}) {
         ws.addEventListener('close', onClose);
         ws.addEventListener('message', onMessage);
       }
+      })();
     });
     return wsReady;
   }
@@ -168,7 +214,13 @@ function createWsStorage({ baseUrl, wsUrl } = {}) {
       return () => { collSubs.get(p)?.delete(cb); };
     },
 
-    dispose() { if (ws) ws.close(); docSubs.clear(); collSubs.clear(); },
+    dispose(cb) {
+      disposed = true;
+      if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
+      if (ws) ws.close();
+      docSubs.clear(); collSubs.clear();
+      if (typeof cb === 'function') cb();
+    },
 
     _api: api,
     _test: {
@@ -182,4 +234,4 @@ function createWsStorage({ baseUrl, wsUrl } = {}) {
   return storage;
 }
 
-module.exports = { createWsStorage };
+export { createWsStorage };

src/tests/DisplayView.drag-order.test.js

@@ -0,0 +1,63 @@
+// RED test: DisplayView must render participants in turnOrderIds (drag) order,
+// NOT re-sort by initiative. 1-list model: participants[] = display source.
+// Bug: DisplayView line ~2505 calls sortParticipantsByInitiative(), ignoring
+// DM drag order. After cross-init drag, display diverges from AdminView/turnOrderIds.
+import React from 'react';
+import { render, waitFor, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import App from '../App';
+import { MOCK_DB } from '../__mocks__/firebase/_mock-db';
+import { resetAdapterCalls } from '../storage/firebase';
+
+function seedDragOrder() {
+  const campaignPath = 'artifacts/ttrpg-initiative-tracker-default/public/data/campaigns/c1';
+  const encounterPath = 'artifacts/ttrpg-initiative-tracker-default/public/data/campaigns/c1/encounters/e1';
+  const activeDisplayPath = 'artifacts/ttrpg-initiative-tracker-default/public/data/activeDisplay/status';
+  // Three monsters, init-sorted would be: high(20), mid(11), low(10).
+  // But participants[] = DRAG order: low BEFORE mid (DM dragged across init).
+  const participants = [
+    { id: 'high', name: 'High', type: 'monster', initiative: 20, currentHp: 10, maxHp: 10, isActive: true },
+    { id: 'low', name: 'Low', type: 'monster', initiative: 10, currentHp: 10, maxHp: 10, isActive: true },
+    { id: 'mid', name: 'Mid', type: 'monster', initiative: 11, currentHp: 10, maxHp: 10, isActive: true },
+  ];
+  MOCK_DB.set(campaignPath, { name: 'Camp', playerDisplayBackgroundUrl: '' });
+  MOCK_DB.set(encounterPath, {
+    name: 'Enc',
+    participants,
+    turnOrderIds: participants.map(p => p.id),
+    round: 1,
+    currentTurnParticipantId: 'high',
+    isStarted: true,
+  });
+  MOCK_DB.set(activeDisplayPath, { activeCampaignId: 'c1', activeEncounterId: 'e1', hidePlayerHp: false });
+}
+
+describe('DisplayView drag order (BUG-15)', () => {
+  beforeEach(() => {
+    window.history.replaceState({}, '', '/display');
+    global.alert = jest.fn();
+    window.open = jest.fn();
+    // jsdom lacks scrollIntoView (DisplayView auto-scrolls current actor)
+    Element.prototype.scrollIntoView = jest.fn();
+    resetAdapterCalls();
+  });
+  afterEach(() => {
+    window.history.replaceState({}, '', '/');
+  });
+
+  test('renders participants in participants[] order, not init-sorted', async () => {
+    seedDragOrder();
+    render(<App />);
+
+    // wait for participant names to render
+    await waitFor(() => {
+      expect(screen.getAllByText(/High|Mid|Low/i).length).toBeGreaterThanOrEqual(3);
+    }, { timeout: 3000 });
+
+    // collect name elements in DOM order (strip Current marker)
+    const names = screen.getAllByText(/High|Mid|Low/i).map(el => el.textContent.replace(/\(Current\)/i, '').trim());
+    // participants[] order = High, Low, Mid (drag moved Low before Mid).
+    // Display must mirror this. Init-sorted would be High, Mid, Low.
+    expect(names).toEqual(['High', 'Low', 'Mid']);
+  });
+});

src/tests/StorageEsm.test.js

@@ -0,0 +1,19 @@
+// Lock: storage adapters must use ESM exports (no module.exports).
+// Regression guard: CJS in src/ crashes CRA prod build (ESM strict).
+// Bug history: ws.js + memory.js used module.exports. Dev lenient (masked),
+// prod bundle crashed blank page. firebase.js always ESM.
+import fs from 'fs';
+import path from 'path';
+
+const ADAPTER_DIR = path.join(__dirname, '..', 'storage');
+
+describe('storage adapters use ESM (no CJS)', () => {
+  const adapters = ['ws.js', 'memory.js', 'firebase.js', 'index.js'];
+  test.each(adapters)('%s has no module.exports', (file) => {
+    const full = fs.readFileSync(path.join(ADAPTER_DIR, file), 'utf8');
+    // strip line comments so words like 'require' in explanatory comments don't trip the guard
+    const src = full.replace(/^\s*\/\/.*$/gm, '');
+    expect(src).not.toMatch(/module\.exports\s*=/);
+    expect(src).not.toMatch(/\brequire\s*\(/);
+  });
+});