From 891fc696d98f525902447054b2bd7bf9f92f98b8 Mon Sep 17 00:00:00 2001
From: david raistrick <1108844+keen99@users.noreply.github.com>
Date: Mon, 29 Jun 2026 15:19:18 -0400
Subject: [PATCH] docs: add glossary (turn vs round, participants, views,
 backend)

---
 docs/GLOSSARY.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 docs/GLOSSARY.md

diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md
new file mode 100644
index 0000000..bddf0b6
--- /dev/null
+++ b/docs/GLOSSARY.md
@@ -0,0 +1,59 @@
+# Glossary — TTRPG Initiative Tracker
+
+Domain terms used throughout the app, shared turn logic, tests, and docs. Keep
+these definitions stable so logs, UI labels, and code agree.
+
+## Combat structure
+
+| Term | Meaning |
+|------|---------|
+| **Initiative** | The ordered sequence determining who acts next. Rolled once at the start of an encounter; re-rolled only on a new encounter or explicit DM re-roll. |
+| **Round** | One full pass through initiative — every active participant gets exactly one turn. N participants (PCs + NPCs + monsters + features) = N turns per round. Round counter increments when initiative wraps back to the first participant. |
+| **Turn** | A single participant's initiative slot within a round. One participant acts. As many turns per round as there are participants. |
+| **Initiative slot** | Synonym for turn's position in the ordered list. |
+| **Top of round** | The first turn of a round (round counter increments here). |
+
+Example: encounter with 8 participants (3 PCs + 4 monsters + 1 NPC).
+
+```
+Round 1: turn 1 (Fighter) → turn 2 (Goblin1) → ... → turn 8 (Merchant)
+Round 2: turn 1 (Fighter) → ... → turn 8 (Merchant)   [round counter +=1 at top]
+```
+
+## Participants
+
+| Term | Meaning |
+|------|---------|
+| **Participant** | Any combatant tracked in initiative. Has HP, initiative roll, conditions, and an `isActive` flag. |
+| **PC** (Player Character) | Controlled by a player. On death → death saves (not removed from initiative). |
+| **NPC** (Non-Player Character) | DM-controlled ally/neutral (e.g. merchant, quest-giver). May or may not roll initiative. |
+| **Monster** | Hostile DM-controlled combatant. On death → typically removed from active initiative or marked dead. |
+| **Feature / Lair** | Environmental or legendary effect that occupies an initiative slot (e.g. lair action at initiative 20). |
+
+## Participant state
+
+| Term | Meaning |
+|------|---------|
+| **HP** (Hit Points) | Current health. `currentHp` / `maxHp`. At 0 → dying or dead (rules differ by type). |
+| **Initiative mod** | Bonus added to d20 initiative roll. `defaultInitMod`. |
+| **Conditions** | Temporary status effects (stunned, prone, poisoned, etc.) applied/toggled during play. Array on participant. |
+| **isActive** | Whether the participant is in the active initiative rotation. Set false on death (CURRENT behavior — see M4 skip-bug fix). |
+| **Death save** | PC-only mechanic. Successes/failures tracked at 0 HP. 3 fails → dead; 3 successes → stable. |
+
+## Views
+
+| Term | Meaning |
+|------|---------|
+| **Admin view** (`/`) | DM interface. Full create/edit/combat control. |
+| **Player view** (`/display` or `?playerView=true`) | Read-only second-screen display for players. Shows current turn, HP bars, conditions, round. No DM controls. |
+| **Active display** | The single `activeDisplay/status` doc controlling what the player view shows (which campaign/encounter, hide-player-HP flag). |
+
+## Backend / storage
+
+| Term | Meaning |
+|------|---------|
+| **Adapter** | `src/storage/{firebase,ws,memory}.js`. Contract boundary between App and backend. App only calls `storage.*`, never raw SDK/fetch. |
+| **Path normalization** (`norm()`) | Strip firebase prefix (`artifacts/{APP_ID}/public/data/`) → bare canonical path (`campaigns/X`). Runs inside every adapter method. |
+| **Generic KV doc store** | Backend stores opaque JSON at arbitrary path strings. No shape-specific endpoints. Backend = firebase mirror, not REST API for app entities. |
+| **Layer 1 test** | App vs firebase mock. Proves adapter call shape. |
+| **Layer 2 test** | ws adapter vs live backend. Proves translation + path identity. |