ttrpg-initiative-tracker/docs/GLOSSARY.md

# 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,server}.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** | server adapter vs live backend. Proves translation + path identity. |