Fix custom combatant form disappearing when dismissing suggestions

The "Add as custom" button and Escape key were clearing the name input
along with the suggestions, preventing the custom fields (Init, AC,
MaxHP) from ever appearing. Now only the suggestions are dismissed,
keeping the typed name intact so the custom combatant form renders.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.claude/commands/integrate-issue.md

@@ -0,0 +1,143 @@
+---
+description: Fetch a Gitea issue, identify the affected feature spec(s), and integrate the issue's requirements into the spec. For new features, hands off to /speckit.specify.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** provide an issue number as the argument (e.g. `/integrate-issue 6`). If `$ARGUMENTS` is empty or not a valid number, ask the user for the issue number.
+
+## Prerequisites
+
+1. Verify the `GITEA_TOKEN_ISSUES` environment variable is set:
+
+```bash
+test -n "$GITEA_TOKEN_ISSUES" && echo "TOKEN_OK" || echo "TOKEN_MISSING"
+```
+
+If missing, tell the user to set it:
+```
+export GITEA_TOKEN_ISSUES="your-gitea-personal-access-token"
+```
+Then abort.
+
+2. Parse the git remote to extract the Gitea API base URL, owner, and repo:
+
+```bash
+git config --get remote.origin.url
+```
+
+Expected format: `ssh://git@<host>:<port>/<owner>/<repo>.git` or `https://<host>/<owner>/<repo>.git`
+
+Extract:
+- `GITEA_HOST` — the hostname
+- `OWNER` — the repo owner/org
+- `REPO` — the repo name (strip `.git` suffix)
+- `API_BASE` — `https://<GITEA_HOST>/api/v1`
+
+## Execution
+
+### Step 1 — Fetch the issue
+
+```bash
+curl -sf -H "Authorization: token $GITEA_TOKEN_ISSUES" "$API_BASE/repos/$OWNER/$REPO/issues/<NUMBER>"
+```
+
+Extract from the JSON response:
+- `title` — the issue title
+- `body` — the issue body (markdown)
+- `labels` — array of label names (if any)
+
+If the API call fails or returns no issue, abort with a clear error.
+
+### Step 2 — Fetch issue comments (if any)
+
+```bash
+curl -sf -H "Authorization: token $GITEA_TOKEN_ISSUES" "$API_BASE/repos/$OWNER/$REPO/issues/<NUMBER>/comments"
+```
+
+If comments exist, include them as additional context (they may contain clarifications or requirements discussed after the issue was created).
+
+### Step 3 — Route: new feature or existing feature?
+
+List the existing feature specs by reading the `specs/` directory:
+
+```bash
+ls -d specs/*/
+```
+
+Present the issue summary and existing specs to the user. Ask:
+
+**"Does this issue belong to an existing feature, or is it a new feature?"**
+
+Present options:
+- Each existing spec as a numbered option (show spec name and one-line description from CLAUDE.md or the spec's overview)
+- A "New feature" option
+
+If the user selects **New feature**, compose the feature description from the issue content (title + body + comments) and hand off to `/speckit.specify`. Stop here.
+
+If the user selects an **existing spec**, continue to Step 4.
+
+### Step 4 — Read the affected spec
+
+Load the selected spec file. Identify the sections that the issue's requirements affect:
+- Which user stories need updating?
+- Which requirements (FR-NNN) need adding or modifying?
+- Which acceptance scenarios change?
+- Are new edge cases introduced?
+
+Present your analysis to the user:
+- **Stories affected**: list the story IDs/titles that need changes
+- **New stories needed**: if the issue introduces behavior not covered by any existing story
+- **Requirements to add/modify**: list specific FR numbers or new ones needed
+
+Ask the user to confirm or adjust the scope.
+
+### Step 5 — Draft spec changes
+
+For each affected section, draft the specific changes:
+
+- **Modified stories**: show the before/after for acceptance scenarios
+- **New stories**: write them in the spec's format (matching the existing story naming convention — e.g., `**Story HP-7**` for combatant-state, `**Story A4**` for combatant-management)
+- **New/modified requirements**: write them with the next available FR number
+- **New edge cases**: add to the relevant edge cases section
+
+For per-topic specs (003-combatant-state, 004-bestiary), place changes in the correct topic section.
+
+### Step 6 — Preview and confirm
+
+Show the user a complete preview of all changes:
+- Which file(s) will be modified
+- The exact additions/modifications (as diffs or before/after blocks)
+
+Ask for confirmation before writing.
+
+### Step 7 — Write changes
+
+On confirmation:
+- Write the updated spec file(s)
+- Report what was changed (sections touched, stories added/modified, requirements added)
+
+### Step 8 — Suggest next steps
+
+Report completion and suggest next steps based on scope:
+
+- **Straightforward change** (1-2 stories, clear acceptance scenarios): "Implement the changes and commit"
+- **Larger change** (multiple stories, cross-cutting concerns): "Use `rpi-research` to investigate the affected code, then `rpi-plan` to create a phased implementation plan, then `rpi-implement` to execute it"
+- **Complex or ambiguous change**: "Run `/speckit.clarify` to resolve remaining ambiguities before implementing"
+- Only if the spec adds substantive new criteria not already captured in the issue: "Run `/sync-issue <number>` to update the Gitea issue with the new acceptance criteria". Skip this if the spec merely reformulates what the issue already says into Given/When/Then format.
+
+## Behavior Rules
+
+- Never modify the issue on Gitea — this is a read-only operation on the issue side.
+- Always preview before writing spec changes — never write without user confirmation.
+- Include comment authors in the context so requirements can be attributed.
+- If the issue body is empty, warn the user but still proceed with just the title.
+- Strip HTML tags from the body/comments if present (Gitea sometimes includes rendered HTML).
+- Use `curl` for all API calls — do not rely on `gh` CLI.
+- Match the existing spec's naming conventions for stories, requirements, and structure.
+- When adding to per-topic specs (003, 004), place content in the correct topic section — do not create new top-level sections unless the change introduces an entirely new topic area.
+- Increment FR/SC numbers from the highest existing number in the spec.

.claude/commands/speckit.plan.md

@@ -75,14 +75,7 @@ You **MUST** consider the user input before proceeding (if not empty).
    - Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
    - Skip if project is purely internal (build scripts, one-off tools, etc.)
 
-3. **Agent context update**:
-   - Run `.specify/scripts/bash/update-agent-context.sh claude`
-   - These scripts detect which AI agent is in use
-   - Update the appropriate agent-specific context file
-   - Add only new technology from current plan
-   - Preserve manual additions between markers
-
-**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file
+**Output**: data-model.md, /contracts/*, quickstart.md
 
 ## Key rules
 

.claude/commands/sync-issue.md

@@ -0,0 +1,162 @@
+---
+description: Update a Gitea issue with business-level acceptance criteria extracted from the feature spec's user stories.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** provide an issue number as the argument (e.g. `/sync-issue 42`). If `$ARGUMENTS` is empty or not a valid number, ask the user for the issue number.
+
+## Prerequisites
+
+1. Verify the `GITEA_TOKEN_ISSUES` environment variable is set:
+
+```bash
+test -n "$GITEA_TOKEN_ISSUES" && echo "TOKEN_OK" || echo "TOKEN_MISSING"
+```
+
+If missing, tell the user to set it:
+```
+export GITEA_TOKEN_ISSUES="your-gitea-personal-access-token"
+```
+Then abort.
+
+2. Parse the git remote to extract the Gitea API base URL, owner, and repo:
+
+```bash
+git config --get remote.origin.url
+```
+
+Expected format: `ssh://git@<host>:<port>/<owner>/<repo>.git` or `https://<host>/<owner>/<repo>.git`
+
+Extract:
+- `GITEA_HOST` — the hostname
+- `OWNER` — the repo owner/org
+- `REPO` — the repo name (strip `.git` suffix)
+- `API_BASE` — `https://<GITEA_HOST>/api/v1`
+
+3. Locate the spec file. List the available feature specs:
+
+```bash
+ls specs/*/spec.md
+```
+
+Present the specs to the user and ask which one contains the acceptance criteria for this issue. If only one spec exists, use it automatically.
+
+## Execution
+
+### Step 1 — Read the spec
+
+Load the spec file at `FEATURE_SPEC`. Extract user stories and acceptance scenarios using these patterns:
+
+**Flat specs** (001-combatant-management, 002-turn-tracking):
+- Look for the `## User Scenarios & Testing` section
+- Each `### ... Story ...` or `**Story ...** ` block
+- The **Acceptance Scenarios** numbered list within each story (Given/When/Then format)
+- The **Edge Cases** section(s)
+
+**Per-topic specs** (003-combatant-state, 004-bestiary):
+- Stories are nested inside topic sections (e.g., `## Hit Points` > `### User Stories` > `**Story HP-1 — ...**`)
+- Scan ALL `##` sections for `**Story ...` or `**US-...` patterns
+- Extract acceptance scenarios from each story regardless of nesting depth
+- Collect edge cases from each topic section's `### Edge Cases` subsection
+
+### Step 2 — Condense into business-level acceptance criteria
+
+For each user story, extract the acceptance scenarios and rewrite them as concise, business-level checkbox items. Group by user story title.
+
+**Transformation rules:**
+- Strip Given/When/Then syntax — write as plain outcomes
+- Remove implementation details (API names, database references, component names, file paths, config values, tool names)
+- Focus on what the user **can do** or **can see**
+- Keep each item to one line
+- Preserve the grouping by user story for readability
+
+**Example transformation:**
+
+Input (from spec):
+```
+**Given** no sources are cached, **When** the user clicks the import button in the top bar,
+**Then** the stat block side panel opens showing a descriptive explanation, an editable
+pre-filled base URL, and a "Load All" button.
+```
+
+Output (for issue):
+```
+- [ ] Clicking the import button opens a panel with a description, editable URL, and "Load All" button
+```
+
+Also include edge cases as a separate group if they describe user-facing behavior.
+
+### Step 3 — Fetch the existing issue
+
+```bash
+curl -sf -H "Authorization: token $GITEA_TOKEN_ISSUES" "$API_BASE/repos/$OWNER/$REPO/issues/<NUMBER>"
+```
+
+Extract the current `body` from the response.
+
+### Step 4 — Update the issue body
+
+Merge the acceptance criteria into the existing issue body:
+
+- If the body already has an `## Acceptance Criteria` section, **replace** its contents (everything between `## Acceptance Criteria` and the next `##` heading or end of body).
+- If the body does not have an `## Acceptance Criteria` section, insert it after the `## Summary` section (or at the end if no Summary exists).
+
+Preserve all other sections of the issue body unchanged.
+
+The acceptance criteria section should look like:
+
+```markdown
+## Acceptance Criteria
+
+### <User Story 1 Title>
+- [ ] <criterion from acceptance scenario>
+- [ ] <criterion from acceptance scenario>
+
+### <User Story 2 Title>
+- [ ] <criterion from acceptance scenario>
+
+### Edge Cases
+- [ ] <edge case behavior>
+```
+
+### Step 5 — Preview and confirm
+
+Show the user:
+- The full updated issue body
+- A diff summary of what changed (sections added/replaced)
+
+Ask for confirmation before updating.
+
+### Step 6 — Push the update
+
+On confirmation:
+
+```bash
+curl -sf -X PATCH \
+  -H "Authorization: token $GITEA_TOKEN_ISSUES" \
+  -H "Content-Type: application/json" \
+  "$API_BASE/repos/$OWNER/$REPO/issues/<NUMBER>" \
+  -d @- <<'PAYLOAD'
+{
+  "body": "<updated body>"
+}
+PAYLOAD
+```
+
+Report success with the issue URL.
+
+## Behavior Rules
+
+- Never modify the issue title, labels, milestone, or assignees — only the body.
+- Always preview before updating — never push without user confirmation.
+- If the spec has no user stories or acceptance scenarios, abort with a clear message suggesting the user run `/speckit.specify` first.
+- Acceptance criteria must be business-level. If you find yourself writing implementation details, rewrite at a higher level of abstraction.
+- Do NOT sync when the issue's existing acceptance criteria already capture the same requirements as the spec. The spec's Given/When/Then format is not needed in the issue — if the only difference is formatting, skip the sync and tell the user the criteria already align.
+- Use `curl` for all API calls — do not rely on `gh` CLI.
+- Always use HEREDOC for the JSON payload to handle special characters in the body.
+- Escape double quotes and newlines properly in the JSON body.

.claude/commands/write-issue.md

@@ -0,0 +1,163 @@
+---
+description: Interactive interview to create a well-structured Gitea issue with business-level acceptance criteria.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Prerequisites
+
+1. Verify the `GITEA_TOKEN_ISSUES` environment variable is set:
+
+```bash
+test -n "$GITEA_TOKEN_ISSUES" && echo "TOKEN_OK" || echo "TOKEN_MISSING"
+```
+
+If missing, tell the user to set it:
+```
+export GITEA_TOKEN_ISSUES="your-gitea-personal-access-token"
+```
+Then abort.
+
+2. Parse the git remote to extract the Gitea base URL, owner, and repo:
+
+```bash
+git config --get remote.origin.url
+```
+
+Expected format: `ssh://git@<host>:<port>/<owner>/<repo>.git` or `https://<host>/<owner>/<repo>.git`
+
+Extract:
+- `GITEA_HOST` — the hostname (e.g. `git.bahamut.nitrix.one`)
+- `GITEA_PORT` — the port if present in SSH URL (for API, always use HTTPS on default port)
+- `OWNER` — the repo owner/org
+- `REPO` — the repo name (strip `.git` suffix)
+- `API_BASE` — `https://<GITEA_HOST>/api/v1`
+
+Verify the remote is reachable:
+```bash
+curl -sf -H "Authorization: token $GITEA_TOKEN_ISSUES" "$API_BASE/repos/$OWNER/$REPO" | head -c 200
+```
+
+If this fails, abort with an error explaining the API is unreachable.
+
+## Interview Flow
+
+### Step 1 — What's the feature?
+
+If `$ARGUMENTS` is not empty, use it as the initial feature description and skip asking.
+
+Otherwise, ask the user: **"What feature or change do you want to build?"**
+
+Accept a free-form description (1-3 sentences is fine).
+
+### Step 2 — Contextual business questions
+
+Analyze the feature description and identify what's ambiguous or underspecified **for this specific feature**. Generate 1-3 targeted questions that would materially improve the issue.
+
+Rules:
+- Questions MUST be derived from the specific feature description, not from a generic checklist.
+- Only ask questions whose answers change the scope, behavior, or acceptance criteria.
+- If the feature is straightforward and well-described, skip this step entirely.
+- Present one question at a time using the AskUserQuestion tool.
+- For each question, provide 2-4 concrete options plus the ability to give a custom answer.
+- After each answer, decide if you need another question or have enough clarity.
+
+Examples of good contextual questions:
+- For a "color overhaul" feature: "Are you targeting specific components or a global palette change?"
+- For a "bulk import" feature: "Should the user see progress during import or just a final result?"
+- For an "initiative tiebreaker" feature: "Should ties be broken by DEX score, manual choice, or random roll?"
+
+Examples of bad questions (never ask these):
+- Generic: "Who is the target user?"
+- Obvious: "Should errors be handled?"
+- Implementation: "What database should we use?"
+
+### Step 3 — Acceptance criteria
+
+Based on the description and clarifications, draft 3-8 business-level acceptance criteria. These should describe **what the user can do or see**, not how the system implements it.
+
+Present the draft to the user and ask if they want to add, remove, or change any.
+
+Good: "User can load all sources with a single click"
+Bad: "System fires concurrent fetch requests to IndexedDB"
+
+### Step 4 — Labels and milestone (optional)
+
+Fetch available labels and milestones from the Gitea API:
+
+```bash
+curl -sf -H "Authorization: token $GITEA_TOKEN_ISSUES" "$API_BASE/repos/$OWNER/$REPO/labels"
+curl -sf -H "Authorization: token $GITEA_TOKEN_ISSUES" "$API_BASE/repos/$OWNER/$REPO/milestones"
+```
+
+If labels/milestones exist, present them to the user and ask which (if any) to apply. If none exist or the API returns empty, skip this step.
+
+### Step 5 — Branch linking
+
+Check if we're on a feature branch:
+
+```bash
+git branch --show-current
+```
+
+If the current branch is not `main` (and looks like a feature branch, e.g. `NNN-feature-name`), offer to include it in the issue body as a linked branch.
+
+### Step 6 — Preview and create
+
+Compose the issue body using this template:
+
+```markdown
+## Summary
+
+<2-3 sentence description synthesized from the interview>
+
+## Acceptance Criteria
+
+- [ ] <criterion 1>
+- [ ] <criterion 2>
+- [ ] <criterion 3>
+...
+
+## Branch
+
+`<branch-name>` *(if linked in step 5)*
+```
+
+Show the full preview (title + body) to the user and ask for confirmation.
+
+On confirmation, create the issue:
+
+```bash
+curl -sf -X POST \
+  -H "Authorization: token $GITEA_TOKEN_ISSUES" \
+  -H "Content-Type: application/json" \
+  "$API_BASE/repos/$OWNER/$REPO/issues" \
+  -d @- <<'PAYLOAD'
+{
+  "title": "<issue title>",
+  "body": "<issue body>",
+  "labels": [<label IDs if selected>],
+  "milestone": <milestone ID if selected or null>
+}
+PAYLOAD
+```
+
+Parse the response and report:
+- Issue number and URL (`https://<GITEA_HOST>/<OWNER>/<REPO>/issues/<number>`)
+- Suggest next step: `/integrate-issue <number>` to integrate into a feature spec
+
+## Behavior Rules
+
+- Keep the title short — under 70 characters.
+- Acceptance criteria must be business-level, not implementation details.
+- Never create an issue without user confirmation of the preview.
+- If any API call fails, show the error and suggest the user check their token permissions.
+- Use `curl` for all API calls — do not rely on `gh` CLI.
+- Always use HEREDOC for the JSON payload to handle special characters in the body.
+- Escape double quotes and newlines properly in the JSON body.

.claude/skills/rpi-implement/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: rpi-implement
+description: Execute approved implementation plans phase by phase with automated and manual verification. Use when the user explicitly says "implement the plan", "execute the plan", or "start implementing" and has a plan file ready. Do not use for ad-hoc coding tasks without a plan.
+---
+
+# Implement Plan
+
+You are tasked with implementing an approved technical plan. These plans contain phases with specific changes and success criteria.
+
+## Getting Started
+
+If the user provided a plan path, proceed directly. If no plan path was provided, check `docs/agents/plans/` for recent plans. If none found, ask the user for a path.
+
+When you have a plan:
+- Read the plan completely and check for any existing checkmarks (`- [x]`)
+- Read all files mentioned in the plan
+- **Read files fully** - never use limit/offset parameters, you need complete context
+- Think deeply about how the pieces fit together
+- If you have a todo list, use it to track your progress
+- Start implementing if you understand what needs to be done
+
+## Implementation Philosophy
+
+Plans are carefully designed, but reality can be messy. Your job is to:
+- Follow the plan's intent while adapting to what you find
+- Implement each phase fully before moving to the next
+- Verify your work makes sense in the broader codebase context
+- Keep plan checkboxes current: `[-]` before starting an item, `[x]` right after it passes verification. Never batch updates.
+
+When things don't match the plan exactly, think about why and communicate clearly. The plan is your guide, but your judgment matters too.
+
+If you encounter a mismatch:
+- STOP and think deeply about why the plan can't be followed
+- Present the issue clearly:
+  ```
+  Issue in Phase [N]:
+  Expected: [what the plan says]
+  Found: [actual situation]
+  Why this matters: [explanation]
+
+  How should I proceed?
+  ```
+
+## Verification Approach
+
+After implementing a phase:
+- Run the success criteria checks listed in the plan (test commands, linters, type checkers, etc.)
+- Fix any issues before proceeding
+- **Check if manual verification is needed**: Look at the plan's success criteria for the current phase.
+  - If the phase has **manual verification steps**, pause and inform the human:
+    ```
+    Phase [N] Complete - Ready for Manual Verification
+
+    Automated verification passed:
+    - [List automated checks that passed]
+
+    Please perform the manual verification steps listed in the plan:
+    - [List manual verification items from the plan]
+
+    Let me know when manual testing is complete so I can proceed to Phase [N+1].
+    ```
+  - If the phase has **only automated verification** (no manual steps), continue directly to the next phase without pausing. Just note in passing that the phase is complete and automated checks passed.
+
+Do not check off items in the manual testing steps until confirmed by the user.
+
+## If You Get Stuck
+
+When something isn't working as expected:
+- First, make sure you've read and understood all the relevant code
+- Consider if the codebase has evolved since the plan was written
+- Present the mismatch clearly and ask for guidance
+
+Use sub-agents sparingly - mainly for targeted debugging or exploring unfamiliar territory.
+
+## Resuming Work
+
+If the plan has existing checkmarks:
+- Trust that completed work is done
+- Pick up from the first unchecked item
+- Verify previous work only if something seems off
+
+Remember: You're implementing a solution, not just checking boxes. Keep the end goal in mind and maintain forward momentum.

.claude/skills/rpi-plan/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: rpi-plan
+description: Create detailed, phased implementation plans through interactive research and iteration. Use when the user explicitly asks to "create a plan", "plan the implementation", or "design an approach" for a feature, refactor, or bug fix. Do not use for quick questions or simple tasks.
+---
+
+# Implementation Plan
+
+You are tasked with creating detailed implementation plans through an interactive, iterative process. You should be skeptical, thorough, and work collaboratively with the user to produce high-quality technical specifications.
+
+## Initial Setup
+
+If the user already provided a task description, file path, or topic alongside this command, proceed directly to step 1 below. Only if no context was given, respond with:
+```
+I'll help you create a detailed implementation plan. Let me start by understanding what we're building.
+
+Please provide:
+1. A description of what you want to build or change
+2. Any relevant context, constraints, or specific requirements
+3. Pointers to related files or previous research
+
+I'll analyze this information and work with you to create a comprehensive plan.
+```
+Then wait for the user's input.
+
+## Process Steps
+
+### Step 1: Context Gathering & Initial Analysis
+
+1. **Read all mentioned files immediately and FULLY**:
+   - Any files the user referenced (docs, research, code)
+   - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
+   - **CRITICAL**: DO NOT spawn sub-tasks before reading these files yourself in the main context
+   - **NEVER** read files partially - if a file is mentioned, read it completely
+
+2. **Determine if research already exists**:
+   - If the user provided a research document (e.g. from `docs/agents/research/`), **trust it as the source of truth**. Do NOT re-research topics that the document already covers. Use its findings, file references, and architecture analysis directly as the basis for planning.
+   - **NEVER repeat or re-do research that has already been provided.** The plan phase is about turning existing research into actionable implementation steps, not about gathering information that's already available.
+   - If NO research document was provided, proceed with targeted research as described below.
+
+3. **Read the most relevant files directly into your main context**:
+   - Based on the research document and/or user input, identify the most relevant source files
+   - **Read these files yourself using the Read tool** — do NOT delegate this to sub-agents. You need these files in your own context to write an accurate plan.
+   - Focus on files that will be modified or that define interfaces/patterns you need to follow
+
+4. **Only spawn sub-agents for genuinely missing information**:
+   - Do NOT spawn sub-agents to re-discover what the research document already covers
+   - Only use sub-agents if there are specific gaps: e.g. the research doesn't cover test conventions, a specific API surface, or a file that was added after the research was written
+   - Each sub-agent should have a narrow, specific question to answer — not broad exploration
+
+5. **Analyze and verify understanding**:
+   - Cross-reference the requirements with actual code (and research document if provided)
+   - Identify any discrepancies or misunderstandings
+   - Note assumptions that need verification
+   - Determine true scope based on codebase reality
+
+6. **Present informed understanding and focused questions**:
+   ```
+   Based on the task and my research of the codebase, I understand we need to [accurate summary].
+
+   I've found that:
+   - [Current implementation detail with file:line reference]
+   - [Relevant pattern or constraint discovered]
+   - [Potential complexity or edge case identified]
+
+   Questions that my research couldn't answer:
+   - [Specific technical question that requires human judgment]
+   - [Business logic clarification]
+   - [Design preference that affects implementation]
+   ```
+
+   Only ask questions that you genuinely cannot answer through code investigation.
+
+### Step 2: Targeted Research & Discovery
+
+After getting initial clarifications:
+
+1. **If the user corrects any misunderstanding**:
+   - DO NOT just accept the correction
+   - Read the specific files/directories they mention directly into your context
+   - Only proceed once you've verified the facts yourself
+
+2. If you have a todo list, use it to track exploration progress
+
+3. **Fill in gaps — do NOT redo existing research**:
+   - If a research document was provided, identify only the specific gaps that need filling
+   - Read additional files directly when possible — only spawn sub-agents for searches where you don't know the file paths
+   - **Ask yourself before any research action: "Is this already covered by the provided research?"** If yes, skip it and use what's there.
+
+4. **Present findings and design options**:
+   ```
+   Based on my research, here's what I found:
+
+   **Current State:**
+   - [Key discovery about existing code]
+   - [Pattern or convention to follow]
+
+   **Design Options:**
+   1. [Option A] - [pros/cons]
+   2. [Option B] - [pros/cons]
+
+   **Open Questions:**
+   - [Technical uncertainty]
+   - [Design decision needed]
+
+   Which approach aligns best with your vision?
+   ```
+
+### Step 3: Plan Structure Development
+
+Once aligned on approach:
+
+1. **Create initial plan outline**:
+   ```
+   Here's my proposed plan structure:
+
+   ## Overview
+   [1-2 sentence summary]
+
+   ## Implementation Phases:
+   1. [Phase name] - [what it accomplishes]
+   2. [Phase name] - [what it accomplishes]
+   3. [Phase name] - [what it accomplishes]
+
+   Does this phasing make sense? Should I adjust the order or granularity?
+   ```
+
+2. **Get feedback on structure** before writing details
+
+### Step 4: Detailed Plan Writing
+
+After structure approval:
+
+1. **Gather metadata**:
+   - Run `python <skill_directory>/scripts/metadata.py` to get date, commit, branch, and repository info
+   - Determine the output filename: `docs/agents/plans/YYYY-MM-DD-description.md`
+     - YYYY-MM-DD is today's date
+     - description is a brief kebab-case description
+     - Example: `2025-01-08-improve-error-handling.md`
+     - The output folder (`docs/agents/plans/`) can be overridden by instructions in the project's `AGENTS.md` or `CLAUDE.md`
+
+2. **Write the plan** to `docs/agents/plans/YYYY-MM-DD-description.md`
+   - Ensure the `docs/agents/plans/` directory exists (create if needed)
+   - **Every actionable item must have a checkbox** (`- [ ]`) so progress can be tracked during implementation. This includes each change in "Changes Required" and each verification step in "Success Criteria".
+   - Use the template structure below:
+
+````markdown
+---
+date: [ISO date/time from metadata]
+git_commit: [Current commit hash from metadata]
+branch: [Current branch name from metadata]
+topic: "[Feature/Task Name]"
+tags: [plan, relevant-component-names]
+status: draft
+---
+
+# [Feature/Task Name] Implementation Plan
+
+## Overview
+
+[Brief description of what we're implementing and why]
+
+## Current State Analysis
+
+[What exists now, what's missing, key constraints discovered]
+
+## Desired End State
+
+[A specification of the desired end state after this plan is complete, and how to verify it]
+
+### UI Mockups (if applicable)
+[If the changes involve user-facing interfaces (CLI output, web UI, terminal UI, etc.), include ASCII mockups
+that visually illustrate the intended result. This helps the reader quickly grasp the change.]
+
+### Key Discoveries:
+- [Important finding with file:line reference]
+- [Pattern to follow]
+- [Constraint to work within]
+
+## What We're NOT Doing
+
+[Explicitly list out-of-scope items to prevent scope creep]
+
+## Implementation Approach
+
+[High-level strategy and reasoning]
+
+## Phase 1: [Descriptive Name]
+
+### Overview
+[What this phase accomplishes]
+
+### Changes Required:
+
+#### [ ] 1. [Component/File Group]
+**File**: `path/to/file.ext`
+**Changes**: [Summary of changes]
+
+```[language]
+// Specific code to add/modify
+```
+
+### Success Criteria:
+
+#### Automated Verification:
+- [ ] Tests pass: `[test command]`
+- [ ] Type checking passes: `[typecheck command]`
+- [ ] Linting passes: `[lint command]`
+
+#### Manual Verification:
+- [ ] Feature works as expected when tested
+- [ ] Edge case handling verified
+- [ ] No regressions in related features
+
+**Implementation Note**: After completing this phase and all automated verification passes, pause here for manual confirmation from the human before proceeding to the next phase.
+
+---
+
+## Phase 2: [Descriptive Name]
+
+[Similar structure with both automated and manual success criteria...]
+
+---
+
+## Testing Strategy
+
+### Unit Tests:
+- [What to test]
+- [Key edge cases]
+
+### Integration Tests:
+- [End-to-end scenarios]
+
+### Manual Testing Steps:
+1. [Specific step to verify feature]
+2. [Another verification step]
+
+## Performance Considerations
+
+[Any performance implications or optimizations needed]
+
+## Migration Notes
+
+[If applicable, how to handle existing data/systems]
+
+## References
+
+- [Related research or documentation]
+- [Similar implementation: file:line]
+````
+
+### Step 5: Review & Iterate
+
+1. **Present the draft plan location**:
+   ```
+   I've created the initial implementation plan at:
+   `docs/agents/plans/YYYY-MM-DD-description.md`
+
+   Please review it and let me know:
+   - Are the phases properly scoped?
+   - Are the success criteria specific enough?
+   - Any technical details that need adjustment?
+   - Missing edge cases or considerations?
+   ```
+
+2. **Iterate based on feedback** - be ready to:
+   - Add missing phases
+   - Adjust technical approach
+   - Clarify success criteria (both automated and manual)
+   - Add/remove scope items
+
+3. **Continue refining** until the user is satisfied
+
+## Important Guidelines
+
+1. **Be Skeptical**:
+   - Question vague requirements
+   - Identify potential issues early
+   - Ask "why" and "what about"
+   - Don't assume - verify with code
+
+2. **Be Interactive**:
+   - Don't write the full plan in one shot
+   - Get buy-in at each major step
+   - Allow course corrections
+   - Work collaboratively
+
+3. **Be Thorough But Not Redundant**:
+   - Read all context files COMPLETELY before planning
+   - Use provided research as-is — do not re-investigate what's already documented
+   - Read key source files directly into your context rather than delegating to sub-agents
+   - Only spawn sub-agents for narrow, specific questions that aren't answered by existing research
+   - Include specific file paths and line numbers
+   - Write measurable success criteria with clear automated vs manual distinction
+
+4. **Be Visual**:
+   - If the change involves any user-facing interface (web UI, CLI output, terminal UI, forms, dashboards, etc.), include ASCII mockups in the plan
+   - Mockups make the intended result immediately understandable and help catch misunderstandings early
+   - Show both the current state and the proposed state when the change modifies an existing UI
+   - Keep mockups simple but accurate enough to convey layout, key elements, and interactions
+
+5. **Be Practical**:
+   - Focus on incremental, testable changes
+   - Consider migration and rollback
+   - Think about edge cases
+   - Include "what we're NOT doing"
+
+6. **No Open Questions in Final Plan**:
+   - If you encounter open questions during planning, STOP
+   - Research or ask for clarification immediately
+   - Do NOT write the plan with unresolved questions
+   - The implementation plan must be complete and actionable
+   - Every decision must be made before finalizing the plan
+
+## Success Criteria Guidelines
+
+**Always separate success criteria into two categories:**
+
+1. **Automated Verification** (can be run by agents):
+   - Commands that can be run: test suites, linters, type checkers
+   - Specific files that should exist
+   - Code compilation/type checking
+
+2. **Manual Verification** (requires human testing):
+   - UI/UX functionality
+   - Performance under real conditions
+   - Edge cases that are hard to automate
+   - User acceptance criteria
+
+## Common Patterns
+
+### For Database Changes:
+- Start with schema/migration
+- Add store methods
+- Update business logic
+- Expose via API
+- Update clients
+
+### For New Features:
+- Research existing patterns first
+- Start with data model
+- Build backend logic
+- Add API endpoints
+- Implement UI last
+
+### For Refactoring:
+- Document current behavior
+- Plan incremental changes
+- Maintain backwards compatibility
+- Include migration strategy

.claude/skills/rpi-plan/scripts/metadata.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Get git metadata for plan documents."""
+
+import json
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def run(cmd: list[str]) -> str:
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    return result.stdout.strip() if result.returncode == 0 else ""
+
+
+def get_repo_name() -> str:
+    remote = run(["git", "remote", "get-url", "origin"])
+    if remote:
+        name = remote.rstrip("/").rsplit("/", 1)[-1]
+        return name.removesuffix(".git")
+    root = run(["git", "rev-parse", "--show-toplevel"])
+    return Path(root).name if root else Path.cwd().name
+
+
+def main() -> None:
+    metadata = {
+        "date": datetime.now(timezone.utc).isoformat(),
+        "commit": run(["git", "rev-parse", "HEAD"]),
+        "branch": run(["git", "branch", "--show-current"]),
+        "repository": get_repo_name(),
+    }
+    json.dump(metadata, sys.stdout, indent=2)
+    print()
+
+
+if __name__ == "__main__":
+    main()

.claude/skills/rpi-research/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: rpi-research
+description: Conduct deep codebase research and produce a written report. Use when the user explicitly requests research like "start a research for", "deeply investigate", or "fully understand how X works". Do not use for quick questions or simple code lookups.
+---
+
+# Research Codebase
+
+You are tasked with conducting comprehensive research across the codebase to answer user questions by spawning parallel sub-agents and synthesizing their findings.
+
+## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY
+- DO NOT suggest improvements or changes unless the user explicitly asks for them
+- DO NOT perform root cause analysis unless the user explicitly asks for them
+- DO NOT propose future enhancements unless the user explicitly asks for them
+- DO NOT critique the implementation or identify problems
+- DO NOT recommend refactoring, optimization, or architectural changes
+- ONLY describe what exists, where it exists, how it works, and how components interact
+- You are creating a technical map/documentation of the existing system
+
+## Initial Setup
+
+If the user already provided a research question or topic alongside this command, proceed directly to step 1 below. Only if no query was given, respond with:
+```
+I'm ready to research the codebase. Please provide your research question or area of interest, and I'll analyze it thoroughly by exploring relevant components and connections.
+```
+Then wait for the user's research query.
+
+## Steps to follow after receiving the research query:
+
+1. **Read any directly mentioned files first:**
+   - If the user mentions specific files or docs, read them FULLY first
+   - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
+   - **CRITICAL**: Read these files yourself in the main context before spawning any sub-tasks
+   - This ensures you have full context before decomposing the research
+
+2. **Analyze and decompose the research question:**
+   - Break down the user's query into composable research areas
+   - Take time to think deeply about the underlying patterns, connections, and architectural implications the user might be seeking
+   - Identify specific components, patterns, or concepts to investigate
+   - If you have a todo list, use it to track progress
+   - Consider which directories, files, or architectural patterns are relevant
+
+3. **Spawn parallel sub-agents to identify relevant files and map the landscape:**
+   - Create multiple Task agents to search for files and identify what's relevant
+   - Each sub-agent should focus on locating files and reporting back paths and brief summaries — NOT on deeply analyzing code
+   - The key is to use these agents for discovery:
+     - Search for files related to each research area
+     - Identify entry points, key types, and important functions
+     - Report back file paths, line numbers, and short descriptions of what each file contains
+     - Run multiple agents in parallel when they're searching for different things
+     - Remind agents they are documenting, not evaluating or improving
+   - **If the user explicitly asks for web research**, spawn additional agents with WebSearch/WebFetch tools and instruct them to return links with their findings
+
+4. **Read the most relevant files yourself in the main context:**
+   - After sub-agents report back, identify the most important files for answering the research question
+   - **Read these files yourself using the Read tool** — you need them in your own context to write an accurate, detailed research document
+   - Do NOT rely solely on sub-agent summaries for the core findings — sub-agent summaries may miss nuances, connections, or important details
+   - Prioritize files that are central to the research question; skip peripheral files that sub-agents already summarized adequately
+   - This is the step where you build deep understanding — the previous step was just finding what to read
+
+5. **Synthesize findings into a complete picture:**
+   - Combine your own reading with sub-agent discoveries
+   - Connect findings across different components
+   - Include specific file paths and line numbers for reference
+   - Highlight patterns, connections, and architectural decisions
+   - Answer the user's specific questions with concrete evidence
+
+6. **Gather metadata for the research document:**
+   - Run `python <skill_directory>/scripts/metadata.py` to get date, commit, branch, and repository info
+   - Determine the output filename: `docs/agents/research/YYYY-MM-DD-description.md`
+     - YYYY-MM-DD is today's date
+     - description is a brief kebab-case description of the research topic
+     - Example: `2025-01-08-authentication-flow.md`
+     - The output folder (`docs/agents/research/`) can be overridden by instructions in the project's `AGENTS.md` or `CLAUDE.md`
+
+7. **Generate research document:**
+   - Use the metadata gathered in step 5
+   - Ensure the `docs/agents/research/` directory exists (create if needed)
+   - Structure the document with YAML frontmatter followed by content:
+     ```markdown
+     ---
+     date: [ISO date/time from metadata]
+     git_commit: [Current commit hash from metadata]
+     branch: [Current branch name from metadata]
+     topic: "[User's Question/Topic]"
+     tags: [research, codebase, relevant-component-names]
+     status: complete
+     ---
+
+     # Research: [User's Question/Topic]
+
+     ## Research Question
+     [Original user query]
+
+     ## Summary
+     [High-level documentation of what was found, answering the user's question by describing what exists]
+
+     ## Detailed Findings
+
+     ### [Component/Area 1]
+     - Description of what exists (file.ext:line)
+     - How it connects to other components
+     - Current implementation details (without evaluation)
+
+     ### [Component/Area 2]
+     ...
+
+     ## Code References
+     - `path/to/file.py:123` - Description of what's there
+     - `another/file.ts:45-67` - Description of the code block
+
+     ## Architecture Documentation
+     [Current patterns, conventions, and design implementations found in the codebase]
+
+     ## Open Questions
+     [Any areas that need further investigation]
+     ```
+
+8. **Present findings to the user:**
+   - Present a concise summary of findings
+   - Include key file references for easy navigation
+   - Ask if they have follow-up questions or need clarification
+
+9. **Handle follow-up questions:**
+   - If the user has follow-up questions, append to the same research document
+   - Add a new section: `## Follow-up Research [timestamp]`
+   - Spawn new sub-agents as needed for additional investigation
+   - Continue updating the document
+
+## Important notes:
+- Use parallel sub-agents for file discovery and landscape mapping, but **read the most important files yourself** in the main context
+- Sub-agents are scouts that find relevant files — the main agent must read key files to build deep understanding
+- Do NOT rely solely on sub-agent summaries for your core findings; they may miss nuances and connections
+- Focus on finding concrete file paths and line numbers for developer reference
+- Research documents should be self-contained with all necessary context
+- Each sub-agent prompt should be specific and focused on locating files and reporting back paths
+- Document cross-component connections and how systems interact
+- **CRITICAL**: You and all sub-agents are documentarians, not evaluators
+- **REMEMBER**: Document what IS, not what SHOULD BE
+- **NO RECOMMENDATIONS**: Only describe the current state of the codebase
+- **File reading**: Always read mentioned files FULLY (no limit/offset) before spawning sub-tasks
+- **Critical ordering**: Follow the numbered steps exactly
+  - ALWAYS read mentioned files first before spawning sub-tasks (step 1)
+  - ALWAYS read key files yourself after sub-agents report back (step 4)
+  - ALWAYS wait for your own reading to complete before synthesizing (step 5)
+  - ALWAYS gather metadata before writing the document (step 6 before step 7)
+  - NEVER write the research document with placeholder values

.claude/skills/rpi-research/scripts/metadata.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Get git metadata for research documents."""
+
+import json
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def run(cmd: list[str]) -> str:
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    return result.stdout.strip() if result.returncode == 0 else ""
+
+
+def get_repo_name() -> str:
+    remote = run(["git", "remote", "get-url", "origin"])
+    if remote:
+        # Handle both HTTPS and SSH URLs
+        name = remote.rstrip("/").rsplit("/", 1)[-1]
+        return name.removesuffix(".git")
+    # Fall back to directory name
+    root = run(["git", "rev-parse", "--show-toplevel"])
+    return Path(root).name if root else Path.cwd().name
+
+
+def main() -> None:
+    metadata = {
+        "date": datetime.now(timezone.utc).isoformat(),
+        "commit": run(["git", "rev-parse", "HEAD"]),
+        "branch": run(["git", "branch", "--show-current"]),
+        "repository": get_repo_name(),
+    }
+    json.dump(metadata, sys.stdout, indent=2)
+    print()
+
+
+if __name__ == "__main__":
+    main()

.dockerignore

@@ -0,0 +1,9 @@
+node_modules
+.pnpm-store
+dist
+coverage
+.git
+.claude
+.specify
+specs
+docs

.gitea/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm check
+
+  build-image:
+    if: startsWith(github.ref, 'refs/tags/')
+    needs: check
+    runs-on: host
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Log in to Gitea registry
+        run: echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login git.bahamut.nitrix.one -u "${{ secrets.REGISTRY_USERNAME }}" --password-stdin
+
+      - name: Build and push
+        run: |
+          IMAGE=git.bahamut.nitrix.one/dostulata/initiative
+          TAG=${GITHUB_REF#refs/tags/}
+          docker build -t $IMAGE:$TAG -t $IMAGE:latest .
+          docker push $IMAGE:$TAG
+          docker push $IMAGE:latest
+
+      - name: Deploy
+        run: |
+          IMAGE=git.bahamut.nitrix.one/dostulata/initiative
+          TAG=${GITHUB_REF#refs/tags/}
+          docker stop initiative || true
+          docker rm initiative || true
+          docker run -d --name initiative --restart unless-stopped -p 8080:80 $IMAGE:$TAG

.jscpd.json

@@ -0,0 +1,8 @@
+{
+	"threshold": 5,
+	"minLines": 5,
+	"minTokens": 50,
+	"pattern": ["**/*.ts", "**/*.tsx"],
+	"ignore": ["node_modules", "dist", "build", "coverage", ".specify", "specs"],
+	"reporters": ["console"]
+}

.specify/memory/constitution.md

@@ -1,14 +1,10 @@
 <!--
   Sync Impact Report
   ───────────────────
-  Version change: 1.0.2 → 1.0.3 (PATCH — add merge-gate rule)
+  Version change: 2.2.1 → 3.0.0 (MAJOR — specs describe features not changes, proportional workflow)
   Modified sections:
-    - Development Workflow: added automated-checks merge gate
-  Templates requiring updates:
-    - .specify/templates/plan-template.md        ✅ no update needed
-    - .specify/templates/spec-template.md         ✅ no update needed
-    - .specify/templates/tasks-template.md        ✅ no update needed
-  Follow-up TODOs: none
+    - Development Workflow: specs are living feature documents; full pipeline for new features only
+  Templates requiring updates: none
 -->
 # Encounter Console Constitution
 
@@ -29,7 +25,7 @@ be injected at the boundary, never sourced inside the domain layer.
 
 ### II. Layered Architecture
 
-The codebase MUST be organized into four layers with strict
+The codebase MUST be organized into three layers with strict
 dependency direction:
 
 1. **Domain** — pure types, state transitions, validation rules.
@@ -39,34 +35,21 @@ dependency direction:
    interfaces that Adapters implement. May import Domain only.
 3. **Adapters** — I/O, persistence, UI rendering, external APIs.
    May import Application and Domain.
-4. **Agent** — AI-assisted features (suggestions, analysis).
-   May import Application and Domain as read-only consumers.
 
 A module in an inner layer MUST NOT import from an outer layer.
 
-### III. Agent Boundary
-
-The agent layer MAY read domain events and current state. The agent
-MAY produce suggestions, annotations, or recommendations. The agent
-MUST NOT mutate domain state directly. All agent-originated changes
-MUST flow through the Application layer as explicit user-confirmed
-commands.
-
-- Agent output MUST be clearly labeled as suggestions.
-- No silent or automatic application of agent recommendations.
-
-### IV. Clarification-First
+### III. Clarification-First
 
 Before making any non-trivial assumption during specification,
-planning, or implementation, the agent MUST surface a clarification
+planning, or implementation, Claude Code MUST surface a clarification
 question to the user. "Non-trivial" means any decision that would
 alter observable behavior, data model shape, or public API surface.
-The agent MUST also ask when multiple valid interpretations exist,
+Claude Code MUST also ask when multiple valid interpretations exist,
 when a choice would affect architectural layering, or when scope
-would expand beyond the current spec. The agent MUST NOT silently
+would expand beyond the current spec. Claude Code MUST NOT silently
 choose among valid alternatives.
 
-### V. Escalation Gates
+### IV. Escalation Gates
 
 Any feature, requirement, or scope change not present in the current
 spec MUST be rejected at implementation time until the spec is
@@ -77,7 +60,7 @@ explicitly updated. The workflow is:
 3. Update the spec via `/speckit.specify` or `/speckit.clarify`.
 4. Only then proceed with implementation.
 
-### VI. MVP Baseline Language
+### V. MVP Baseline Language
 
 Constraints in this constitution and in specs MUST use MVP baseline
 language ("MVP baseline does not include X") rather than permanent
@@ -86,7 +69,7 @@ add capabilities in future iterations without constitutional
 amendment. The current MVP baseline is local-first and single-user;
 this is a starting scope, not a permanent restriction.
 
-### VII. No Gameplay Rules in Constitution
+### VI. No Gameplay Rules in Constitution
 
 This constitution MUST NOT contain concrete gameplay mechanics,
 rule-system specifics, or encounter resolution logic. Such details
@@ -96,9 +79,9 @@ architecture, and quality — not product behavior.
 ## Scope Constraints
 
 - The Encounter Console's primary focus is initiative tracking and
-  encounter state management. Adjacent capabilities (e.g., richer
-  game-engine features) are not in the MVP baseline but may be
-  added via spec updates in future iterations.
+  encounter state management. Adjacent capabilities (e.g., bestiary
+  integration, richer game-engine features) may be added via spec
+  updates.
 - Technology choices, UI framework, and storage mechanism are
   spec-level decisions, not constitutional mandates.
 - Testing strategy (unit, integration, contract) is determined per
@@ -109,16 +92,31 @@ architecture, and quality — not product behavior.
 
 - No change may be merged unless all automated checks (tests and
   static analysis as defined by the project) pass.
-- Every feature begins with a spec (`/speckit.specify`).
-- Implementation follows the plan → tasks → implement pipeline.
+- Specs describe **features**, not individual changes. Each spec is
+  a living document. New features begin with `/speckit.specify`
+  (which creates a feature branch for the full speckit pipeline);
+  changes to existing features update the existing spec via
+  `/integrate-issue`.
+- The full pipeline (spec → plan → tasks → implement) applies to new
+  features and significant additions. Bug fixes, tooling changes,
+  and trivial UI adjustments do not require specs.
 - Domain logic MUST be testable without mocks for external systems.
 - Long-running or multi-step state transitions SHOULD be verifiable
   through reproducible event logs or snapshot-style tests.
 - Commits SHOULD be atomic and map to individual tasks where
   practical.
 - Layer boundary compliance MUST be verified by automated import
-  rules or architectural tests. Agent-assisted or manual review MAY
-  supplement but not replace automated checks.
+  rules or architectural tests.
+- All automated quality gates MUST run at the earliest feasible
+  enforcement point (currently pre-commit via Lefthook). No gate
+  may exist only as a CI step or manual process.
+- When a feature adds, removes, or changes user-facing capabilities
+  described in README.md, the README MUST be updated in the same
+  change. Features that materially alter what the product does or
+  how it is set up SHOULD also be reflected in the README.
+- When a feature changes the tech stack, project structure, or
+  architectural patterns documented in CLAUDE.md, the CLAUDE.md
+  MUST be updated in the same change.
 
 ## Governance
 
@@ -142,4 +140,4 @@ MUST comply with its principles.
 **Compliance review**: Every spec and plan MUST include a
 Constitution Check section validating adherence to all principles.
 
-**Version**: 1.0.3 | **Ratified**: 2026-03-03 | **Last Amended**: 2026-03-03
+**Version**: 3.0.0 | **Ratified**: 2026-03-03 | **Last Amended**: 2026-03-11

.specify/scripts/bash/check-prerequisites.sh

@@ -122,6 +122,10 @@ fi
 # Build list of available documents
 docs=()
 
+# Include required docs that passed validation above
+[[ -f "$FEATURE_SPEC" ]] && docs+=("spec.md")
+[[ -f "$IMPL_PLAN" ]] && docs+=("plan.md")
+
 # Always check these optional docs
 [[ -f "$RESEARCH" ]] && docs+=("research.md")
 [[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")

CLAUDE.md

@@ -5,7 +5,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Commands
 
 ```bash
-pnpm check              # Merge gate — must pass before every commit (knip + format + lint + typecheck + test)
+pnpm check              # Merge gate — must pass before every commit (audit + knip + biome + typecheck + test/coverage + jscpd)
 pnpm knip               # Unused code detection (Knip)
 pnpm test               # Run all tests (Vitest)
 pnpm test:watch         # Tests in watch mode
@@ -27,11 +27,40 @@ apps/web (React 19 + Vite)  →  packages/application (use cases)  →  packages
 ```
 
 - **Domain** — Pure functions, no I/O, no framework imports. All state transitions are deterministic. Errors returned as values (`DomainError`), never thrown. Adapters may throw only for programmer errors.
-- **Application** — Orchestrates domain calls via port interfaces (e.g., `EncounterStore`). No business logic here.
-- **Web** — React adapter. Implements ports using hooks/state.
+- **Application** — Orchestrates domain calls via port interfaces (`EncounterStore`, `BestiarySourceCache`). No business logic here.
+- **Web** — React adapter. Implements ports using hooks/state. All UI components, routing, and user interaction live here.
 
 Layer boundaries are enforced by `scripts/check-layer-boundaries.mjs`, which runs as a Vitest test. Domain and application must never import from React, Vite, or upper layers.
 
+### Data & Storage
+
+- **localStorage** — encounter persistence (adapter layer, JSON serialization)
+- **IndexedDB** — bestiary source cache (`apps/web/src/adapters/bestiary-cache.ts`, via `idb` wrapper)
+- **`data/bestiary/index.json`** — pre-built search index for creature lookup, generated by `scripts/generate-bestiary-index.mjs`
+
+### Project Structure
+
+```
+apps/web/                  React app — components, hooks, adapters
+packages/domain/src/       Pure state transitions, types, validation
+packages/application/src/  Use cases, port interfaces
+data/bestiary/             Bestiary search index
+scripts/                   Build tooling (layer checks, index generation)
+specs/NNN-feature-name/    Feature specs (spec.md, plan.md, tasks.md)
+.specify/                  Speckit config (templates, scripts, constitution)
+docs/agents/               RPI skill artifacts (research reports, plans)
+.claude/skills/            Agent skills (rpi-research, rpi-plan, rpi-implement)
+```
+
+## Tech Stack
+
+- TypeScript 5.8 (strict mode, `verbatimModuleSyntax`)
+- React 19, Vite 6, Tailwind CSS v4
+- Lucide React (icons)
+- `idb` (IndexedDB wrapper for bestiary cache)
+- Biome 2.0 (formatting + linting), Knip (unused code), jscpd (copy-paste detection)
+- Vitest (testing, v8 coverage), Lefthook (pre-commit hooks)
+
 ## Conventions
 
 - **Biome 2.0** for formatting and linting (no Prettier, no ESLint). Tab indentation, 80-char lines. Imports are auto-organized alphabetically.
@@ -39,7 +68,40 @@ Layer boundaries are enforced by `scripts/check-layer-boundaries.mjs`, which run
 - **Branded types** for identity values (e.g., `CombatantId`). Prefer immutability/`readonly` where practical.
 - **Domain events** are plain data objects with a `type` discriminant — no classes.
 - **Tests** live in `packages/*/src/__tests__/*.test.ts`. Test pure functions directly; map acceptance scenarios and invariants from specs to individual `it()` blocks.
-- **Feature specs** live in `specs/<feature>/` with spec.md, plan.md, tasks.md. The project constitution is at `.specify/memory/constitution.md`.
+- **Feature specs** live in `specs/NNN-feature-name/` with spec.md (and optionally plan.md, tasks.md for new work). Specs describe features, not individual changes. The project constitution is at `.specify/memory/constitution.md`.
+- **Quality gates** are enforced at pre-commit via Lefthook's `pnpm check` — the project's single earliest enforcement point. No gate may exist only as a CI step or manual process.
+
+## Speckit Workflow
+
+Speckit (`/speckit.*` skills) manages the spec-driven development pipeline. Specs are **living documents** that describe features, not individual changes.
+
+### Issue-driven workflow
+- `/write-issue` — create a well-structured Gitea issue via interactive interview
+- `/integrate-issue <number>` — fetch an issue, route it to the right spec, and update the spec with the new/changed requirements. Then implement directly.
+- `/sync-issue <number>` — push acceptance criteria from the spec back to the Gitea issue
+
+### RPI skills (Research → Plan → Implement)
+- `rpi-research` — deep codebase research producing a written report in `docs/agents/research/`
+- `rpi-plan` — interactive phased implementation plan in `docs/agents/plans/`
+- `rpi-implement` — execute a plan file phase by phase with automated + manual verification
+
+### Choosing the right workflow by scope
+
+| Scope | Workflow |
+|---|---|
+| Bug fix / CSS tweak | Just fix it, commit |
+| Small change to existing feature | `/integrate-issue` → implement → commit |
+| Larger addition to existing feature | `/integrate-issue` → `rpi-research` → `rpi-plan` → `rpi-implement` |
+| New feature | `/speckit.specify` → `/speckit.clarify` → `/speckit.plan` → `/speckit.tasks` → `/speckit.implement` |
+
+Speckit manages **what** to build (specs as living documents). RPI manages **how** to build it (research, planning, execution). The full speckit pipeline is for new features. For changes to existing features, update the spec via `/integrate-issue`, then use RPI skills if the change is non-trivial.
+
+### Current feature specs
+- `specs/001-combatant-management/` — CRUD, persistence, clear, batch add, confirm buttons
+- `specs/002-turn-tracking/` — rounds, turn order, advance/retreat, top bar
+- `specs/003-combatant-state/` — HP, AC, conditions, concentration, initiative
+- `specs/004-bestiary/` — search index, stat blocks, source management, panel UX
+- `specs/005-player-characters/` — persistent player character templates (CRUD), search & add to encounters, color/icon visual distinction, `PlayerCharacterStore` port
 
 ## Constitution (key principles)
 
@@ -49,13 +111,11 @@ The constitution (`.specify/memory/constitution.md`) governs all feature work:
 2. **Layered Architecture** — Domain → Application → Adapters. Never skip layers or reverse dependencies.
 3. **Clarification-First** — Ask before making non-trivial assumptions.
 4. **MVP Baseline** — Say "MVP baseline does not include X", never permanent bans.
-5. **Every feature begins with a spec** — Spec → Plan → Tasks → Implementation.
+5. **Spec-driven features** — Features are described in living specs; evolve existing specs via `/integrate-issue`, create new ones via `/speckit.specify`. Bug fixes and tooling changes do not require specs.
 
 ## Active Technologies
-- TypeScript 5.x (strict mode, verbatimModuleSyntax) + React 19, Vite (003-remove-combatant)
-- In-memory React state (local-first, single-user MVP) (003-remove-combatant)
-- TypeScript 5.x (project), Go binary via npm (Lefthook) + `lefthook` (npm devDependency) (006-pre-commit-gate)
-- TypeScript 5.x (strict mode, verbatimModuleSyntax) + Knip v5 (new), Biome 2.0, Vitest, Vite 6, React 19 (007-add-knip)
+- TypeScript 5.8 (strict mode, `verbatimModuleSyntax`) + React 19, Vite 6, Tailwind CSS v4, Lucide Reac (005-player-characters)
+- localStorage (new key `"initiative:player-characters"`) (005-player-characters)
 
 ## Recent Changes
-- 003-remove-combatant: Added TypeScript 5.x (strict mode, verbatimModuleSyntax) + React 19, Vite
+- 005-player-characters: Added TypeScript 5.8 (strict mode, `verbatimModuleSyntax`) + React 19, Vite 6, Tailwind CSS v4, Lucide Reac

Dockerfile

@@ -0,0 +1,19 @@
+FROM node:22-slim AS build
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
+RUN corepack enable
+
+WORKDIR /app
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY packages/domain/package.json packages/domain/
+COPY packages/application/package.json packages/application/
+COPY apps/web/package.json apps/web/
+RUN pnpm install --frozen-lockfile --ignore-scripts
+
+COPY . .
+RUN pnpm --filter web build
+
+FROM nginx:alpine
+COPY --from=build /app/apps/web/dist /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+EXPOSE 80

README.md

@@ -1,10 +1,18 @@
-# Initiative Tracker
+# Encounter Console
 
-A turn-based initiative tracker for tabletop RPG encounters. Click "Next Turn" to cycle through combatants and advance rounds.
+A local-first initiative tracker and encounter manager for tabletop RPGs (D&D 5e / 2024). Runs entirely in the browser — no server, no account, no data leaves your machine.
+
+## What it does
+
+- **Initiative tracking** — add combatants (batch-add from bestiary, custom creatures with optional stats), roll initiative (manual or d20), cycle turns and rounds
+- **Encounter state** — HP, AC, conditions, concentration tracking with visual status indicators
+- **Bestiary integration** — import bestiary JSON sources, search creatures, and view full stat blocks
+- **Player characters** — create reusable player character templates with name, AC, HP, color, and icon; search and add them to encounters with pre-filled stats; manage (edit/delete) from a dedicated panel
+- **Persistent** — encounters survive page reloads via localStorage; bestiary data cached in IndexedDB; player characters stored independently
 
 ## Prerequisites
 
-- Node.js 22
+- Node.js 22+
 - pnpm 10.6+
 
 ## Getting Started
@@ -14,9 +22,7 @@ pnpm install
 pnpm --filter web dev
 ```
 
-Open the URL printed in your terminal (typically `http://localhost:5173`).
-
-The app starts with a 3-combatant demo encounter (Aria, Brak, Cael). Click **Next Turn** to advance through the initiative order. When the last combatant finishes their turn, the round number increments and the cycle restarts.
+Open `http://localhost:5173`.
 
 ## Scripts
 
@@ -24,5 +30,27 @@ The app starts with a 3-combatant demo encounter (Aria, Brak, Cael). Click **Nex
 |---------|-------------|
 | `pnpm --filter web dev` | Start the dev server |
 | `pnpm --filter web build` | Production build |
-| `pnpm test` | Run all tests |
-| `pnpm check` | Full merge gate (format, lint, typecheck, test) |
+| `pnpm test` | Run all tests (Vitest) |
+| `pnpm check` | Full merge gate (knip, biome, typecheck, test, jscpd) |
+
+## Project Structure
+
+```
+apps/web/          React 19 + Vite — UI components, hooks, adapters
+packages/domain/   Pure functions — state transitions, types, validation
+packages/app/      Use cases — orchestrates domain via port interfaces
+data/bestiary/     Bestiary index for creature search
+scripts/           Build tooling (layer boundary checks, index generation)
+specs/             Feature specifications (spec → plan → tasks)
+```
+
+## Architecture
+
+Strict layered architecture with enforced dependency direction:
+
+```
+apps/web (adapters)  →  packages/application (use cases)  →  packages/domain (pure logic)
+```
+
+Domain is pure — no I/O, no randomness, no framework imports. Layer boundaries are enforced by automated import checks that run as part of the test suite. See [CLAUDE.md](./CLAUDE.md) for full conventions.
+

apps/web/package.json

@@ -11,13 +11,23 @@
 	"dependencies": {
 		"@initiative/application": "workspace:*",
 		"@initiative/domain": "workspace:*",
+		"class-variance-authority": "^0.7.1",
+		"clsx": "^2.1.1",
+		"idb": "^8.0.3",
+		"lucide-react": "^0.577.0",
 		"react": "^19.0.0",
-		"react-dom": "^19.0.0"
+		"react-dom": "^19.0.0",
+		"tailwind-merge": "^3.5.0"
 	},
 	"devDependencies": {
+		"@tailwindcss/vite": "^4.2.1",
+		"@testing-library/jest-dom": "^6.9.1",
+		"@testing-library/react": "^16.3.2",
 		"@types/react": "^19.0.0",
 		"@types/react-dom": "^19.0.0",
 		"@vitejs/plugin-react": "^4.3.0",
+		"jsdom": "^28.1.0",
+		"tailwindcss": "^4.2.1",
 		"vite": "^6.2.0"
 	}
 }

apps/web/src/App.tsx

@@ -1,163 +1,462 @@
-import type { CombatantId } from "@initiative/domain";
-import { type FormEvent, useCallback, useRef, useState } from "react";
+import {
+	rollAllInitiativeUseCase,
+	rollInitiativeUseCase,
+} from "@initiative/application";
+import type { CombatantId, Creature, CreatureId } from "@initiative/domain";
+import {
+	useCallback,
+	useEffect,
+	useLayoutEffect,
+	useRef,
+	useState,
+} from "react";
+import { ActionBar } from "./components/action-bar";
+import { CombatantRow } from "./components/combatant-row";
+import { CreatePlayerModal } from "./components/create-player-modal";
+import { PlayerManagement } from "./components/player-management";
+import { SourceManager } from "./components/source-manager";
+import { StatBlockPanel } from "./components/stat-block-panel";
+import { Toast } from "./components/toast";
+import { TurnNavigation } from "./components/turn-navigation";
+import { type SearchResult, useBestiary } from "./hooks/use-bestiary";
+import { useBulkImport } from "./hooks/use-bulk-import";
 import { useEncounter } from "./hooks/use-encounter";
+import { usePlayerCharacters } from "./hooks/use-player-characters";
 
-function formatEvent(e: ReturnType<typeof useEncounter>["events"][number]) {
-	switch (e.type) {
-		case "TurnAdvanced":
-			return `Turn: ${e.previousCombatantId} → ${e.newCombatantId} (round ${e.roundNumber})`;
-		case "RoundAdvanced":
-			return `Round advanced to ${e.newRoundNumber}`;
-		case "CombatantAdded":
-			return `Added combatant: ${e.name}`;
-		case "CombatantRemoved":
-			return `Removed combatant: ${e.name}`;
-		case "CombatantUpdated":
-			return `Renamed combatant: ${e.oldName} → ${e.newName}`;
-		case "InitiativeSet":
-			return `Initiative: ${e.combatantId} ${e.previousValue ?? "unset"} → ${e.newValue ?? "unset"}`;
-	}
+function rollDice(): number {
+	return Math.floor(Math.random() * 20) + 1;
 }
 
-function EditableName({
-	name,
-	combatantId,
-	isActive,
-	onRename,
-}: {
-	name: string;
-	combatantId: CombatantId;
-	isActive: boolean;
-	onRename: (id: CombatantId, newName: string) => void;
-}) {
-	const [editing, setEditing] = useState(false);
-	const [draft, setDraft] = useState(name);
-	const inputRef = useRef<HTMLInputElement>(null);
+function useActionBarAnimation(combatantCount: number) {
+	const wasEmptyRef = useRef(combatantCount === 0);
+	const [settling, setSettling] = useState(false);
+	const [rising, setRising] = useState(false);
+	const [topBarExiting, setTopBarExiting] = useState(false);
 
-	const commit = useCallback(() => {
-		const trimmed = draft.trim();
-		if (trimmed !== "" && trimmed !== name) {
-			onRename(combatantId, trimmed);
+	useLayoutEffect(() => {
+		const nowEmpty = combatantCount === 0;
+		if (wasEmptyRef.current && !nowEmpty) {
+			setSettling(true);
+		} else if (!wasEmptyRef.current && nowEmpty) {
+			setRising(true);
+			setTopBarExiting(true);
 		}
-		setEditing(false);
-	}, [draft, name, combatantId, onRename]);
+		wasEmptyRef.current = nowEmpty;
+	}, [combatantCount]);
 
-	const startEditing = useCallback(() => {
-		setDraft(name);
-		setEditing(true);
-		requestAnimationFrame(() => inputRef.current?.select());
-	}, [name]);
+	const empty = combatantCount === 0;
+	const risingClass = rising ? " animate-rise-to-center" : "";
+	const settlingClass = settling ? " animate-settle-to-bottom" : "";
+	const topBarClass = settling
+		? " animate-slide-down-in"
+		: topBarExiting
+			? " absolute inset-x-0 top-0 z-10 px-4 animate-slide-up-out"
+			: "";
+	const showTopBar = !empty || topBarExiting;
 
-	if (editing) {
-		return (
-			<input
-				ref={inputRef}
-				type="text"
-				value={draft}
-				onChange={(e) => setDraft(e.target.value)}
-				onBlur={commit}
-				onKeyDown={(e) => {
-					if (e.key === "Enter") commit();
-					if (e.key === "Escape") setEditing(false);
-				}}
-			/>
-		);
-	}
-
-	return (
-		<button type="button" onClick={startEditing}>
-			{isActive ? `▶ ${name}` : name}
-		</button>
-	);
+	return {
+		risingClass,
+		settlingClass,
+		topBarClass,
+		showTopBar,
+		onSettleEnd: () => setSettling(false),
+		onRiseEnd: () => setRising(false),
+		onTopBarExitEnd: () => setTopBarExiting(false),
+	};
 }
 
 export function App() {
 	const {
 		encounter,
-		events,
 		advanceTurn,
+		retreatTurn,
 		addCombatant,
+		clearEncounter,
 		removeCombatant,
 		editCombatant,
 		setInitiative,
+		setHp,
+		adjustHp,
+		setAc,
+		toggleCondition,
+		toggleConcentration,
+		addFromBestiary,
+		addFromPlayerCharacter,
+		makeStore,
 	} = useEncounter();
-	const activeCombatant = encounter.combatants[encounter.activeIndex];
-	const [nameInput, setNameInput] = useState("");
 
-	const handleAdd = (e: FormEvent) => {
-		e.preventDefault();
-		if (nameInput.trim() === "") return;
-		addCombatant(nameInput);
-		setNameInput("");
-	};
+	const {
+		characters: playerCharacters,
+		createCharacter: createPlayerCharacter,
+		editCharacter: editPlayerCharacter,
+		deleteCharacter: deletePlayerCharacter,
+	} = usePlayerCharacters();
+
+	const [createPlayerOpen, setCreatePlayerOpen] = useState(false);
+	const [managementOpen, setManagementOpen] = useState(false);
+	const [editingPlayer, setEditingPlayer] = useState<
+		(typeof playerCharacters)[number] | undefined
+	>(undefined);
+
+	const {
+		search,
+		getCreature,
+		isLoaded,
+		isSourceCached,
+		fetchAndCacheSource,
+		uploadAndCacheSource,
+		refreshCache,
+	} = useBestiary();
+
+	const bulkImport = useBulkImport();
+
+	const [selectedCreatureId, setSelectedCreatureId] =
+		useState<CreatureId | null>(null);
+	const [bulkImportMode, setBulkImportMode] = useState(false);
+	const [sourceManagerOpen, setSourceManagerOpen] = useState(false);
+	const [isRightPanelFolded, setIsRightPanelFolded] = useState(false);
+	const [pinnedCreatureId, setPinnedCreatureId] = useState<CreatureId | null>(
+		null,
+	);
+	const [isWideDesktop, setIsWideDesktop] = useState(
+		() => window.matchMedia("(min-width: 1280px)").matches,
+	);
+
+	useEffect(() => {
+		const mq = window.matchMedia("(min-width: 1280px)");
+		const handler = (e: MediaQueryListEvent) => setIsWideDesktop(e.matches);
+		mq.addEventListener("change", handler);
+		return () => mq.removeEventListener("change", handler);
+	}, []);
+
+	const selectedCreature: Creature | null = selectedCreatureId
+		? (getCreature(selectedCreatureId) ?? null)
+		: null;
+
+	const pinnedCreature: Creature | null = pinnedCreatureId
+		? (getCreature(pinnedCreatureId) ?? null)
+		: null;
+
+	const handleAddFromBestiary = useCallback(
+		(result: SearchResult) => {
+			addFromBestiary(result);
+		},
+		[addFromBestiary],
+	);
+
+	const handleCombatantStatBlock = useCallback((creatureId: string) => {
+		setSelectedCreatureId(creatureId as CreatureId);
+		setIsRightPanelFolded(false);
+	}, []);
+
+	const handleRollInitiative = useCallback(
+		(id: CombatantId) => {
+			rollInitiativeUseCase(makeStore(), id, rollDice(), getCreature);
+		},
+		[makeStore, getCreature],
+	);
+
+	const handleRollAllInitiative = useCallback(() => {
+		rollAllInitiativeUseCase(makeStore(), rollDice, getCreature);
+	}, [makeStore, getCreature]);
+
+	const handleViewStatBlock = useCallback((result: SearchResult) => {
+		const slug = result.name
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, "-")
+			.replace(/(^-|-$)/g, "");
+		const cId = `${result.source.toLowerCase()}:${slug}` as CreatureId;
+		setSelectedCreatureId(cId);
+		setIsRightPanelFolded(false);
+	}, []);
+
+	const handleBulkImport = useCallback(() => {
+		setBulkImportMode(true);
+		setSelectedCreatureId(null);
+	}, []);
+
+	const handleStartBulkImport = useCallback(
+		(baseUrl: string) => {
+			bulkImport.startImport(
+				baseUrl,
+				fetchAndCacheSource,
+				isSourceCached,
+				refreshCache,
+			);
+		},
+		[bulkImport.startImport, fetchAndCacheSource, isSourceCached, refreshCache],
+	);
+
+	const handleBulkImportDone = useCallback(() => {
+		setBulkImportMode(false);
+		bulkImport.reset();
+	}, [bulkImport.reset]);
+
+	const handleDismissBrowsePanel = useCallback(() => {
+		setSelectedCreatureId(null);
+		setBulkImportMode(false);
+	}, []);
+
+	const handleToggleFold = useCallback(() => {
+		setIsRightPanelFolded((f) => !f);
+	}, []);
+
+	const handlePin = useCallback(() => {
+		if (selectedCreatureId) {
+			setPinnedCreatureId((prev) =>
+				prev === selectedCreatureId ? null : selectedCreatureId,
+			);
+		}
+	}, [selectedCreatureId]);
+
+	const handleUnpin = useCallback(() => {
+		setPinnedCreatureId(null);
+	}, []);
+
+	const actionBarInputRef = useRef<HTMLInputElement>(null);
+	const actionBarAnim = useActionBarAnimation(encounter.combatants.length);
+
+	// Auto-scroll to the active combatant when the turn changes
+	const activeRowRef = useRef<HTMLDivElement>(null);
+	useEffect(() => {
+		activeRowRef.current?.scrollIntoView({
+			block: "nearest",
+			behavior: "smooth",
+		});
+	}, [encounter.activeIndex]);
+
+	// Auto-show stat block for the active combatant when turn changes,
+	// but only when the viewport is wide enough to show it alongside the tracker.
+	// Only react to activeIndex changes — not combatant reordering (e.g. Roll All).
+	const prevActiveIndexRef = useRef(encounter.activeIndex);
+	useEffect(() => {
+		if (prevActiveIndexRef.current === encounter.activeIndex) return;
+		prevActiveIndexRef.current = encounter.activeIndex;
+		if (!window.matchMedia("(min-width: 1024px)").matches) return;
+		const active = encounter.combatants[encounter.activeIndex];
+		if (!active?.creatureId || !isLoaded) return;
+		setSelectedCreatureId(active.creatureId as CreatureId);
+	}, [encounter.activeIndex, encounter.combatants, isLoaded]);
+
+	const isEmpty = encounter.combatants.length === 0;
+	const showRollAllInitiative = encounter.combatants.some(
+		(c) => c.creatureId != null && c.initiative == null,
+	);
 
 	return (
-		<div>
-			<h1>Initiative Tracker</h1>
+		<div className="flex h-screen flex-col">
+			<div className="relative mx-auto flex w-full max-w-2xl flex-1 flex-col gap-3 px-4 min-h-0">
+				{actionBarAnim.showTopBar && (
+					<div
+						className={`shrink-0 pt-8${actionBarAnim.topBarClass}`}
+						onAnimationEnd={actionBarAnim.onTopBarExitEnd}
+					>
+						<TurnNavigation
+							encounter={encounter}
+							onAdvanceTurn={advanceTurn}
+							onRetreatTurn={retreatTurn}
+							onClearEncounter={clearEncounter}
+						/>
+					</div>
+				)}
 
-			{activeCombatant && (
-				<p>
-					Round {encounter.roundNumber} — Current: {activeCombatant.name}
-				</p>
-			)}
+				{isEmpty ? (
+					/* Empty state — ActionBar centered */
+					<div className="flex flex-1 items-center justify-center min-h-0 pb-[15%] pt-8">
+						<div
+							className={`w-full${actionBarAnim.risingClass}`}
+							onAnimationEnd={actionBarAnim.onRiseEnd}
+						>
+							<ActionBar
+								onAddCombatant={addCombatant}
+								onAddFromBestiary={handleAddFromBestiary}
+								bestiarySearch={search}
+								bestiaryLoaded={isLoaded}
+								onViewStatBlock={handleViewStatBlock}
+								onBulkImport={handleBulkImport}
+								bulkImportDisabled={bulkImport.state.status === "loading"}
+								inputRef={actionBarInputRef}
+								playerCharacters={playerCharacters}
+								onAddFromPlayerCharacter={addFromPlayerCharacter}
+								onManagePlayers={() => setManagementOpen(true)}
+								onRollAllInitiative={handleRollAllInitiative}
+								showRollAllInitiative={showRollAllInitiative}
+								onOpenSourceManager={() => setSourceManagerOpen((o) => !o)}
+								autoFocus
+							/>
+						</div>
+					</div>
+				) : (
+					<>
+						{sourceManagerOpen && (
+							<div className="shrink-0 rounded-md border border-border bg-card px-4 py-3">
+								<SourceManager onCacheCleared={refreshCache} />
+							</div>
+						)}
 
-			<ul>
-				{encounter.combatants.map((c, i) => (
-					<li key={c.id}>
-						<EditableName
-							name={c.name}
-							combatantId={c.id}
-							isActive={i === encounter.activeIndex}
-							onRename={editCombatant}
-						/>{" "}
-						<input
-							type="number"
-							value={c.initiative ?? ""}
-							placeholder="Init"
-							style={{ width: "4em" }}
-							onChange={(e) => {
-								const raw = e.target.value;
-								if (raw === "") {
-									setInitiative(c.id, undefined);
-								} else {
-									const n = Number.parseInt(raw, 10);
-									if (!Number.isNaN(n)) {
-										setInitiative(c.id, n);
-									}
-								}
-							}}
-						/>{" "}
-						<button type="button" onClick={() => removeCombatant(c.id)}>
-							Remove
-						</button>
-					</li>
-				))}
-			</ul>
+						{/* Scrollable area — combatant list */}
+						<div className="flex-1 overflow-y-auto min-h-0">
+							<div className="flex flex-col px-2 py-2">
+								{encounter.combatants.map((c, i) => (
+									<CombatantRow
+										key={c.id}
+										ref={i === encounter.activeIndex ? activeRowRef : null}
+										combatant={c}
+										isActive={i === encounter.activeIndex}
+										onRename={editCombatant}
+										onSetInitiative={setInitiative}
+										onRemove={removeCombatant}
+										onSetHp={setHp}
+										onAdjustHp={adjustHp}
+										onSetAc={setAc}
+										onToggleCondition={toggleCondition}
+										onToggleConcentration={toggleConcentration}
+										onShowStatBlock={
+											c.creatureId
+												? () => handleCombatantStatBlock(c.creatureId as string)
+												: undefined
+										}
+										onRollInitiative={
+											c.creatureId ? handleRollInitiative : undefined
+										}
+									/>
+								))}
+							</div>
+						</div>
 
-			<form onSubmit={handleAdd}>
-				<input
-					type="text"
-					value={nameInput}
-					onChange={(e) => setNameInput(e.target.value)}
-					placeholder="Combatant name"
+						{/* Action Bar — fixed at bottom */}
+						<div
+							className={`shrink-0 pb-8${actionBarAnim.settlingClass}`}
+							onAnimationEnd={actionBarAnim.onSettleEnd}
+						>
+							<ActionBar
+								onAddCombatant={addCombatant}
+								onAddFromBestiary={handleAddFromBestiary}
+								bestiarySearch={search}
+								bestiaryLoaded={isLoaded}
+								onViewStatBlock={handleViewStatBlock}
+								onBulkImport={handleBulkImport}
+								bulkImportDisabled={bulkImport.state.status === "loading"}
+								inputRef={actionBarInputRef}
+								playerCharacters={playerCharacters}
+								onAddFromPlayerCharacter={addFromPlayerCharacter}
+								onManagePlayers={() => setManagementOpen(true)}
+								onRollAllInitiative={handleRollAllInitiative}
+								showRollAllInitiative={showRollAllInitiative}
+								onOpenSourceManager={() => setSourceManagerOpen((o) => !o)}
+							/>
+						</div>
+					</>
+				)}
+			</div>
+
+			{/* Pinned Stat Block Panel (left) */}
+			{pinnedCreatureId && isWideDesktop && (
+				<StatBlockPanel
+					creatureId={pinnedCreatureId}
+					creature={pinnedCreature}
+					isSourceCached={isSourceCached}
+					fetchAndCacheSource={fetchAndCacheSource}
+					uploadAndCacheSource={uploadAndCacheSource}
+					refreshCache={refreshCache}
+					panelRole="pinned"
+					isFolded={false}
+					onToggleFold={() => {}}
+					onPin={() => {}}
+					onUnpin={handleUnpin}
+					showPinButton={false}
+					side="left"
+					onDismiss={() => {}}
 				/>
-				<button type="submit">Add Combatant</button>
-			</form>
-
-			<button type="button" onClick={advanceTurn}>
-				Next Turn
-			</button>
-
-			{events.length > 0 && (
-				<div>
-					<h2>Events</h2>
-					<ul>
-						{events.map((e, i) => (
-							<li key={`${e.type}-${i}`}>{formatEvent(e)}</li>
-						))}
-					</ul>
-				</div>
 			)}
+
+			{/* Browse Stat Block Panel (right) */}
+			<StatBlockPanel
+				creatureId={selectedCreatureId}
+				creature={selectedCreature}
+				isSourceCached={isSourceCached}
+				fetchAndCacheSource={fetchAndCacheSource}
+				uploadAndCacheSource={uploadAndCacheSource}
+				refreshCache={refreshCache}
+				panelRole="browse"
+				isFolded={isRightPanelFolded}
+				onToggleFold={handleToggleFold}
+				onPin={handlePin}
+				onUnpin={() => {}}
+				showPinButton={isWideDesktop && !!selectedCreature}
+				side="right"
+				onDismiss={handleDismissBrowsePanel}
+				bulkImportMode={bulkImportMode}
+				bulkImportState={bulkImport.state}
+				onStartBulkImport={handleStartBulkImport}
+				onBulkImportDone={handleBulkImportDone}
+			/>
+
+			{/* Toast for bulk import progress when panel is closed */}
+			{bulkImport.state.status === "loading" && !bulkImportMode && (
+				<Toast
+					message={`Loading sources... ${bulkImport.state.completed + bulkImport.state.failed}/${bulkImport.state.total}`}
+					progress={
+						bulkImport.state.total > 0
+							? (bulkImport.state.completed + bulkImport.state.failed) /
+								bulkImport.state.total
+							: 0
+					}
+					onDismiss={() => {}}
+				/>
+			)}
+			{bulkImport.state.status === "complete" && !bulkImportMode && (
+				<Toast
+					message="All sources loaded"
+					onDismiss={bulkImport.reset}
+					autoDismissMs={3000}
+				/>
+			)}
+			{bulkImport.state.status === "partial-failure" && !bulkImportMode && (
+				<Toast
+					message={`Loaded ${bulkImport.state.completed}/${bulkImport.state.total} sources (${bulkImport.state.failed} failed)`}
+					onDismiss={bulkImport.reset}
+				/>
+			)}
+
+			<CreatePlayerModal
+				open={createPlayerOpen}
+				onClose={() => {
+					setCreatePlayerOpen(false);
+					setEditingPlayer(undefined);
+				}}
+				onSave={(name, ac, maxHp, color, icon) => {
+					if (editingPlayer) {
+						editPlayerCharacter?.(editingPlayer.id, {
+							name,
+							ac,
+							maxHp,
+							color,
+							icon,
+						});
+					} else {
+						createPlayerCharacter(name, ac, maxHp, color, icon);
+					}
+				}}
+				playerCharacter={editingPlayer}
+			/>
+
+			<PlayerManagement
+				open={managementOpen}
+				onClose={() => setManagementOpen(false)}
+				characters={playerCharacters}
+				onEdit={(pc) => {
+					setEditingPlayer(pc);
+					setCreatePlayerOpen(true);
+					setManagementOpen(false);
+				}}
+				onDelete={(id) => deletePlayerCharacter?.(id)}
+				onCreate={() => {
+					setEditingPlayer(undefined);
+					setCreatePlayerOpen(true);
+					setManagementOpen(false);
+				}}
+			/>
 		</div>
 	);
 }

apps/web/src/__tests__/bestiary-index-helpers.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import {
+	getAllSourceCodes,
+	getDefaultFetchUrl,
+} from "../adapters/bestiary-index-adapter.js";
+
+describe("getAllSourceCodes", () => {
+	it("returns all keys from the index sources object", () => {
+		const codes = getAllSourceCodes();
+		expect(codes.length).toBeGreaterThan(0);
+		expect(Array.isArray(codes)).toBe(true);
+		for (const code of codes) {
+			expect(typeof code).toBe("string");
+		}
+	});
+});
+
+describe("getDefaultFetchUrl", () => {
+	it("returns the default URL when no baseUrl is provided", () => {
+		const url = getDefaultFetchUrl("XMM");
+		expect(url).toBe(
+			"https://raw.githubusercontent.com/5etools-mirror-3/5etools-src/main/data/bestiary/bestiary-xmm.json",
+		);
+	});
+
+	it("constructs URL from baseUrl with trailing slash", () => {
+		const url = getDefaultFetchUrl("PHB", "https://example.com/data/");
+		expect(url).toBe("https://example.com/data/bestiary-phb.json");
+	});
+
+	it("normalizes baseUrl without trailing slash", () => {
+		const url = getDefaultFetchUrl("PHB", "https://example.com/data");
+		expect(url).toBe("https://example.com/data/bestiary-phb.json");
+	});
+
+	it("lowercases the source code in the filename", () => {
+		const url = getDefaultFetchUrl("MM", "https://example.com/");
+		expect(url).toBe("https://example.com/bestiary-mm.json");
+	});
+});

apps/web/src/__tests__/confirm-button.test.tsx

@@ -0,0 +1,218 @@
+// @vitest-environment jsdom
+import {
+	act,
+	cleanup,
+	fireEvent,
+	render,
+	screen,
+} from "@testing-library/react";
+import "@testing-library/jest-dom/vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ConfirmButton } from "../components/ui/confirm-button";
+
+function XIcon() {
+	return <span data-testid="x-icon">X</span>;
+}
+
+function renderButton(
+	props: Partial<Parameters<typeof ConfirmButton>[0]> = {},
+) {
+	const onConfirm = props.onConfirm ?? vi.fn();
+	render(
+		<ConfirmButton
+			icon={<XIcon />}
+			label="Remove combatant"
+			onConfirm={onConfirm}
+			{...props}
+		/>,
+	);
+	return { onConfirm };
+}
+
+describe("ConfirmButton", () => {
+	beforeEach(() => {
+		vi.useFakeTimers();
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+		cleanup();
+	});
+
+	it("renders the default icon in idle state", () => {
+		renderButton();
+		expect(screen.getByTestId("x-icon")).toBeTruthy();
+		expect(screen.getByRole("button")).toHaveAttribute(
+			"aria-label",
+			"Remove combatant",
+		);
+	});
+
+	it("transitions to confirm state with Check icon on first click", () => {
+		renderButton();
+		fireEvent.click(screen.getByRole("button"));
+
+		expect(screen.queryByTestId("x-icon")).toBeNull();
+		expect(screen.getByRole("button")).toHaveAttribute(
+			"aria-label",
+			"Confirm remove combatant",
+		);
+		expect(screen.getByRole("button").className).toContain("bg-destructive");
+	});
+
+	it("calls onConfirm on second click in confirm state", () => {
+		const { onConfirm } = renderButton();
+		const button = screen.getByRole("button");
+
+		fireEvent.click(button);
+		fireEvent.click(button);
+
+		expect(onConfirm).toHaveBeenCalledOnce();
+	});
+
+	it("auto-reverts after 5 seconds", () => {
+		renderButton();
+		fireEvent.click(screen.getByRole("button"));
+
+		expect(screen.queryByTestId("x-icon")).toBeNull();
+
+		act(() => {
+			vi.advanceTimersByTime(5000);
+		});
+
+		expect(screen.getByTestId("x-icon")).toBeTruthy();
+	});
+
+	it("reverts on Escape key", () => {
+		renderButton();
+		fireEvent.click(screen.getByRole("button"));
+
+		expect(screen.queryByTestId("x-icon")).toBeNull();
+
+		fireEvent.keyDown(document, { key: "Escape" });
+
+		expect(screen.getByTestId("x-icon")).toBeTruthy();
+	});
+
+	it("reverts on click outside", () => {
+		renderButton();
+		fireEvent.click(screen.getByRole("button"));
+
+		expect(screen.queryByTestId("x-icon")).toBeNull();
+
+		fireEvent.mouseDown(document.body);
+
+		expect(screen.getByTestId("x-icon")).toBeTruthy();
+	});
+
+	it("does not enter confirm state when disabled", () => {
+		renderButton({ disabled: true });
+		fireEvent.click(screen.getByRole("button"));
+
+		expect(screen.getByTestId("x-icon")).toBeTruthy();
+	});
+
+	it("cleans up timer on unmount", () => {
+		const clearTimeoutSpy = vi.spyOn(globalThis, "clearTimeout");
+		renderButton();
+		fireEvent.click(screen.getByRole("button"));
+
+		cleanup();
+
+		expect(clearTimeoutSpy).toHaveBeenCalled();
+		clearTimeoutSpy.mockRestore();
+	});
+
+	it("manages independent instances separately", () => {
+		const onConfirm1 = vi.fn();
+		const onConfirm2 = vi.fn();
+
+		render(
+			<>
+				<ConfirmButton
+					icon={<span data-testid="icon-1">1</span>}
+					label="Remove first"
+					onConfirm={onConfirm1}
+				/>
+				<ConfirmButton
+					icon={<span data-testid="icon-2">2</span>}
+					label="Remove second"
+					onConfirm={onConfirm2}
+				/>
+			</>,
+		);
+
+		const buttons = screen.getAllByRole("button");
+		fireEvent.click(buttons[0]);
+
+		// First is confirming, second is still idle
+		expect(screen.queryByTestId("icon-1")).toBeNull();
+		expect(screen.getByTestId("icon-2")).toBeTruthy();
+	});
+
+	// T008: Keyboard-specific tests
+	it("Enter key triggers confirm state", () => {
+		renderButton();
+		const button = screen.getByRole("button");
+
+		// Native button handles Enter via click event
+		fireEvent.click(button);
+
+		expect(screen.queryByTestId("x-icon")).toBeNull();
+		expect(button).toHaveAttribute("aria-label", "Confirm remove combatant");
+	});
+
+	it("Enter in confirm state calls onConfirm", () => {
+		const { onConfirm } = renderButton();
+		const button = screen.getByRole("button");
+
+		fireEvent.click(button); // enter confirm state
+		fireEvent.click(button); // confirm
+
+		expect(onConfirm).toHaveBeenCalledOnce();
+	});
+
+	it("Escape in confirm state reverts", () => {
+		renderButton();
+		fireEvent.click(screen.getByRole("button"));
+
+		fireEvent.keyDown(document, { key: "Escape" });
+
+		expect(screen.getByTestId("x-icon")).toBeTruthy();
+		expect(screen.getByRole("button")).toHaveAttribute(
+			"aria-label",
+			"Remove combatant",
+		);
+	});
+
+	it("blur event reverts confirm state", () => {
+		renderButton();
+		const button = screen.getByRole("button");
+
+		fireEvent.click(button);
+		expect(screen.queryByTestId("x-icon")).toBeNull();
+
+		fireEvent.blur(button);
+		expect(screen.getByTestId("x-icon")).toBeTruthy();
+	});
+
+	it("Enter/Space keydown stops propagation to prevent parent handlers", () => {
+		const parentHandler = vi.fn();
+		render(
+			// biome-ignore lint/a11y/noStaticElementInteractions: test wrapper
+			<div onKeyDown={parentHandler}>
+				<ConfirmButton
+					icon={<XIcon />}
+					label="Remove combatant"
+					onConfirm={vi.fn()}
+				/>
+			</div>,
+		);
+		const button = screen.getByRole("button");
+
+		fireEvent.keyDown(button, { key: "Enter" });
+		fireEvent.keyDown(button, { key: " " });
+
+		expect(parentHandler).not.toHaveBeenCalled();
+	});
+});

apps/web/src/__tests__/stat-block-fold-pin.test.tsx

@@ -0,0 +1,263 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import type { Creature, CreatureId } from "@initiative/domain";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { StatBlockPanel } from "../components/stat-block-panel";
+
+const CREATURE_ID = "srd:goblin" as CreatureId;
+const CREATURE: Creature = {
+	id: CREATURE_ID,
+	name: "Goblin",
+	source: "SRD",
+	sourceDisplayName: "SRD",
+	size: "Small",
+	type: "humanoid",
+	alignment: "neutral evil",
+	ac: 15,
+	hp: { average: 7, formula: "2d6" },
+	speed: "30 ft.",
+	abilities: { str: 8, dex: 14, con: 10, int: 10, wis: 8, cha: 8 },
+	cr: "1/4",
+	initiativeProficiency: 0,
+	proficiencyBonus: 2,
+	passive: 9,
+};
+
+function mockMatchMedia(matches: boolean) {
+	Object.defineProperty(window, "matchMedia", {
+		writable: true,
+		value: vi.fn().mockImplementation((query: string) => ({
+			matches,
+			media: query,
+			onchange: null,
+			addListener: vi.fn(),
+			removeListener: vi.fn(),
+			addEventListener: vi.fn(),
+			removeEventListener: vi.fn(),
+			dispatchEvent: vi.fn(),
+		})),
+	});
+}
+
+interface PanelProps {
+	creatureId?: CreatureId | null;
+	creature?: Creature | null;
+	panelRole?: "browse" | "pinned";
+	isFolded?: boolean;
+	onToggleFold?: () => void;
+	onPin?: () => void;
+	onUnpin?: () => void;
+	showPinButton?: boolean;
+	side?: "left" | "right";
+	onDismiss?: () => void;
+	bulkImportMode?: boolean;
+}
+
+function renderPanel(overrides: PanelProps = {}) {
+	const props = {
+		creatureId: CREATURE_ID,
+		creature: CREATURE,
+		isSourceCached: vi.fn().mockResolvedValue(true),
+		fetchAndCacheSource: vi.fn(),
+		uploadAndCacheSource: vi.fn(),
+		refreshCache: vi.fn(),
+		panelRole: "browse" as const,
+		isFolded: false,
+		onToggleFold: vi.fn(),
+		onPin: vi.fn(),
+		onUnpin: vi.fn(),
+		showPinButton: false,
+		side: "right" as const,
+		onDismiss: vi.fn(),
+		...overrides,
+	};
+
+	render(<StatBlockPanel {...props} />);
+	return props;
+}
+
+describe("Stat Block Panel Fold/Unfold and Pin", () => {
+	beforeEach(() => {
+		mockMatchMedia(true); // desktop by default
+	});
+
+	afterEach(cleanup);
+
+	describe("US1: Fold and Unfold", () => {
+		it("shows fold button instead of close button on desktop", () => {
+			renderPanel();
+			expect(
+				screen.getByRole("button", { name: "Fold stat block panel" }),
+			).toBeInTheDocument();
+			expect(
+				screen.queryByRole("button", { name: /close/i }),
+			).not.toBeInTheDocument();
+		});
+
+		it("does not show 'Stat Block' heading", () => {
+			renderPanel();
+			expect(screen.queryByText("Stat Block")).not.toBeInTheDocument();
+		});
+
+		it("renders folded tab with creature name when isFolded is true", () => {
+			renderPanel({ isFolded: true });
+			expect(screen.getByText("Goblin")).toBeInTheDocument();
+			expect(
+				screen.getByRole("button", { name: "Unfold stat block panel" }),
+			).toBeInTheDocument();
+		});
+
+		it("calls onToggleFold when fold button is clicked", () => {
+			const props = renderPanel();
+			fireEvent.click(
+				screen.getByRole("button", { name: "Fold stat block panel" }),
+			);
+			expect(props.onToggleFold).toHaveBeenCalledTimes(1);
+		});
+
+		it("calls onToggleFold when folded tab is clicked", () => {
+			const props = renderPanel({ isFolded: true });
+			fireEvent.click(
+				screen.getByRole("button", { name: "Unfold stat block panel" }),
+			);
+			expect(props.onToggleFold).toHaveBeenCalledTimes(1);
+		});
+
+		it("applies translate-x class when folded (right side)", () => {
+			renderPanel({ isFolded: true, side: "right" });
+			const panel = screen
+				.getByRole("button", { name: "Unfold stat block panel" })
+				.closest("div");
+			expect(panel?.className).toContain("translate-x-[calc(100%-40px)]");
+		});
+
+		it("applies translate-x-0 when expanded", () => {
+			renderPanel({ isFolded: false });
+			const foldBtn = screen.getByRole("button", {
+				name: "Fold stat block panel",
+			});
+			const panel = foldBtn.closest("div.fixed") as HTMLElement;
+			expect(panel?.className).toContain("translate-x-0");
+		});
+	});
+
+	describe("US1: Mobile behavior", () => {
+		beforeEach(() => {
+			mockMatchMedia(false); // mobile
+		});
+
+		it("shows fold button instead of X close button on mobile drawer", () => {
+			renderPanel();
+			expect(
+				screen.getByRole("button", { name: "Fold stat block panel" }),
+			).toBeInTheDocument();
+			// No X close icon button — only backdrop dismiss and fold toggle
+			const buttons = screen.getAllByRole("button");
+			const buttonLabels = buttons.map((b) => b.getAttribute("aria-label"));
+			expect(buttonLabels).not.toContain("Close");
+		});
+
+		it("calls onDismiss when backdrop is clicked on mobile", () => {
+			const props = renderPanel();
+			fireEvent.click(screen.getByRole("button", { name: "Close stat block" }));
+			expect(props.onDismiss).toHaveBeenCalledTimes(1);
+		});
+
+		it("does not render pinned panel on mobile", () => {
+			const { container } = render(
+				<StatBlockPanel
+					creatureId={CREATURE_ID}
+					creature={CREATURE}
+					isSourceCached={vi.fn().mockResolvedValue(true)}
+					fetchAndCacheSource={vi.fn()}
+					uploadAndCacheSource={vi.fn()}
+					refreshCache={vi.fn()}
+					panelRole="pinned"
+					isFolded={false}
+					onToggleFold={vi.fn()}
+					onPin={vi.fn()}
+					onUnpin={vi.fn()}
+					showPinButton={false}
+					side="left"
+					onDismiss={vi.fn()}
+				/>,
+			);
+			expect(container.innerHTML).toBe("");
+		});
+	});
+
+	describe("US2: Pin and Unpin", () => {
+		it("shows pin button when showPinButton is true on desktop", () => {
+			renderPanel({ showPinButton: true });
+			expect(
+				screen.getByRole("button", { name: "Pin creature" }),
+			).toBeInTheDocument();
+		});
+
+		it("hides pin button when showPinButton is false", () => {
+			renderPanel({ showPinButton: false });
+			expect(
+				screen.queryByRole("button", { name: "Pin creature" }),
+			).not.toBeInTheDocument();
+		});
+
+		it("calls onPin when pin button is clicked", () => {
+			const props = renderPanel({ showPinButton: true });
+			fireEvent.click(screen.getByRole("button", { name: "Pin creature" }));
+			expect(props.onPin).toHaveBeenCalledTimes(1);
+		});
+
+		it("shows unpin button for pinned role", () => {
+			renderPanel({ panelRole: "pinned", side: "left" });
+			expect(
+				screen.getByRole("button", { name: "Unpin creature" }),
+			).toBeInTheDocument();
+		});
+
+		it("calls onUnpin when unpin button is clicked", () => {
+			const props = renderPanel({ panelRole: "pinned", side: "left" });
+			fireEvent.click(screen.getByRole("button", { name: "Unpin creature" }));
+			expect(props.onUnpin).toHaveBeenCalledTimes(1);
+		});
+
+		it("positions pinned panel on the left side", () => {
+			renderPanel({ panelRole: "pinned", side: "left" });
+			const unpinBtn = screen.getByRole("button", {
+				name: "Unpin creature",
+			});
+			const panel = unpinBtn.closest("div.fixed") as HTMLElement;
+			expect(panel?.className).toContain("left-0");
+			expect(panel?.className).toContain("border-r");
+		});
+
+		it("positions browse panel on the right side", () => {
+			renderPanel({ panelRole: "browse", side: "right" });
+			const foldBtn = screen.getByRole("button", {
+				name: "Fold stat block panel",
+			});
+			const panel = foldBtn.closest("div.fixed") as HTMLElement;
+			expect(panel?.className).toContain("right-0");
+			expect(panel?.className).toContain("border-l");
+		});
+	});
+
+	describe("US3: Fold independence with pinned panel", () => {
+		it("pinned panel has no fold button", () => {
+			renderPanel({ panelRole: "pinned", side: "left" });
+			expect(
+				screen.queryByRole("button", { name: /fold/i }),
+			).not.toBeInTheDocument();
+		});
+
+		it("pinned panel is always expanded (no translate offset)", () => {
+			renderPanel({ panelRole: "pinned", side: "left", isFolded: false });
+			const unpinBtn = screen.getByRole("button", {
+				name: "Unpin creature",
+			});
+			const panel = unpinBtn.closest("div.fixed") as HTMLElement;
+			expect(panel?.className).toContain("translate-x-0");
+		});
+	});
+});

apps/web/src/__tests__/use-bulk-import.test.ts

@@ -0,0 +1,235 @@
+import { describe, expect, it, vi } from "vitest";
+import * as indexAdapter from "../adapters/bestiary-index-adapter.js";
+
+// We test the bulk import logic by extracting and exercising the async flow.
+// Since useBulkImport is a thin React wrapper around async logic,
+// we test the core behavior via a direct simulation.
+
+vi.mock("../adapters/bestiary-index-adapter.js", async () => {
+	const actual = await vi.importActual<
+		typeof import("../adapters/bestiary-index-adapter.js")
+	>("../adapters/bestiary-index-adapter.js");
+	return {
+		...actual,
+		getAllSourceCodes: vi.fn(),
+	};
+});
+
+const mockGetAllSourceCodes = vi.mocked(indexAdapter.getAllSourceCodes);
+
+interface BulkImportState {
+	status: "idle" | "loading" | "complete" | "partial-failure";
+	total: number;
+	completed: number;
+	failed: number;
+}
+
+/** Simulate the core bulk import logic extracted from the hook */
+async function runBulkImport(
+	baseUrl: string,
+	fetchAndCacheSource: (sourceCode: string, url: string) => Promise<void>,
+	isSourceCached: (sourceCode: string) => Promise<boolean>,
+	refreshCache: () => Promise<void>,
+): Promise<BulkImportState> {
+	const allCodes = indexAdapter.getAllSourceCodes();
+	const total = allCodes.length;
+
+	const cacheChecks = await Promise.all(
+		allCodes.map(async (code) => ({
+			code,
+			cached: await isSourceCached(code),
+		})),
+	);
+
+	const alreadyCached = cacheChecks.filter((c) => c.cached).length;
+	const uncached = cacheChecks.filter((c) => !c.cached);
+
+	if (uncached.length === 0) {
+		return { status: "complete", total, completed: total, failed: 0 };
+	}
+
+	let completed = alreadyCached;
+	let failed = 0;
+
+	await Promise.allSettled(
+		uncached.map(async ({ code }) => {
+			const url = indexAdapter.getDefaultFetchUrl(code, baseUrl);
+			try {
+				await fetchAndCacheSource(code, url);
+				completed++;
+			} catch {
+				failed++;
+			}
+		}),
+	);
+
+	await refreshCache();
+
+	return {
+		status: failed > 0 ? "partial-failure" : "complete",
+		total,
+		completed,
+		failed,
+	};
+}
+
+describe("bulk import logic", () => {
+	it("skips already-cached sources and counts them into completed", async () => {
+		mockGetAllSourceCodes.mockReturnValue(["SRC1", "SRC2", "SRC3"]);
+
+		const fetchAndCache = vi.fn().mockResolvedValue(undefined);
+		const isSourceCached = vi
+			.fn()
+			.mockImplementation((code: string) =>
+				Promise.resolve(code === "SRC1" || code === "SRC3"),
+			);
+		const refreshCache = vi.fn().mockResolvedValue(undefined);
+
+		const result = await runBulkImport(
+			"https://example.com/",
+			fetchAndCache,
+			isSourceCached,
+			refreshCache,
+		);
+
+		expect(fetchAndCache).toHaveBeenCalledTimes(1);
+		expect(fetchAndCache).toHaveBeenCalledWith(
+			"SRC2",
+			"https://example.com/bestiary-src2.json",
+		);
+		expect(result.completed).toBe(3);
+		expect(result.status).toBe("complete");
+	});
+
+	it("increments completed on successful fetch", async () => {
+		mockGetAllSourceCodes.mockReturnValue(["SRC1"]);
+
+		const fetchAndCache = vi.fn().mockResolvedValue(undefined);
+		const isSourceCached = vi.fn().mockResolvedValue(false);
+		const refreshCache = vi.fn().mockResolvedValue(undefined);
+
+		const result = await runBulkImport(
+			"https://example.com/",
+			fetchAndCache,
+			isSourceCached,
+			refreshCache,
+		);
+
+		expect(result.completed).toBe(1);
+		expect(result.failed).toBe(0);
+		expect(result.status).toBe("complete");
+	});
+
+	it("increments failed on rejected fetch", async () => {
+		mockGetAllSourceCodes.mockReturnValue(["SRC1"]);
+
+		const fetchAndCache = vi.fn().mockRejectedValue(new Error("fail"));
+		const isSourceCached = vi.fn().mockResolvedValue(false);
+		const refreshCache = vi.fn().mockResolvedValue(undefined);
+
+		const result = await runBulkImport(
+			"https://example.com/",
+			fetchAndCache,
+			isSourceCached,
+			refreshCache,
+		);
+
+		expect(result.failed).toBe(1);
+		expect(result.completed).toBe(0);
+		expect(result.status).toBe("partial-failure");
+	});
+
+	it("transitions to complete when all succeed", async () => {
+		mockGetAllSourceCodes.mockReturnValue(["A", "B"]);
+
+		const fetchAndCache = vi.fn().mockResolvedValue(undefined);
+		const isSourceCached = vi.fn().mockResolvedValue(false);
+		const refreshCache = vi.fn().mockResolvedValue(undefined);
+
+		const result = await runBulkImport(
+			"https://example.com/",
+			fetchAndCache,
+			isSourceCached,
+			refreshCache,
+		);
+
+		expect(result.status).toBe("complete");
+		expect(result.completed).toBe(2);
+		expect(result.failed).toBe(0);
+	});
+
+	it("transitions to partial-failure when any fetch fails", async () => {
+		mockGetAllSourceCodes.mockReturnValue(["A", "B"]);
+
+		const fetchAndCache = vi
+			.fn()
+			.mockResolvedValueOnce(undefined)
+			.mockRejectedValueOnce(new Error("fail"));
+		const isSourceCached = vi.fn().mockResolvedValue(false);
+		const refreshCache = vi.fn().mockResolvedValue(undefined);
+
+		const result = await runBulkImport(
+			"https://example.com/",
+			fetchAndCache,
+			isSourceCached,
+			refreshCache,
+		);
+
+		expect(result.status).toBe("partial-failure");
+		expect(result.failed).toBe(1);
+	});
+
+	it("immediately transitions to complete when all sources are cached", async () => {
+		mockGetAllSourceCodes.mockReturnValue(["A", "B", "C"]);
+
+		const fetchAndCache = vi.fn();
+		const isSourceCached = vi.fn().mockResolvedValue(true);
+		const refreshCache = vi.fn().mockResolvedValue(undefined);
+
+		const result = await runBulkImport(
+			"https://example.com/",
+			fetchAndCache,
+			isSourceCached,
+			refreshCache,
+		);
+
+		expect(result.status).toBe("complete");
+		expect(result.total).toBe(3);
+		expect(result.completed).toBe(3);
+		expect(fetchAndCache).not.toHaveBeenCalled();
+	});
+
+	it("calls refreshCache exactly once when all settle", async () => {
+		mockGetAllSourceCodes.mockReturnValue(["A", "B"]);
+
+		const fetchAndCache = vi.fn().mockResolvedValue(undefined);
+		const isSourceCached = vi.fn().mockResolvedValue(false);
+		const refreshCache = vi.fn().mockResolvedValue(undefined);
+
+		await runBulkImport(
+			"https://example.com/",
+			fetchAndCache,
+			isSourceCached,
+			refreshCache,
+		);
+
+		expect(refreshCache).toHaveBeenCalledTimes(1);
+	});
+
+	it("does not call refreshCache when all sources are already cached", async () => {
+		mockGetAllSourceCodes.mockReturnValue(["A"]);
+
+		const fetchAndCache = vi.fn();
+		const isSourceCached = vi.fn().mockResolvedValue(true);
+		const refreshCache = vi.fn().mockResolvedValue(undefined);
+
+		await runBulkImport(
+			"https://example.com/",
+			fetchAndCache,
+			isSourceCached,
+			refreshCache,
+		);
+
+		expect(refreshCache).not.toHaveBeenCalled();
+	});
+});

apps/web/src/adapters/__tests__/bestiary-adapter.test.ts

@@ -0,0 +1,333 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import {
+	normalizeBestiary,
+	setSourceDisplayNames,
+} from "../bestiary-adapter.js";
+
+beforeAll(() => {
+	setSourceDisplayNames({ XMM: "MM 2024" });
+});
+
+describe("normalizeBestiary", () => {
+	it("normalizes a simple creature", () => {
+		const raw = {
+			monster: [
+				{
+					name: "Goblin Warrior",
+					source: "XMM",
+					size: ["S"],
+					type: { type: "fey", tags: ["goblinoid"] },
+					alignment: ["C", "N"],
+					ac: [15],
+					hp: { average: 10, formula: "3d6" },
+					speed: { walk: 30 },
+					str: 8,
+					dex: 15,
+					con: 10,
+					int: 10,
+					wis: 8,
+					cha: 8,
+					skill: { stealth: "+6" },
+					senses: ["Darkvision 60 ft."],
+					passive: 9,
+					languages: ["Common", "Goblin"],
+					cr: "1/4",
+					action: [
+						{
+							name: "Scimitar",
+							entries: [
+								"{@atkr m} {@hit 4}, reach 5 ft. {@h}5 ({@damage 1d6 + 2}) Slashing damage.",
+							],
+						},
+					],
+					bonus: [
+						{
+							name: "Nimble Escape",
+							entries: [
+								"The goblin takes the {@action Disengage|XPHB} or {@action Hide|XPHB} action.",
+							],
+						},
+					],
+				},
+			],
+		};
+
+		const creatures = normalizeBestiary(raw);
+		expect(creatures).toHaveLength(1);
+
+		const c = creatures[0];
+		expect(c.id).toBe("xmm:goblin-warrior");
+		expect(c.name).toBe("Goblin Warrior");
+		expect(c.source).toBe("XMM");
+		expect(c.sourceDisplayName).toBe("MM 2024");
+		expect(c.size).toBe("Small");
+		expect(c.type).toBe("Fey (Goblinoid)");
+		expect(c.alignment).toBe("Chaotic Neutral");
+		expect(c.ac).toBe(15);
+		expect(c.hp).toEqual({ average: 10, formula: "3d6" });
+		expect(c.speed).toBe("30 ft.");
+		expect(c.abilities.dex).toBe(15);
+		expect(c.cr).toBe("1/4");
+		expect(c.proficiencyBonus).toBe(2);
+		expect(c.passive).toBe(9);
+		expect(c.skills).toBe("Stealth +6");
+		expect(c.senses).toBe("Darkvision 60 ft.");
+		expect(c.languages).toBe("Common, Goblin");
+		expect(c.actions).toHaveLength(1);
+		expect(c.actions?.[0].text).toContain("Melee Attack Roll:");
+		expect(c.actions?.[0].text).not.toContain("{@");
+		expect(c.bonusActions).toHaveLength(1);
+		expect(c.bonusActions?.[0].text).toContain("Disengage");
+		expect(c.bonusActions?.[0].text).not.toContain("{@");
+	});
+
+	it("normalizes a creature with legendary actions", () => {
+		const raw = {
+			monster: [
+				{
+					name: "Aboleth",
+					source: "XMM",
+					size: ["L"],
+					type: "aberration",
+					alignment: ["L", "E"],
+					ac: [17],
+					hp: { average: 135, formula: "18d10 + 36" },
+					speed: { walk: 10, swim: 40 },
+					str: 21,
+					dex: 9,
+					con: 15,
+					int: 18,
+					wis: 15,
+					cha: 18,
+					save: { con: "+6", int: "+8", wis: "+6" },
+					senses: ["Darkvision 120 ft."],
+					passive: 12,
+					languages: ["Deep Speech", "Telepathy 120 ft."],
+					cr: "10",
+					legendary: [
+						{
+							name: "Lash",
+							entries: ["The aboleth makes one Tentacle attack."],
+						},
+					],
+				},
+			],
+		};
+
+		const creatures = normalizeBestiary(raw);
+		const c = creatures[0];
+		expect(c.legendaryActions).toBeDefined();
+		expect(c.legendaryActions?.preamble).toContain("3 Legendary Actions");
+		expect(c.legendaryActions?.entries).toHaveLength(1);
+		expect(c.legendaryActions?.entries[0].name).toBe("Lash");
+	});
+
+	it("normalizes a creature with spellcasting", () => {
+		const raw = {
+			monster: [
+				{
+					name: "Test Caster",
+					source: "XMM",
+					size: ["M"],
+					type: "humanoid",
+					ac: [12],
+					hp: { average: 40, formula: "9d8" },
+					speed: { walk: 30 },
+					str: 10,
+					dex: 14,
+					con: 10,
+					int: 17,
+					wis: 12,
+					cha: 11,
+					passive: 11,
+					cr: "6",
+					spellcasting: [
+						{
+							name: "Spellcasting",
+							headerEntries: [
+								"The caster casts spells using Intelligence (spell save {@dc 15}):",
+							],
+							will: ["{@spell Detect Magic|XPHB}", "{@spell Mage Hand|XPHB}"],
+							daily: {
+								"2e": ["{@spell Fireball|XPHB}"],
+								"1": ["{@spell Dimension Door|XPHB}"],
+							},
+						},
+					],
+				},
+			],
+		};
+
+		const creatures = normalizeBestiary(raw);
+		const c = creatures[0];
+		expect(c.spellcasting).toHaveLength(1);
+		const sc = c.spellcasting?.[0];
+		expect(sc).toBeDefined();
+		expect(sc?.name).toBe("Spellcasting");
+		expect(sc?.headerText).toContain("DC 15");
+		expect(sc?.headerText).not.toContain("{@");
+		expect(sc?.atWill).toEqual(["Detect Magic", "Mage Hand"]);
+		expect(sc?.daily).toHaveLength(2);
+		expect(sc?.daily).toContainEqual({
+			uses: 2,
+			each: true,
+			spells: ["Fireball"],
+		});
+		expect(sc?.daily).toContainEqual({
+			uses: 1,
+			each: false,
+			spells: ["Dimension Door"],
+		});
+	});
+
+	it("normalizes a creature with object-type type field", () => {
+		const raw = {
+			monster: [
+				{
+					name: "Swarm of Bats",
+					source: "XMM",
+					size: ["L"],
+					type: { type: "beast", swarmSize: "T" },
+					ac: [12],
+					hp: { average: 11, formula: "2d10" },
+					speed: { walk: 5, fly: 30 },
+					str: 5,
+					dex: 15,
+					con: 10,
+					int: 2,
+					wis: 12,
+					cha: 4,
+					passive: 11,
+					resist: ["bludgeoning", "piercing", "slashing"],
+					conditionImmune: ["charmed", "frightened"],
+					cr: "1/4",
+				},
+			],
+		};
+
+		const creatures = normalizeBestiary(raw);
+		const c = creatures[0];
+		expect(c.type).toBe("Swarm of Tiny Beasts");
+		expect(c.resist).toBe("Bludgeoning, Piercing, Slashing");
+		expect(c.conditionImmune).toBe("Charmed, Frightened");
+	});
+
+	it("normalizes a creature with conditional resistances", () => {
+		const raw = {
+			monster: [
+				{
+					name: "Half-Dragon",
+					source: "XMM",
+					size: ["M"],
+					type: "humanoid",
+					ac: [18],
+					hp: { average: 65, formula: "10d8 + 20" },
+					speed: { walk: 30 },
+					str: 16,
+					dex: 13,
+					con: 14,
+					int: 10,
+					wis: 11,
+					cha: 10,
+					passive: 10,
+					cr: "5",
+					resist: [
+						{
+							special: "Damage type chosen for the Draconic Origin trait",
+						},
+					],
+				},
+			],
+		};
+
+		const creatures = normalizeBestiary(raw);
+		const c = creatures[0];
+		expect(c.resist).toBe("Damage type chosen for the Draconic Origin trait");
+	});
+
+	it("normalizes a creature with multiple sizes", () => {
+		const raw = {
+			monster: [
+				{
+					name: "Aberrant Cultist",
+					source: "XMM",
+					size: ["S", "M"],
+					type: "humanoid",
+					ac: [13],
+					hp: { average: 22, formula: "4d8 + 4" },
+					speed: { walk: 30 },
+					str: 11,
+					dex: 14,
+					con: 12,
+					int: 10,
+					wis: 13,
+					cha: 8,
+					passive: 11,
+					cr: "1/2",
+				},
+			],
+		};
+
+		const creatures = normalizeBestiary(raw);
+		expect(creatures[0].size).toBe("Small or Medium");
+	});
+
+	it("normalizes a creature with CR as object", () => {
+		const raw = {
+			monster: [
+				{
+					name: "Dragon",
+					source: "XMM",
+					size: ["H"],
+					type: "dragon",
+					ac: [19],
+					hp: { average: 256, formula: "19d12 + 133" },
+					speed: { walk: 40 },
+					str: 27,
+					dex: 10,
+					con: 25,
+					int: 16,
+					wis: 13,
+					cha: 23,
+					passive: 23,
+					cr: { cr: "17", xpLair: 20000 },
+				},
+			],
+		};
+
+		const creatures = normalizeBestiary(raw);
+		expect(creatures[0].cr).toBe("17");
+		expect(creatures[0].proficiencyBonus).toBe(6);
+	});
+
+	it("handles fly speed with hover condition", () => {
+		const raw = {
+			monster: [
+				{
+					name: "Air Elemental",
+					source: "XMM",
+					size: ["L"],
+					type: "elemental",
+					ac: [15],
+					hp: { average: 90, formula: "12d10 + 24" },
+					speed: {
+						walk: 10,
+						fly: { number: 90, condition: "(hover)" },
+						canHover: true,
+					},
+					str: 14,
+					dex: 20,
+					con: 14,
+					int: 6,
+					wis: 10,
+					cha: 6,
+					passive: 10,
+					cr: "5",
+				},
+			],
+		};
+
+		const creatures = normalizeBestiary(raw);
+		expect(creatures[0].speed).toBe("10 ft., fly 90 ft. (hover)");
+	});
+});

apps/web/src/adapters/__tests__/strip-tags.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from "vitest";
+import { stripTags } from "../strip-tags.js";
+
+describe("stripTags", () => {
+	it("returns text unchanged when no tags present", () => {
+		expect(stripTags("Hello world")).toBe("Hello world");
+	});
+
+	it("strips {@spell Name|Source} to Name", () => {
+		expect(stripTags("{@spell Fireball|XPHB}")).toBe("Fireball");
+	});
+
+	it("strips {@condition Name|Source} to Name", () => {
+		expect(stripTags("{@condition Frightened|XPHB}")).toBe("Frightened");
+	});
+
+	it("strips {@damage dice} to dice", () => {
+		expect(stripTags("{@damage 2d10}")).toBe("2d10");
+	});
+
+	it("strips {@dice value} to value", () => {
+		expect(stripTags("{@dice 5d10}")).toBe("5d10");
+	});
+
+	it("strips {@dc N} to DC N", () => {
+		expect(stripTags("{@dc 15}")).toBe("DC 15");
+	});
+
+	it("strips {@hit N} to +N", () => {
+		expect(stripTags("{@hit 5}")).toBe("+5");
+	});
+
+	it("strips {@h} to Hit: ", () => {
+		expect(stripTags("{@h}")).toBe("Hit: ");
+	});
+
+	it("strips {@hom} to Hit or Miss: ", () => {
+		expect(stripTags("{@hom}")).toBe("Hit or Miss: ");
+	});
+
+	it("strips {@atkr m} to Melee Attack Roll:", () => {
+		expect(stripTags("{@atkr m}")).toBe("Melee Attack Roll:");
+	});
+
+	it("strips {@atkr r} to Ranged Attack Roll:", () => {
+		expect(stripTags("{@atkr r}")).toBe("Ranged Attack Roll:");
+	});
+
+	it("strips {@atkr m,r} to Melee or Ranged Attack Roll:", () => {
+		expect(stripTags("{@atkr m,r}")).toBe("Melee or Ranged Attack Roll:");
+	});
+
+	it("strips {@recharge 5} to (Recharge 5-6)", () => {
+		expect(stripTags("{@recharge 5}")).toBe("(Recharge 5-6)");
+	});
+
+	it("strips {@recharge} to (Recharge 6)", () => {
+		expect(stripTags("{@recharge}")).toBe("(Recharge 6)");
+	});
+
+	it("strips {@actSave wis} to Wisdom saving throw", () => {
+		expect(stripTags("{@actSave wis}")).toBe("Wisdom saving throw");
+	});
+
+	it("strips {@actSaveFail} to Failure:", () => {
+		expect(stripTags("{@actSaveFail}")).toBe("Failure:");
+	});
+
+	it("strips {@actSaveFail 2} to Failure by 2 or More:", () => {
+		expect(stripTags("{@actSaveFail 2}")).toBe("Failure by 2 or More:");
+	});
+
+	it("strips {@actSaveSuccess} to Success:", () => {
+		expect(stripTags("{@actSaveSuccess}")).toBe("Success:");
+	});
+
+	it("strips {@actTrigger} to Trigger:", () => {
+		expect(stripTags("{@actTrigger}")).toBe("Trigger:");
+	});
+
+	it("strips {@actResponse} to Response:", () => {
+		expect(stripTags("{@actResponse}")).toBe("Response:");
+	});
+
+	it("strips {@variantrule Name|Source|Display} to Display", () => {
+		expect(stripTags("{@variantrule Cone [Area of Effect]|XPHB|Cone}")).toBe(
+			"Cone",
+		);
+	});
+
+	it("strips {@action Name|Source|Display} to Display", () => {
+		expect(stripTags("{@action Disengage|XPHB|Disengage}")).toBe("Disengage");
+	});
+
+	it("strips {@skill Name|Source} to Name", () => {
+		expect(stripTags("{@skill Perception|XPHB}")).toBe("Perception");
+	});
+
+	it("strips {@creature Name|Source} to Name", () => {
+		expect(stripTags("{@creature Goblin|XPHB}")).toBe("Goblin");
+	});
+
+	it("strips {@hazard Name|Source} to Name", () => {
+		expect(stripTags("{@hazard Lava|XPHB}")).toBe("Lava");
+	});
+
+	it("strips {@status Name|Source} to Name", () => {
+		expect(stripTags("{@status Bloodied|XPHB}")).toBe("Bloodied");
+	});
+
+	it("handles unknown tags by extracting first segment", () => {
+		expect(stripTags("{@unknown Something|else}")).toBe("Something");
+	});
+
+	it("handles multiple tags in the same string", () => {
+		expect(stripTags("{@hit 4}, reach 5 ft. {@h}5 ({@damage 1d6 + 2})")).toBe(
+			"+4, reach 5 ft. Hit: 5 (1d6 + 2)",
+		);
+	});
+
+	it("handles nested tags gracefully", () => {
+		expect(
+			stripTags("The spell {@spell Fireball|XPHB} deals {@damage 8d6}."),
+		).toBe("The spell Fireball deals 8d6.");
+	});
+
+	it("handles text with no tags", () => {
+		expect(stripTags("Just plain text.")).toBe("Just plain text.");
+	});
+
+	it("strips {@actSaveSuccessOrFail} to Success or Failure:", () => {
+		expect(stripTags("{@actSaveSuccessOrFail}")).toBe("Success or Failure:");
+	});
+
+	it("strips {@action Name|Source} to Name when no display text", () => {
+		expect(stripTags("{@action Disengage|XPHB}")).toBe("Disengage");
+	});
+});

apps/web/src/adapters/bestiary-adapter.ts

@@ -0,0 +1,460 @@
+import type {
+	Creature,
+	CreatureId,
+	DailySpells,
+	LegendaryBlock,
+	SpellcastingBlock,
+	TraitBlock,
+} from "@initiative/domain";
+import { creatureId, proficiencyBonus } from "@initiative/domain";
+import { stripTags } from "./strip-tags.js";
+
+// --- Raw 5etools types (minimal, for parsing) ---
+
+interface RawMonster {
+	name: string;
+	source: string;
+	size: string[];
+	type: string | { type: string; tags?: string[]; swarmSize?: string };
+	alignment?: string[];
+	ac: (number | { ac: number; from?: string[] } | { special: string })[];
+	hp: { average?: number; formula?: string; special?: string };
+	speed: Record<
+		string,
+		number | { number: number; condition?: string } | boolean
+	>;
+	str: number;
+	dex: number;
+	con: number;
+	int: number;
+	wis: number;
+	cha: number;
+	save?: Record<string, string>;
+	skill?: Record<string, string>;
+	senses?: string[];
+	passive: number;
+	resist?: (string | { special: string })[];
+	immune?: (string | { special: string })[];
+	vulnerable?: (string | { special: string })[];
+	conditionImmune?: string[];
+	languages?: string[];
+	cr?: string | { cr: string };
+	trait?: RawEntry[];
+	action?: RawEntry[];
+	bonus?: RawEntry[];
+	reaction?: RawEntry[];
+	legendary?: RawEntry[];
+	legendaryActions?: number;
+	legendaryActionsLair?: number;
+	legendaryHeader?: string[];
+	spellcasting?: RawSpellcasting[];
+	initiative?: { proficiency?: number };
+}
+
+interface RawEntry {
+	name: string;
+	entries: (string | RawEntryObject)[];
+}
+
+interface RawEntryObject {
+	type: string;
+	items?: (
+		| string
+		| { type: string; name?: string; entries?: (string | RawEntryObject)[] }
+	)[];
+	style?: string;
+	name?: string;
+	entries?: (string | RawEntryObject)[];
+}
+
+interface RawSpellcasting {
+	name: string;
+	headerEntries: string[];
+	will?: string[];
+	daily?: Record<string, string[]>;
+	rest?: Record<string, string[]>;
+	hidden?: string[];
+	ability?: string;
+	displayAs?: string;
+	legendary?: Record<string, string[]>;
+}
+
+// --- Source mapping ---
+
+let sourceDisplayNames: Record<string, string> = {};
+
+export function setSourceDisplayNames(names: Record<string, string>): void {
+	sourceDisplayNames = names;
+}
+
+// --- Size mapping ---
+
+const SIZE_MAP: Record<string, string> = {
+	T: "Tiny",
+	S: "Small",
+	M: "Medium",
+	L: "Large",
+	H: "Huge",
+	G: "Gargantuan",
+};
+
+// --- Alignment mapping ---
+
+const ALIGNMENT_MAP: Record<string, string> = {
+	L: "Lawful",
+	N: "Neutral",
+	C: "Chaotic",
+	G: "Good",
+	E: "Evil",
+	U: "Unaligned",
+};
+
+function formatAlignment(codes?: string[]): string {
+	if (!codes || codes.length === 0) return "Unaligned";
+	if (codes.length === 1 && codes[0] === "U") return "Unaligned";
+	if (codes.length === 1 && codes[0] === "N") return "Neutral";
+	return codes.map((c) => ALIGNMENT_MAP[c] ?? c).join(" ");
+}
+
+// --- Helpers ---
+
+function formatSize(sizes: string[]): string {
+	return sizes.map((s) => SIZE_MAP[s] ?? s).join(" or ");
+}
+
+function formatType(
+	type:
+		| string
+		| {
+				type: string | { choose: string[] };
+				tags?: string[];
+				swarmSize?: string;
+		  },
+): string {
+	if (typeof type === "string") return capitalize(type);
+
+	const baseType =
+		typeof type.type === "string"
+			? capitalize(type.type)
+			: type.type.choose.map(capitalize).join(" or ");
+
+	let result = baseType;
+	if (type.tags && type.tags.length > 0) {
+		const tagStrs = type.tags
+			.filter((t): t is string => typeof t === "string")
+			.map(capitalize);
+		if (tagStrs.length > 0) {
+			result += ` (${tagStrs.join(", ")})`;
+		}
+	}
+	if (type.swarmSize) {
+		const swarmSizeLabel = SIZE_MAP[type.swarmSize] ?? type.swarmSize;
+		result = `Swarm of ${swarmSizeLabel} ${result}s`;
+	}
+	return result;
+}
+
+function capitalize(s: string): string {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function extractAc(ac: RawMonster["ac"]): {
+	value: number;
+	source?: string;
+} {
+	const first = ac[0];
+	if (typeof first === "number") {
+		return { value: first };
+	}
+	if ("special" in first) {
+		// Variable AC (e.g. spell summons) — parse leading number if possible
+		const match = first.special.match(/^(\d+)/);
+		return {
+			value: match ? Number(match[1]) : 0,
+			source: first.special,
+		};
+	}
+	return {
+		value: first.ac,
+		source: first.from ? stripTags(first.from.join(", ")) : undefined,
+	};
+}
+
+function formatSpeed(speed: RawMonster["speed"]): string {
+	const parts: string[] = [];
+	for (const [mode, value] of Object.entries(speed)) {
+		if (mode === "canHover") continue;
+		if (typeof value === "boolean") continue;
+
+		let numStr: string;
+		let condition = "";
+		if (typeof value === "number") {
+			numStr = `${value} ft.`;
+		} else {
+			numStr = `${value.number} ft.`;
+			if (value.condition) {
+				condition = ` ${value.condition}`;
+			}
+		}
+
+		if (mode === "walk") {
+			parts.push(`${numStr}${condition}`);
+		} else {
+			parts.push(`${mode} ${numStr}${condition}`);
+		}
+	}
+	return parts.join(", ");
+}
+
+function formatSaves(save?: Record<string, string>): string | undefined {
+	if (!save) return undefined;
+	return Object.entries(save)
+		.map(([key, val]) => `${key.toUpperCase()} ${val}`)
+		.join(", ");
+}
+
+function formatSkills(skill?: Record<string, string>): string | undefined {
+	if (!skill) return undefined;
+	return Object.entries(skill)
+		.map(([key, val]) => `${capitalize(key)} ${val}`)
+		.join(", ");
+}
+
+function formatDamageList(
+	items?: (string | Record<string, unknown>)[],
+): string | undefined {
+	if (!items || items.length === 0) return undefined;
+	return items
+		.map((item) => {
+			if (typeof item === "string") return capitalize(stripTags(item));
+			if (typeof item.special === "string") return stripTags(item.special);
+			// Handle conditional entries like { vulnerable: [...], note: "..." }
+			const damageTypes = (Object.values(item).find((v) => Array.isArray(v)) ??
+				[]) as string[];
+			const note = typeof item.note === "string" ? ` ${item.note}` : "";
+			return damageTypes.map((d) => capitalize(stripTags(d))).join(", ") + note;
+		})
+		.join(", ");
+}
+
+function formatConditionImmunities(
+	items?: (string | { conditionImmune?: string[]; note?: string })[],
+): string | undefined {
+	if (!items || items.length === 0) return undefined;
+	return items
+		.flatMap((c) => {
+			if (typeof c === "string") return [capitalize(stripTags(c))];
+			if (c.conditionImmune) {
+				const conds = c.conditionImmune.map((ci) => capitalize(stripTags(ci)));
+				const note = c.note ? ` ${c.note}` : "";
+				return conds.map((ci) => `${ci}${note}`);
+			}
+			return [];
+		})
+		.join(", ");
+}
+
+function renderListItem(item: string | RawEntryObject): string | undefined {
+	if (typeof item === "string") {
+		return `• ${stripTags(item)}`;
+	}
+	if (item.name && item.entries) {
+		return `• ${stripTags(item.name)}: ${renderEntries(item.entries)}`;
+	}
+	return undefined;
+}
+
+function renderEntryObject(entry: RawEntryObject, parts: string[]): void {
+	if (entry.type === "list") {
+		for (const item of entry.items ?? []) {
+			const rendered = renderListItem(item);
+			if (rendered) parts.push(rendered);
+		}
+	} else if (entry.type === "item" && entry.name && entry.entries) {
+		parts.push(`${stripTags(entry.name)}: ${renderEntries(entry.entries)}`);
+	} else if (entry.entries) {
+		parts.push(renderEntries(entry.entries));
+	}
+}
+
+function renderEntries(entries: (string | RawEntryObject)[]): string {
+	const parts: string[] = [];
+	for (const entry of entries) {
+		if (typeof entry === "string") {
+			parts.push(stripTags(entry));
+		} else {
+			renderEntryObject(entry, parts);
+		}
+	}
+	return parts.join(" ");
+}
+
+function normalizeTraits(raw?: RawEntry[]): TraitBlock[] | undefined {
+	if (!raw || raw.length === 0) return undefined;
+	return raw.map((t) => ({
+		name: stripTags(t.name),
+		text: renderEntries(t.entries),
+	}));
+}
+
+function normalizeSpellcasting(
+	raw?: RawSpellcasting[],
+): SpellcastingBlock[] | undefined {
+	if (!raw || raw.length === 0) return undefined;
+
+	return raw.map((sc) => {
+		const block: {
+			name: string;
+			headerText: string;
+			atWill?: string[];
+			daily?: DailySpells[];
+			restLong?: DailySpells[];
+		} = {
+			name: stripTags(sc.name),
+			headerText: sc.headerEntries.map((e) => stripTags(e)).join(" "),
+		};
+
+		const hidden = new Set(sc.hidden ?? []);
+
+		if (sc.will && !hidden.has("will")) {
+			block.atWill = sc.will.map((s) => stripTags(s));
+		}
+
+		if (sc.daily) {
+			block.daily = parseDailyMap(sc.daily);
+		}
+
+		if (sc.rest) {
+			block.restLong = parseDailyMap(sc.rest);
+		}
+
+		return block;
+	});
+}
+
+function parseDailyMap(map: Record<string, string[]>): DailySpells[] {
+	return Object.entries(map).map(([key, spells]) => {
+		const each = key.endsWith("e");
+		const uses = Number.parseInt(each ? key.slice(0, -1) : key, 10);
+		return {
+			uses,
+			each,
+			spells: spells.map((s) => stripTags(s)),
+		};
+	});
+}
+
+function normalizeLegendary(
+	raw?: RawEntry[],
+	monster?: RawMonster,
+): LegendaryBlock | undefined {
+	if (!raw || raw.length === 0) return undefined;
+
+	const name = monster?.name ?? "creature";
+	const count = monster?.legendaryActions ?? 3;
+	const preamble = `${name} can take ${count} Legendary Actions, choosing from the options below. Only one Legendary Action can be used at a time and only at the end of another creature's turn. ${name} regains spent Legendary Actions at the start of its turn.`;
+
+	return {
+		preamble,
+		entries: raw.map((e) => ({
+			name: stripTags(e.name),
+			text: renderEntries(e.entries),
+		})),
+	};
+}
+
+function extractCr(cr: string | { cr: string } | undefined): string {
+	if (cr === undefined) return "—";
+	return typeof cr === "string" ? cr : cr.cr;
+}
+
+function makeCreatureId(source: string, name: string): CreatureId {
+	const slug = name
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/(^-|-$)/g, "");
+	return creatureId(`${source.toLowerCase()}:${slug}`);
+}
+
+/**
+ * Normalizes raw 5etools bestiary JSON into domain Creature[].
+ */
+export function normalizeBestiary(raw: { monster: RawMonster[] }): Creature[] {
+	// Filter out _copy entries (reference another source's monster) and
+	// monsters missing required fields (ac, hp, size, type)
+	const monsters = raw.monster.filter((m) => {
+		// biome-ignore lint/suspicious/noExplicitAny: raw JSON may have _copy field
+		if ((m as any)._copy) return false;
+		return (
+			Array.isArray(m.ac) &&
+			m.ac.length > 0 &&
+			m.hp !== undefined &&
+			Array.isArray(m.size) &&
+			m.size.length > 0 &&
+			m.type !== undefined
+		);
+	});
+	const creatures: Creature[] = [];
+	for (const m of monsters) {
+		try {
+			creatures.push(normalizeMonster(m));
+		} catch {
+			// Skip monsters with unexpected data shapes
+		}
+	}
+	return creatures;
+}
+
+function normalizeMonster(m: RawMonster): Creature {
+	const crStr = extractCr(m.cr);
+	const ac = extractAc(m.ac);
+
+	return {
+		id: makeCreatureId(m.source, m.name),
+		name: m.name,
+		source: m.source,
+		sourceDisplayName: sourceDisplayNames[m.source] ?? m.source,
+		size: formatSize(m.size),
+		type: formatType(m.type),
+		alignment: formatAlignment(m.alignment),
+		ac: ac.value,
+		acSource: ac.source,
+		hp: {
+			average: m.hp.average ?? 0,
+			formula: m.hp.formula ?? m.hp.special ?? "",
+		},
+		speed: formatSpeed(m.speed),
+		abilities: {
+			str: m.str,
+			dex: m.dex,
+			con: m.con,
+			int: m.int,
+			wis: m.wis,
+			cha: m.cha,
+		},
+		cr: crStr,
+		initiativeProficiency: m.initiative?.proficiency ?? 0,
+		proficiencyBonus: proficiencyBonus(crStr),
+		passive: m.passive,
+		savingThrows: formatSaves(m.save),
+		skills: formatSkills(m.skill),
+		resist: formatDamageList(m.resist),
+		immune: formatDamageList(m.immune),
+		vulnerable: formatDamageList(m.vulnerable),
+		conditionImmune: formatConditionImmunities(m.conditionImmune),
+		senses:
+			m.senses && m.senses.length > 0
+				? m.senses.map((s) => stripTags(s)).join(", ")
+				: undefined,
+		languages:
+			m.languages && m.languages.length > 0
+				? m.languages.join(", ")
+				: undefined,
+		traits: normalizeTraits(m.trait),
+		actions: normalizeTraits(m.action),
+		bonusActions: normalizeTraits(m.bonus),
+		reactions: normalizeTraits(m.reaction),
+		legendaryActions: normalizeLegendary(m.legendary, m),
+		spellcasting: normalizeSpellcasting(m.spellcasting),
+	};
+}

apps/web/src/adapters/bestiary-cache.ts

@@ -0,0 +1,139 @@
+import type { Creature, CreatureId } from "@initiative/domain";
+import { type IDBPDatabase, openDB } from "idb";
+
+const DB_NAME = "initiative-bestiary";
+const STORE_NAME = "sources";
+const DB_VERSION = 1;
+
+export interface CachedSourceInfo {
+	readonly sourceCode: string;
+	readonly displayName: string;
+	readonly creatureCount: number;
+	readonly cachedAt: number;
+}
+
+interface CachedSourceRecord {
+	sourceCode: string;
+	displayName: string;
+	creatures: Creature[];
+	cachedAt: number;
+	creatureCount: number;
+}
+
+let db: IDBPDatabase | null = null;
+let dbFailed = false;
+
+// In-memory fallback when IndexedDB is unavailable
+const memoryStore = new Map<string, CachedSourceRecord>();
+
+async function getDb(): Promise<IDBPDatabase | null> {
+	if (db) return db;
+	if (dbFailed) return null;
+
+	try {
+		db = await openDB(DB_NAME, DB_VERSION, {
+			upgrade(database) {
+				if (!database.objectStoreNames.contains(STORE_NAME)) {
+					database.createObjectStore(STORE_NAME, {
+						keyPath: "sourceCode",
+					});
+				}
+			},
+		});
+		return db;
+	} catch {
+		dbFailed = true;
+		console.warn(
+			"IndexedDB unavailable — bestiary cache will not persist across sessions.",
+		);
+		return null;
+	}
+}
+
+export async function cacheSource(
+	sourceCode: string,
+	displayName: string,
+	creatures: Creature[],
+): Promise<void> {
+	const record: CachedSourceRecord = {
+		sourceCode,
+		displayName,
+		creatures,
+		cachedAt: Date.now(),
+		creatureCount: creatures.length,
+	};
+
+	const database = await getDb();
+	if (database) {
+		await database.put(STORE_NAME, record);
+	} else {
+		memoryStore.set(sourceCode, record);
+	}
+}
+
+export async function isSourceCached(sourceCode: string): Promise<boolean> {
+	const database = await getDb();
+	if (database) {
+		const record = await database.get(STORE_NAME, sourceCode);
+		return record !== undefined;
+	}
+	return memoryStore.has(sourceCode);
+}
+
+export async function getCachedSources(): Promise<CachedSourceInfo[]> {
+	const database = await getDb();
+	if (database) {
+		const all: CachedSourceRecord[] = await database.getAll(STORE_NAME);
+		return all.map((r) => ({
+			sourceCode: r.sourceCode,
+			displayName: r.displayName,
+			creatureCount: r.creatureCount,
+			cachedAt: r.cachedAt,
+		}));
+	}
+	return [...memoryStore.values()].map((r) => ({
+		sourceCode: r.sourceCode,
+		displayName: r.displayName,
+		creatureCount: r.creatureCount,
+		cachedAt: r.cachedAt,
+	}));
+}
+
+export async function clearSource(sourceCode: string): Promise<void> {
+	const database = await getDb();
+	if (database) {
+		await database.delete(STORE_NAME, sourceCode);
+	} else {
+		memoryStore.delete(sourceCode);
+	}
+}
+
+export async function clearAll(): Promise<void> {
+	const database = await getDb();
+	if (database) {
+		await database.clear(STORE_NAME);
+	} else {
+		memoryStore.clear();
+	}
+}
+
+export async function loadAllCachedCreatures(): Promise<
+	Map<CreatureId, Creature>
+> {
+	const map = new Map<CreatureId, Creature>();
+	const database = await getDb();
+
+	let records: CachedSourceRecord[];
+	if (database) {
+		records = await database.getAll(STORE_NAME);
+	} else {
+		records = [...memoryStore.values()];
+	}
+
+	for (const record of records) {
+		for (const creature of record.creatures) {
+			map.set(creature.id, creature);
+		}
+	}
+	return map;
+}

apps/web/src/adapters/bestiary-index-adapter.ts

@@ -0,0 +1,96 @@
+import type { BestiaryIndex, BestiaryIndexEntry } from "@initiative/domain";
+
+import rawIndex from "../../../../data/bestiary/index.json";
+
+interface CompactCreature {
+	readonly n: string;
+	readonly s: string;
+	readonly ac: number;
+	readonly hp: number;
+	readonly dx: number;
+	readonly cr: string;
+	readonly ip: number;
+	readonly sz: string;
+	readonly tp: string;
+}
+
+interface CompactIndex {
+	readonly sources: Record<string, string>;
+	readonly creatures: readonly CompactCreature[];
+}
+
+function mapCreature(c: CompactCreature): BestiaryIndexEntry {
+	return {
+		name: c.n,
+		source: c.s,
+		ac: c.ac,
+		hp: c.hp,
+		dex: c.dx,
+		cr: c.cr,
+		initiativeProficiency: c.ip,
+		size: c.sz,
+		type: c.tp,
+	};
+}
+
+// Source codes whose filename on the remote differs from a simple lowercase.
+// Plane Shift sources use a hyphen: PSA -> ps-a, etc.
+const FILENAME_OVERRIDES: Record<string, string> = {
+	PSA: "ps-a",
+	PSD: "ps-d",
+	PSI: "ps-i",
+	PSK: "ps-k",
+	PSX: "ps-x",
+	PSZ: "ps-z",
+};
+
+// Source codes with no corresponding remote bestiary file.
+// Excluded from the index entirely so creatures aren't searchable
+// without a fetchable source.
+const EXCLUDED_SOURCES = new Set<string>([]);
+
+let cachedIndex: BestiaryIndex | undefined;
+
+export function loadBestiaryIndex(): BestiaryIndex {
+	if (cachedIndex) return cachedIndex;
+
+	const compact = rawIndex as unknown as CompactIndex;
+	const sources = Object.fromEntries(
+		Object.entries(compact.sources).filter(
+			([code]) => !EXCLUDED_SOURCES.has(code),
+		),
+	);
+	cachedIndex = {
+		sources,
+		creatures: compact.creatures
+			.filter((c) => !EXCLUDED_SOURCES.has(c.s))
+			.map(mapCreature),
+	};
+	return cachedIndex;
+}
+
+export function getAllSourceCodes(): string[] {
+	const index = loadBestiaryIndex();
+	return Object.keys(index.sources).filter((c) => !EXCLUDED_SOURCES.has(c));
+}
+
+function sourceCodeToFilename(sourceCode: string): string {
+	return FILENAME_OVERRIDES[sourceCode] ?? sourceCode.toLowerCase();
+}
+
+export function getDefaultFetchUrl(
+	sourceCode: string,
+	baseUrl?: string,
+): string {
+	const filename = `bestiary-${sourceCodeToFilename(sourceCode)}.json`;
+	if (baseUrl !== undefined) {
+		const normalized = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+		return `${normalized}${filename}`;
+	}
+	return `https://raw.githubusercontent.com/5etools-mirror-3/5etools-src/main/data/bestiary/${filename}`;
+}
+
+export function getSourceDisplayName(sourceCode: string): string {
+	const index = loadBestiaryIndex();
+	return index.sources[sourceCode] ?? sourceCode;
+}

apps/web/src/adapters/strip-tags.ts

@@ -0,0 +1,100 @@
+const ABILITY_MAP: Record<string, string> = {
+	str: "Strength",
+	dex: "Dexterity",
+	con: "Constitution",
+	int: "Intelligence",
+	wis: "Wisdom",
+	cha: "Charisma",
+};
+
+const ATKR_MAP: Record<string, string> = {
+	m: "Melee Attack Roll:",
+	r: "Ranged Attack Roll:",
+	"m,r": "Melee or Ranged Attack Roll:",
+	"r,m": "Melee or Ranged Attack Roll:",
+};
+
+/**
+ * Strips 5etools {@tag ...} markup from text, converting to plain readable text.
+ *
+ * Handles 15+ tag types per research.md R-002 tag resolution rules.
+ */
+export function stripTags(text: string): string {
+	if (typeof text !== "string") return String(text);
+	// Process special tags with specific output formats first
+	let result = text;
+
+	// {@h} → "Hit: "
+	result = result.replace(/\{@h\}/g, "Hit: ");
+
+	// {@hom} → "Hit or Miss: "
+	result = result.replace(/\{@hom\}/g, "Hit or Miss: ");
+
+	// {@actTrigger} → "Trigger:"
+	result = result.replace(/\{@actTrigger\}/g, "Trigger:");
+
+	// {@actResponse} → "Response:"
+	result = result.replace(/\{@actResponse\}/g, "Response:");
+
+	// {@actSaveSuccess} → "Success:"
+	result = result.replace(/\{@actSaveSuccess\}/g, "Success:");
+
+	// {@actSaveSuccessOrFail} → handled below as parameterized
+
+	// {@recharge 5} → "(Recharge 5-6)", {@recharge} → "(Recharge 6)"
+	result = result.replace(/\{@recharge\s+(\d)\}/g, "(Recharge $1-6)");
+	result = result.replace(/\{@recharge\}/g, "(Recharge 6)");
+
+	// {@dc N} → "DC N"
+	result = result.replace(/\{@dc\s+(\d+)\}/g, "DC $1");
+
+	// {@hit N} → "+N"
+	result = result.replace(/\{@hit\s+(\d+)\}/g, "+$1");
+
+	// {@atkr type} → mapped attack roll text
+	result = result.replace(/\{@atkr\s+([^}]+)\}/g, (_, type: string) => {
+		return ATKR_MAP[type.trim()] ?? `Attack Roll:`;
+	});
+
+	// {@actSave ability} → "Ability saving throw"
+	result = result.replace(/\{@actSave\s+([^}]+)\}/g, (_, ability: string) => {
+		const name = ABILITY_MAP[ability.trim().toLowerCase()];
+		return name ? `${name} saving throw` : `${ability} saving throw`;
+	});
+
+	// {@actSaveFail} → "Failure:" or {@actSaveFail N} → "Failure by N or More:"
+	result = result.replace(
+		/\{@actSaveFail\s+(\d+)\}/g,
+		"Failure by $1 or More:",
+	);
+	result = result.replace(/\{@actSaveFail\}/g, "Failure:");
+
+	// {@actSaveSuccessOrFail} → keep as-is label
+	result = result.replace(/\{@actSaveSuccessOrFail\}/g, "Success or Failure:");
+
+	// {@actSaveFailBy N} → "Failure by N or More:"
+	result = result.replace(
+		/\{@actSaveFailBy\s+(\d+)\}/g,
+		"Failure by $1 or More:",
+	);
+
+	// Generic tags: {@tag Display|Source|...} → Display (first segment before |)
+	// Covers: spell, condition, damage, dice, variantrule, action, skill,
+	//         creature, hazard, status, plus any unknown tags
+	result = result.replace(
+		/\{@(\w+)\s+([^}]+)\}/g,
+		(_, tag: string, content: string) => {
+			// For tags with Display|Source format, extract first segment
+			const segments = content.split("|");
+
+			// Some tags have a third segment as display text: {@variantrule Name|Source|Display}
+			if ((tag === "variantrule" || tag === "action") && segments.length >= 3) {
+				return segments[2];
+			}
+
+			return segments[0];
+		},
+	);
+
+	return result;
+}

apps/web/src/components/__tests__/turn-navigation.test.tsx

@@ -0,0 +1,199 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import type { Encounter } from "@initiative/domain";
+import { combatantId } from "@initiative/domain";
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TurnNavigation } from "../turn-navigation";
+
+afterEach(cleanup);
+
+function renderNav(overrides: Partial<Encounter> = {}) {
+	const encounter: Encounter = {
+		combatants: [
+			{ id: combatantId("1"), name: "Goblin" },
+			{ id: combatantId("2"), name: "Conjurer" },
+		],
+		activeIndex: 0,
+		roundNumber: 1,
+		...overrides,
+	};
+
+	return render(
+		<TurnNavigation
+			encounter={encounter}
+			onAdvanceTurn={vi.fn()}
+			onRetreatTurn={vi.fn()}
+			onClearEncounter={vi.fn()}
+		/>,
+	);
+}
+
+describe("TurnNavigation", () => {
+	describe("US1: Round badge and combatant name", () => {
+		it("renders the round badge with correct round number", () => {
+			renderNav({ roundNumber: 3 });
+			expect(screen.getByText("R3")).toBeInTheDocument();
+		});
+
+		it("renders the combatant name separately from the round badge", () => {
+			renderNav();
+			const badge = screen.getByText("R1");
+			const name = screen.getByText("Goblin");
+			expect(badge).toBeInTheDocument();
+			expect(name).toBeInTheDocument();
+			expect(badge).not.toBe(name);
+			expect(badge.closest("[class]")).not.toBe(name.closest("[class]"));
+		});
+
+		it("does not render an em dash between round and name", () => {
+			const { container } = renderNav();
+			expect(container.textContent).not.toContain("—");
+		});
+
+		it("round badge and combatant name are siblings in the center area", () => {
+			renderNav();
+			const badge = screen.getByText("R1");
+			const name = screen.getByText("Goblin");
+			expect(badge.parentElement).toBe(name.parentElement);
+		});
+
+		it("updates the round badge when round changes", () => {
+			const { rerender } = render(
+				<TurnNavigation
+					encounter={{
+						combatants: [{ id: combatantId("1"), name: "Goblin" }],
+						activeIndex: 0,
+						roundNumber: 2,
+					}}
+					onAdvanceTurn={vi.fn()}
+					onRetreatTurn={vi.fn()}
+					onClearEncounter={vi.fn()}
+				/>,
+			);
+			expect(screen.getByText("R2")).toBeInTheDocument();
+
+			rerender(
+				<TurnNavigation
+					encounter={{
+						combatants: [{ id: combatantId("1"), name: "Goblin" }],
+						activeIndex: 0,
+						roundNumber: 3,
+					}}
+					onAdvanceTurn={vi.fn()}
+					onRetreatTurn={vi.fn()}
+					onClearEncounter={vi.fn()}
+				/>,
+			);
+			expect(screen.getByText("R3")).toBeInTheDocument();
+			expect(screen.queryByText("R2")).not.toBeInTheDocument();
+		});
+
+		it("renders the next combatant name when turn advances", () => {
+			const { rerender } = render(
+				<TurnNavigation
+					encounter={{
+						combatants: [
+							{ id: combatantId("1"), name: "Goblin" },
+							{ id: combatantId("2"), name: "Conjurer" },
+						],
+						activeIndex: 0,
+						roundNumber: 1,
+					}}
+					onAdvanceTurn={vi.fn()}
+					onRetreatTurn={vi.fn()}
+					onClearEncounter={vi.fn()}
+				/>,
+			);
+			expect(screen.getByText("Goblin")).toBeInTheDocument();
+
+			rerender(
+				<TurnNavigation
+					encounter={{
+						combatants: [
+							{ id: combatantId("1"), name: "Goblin" },
+							{ id: combatantId("2"), name: "Conjurer" },
+						],
+						activeIndex: 1,
+						roundNumber: 1,
+					}}
+					onAdvanceTurn={vi.fn()}
+					onRetreatTurn={vi.fn()}
+					onClearEncounter={vi.fn()}
+				/>,
+			);
+			expect(screen.getByText("Conjurer")).toBeInTheDocument();
+		});
+	});
+
+	describe("US2: Layout robustness", () => {
+		it("applies truncation styles to long combatant names", () => {
+			const longName =
+				"Ancient Red Dragon Wyrm of the Northern Wastes and Beyond";
+			renderNav({
+				combatants: [{ id: combatantId("1"), name: longName }],
+			});
+			const nameEl = screen.getByText(longName);
+			expect(nameEl.className).toContain("truncate");
+		});
+
+		it("renders three-zone layout with a single-character name", () => {
+			renderNav({
+				combatants: [{ id: combatantId("1"), name: "O" }],
+			});
+			expect(screen.getByText("R1")).toBeInTheDocument();
+			expect(screen.getByText("O")).toBeInTheDocument();
+			expect(
+				screen.getByRole("button", { name: "Previous turn" }),
+			).toBeInTheDocument();
+			expect(
+				screen.getByRole("button", { name: "Next turn" }),
+			).toBeInTheDocument();
+		});
+
+		it("keeps all action buttons accessible regardless of name length", () => {
+			const longName = "A".repeat(60);
+			renderNav({
+				combatants: [{ id: combatantId("1"), name: longName }],
+			});
+			expect(
+				screen.getByRole("button", { name: "Previous turn" }),
+			).toBeInTheDocument();
+			expect(
+				screen.getByRole("button", { name: "Next turn" }),
+			).toBeInTheDocument();
+		});
+
+		it("renders a 40-character name without truncation class issues", () => {
+			const name40 = "A".repeat(40);
+			renderNav({
+				combatants: [{ id: combatantId("1"), name: name40 }],
+			});
+			const nameEl = screen.getByText(name40);
+			expect(nameEl).toBeInTheDocument();
+			// The truncate class is applied but CSS only visually truncates if content overflows
+			expect(nameEl.className).toContain("truncate");
+		});
+	});
+
+	describe("US3: No combatants state", () => {
+		it("shows the round badge when there are no combatants", () => {
+			renderNav({ combatants: [], roundNumber: 1 });
+			expect(screen.getByText("R1")).toBeInTheDocument();
+		});
+
+		it("shows 'No combatants' placeholder text", () => {
+			renderNav({ combatants: [] });
+			expect(screen.getByText("No combatants")).toBeInTheDocument();
+		});
+
+		it("disables navigation buttons when there are no combatants", () => {
+			renderNav({ combatants: [] });
+			expect(
+				screen.getByRole("button", { name: "Previous turn" }),
+			).toBeDisabled();
+			expect(screen.getByRole("button", { name: "Next turn" })).toBeDisabled();
+		});
+	});
+});

apps/web/src/components/ac-shield.tsx

@@ -0,0 +1,37 @@
+import { cn } from "../lib/utils";
+
+interface AcShieldProps {
+	readonly value: number | undefined;
+	readonly onClick?: () => void;
+	readonly className?: string;
+}
+
+export function AcShield({ value, onClick, className }: AcShieldProps) {
+	return (
+		<button
+			type="button"
+			onClick={onClick}
+			className={cn(
+				"relative inline-flex items-center justify-center text-sm tabular-nums text-muted-foreground transition-colors hover:text-hover-neutral",
+				className,
+			)}
+			style={{ width: 28, height: 32 }}
+		>
+			<svg
+				viewBox="0 0 28 32"
+				fill="none"
+				stroke="currentColor"
+				strokeWidth={1.5}
+				strokeLinecap="round"
+				strokeLinejoin="round"
+				className="absolute inset-0 h-full w-full"
+				aria-hidden="true"
+			>
+				<path d="M14 1.5 L2.5 6.5 L2.5 15 Q2.5 25 14 30.5 Q25.5 25 25.5 15 L25.5 6.5 Z" />
+			</svg>
+			<span className="relative text-xs font-medium leading-none">
+				{value !== undefined ? value : "\u2014"}
+			</span>
+		</button>
+	);
+}

apps/web/src/components/action-bar.tsx

@@ -0,0 +1,582 @@
+import type { PlayerCharacter, PlayerIcon } from "@initiative/domain";
+import {
+	Check,
+	Eye,
+	EyeOff,
+	Import,
+	Library,
+	Minus,
+	Plus,
+	Users,
+} from "lucide-react";
+import { type FormEvent, type RefObject, useState } from "react";
+import type { SearchResult } from "../hooks/use-bestiary.js";
+import { cn } from "../lib/utils.js";
+import { D20Icon } from "./d20-icon.js";
+import { PLAYER_COLOR_HEX, PLAYER_ICON_MAP } from "./player-icon-map";
+import { Button } from "./ui/button.js";
+import { Input } from "./ui/input.js";
+import { OverflowMenu, type OverflowMenuItem } from "./ui/overflow-menu.js";
+
+interface QueuedCreature {
+	result: SearchResult;
+	count: number;
+}
+
+interface ActionBarProps {
+	onAddCombatant: (
+		name: string,
+		opts?: { initiative?: number; ac?: number; maxHp?: number },
+	) => void;
+	onAddFromBestiary: (result: SearchResult) => void;
+	bestiarySearch: (query: string) => SearchResult[];
+	bestiaryLoaded: boolean;
+	onViewStatBlock?: (result: SearchResult) => void;
+	onBulkImport?: () => void;
+	bulkImportDisabled?: boolean;
+	inputRef?: RefObject<HTMLInputElement | null>;
+	playerCharacters?: readonly PlayerCharacter[];
+	onAddFromPlayerCharacter?: (pc: PlayerCharacter) => void;
+	onManagePlayers?: () => void;
+	onRollAllInitiative?: () => void;
+	showRollAllInitiative?: boolean;
+	onOpenSourceManager?: () => void;
+	autoFocus?: boolean;
+}
+
+function creatureKey(r: SearchResult): string {
+	return `${r.source}:${r.name}`;
+}
+
+function AddModeSuggestions({
+	nameInput,
+	suggestions,
+	pcMatches,
+	suggestionIndex,
+	queued,
+	onDismiss,
+	onClickSuggestion,
+	onSetSuggestionIndex,
+	onSetQueued,
+	onConfirmQueued,
+	onAddFromPlayerCharacter,
+}: {
+	nameInput: string;
+	suggestions: SearchResult[];
+	pcMatches: PlayerCharacter[];
+	suggestionIndex: number;
+	queued: QueuedCreature | null;
+	onDismiss: () => void;
+	onClickSuggestion: (result: SearchResult) => void;
+	onSetSuggestionIndex: (i: number) => void;
+	onSetQueued: (q: QueuedCreature | null) => void;
+	onConfirmQueued: () => void;
+	onAddFromPlayerCharacter?: (pc: PlayerCharacter) => void;
+}) {
+	return (
+		<div className="absolute bottom-full z-50 mb-1 w-full max-w-xs rounded-md border border-border bg-card shadow-lg">
+			<button
+				type="button"
+				className="flex w-full items-center gap-1.5 border-b border-border px-3 py-2 text-left text-sm text-accent hover:bg-accent/20"
+				onMouseDown={(e) => e.preventDefault()}
+				onClick={onDismiss}
+			>
+				<Plus className="h-3.5 w-3.5" />
+				<span className="flex-1">Add "{nameInput}" as custom</span>
+				<kbd className="rounded border border-border px-1.5 py-0.5 text-xs text-muted-foreground">
+					Esc
+				</kbd>
+			</button>
+			<div className="max-h-48 overflow-y-auto py-1">
+				{pcMatches.length > 0 && (
+					<>
+						<div className="px-3 py-1 text-xs font-medium text-muted-foreground">
+							Players
+						</div>
+						<ul>
+							{pcMatches.map((pc) => {
+								const PcIcon = PLAYER_ICON_MAP[pc.icon as PlayerIcon];
+								const pcColor =
+									PLAYER_COLOR_HEX[pc.color as keyof typeof PLAYER_COLOR_HEX];
+								return (
+									<li key={pc.id}>
+										<button
+											type="button"
+											className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-sm text-foreground hover:bg-hover-neutral-bg"
+											onMouseDown={(e) => e.preventDefault()}
+											onClick={() => {
+												onAddFromPlayerCharacter?.(pc);
+												onDismiss();
+											}}
+										>
+											{PcIcon && (
+												<PcIcon size={14} style={{ color: pcColor }} />
+											)}
+											<span className="flex-1 truncate">{pc.name}</span>
+											<span className="text-xs text-muted-foreground">
+												Player
+											</span>
+										</button>
+									</li>
+								);
+							})}
+						</ul>
+					</>
+				)}
+				{suggestions.length > 0 && (
+					<ul>
+						{suggestions.map((result, i) => {
+							const key = creatureKey(result);
+							const isQueued =
+								queued !== null && creatureKey(queued.result) === key;
+							return (
+								<li key={key}>
+									<button
+										type="button"
+										className={`flex w-full items-center justify-between px-3 py-1.5 text-left text-sm ${
+											isQueued
+												? "bg-accent/30 text-foreground"
+												: i === suggestionIndex
+													? "bg-accent/20 text-foreground"
+													: "text-foreground hover:bg-hover-neutral-bg"
+										}`}
+										onMouseDown={(e) => e.preventDefault()}
+										onClick={() => onClickSuggestion(result)}
+										onMouseEnter={() => onSetSuggestionIndex(i)}
+									>
+										<span>{result.name}</span>
+										<span className="flex items-center gap-1 text-xs text-muted-foreground">
+											{isQueued ? (
+												<>
+													<button
+														type="button"
+														className="rounded p-0.5 text-foreground hover:bg-accent/40"
+														onMouseDown={(e) => e.preventDefault()}
+														onClick={(e) => {
+															e.stopPropagation();
+															if (queued.count <= 1) {
+																onSetQueued(null);
+															} else {
+																onSetQueued({
+																	...queued,
+																	count: queued.count - 1,
+																});
+															}
+														}}
+													>
+														<Minus className="h-3 w-3" />
+													</button>
+													<span className="min-w-5 rounded-full bg-accent px-1.5 py-0.5 text-center font-medium text-foreground">
+														{queued.count}
+													</span>
+													<button
+														type="button"
+														className="rounded p-0.5 text-foreground hover:bg-accent/40"
+														onMouseDown={(e) => e.preventDefault()}
+														onClick={(e) => {
+															e.stopPropagation();
+															onSetQueued({
+																...queued,
+																count: queued.count + 1,
+															});
+														}}
+													>
+														<Plus className="h-3 w-3" />
+													</button>
+													<button
+														type="button"
+														className="ml-0.5 rounded p-0.5 text-foreground hover:bg-accent/40"
+														onMouseDown={(e) => e.preventDefault()}
+														onClick={(e) => {
+															e.stopPropagation();
+															onConfirmQueued();
+														}}
+													>
+														<Check className="h-3.5 w-3.5" />
+													</button>
+												</>
+											) : (
+												result.sourceDisplayName
+											)}
+										</span>
+									</button>
+								</li>
+							);
+						})}
+					</ul>
+				)}
+			</div>
+		</div>
+	);
+}
+
+function buildOverflowItems(opts: {
+	onManagePlayers?: () => void;
+	onOpenSourceManager?: () => void;
+	bestiaryLoaded: boolean;
+	onBulkImport?: () => void;
+	bulkImportDisabled?: boolean;
+}): OverflowMenuItem[] {
+	const items: OverflowMenuItem[] = [];
+	if (opts.onManagePlayers) {
+		items.push({
+			icon: <Users className="h-4 w-4" />,
+			label: "Player Characters",
+			onClick: opts.onManagePlayers,
+		});
+	}
+	if (opts.onOpenSourceManager) {
+		items.push({
+			icon: <Library className="h-4 w-4" />,
+			label: "Manage Sources",
+			onClick: opts.onOpenSourceManager,
+		});
+	}
+	if (opts.bestiaryLoaded && opts.onBulkImport) {
+		items.push({
+			icon: <Import className="h-4 w-4" />,
+			label: "Bulk Import",
+			onClick: opts.onBulkImport,
+			disabled: opts.bulkImportDisabled,
+		});
+	}
+	return items;
+}
+
+export function ActionBar({
+	onAddCombatant,
+	onAddFromBestiary,
+	bestiarySearch,
+	bestiaryLoaded,
+	onViewStatBlock,
+	onBulkImport,
+	bulkImportDisabled,
+	inputRef,
+	playerCharacters,
+	onAddFromPlayerCharacter,
+	onManagePlayers,
+	onRollAllInitiative,
+	showRollAllInitiative,
+	onOpenSourceManager,
+	autoFocus,
+}: ActionBarProps) {
+	const [nameInput, setNameInput] = useState("");
+	const [suggestions, setSuggestions] = useState<SearchResult[]>([]);
+	const [pcMatches, setPcMatches] = useState<PlayerCharacter[]>([]);
+	const [suggestionIndex, setSuggestionIndex] = useState(-1);
+	const [queued, setQueued] = useState<QueuedCreature | null>(null);
+	const [customInit, setCustomInit] = useState("");
+	const [customAc, setCustomAc] = useState("");
+	const [customMaxHp, setCustomMaxHp] = useState("");
+	const [browseMode, setBrowseMode] = useState(false);
+
+	const clearCustomFields = () => {
+		setCustomInit("");
+		setCustomAc("");
+		setCustomMaxHp("");
+	};
+
+	const clearInput = () => {
+		setNameInput("");
+		setSuggestions([]);
+		setPcMatches([]);
+		setQueued(null);
+		setSuggestionIndex(-1);
+	};
+
+	const dismissSuggestions = () => {
+		setSuggestions([]);
+		setPcMatches([]);
+		setQueued(null);
+		setSuggestionIndex(-1);
+	};
+
+	const confirmQueued = () => {
+		if (!queued) return;
+		for (let i = 0; i < queued.count; i++) {
+			onAddFromBestiary(queued.result);
+		}
+		clearInput();
+	};
+
+	const parseNum = (v: string): number | undefined => {
+		if (v.trim() === "") return undefined;
+		const n = Number(v);
+		return Number.isNaN(n) ? undefined : n;
+	};
+
+	const handleAdd = (e: FormEvent) => {
+		e.preventDefault();
+		if (browseMode) return;
+		if (queued) {
+			confirmQueued();
+			return;
+		}
+		if (nameInput.trim() === "") return;
+		const opts: { initiative?: number; ac?: number; maxHp?: number } = {};
+		const init = parseNum(customInit);
+		const ac = parseNum(customAc);
+		const maxHp = parseNum(customMaxHp);
+		if (init !== undefined) opts.initiative = init;
+		if (ac !== undefined) opts.ac = ac;
+		if (maxHp !== undefined) opts.maxHp = maxHp;
+		onAddCombatant(nameInput, Object.keys(opts).length > 0 ? opts : undefined);
+		setNameInput("");
+		setSuggestions([]);
+		setPcMatches([]);
+		clearCustomFields();
+	};
+
+	const handleBrowseSearch = (value: string) => {
+		setSuggestions(value.length >= 2 ? bestiarySearch(value) : []);
+	};
+
+	const handleAddSearch = (value: string) => {
+		let newSuggestions: SearchResult[] = [];
+		let newPcMatches: PlayerCharacter[] = [];
+		if (value.length >= 2) {
+			newSuggestions = bestiarySearch(value);
+			setSuggestions(newSuggestions);
+			if (playerCharacters && playerCharacters.length > 0) {
+				const lower = value.toLowerCase();
+				newPcMatches = playerCharacters.filter((pc) =>
+					pc.name.toLowerCase().includes(lower),
+				);
+			}
+			setPcMatches(newPcMatches);
+		} else {
+			setSuggestions([]);
+			setPcMatches([]);
+		}
+		if (newSuggestions.length > 0 || newPcMatches.length > 0) {
+			clearCustomFields();
+		}
+		if (queued) {
+			const qKey = creatureKey(queued.result);
+			const stillVisible = newSuggestions.some((s) => creatureKey(s) === qKey);
+			if (!stillVisible) {
+				setQueued(null);
+			}
+		}
+	};
+
+	const handleNameChange = (value: string) => {
+		setNameInput(value);
+		setSuggestionIndex(-1);
+		if (browseMode) {
+			handleBrowseSearch(value);
+		} else {
+			handleAddSearch(value);
+		}
+	};
+
+	const handleClickSuggestion = (result: SearchResult) => {
+		const key = creatureKey(result);
+		if (queued && creatureKey(queued.result) === key) {
+			setQueued({ ...queued, count: queued.count + 1 });
+		} else {
+			setQueued({ result, count: 1 });
+		}
+	};
+
+	const handleEnter = () => {
+		if (queued) {
+			confirmQueued();
+		} else if (suggestionIndex >= 0) {
+			handleClickSuggestion(suggestions[suggestionIndex]);
+		}
+	};
+
+	const hasSuggestions = suggestions.length > 0 || pcMatches.length > 0;
+
+	const handleKeyDown = (e: React.KeyboardEvent) => {
+		if (!hasSuggestions) return;
+
+		if (e.key === "ArrowDown") {
+			e.preventDefault();
+			setSuggestionIndex((i) => (i < suggestions.length - 1 ? i + 1 : 0));
+		} else if (e.key === "ArrowUp") {
+			e.preventDefault();
+			setSuggestionIndex((i) => (i > 0 ? i - 1 : suggestions.length - 1));
+		} else if (e.key === "Enter") {
+			e.preventDefault();
+			handleEnter();
+		} else if (e.key === "Escape") {
+			dismissSuggestions();
+		}
+	};
+
+	const handleBrowseKeyDown = (e: React.KeyboardEvent) => {
+		if (e.key === "Escape") {
+			setBrowseMode(false);
+			clearInput();
+			return;
+		}
+		if (suggestions.length === 0) return;
+		if (e.key === "ArrowDown") {
+			e.preventDefault();
+			setSuggestionIndex((i) => (i < suggestions.length - 1 ? i + 1 : 0));
+		} else if (e.key === "ArrowUp") {
+			e.preventDefault();
+			setSuggestionIndex((i) => (i > 0 ? i - 1 : suggestions.length - 1));
+		} else if (e.key === "Enter" && suggestionIndex >= 0) {
+			e.preventDefault();
+			onViewStatBlock?.(suggestions[suggestionIndex]);
+			setBrowseMode(false);
+			clearInput();
+		}
+	};
+
+	const handleBrowseSelect = (result: SearchResult) => {
+		onViewStatBlock?.(result);
+		setBrowseMode(false);
+		clearInput();
+	};
+
+	const toggleBrowseMode = () => {
+		setBrowseMode((m) => !m);
+		clearInput();
+		clearCustomFields();
+	};
+
+	const overflowItems = buildOverflowItems({
+		onManagePlayers,
+		onOpenSourceManager,
+		bestiaryLoaded,
+		onBulkImport,
+		bulkImportDisabled,
+	});
+
+	return (
+		<div className="flex items-center gap-3 rounded-md border border-border bg-card px-4 py-3">
+			<form
+				onSubmit={handleAdd}
+				className="relative flex flex-1 items-center gap-2"
+			>
+				<div className="flex-1">
+					<div className="relative max-w-xs">
+						<Input
+							ref={inputRef}
+							type="text"
+							value={nameInput}
+							onChange={(e) => handleNameChange(e.target.value)}
+							onKeyDown={browseMode ? handleBrowseKeyDown : handleKeyDown}
+							placeholder={
+								browseMode ? "Search stat blocks..." : "+ Add combatants"
+							}
+							className="pr-8"
+							autoFocus={autoFocus}
+						/>
+						{bestiaryLoaded && onViewStatBlock && (
+							<button
+								type="button"
+								tabIndex={-1}
+								className={cn(
+									"absolute right-2 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-hover-neutral",
+									browseMode && "text-accent",
+								)}
+								onClick={toggleBrowseMode}
+								title={browseMode ? "Switch to add mode" : "Browse stat blocks"}
+								aria-label={
+									browseMode ? "Switch to add mode" : "Browse stat blocks"
+								}
+							>
+								{browseMode ? (
+									<EyeOff className="h-4 w-4" />
+								) : (
+									<Eye className="h-4 w-4" />
+								)}
+							</button>
+						)}
+						{browseMode && suggestions.length > 0 && (
+							<div className="absolute bottom-full z-50 mb-1 w-full rounded-md border border-border bg-card shadow-lg">
+								<ul className="max-h-48 overflow-y-auto py-1">
+									{suggestions.map((result, i) => (
+										<li key={creatureKey(result)}>
+											<button
+												type="button"
+												className={`flex w-full items-center justify-between px-3 py-1.5 text-left text-sm ${
+													i === suggestionIndex
+														? "bg-accent/20 text-foreground"
+														: "text-foreground hover:bg-hover-neutral-bg"
+												}`}
+												onMouseDown={(e) => e.preventDefault()}
+												onClick={() => handleBrowseSelect(result)}
+												onMouseEnter={() => setSuggestionIndex(i)}
+											>
+												<span>{result.name}</span>
+												<span className="text-xs text-muted-foreground">
+													{result.sourceDisplayName}
+												</span>
+											</button>
+										</li>
+									))}
+								</ul>
+							</div>
+						)}
+						{!browseMode && hasSuggestions && (
+							<AddModeSuggestions
+								nameInput={nameInput}
+								suggestions={suggestions}
+								pcMatches={pcMatches}
+								suggestionIndex={suggestionIndex}
+								queued={queued}
+								onDismiss={dismissSuggestions}
+								onClickSuggestion={handleClickSuggestion}
+								onSetSuggestionIndex={setSuggestionIndex}
+								onSetQueued={setQueued}
+								onConfirmQueued={confirmQueued}
+								onAddFromPlayerCharacter={onAddFromPlayerCharacter}
+							/>
+						)}
+					</div>
+				</div>
+				{!browseMode && nameInput.length >= 2 && !hasSuggestions && (
+					<div className="flex items-center gap-2">
+						<Input
+							type="text"
+							inputMode="numeric"
+							value={customInit}
+							onChange={(e) => setCustomInit(e.target.value)}
+							placeholder="Init"
+							className="w-16 text-center"
+						/>
+						<Input
+							type="text"
+							inputMode="numeric"
+							value={customAc}
+							onChange={(e) => setCustomAc(e.target.value)}
+							placeholder="AC"
+							className="w-16 text-center"
+						/>
+						<Input
+							type="text"
+							inputMode="numeric"
+							value={customMaxHp}
+							onChange={(e) => setCustomMaxHp(e.target.value)}
+							placeholder="MaxHP"
+							className="w-18 text-center"
+						/>
+					</div>
+				)}
+				{!browseMode && nameInput.length >= 2 && !hasSuggestions && (
+					<Button type="submit">Add</Button>
+				)}
+				{showRollAllInitiative && onRollAllInitiative && (
+					<Button
+						type="button"
+						size="icon"
+						variant="ghost"
+						className="text-muted-foreground hover:text-hover-action"
+						onClick={onRollAllInitiative}
+						title="Roll all initiative"
+						aria-label="Roll all initiative"
+					>
+						<D20Icon className="h-6 w-6" />
+					</Button>
+				)}
+				{overflowItems.length > 0 && <OverflowMenu items={overflowItems} />}
+			</form>
+		</div>
+	);
+}

apps/web/src/components/bulk-import-prompt.tsx

@@ -0,0 +1,107 @@
+import { Loader2 } from "lucide-react";
+import { useState } from "react";
+import { getAllSourceCodes } from "../adapters/bestiary-index-adapter.js";
+import type { BulkImportState } from "../hooks/use-bulk-import.js";
+import { Button } from "./ui/button.js";
+import { Input } from "./ui/input.js";
+
+const DEFAULT_BASE_URL =
+	"https://raw.githubusercontent.com/5etools-mirror-3/5etools-src/main/data/bestiary/";
+
+interface BulkImportPromptProps {
+	importState: BulkImportState;
+	onStartImport: (baseUrl: string) => void;
+	onDone: () => void;
+}
+
+export function BulkImportPrompt({
+	importState,
+	onStartImport,
+	onDone,
+}: BulkImportPromptProps) {
+	const [baseUrl, setBaseUrl] = useState(DEFAULT_BASE_URL);
+	const totalSources = getAllSourceCodes().length;
+
+	if (importState.status === "complete") {
+		return (
+			<div className="flex flex-col gap-4">
+				<div className="rounded-md border border-green-500/50 bg-green-500/10 px-3 py-2 text-sm text-green-400">
+					All sources loaded
+				</div>
+				<Button onClick={onDone}>Done</Button>
+			</div>
+		);
+	}
+
+	if (importState.status === "partial-failure") {
+		return (
+			<div className="flex flex-col gap-4">
+				<div className="rounded-md border border-yellow-500/50 bg-yellow-500/10 px-3 py-2 text-sm text-yellow-400">
+					Loaded {importState.completed}/{importState.total} sources (
+					{importState.failed} failed)
+				</div>
+				<Button onClick={onDone}>Done</Button>
+			</div>
+		);
+	}
+
+	if (importState.status === "loading") {
+		const processed = importState.completed + importState.failed;
+		const pct =
+			importState.total > 0
+				? Math.round((processed / importState.total) * 100)
+				: 0;
+
+		return (
+			<div className="flex flex-col gap-4">
+				<div className="flex items-center gap-2 text-sm text-muted-foreground">
+					<Loader2 className="h-4 w-4 animate-spin" />
+					Loading sources... {processed}/{importState.total}
+				</div>
+				<div className="h-2 overflow-hidden rounded-full bg-muted">
+					<div
+						className="h-full rounded-full bg-primary transition-all"
+						style={{ width: `${pct}%` }}
+					/>
+				</div>
+			</div>
+		);
+	}
+
+	// idle state
+	const isDisabled = !baseUrl.trim() || importState.status !== "idle";
+
+	return (
+		<div className="flex flex-col gap-4">
+			<div>
+				<h3 className="text-sm font-semibold text-foreground">
+					Bulk Import Sources
+				</h3>
+				<p className="mt-1 text-xs text-muted-foreground">
+					Load stat block data for all {totalSources} sources at once. This will
+					download approximately 12.5 MB of data.
+				</p>
+			</div>
+
+			<div className="flex flex-col gap-2">
+				<label
+					htmlFor="bulk-base-url"
+					className="text-xs text-muted-foreground"
+				>
+					Base URL
+				</label>
+				<Input
+					id="bulk-base-url"
+					type="url"
+					value={baseUrl}
+					onChange={(e) => setBaseUrl(e.target.value)}
+					className="text-xs"
+				/>
+			</div>
+
+			<Button onClick={() => onStartImport(baseUrl)} disabled={isDisabled}>
+				Load All
+			</Button>
+		</div>
+	);
+}

apps/web/src/components/color-palette.tsx

@@ -0,0 +1,36 @@
+import { VALID_PLAYER_COLORS } from "@initiative/domain";
+import { cn } from "../lib/utils";
+import { PLAYER_COLOR_HEX } from "./player-icon-map";
+
+interface ColorPaletteProps {
+	value: string;
+	onChange: (color: string) => void;
+}
+
+const COLORS = [...VALID_PLAYER_COLORS] as string[];
+
+export function ColorPalette({ value, onChange }: ColorPaletteProps) {
+	return (
+		<div className="flex flex-wrap gap-2">
+			{COLORS.map((color) => (
+				<button
+					key={color}
+					type="button"
+					onClick={() => onChange(color)}
+					className={cn(
+						"h-8 w-8 rounded-full transition-all",
+						value === color
+							? "ring-2 ring-foreground ring-offset-2 ring-offset-background scale-110"
+							: "hover:scale-110",
+					)}
+					style={{
+						backgroundColor:
+							PLAYER_COLOR_HEX[color as keyof typeof PLAYER_COLOR_HEX],
+					}}
+					aria-label={color}
+					title={color}
+				/>
+			))}
+		</div>
+	);
+}

apps/web/src/components/combatant-row.tsx

@@ -0,0 +1,634 @@
+import {
+	type CombatantId,
+	type ConditionId,
+	deriveHpStatus,
+	type PlayerIcon,
+} from "@initiative/domain";
+import { Brain, X } from "lucide-react";
+import { type Ref, useCallback, useEffect, useRef, useState } from "react";
+import { cn } from "../lib/utils";
+import { AcShield } from "./ac-shield";
+import { ConditionPicker } from "./condition-picker";
+import { ConditionTags } from "./condition-tags";
+import { D20Icon } from "./d20-icon";
+import { HpAdjustPopover } from "./hp-adjust-popover";
+import { PLAYER_COLOR_HEX, PLAYER_ICON_MAP } from "./player-icon-map";
+import { ConfirmButton } from "./ui/confirm-button";
+import { Input } from "./ui/input";
+
+interface Combatant {
+	readonly id: CombatantId;
+	readonly name: string;
+	readonly initiative?: number;
+	readonly maxHp?: number;
+	readonly currentHp?: number;
+	readonly ac?: number;
+	readonly conditions?: readonly ConditionId[];
+	readonly isConcentrating?: boolean;
+	readonly color?: string;
+	readonly icon?: string;
+}
+
+interface CombatantRowProps {
+	combatant: Combatant;
+	isActive: boolean;
+	onRename: (id: CombatantId, newName: string) => void;
+	onSetInitiative: (id: CombatantId, value: number | undefined) => void;
+	onRemove: (id: CombatantId) => void;
+	onSetHp: (id: CombatantId, maxHp: number | undefined) => void;
+	onAdjustHp: (id: CombatantId, delta: number) => void;
+	onSetAc: (id: CombatantId, value: number | undefined) => void;
+	onToggleCondition: (id: CombatantId, conditionId: ConditionId) => void;
+	onToggleConcentration: (id: CombatantId) => void;
+	onShowStatBlock?: () => void;
+	onRollInitiative?: (id: CombatantId) => void;
+}
+
+function EditableName({
+	name,
+	combatantId,
+	onRename,
+	onShowStatBlock,
+	color,
+}: {
+	name: string;
+	combatantId: CombatantId;
+	onRename: (id: CombatantId, newName: string) => void;
+	onShowStatBlock?: () => void;
+	color?: string;
+}) {
+	const [editing, setEditing] = useState(false);
+	const [draft, setDraft] = useState(name);
+	const inputRef = useRef<HTMLInputElement>(null);
+	const clickTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+	const longPressTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+	const longPressTriggeredRef = useRef(false);
+
+	const commit = useCallback(() => {
+		const trimmed = draft.trim();
+		if (trimmed !== "" && trimmed !== name) {
+			onRename(combatantId, trimmed);
+		}
+		setEditing(false);
+	}, [draft, name, combatantId, onRename]);
+
+	const startEditing = useCallback(() => {
+		setDraft(name);
+		setEditing(true);
+		requestAnimationFrame(() => inputRef.current?.select());
+	}, [name]);
+
+	useEffect(() => {
+		return () => {
+			clearTimeout(clickTimerRef.current);
+			clearTimeout(longPressTimerRef.current);
+		};
+	}, []);
+
+	const handleClick = useCallback(
+		(e: React.MouseEvent) => {
+			e.stopPropagation();
+			if (longPressTriggeredRef.current) {
+				longPressTriggeredRef.current = false;
+				return;
+			}
+			if (clickTimerRef.current) {
+				clearTimeout(clickTimerRef.current);
+				clickTimerRef.current = undefined;
+				startEditing();
+			} else {
+				clickTimerRef.current = setTimeout(() => {
+					clickTimerRef.current = undefined;
+					onShowStatBlock?.();
+				}, 250);
+			}
+		},
+		[startEditing, onShowStatBlock],
+	);
+
+	const handleTouchStart = useCallback(() => {
+		longPressTriggeredRef.current = false;
+		longPressTimerRef.current = setTimeout(() => {
+			longPressTriggeredRef.current = true;
+			startEditing();
+		}, 500);
+	}, [startEditing]);
+
+	const cancelLongPress = useCallback(() => {
+		clearTimeout(longPressTimerRef.current);
+	}, []);
+
+	if (editing) {
+		return (
+			<Input
+				ref={inputRef}
+				type="text"
+				value={draft}
+				className="h-7 text-sm"
+				onChange={(e) => setDraft(e.target.value)}
+				onBlur={commit}
+				onKeyDown={(e) => {
+					if (e.key === "Enter") commit();
+					if (e.key === "Escape") setEditing(false);
+				}}
+			/>
+		);
+	}
+
+	return (
+		<>
+			<button
+				type="button"
+				onClick={handleClick}
+				onTouchStart={handleTouchStart}
+				onTouchEnd={cancelLongPress}
+				onTouchCancel={cancelLongPress}
+				onTouchMove={cancelLongPress}
+				className="truncate text-left text-sm text-foreground cursor-text hover:text-hover-neutral transition-colors"
+				style={color ? { color } : undefined}
+			>
+				{name}
+			</button>
+		</>
+	);
+}
+
+function MaxHpDisplay({
+	maxHp,
+	onCommit,
+}: {
+	maxHp: number | undefined;
+	onCommit: (value: number | undefined) => void;
+}) {
+	const [editing, setEditing] = useState(false);
+	const [draft, setDraft] = useState(maxHp?.toString() ?? "");
+	const inputRef = useRef<HTMLInputElement>(null);
+
+	const commit = useCallback(() => {
+		if (draft === "") {
+			onCommit(undefined);
+		} else {
+			const n = Number.parseInt(draft, 10);
+			if (!Number.isNaN(n) && n >= 1) {
+				onCommit(n);
+			}
+		}
+		setEditing(false);
+	}, [draft, onCommit]);
+
+	const startEditing = useCallback(() => {
+		setDraft(maxHp?.toString() ?? "");
+		setEditing(true);
+		requestAnimationFrame(() => inputRef.current?.select());
+	}, [maxHp]);
+
+	if (editing) {
+		return (
+			<Input
+				ref={inputRef}
+				type="text"
+				inputMode="numeric"
+				value={draft}
+				placeholder="Max"
+				className="h-7 w-[7ch] text-center text-sm tabular-nums"
+				onChange={(e) => setDraft(e.target.value)}
+				onBlur={commit}
+				onKeyDown={(e) => {
+					if (e.key === "Enter") commit();
+					if (e.key === "Escape") setEditing(false);
+				}}
+			/>
+		);
+	}
+
+	return (
+		<button
+			type="button"
+			onClick={startEditing}
+			className="inline-block h-7 min-w-[3ch] text-center text-sm leading-7 tabular-nums text-muted-foreground transition-colors hover:text-hover-neutral"
+		>
+			{maxHp ?? "Max"}
+		</button>
+	);
+}
+
+function ClickableHp({
+	currentHp,
+	maxHp,
+	onAdjust,
+	dimmed,
+}: {
+	currentHp: number | undefined;
+	maxHp: number | undefined;
+	onAdjust: (delta: number) => void;
+	dimmed?: boolean;
+}) {
+	const [popoverOpen, setPopoverOpen] = useState(false);
+	const status = deriveHpStatus(currentHp, maxHp);
+
+	if (maxHp === undefined) {
+		return (
+			<span
+				className={cn(
+					"inline-block h-7 w-[4ch] text-center text-sm leading-7 tabular-nums text-muted-foreground",
+					dimmed && "opacity-50",
+				)}
+			>
+				--
+			</span>
+		);
+	}
+
+	return (
+		<div className="relative">
+			<button
+				type="button"
+				onClick={() => setPopoverOpen(true)}
+				className={cn(
+					"inline-block h-7 min-w-[3ch] text-center text-sm font-medium leading-7 tabular-nums transition-colors hover:text-hover-neutral",
+					status === "bloodied" && "text-amber-400",
+					status === "unconscious" && "text-red-400",
+					status === "healthy" && "text-foreground",
+					dimmed && "opacity-50",
+				)}
+			>
+				{currentHp}
+			</button>
+			{popoverOpen && (
+				<HpAdjustPopover
+					onAdjust={onAdjust}
+					onClose={() => setPopoverOpen(false)}
+				/>
+			)}
+		</div>
+	);
+}
+
+function AcDisplay({
+	ac,
+	onCommit,
+}: {
+	ac: number | undefined;
+	onCommit: (value: number | undefined) => void;
+}) {
+	const [editing, setEditing] = useState(false);
+	const [draft, setDraft] = useState(ac?.toString() ?? "");
+	const inputRef = useRef<HTMLInputElement>(null);
+
+	const commit = useCallback(() => {
+		if (draft === "") {
+			onCommit(undefined);
+		} else {
+			const n = Number.parseInt(draft, 10);
+			if (!Number.isNaN(n) && n >= 0) {
+				onCommit(n);
+			}
+		}
+		setEditing(false);
+	}, [draft, onCommit]);
+
+	const startEditing = useCallback(() => {
+		setDraft(ac?.toString() ?? "");
+		setEditing(true);
+		requestAnimationFrame(() => inputRef.current?.select());
+	}, [ac]);
+
+	if (editing) {
+		return (
+			<Input
+				ref={inputRef}
+				type="text"
+				inputMode="numeric"
+				value={draft}
+				placeholder="AC"
+				className="h-7 w-[6ch] text-center text-sm tabular-nums"
+				onChange={(e) => setDraft(e.target.value)}
+				onBlur={commit}
+				onKeyDown={(e) => {
+					if (e.key === "Enter") commit();
+					if (e.key === "Escape") setEditing(false);
+				}}
+			/>
+		);
+	}
+
+	return <AcShield value={ac} onClick={startEditing} />;
+}
+
+function InitiativeDisplay({
+	initiative,
+	combatantId,
+	dimmed,
+	onSetInitiative,
+	onRollInitiative,
+}: {
+	initiative: number | undefined;
+	combatantId: CombatantId;
+	dimmed: boolean;
+	onSetInitiative: (id: CombatantId, value: number | undefined) => void;
+	onRollInitiative?: (id: CombatantId) => void;
+}) {
+	const [editing, setEditing] = useState(false);
+	const [draft, setDraft] = useState(initiative?.toString() ?? "");
+	const inputRef = useRef<HTMLInputElement>(null);
+
+	const commit = useCallback(() => {
+		if (draft === "") {
+			onSetInitiative(combatantId, undefined);
+		} else {
+			const n = Number.parseInt(draft, 10);
+			if (!Number.isNaN(n)) {
+				onSetInitiative(combatantId, n);
+			}
+		}
+		setEditing(false);
+	}, [draft, combatantId, onSetInitiative]);
+
+	const startEditing = useCallback(() => {
+		setDraft(initiative?.toString() ?? "");
+		setEditing(true);
+		requestAnimationFrame(() => inputRef.current?.select());
+	}, [initiative]);
+
+	if (editing) {
+		return (
+			<Input
+				ref={inputRef}
+				type="text"
+				inputMode="numeric"
+				value={draft}
+				placeholder="--"
+				className={cn(
+					"h-7 w-[6ch] text-center text-sm tabular-nums",
+					dimmed && "opacity-50",
+				)}
+				onChange={(e) => setDraft(e.target.value)}
+				onBlur={commit}
+				onKeyDown={(e) => {
+					if (e.key === "Enter") commit();
+					if (e.key === "Escape") setEditing(false);
+				}}
+			/>
+		);
+	}
+
+	// Empty + bestiary creature → d20 roll button
+	if (initiative === undefined && onRollInitiative) {
+		return (
+			<button
+				type="button"
+				onClick={() => onRollInitiative(combatantId)}
+				className={cn(
+					"flex h-7 w-full items-center justify-center text-muted-foreground transition-colors hover:text-hover-neutral",
+					dimmed && "opacity-50",
+				)}
+				title="Roll initiative"
+				aria-label="Roll initiative"
+			>
+				<D20Icon className="h-7 w-7" />
+			</button>
+		);
+	}
+
+	// Has value → bold number, click to edit
+	// Empty + manual → "--" placeholder, click to edit
+	return (
+		<button
+			type="button"
+			onClick={startEditing}
+			className={cn(
+				"h-7 w-full text-center text-sm leading-7 tabular-nums transition-colors",
+				initiative !== undefined
+					? "font-medium text-foreground hover:text-hover-neutral"
+					: "text-muted-foreground hover:text-hover-neutral",
+				dimmed && "opacity-50",
+			)}
+		>
+			{initiative ?? "--"}
+		</button>
+	);
+}
+
+function rowBorderClass(
+	isActive: boolean,
+	isConcentrating: boolean | undefined,
+): string {
+	if (isActive) return "border-l-2 border-l-accent bg-accent/10";
+	if (isConcentrating) return "border-l-2 border-l-purple-400";
+	return "border-l-2 border-l-transparent";
+}
+
+function concentrationIconClass(
+	isConcentrating: boolean | undefined,
+	dimmed: boolean,
+): string {
+	if (!isConcentrating)
+		return "opacity-0 group-hover:opacity-50 text-muted-foreground";
+	return dimmed ? "opacity-50 text-purple-400" : "opacity-100 text-purple-400";
+}
+
+function activateOnKeyDown(
+	handler: () => void,
+): (e: { key: string; preventDefault: () => void }) => void {
+	return (e) => {
+		if (e.key === "Enter" || e.key === " ") {
+			e.preventDefault();
+			handler();
+		}
+	};
+}
+
+export function CombatantRow({
+	ref,
+	combatant,
+	isActive,
+	onRename,
+	onSetInitiative,
+	onRemove,
+	onSetHp,
+	onAdjustHp,
+	onSetAc,
+	onToggleCondition,
+	onToggleConcentration,
+	onShowStatBlock,
+	onRollInitiative,
+}: CombatantRowProps & { ref?: Ref<HTMLDivElement> }) {
+	const { id, name, initiative, maxHp, currentHp } = combatant;
+	const status = deriveHpStatus(currentHp, maxHp);
+	const dimmed = status === "unconscious";
+	const [pickerOpen, setPickerOpen] = useState(false);
+
+	const prevHpRef = useRef(currentHp);
+	const [isPulsing, setIsPulsing] = useState(false);
+	const pulseTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+
+	useEffect(() => {
+		const prevHp = prevHpRef.current;
+		prevHpRef.current = currentHp;
+
+		if (
+			prevHp !== undefined &&
+			currentHp !== undefined &&
+			currentHp < prevHp &&
+			combatant.isConcentrating
+		) {
+			setIsPulsing(true);
+			clearTimeout(pulseTimerRef.current);
+			pulseTimerRef.current = setTimeout(() => setIsPulsing(false), 1200);
+		}
+	}, [currentHp, combatant.isConcentrating]);
+
+	useEffect(() => {
+		if (!combatant.isConcentrating) {
+			clearTimeout(pulseTimerRef.current);
+			setIsPulsing(false);
+		}
+	}, [combatant.isConcentrating]);
+
+	const pcColor = combatant.color
+		? PLAYER_COLOR_HEX[combatant.color as keyof typeof PLAYER_COLOR_HEX]
+		: undefined;
+
+	return (
+		/* biome-ignore lint/a11y/noStaticElementInteractions: role="button" is set conditionally when onShowStatBlock exists */
+		<div
+			ref={ref}
+			role={onShowStatBlock ? "button" : undefined}
+			tabIndex={onShowStatBlock ? 0 : undefined}
+			className={cn(
+				"group rounded-md pr-3 transition-colors",
+				rowBorderClass(isActive, combatant.isConcentrating),
+				isPulsing && "animate-concentration-pulse",
+				onShowStatBlock && "cursor-pointer",
+			)}
+			onClick={onShowStatBlock}
+			onKeyDown={
+				onShowStatBlock ? activateOnKeyDown(onShowStatBlock) : undefined
+			}
+		>
+			<div className="grid grid-cols-[2rem_3rem_1fr_auto_auto_2rem] items-center gap-3 py-2">
+				{/* Concentration */}
+				<button
+					type="button"
+					onClick={(e) => {
+						e.stopPropagation();
+						onToggleConcentration(id);
+					}}
+					title="Concentrating"
+					aria-label="Toggle concentration"
+					className={cn(
+						"flex w-full items-center justify-center self-stretch -my-2 -ml-[2px] pl-[14px] transition-opacity hover:text-hover-neutral hover:opacity-100",
+						concentrationIconClass(combatant.isConcentrating, dimmed),
+					)}
+				>
+					<Brain size={16} />
+				</button>
+
+				{/* Initiative */}
+				{/* biome-ignore lint/a11y/noStaticElementInteractions: stopPropagation wrapper for interactive children */}
+				<div
+					onClick={(e) => e.stopPropagation()}
+					onKeyDown={(e) => e.stopPropagation()}
+				>
+					<InitiativeDisplay
+						initiative={initiative}
+						combatantId={id}
+						dimmed={dimmed}
+						onSetInitiative={onSetInitiative}
+						onRollInitiative={onRollInitiative}
+					/>
+				</div>
+
+				{/* Name + Conditions */}
+				<div
+					className={cn(
+						"relative flex flex-wrap items-center gap-1 min-w-0",
+						dimmed && "opacity-50",
+					)}
+				>
+					{combatant.icon &&
+						combatant.color &&
+						(() => {
+							const PcIcon = PLAYER_ICON_MAP[combatant.icon as PlayerIcon];
+							const pcColor =
+								PLAYER_COLOR_HEX[
+									combatant.color as keyof typeof PLAYER_COLOR_HEX
+								];
+							return PcIcon ? (
+								<PcIcon
+									size={14}
+									style={{ color: pcColor }}
+									className="shrink-0"
+								/>
+							) : null;
+						})()}
+					<EditableName
+						name={name}
+						combatantId={id}
+						onRename={onRename}
+						onShowStatBlock={onShowStatBlock}
+						color={pcColor}
+					/>
+					<ConditionTags
+						conditions={combatant.conditions}
+						onRemove={(conditionId) => onToggleCondition(id, conditionId)}
+						onOpenPicker={() => setPickerOpen((prev) => !prev)}
+					/>
+					{pickerOpen && (
+						<ConditionPicker
+							activeConditions={combatant.conditions}
+							onToggle={(conditionId) => onToggleCondition(id, conditionId)}
+							onClose={() => setPickerOpen(false)}
+						/>
+					)}
+				</div>
+
+				{/* AC */}
+				{/* biome-ignore lint/a11y/noStaticElementInteractions: stopPropagation wrapper for interactive children */}
+				<div
+					className={cn(dimmed && "opacity-50")}
+					onClick={(e) => e.stopPropagation()}
+					onKeyDown={(e) => e.stopPropagation()}
+				>
+					<AcDisplay ac={combatant.ac} onCommit={(v) => onSetAc(id, v)} />
+				</div>
+
+				{/* HP */}
+				{/* biome-ignore lint/a11y/noStaticElementInteractions: stopPropagation wrapper for interactive children */}
+				<div
+					className="flex items-center gap-1"
+					onClick={(e) => e.stopPropagation()}
+					onKeyDown={(e) => e.stopPropagation()}
+				>
+					<ClickableHp
+						currentHp={currentHp}
+						maxHp={maxHp}
+						onAdjust={(delta) => onAdjustHp(id, delta)}
+						dimmed={dimmed}
+					/>
+					{maxHp !== undefined && (
+						<span
+							className={cn(
+								"text-sm tabular-nums text-muted-foreground",
+								dimmed && "opacity-50",
+							)}
+						>
+							/
+						</span>
+					)}
+					<div className={cn(dimmed && "opacity-50")}>
+						<MaxHpDisplay maxHp={maxHp} onCommit={(v) => onSetHp(id, v)} />
+					</div>
+				</div>
+
+				{/* Actions */}
+				<ConfirmButton
+					icon={<X size={16} />}
+					label="Remove combatant"
+					onConfirm={() => onRemove(id)}
+					className="h-7 w-7 text-muted-foreground opacity-0 pointer-events-none group-hover:opacity-100 group-hover:pointer-events-auto focus:opacity-100 focus:pointer-events-auto pointer-coarse:opacity-100 pointer-coarse:pointer-events-auto transition-opacity"
+				/>
+			</div>
+		</div>
+	);
+}

apps/web/src/components/condition-picker.tsx

@@ -0,0 +1,134 @@
+import { CONDITION_DEFINITIONS, type ConditionId } from "@initiative/domain";
+import type { LucideIcon } from "lucide-react";
+import {
+	ArrowDown,
+	Ban,
+	BatteryLow,
+	Droplet,
+	EarOff,
+	EyeOff,
+	Gem,
+	Ghost,
+	Hand,
+	Heart,
+	Link,
+	Moon,
+	Siren,
+	Sparkles,
+	ZapOff,
+} from "lucide-react";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { cn } from "../lib/utils";
+
+const ICON_MAP: Record<string, LucideIcon> = {
+	EyeOff,
+	Heart,
+	EarOff,
+	BatteryLow,
+	Siren,
+	Hand,
+	Ban,
+	Ghost,
+	ZapOff,
+	Gem,
+	Droplet,
+	ArrowDown,
+	Link,
+	Sparkles,
+	Moon,
+};
+
+const COLOR_CLASSES: Record<string, string> = {
+	neutral: "text-muted-foreground",
+	pink: "text-pink-400",
+	amber: "text-amber-400",
+	orange: "text-orange-400",
+	gray: "text-gray-400",
+	violet: "text-violet-400",
+	yellow: "text-yellow-400",
+	slate: "text-slate-400",
+	green: "text-green-400",
+	indigo: "text-indigo-400",
+};
+
+interface ConditionPickerProps {
+	activeConditions: readonly ConditionId[] | undefined;
+	onToggle: (conditionId: ConditionId) => void;
+	onClose: () => void;
+}
+
+export function ConditionPicker({
+	activeConditions,
+	onToggle,
+	onClose,
+}: ConditionPickerProps) {
+	const ref = useRef<HTMLDivElement>(null);
+	const [flipped, setFlipped] = useState(false);
+	const [maxHeight, setMaxHeight] = useState<number | undefined>(undefined);
+
+	useLayoutEffect(() => {
+		const el = ref.current;
+		if (!el) return;
+		const rect = el.getBoundingClientRect();
+		const spaceBelow = window.innerHeight - rect.top;
+		const spaceAbove = rect.bottom;
+		const shouldFlip =
+			rect.bottom > window.innerHeight && spaceAbove > spaceBelow;
+		setFlipped(shouldFlip);
+		const available = shouldFlip ? spaceAbove : spaceBelow;
+		if (rect.height > available) {
+			setMaxHeight(available - 16);
+		}
+	}, []);
+
+	useEffect(() => {
+		function handleClickOutside(e: MouseEvent) {
+			if (ref.current && !ref.current.contains(e.target as Node)) {
+				onClose();
+			}
+		}
+		document.addEventListener("mousedown", handleClickOutside);
+		return () => document.removeEventListener("mousedown", handleClickOutside);
+	}, [onClose]);
+
+	const active = new Set(activeConditions ?? []);
+
+	return (
+		<div
+			ref={ref}
+			className={cn(
+				"absolute left-0 z-10 w-fit overflow-y-auto rounded-md border border-border bg-background p-1 shadow-lg",
+				flipped ? "bottom-full mb-1" : "top-full mt-1",
+			)}
+			style={maxHeight ? { maxHeight } : undefined}
+		>
+			{CONDITION_DEFINITIONS.map((def) => {
+				const Icon = ICON_MAP[def.iconName];
+				if (!Icon) return null;
+				const isActive = active.has(def.id);
+				const colorClass = COLOR_CLASSES[def.color] ?? "text-muted-foreground";
+				return (
+					<button
+						key={def.id}
+						type="button"
+						className={cn(
+							"flex w-full items-center gap-2 rounded px-2 py-1 text-sm transition-colors hover:bg-hover-neutral-bg",
+							isActive && "bg-card/50",
+						)}
+						onClick={() => onToggle(def.id)}
+					>
+						<Icon
+							size={14}
+							className={isActive ? colorClass : "text-muted-foreground"}
+						/>
+						<span
+							className={isActive ? "text-foreground" : "text-muted-foreground"}
+						>
+							{def.label}
+						</span>
+					</button>
+				);
+			})}
+		</div>
+	);
+}

apps/web/src/components/condition-tags.tsx

@@ -0,0 +1,102 @@
+import { CONDITION_DEFINITIONS, type ConditionId } from "@initiative/domain";
+import type { LucideIcon } from "lucide-react";
+import {
+	ArrowDown,
+	Ban,
+	BatteryLow,
+	Droplet,
+	EarOff,
+	EyeOff,
+	Gem,
+	Ghost,
+	Hand,
+	Heart,
+	Link,
+	Moon,
+	Plus,
+	Siren,
+	Sparkles,
+	ZapOff,
+} from "lucide-react";
+
+const ICON_MAP: Record<string, LucideIcon> = {
+	EyeOff,
+	Heart,
+	EarOff,
+	BatteryLow,
+	Siren,
+	Hand,
+	Ban,
+	Ghost,
+	ZapOff,
+	Gem,
+	Droplet,
+	ArrowDown,
+	Link,
+	Sparkles,
+	Moon,
+};
+
+const COLOR_CLASSES: Record<string, string> = {
+	neutral: "text-muted-foreground",
+	pink: "text-pink-400",
+	amber: "text-amber-400",
+	orange: "text-orange-400",
+	gray: "text-gray-400",
+	violet: "text-violet-400",
+	yellow: "text-yellow-400",
+	slate: "text-slate-400",
+	green: "text-green-400",
+	indigo: "text-indigo-400",
+};
+
+interface ConditionTagsProps {
+	conditions: readonly ConditionId[] | undefined;
+	onRemove: (conditionId: ConditionId) => void;
+	onOpenPicker: () => void;
+}
+
+export function ConditionTags({
+	conditions,
+	onRemove,
+	onOpenPicker,
+}: ConditionTagsProps) {
+	return (
+		<div className="flex flex-wrap items-center gap-0.5">
+			{conditions?.map((condId) => {
+				const def = CONDITION_DEFINITIONS.find((d) => d.id === condId);
+				if (!def) return null;
+				const Icon = ICON_MAP[def.iconName];
+				if (!Icon) return null;
+				const colorClass = COLOR_CLASSES[def.color] ?? "text-muted-foreground";
+				return (
+					<button
+						key={condId}
+						type="button"
+						title={def.label}
+						aria-label={`Remove ${def.label}`}
+						className={`inline-flex items-center rounded p-0.5 hover:bg-hover-neutral-bg transition-colors ${colorClass}`}
+						onClick={(e) => {
+							e.stopPropagation();
+							onRemove(condId);
+						}}
+					>
+						<Icon size={14} />
+					</button>
+				);
+			})}
+			<button
+				type="button"
+				title="Add condition"
+				aria-label="Add condition"
+				className="inline-flex items-center rounded p-0.5 text-muted-foreground hover:text-hover-neutral hover:bg-hover-neutral-bg transition-colors opacity-0 group-hover:opacity-100 focus:opacity-100 pointer-coarse:opacity-100 transition-opacity"
+				onClick={(e) => {
+					e.stopPropagation();
+					onOpenPicker();
+				}}
+			>
+				<Plus size={14} />
+			</button>
+		</div>
+	);
+}

apps/web/src/components/create-player-modal.tsx

@@ -0,0 +1,187 @@
+import type { PlayerCharacter } from "@initiative/domain";
+import { X } from "lucide-react";
+import { type FormEvent, useEffect, useState } from "react";
+import { ColorPalette } from "./color-palette";
+import { IconGrid } from "./icon-grid";
+import { Button } from "./ui/button";
+import { Input } from "./ui/input";
+
+interface CreatePlayerModalProps {
+	open: boolean;
+	onClose: () => void;
+	onSave: (
+		name: string,
+		ac: number,
+		maxHp: number,
+		color: string,
+		icon: string,
+	) => void;
+	playerCharacter?: PlayerCharacter;
+}
+
+export function CreatePlayerModal({
+	open,
+	onClose,
+	onSave,
+	playerCharacter,
+}: CreatePlayerModalProps) {
+	const [name, setName] = useState("");
+	const [ac, setAc] = useState("10");
+	const [maxHp, setMaxHp] = useState("10");
+	const [color, setColor] = useState("blue");
+	const [icon, setIcon] = useState("sword");
+	const [error, setError] = useState("");
+
+	const isEdit = !!playerCharacter;
+
+	useEffect(() => {
+		if (open) {
+			if (playerCharacter) {
+				setName(playerCharacter.name);
+				setAc(String(playerCharacter.ac));
+				setMaxHp(String(playerCharacter.maxHp));
+				setColor(playerCharacter.color);
+				setIcon(playerCharacter.icon);
+			} else {
+				setName("");
+				setAc("10");
+				setMaxHp("10");
+				setColor("blue");
+				setIcon("sword");
+			}
+			setError("");
+		}
+	}, [open, playerCharacter]);
+
+	useEffect(() => {
+		if (!open) return;
+		function handleKeyDown(e: KeyboardEvent) {
+			if (e.key === "Escape") onClose();
+		}
+		document.addEventListener("keydown", handleKeyDown);
+		return () => document.removeEventListener("keydown", handleKeyDown);
+	}, [open, onClose]);
+
+	if (!open) return null;
+
+	const handleSubmit = (e: FormEvent) => {
+		e.preventDefault();
+		const trimmed = name.trim();
+		if (trimmed === "") {
+			setError("Name is required");
+			return;
+		}
+		const acNum = Number.parseInt(ac, 10);
+		if (Number.isNaN(acNum) || acNum < 0) {
+			setError("AC must be a non-negative number");
+			return;
+		}
+		const hpNum = Number.parseInt(maxHp, 10);
+		if (Number.isNaN(hpNum) || hpNum < 1) {
+			setError("Max HP must be at least 1");
+			return;
+		}
+		onSave(trimmed, acNum, hpNum, color, icon);
+		onClose();
+	};
+
+	return (
+		// biome-ignore lint/a11y/noStaticElementInteractions: backdrop click to close
+		<div
+			className="fixed inset-0 z-50 flex items-center justify-center bg-black/50"
+			onMouseDown={onClose}
+		>
+			{/* biome-ignore lint/a11y/noStaticElementInteractions: prevent close when clicking modal content */}
+			<div
+				className="w-full max-w-md rounded-lg border border-border bg-card p-6 shadow-xl"
+				onMouseDown={(e) => e.stopPropagation()}
+			>
+				<div className="mb-4 flex items-center justify-between">
+					<h2 className="text-lg font-semibold text-foreground">
+						{isEdit ? "Edit Player" : "Create Player"}
+					</h2>
+					<Button
+						variant="ghost"
+						size="icon"
+						onClick={onClose}
+						className="text-muted-foreground"
+					>
+						<X size={20} />
+					</Button>
+				</div>
+
+				<form onSubmit={handleSubmit} className="flex flex-col gap-4">
+					<div>
+						<span className="mb-1 block text-sm text-muted-foreground">
+							Name
+						</span>
+						<Input
+							type="text"
+							value={name}
+							onChange={(e) => {
+								setName(e.target.value);
+								setError("");
+							}}
+							placeholder="Character name"
+							aria-label="Name"
+							autoFocus
+						/>
+						{error && <p className="mt-1 text-sm text-destructive">{error}</p>}
+					</div>
+
+					<div className="flex gap-3">
+						<div className="flex-1">
+							<span className="mb-1 block text-sm text-muted-foreground">
+								AC
+							</span>
+							<Input
+								type="text"
+								inputMode="numeric"
+								value={ac}
+								onChange={(e) => setAc(e.target.value)}
+								placeholder="AC"
+								aria-label="AC"
+								className="text-center"
+							/>
+						</div>
+						<div className="flex-1">
+							<span className="mb-1 block text-sm text-muted-foreground">
+								Max HP
+							</span>
+							<Input
+								type="text"
+								inputMode="numeric"
+								value={maxHp}
+								onChange={(e) => setMaxHp(e.target.value)}
+								placeholder="Max HP"
+								aria-label="Max HP"
+								className="text-center"
+							/>
+						</div>
+					</div>
+
+					<div>
+						<span className="mb-2 block text-sm text-muted-foreground">
+							Color
+						</span>
+						<ColorPalette value={color} onChange={setColor} />
+					</div>
+
+					<div>
+						<span className="mb-2 block text-sm text-muted-foreground">
+							Icon
+						</span>
+						<IconGrid value={icon} onChange={setIcon} />
+					</div>
+
+					<div className="flex justify-end gap-2 pt-2">
+						<Button type="button" variant="ghost" onClick={onClose}>
+							Cancel
+						</Button>
+						<Button type="submit">{isEdit ? "Save" : "Create"}</Button>
+					</div>
+				</form>
+			</div>
+		</div>
+	);
+}

apps/web/src/components/d20-icon.tsx

@@ -0,0 +1,29 @@
+interface D20IconProps {
+	readonly className?: string;
+}
+
+export function D20Icon({ className }: D20IconProps) {
+	return (
+		<svg
+			xmlns="http://www.w3.org/2000/svg"
+			height="24"
+			width="24"
+			viewBox="0 0 24 24"
+			fill="none"
+			stroke="currentColor"
+			strokeWidth={1.5}
+			strokeLinecap="round"
+			strokeLinejoin="round"
+			className={className}
+			aria-hidden="true"
+		>
+			<polygon points="20.22 16.76 20.22 7.26 12.04 2.51 3.85 7.26 3.85 16.76 12.04 21.51 20.22 16.76" />
+			<line x1="7.29" y1="9.26" x2="3.85" y2="7.26" />
+			<line x1="20.22" y1="7.26" x2="16.79" y2="9.26" />
+			<line x1="12.04" y1="17.44" x2="12.04" y2="21.51" />
+			<polygon points="12.04 17.44 20.22 16.76 16.79 9.26 12.04 17.44" />
+			<polygon points="12.04 17.44 7.29 9.26 3.85 16.76 12.04 17.44" />
+			<polygon points="12.04 2.51 7.29 9.26 16.79 9.26 12.04 2.51" />
+		</svg>
+	);
+}

apps/web/src/components/hp-adjust-popover.tsx

@@ -0,0 +1,134 @@
+import { Heart, Sword } from "lucide-react";
+import {
+	useCallback,
+	useEffect,
+	useLayoutEffect,
+	useRef,
+	useState,
+} from "react";
+import { Input } from "./ui/input";
+
+interface HpAdjustPopoverProps {
+	readonly onAdjust: (delta: number) => void;
+	readonly onClose: () => void;
+}
+
+export function HpAdjustPopover({ onAdjust, onClose }: HpAdjustPopoverProps) {
+	const [inputValue, setInputValue] = useState("");
+	const [pos, setPos] = useState<{ top: number; left: number } | null>(null);
+	const ref = useRef<HTMLDivElement>(null);
+	const inputRef = useRef<HTMLInputElement>(null);
+
+	useLayoutEffect(() => {
+		const el = ref.current;
+		if (!el) return;
+		const parent = el.parentElement;
+		if (!parent) return;
+		const trigger = parent.getBoundingClientRect();
+		const popover = el.getBoundingClientRect();
+		const vw = document.documentElement.clientWidth;
+		let left = trigger.left;
+		if (left + popover.width > vw) {
+			left = vw - popover.width - 8;
+		}
+		if (left < 8) {
+			left = 8;
+		}
+		setPos({ top: trigger.bottom + 4, left });
+	}, []);
+
+	useEffect(() => {
+		requestAnimationFrame(() => inputRef.current?.focus());
+	}, []);
+
+	useEffect(() => {
+		function handleClickOutside(e: MouseEvent) {
+			if (ref.current && !ref.current.contains(e.target as Node)) {
+				onClose();
+			}
+		}
+		document.addEventListener("mousedown", handleClickOutside);
+		return () => document.removeEventListener("mousedown", handleClickOutside);
+	}, [onClose]);
+
+	const parsedValue =
+		inputValue === "" ? null : Number.parseInt(inputValue, 10);
+	const isValid =
+		parsedValue !== null && !Number.isNaN(parsedValue) && parsedValue > 0;
+
+	const applyDelta = useCallback(
+		(sign: -1 | 1) => {
+			if (inputValue === "") return;
+			const n = Number.parseInt(inputValue, 10);
+			if (Number.isNaN(n) || n <= 0) return;
+			onAdjust(sign * n);
+			onClose();
+		},
+		[inputValue, onAdjust, onClose],
+	);
+
+	const handleKeyDown = useCallback(
+		(e: React.KeyboardEvent<HTMLInputElement>) => {
+			if (e.key === "Enter") {
+				if (e.shiftKey) {
+					applyDelta(1);
+				} else {
+					applyDelta(-1);
+				}
+			} else if (e.key === "Escape") {
+				onClose();
+			}
+		},
+		[applyDelta, onClose],
+	);
+
+	return (
+		<div
+			ref={ref}
+			className="fixed z-10 rounded-md border border-border bg-background p-2 shadow-lg"
+			style={
+				pos
+					? { top: pos.top, left: pos.left }
+					: { visibility: "hidden" as const }
+			}
+		>
+			<div className="flex items-center gap-1">
+				<Input
+					ref={inputRef}
+					type="text"
+					inputMode="numeric"
+					value={inputValue}
+					placeholder="HP"
+					className="h-7 w-[7ch] text-center text-sm tabular-nums"
+					onChange={(e) => {
+						const v = e.target.value;
+						if (v === "" || /^\d+$/.test(v)) {
+							setInputValue(v);
+						}
+					}}
+					onKeyDown={handleKeyDown}
+				/>
+				<button
+					type="button"
+					disabled={!isValid}
+					className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-red-400 transition-colors hover:bg-red-950 hover:text-red-300 disabled:pointer-events-none disabled:opacity-50"
+					onClick={() => applyDelta(-1)}
+					title="Apply damage"
+					aria-label="Apply damage"
+				>
+					<Sword size={14} />
+				</button>
+				<button
+					type="button"
+					disabled={!isValid}
+					className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-emerald-400 transition-colors hover:bg-emerald-950 hover:text-emerald-300 disabled:pointer-events-none disabled:opacity-50"
+					onClick={() => applyDelta(1)}
+					title="Apply healing"
+					aria-label="Apply healing"
+				>
+					<Heart size={14} />
+				</button>
+			</div>
+		</div>
+	);
+}

apps/web/src/components/icon-grid.tsx

@@ -0,0 +1,38 @@
+import type { PlayerIcon } from "@initiative/domain";
+import { VALID_PLAYER_ICONS } from "@initiative/domain";
+import { cn } from "../lib/utils";
+import { PLAYER_ICON_MAP } from "./player-icon-map";
+
+interface IconGridProps {
+	value: string;
+	onChange: (icon: string) => void;
+}
+
+const ICONS = [...VALID_PLAYER_ICONS] as PlayerIcon[];
+
+export function IconGrid({ value, onChange }: IconGridProps) {
+	return (
+		<div className="flex flex-wrap gap-2">
+			{ICONS.map((iconId) => {
+				const Icon = PLAYER_ICON_MAP[iconId];
+				return (
+					<button
+						key={iconId}
+						type="button"
+						onClick={() => onChange(iconId)}
+						className={cn(
+							"flex h-9 w-9 items-center justify-center rounded-md transition-all",
+							value === iconId
+								? "bg-primary/20 ring-2 ring-primary text-foreground"
+								: "text-muted-foreground hover:bg-card hover:text-foreground",
+						)}
+						aria-label={iconId}
+						title={iconId}
+					>
+						<Icon size={20} />
+					</button>
+				);
+			})}
+		</div>
+	);
+}

apps/web/src/components/player-icon-map.ts

@@ -0,0 +1,50 @@
+import type { PlayerColor, PlayerIcon } from "@initiative/domain";
+import type { LucideIcon } from "lucide-react";
+import {
+	Axe,
+	Crosshair,
+	Crown,
+	Eye,
+	Feather,
+	Flame,
+	Heart,
+	Moon,
+	Shield,
+	Skull,
+	Star,
+	Sun,
+	Sword,
+	Wand,
+	Zap,
+} from "lucide-react";
+
+export const PLAYER_ICON_MAP: Record<PlayerIcon, LucideIcon> = {
+	sword: Sword,
+	shield: Shield,
+	skull: Skull,
+	heart: Heart,
+	wand: Wand,
+	flame: Flame,
+	crown: Crown,
+	star: Star,
+	moon: Moon,
+	sun: Sun,
+	axe: Axe,
+	crosshair: Crosshair,
+	eye: Eye,
+	feather: Feather,
+	zap: Zap,
+};
+
+export const PLAYER_COLOR_HEX: Record<PlayerColor, string> = {
+	red: "#ef4444",
+	blue: "#3b82f6",
+	green: "#22c55e",
+	purple: "#a855f7",
+	orange: "#f97316",
+	pink: "#ec4899",
+	cyan: "#06b6d4",
+	yellow: "#eab308",
+	emerald: "#10b981",
+	indigo: "#6366f1",
+};

apps/web/src/components/player-management.tsx

@@ -0,0 +1,126 @@
+import type {
+	PlayerCharacter,
+	PlayerCharacterId,
+	PlayerIcon,
+} from "@initiative/domain";
+import { Pencil, Plus, Trash2, X } from "lucide-react";
+import { useEffect } from "react";
+import { PLAYER_COLOR_HEX, PLAYER_ICON_MAP } from "./player-icon-map";
+import { Button } from "./ui/button";
+import { ConfirmButton } from "./ui/confirm-button";
+
+interface PlayerManagementProps {
+	open: boolean;
+	onClose: () => void;
+	characters: readonly PlayerCharacter[];
+	onEdit: (pc: PlayerCharacter) => void;
+	onDelete: (id: PlayerCharacterId) => void;
+	onCreate: () => void;
+}
+
+export function PlayerManagement({
+	open,
+	onClose,
+	characters,
+	onEdit,
+	onDelete,
+	onCreate,
+}: PlayerManagementProps) {
+	useEffect(() => {
+		if (!open) return;
+		function handleKeyDown(e: KeyboardEvent) {
+			if (e.key === "Escape") onClose();
+		}
+		document.addEventListener("keydown", handleKeyDown);
+		return () => document.removeEventListener("keydown", handleKeyDown);
+	}, [open, onClose]);
+
+	if (!open) return null;
+
+	return (
+		// biome-ignore lint/a11y/noStaticElementInteractions: backdrop click to close
+		<div
+			className="fixed inset-0 z-50 flex items-center justify-center bg-black/50"
+			onMouseDown={onClose}
+		>
+			{/* biome-ignore lint/a11y/noStaticElementInteractions: prevent close when clicking modal content */}
+			<div
+				className="w-full max-w-md rounded-lg border border-border bg-card p-6 shadow-xl"
+				onMouseDown={(e) => e.stopPropagation()}
+			>
+				<div className="mb-4 flex items-center justify-between">
+					<h2 className="text-lg font-semibold text-foreground">
+						Player Characters
+					</h2>
+					<Button
+						variant="ghost"
+						size="icon"
+						onClick={onClose}
+						className="text-muted-foreground"
+					>
+						<X size={20} />
+					</Button>
+				</div>
+
+				{characters.length === 0 ? (
+					<div className="flex flex-col items-center gap-3 py-8 text-center">
+						<p className="text-muted-foreground">No player characters yet</p>
+						<Button onClick={onCreate}>
+							<Plus size={16} />
+							Create your first player character
+						</Button>
+					</div>
+				) : (
+					<div className="flex flex-col gap-1">
+						{characters.map((pc) => {
+							const Icon = PLAYER_ICON_MAP[pc.icon as PlayerIcon];
+							const color =
+								PLAYER_COLOR_HEX[pc.color as keyof typeof PLAYER_COLOR_HEX];
+							return (
+								<div
+									key={pc.id}
+									className="group flex items-center gap-3 rounded-md px-3 py-2 hover:bg-hover-neutral-bg"
+								>
+									{Icon && (
+										<Icon size={18} style={{ color }} className="shrink-0" />
+									)}
+									<span className="flex-1 truncate text-sm text-foreground">
+										{pc.name}
+									</span>
+									<span className="text-xs tabular-nums text-muted-foreground">
+										AC {pc.ac}
+									</span>
+									<span className="text-xs tabular-nums text-muted-foreground">
+										HP {pc.maxHp}
+									</span>
+									<Button
+										variant="ghost"
+										size="icon-sm"
+										onClick={() => onEdit(pc)}
+										className="text-muted-foreground"
+										title="Edit"
+									>
+										<Pencil size={14} />
+									</Button>
+									<ConfirmButton
+										icon={<Trash2 size={14} />}
+										label="Delete player character"
+										onConfirm={() => onDelete(pc.id)}
+										size="icon-sm"
+										className="text-muted-foreground"
+									/>
+								</div>
+							);
+						})}
+						<div className="mt-2 flex justify-end">
+							<Button onClick={onCreate} variant="ghost">
+								<Plus size={16} />
+								Add
+							</Button>
+						</div>
+					</div>
+				)}
+			</div>
+		</div>
+	);
+}

apps/web/src/components/source-fetch-prompt.tsx

@@ -0,0 +1,126 @@
+import { Download, Loader2, Upload } from "lucide-react";
+import { useRef, useState } from "react";
+import { getDefaultFetchUrl } from "../adapters/bestiary-index-adapter.js";
+import { Button } from "./ui/button.js";
+import { Input } from "./ui/input.js";
+
+interface SourceFetchPromptProps {
+	sourceCode: string;
+	sourceDisplayName: string;
+	fetchAndCacheSource: (sourceCode: string, url: string) => Promise<void>;
+	onSourceLoaded: () => void;
+	onUploadSource: (sourceCode: string, jsonData: unknown) => Promise<void>;
+}
+
+export function SourceFetchPrompt({
+	sourceCode,
+	sourceDisplayName,
+	fetchAndCacheSource,
+	onSourceLoaded,
+	onUploadSource,
+}: SourceFetchPromptProps) {
+	const [url, setUrl] = useState(() => getDefaultFetchUrl(sourceCode));
+	const [status, setStatus] = useState<"idle" | "fetching" | "error">("idle");
+	const [error, setError] = useState<string>("");
+	const fileInputRef = useRef<HTMLInputElement>(null);
+
+	const handleFetch = async () => {
+		setStatus("fetching");
+		setError("");
+		try {
+			await fetchAndCacheSource(sourceCode, url);
+			onSourceLoaded();
+		} catch (e) {
+			setStatus("error");
+			setError(e instanceof Error ? e.message : "Failed to fetch source data");
+		}
+	};
+
+	const handleFileUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
+		const file = e.target.files?.[0];
+		if (!file) return;
+
+		setStatus("fetching");
+		setError("");
+
+		try {
+			const text = await file.text();
+			const json = JSON.parse(text);
+			await onUploadSource(sourceCode, json);
+			onSourceLoaded();
+		} catch (err) {
+			setStatus("error");
+			setError(
+				err instanceof Error ? err.message : "Failed to process uploaded file",
+			);
+		}
+
+		// Reset file input
+		if (fileInputRef.current) {
+			fileInputRef.current.value = "";
+		}
+	};
+
+	return (
+		<div className="flex flex-col gap-4">
+			<div>
+				<h3 className="text-sm font-semibold text-foreground">
+					Load {sourceDisplayName}
+				</h3>
+				<p className="mt-1 text-xs text-muted-foreground">
+					Stat block data for this source needs to be loaded. Enter a URL or
+					upload a JSON file.
+				</p>
+			</div>
+
+			<div className="flex flex-col gap-2">
+				<label htmlFor="source-url" className="text-xs text-muted-foreground">
+					Source URL
+				</label>
+				<Input
+					id="source-url"
+					type="url"
+					value={url}
+					onChange={(e) => setUrl(e.target.value)}
+					disabled={status === "fetching"}
+					className="text-xs"
+				/>
+			</div>
+
+			<div className="flex items-center gap-2">
+				<Button onClick={handleFetch} disabled={status === "fetching" || !url}>
+					{status === "fetching" ? (
+						<Loader2 className="mr-1 h-3 w-3 animate-spin" />
+					) : (
+						<Download className="mr-1 h-3 w-3" />
+					)}
+					{status === "fetching" ? "Loading..." : "Load"}
+				</Button>
+
+				<span className="text-xs text-muted-foreground">or</span>
+
+				<Button
+					variant="outline"
+					onClick={() => fileInputRef.current?.click()}
+					disabled={status === "fetching"}
+				>
+					<Upload className="mr-1 h-3 w-3" />
+					Upload file
+				</Button>
+				<input
+					ref={fileInputRef}
+					type="file"
+					accept=".json"
+					className="hidden"
+					onChange={handleFileUpload}
+				/>
+			</div>
+
+			{status === "error" && (
+				<div className="rounded-md border border-destructive/50 bg-destructive/10 px-3 py-2 text-xs text-destructive">
+					{error}
+				</div>
+			)}
+		</div>
+	);
+}

apps/web/src/components/source-manager.tsx

@@ -0,0 +1,85 @@
+import { Database, Trash2 } from "lucide-react";
+import { useCallback, useEffect, useState } from "react";
+import type { CachedSourceInfo } from "../adapters/bestiary-cache.js";
+import * as bestiaryCache from "../adapters/bestiary-cache.js";
+import { Button } from "./ui/button.js";
+
+interface SourceManagerProps {
+	onCacheCleared: () => void;
+}
+
+export function SourceManager({ onCacheCleared }: SourceManagerProps) {
+	const [sources, setSources] = useState<CachedSourceInfo[]>([]);
+
+	const loadSources = useCallback(async () => {
+		const cached = await bestiaryCache.getCachedSources();
+		setSources(cached);
+	}, []);
+
+	useEffect(() => {
+		loadSources();
+	}, [loadSources]);
+
+	const handleClearSource = async (sourceCode: string) => {
+		await bestiaryCache.clearSource(sourceCode);
+		await loadSources();
+		onCacheCleared();
+	};
+
+	const handleClearAll = async () => {
+		await bestiaryCache.clearAll();
+		await loadSources();
+		onCacheCleared();
+	};
+
+	if (sources.length === 0) {
+		return (
+			<div className="flex flex-col items-center gap-2 py-8 text-center">
+				<Database className="h-8 w-8 text-muted-foreground" />
+				<p className="text-sm text-muted-foreground">No cached sources</p>
+			</div>
+		);
+	}
+
+	return (
+		<div className="flex flex-col gap-3">
+			<div className="flex items-center justify-between">
+				<span className="text-sm font-semibold text-foreground">
+					Cached Sources
+				</span>
+				<Button
+					variant="outline"
+					className="hover:text-hover-destructive hover:border-hover-destructive"
+					onClick={handleClearAll}
+				>
+					<Trash2 className="mr-1 h-3 w-3" />
+					Clear All
+				</Button>
+			</div>
+			<ul className="flex flex-col gap-1">
+				{sources.map((source) => (
+					<li
+						key={source.sourceCode}
+						className="flex items-center justify-between rounded-md border border-border px-3 py-2"
+					>
+						<div>
+							<span className="text-sm text-foreground">
+								{source.displayName}
+							</span>
+							<span className="ml-2 text-xs text-muted-foreground">
+								{source.creatureCount} creatures
+							</span>
+						</div>
+						<button
+							type="button"
+							onClick={() => handleClearSource(source.sourceCode)}
+							className="rounded-md p-1 text-muted-foreground transition-colors hover:bg-hover-destructive-bg hover:text-hover-destructive"
+						>
+							<Trash2 className="h-3.5 w-3.5" />
+						</button>
+					</li>
+				))}
+			</ul>
+		</div>
+	);
+}

apps/web/src/components/stat-block-panel.tsx

@@ -0,0 +1,349 @@
+import type { Creature, CreatureId } from "@initiative/domain";
+import { PanelRightClose, Pin, PinOff } from "lucide-react";
+import type { ReactNode } from "react";
+import { useEffect, useState } from "react";
+import { getSourceDisplayName } from "../adapters/bestiary-index-adapter.js";
+import type { BulkImportState } from "../hooks/use-bulk-import.js";
+import { useSwipeToDismiss } from "../hooks/use-swipe-to-dismiss.js";
+import { BulkImportPrompt } from "./bulk-import-prompt.js";
+import { SourceFetchPrompt } from "./source-fetch-prompt.js";
+import { StatBlock } from "./stat-block.js";
+import { Button } from "./ui/button.js";
+
+interface StatBlockPanelProps {
+	creatureId: CreatureId | null;
+	creature: Creature | null;
+	isSourceCached: (sourceCode: string) => Promise<boolean>;
+	fetchAndCacheSource: (sourceCode: string, url: string) => Promise<void>;
+	uploadAndCacheSource: (
+		sourceCode: string,
+		jsonData: unknown,
+	) => Promise<void>;
+	refreshCache: () => Promise<void>;
+	panelRole: "browse" | "pinned";
+	isFolded: boolean;
+	onToggleFold: () => void;
+	onPin: () => void;
+	onUnpin: () => void;
+	showPinButton: boolean;
+	side: "left" | "right";
+	onDismiss: () => void;
+	bulkImportMode?: boolean;
+	bulkImportState?: BulkImportState;
+	onStartBulkImport?: (baseUrl: string) => void;
+	onBulkImportDone?: () => void;
+}
+
+function extractSourceCode(cId: CreatureId): string {
+	const colonIndex = cId.indexOf(":");
+	if (colonIndex === -1) return "";
+	return cId.slice(0, colonIndex).toUpperCase();
+}
+
+function FoldedTab({
+	creatureName,
+	side,
+	onToggleFold,
+}: {
+	creatureName: string;
+	side: "left" | "right";
+	onToggleFold: () => void;
+}) {
+	return (
+		<button
+			type="button"
+			onClick={onToggleFold}
+			className={`flex h-full w-[40px] cursor-pointer items-center justify-center text-muted-foreground hover:text-hover-neutral ${
+				side === "right" ? "self-start" : "self-end"
+			}`}
+			aria-label="Unfold stat block panel"
+		>
+			<span className="writing-vertical-rl text-sm font-medium">
+				{creatureName}
+			</span>
+		</button>
+	);
+}
+
+function PanelHeader({
+	panelRole,
+	showPinButton,
+	onToggleFold,
+	onPin,
+	onUnpin,
+}: {
+	panelRole: "browse" | "pinned";
+	showPinButton: boolean;
+	onToggleFold: () => void;
+	onPin: () => void;
+	onUnpin: () => void;
+}) {
+	return (
+		<div className="flex items-center justify-between border-b border-border px-4 py-2">
+			<div className="flex items-center gap-1">
+				{panelRole === "browse" && (
+					<Button
+						variant="ghost"
+						size="icon-sm"
+						onClick={onToggleFold}
+						className="text-muted-foreground"
+						aria-label="Fold stat block panel"
+					>
+						<PanelRightClose className="h-4 w-4" />
+					</Button>
+				)}
+			</div>
+			<div className="flex items-center gap-1">
+				{panelRole === "browse" && showPinButton && (
+					<Button
+						variant="ghost"
+						size="icon-sm"
+						onClick={onPin}
+						className="text-muted-foreground"
+						aria-label="Pin creature"
+					>
+						<Pin className="h-4 w-4" />
+					</Button>
+				)}
+				{panelRole === "pinned" && (
+					<Button
+						variant="ghost"
+						size="icon-sm"
+						onClick={onUnpin}
+						className="text-muted-foreground"
+						aria-label="Unpin creature"
+					>
+						<PinOff className="h-4 w-4" />
+					</Button>
+				)}
+			</div>
+		</div>
+	);
+}
+
+function DesktopPanel({
+	isFolded,
+	side,
+	creatureName,
+	panelRole,
+	showPinButton,
+	onToggleFold,
+	onPin,
+	onUnpin,
+	children,
+}: {
+	isFolded: boolean;
+	side: "left" | "right";
+	creatureName: string;
+	panelRole: "browse" | "pinned";
+	showPinButton: boolean;
+	onToggleFold: () => void;
+	onPin: () => void;
+	onUnpin: () => void;
+	children: ReactNode;
+}) {
+	const sideClasses = side === "left" ? "left-0 border-r" : "right-0 border-l";
+	const foldedTranslate =
+		side === "right"
+			? "translate-x-[calc(100%-40px)]"
+			: "translate-x-[calc(-100%+40px)]";
+
+	return (
+		<div
+			className={`fixed top-0 bottom-0 flex w-[400px] flex-col border-border bg-card transition-slide-panel ${sideClasses} ${isFolded ? foldedTranslate : "translate-x-0"}`}
+		>
+			{isFolded ? (
+				<FoldedTab
+					creatureName={creatureName}
+					side={side}
+					onToggleFold={onToggleFold}
+				/>
+			) : (
+				<>
+					<PanelHeader
+						panelRole={panelRole}
+						showPinButton={showPinButton}
+						onToggleFold={onToggleFold}
+						onPin={onPin}
+						onUnpin={onUnpin}
+					/>
+					<div className="flex-1 overflow-y-auto p-4">{children}</div>
+				</>
+			)}
+		</div>
+	);
+}
+
+function MobileDrawer({
+	onDismiss,
+	children,
+}: {
+	onDismiss: () => void;
+	children: ReactNode;
+}) {
+	const { offsetX, isSwiping, handlers } = useSwipeToDismiss(onDismiss);
+
+	return (
+		<div className="fixed inset-0 z-50">
+			<button
+				type="button"
+				className="absolute inset-0 bg-black/50 animate-in fade-in"
+				onClick={onDismiss}
+				aria-label="Close stat block"
+			/>
+			<div
+				className={`absolute top-0 right-0 bottom-0 w-[85%] max-w-md border-l border-border bg-card shadow-xl ${isSwiping ? "" : "animate-slide-in-right"}`}
+				style={
+					isSwiping ? { transform: `translateX(${offsetX}px)` } : undefined
+				}
+				{...handlers}
+			>
+				<div className="flex items-center justify-between border-b border-border px-4 py-2">
+					<Button
+						variant="ghost"
+						size="icon-sm"
+						onClick={onDismiss}
+						className="text-muted-foreground"
+						aria-label="Fold stat block panel"
+					>
+						<PanelRightClose className="h-4 w-4" />
+					</Button>
+				</div>
+				<div className="h-[calc(100%-41px)] overflow-y-auto p-4">
+					{children}
+				</div>
+			</div>
+		</div>
+	);
+}
+
+export function StatBlockPanel({
+	creatureId,
+	creature,
+	isSourceCached,
+	fetchAndCacheSource,
+	uploadAndCacheSource,
+	refreshCache,
+	panelRole,
+	isFolded,
+	onToggleFold,
+	onPin,
+	onUnpin,
+	showPinButton,
+	side,
+	onDismiss,
+	bulkImportMode,
+	bulkImportState,
+	onStartBulkImport,
+	onBulkImportDone,
+}: StatBlockPanelProps) {
+	const [isDesktop, setIsDesktop] = useState(
+		() => window.matchMedia("(min-width: 1024px)").matches,
+	);
+	const [needsFetch, setNeedsFetch] = useState(false);
+	const [checkingCache, setCheckingCache] = useState(false);
+
+	useEffect(() => {
+		const mq = window.matchMedia("(min-width: 1024px)");
+		const handler = (e: MediaQueryListEvent) => setIsDesktop(e.matches);
+		mq.addEventListener("change", handler);
+		return () => mq.removeEventListener("change", handler);
+	}, []);
+
+	useEffect(() => {
+		if (!creatureId || creature) {
+			setNeedsFetch(false);
+			return;
+		}
+
+		const sourceCode = extractSourceCode(creatureId);
+		if (!sourceCode) {
+			setNeedsFetch(false);
+			return;
+		}
+
+		setCheckingCache(true);
+		isSourceCached(sourceCode).then((cached) => {
+			setNeedsFetch(!cached);
+			setCheckingCache(false);
+		});
+	}, [creatureId, creature, isSourceCached]);
+
+	if (!creatureId && !bulkImportMode) return null;
+
+	const sourceCode = creatureId ? extractSourceCode(creatureId) : "";
+
+	const handleSourceLoaded = async () => {
+		await refreshCache();
+		setNeedsFetch(false);
+	};
+
+	const renderContent = () => {
+		if (
+			bulkImportMode &&
+			bulkImportState &&
+			onStartBulkImport &&
+			onBulkImportDone
+		) {
+			return (
+				<BulkImportPrompt
+					importState={bulkImportState}
+					onStartImport={onStartBulkImport}
+					onDone={onBulkImportDone}
+				/>
+			);
+		}
+
+		if (checkingCache) {
+			return (
+				<div className="p-4 text-sm text-muted-foreground">Loading...</div>
+			);
+		}
+
+		if (creature) {
+			return <StatBlock creature={creature} />;
+		}
+
+		if (needsFetch && sourceCode) {
+			return (
+				<SourceFetchPrompt
+					sourceCode={sourceCode}
+					sourceDisplayName={getSourceDisplayName(sourceCode)}
+					fetchAndCacheSource={fetchAndCacheSource}
+					onSourceLoaded={handleSourceLoaded}
+					onUploadSource={uploadAndCacheSource}
+				/>
+			);
+		}
+
+		return (
+			<div className="p-4 text-sm text-muted-foreground">
+				No stat block available
+			</div>
+		);
+	};
+
+	const creatureName =
+		creature?.name ?? (bulkImportMode ? "Bulk Import" : "Creature");
+
+	if (isDesktop) {
+		return (
+			<DesktopPanel
+				isFolded={isFolded}
+				side={side}
+				creatureName={creatureName}
+				panelRole={panelRole}
+				showPinButton={showPinButton}
+				onToggleFold={onToggleFold}
+				onPin={onPin}
+				onUnpin={onUnpin}
+			>
+				{renderContent()}
+			</DesktopPanel>
+		);
+	}
+
+	if (panelRole === "pinned") return null;
+
+	return <MobileDrawer onDismiss={onDismiss}>{renderContent()}</MobileDrawer>;
+}

apps/web/src/components/stat-block.tsx

@@ -0,0 +1,259 @@
+import {
+	type Creature,
+	calculateInitiative,
+	formatInitiativeModifier,
+} from "@initiative/domain";
+
+interface StatBlockProps {
+	creature: Creature;
+}
+
+function abilityMod(score: number): string {
+	const mod = Math.floor((score - 10) / 2);
+	return mod >= 0 ? `+${mod}` : `${mod}`;
+}
+
+function PropertyLine({
+	label,
+	value,
+}: {
+	label: string;
+	value: string | undefined;
+}) {
+	if (!value) return null;
+	return (
+		<div className="text-sm">
+			<span className="font-semibold">{label}</span> {value}
+		</div>
+	);
+}
+
+function SectionDivider() {
+	return (
+		<div className="my-2 h-px bg-gradient-to-r from-amber-800/60 via-amber-700/40 to-transparent" />
+	);
+}
+
+export function StatBlock({ creature }: StatBlockProps) {
+	const abilities = [
+		{ label: "STR", score: creature.abilities.str },
+		{ label: "DEX", score: creature.abilities.dex },
+		{ label: "CON", score: creature.abilities.con },
+		{ label: "INT", score: creature.abilities.int },
+		{ label: "WIS", score: creature.abilities.wis },
+		{ label: "CHA", score: creature.abilities.cha },
+	];
+
+	const initiative = calculateInitiative({
+		dexScore: creature.abilities.dex,
+		cr: creature.cr,
+		initiativeProficiency: creature.initiativeProficiency,
+	});
+
+	return (
+		<div className="space-y-1 text-foreground">
+			{/* Header */}
+			<div>
+				<h2 className="text-xl font-bold text-amber-400">{creature.name}</h2>
+				<p className="text-sm italic text-muted-foreground">
+					{creature.size} {creature.type}, {creature.alignment}
+				</p>
+				<p className="text-xs text-muted-foreground">
+					{creature.sourceDisplayName}
+				</p>
+			</div>
+
+			<SectionDivider />
+
+			{/* Stats bar */}
+			<div className="space-y-0.5 text-sm">
+				<div>
+					<span className="font-semibold">Armor Class</span> {creature.ac}
+					{creature.acSource && (
+						<span className="text-muted-foreground">
+							{" "}
+							({creature.acSource})
+						</span>
+					)}
+					<span className="ml-3">
+						<span className="font-semibold">Initiative</span>{" "}
+						{formatInitiativeModifier(initiative.modifier)} (
+						{initiative.passive})
+					</span>
+				</div>
+				<div>
+					<span className="font-semibold">Hit Points</span>{" "}
+					{creature.hp.average}{" "}
+					<span className="text-muted-foreground">({creature.hp.formula})</span>
+				</div>
+				<div>
+					<span className="font-semibold">Speed</span> {creature.speed}
+				</div>
+			</div>
+
+			<SectionDivider />
+
+			{/* Ability scores */}
+			<div className="grid grid-cols-6 gap-1 text-center text-sm">
+				{abilities.map(({ label, score }) => (
+					<div key={label}>
+						<div className="font-semibold">{label}</div>
+						<div>
+							{score}{" "}
+							<span className="text-muted-foreground">
+								({abilityMod(score)})
+							</span>
+						</div>
+					</div>
+				))}
+			</div>
+
+			<SectionDivider />
+
+			{/* Properties */}
+			<div className="space-y-0.5">
+				<PropertyLine label="Saving Throws" value={creature.savingThrows} />
+				<PropertyLine label="Skills" value={creature.skills} />
+				<PropertyLine
+					label="Damage Vulnerabilities"
+					value={creature.vulnerable}
+				/>
+				<PropertyLine label="Damage Resistances" value={creature.resist} />
+				<PropertyLine label="Damage Immunities" value={creature.immune} />
+				<PropertyLine
+					label="Condition Immunities"
+					value={creature.conditionImmune}
+				/>
+				<PropertyLine label="Senses" value={creature.senses} />
+				<PropertyLine label="Languages" value={creature.languages} />
+				<div className="text-sm">
+					<span className="font-semibold">Challenge</span> {creature.cr}{" "}
+					<span className="text-muted-foreground">
+						(Proficiency Bonus +{creature.proficiencyBonus})
+					</span>
+				</div>
+			</div>
+
+			{/* Traits */}
+			{creature.traits && creature.traits.length > 0 && (
+				<>
+					<SectionDivider />
+					<div className="space-y-2">
+						{creature.traits.map((t) => (
+							<div key={t.name} className="text-sm">
+								<span className="font-semibold italic">{t.name}.</span> {t.text}
+							</div>
+						))}
+					</div>
+				</>
+			)}
+
+			{/* Spellcasting */}
+			{creature.spellcasting && creature.spellcasting.length > 0 && (
+				<>
+					<SectionDivider />
+					{creature.spellcasting.map((sc) => (
+						<div key={sc.name} className="space-y-1 text-sm">
+							<div>
+								<span className="font-semibold italic">{sc.name}.</span>{" "}
+								{sc.headerText}
+							</div>
+							{sc.atWill && sc.atWill.length > 0 && (
+								<div className="pl-2">
+									<span className="font-semibold">At Will:</span>{" "}
+									{sc.atWill.join(", ")}
+								</div>
+							)}
+							{sc.daily?.map((d) => (
+								<div key={`${d.uses}${d.each ? "e" : ""}`} className="pl-2">
+									<span className="font-semibold">
+										{d.uses}/day
+										{d.each ? " each" : ""}:
+									</span>{" "}
+									{d.spells.join(", ")}
+								</div>
+							))}
+							{sc.restLong?.map((d) => (
+								<div
+									key={`rest-${d.uses}${d.each ? "e" : ""}`}
+									className="pl-2"
+								>
+									<span className="font-semibold">
+										{d.uses}/long rest
+										{d.each ? " each" : ""}:
+									</span>{" "}
+									{d.spells.join(", ")}
+								</div>
+							))}
+						</div>
+					))}
+				</>
+			)}
+
+			{/* Actions */}
+			{creature.actions && creature.actions.length > 0 && (
+				<>
+					<SectionDivider />
+					<h3 className="text-base font-bold text-amber-400">Actions</h3>
+					<div className="space-y-2">
+						{creature.actions.map((a) => (
+							<div key={a.name} className="text-sm">
+								<span className="font-semibold italic">{a.name}.</span> {a.text}
+							</div>
+						))}
+					</div>
+				</>
+			)}
+
+			{/* Bonus Actions */}
+			{creature.bonusActions && creature.bonusActions.length > 0 && (
+				<>
+					<SectionDivider />
+					<h3 className="text-base font-bold text-amber-400">Bonus Actions</h3>
+					<div className="space-y-2">
+						{creature.bonusActions.map((a) => (
+							<div key={a.name} className="text-sm">
+								<span className="font-semibold italic">{a.name}.</span> {a.text}
+							</div>
+						))}
+					</div>
+				</>
+			)}
+
+			{/* Reactions */}
+			{creature.reactions && creature.reactions.length > 0 && (
+				<>
+					<SectionDivider />
+					<h3 className="text-base font-bold text-amber-400">Reactions</h3>
+					<div className="space-y-2">
+						{creature.reactions.map((a) => (
+							<div key={a.name} className="text-sm">
+								<span className="font-semibold italic">{a.name}.</span> {a.text}
+							</div>
+						))}
+					</div>
+				</>
+			)}
+
+			{/* Legendary Actions */}
+			{creature.legendaryActions && (
+				<>
+					<SectionDivider />
+					<h3 className="text-base font-bold text-amber-400">
+						Legendary Actions
+					</h3>
+					<p className="text-sm italic text-muted-foreground">
+						{creature.legendaryActions.preamble}
+					</p>
+					<div className="space-y-2">
+						{creature.legendaryActions.entries.map((a) => (
+							<div key={a.name} className="text-sm">
+								<span className="font-semibold italic">{a.name}.</span> {a.text}
+							</div>
+						))}
+					</div>
+				</>
+			)}
+		</div>
+	);
+}

apps/web/src/components/toast.tsx

@@ -0,0 +1,49 @@
+import { X } from "lucide-react";
+import { useEffect } from "react";
+import { createPortal } from "react-dom";
+import { Button } from "./ui/button.js";
+
+interface ToastProps {
+	message: string;
+	progress?: number;
+	onDismiss: () => void;
+	autoDismissMs?: number;
+}
+
+export function Toast({
+	message,
+	progress,
+	onDismiss,
+	autoDismissMs,
+}: ToastProps) {
+	useEffect(() => {
+		if (autoDismissMs === undefined) return;
+		const timer = setTimeout(onDismiss, autoDismissMs);
+		return () => clearTimeout(timer);
+	}, [autoDismissMs, onDismiss]);
+
+	return createPortal(
+		<div className="fixed bottom-4 left-1/2 z-50 -translate-x-1/2">
+			<div className="flex items-center gap-3 rounded-lg border border-border bg-card px-4 py-3 shadow-lg">
+				<span className="text-sm text-foreground">{message}</span>
+				{progress !== undefined && (
+					<div className="h-2 w-24 overflow-hidden rounded-full bg-muted">
+						<div
+							className="h-full rounded-full bg-primary transition-all"
+							style={{ width: `${Math.round(progress * 100)}%` }}
+						/>
+					</div>
+				)}
+				<Button
+					variant="ghost"
+					size="icon-sm"
+					onClick={onDismiss}
+					className="text-muted-foreground"
+				>
+					<X className="h-3 w-3" />
+				</Button>
+			</div>
+		</div>,
+		document.body,
+	);
+}

apps/web/src/components/turn-navigation.tsx

@@ -0,0 +1,68 @@
+import type { Encounter } from "@initiative/domain";
+import { StepBack, StepForward, Trash2 } from "lucide-react";
+import { Button } from "./ui/button";
+import { ConfirmButton } from "./ui/confirm-button";
+
+interface TurnNavigationProps {
+	encounter: Encounter;
+	onAdvanceTurn: () => void;
+	onRetreatTurn: () => void;
+	onClearEncounter: () => void;
+}
+
+export function TurnNavigation({
+	encounter,
+	onAdvanceTurn,
+	onRetreatTurn,
+	onClearEncounter,
+}: TurnNavigationProps) {
+	const hasCombatants = encounter.combatants.length > 0;
+	const isAtStart = encounter.roundNumber === 1 && encounter.activeIndex === 0;
+	const activeCombatant = encounter.combatants[encounter.activeIndex];
+
+	return (
+		<div className="flex items-center gap-3 rounded-md border border-border bg-card px-4 py-3">
+			<Button
+				variant="outline"
+				size="icon"
+				onClick={onRetreatTurn}
+				disabled={!hasCombatants || isAtStart}
+				title="Previous turn"
+				aria-label="Previous turn"
+			>
+				<StepBack className="h-5 w-5" />
+			</Button>
+
+			<div className="min-w-0 flex-1 flex items-center justify-center gap-2 text-sm">
+				<span className="rounded-full bg-muted text-foreground text-sm px-2 py-0.5 font-semibold shrink-0">
+					R{encounter.roundNumber}
+				</span>
+				{activeCombatant ? (
+					<span className="truncate font-medium">{activeCombatant.name}</span>
+				) : (
+					<span className="text-muted-foreground">No combatants</span>
+				)}
+			</div>
+
+			<div className="flex flex-shrink-0 items-center gap-3">
+				<ConfirmButton
+					icon={<Trash2 className="h-5 w-5" />}
+					label="Clear encounter"
+					onConfirm={onClearEncounter}
+					disabled={!hasCombatants}
+					className="text-muted-foreground"
+				/>
+				<Button
+					variant="outline"
+					size="icon"
+					onClick={onAdvanceTurn}
+					disabled={!hasCombatants}
+					title="Next turn"
+					aria-label="Next turn"
+				>
+					<StepForward className="h-5 w-5" />
+				</Button>
+			</div>
+		</div>
+	);
+}

apps/web/src/components/ui/button.tsx

@@ -0,0 +1,38 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import type { ButtonHTMLAttributes } from "react";
+import { cn } from "../../lib/utils";
+
+const buttonVariants = cva(
+	"inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary disabled:pointer-events-none disabled:opacity-50",
+	{
+		variants: {
+			variant: {
+				default: "bg-primary text-primary-foreground hover:bg-primary/90",
+				outline:
+					"border border-border bg-transparent hover:bg-hover-neutral-bg hover:text-hover-neutral",
+				ghost: "hover:bg-hover-neutral-bg hover:text-hover-neutral",
+			},
+			size: {
+				default: "h-8 px-3 text-xs",
+				icon: "h-8 w-8",
+				"icon-sm": "h-6 w-6",
+			},
+		},
+		defaultVariants: {
+			variant: "default",
+			size: "default",
+		},
+	},
+);
+
+type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> &
+	VariantProps<typeof buttonVariants>;
+
+export function Button({ className, variant, size, ...props }: ButtonProps) {
+	return (
+		<button
+			className={cn(buttonVariants({ variant, size, className }))}
+			{...props}
+		/>
+	);
+}

apps/web/src/components/ui/confirm-button.tsx

@@ -0,0 +1,117 @@
+import { Check } from "lucide-react";
+import {
+	type ReactElement,
+	useCallback,
+	useEffect,
+	useRef,
+	useState,
+} from "react";
+import { cn } from "../../lib/utils";
+import { Button } from "./button";
+
+interface ConfirmButtonProps {
+	readonly onConfirm: () => void;
+	readonly icon: ReactElement;
+	readonly label: string;
+	readonly size?: "icon" | "icon-sm";
+	readonly className?: string;
+	readonly disabled?: boolean;
+}
+
+const REVERT_TIMEOUT_MS = 5_000;
+
+export function ConfirmButton({
+	onConfirm,
+	icon,
+	label,
+	size = "icon",
+	className,
+	disabled,
+}: ConfirmButtonProps) {
+	const [isConfirming, setIsConfirming] = useState(false);
+	const timerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+	const wrapperRef = useRef<HTMLDivElement>(null);
+
+	const revert = useCallback(() => {
+		setIsConfirming(false);
+		clearTimeout(timerRef.current);
+	}, []);
+
+	// Cleanup timer on unmount
+	useEffect(() => {
+		return () => clearTimeout(timerRef.current);
+	}, []);
+
+	// Click-outside listener when confirming
+	useEffect(() => {
+		if (!isConfirming) return;
+
+		function handleMouseDown(e: MouseEvent) {
+			if (
+				wrapperRef.current &&
+				!wrapperRef.current.contains(e.target as Node)
+			) {
+				revert();
+			}
+		}
+
+		function handleKeyDown(e: KeyboardEvent) {
+			if (e.key === "Escape") {
+				revert();
+			}
+		}
+
+		document.addEventListener("mousedown", handleMouseDown);
+		document.addEventListener("keydown", handleKeyDown);
+		return () => {
+			document.removeEventListener("mousedown", handleMouseDown);
+			document.removeEventListener("keydown", handleKeyDown);
+		};
+	}, [isConfirming, revert]);
+
+	const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
+		if (e.key === "Enter" || e.key === " ") {
+			e.stopPropagation();
+		}
+	}, []);
+
+	const handleClick = useCallback(
+		(e: React.MouseEvent) => {
+			e.stopPropagation();
+			if (disabled) return;
+
+			if (isConfirming) {
+				revert();
+				onConfirm();
+			} else {
+				setIsConfirming(true);
+				clearTimeout(timerRef.current);
+				timerRef.current = setTimeout(revert, REVERT_TIMEOUT_MS);
+			}
+		},
+		[isConfirming, disabled, onConfirm, revert],
+	);
+
+	return (
+		<div ref={wrapperRef} className="inline-flex">
+			<Button
+				variant="ghost"
+				size={size}
+				className={cn(
+					className,
+					isConfirming
+						? "bg-destructive text-primary-foreground rounded-md animate-confirm-pulse hover:bg-destructive hover:text-primary-foreground"
+						: "hover:text-hover-destructive",
+				)}
+				onClick={handleClick}
+				onKeyDown={handleKeyDown}
+				onBlur={revert}
+				disabled={disabled}
+				aria-label={isConfirming ? `Confirm ${label.toLowerCase()}` : label}
+				title={isConfirming ? `Confirm ${label.toLowerCase()}` : label}
+			>
+				{isConfirming ? <Check size={16} /> : icon}
+			</Button>
+		</div>
+	);
+}

apps/web/src/components/ui/input.tsx

@@ -0,0 +1,19 @@
+import { forwardRef, type InputHTMLAttributes } from "react";
+import { cn } from "../../lib/utils";
+
+type InputProps = InputHTMLAttributes<HTMLInputElement>;
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(
+	({ className, ...props }, ref) => {
+		return (
+			<input
+				ref={ref}
+				className={cn(
+					"flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm text-foreground shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-primary disabled:cursor-not-allowed disabled:opacity-50",
+					className,
+				)}
+				{...props}
+			/>
+		);
+	},
+);

apps/web/src/components/ui/overflow-menu.tsx

@@ -0,0 +1,72 @@
+import { EllipsisVertical } from "lucide-react";
+import { type ReactNode, useEffect, useRef, useState } from "react";
+import { Button } from "./button";
+
+export interface OverflowMenuItem {
+	readonly icon: ReactNode;
+	readonly label: string;
+	readonly onClick: () => void;
+	readonly disabled?: boolean;
+}
+
+interface OverflowMenuProps {
+	readonly items: readonly OverflowMenuItem[];
+}
+
+export function OverflowMenu({ items }: OverflowMenuProps) {
+	const [open, setOpen] = useState(false);
+	const ref = useRef<HTMLDivElement>(null);
+
+	useEffect(() => {
+		if (!open) return;
+		function handleMouseDown(e: MouseEvent) {
+			if (ref.current && !ref.current.contains(e.target as Node)) {
+				setOpen(false);
+			}
+		}
+		function handleKeyDown(e: KeyboardEvent) {
+			if (e.key === "Escape") setOpen(false);
+		}
+		document.addEventListener("mousedown", handleMouseDown);
+		document.addEventListener("keydown", handleKeyDown);
+		return () => {
+			document.removeEventListener("mousedown", handleMouseDown);
+			document.removeEventListener("keydown", handleKeyDown);
+		};
+	}, [open]);
+
+	return (
+		<div ref={ref} className="relative">
+			<Button
+				type="button"
+				variant="ghost"
+				size="icon"
+				className="text-muted-foreground hover:text-hover-neutral"
+				onClick={() => setOpen((o) => !o)}
+				aria-label="More actions"
+				title="More actions"
+			>
+				<EllipsisVertical className="h-5 w-5" />
+			</Button>
+			{open && (
+				<div className="absolute bottom-full right-0 z-50 mb-1 min-w-48 rounded-md border border-border bg-card py-1 shadow-lg">
+					{items.map((item) => (
+						<button
+							key={item.label}
+							type="button"
+							className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-sm text-foreground hover:bg-hover-neutral-bg disabled:pointer-events-none disabled:opacity-50"
+							disabled={item.disabled}
+							onClick={() => {
+								item.onClick();
+								setOpen(false);
+							}}
+						>
+							{item.icon}
+							{item.label}
+						</button>
+					))}
+				</div>
+			)}
+		</div>
+	);
+}

apps/web/src/hooks/use-bestiary.ts

@@ -0,0 +1,126 @@
+import type {
+	BestiaryIndexEntry,
+	Creature,
+	CreatureId,
+} from "@initiative/domain";
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+	normalizeBestiary,
+	setSourceDisplayNames,
+} from "../adapters/bestiary-adapter.js";
+import * as bestiaryCache from "../adapters/bestiary-cache.js";
+import {
+	getSourceDisplayName,
+	loadBestiaryIndex,
+} from "../adapters/bestiary-index-adapter.js";
+
+export interface SearchResult extends BestiaryIndexEntry {
+	readonly sourceDisplayName: string;
+}
+
+interface BestiaryHook {
+	search: (query: string) => SearchResult[];
+	getCreature: (id: CreatureId) => Creature | undefined;
+	isLoaded: boolean;
+	isSourceCached: (sourceCode: string) => Promise<boolean>;
+	fetchAndCacheSource: (sourceCode: string, url: string) => Promise<void>;
+	uploadAndCacheSource: (
+		sourceCode: string,
+		jsonData: unknown,
+	) => Promise<void>;
+	refreshCache: () => Promise<void>;
+}
+
+export function useBestiary(): BestiaryHook {
+	const [isLoaded, setIsLoaded] = useState(false);
+	const creatureMapRef = useRef<Map<CreatureId, Creature>>(new Map());
+	const [, setTick] = useState(0);
+
+	useEffect(() => {
+		const index = loadBestiaryIndex();
+		setSourceDisplayNames(index.sources as Record<string, string>);
+		if (index.creatures.length > 0) {
+			setIsLoaded(true);
+		}
+
+		bestiaryCache.loadAllCachedCreatures().then((map) => {
+			creatureMapRef.current = map;
+			setTick((t) => t + 1);
+		});
+	}, []);
+
+	const search = useCallback((query: string): SearchResult[] => {
+		if (query.length < 2) return [];
+		const lower = query.toLowerCase();
+		const index = loadBestiaryIndex();
+		return index.creatures
+			.filter((c) => c.name.toLowerCase().includes(lower))
+			.sort((a, b) => a.name.localeCompare(b.name))
+			.slice(0, 10)
+			.map((c) => ({
+				...c,
+				sourceDisplayName: getSourceDisplayName(c.source),
+			}));
+	}, []);
+
+	const getCreature = useCallback((id: CreatureId): Creature | undefined => {
+		return creatureMapRef.current.get(id);
+	}, []);
+
+	const isSourceCachedFn = useCallback(
+		(sourceCode: string): Promise<boolean> => {
+			return bestiaryCache.isSourceCached(sourceCode);
+		},
+		[],
+	);
+
+	const fetchAndCacheSource = useCallback(
+		async (sourceCode: string, url: string): Promise<void> => {
+			const response = await fetch(url);
+			if (!response.ok) {
+				throw new Error(
+					`Failed to fetch: ${response.status} ${response.statusText}`,
+				);
+			}
+			const json = await response.json();
+			const creatures = normalizeBestiary(json);
+			const displayName = getSourceDisplayName(sourceCode);
+			await bestiaryCache.cacheSource(sourceCode, displayName, creatures);
+			for (const c of creatures) {
+				creatureMapRef.current.set(c.id, c);
+			}
+			setTick((t) => t + 1);
+		},
+		[],
+	);
+
+	const uploadAndCacheSource = useCallback(
+		async (sourceCode: string, jsonData: unknown): Promise<void> => {
+			// biome-ignore lint/suspicious/noExplicitAny: raw JSON shape varies
+			const creatures = normalizeBestiary(jsonData as any);
+			const displayName = getSourceDisplayName(sourceCode);
+			await bestiaryCache.cacheSource(sourceCode, displayName, creatures);
+			for (const c of creatures) {
+				creatureMapRef.current.set(c.id, c);
+			}
+			setTick((t) => t + 1);
+		},
+		[],
+	);
+
+	const refreshCache = useCallback(async (): Promise<void> => {
+		const map = await bestiaryCache.loadAllCachedCreatures();
+		creatureMapRef.current = map;
+		setTick((t) => t + 1);
+	}, []);
+
+	return {
+		search,
+		getCreature,
+		isLoaded,
+		isSourceCached: isSourceCachedFn,
+		fetchAndCacheSource,
+		uploadAndCacheSource,
+		refreshCache,
+	};
+}

apps/web/src/hooks/use-bulk-import.ts

@@ -0,0 +1,120 @@
+import { useCallback, useRef, useState } from "react";
+import {
+	getAllSourceCodes,
+	getDefaultFetchUrl,
+} from "../adapters/bestiary-index-adapter.js";
+
+const BATCH_SIZE = 6;
+
+export interface BulkImportState {
+	readonly status: "idle" | "loading" | "complete" | "partial-failure";
+	readonly total: number;
+	readonly completed: number;
+	readonly failed: number;
+}
+
+const IDLE_STATE: BulkImportState = {
+	status: "idle",
+	total: 0,
+	completed: 0,
+	failed: 0,
+};
+
+interface BulkImportHook {
+	state: BulkImportState;
+	startImport: (
+		baseUrl: string,
+		fetchAndCacheSource: (sourceCode: string, url: string) => Promise<void>,
+		isSourceCached: (sourceCode: string) => Promise<boolean>,
+		refreshCache: () => Promise<void>,
+	) => void;
+	reset: () => void;
+}
+
+export function useBulkImport(): BulkImportHook {
+	const [state, setState] = useState<BulkImportState>(IDLE_STATE);
+	const countersRef = useRef({ completed: 0, failed: 0 });
+
+	const startImport = useCallback(
+		(
+			baseUrl: string,
+			fetchAndCacheSource: (sourceCode: string, url: string) => Promise<void>,
+			isSourceCached: (sourceCode: string) => Promise<boolean>,
+			refreshCache: () => Promise<void>,
+		) => {
+			const allCodes = getAllSourceCodes();
+			const total = allCodes.length;
+
+			countersRef.current = { completed: 0, failed: 0 };
+			setState({ status: "loading", total, completed: 0, failed: 0 });
+
+			(async () => {
+				const cacheChecks = await Promise.all(
+					allCodes.map(async (code) => ({
+						code,
+						cached: await isSourceCached(code),
+					})),
+				);
+
+				const alreadyCached = cacheChecks.filter((c) => c.cached).length;
+				const uncached = cacheChecks.filter((c) => !c.cached);
+
+				countersRef.current.completed = alreadyCached;
+
+				if (uncached.length === 0) {
+					setState({
+						status: "complete",
+						total,
+						completed: total,
+						failed: 0,
+					});
+					return;
+				}
+
+				setState((s) => ({ ...s, completed: alreadyCached }));
+
+				for (let i = 0; i < uncached.length; i += BATCH_SIZE) {
+					const batch = uncached.slice(i, i + BATCH_SIZE);
+					await Promise.allSettled(
+						batch.map(async ({ code }) => {
+							const url = getDefaultFetchUrl(code, baseUrl);
+							try {
+								await fetchAndCacheSource(code, url);
+								countersRef.current.completed++;
+							} catch (err) {
+								countersRef.current.failed++;
+								console.warn(
+									`[bulk-import] FAILED ${code} (${url}):`,
+									err instanceof Error ? err.message : err,
+								);
+							}
+							setState({
+								status: "loading",
+								total,
+								completed: countersRef.current.completed,
+								failed: countersRef.current.failed,
+							});
+						}),
+					);
+				}
+
+				await refreshCache();
+
+				const { completed, failed } = countersRef.current;
+				setState({
+					status: failed > 0 ? "partial-failure" : "complete",
+					total,
+					completed,
+					failed,
+				});
+			})();
+		},
+		[],
+	);
+
+	const reset = useCallback(() => {
+		setState(IDLE_STATE);
+	}, []);
+
+	return { state, startImport, reset };
+}

apps/web/src/hooks/use-encounter.ts

@@ -1,43 +1,106 @@
 import type { EncounterStore } from "@initiative/application";
 import {
 	addCombatantUseCase,
+	adjustHpUseCase,
 	advanceTurnUseCase,
+	clearEncounterUseCase,
 	editCombatantUseCase,
 	removeCombatantUseCase,
+	retreatTurnUseCase,
+	setAcUseCase,
+	setHpUseCase,
 	setInitiativeUseCase,
+	toggleConcentrationUseCase,
+	toggleConditionUseCase,
 } from "@initiative/application";
-import type { CombatantId, DomainEvent, Encounter } from "@initiative/domain";
+import type {
+	BestiaryIndexEntry,
+	CombatantId,
+	ConditionId,
+	DomainEvent,
+	Encounter,
+	PlayerCharacter,
+} from "@initiative/domain";
 import {
 	combatantId,
-	createEncounter,
 	isDomainError,
+	creatureId as makeCreatureId,
+	resolveCreatureName,
 } from "@initiative/domain";
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+	loadEncounter,
+	saveEncounter,
+} from "../persistence/encounter-storage.js";
 
-function createDemoEncounter(): Encounter {
-	const result = createEncounter([
-		{ id: combatantId("1"), name: "Aria" },
-		{ id: combatantId("2"), name: "Brak" },
-		{ id: combatantId("3"), name: "Cael" },
-	]);
+const EMPTY_ENCOUNTER: Encounter = {
+	combatants: [],
+	activeIndex: 0,
+	roundNumber: 1,
+};
 
-	if (isDomainError(result)) {
-		throw new Error(`Failed to create demo encounter: ${result.message}`);
+function initializeEncounter(): Encounter {
+	const stored = loadEncounter();
+	if (stored !== null) return stored;
+	return EMPTY_ENCOUNTER;
+}
+
+function deriveNextId(encounter: Encounter): number {
+	let max = 0;
+	for (const c of encounter.combatants) {
+		const match = /^c-(\d+)$/.exec(c.id);
+		if (match) {
+			const n = Number.parseInt(match[1], 10);
+			if (n > max) max = n;
+		}
 	}
+	return max;
+}
 
-	return result;
+interface CombatantOpts {
+	initiative?: number;
+	ac?: number;
+	maxHp?: number;
+}
+
+function applyCombatantOpts(
+	makeStore: () => EncounterStore,
+	id: ReturnType<typeof combatantId>,
+	opts: CombatantOpts,
+): DomainEvent[] {
+	const events: DomainEvent[] = [];
+	if (opts.maxHp !== undefined) {
+		const r = setHpUseCase(makeStore(), id, opts.maxHp);
+		if (!isDomainError(r)) events.push(...r);
+	}
+	if (opts.ac !== undefined) {
+		const r = setAcUseCase(makeStore(), id, opts.ac);
+		if (!isDomainError(r)) events.push(...r);
+	}
+	if (opts.initiative !== undefined) {
+		const r = setInitiativeUseCase(makeStore(), id, opts.initiative);
+		if (!isDomainError(r)) events.push(...r);
+	}
+	return events;
 }
 
 export function useEncounter() {
-	const [encounter, setEncounter] = useState<Encounter>(createDemoEncounter);
+	const [encounter, setEncounter] = useState<Encounter>(initializeEncounter);
 	const [events, setEvents] = useState<DomainEvent[]>([]);
 	const encounterRef = useRef(encounter);
 	encounterRef.current = encounter;
 
+	useEffect(() => {
+		saveEncounter(encounter);
+	}, [encounter]);
+
 	const makeStore = useCallback((): EncounterStore => {
 		return {
 			get: () => encounterRef.current,
-			save: (e) => setEncounter(e),
+			save: (e) => {
+				encounterRef.current = e;
+				setEncounter(e);
+			},
 		};
 	}, []);
 
@@ -51,10 +114,20 @@ export function useEncounter() {
 		setEvents((prev) => [...prev, ...result]);
 	}, [makeStore]);
 
-	const nextId = useRef(0);
+	const retreatTurn = useCallback(() => {
+		const result = retreatTurnUseCase(makeStore());
+
+		if (isDomainError(result)) {
+			return;
+		}
+
+		setEvents((prev) => [...prev, ...result]);
+	}, [makeStore]);
+
+	const nextId = useRef(deriveNextId(encounter));
 
 	const addCombatant = useCallback(
-		(name: string) => {
+		(name: string, opts?: CombatantOpts) => {
 			const id = combatantId(`c-${++nextId.current}`);
 			const result = addCombatantUseCase(makeStore(), id, name);
 
@@ -62,6 +135,13 @@ export function useEncounter() {
 				return;
 			}
 
+			if (opts) {
+				const optEvents = applyCombatantOpts(makeStore, id, opts);
+				if (optEvents.length > 0) {
+					setEvents((prev) => [...prev, ...optEvents]);
+				}
+			}
+
 			setEvents((prev) => [...prev, ...result]);
 		},
 		[makeStore],
@@ -106,13 +186,208 @@ export function useEncounter() {
 		[makeStore],
 	);
 
+	const setHp = useCallback(
+		(id: CombatantId, maxHp: number | undefined) => {
+			const result = setHpUseCase(makeStore(), id, maxHp);
+
+			if (isDomainError(result)) {
+				return;
+			}
+
+			setEvents((prev) => [...prev, ...result]);
+		},
+		[makeStore],
+	);
+
+	const adjustHp = useCallback(
+		(id: CombatantId, delta: number) => {
+			const result = adjustHpUseCase(makeStore(), id, delta);
+
+			if (isDomainError(result)) {
+				return;
+			}
+
+			setEvents((prev) => [...prev, ...result]);
+		},
+		[makeStore],
+	);
+
+	const setAc = useCallback(
+		(id: CombatantId, value: number | undefined) => {
+			const result = setAcUseCase(makeStore(), id, value);
+
+			if (isDomainError(result)) {
+				return;
+			}
+
+			setEvents((prev) => [...prev, ...result]);
+		},
+		[makeStore],
+	);
+
+	const toggleCondition = useCallback(
+		(id: CombatantId, conditionId: ConditionId) => {
+			const result = toggleConditionUseCase(makeStore(), id, conditionId);
+
+			if (isDomainError(result)) {
+				return;
+			}
+
+			setEvents((prev) => [...prev, ...result]);
+		},
+		[makeStore],
+	);
+
+	const toggleConcentration = useCallback(
+		(id: CombatantId) => {
+			const result = toggleConcentrationUseCase(makeStore(), id);
+
+			if (isDomainError(result)) {
+				return;
+			}
+
+			setEvents((prev) => [...prev, ...result]);
+		},
+		[makeStore],
+	);
+
+	const clearEncounter = useCallback(() => {
+		const result = clearEncounterUseCase(makeStore());
+
+		if (isDomainError(result)) {
+			return;
+		}
+
+		nextId.current = 0;
+		setEvents((prev) => [...prev, ...result]);
+	}, [makeStore]);
+
+	const addFromBestiary = useCallback(
+		(entry: BestiaryIndexEntry) => {
+			const store = makeStore();
+			const existingNames = store.get().combatants.map((c) => c.name);
+			const { newName, renames } = resolveCreatureName(
+				entry.name,
+				existingNames,
+			);
+
+			// Apply renames (e.g., "Goblin" → "Goblin 1")
+			for (const { from, to } of renames) {
+				const target = store.get().combatants.find((c) => c.name === from);
+				if (target) {
+					editCombatantUseCase(makeStore(), target.id, to);
+				}
+			}
+
+			// Add combatant with resolved name
+			const id = combatantId(`c-${++nextId.current}`);
+			const addResult = addCombatantUseCase(makeStore(), id, newName);
+			if (isDomainError(addResult)) return;
+
+			// Set HP
+			const hpResult = setHpUseCase(makeStore(), id, entry.hp);
+			if (!isDomainError(hpResult)) {
+				setEvents((prev) => [...prev, ...hpResult]);
+			}
+
+			// Set AC
+			if (entry.ac > 0) {
+				const acResult = setAcUseCase(makeStore(), id, entry.ac);
+				if (!isDomainError(acResult)) {
+					setEvents((prev) => [...prev, ...acResult]);
+				}
+			}
+
+			// Derive creatureId from source + name
+			const slug = entry.name
+				.toLowerCase()
+				.replace(/[^a-z0-9]+/g, "-")
+				.replace(/(^-|-$)/g, "");
+			const cId = makeCreatureId(`${entry.source.toLowerCase()}:${slug}`);
+
+			// Set creatureId on the combatant (use store.save to keep ref in sync for batch calls)
+			const currentEncounter = store.get();
+			store.save({
+				...currentEncounter,
+				combatants: currentEncounter.combatants.map((c) =>
+					c.id === id ? { ...c, creatureId: cId } : c,
+				),
+			});
+
+			setEvents((prev) => [...prev, ...addResult]);
+		},
+		[makeStore, editCombatant],
+	);
+
+	const addFromPlayerCharacter = useCallback(
+		(pc: PlayerCharacter) => {
+			const store = makeStore();
+			const existingNames = store.get().combatants.map((c) => c.name);
+			const { newName, renames } = resolveCreatureName(pc.name, existingNames);
+
+			for (const { from, to } of renames) {
+				const target = store.get().combatants.find((c) => c.name === from);
+				if (target) {
+					editCombatantUseCase(makeStore(), target.id, to);
+				}
+			}
+
+			const id = combatantId(`c-${++nextId.current}`);
+			const addResult = addCombatantUseCase(makeStore(), id, newName);
+			if (isDomainError(addResult)) return;
+
+			// Set HP
+			const hpResult = setHpUseCase(makeStore(), id, pc.maxHp);
+			if (!isDomainError(hpResult)) {
+				setEvents((prev) => [...prev, ...hpResult]);
+			}
+
+			// Set AC
+			if (pc.ac > 0) {
+				const acResult = setAcUseCase(makeStore(), id, pc.ac);
+				if (!isDomainError(acResult)) {
+					setEvents((prev) => [...prev, ...acResult]);
+				}
+			}
+
+			// Set color, icon, and playerCharacterId on the combatant
+			const currentEncounter = store.get();
+			store.save({
+				...currentEncounter,
+				combatants: currentEncounter.combatants.map((c) =>
+					c.id === id
+						? {
+								...c,
+								color: pc.color,
+								icon: pc.icon,
+								playerCharacterId: pc.id,
+							}
+						: c,
+				),
+			});
+
+			setEvents((prev) => [...prev, ...addResult]);
+		},
+		[makeStore, editCombatant],
+	);
+
 	return {
 		encounter,
 		events,
 		advanceTurn,
+		retreatTurn,
 		addCombatant,
+		clearEncounter,
 		removeCombatant,
 		editCombatant,
 		setInitiative,
+		setHp,
+		adjustHp,
+		setAc,
+		toggleCondition,
+		toggleConcentration,
+		addFromBestiary,
+		addFromPlayerCharacter,
+		makeStore,
 	} as const;
 }

apps/web/src/hooks/use-player-characters.ts

@@ -0,0 +1,102 @@
+import type { PlayerCharacterStore } from "@initiative/application";
+import {
+	createPlayerCharacterUseCase,
+	deletePlayerCharacterUseCase,
+	editPlayerCharacterUseCase,
+} from "@initiative/application";
+import type { PlayerCharacter, PlayerCharacterId } from "@initiative/domain";
+import { isDomainError, playerCharacterId } from "@initiative/domain";
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+	loadPlayerCharacters,
+	savePlayerCharacters,
+} from "../persistence/player-character-storage.js";
+
+function initializeCharacters(): PlayerCharacter[] {
+	return loadPlayerCharacters();
+}
+
+let nextPcId = 0;
+
+function generatePcId(): PlayerCharacterId {
+	return playerCharacterId(`pc-${++nextPcId}`);
+}
+
+interface EditFields {
+	readonly name?: string;
+	readonly ac?: number;
+	readonly maxHp?: number;
+	readonly color?: string;
+	readonly icon?: string;
+}
+
+export function usePlayerCharacters() {
+	const [characters, setCharacters] =
+		useState<PlayerCharacter[]>(initializeCharacters);
+	const charactersRef = useRef(characters);
+	charactersRef.current = characters;
+
+	useEffect(() => {
+		savePlayerCharacters(characters);
+	}, [characters]);
+
+	const makeStore = useCallback((): PlayerCharacterStore => {
+		return {
+			getAll: () => charactersRef.current,
+			save: (updated) => {
+				charactersRef.current = updated;
+				setCharacters(updated);
+			},
+		};
+	}, []);
+
+	const createCharacter = useCallback(
+		(name: string, ac: number, maxHp: number, color: string, icon: string) => {
+			const id = generatePcId();
+			const result = createPlayerCharacterUseCase(
+				makeStore(),
+				id,
+				name,
+				ac,
+				maxHp,
+				color,
+				icon,
+			);
+			if (isDomainError(result)) {
+				return result;
+			}
+			return undefined;
+		},
+		[makeStore],
+	);
+
+	const editCharacter = useCallback(
+		(id: PlayerCharacterId, fields: EditFields) => {
+			const result = editPlayerCharacterUseCase(makeStore(), id, fields);
+			if (isDomainError(result)) {
+				return result;
+			}
+			return undefined;
+		},
+		[makeStore],
+	);
+
+	const deleteCharacter = useCallback(
+		(id: PlayerCharacterId) => {
+			const result = deletePlayerCharacterUseCase(makeStore(), id);
+			if (isDomainError(result)) {
+				return result;
+			}
+			return undefined;
+		},
+		[makeStore],
+	);
+
+	return {
+		characters,
+		createCharacter,
+		editCharacter,
+		deleteCharacter,
+		makeStore,
+	} as const;
+}

apps/web/src/hooks/use-swipe-to-dismiss.ts

@@ -0,0 +1,72 @@
+import { useCallback, useRef, useState } from "react";
+
+const DISMISS_THRESHOLD = 0.35;
+const VELOCITY_THRESHOLD = 0.5;
+
+interface SwipeState {
+	offsetX: number;
+	isSwiping: boolean;
+}
+
+export function useSwipeToDismiss(onDismiss: () => void) {
+	const [swipe, setSwipe] = useState<SwipeState>({
+		offsetX: 0,
+		isSwiping: false,
+	});
+	const startX = useRef(0);
+	const startY = useRef(0);
+	const startTime = useRef(0);
+	const panelWidth = useRef(0);
+	const directionLocked = useRef<"horizontal" | "vertical" | null>(null);
+
+	const onTouchStart = useCallback((e: React.TouchEvent) => {
+		const touch = e.touches[0];
+		startX.current = touch.clientX;
+		startY.current = touch.clientY;
+		startTime.current = Date.now();
+		directionLocked.current = null;
+		const el = e.currentTarget as HTMLElement;
+		panelWidth.current = el.getBoundingClientRect().width;
+	}, []);
+
+	const onTouchMove = useCallback((e: React.TouchEvent) => {
+		const touch = e.touches[0];
+		const dx = touch.clientX - startX.current;
+		const dy = touch.clientY - startY.current;
+
+		if (!directionLocked.current) {
+			if (Math.abs(dx) < 10 && Math.abs(dy) < 10) return;
+			directionLocked.current =
+				Math.abs(dx) > Math.abs(dy) ? "horizontal" : "vertical";
+		}
+
+		if (directionLocked.current === "vertical") return;
+
+		const clampedX = Math.max(0, dx);
+		setSwipe({ offsetX: clampedX, isSwiping: true });
+	}, []);
+
+	const onTouchEnd = useCallback(() => {
+		if (directionLocked.current !== "horizontal") {
+			setSwipe({ offsetX: 0, isSwiping: false });
+			return;
+		}
+
+		const elapsed = (Date.now() - startTime.current) / 1000;
+		const velocity = swipe.offsetX / elapsed / panelWidth.current;
+		const ratio =
+			panelWidth.current > 0 ? swipe.offsetX / panelWidth.current : 0;
+
+		if (ratio > DISMISS_THRESHOLD || velocity > VELOCITY_THRESHOLD) {
+			onDismiss();
+		}
+
+		setSwipe({ offsetX: 0, isSwiping: false });
+	}, [swipe.offsetX, onDismiss]);
+
+	return {
+		offsetX: swipe.offsetX,
+		isSwiping: swipe.isSwiping,
+		handlers: { onTouchStart, onTouchMove, onTouchEnd },
+	};
+}

apps/web/src/index.css

@@ -0,0 +1,181 @@
+@import "tailwindcss";
+
+@theme {
+	--color-background: #0f172a;
+	--color-foreground: #e2e8f0;
+	--color-muted: #64748b;
+	--color-muted-foreground: #94a3b8;
+	--color-card: #1e293b;
+	--color-card-foreground: #e2e8f0;
+	--color-border: #334155;
+	--color-input: #334155;
+	--color-primary: #3b82f6;
+	--color-primary-foreground: #ffffff;
+	--color-accent: #3b82f6;
+	--color-destructive: #ef4444;
+	--color-hover-neutral: var(--color-primary);
+	--color-hover-action: var(--color-primary);
+	--color-hover-destructive: var(--color-destructive);
+	--color-hover-neutral-bg: oklch(0.623 0.214 259 / 0.15);
+	--color-hover-action-bg: var(--color-muted);
+	--color-hover-destructive-bg: transparent;
+	--radius-sm: 0.25rem;
+	--radius-md: 0.375rem;
+	--radius-lg: 0.5rem;
+	--font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
+}
+
+@keyframes concentration-shake {
+	0% {
+		translate: 0;
+	}
+	20% {
+		translate: -3px;
+	}
+	40% {
+		translate: 3px;
+	}
+	60% {
+		translate: -2px;
+	}
+	80% {
+		translate: 1px;
+	}
+	100% {
+		translate: 0;
+	}
+}
+
+@keyframes concentration-glow {
+	0% {
+		box-shadow: 0 0 4px 2px #c084fc;
+	}
+	100% {
+		box-shadow: 0 0 0 0 transparent;
+	}
+}
+
+@keyframes slide-in-right {
+	from {
+		translate: 100%;
+	}
+	to {
+		translate: 0;
+	}
+}
+
+@utility animate-slide-in-right {
+	animation: slide-in-right 200ms ease-out;
+}
+
+@keyframes confirm-pulse {
+	0% {
+		scale: 1;
+	}
+	50% {
+		scale: 1.15;
+	}
+	100% {
+		scale: 1;
+	}
+}
+
+@keyframes settle-to-bottom {
+	from {
+		transform: translateY(-40vh);
+		opacity: 0;
+	}
+	40% {
+		opacity: 1;
+	}
+	to {
+		transform: translateY(0);
+		opacity: 1;
+	}
+}
+
+@utility animate-settle-to-bottom {
+	animation: settle-to-bottom 700ms cubic-bezier(0.22, 1, 0.36, 1) backwards;
+}
+
+@keyframes rise-to-center {
+	from {
+		transform: translateY(40vh);
+		opacity: 0;
+	}
+	40% {
+		opacity: 1;
+	}
+	to {
+		transform: translateY(0);
+		opacity: 1;
+	}
+}
+
+@utility animate-rise-to-center {
+	animation: rise-to-center 700ms cubic-bezier(0.22, 1, 0.36, 1) backwards;
+}
+
+@keyframes slide-down-in {
+	from {
+		transform: translateY(-100%);
+		opacity: 0;
+	}
+	to {
+		transform: translateY(0);
+		opacity: 1;
+	}
+}
+
+@utility animate-slide-down-in {
+	animation: slide-down-in 700ms cubic-bezier(0.22, 1, 0.36, 1) backwards;
+}
+
+@keyframes slide-up-out {
+	from {
+		transform: translateY(0);
+		opacity: 1;
+	}
+	60% {
+		opacity: 0;
+	}
+	to {
+		transform: translateY(-100%);
+		opacity: 0;
+	}
+}
+
+@utility animate-slide-up-out {
+	animation: slide-up-out 700ms cubic-bezier(0.22, 1, 0.36, 1) forwards;
+}
+
+@custom-variant pointer-coarse (@media (pointer: coarse));
+
+@utility animate-confirm-pulse {
+	animation: confirm-pulse 300ms ease-out;
+}
+
+@utility transition-slide-panel {
+	transition: translate 200ms ease-out;
+}
+
+@utility writing-vertical-rl {
+	writing-mode: vertical-rl;
+}
+
+@utility animate-concentration-pulse {
+	animation:
+		concentration-shake 450ms ease-out,
+		concentration-glow 1200ms ease-out;
+}
+
+* {
+	scrollbar-color: var(--color-border) transparent;
+	scrollbar-width: thin;
+}
+
+body {
+	background-color: var(--color-background);
+	color: var(--color-foreground);
+	font-family: var(--font-sans);
+}

apps/web/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}

apps/web/src/main.tsx

@@ -1,6 +1,7 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { App } from "./App";
+import "./index.css";
 
 const root = document.getElementById("root");
 if (root) {

apps/web/src/persistence/__tests__/encounter-storage.test.ts

@@ -0,0 +1,296 @@
+import {
+	combatantId,
+	createEncounter,
+	isDomainError,
+} from "@initiative/domain";
+import { beforeEach, describe, expect, it } from "vitest";
+import { loadEncounter, saveEncounter } from "../encounter-storage.js";
+
+const STORAGE_KEY = "initiative:encounter";
+
+function makeEncounter() {
+	const result = createEncounter(
+		[
+			{ id: combatantId("1"), name: "Aria", initiative: 18 },
+			{ id: combatantId("c-2"), name: "Brak", initiative: 12 },
+			{ id: combatantId("3"), name: "Cael" },
+		],
+		1,
+		3,
+	);
+	if (isDomainError(result)) throw new Error("Failed to create test encounter");
+	return result;
+}
+
+function createMockLocalStorage() {
+	const store = new Map<string, string>();
+	return {
+		getItem: (key: string) => store.get(key) ?? null,
+		setItem: (key: string, value: string) => store.set(key, value),
+		removeItem: (key: string) => store.delete(key),
+		clear: () => store.clear(),
+		get length() {
+			return store.size;
+		},
+		key: (_index: number) => null,
+	} as Storage;
+}
+
+beforeEach(() => {
+	Object.defineProperty(globalThis, "localStorage", {
+		value: createMockLocalStorage(),
+		writable: true,
+		configurable: true,
+	});
+});
+
+describe("saveEncounter", () => {
+	it("writes encounter to localStorage", () => {
+		const encounter = makeEncounter();
+		saveEncounter(encounter);
+		expect(localStorage.getItem(STORAGE_KEY)).not.toBeNull();
+	});
+});
+
+describe("loadEncounter", () => {
+	it("returns null when localStorage is empty", () => {
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("round-trip save/load preserves encounter state", () => {
+		const encounter = makeEncounter();
+		saveEncounter(encounter);
+		const loaded = loadEncounter();
+
+		expect(loaded).not.toBeNull();
+		expect(loaded?.combatants).toHaveLength(3);
+		expect(loaded?.activeIndex).toBe(1);
+		expect(loaded?.roundNumber).toBe(3);
+	});
+
+	it("round-trip preserves combatant IDs, names, and initiative values", () => {
+		const encounter = makeEncounter();
+		saveEncounter(encounter);
+		const loaded = loadEncounter();
+		expect(loaded).not.toBeNull();
+
+		expect(loaded?.combatants[0].id).toBe("1");
+		expect(loaded?.combatants[0].name).toBe("Aria");
+		expect(loaded?.combatants[0].initiative).toBe(18);
+
+		expect(loaded?.combatants[1].id).toBe("c-2");
+		expect(loaded?.combatants[1].name).toBe("Brak");
+		expect(loaded?.combatants[1].initiative).toBe(12);
+
+		expect(loaded?.combatants[2].id).toBe("3");
+		expect(loaded?.combatants[2].name).toBe("Cael");
+		expect(loaded?.combatants[2].initiative).toBeUndefined();
+	});
+
+	it("returns null for non-JSON strings", () => {
+		localStorage.setItem(STORAGE_KEY, "not json at all");
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null for JSON missing required fields", () => {
+		localStorage.setItem(STORAGE_KEY, JSON.stringify({ foo: "bar" }));
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns empty encounter for cleared state (empty combatants)", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({ combatants: [], activeIndex: 0, roundNumber: 1 }),
+		);
+		const result = loadEncounter();
+		expect(result).toEqual({
+			combatants: [],
+			activeIndex: 0,
+			roundNumber: 1,
+		});
+	});
+
+	it("returns null for out-of-bounds activeIndex", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({
+				combatants: [{ id: "1", name: "Aria" }],
+				activeIndex: 5,
+				roundNumber: 1,
+			}),
+		);
+		expect(loadEncounter()).toBeNull();
+	});
+
+	// US3: Corrupt data scenarios
+	it("returns null for non-object JSON (string)", () => {
+		localStorage.setItem(STORAGE_KEY, JSON.stringify("hello"));
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null for non-object JSON (number)", () => {
+		localStorage.setItem(STORAGE_KEY, JSON.stringify(42));
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null for non-object JSON (array)", () => {
+		localStorage.setItem(STORAGE_KEY, JSON.stringify([1, 2, 3]));
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null for non-object JSON (null)", () => {
+		localStorage.setItem(STORAGE_KEY, "null");
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null when combatants is a string instead of array", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({
+				combatants: "not-array",
+				activeIndex: 0,
+				roundNumber: 1,
+			}),
+		);
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null when activeIndex is a string instead of number", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({
+				combatants: [{ id: "1", name: "Aria" }],
+				activeIndex: "zero",
+				roundNumber: 1,
+			}),
+		);
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null when combatant entry is missing id", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({
+				combatants: [{ name: "Aria" }],
+				activeIndex: 0,
+				roundNumber: 1,
+			}),
+		);
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null when combatant entry is missing name", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({
+				combatants: [{ id: "1" }],
+				activeIndex: 0,
+				roundNumber: 1,
+			}),
+		);
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns null for negative roundNumber", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({
+				combatants: [{ id: "1", name: "Aria" }],
+				activeIndex: 0,
+				roundNumber: -1,
+			}),
+		);
+		expect(loadEncounter()).toBeNull();
+	});
+
+	it("returns empty encounter for zero combatants (cleared state)", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({ combatants: [], activeIndex: 0, roundNumber: 1 }),
+		);
+		const result = loadEncounter();
+		expect(result).toEqual({
+			combatants: [],
+			activeIndex: 0,
+			roundNumber: 1,
+		});
+	});
+
+	it("round-trip preserves combatant AC value", () => {
+		const result = createEncounter(
+			[{ id: combatantId("1"), name: "Aria", ac: 18 }],
+			0,
+			1,
+		);
+		if (isDomainError(result)) throw new Error("unreachable");
+		saveEncounter(result);
+		const loaded = loadEncounter();
+		expect(loaded?.combatants[0].ac).toBe(18);
+	});
+
+	it("round-trip preserves combatant without AC", () => {
+		const result = createEncounter(
+			[{ id: combatantId("1"), name: "Aria" }],
+			0,
+			1,
+		);
+		if (isDomainError(result)) throw new Error("unreachable");
+		saveEncounter(result);
+		const loaded = loadEncounter();
+		expect(loaded?.combatants[0].ac).toBeUndefined();
+	});
+
+	it("discards invalid AC values during rehydration", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({
+				combatants: [
+					{ id: "1", name: "Neg", ac: -1 },
+					{ id: "2", name: "Float", ac: 3.5 },
+					{ id: "3", name: "Str", ac: "high" },
+				],
+				activeIndex: 0,
+				roundNumber: 1,
+			}),
+		);
+		const loaded = loadEncounter();
+		expect(loaded).not.toBeNull();
+		expect(loaded?.combatants[0].ac).toBeUndefined();
+		expect(loaded?.combatants[1].ac).toBeUndefined();
+		expect(loaded?.combatants[2].ac).toBeUndefined();
+	});
+
+	it("preserves AC of 0 during rehydration", () => {
+		localStorage.setItem(
+			STORAGE_KEY,
+			JSON.stringify({
+				combatants: [{ id: "1", name: "Aria", ac: 0 }],
+				activeIndex: 0,
+				roundNumber: 1,
+			}),
+		);
+		const loaded = loadEncounter();
+		expect(loaded?.combatants[0].ac).toBe(0);
+	});
+
+	it("saving after modifications persists the latest state", () => {
+		const encounter = makeEncounter();
+		saveEncounter(encounter);
+
+		const modified = createEncounter(
+			[
+				{ id: combatantId("1"), name: "Aria", initiative: 18 },
+				{ id: combatantId("c-2"), name: "Brak", initiative: 12 },
+			],
+			0,
+			5,
+		);
+		if (isDomainError(modified)) throw new Error("unreachable");
+
+		saveEncounter(modified);
+		const loaded = loadEncounter();
+
+		expect(loaded?.combatants).toHaveLength(2);
+		expect(loaded?.roundNumber).toBe(5);
+	});
+});

apps/web/src/persistence/__tests__/player-character-storage.test.ts

@@ -0,0 +1,231 @@
+import type { PlayerCharacter } from "@initiative/domain";
+import { playerCharacterId } from "@initiative/domain";
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+	loadPlayerCharacters,
+	savePlayerCharacters,
+} from "../player-character-storage.js";
+
+const STORAGE_KEY = "initiative:player-characters";
+
+function createMockLocalStorage() {
+	const store = new Map<string, string>();
+	return {
+		getItem: (key: string) => store.get(key) ?? null,
+		setItem: (key: string, value: string) => store.set(key, value),
+		removeItem: (key: string) => store.delete(key),
+		clear: () => store.clear(),
+		get length() {
+			return store.size;
+		},
+		key: (_index: number) => null,
+		store,
+	};
+}
+
+function makePC(overrides?: Partial<PlayerCharacter>): PlayerCharacter {
+	return {
+		id: playerCharacterId("pc-1"),
+		name: "Aragorn",
+		ac: 16,
+		maxHp: 120,
+		color: "green",
+		icon: "sword",
+		...overrides,
+	};
+}
+
+describe("player-character-storage", () => {
+	let mockStorage: ReturnType<typeof createMockLocalStorage>;
+
+	beforeEach(() => {
+		mockStorage = createMockLocalStorage();
+		Object.defineProperty(globalThis, "localStorage", {
+			value: mockStorage,
+			writable: true,
+		});
+	});
+
+	describe("round-trip save/load", () => {
+		it("saves and loads a single character", () => {
+			const pc = makePC();
+			savePlayerCharacters([pc]);
+			const loaded = loadPlayerCharacters();
+			expect(loaded).toEqual([pc]);
+		});
+
+		it("saves and loads multiple characters", () => {
+			const pcs = [
+				makePC({ id: playerCharacterId("pc-1"), name: "Aragorn" }),
+				makePC({
+					id: playerCharacterId("pc-2"),
+					name: "Legolas",
+					ac: 14,
+					maxHp: 90,
+					color: "blue",
+					icon: "eye",
+				}),
+			];
+			savePlayerCharacters(pcs);
+			const loaded = loadPlayerCharacters();
+			expect(loaded).toEqual(pcs);
+		});
+	});
+
+	describe("empty storage", () => {
+		it("returns empty array when no data exists", () => {
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+	});
+
+	describe("corrupt JSON", () => {
+		it("returns empty array for invalid JSON", () => {
+			mockStorage.setItem(STORAGE_KEY, "not-json{{{");
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+
+		it("returns empty array for non-array JSON", () => {
+			mockStorage.setItem(STORAGE_KEY, '{"foo": "bar"}');
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+	});
+
+	describe("per-character validation", () => {
+		it("discards character with missing name", () => {
+			mockStorage.setItem(
+				STORAGE_KEY,
+				JSON.stringify([
+					{ id: "pc-1", ac: 10, maxHp: 50, color: "blue", icon: "sword" },
+				]),
+			);
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+
+		it("discards character with empty name", () => {
+			mockStorage.setItem(
+				STORAGE_KEY,
+				JSON.stringify([
+					{
+						id: "pc-1",
+						name: "",
+						ac: 10,
+						maxHp: 50,
+						color: "blue",
+						icon: "sword",
+					},
+				]),
+			);
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+
+		it("discards character with invalid color", () => {
+			mockStorage.setItem(
+				STORAGE_KEY,
+				JSON.stringify([
+					{
+						id: "pc-1",
+						name: "Test",
+						ac: 10,
+						maxHp: 50,
+						color: "neon",
+						icon: "sword",
+					},
+				]),
+			);
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+
+		it("discards character with invalid icon", () => {
+			mockStorage.setItem(
+				STORAGE_KEY,
+				JSON.stringify([
+					{
+						id: "pc-1",
+						name: "Test",
+						ac: 10,
+						maxHp: 50,
+						color: "blue",
+						icon: "banana",
+					},
+				]),
+			);
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+
+		it("discards character with negative AC", () => {
+			mockStorage.setItem(
+				STORAGE_KEY,
+				JSON.stringify([
+					{
+						id: "pc-1",
+						name: "Test",
+						ac: -1,
+						maxHp: 50,
+						color: "blue",
+						icon: "sword",
+					},
+				]),
+			);
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+
+		it("discards character with maxHp of 0", () => {
+			mockStorage.setItem(
+				STORAGE_KEY,
+				JSON.stringify([
+					{
+						id: "pc-1",
+						name: "Test",
+						ac: 10,
+						maxHp: 0,
+						color: "blue",
+						icon: "sword",
+					},
+				]),
+			);
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+
+		it("keeps valid characters and discards invalid ones", () => {
+			mockStorage.setItem(
+				STORAGE_KEY,
+				JSON.stringify([
+					{
+						id: "pc-1",
+						name: "Valid",
+						ac: 10,
+						maxHp: 50,
+						color: "blue",
+						icon: "sword",
+					},
+					{
+						id: "pc-2",
+						name: "",
+						ac: 10,
+						maxHp: 50,
+						color: "blue",
+						icon: "sword",
+					},
+				]),
+			);
+			const loaded = loadPlayerCharacters();
+			expect(loaded).toHaveLength(1);
+			expect(loaded[0].name).toBe("Valid");
+		});
+	});
+
+	describe("storage errors", () => {
+		it("save silently catches errors", () => {
+			Object.defineProperty(globalThis, "localStorage", {
+				value: {
+					setItem: () => {
+						throw new Error("QuotaExceeded");
+					},
+					getItem: () => null,
+				},
+				writable: true,
+			});
+			expect(() => savePlayerCharacters([makePC()])).not.toThrow();
+		});
+	});
+});

apps/web/src/persistence/encounter-storage.ts

@@ -0,0 +1,153 @@
+import {
+	type ConditionId,
+	combatantId,
+	createEncounter,
+	creatureId,
+	type Encounter,
+	isDomainError,
+	playerCharacterId,
+	VALID_CONDITION_IDS,
+	VALID_PLAYER_COLORS,
+	VALID_PLAYER_ICONS,
+} from "@initiative/domain";
+
+const STORAGE_KEY = "initiative:encounter";
+
+export function saveEncounter(encounter: Encounter): void {
+	try {
+		localStorage.setItem(STORAGE_KEY, JSON.stringify(encounter));
+	} catch {
+		// Silently swallow errors (quota exceeded, storage unavailable)
+	}
+}
+
+function validateAc(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0
+		? value
+		: undefined;
+}
+
+function validateConditions(value: unknown): ConditionId[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	const valid = value.filter(
+		(v): v is ConditionId =>
+			typeof v === "string" && VALID_CONDITION_IDS.has(v),
+	);
+	return valid.length > 0 ? valid : undefined;
+}
+
+function validateCreatureId(value: unknown) {
+	return typeof value === "string" && value.length > 0
+		? creatureId(value)
+		: undefined;
+}
+
+function validateHp(
+	rawMaxHp: unknown,
+	rawCurrentHp: unknown,
+): { maxHp: number; currentHp: number } | undefined {
+	if (
+		typeof rawMaxHp !== "number" ||
+		!Number.isInteger(rawMaxHp) ||
+		rawMaxHp < 1
+	) {
+		return undefined;
+	}
+	const validCurrentHp =
+		typeof rawCurrentHp === "number" &&
+		Number.isInteger(rawCurrentHp) &&
+		rawCurrentHp >= 0 &&
+		rawCurrentHp <= rawMaxHp;
+	return {
+		maxHp: rawMaxHp,
+		currentHp: validCurrentHp ? rawCurrentHp : rawMaxHp,
+	};
+}
+
+function rehydrateCombatant(c: unknown) {
+	const entry = c as Record<string, unknown>;
+	const base = {
+		id: combatantId(entry.id as string),
+		name: entry.name as string,
+		initiative:
+			typeof entry.initiative === "number" ? entry.initiative : undefined,
+	};
+
+	const color =
+		typeof entry.color === "string" && VALID_PLAYER_COLORS.has(entry.color)
+			? entry.color
+			: undefined;
+	const icon =
+		typeof entry.icon === "string" && VALID_PLAYER_ICONS.has(entry.icon)
+			? entry.icon
+			: undefined;
+	const pcId =
+		typeof entry.playerCharacterId === "string" &&
+		entry.playerCharacterId.length > 0
+			? playerCharacterId(entry.playerCharacterId)
+			: undefined;
+
+	const shared = {
+		...base,
+		ac: validateAc(entry.ac),
+		conditions: validateConditions(entry.conditions),
+		isConcentrating: entry.isConcentrating === true ? true : undefined,
+		creatureId: validateCreatureId(entry.creatureId),
+		color,
+		icon,
+		playerCharacterId: pcId,
+	};
+
+	const hp = validateHp(entry.maxHp, entry.currentHp);
+	return hp ? { ...shared, ...hp } : shared;
+}
+
+function isValidCombatantEntry(c: unknown): boolean {
+	if (typeof c !== "object" || c === null || Array.isArray(c)) return false;
+	const entry = c as Record<string, unknown>;
+	return typeof entry.id === "string" && typeof entry.name === "string";
+}
+
+export function loadEncounter(): Encounter | null {
+	try {
+		const raw = localStorage.getItem(STORAGE_KEY);
+		if (raw === null) return null;
+
+		const parsed: unknown = JSON.parse(raw);
+
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+			return null;
+
+		const obj = parsed as Record<string, unknown>;
+
+		if (!Array.isArray(obj.combatants)) return null;
+		if (typeof obj.activeIndex !== "number") return null;
+		if (typeof obj.roundNumber !== "number") return null;
+
+		const combatants = obj.combatants as unknown[];
+
+		// Handle empty encounter (cleared state) directly — createEncounter rejects empty arrays
+		if (combatants.length === 0) {
+			return {
+				combatants: [],
+				activeIndex: 0,
+				roundNumber: 1,
+			};
+		}
+
+		if (!combatants.every(isValidCombatantEntry)) return null;
+
+		const rehydrated = combatants.map(rehydrateCombatant);
+
+		const result = createEncounter(
+			rehydrated,
+			obj.activeIndex,
+			obj.roundNumber,
+		);
+		if (isDomainError(result)) return null;
+
+		return result;
+	} catch {
+		return null;
+	}
+}

apps/web/src/persistence/player-character-storage.ts

@@ -0,0 +1,72 @@
+import type { PlayerCharacter } from "@initiative/domain";
+import {
+	playerCharacterId,
+	VALID_PLAYER_COLORS,
+	VALID_PLAYER_ICONS,
+} from "@initiative/domain";
+
+const STORAGE_KEY = "initiative:player-characters";
+
+export function savePlayerCharacters(characters: PlayerCharacter[]): void {
+	try {
+		localStorage.setItem(STORAGE_KEY, JSON.stringify(characters));
+	} catch {
+		// Silently swallow errors (quota exceeded, storage unavailable)
+	}
+}
+
+function rehydrateCharacter(raw: unknown): PlayerCharacter | null {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+		return null;
+	const entry = raw as Record<string, unknown>;
+
+	if (typeof entry.id !== "string" || entry.id.length === 0) return null;
+	if (typeof entry.name !== "string" || entry.name.trim().length === 0)
+		return null;
+	if (
+		typeof entry.ac !== "number" ||
+		!Number.isInteger(entry.ac) ||
+		entry.ac < 0
+	)
+		return null;
+	if (
+		typeof entry.maxHp !== "number" ||
+		!Number.isInteger(entry.maxHp) ||
+		entry.maxHp < 1
+	)
+		return null;
+	if (typeof entry.color !== "string" || !VALID_PLAYER_COLORS.has(entry.color))
+		return null;
+	if (typeof entry.icon !== "string" || !VALID_PLAYER_ICONS.has(entry.icon))
+		return null;
+
+	return {
+		id: playerCharacterId(entry.id),
+		name: entry.name,
+		ac: entry.ac,
+		maxHp: entry.maxHp,
+		color: entry.color as PlayerCharacter["color"],
+		icon: entry.icon as PlayerCharacter["icon"],
+	};
+}
+
+export function loadPlayerCharacters(): PlayerCharacter[] {
+	try {
+		const raw = localStorage.getItem(STORAGE_KEY);
+		if (raw === null) return [];
+
+		const parsed: unknown = JSON.parse(raw);
+		if (!Array.isArray(parsed)) return [];
+
+		const characters: PlayerCharacter[] = [];
+		for (const item of parsed) {
+			const pc = rehydrateCharacter(item);
+			if (pc !== null) {
+				characters.push(pc);
+			}
+		}
+		return characters;
+	} catch {
+		return [];
+	}
+}

apps/web/vite.config.ts

@@ -1,6 +1,7 @@
+import tailwindcss from "@tailwindcss/vite";
 import react from "@vitejs/plugin-react";
 import { defineConfig } from "vite";
 
 export default defineConfig({
-	plugins: [react()],
+	plugins: [tailwindcss(), react()],
 });

biome.json

@@ -6,7 +6,9 @@
 			"!**/dist/**",
 			"!.claude/**",
 			"!.specify/**",
-			"!specs/**"
+			"!specs/**",
+			"!coverage/**",
+			"!.pnpm-store/**"
 		]
 	},
 	"assist": {
@@ -27,7 +29,15 @@
 	"linter": {
 		"enabled": true,
 		"rules": {
-			"recommended": true
+			"recommended": true,
+			"complexity": {
+				"noExcessiveCognitiveComplexity": {
+					"level": "error",
+					"options": {
+						"maxAllowedComplexity": 15
+					}
+				}
+			}
 		}
 	}
 }

d20.svg

@@ -0,0 +1,19 @@
+<svg 
+  xmlns="http://www.w3.org/2000/svg" 
+  height="24"
+  width="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="1"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <polygon points="20.22 16.76 20.22 7.26 12.04 2.51 3.85 7.26 3.85 16.76 12.04 21.51 20.22 16.76"/>
+  <line x1="7.29" y1="9.26" x2="3.85" y2="7.26"/>
+  <line x1="20.22" y1="7.26" x2="16.79" y2="9.26"/>
+  <line x1="12.04" y1="17.44" x2="12.04" y2="21.51"/>
+  <polygon points="12.04 17.44 20.22 16.76 16.79 9.26 12.04 17.44"/>
+  <polygon points="12.04 17.44 7.29 9.26 3.85 16.76 12.04 17.44"/>
+  <polygon points="12.04 2.51 7.29 9.26 16.79 9.26 12.04 2.51"/>
+</svg>

docs/agents/.gitkeep

@@ -0,0 +1,4 @@
+# Agent Artifacts
+
+Research reports and implementation plans generated by RPI skills.
+

docs/agents/plans/2026-03-13-declutter-action-bars.md

@@ -0,0 +1,536 @@
+---
+date: "2026-03-13T14:58:42.882813+00:00"
+git_commit: 75778884bd1be7d135b2f5ea9b8a8e77a0149f7b
+branch: main
+topic: "Declutter Action Bars"
+tags: [plan, turn-navigation, action-bar, overflow-menu, ux]
+status: draft
+---
+
+# Declutter Action Bars — Implementation Plan
+
+## Overview
+
+Reorganize buttons across the top bar (TurnNavigation) and bottom bar (ActionBar) to reduce visual clutter and improve UX. Each bar gets a clear purpose: the top bar is for turn navigation + encounter lifecycle, the bottom bar is for adding combatants + setup actions.
+
+## Current State Analysis
+
+**Top bar** (`turn-navigation.tsx`) has 5 buttons + center info:
+```
+[ Prev ] | [ R1  Dwarf ] | [ D20  Library  Trash ] [ Next ]
+```
+The D20 (roll all initiative) and Library (manage sources) buttons are unrelated to turn navigation — they're setup/utility actions that add noise.
+
+**Bottom bar** (`action-bar.tsx`) has an input, Add button, and 3 icon buttons:
+```
+[ + Add combatants... ] [ Add ] [ Users  Eye  Import ]
+```
+The icon cluster (Users, Eye, Import) is cryptic — three ghost icon buttons with no labels, requiring hover to discover purpose. The Eye button opens a separate search dropdown for browsing stat blocks, which duplicates the existing search input.
+
+### Key Discoveries:
+- `rollAllInitiativeUseCase` (`packages/application/src/roll-all-initiative-use-case.ts`) applies to combatants with `creatureId` AND no `initiative` set — this defines the conditional visibility logic
+- `Combatant.initiative` is `number | undefined` and `Combatant.creatureId` is `CreatureId | undefined` (`packages/domain/src/types.ts`)
+- No existing dropdown/menu UI component — the overflow menu needs a new component
+- Lucide provides `EllipsisVertical` for the kebab menu trigger
+- The stat block viewer already has its own search input, results list, and keyboard navigation (`action-bar.tsx:65-236`) — in browse mode, we reuse the main input for this instead
+
+## Desired End State
+
+### UI Mockups
+
+**Top bar (after):**
+```
+[ Prev ]  [ R1  Dwarf ]  [ Trash ]  [ Next ]
+```
+4 elements. Clean, focused on turn flow + encounter lifecycle.
+
+**Bottom bar — add mode (default):**
+```
+[ + Add combatants...  👁 ]  [ Add ]  [ D20? ]  [ ⋮ ]
+```
+The Eye icon sits inside/beside the input as a toggle. D20 appears conditionally. Kebab menu holds infrequent actions.
+
+**Bottom bar — browse mode (Eye toggled on):**
+```
+[ 🔍 Search stat blocks...  👁 ]              [ ⋮ ]
+```
+The input switches purpose: placeholder changes, typing searches stat blocks instead of adding combatants. The Add button and D20 hide (irrelevant in browse mode). Eye icon stays as the toggle to switch back. Selecting a result opens the stat block panel and exits browse mode.
+
+**Overflow menu (⋮ clicked):**
+```
+┌──────────────────────┐
+│ 👥 Player Characters │
+│ 📚 Manage Sources    │
+│ 📥 Bulk Import       │
+└──────────────────────┘
+```
+Labeled items with icons — discoverable without hover.
+
+### Key Discoveries:
+- `sourceManagerOpen` state lives in App.tsx:116 — the overflow menu's "Manage Sources" item needs the same toggle callback
+- The stat block viewer state (viewerOpen, viewerQuery, viewerResults, viewerIndex) in action-bar.tsx:66-71 gets replaced by a `browseMode` boolean that repurposes the main input
+- The viewer's separate input, dropdown, and keyboard handling (action-bar.tsx:188-248) can be removed — browse mode reuses the existing input and suggestion dropdown infrastructure
+
+## What We're NOT Doing
+
+- Changing domain logic or use cases
+- Modifying ConfirmButton behavior
+- Changing the stat block panel itself
+- Altering animation logic (useActionBarAnimation)
+- Modifying combatant row buttons
+- Changing how SourceManager works (just moving where the trigger lives)
+
+## Implementation Approach
+
+Four phases, each independently testable. Phase 1 simplifies the top bar (pure removal). Phase 2 adds the overflow menu component. Phase 3 reworks the ActionBar (browse toggle + conditional D20 + overflow integration). Phase 4 wires everything together in App.tsx.
+
+---
+
+## Phase 1: Simplify TurnNavigation
+
+### Overview
+Strip TurnNavigation down to just turn controls + clear encounter. Remove Roll All Initiative and Manage Sources buttons and their associated props.
+
+### Changes Required:
+
+#### [x] 1. Update TurnNavigation component
+**File**: `apps/web/src/components/turn-navigation.tsx`
+**Changes**:
+- Remove `onRollAllInitiative` and `onOpenSourceManager` from props interface
+- Remove the D20 button (lines 53-62)
+- Remove the Library button (lines 63-72)
+- Remove the inner `gap-0` div wrapper (lines 52, 80) since only the ConfirmButton remains
+- Remove unused imports: `Library` from lucide-react, `D20Icon`
+- Adjust layout: ConfirmButton + Next button grouped with `gap-3`
+
+Result:
+```tsx
+interface TurnNavigationProps {
+	encounter: Encounter;
+	onAdvanceTurn: () => void;
+	onRetreatTurn: () => void;
+	onClearEncounter: () => void;
+}
+
+// Layout becomes:
+// [ Prev ] | [ R1  Name ] | [ Trash ] [ Next ]
+```
+
+#### [x] 2. Update TurnNavigation usage in App.tsx
+**File**: `apps/web/src/App.tsx`
+**Changes**:
+- Remove `onRollAllInitiative` and `onOpenSourceManager` props from the `<TurnNavigation>` call (lines 256-257)
+
+### Success Criteria:
+
+#### Automated Verification:
+- [x] `pnpm check` passes (typecheck catches removed props, lint catches unused imports)
+
+#### Manual Verification:
+- [ ] Top bar shows only: Prev, round badge + name, trash, Next
+- [ ] Prev/Next/Clear buttons still work as before
+- [ ] Top bar animation (slide in/out) unchanged
+
+**Implementation Note**: After completing this phase and all automated verification passes, pause here for manual confirmation from the human before proceeding to the next phase.
+
+---
+
+## Phase 2: Create Overflow Menu Component
+
+### Overview
+Build a reusable overflow menu (kebab menu) component with click-outside and Escape handling, following the same patterns as ConfirmButton and the existing viewer dropdown.
+
+### Changes Required:
+
+#### [x] 1. Create OverflowMenu component
+**File**: `apps/web/src/components/ui/overflow-menu.tsx` (new file)
+**Changes**: Create a dropdown menu triggered by an EllipsisVertical icon button. Features:
+- Toggle open/close on button click
+- Close on click outside (document mousedown listener, same pattern as confirm-button.tsx:44-67)
+- Close on Escape key
+- Renders above the trigger (bottom-full positioning, same as action-bar suggestion dropdown)
+- Each item: icon + label, full-width clickable row
+- Clicking an item calls its action and closes the menu
+
+```tsx
+import { EllipsisVertical } from "lucide-react";
+import { type ReactNode, useEffect, useRef, useState } from "react";
+import { Button } from "./button";
+
+export interface OverflowMenuItem {
+	readonly icon: ReactNode;
+	readonly label: string;
+	readonly onClick: () => void;
+	readonly disabled?: boolean;
+}
+
+interface OverflowMenuProps {
+	readonly items: readonly OverflowMenuItem[];
+}
+
+export function OverflowMenu({ items }: OverflowMenuProps) {
+	const [open, setOpen] = useState(false);
+	const ref = useRef<HTMLDivElement>(null);
+
+	useEffect(() => {
+		if (!open) return;
+		function handleMouseDown(e: MouseEvent) {
+			if (ref.current && !ref.current.contains(e.target as Node)) {
+				setOpen(false);
+			}
+		}
+		function handleKeyDown(e: KeyboardEvent) {
+			if (e.key === "Escape") setOpen(false);
+		}
+		document.addEventListener("mousedown", handleMouseDown);
+		document.addEventListener("keydown", handleKeyDown);
+		return () => {
+			document.removeEventListener("mousedown", handleMouseDown);
+			document.removeEventListener("keydown", handleKeyDown);
+		};
+	}, [open]);
+
+	return (
+		<div ref={ref} className="relative">
+			<Button
+				type="button"
+				variant="ghost"
+				size="icon"
+				className="text-muted-foreground hover:text-hover-neutral"
+				onClick={() => setOpen((o) => !o)}
+				aria-label="More actions"
+				title="More actions"
+			>
+				<EllipsisVertical className="h-5 w-5" />
+			</Button>
+			{open && (
+				<div className="absolute bottom-full right-0 z-50 mb-1 min-w-48 rounded-md border border-border bg-card py-1 shadow-lg">
+					{items.map((item) => (
+						<button
+							key={item.label}
+							type="button"
+							className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-sm text-foreground hover:bg-hover-neutral-bg disabled:pointer-events-none disabled:opacity-50"
+							disabled={item.disabled}
+							onClick={() => {
+								item.onClick();
+								setOpen(false);
+							}}
+						>
+							{item.icon}
+							{item.label}
+						</button>
+					))}
+				</div>
+			)}
+		</div>
+	);
+}
+```
+
+### Success Criteria:
+
+#### Automated Verification:
+- [x] `pnpm check` passes (new file compiles, no unused exports yet — will be used in phase 3)
+
+#### Manual Verification:
+- [ ] N/A — component not yet wired into the UI
+
+**Implementation Note**: After completing this phase and all automated verification passes, pause here for manual confirmation from the human before proceeding to the next phase.
+
+---
+
+## Phase 3: Rework ActionBar
+
+### Overview
+Replace the icon button cluster with: (1) an Eye toggle on the input that switches between add mode and browse mode, (2) a conditional Roll All Initiative button, and (3) the overflow menu for infrequent actions.
+
+### Changes Required:
+
+#### [x] 1. Update ActionBarProps
+**File**: `apps/web/src/components/action-bar.tsx`
+**Changes**: Add new props, keep existing ones needed for overflow menu items:
+```tsx
+interface ActionBarProps {
+	// ... existing props stay ...
+	onRollAllInitiative?: () => void;       // new — moved from top bar
+	showRollAllInitiative?: boolean;         // new — conditional visibility
+	onOpenSourceManager?: () => void;        // new — moved from top bar
+}
+```
+
+#### [x] 2. Add browse mode state
+**File**: `apps/web/src/components/action-bar.tsx`
+**Changes**: Replace the separate viewer state (viewerOpen, viewerQuery, viewerResults, viewerIndex, viewerRef, viewerInputRef — lines 66-71) with a single `browseMode` boolean:
+
+```tsx
+const [browseMode, setBrowseMode] = useState(false);
+```
+
+Remove all viewer-specific state variables and handlers:
+- `viewerOpen`, `viewerQuery`, `viewerResults`, `viewerIndex` (lines 66-69)
+- `viewerRef`, `viewerInputRef` (lines 70-71)
+- `openViewer`, `closeViewer` (lines 189-202)
+- `handleViewerQueryChange`, `handleViewerSelect`, `handleViewerKeyDown` (lines 204-236)
+- The viewer click-outside effect (lines 239-248)
+
+#### [x] 3. Rework the input area with Eye toggle
+**File**: `apps/web/src/components/action-bar.tsx`
+**Changes**: Add an Eye icon button inside the input wrapper that toggles browse mode. When browse mode is active:
+- Placeholder changes to "Search stat blocks..."
+- Typing calls `bestiarySearch` but selecting a result calls `onViewStatBlock` instead of queuing/adding
+- The suggestion dropdown shows results but clicking opens stat block panel instead of adding
+- Add button and custom fields (Init/AC/MaxHP) are hidden
+- D20 button is hidden
+
+When toggling browse mode off, clear the input and suggestions.
+
+The Eye icon sits to the right of the input inside the `relative flex-1` wrapper:
+```tsx
+<div className="relative flex-1">
+	<Input
+		ref={inputRef}
+		type="text"
+		value={nameInput}
+		onChange={(e) => handleNameChange(e.target.value)}
+		onKeyDown={browseMode ? handleBrowseKeyDown : handleKeyDown}
+		placeholder={browseMode ? "Search stat blocks..." : "+ Add combatants"}
+		className="max-w-xs pr-8"
+		autoFocus={autoFocus}
+	/>
+	{bestiaryLoaded && onViewStatBlock && (
+		<button
+			type="button"
+			className={cn(
+				"absolute right-2 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-hover-neutral",
+				browseMode && "text-accent",
+			)}
+			onClick={() => {
+				setBrowseMode((m) => !m);
+				setNameInput("");
+				setSuggestions([]);
+				setPcMatches([]);
+				setQueued(null);
+				setSuggestionIndex(-1);
+			}}
+			title={browseMode ? "Switch to add mode" : "Browse stat blocks"}
+			aria-label={browseMode ? "Switch to add mode" : "Browse stat blocks"}
+		>
+			<Eye className="h-4 w-4" />
+		</button>
+	)}
+	{/* suggestion dropdown — behavior changes based on browseMode */}
+</div>
+```
+
+Import `cn` from `../../lib/utils` (already used by other components).
+
+#### [x] 4. Update suggestion dropdown for browse mode
+**File**: `apps/web/src/components/action-bar.tsx`
+**Changes**: In browse mode, the suggestion dropdown behaves differently:
+- No "Add as custom" row at the top
+- No player character matches section
+- No queuing (plus/minus/confirm) — clicking a result calls `onViewStatBlock` and exits browse mode
+- Keyboard Enter on a highlighted result calls `onViewStatBlock` and exits browse mode
+
+Add a `handleBrowseKeyDown` handler:
+```tsx
+const handleBrowseKeyDown = (e: React.KeyboardEvent) => {
+	if (e.key === "Escape") {
+		setBrowseMode(false);
+		setNameInput("");
+		setSuggestions([]);
+		setSuggestionIndex(-1);
+		return;
+	}
+	if (suggestions.length === 0) return;
+	if (e.key === "ArrowDown") {
+		e.preventDefault();
+		setSuggestionIndex((i) => (i < suggestions.length - 1 ? i + 1 : 0));
+	} else if (e.key === "ArrowUp") {
+		e.preventDefault();
+		setSuggestionIndex((i) => (i > 0 ? i - 1 : suggestions.length - 1));
+	} else if (e.key === "Enter" && suggestionIndex >= 0) {
+		e.preventDefault();
+		onViewStatBlock?.(suggestions[suggestionIndex]);
+		setBrowseMode(false);
+		setNameInput("");
+		setSuggestions([]);
+		setSuggestionIndex(-1);
+	}
+};
+```
+
+In the suggestion dropdown JSX, conditionally render based on `browseMode`:
+- Browse mode: simple list of creature results, click → `onViewStatBlock` + exit browse mode
+- Add mode: existing behavior (custom row, PC matches, queuing)
+
+#### [x] 5. Replace icon button cluster with D20 + overflow menu
+**File**: `apps/web/src/components/action-bar.tsx`
+**Changes**: Replace the `div.flex.items-center.gap-0` block (lines 443-529) containing Users, Eye, and Import buttons with:
+
+```tsx
+{!browseMode && (
+	<>
+		<Button type="submit" size="sm">
+			Add
+		</Button>
+		{showRollAllInitiative && onRollAllInitiative && (
+			<Button
+				type="button"
+				size="icon"
+				variant="ghost"
+				className="text-muted-foreground hover:text-hover-action"
+				onClick={onRollAllInitiative}
+				title="Roll all initiative"
+				aria-label="Roll all initiative"
+			>
+				<D20Icon className="h-6 w-6" />
+			</Button>
+		)}
+	</>
+)}
+<OverflowMenu items={overflowItems} />
+```
+
+Build the `overflowItems` array from props:
+```tsx
+const overflowItems: OverflowMenuItem[] = [];
+if (onManagePlayers) {
+	overflowItems.push({
+		icon: <Users className="h-4 w-4" />,
+		label: "Player Characters",
+		onClick: onManagePlayers,
+	});
+}
+if (onOpenSourceManager) {
+	overflowItems.push({
+		icon: <Library className="h-4 w-4" />,
+		label: "Manage Sources",
+		onClick: onOpenSourceManager,
+	});
+}
+if (bestiaryLoaded && onBulkImport) {
+	overflowItems.push({
+		icon: <Import className="h-4 w-4" />,
+		label: "Bulk Import",
+		onClick: onBulkImport,
+		disabled: bulkImportDisabled,
+	});
+}
+```
+
+#### [x] 6. Clean up imports
+**File**: `apps/web/src/components/action-bar.tsx`
+**Changes**:
+- Add imports: `D20Icon`, `OverflowMenu` + `OverflowMenuItem`, `Library` from lucide-react, `cn` from utils
+- Remove imports that are no longer needed after removing the standalone viewer: check which of `Eye`, `Import`, `Users` are still used (Eye stays for the toggle, Users and Import stay for overflow item icons, Library is new)
+- The `Check`, `Minus`, `Plus` imports stay (used in queuing UI)
+
+### Success Criteria:
+
+#### Automated Verification:
+- [x] `pnpm check` passes
+
+#### Manual Verification:
+- [ ] Bottom bar shows: input with Eye toggle, Add button, (conditional D20), kebab menu
+- [ ] Eye toggle switches input between "add" and "browse" modes
+- [ ] In browse mode: typing shows bestiary results, clicking one opens stat block panel, exits browse mode
+- [ ] In browse mode: Add button and D20 are hidden, overflow menu stays visible
+- [ ] In add mode: existing behavior works (search, queue, custom fields, PC matches)
+- [ ] Overflow menu opens/closes on click, closes on Escape and click-outside
+- [ ] Overflow menu items (Player Characters, Manage Sources, Bulk Import) trigger correct actions
+- [ ] D20 button appears only when bestiary combatants lack initiative, disappears when all have values
+
+**Implementation Note**: After completing this phase and all automated verification passes, pause here for manual confirmation from the human before proceeding to the next phase.
+
+---
+
+## Phase 4: Wire Up App.tsx
+
+### Overview
+Pass the new props to ActionBar — roll all initiative handler, conditional visibility flag, and source manager toggle. Remove the now-unused `onOpenSourceManager` callback from the TurnNavigation call (already removed in Phase 1) and ensure sourceManagerOpen toggle is routed through the overflow menu.
+
+### Changes Required:
+
+#### [x] 1. Compute showRollAllInitiative flag
+**File**: `apps/web/src/App.tsx`
+**Changes**: Add a derived boolean that checks if any combatant with a `creatureId` lacks an `initiative` value:
+
+```tsx
+const showRollAllInitiative = encounter.combatants.some(
+	(c) => c.creatureId != null && c.initiative == null,
+);
+```
+
+Place this near `const isEmpty = ...` (line 241).
+
+#### [x] 2. Pass new props to both ActionBar instances
+**File**: `apps/web/src/App.tsx`
+**Changes**: Add to both `<ActionBar>` calls (empty state at ~line 269 and populated state at ~line 328):
+
+```tsx
+<ActionBar
+	// ... existing props ...
+	onRollAllInitiative={handleRollAllInitiative}
+	showRollAllInitiative={showRollAllInitiative}
+	onOpenSourceManager={() => setSourceManagerOpen((o) => !o)}
+/>
+```
+
+#### [x] 3. Remove stale code
+**File**: `apps/web/src/App.tsx`
+**Changes**:
+- The `onRollAllInitiative` and `onOpenSourceManager` props were already removed from `<TurnNavigation>` in Phase 1 — verify no references remain
+- Verify `sourceManagerOpen` state and the `<SourceManager>` rendering block (lines 287-291) still work correctly — the SourceManager inline panel is still toggled by the same state, just from a different trigger location
+
+### Success Criteria:
+
+#### Automated Verification:
+- [x] `pnpm check` passes
+
+#### Manual Verification:
+- [ ] Top bar: only Prev, round badge + name, trash, Next — no D20 or Library buttons
+- [ ] Bottom bar: input with Eye toggle, Add, conditional D20, overflow menu
+- [ ] Roll All Initiative (D20 in bottom bar): visible when bestiary creatures lack initiative, hidden after rolling
+- [ ] Overflow → Player Characters: opens player management modal
+- [ ] Overflow → Manage Sources: toggles source manager panel (same as before, just different trigger)
+- [ ] Overflow → Bulk Import: opens bulk import mode
+- [ ] Browse mode (Eye toggle): search stat blocks without adding, selecting opens panel
+- [ ] Clear encounter (top bar trash): still works with two-click confirmation
+- [ ] All animations (bar transitions) unchanged
+- [ ] Empty state: ActionBar centered with all functionality accessible
+
+**Implementation Note**: After completing this phase and all automated verification passes, pause here for manual confirmation from the human before proceeding to the next phase.
+
+---
+
+## Testing Strategy
+
+### Unit Tests:
+- No domain/application changes — existing tests should pass unchanged
+- `pnpm check` covers typecheck + lint + existing test suite
+
+### Manual Testing Steps:
+1. Start with empty encounter — verify ActionBar is centered with Eye toggle and overflow menu
+2. Add a bestiary creature — verify D20 appears in bottom bar, top bar slides in with just 4 elements
+3. Click D20 → initiative rolls → D20 disappears from bottom bar
+4. Toggle Eye → input switches to browse mode → search and select → stat block opens → exits browse mode
+5. Open overflow menu → click each item → verify correct modal/panel opens
+6. Click trash in top bar → confirm → encounter clears, back to empty state
+7. Add custom creature (no creatureId) → D20 should not appear (no bestiary creatures)
+8. Add mix of custom + bestiary creatures → D20 visible → roll all → D20 hidden
+
+## Performance Considerations
+
+None — this is a pure UI reorganization with no new data fetching, state management changes, or rendering overhead. The `showRollAllInitiative` computation is a simple `.some()` over the combatant array, which is negligible.
+
+## References
+
+- Research: `docs/agents/research/2026-03-13-action-bars-and-buttons.md`
+- Top bar: `apps/web/src/components/turn-navigation.tsx`
+- Bottom bar: `apps/web/src/components/action-bar.tsx`
+- App layout: `apps/web/src/App.tsx`
+- Button: `apps/web/src/components/ui/button.tsx`
+- ConfirmButton: `apps/web/src/components/ui/confirm-button.tsx`
+- Roll all use case: `packages/application/src/roll-all-initiative-use-case.ts`
+- Combatant type: `packages/domain/src/types.ts`

docs/agents/research/2026-03-13-action-bars-and-buttons.md

@@ -0,0 +1,176 @@
+---
+date: "2026-03-13T14:39:15.661886+00:00"
+git_commit: 75778884bd1be7d135b2f5ea9b8a8e77a0149f7b
+branch: main
+topic: "Action Bars Setup — Top Bar and Bottom Bar Buttons"
+tags: [research, codebase, action-bar, turn-navigation, layout, buttons]
+status: complete
+---
+
+# Research: Action Bars Setup — Top Bar and Bottom Bar Buttons
+
+## Research Question
+
+How are the top and bottom action bars set up, what buttons do they contain, and how are their actions wired?
+
+## Summary
+
+The application has two primary bar components that frame the encounter tracker UI:
+
+1. **Top bar** — `TurnNavigation` (`turn-navigation.tsx`) — turn controls, round/combatant display, and encounter-wide actions.
+2. **Bottom bar** — `ActionBar` (`action-bar.tsx`) — combatant input, bestiary search, stat block browsing, bulk import, and player character management.
+
+Both bars share the same visual container styling (`flex items-center gap-3 rounded-md border border-border bg-card px-4 py-3`). They are laid out in `App.tsx` within a flex column, with a scrollable combatant list between them. When the encounter is empty, only the ActionBar is shown (centered in the viewport); the TurnNavigation appears with an animation when the first combatant is added.
+
+## Detailed Findings
+
+### Layout Structure (`App.tsx:243-344`)
+
+The bars live inside a `max-w-2xl` centered column:
+
+```
+┌──────────────────────────────────┐
+│  TurnNavigation (pt-8, shrink-0) │  ← top bar, conditionally shown
+├──────────────────────────────────┤
+│  SourceManager (optional inline) │  ← toggled by Library button in top bar
+├──────────────────────────────────┤
+│  Combatant list (flex-1,         │  ← scrollable
+│    overflow-y-auto)              │
+├──────────────────────────────────┤
+│  ActionBar (pb-8, shrink-0)      │  ← bottom bar
+└──────────────────────────────────┘
+```
+
+**Empty state**: When `encounter.combatants.length === 0`, the top bar is hidden and the ActionBar is vertically centered in a `flex items-center justify-center` wrapper with `pb-[15%]` offset. It receives `autoFocus` in this state.
+
+**Animation** (`useActionBarAnimation`, `App.tsx:30-66`): Manages transitions between empty and populated states:
+- Empty → populated: ActionBar plays `animate-settle-to-bottom`, TurnNavigation plays `animate-slide-down-in`.
+- Populated → empty: ActionBar plays `animate-rise-to-center`, TurnNavigation plays `animate-slide-up-out` (with `absolute` positioning during exit).
+
+The `showTopBar` flag is `true` when either combatants exist or the top bar exit animation is still running.
+
+### Top Bar — TurnNavigation (`turn-navigation.tsx`)
+
+**Props interface** (`turn-navigation.tsx:7-14`):
+- `encounter: Encounter` — full encounter state
+- `onAdvanceTurn`, `onRetreatTurn` — turn navigation callbacks
+- `onClearEncounter` — destructive clear with confirmation
+- `onRollAllInitiative` — rolls initiative for all combatants
+- `onOpenSourceManager` — toggles source manager panel
+
+**Layout**: Left–Center–Right structure:
+
+```
+[ ◀ Prev ] | [ R1  Active Combatant Name ] | [ 🎲  📚  🗑 ] [ Next ▶ ]
+```
+
+**Buttons (left to right)**:
+
+| # | Icon | Component | Variant | Action | Disabled when |
+|---|------|-----------|---------|--------|---------------|
+| 1 | `StepBack` | `Button` | default | `onRetreatTurn` | No combatants OR at round 1 index 0 |
+| 2 | `D20Icon` | `Button` | ghost | `onRollAllInitiative` | Never |
+| 3 | `Library` | `Button` | ghost | `onOpenSourceManager` | Never |
+| 4 | `Trash2` | `ConfirmButton` | — | `onClearEncounter` | No combatants |
+| 5 | `StepForward` | `Button` | default | `onAdvanceTurn` | No combatants |
+
+**Center section** (`turn-navigation.tsx:40-49`): Displays a round badge (`R{n}` in a `rounded-full bg-muted` span) and the active combatant's name (truncated). Falls back to "No combatants" in muted text.
+
+**Button grouping**: Buttons 2-4 are grouped in a `gap-0` div (tight spacing), while button 5 (Next) is separated by the outer `gap-3`.
+
+**Wiring in App.tsx** (`App.tsx:251-258`):
+- `onAdvanceTurn` → `advanceTurn` from `useEncounter()`
+- `onRetreatTurn` → `retreatTurn` from `useEncounter()`
+- `onClearEncounter` → `clearEncounter` from `useEncounter()`
+- `onRollAllInitiative` → `handleRollAllInitiative` → calls `rollAllInitiativeUseCase(makeStore(), rollDice, getCreature)`
+- `onOpenSourceManager` → toggles `sourceManagerOpen` state
+
+### Bottom Bar — ActionBar (`action-bar.tsx`)
+
+**Props interface** (`action-bar.tsx:20-36`):
+- `onAddCombatant` — adds custom combatant with optional init/AC/maxHP
+- `onAddFromBestiary` — adds creature from search result
+- `bestiarySearch` — search function returning `SearchResult[]`
+- `bestiaryLoaded` — whether bestiary index is loaded
+- `onViewStatBlock` — opens stat block panel for a creature
+- `onBulkImport` — triggers bulk source import mode
+- `bulkImportDisabled` — disables import button during loading
+- `inputRef` — external ref to the name input
+- `playerCharacters` — list of player characters for quick-add
+- `onAddFromPlayerCharacter` — adds a player character to encounter
+- `onManagePlayers` — opens player management modal
+- `autoFocus` — auto-focuses input (used in empty state)
+
+**Layout**: Form with input, contextual fields, submit button, and action icons:
+
+```
+[ + Add combatants... ] [ Init ] [ AC ] [ MaxHP ] [ Add ] [ 👥  👁  📥 ]
+```
+
+The Init/AC/MaxHP fields only appear when the input has 2+ characters and no bestiary suggestions are showing.
+
+**Buttons (left to right)**:
+
+| # | Icon | Component | Variant | Action | Condition |
+|---|------|-----------|---------|--------|-----------|
+| 1 | — | `Button` | sm | Form submit → `handleAdd` | Always shown |
+| 2 | `Users` | `Button` | ghost | `onManagePlayers` | Only if `onManagePlayers` provided |
+| 3 | `Eye` | `Button` | ghost | Toggle stat block viewer dropdown | Only if `bestiaryLoaded && onViewStatBlock` |
+| 4 | `Import` | `Button` | ghost | `onBulkImport` | Only if `bestiaryLoaded && onBulkImport` |
+
+**Button grouping**: Buttons 2-4 are grouped in a `gap-0` div, mirroring the top bar's icon button grouping.
+
+**Suggestion dropdown** (`action-bar.tsx:267-410`): Opens above the input when 2+ chars are typed and results exist. Contains:
+- A "Add as custom" escape row at the top (with `Esc` keyboard hint)
+- **Players section**: Lists matching player characters with colored icons; clicking adds them directly via `onAddFromPlayerCharacter`
+- **Bestiary section**: Lists search results; clicking queues a creature. Queued creatures show:
+  - `Minus` button — decrements count (removes queue at 0)
+  - Count badge — current queued count
+  - `Plus` button — increments count
+  - `Check` button — confirms and adds all queued copies
+
+**Stat block viewer dropdown** (`action-bar.tsx:470-513`): A separate search dropdown anchored to the Eye button. Has its own input, search results, and keyboard navigation. Selecting a result calls `onViewStatBlock`.
+
+**Keyboard handling** (`action-bar.tsx:168-186`):
+- Arrow Up/Down — navigate suggestion list
+- Enter — queue selected suggestion or confirm queued batch
+- Escape — clear suggestions and queue
+
+**Wiring in App.tsx** (`App.tsx:269-282` and `328-340`):
+- `onAddCombatant` → `addCombatant` from `useEncounter()`
+- `onAddFromBestiary` → `handleAddFromBestiary` → `addFromBestiary` from `useEncounter()`
+- `bestiarySearch` → `search` from `useBestiary()`
+- `onViewStatBlock` → `handleViewStatBlock` → constructs `CreatureId` and sets `selectedCreatureId`
+- `onBulkImport` → `handleBulkImport` → sets `bulkImportMode` and clears selection
+- `onAddFromPlayerCharacter` → `addFromPlayerCharacter` from `useEncounter()`
+- `onManagePlayers` → opens `managementOpen` state (shows `PlayerManagement` modal)
+
+### Shared UI Primitives
+
+**`Button`** (`ui/button.tsx`): CVA-based component with variants (`default`, `outline`, `ghost`) and sizes (`default`, `sm`, `icon`). Both bars use `size="icon"` with `variant="ghost"` for their icon button clusters, and `size="icon"` with default variant for the primary navigation buttons (Prev/Next in top bar).
+
+**`ConfirmButton`** (`ui/confirm-button.tsx`): Two-click destructive action button. First click shows a red pulsing confirmation state with a Check icon; second click fires `onConfirm`. Auto-reverts after 5 seconds. Supports Escape and click-outside cancellation. Used for Clear Encounter in the top bar.
+
+### Hover Color Convention
+
+Both bars use consistent hover color classes on their ghost icon buttons:
+- `hover:text-hover-action` — used on the D20 (roll initiative) button, suggesting an action/accent color
+- `hover:text-hover-neutral` — used on Library, Users, Eye, Import buttons, suggesting a neutral/informational color
+
+## Code References
+
+- `apps/web/src/components/turn-navigation.tsx` — Top bar component (93 lines)
+- `apps/web/src/components/action-bar.tsx` — Bottom bar component (533 lines)
+- `apps/web/src/App.tsx:30-66` — `useActionBarAnimation` hook for bar transitions
+- `apps/web/src/App.tsx:243-344` — Layout structure with both bars
+- `apps/web/src/components/ui/button.tsx` — Shared Button component
+- `apps/web/src/components/ui/confirm-button.tsx` — Two-step confirmation button
+- `apps/web/src/components/d20-icon.tsx` — Custom D20 dice SVG icon
+
+## Architecture Documentation
+
+The bars follow the app's adapter-layer convention: they are pure presentational React components that receive all behavior via callback props. No business logic lives in either bar — they delegate to handlers defined in `App.tsx`, which in turn call use-case functions from the application layer or manipulate local UI state.
+
+Both bars are rendered twice in `App.tsx` (once in the empty-state branch, once in the populated branch) rather than being conditionally repositioned, which simplifies the animation logic.
+
+The `ActionBar` is the more complex of the two, managing multiple pieces of local state (input value, suggestions, queued creatures, custom fields, stat block viewer) while `TurnNavigation` is fully stateless — all its data comes from the `encounter` prop.

docs/agents/research/2026-03-13-css-classes-buttons-hover.md

@@ -0,0 +1,188 @@
+---
+date: "2026-03-13T15:35:07.699570+00:00"
+git_commit: bd398080008349b47726d0016f4b03587f453833
+branch: main
+topic: "CSS class usage, button categorization, and hover effects across all components"
+tags: [research, codebase, css, tailwind, buttons, hover, ui]
+status: complete
+---
+
+# Research: CSS Class Usage, Button Categorization, and Hover Effects
+
+## Research Question
+How are CSS classes used across all components? How are buttons categorized — are there primary and secondary buttons? What hover effects exist, and are they unified?
+
+## Summary
+
+The project uses **Tailwind CSS v4** with a custom dark theme defined in `index.css` via `@theme`. All class merging goes through a `cn()` utility (clsx + tailwind-merge). Buttons are built on a shared `Button` component using **class-variance-authority (CVA)** with three variants: **default** (primary), **outline**, and **ghost**. Hover effects are partially unified through semantic color tokens (`hover-neutral`, `hover-action`, `hover-destructive`) defined in the theme, but several components use **one-off hardcoded hover colors** that bypass the token system.
+
+## Detailed Findings
+
+### Theme System (`index.css`)
+
+All colors are defined as CSS custom properties via Tailwind v4's `@theme` directive (`index.css:3-26`):
+
+| Token | Value | Purpose |
+|---|---|---|
+| `--color-background` | `#0f172a` | Page background |
+| `--color-foreground` | `#e2e8f0` | Default text |
+| `--color-muted` | `#64748b` | Subdued elements |
+| `--color-muted-foreground` | `#94a3b8` | Secondary text |
+| `--color-card` | `#1e293b` | Card/panel surfaces |
+| `--color-border` | `#334155` | Borders |
+| `--color-primary` | `#3b82f6` | Primary actions (blue) |
+| `--color-accent` | `#3b82f6` | Accent (same as primary) |
+| `--color-destructive` | `#ef4444` | Destructive actions (red) |
+
+**Hover tokens** (semantic layer for hover states):
+
+| Token | Resolves to | Usage |
+|---|---|---|
+| `hover-neutral` | `primary` (blue) | Text color on neutral hover |
+| `hover-action` | `primary` (blue) | Text color on action hover |
+| `hover-destructive` | `destructive` (red) | Text color on destructive hover |
+| `hover-neutral-bg` | `card` (slate) | Background on neutral hover |
+| `hover-action-bg` | `muted` | Background on action hover |
+| `hover-destructive-bg` | `transparent` | Background on destructive hover |
+
+### Button Component (`components/ui/button.tsx`)
+
+Uses CVA with three variants and three sizes:
+
+**Variants:**
+
+| Variant | Base styles | Hover |
+|---|---|---|
+| `default` (primary) | `bg-primary text-primary-foreground` | `hover:bg-primary/90` |
+| `outline` | `border border-border bg-transparent` | `hover:bg-hover-neutral-bg hover:text-hover-neutral` |
+| `ghost` | (no background/border) | `hover:bg-hover-neutral-bg hover:text-hover-neutral` |
+
+**Sizes:**
+
+| Size | Classes |
+|---|---|
+| `default` | `h-9 px-4 py-2` |
+| `sm` | `h-8 px-3 text-xs` |
+| `icon` | `h-8 w-8` |
+
+All variants share: `rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary disabled:pointer-events-none disabled:opacity-50`.
+
+There is **no "secondary" variant** — the outline variant is the closest equivalent.
+
+### Composite Button Components
+
+**ConfirmButton** (`components/ui/confirm-button.tsx`):
+- Wraps `Button variant="ghost" size="icon"`
+- Default state: `hover:text-hover-destructive` (uses token)
+- Confirming state: `bg-destructive text-primary-foreground animate-confirm-pulse hover:bg-destructive hover:text-primary-foreground`
+
+**OverflowMenu** (`components/ui/overflow-menu.tsx`):
+- Trigger: `Button variant="ghost" size="icon"` with `text-muted-foreground hover:text-hover-neutral`
+- Menu items: raw `<button>` elements with `hover:bg-muted/20` (**not using the token system**)
+
+### Button Usage Across Components
+
+| Component | Button type | Variant/Style |
+|---|---|---|
+| `action-bar.tsx:556` | `<Button type="submit">` | default (primary) — "Add" |
+| `action-bar.tsx:561` | `<Button type="button">` | default (primary) — "Roll all" |
+| `turn-navigation.tsx:25,54` | `<Button size="icon">` | default — prev/next turn |
+| `turn-navigation.tsx:47` | `<ConfirmButton>` | ghost+destructive — clear encounter |
+| `source-fetch-prompt.tsx:91` | `<Button size="sm">` | default — "Load" |
+| `source-fetch-prompt.tsx:106` | `<Button size="sm" variant="outline">` | outline — "Upload file" |
+| `bulk-import-prompt.tsx:31,45,106` | `<Button size="sm">` | default — "Done"/"Load All" |
+| `source-manager.tsx:50` | `<Button size="sm" variant="outline">` | outline — "Clear all" |
+| `hp-adjust-popover.tsx:112` | `<Button variant="ghost" size="icon">` | ghost + custom red — damage |
+| `hp-adjust-popover.tsx:124` | `<Button variant="ghost" size="icon">` | ghost + custom green — heal |
+| `player-management.tsx:67` | `<Button>` | default — "Create first player" |
+| `player-management.tsx:113` | `<Button variant="ghost">` | ghost — "Add player" |
+| `create-player-modal.tsx:177` | `<Button variant="ghost">` | ghost — "Cancel" |
+| `create-player-modal.tsx:180` | `<Button type="submit">` | default — "Save"/"Create" |
+| `combatant-row.tsx:625` | `<ConfirmButton>` | ghost+destructive — remove combatant |
+
+**Raw `<button>` elements** (not using the Button component):
+- `action-bar.tsx` — suggestion items, count increment/decrement, browse toggle, custom add (all inline-styled)
+- `combatant-row.tsx` — editable name, HP display, AC, initiative, concentration toggle
+- `stat-block-panel.tsx` — fold/close/pin/unpin buttons
+- `condition-picker.tsx` — condition items
+- `condition-tags.tsx` — condition tags, add condition button
+- `toast.tsx` — dismiss button
+- `player-management.tsx` — close modal, edit player
+- `create-player-modal.tsx` — close modal
+- `color-palette.tsx` — color swatches
+- `icon-grid.tsx` — icon options
+
+### Hover Effects Inventory
+
+**Using semantic tokens (unified):**
+
+| Hover class | Meaning | Used in |
+|---|---|---|
+| `hover:bg-hover-neutral-bg` | Neutral background highlight | button.tsx (outline/ghost), action-bar.tsx, condition-picker.tsx, condition-tags.tsx |
+| `hover:text-hover-neutral` | Text turns primary blue | button.tsx (outline/ghost), action-bar.tsx, combatant-row.tsx, stat-block-panel.tsx, ac-shield.tsx, toast.tsx, overflow-menu.tsx, condition-tags.tsx |
+| `hover:text-hover-action` | Action text (same as neutral) | action-bar.tsx (overflow trigger) |
+| `hover:text-hover-destructive` | Destructive text turns red | confirm-button.tsx, source-manager.tsx |
+| `hover:bg-hover-destructive-bg` | Destructive background (transparent) | source-manager.tsx |
+
+**One-off / hardcoded hover colors (NOT using tokens):**
+
+| Hover class | Used in | Context |
+|---|---|---|
+| `hover:bg-primary/90` | button.tsx (default variant) | Primary button darken |
+| `hover:bg-accent/20` | action-bar.tsx | Suggestion highlight, custom add |
+| `hover:bg-accent/40` | action-bar.tsx | Count +/- buttons, confirm queued |
+| `hover:bg-muted/20` | overflow-menu.tsx | Menu item highlight |
+| `hover:bg-red-950` | hp-adjust-popover.tsx | Damage button |
+| `hover:text-red-300` | hp-adjust-popover.tsx | Damage button text |
+| `hover:bg-emerald-950` | hp-adjust-popover.tsx | Heal button |
+| `hover:text-emerald-300` | hp-adjust-popover.tsx | Heal button text |
+| `hover:text-foreground` | player-management.tsx, create-player-modal.tsx, icon-grid.tsx | Close/edit buttons |
+| `hover:bg-background/50` | player-management.tsx | Player row hover |
+| `hover:bg-card` | icon-grid.tsx | Icon option hover |
+| `hover:border-hover-destructive` | source-manager.tsx | Clear all button border |
+| `hover:scale-110` | color-palette.tsx | Color swatch enlarge |
+| `hover:bg-destructive` | confirm-button.tsx (confirming state) | Maintain red bg on hover |
+| `hover:text-primary-foreground` | confirm-button.tsx (confirming state) | Maintain white text on hover |
+
+### Hover unification assessment
+
+The hover token system (`hover-neutral`, `hover-action`, `hover-destructive`) provides a consistent pattern for the most common interactions. The `Button` component's outline and ghost variants use these tokens, and many inline buttons in action-bar, combatant-row, stat-block-panel, and condition components also use them.
+
+However, there are notable gaps:
+1. **HP adjust popover** uses hardcoded red/green colors (`red-950`, `emerald-950`) instead of tokens
+2. **Overflow menu items** use `hover:bg-muted/20` instead of `hover:bg-hover-neutral-bg`
+3. **Player management modals** use `hover:text-foreground` and `hover:bg-background/50` instead of the semantic tokens
+4. **Action-bar suggestion items** use `hover:bg-accent/20` and `hover:bg-accent/40` — accent-specific patterns not in the token system
+5. **Icon grid** and **color palette** use their own hover patterns (`hover:bg-card`, `hover:scale-110`)
+
+## Code References
+
+- `apps/web/src/index.css:3-26` — Theme color definitions including hover tokens
+- `apps/web/src/components/ui/button.tsx:1-38` — Button component with CVA variants
+- `apps/web/src/components/ui/confirm-button.tsx:93-115` — ConfirmButton with destructive hover states
+- `apps/web/src/components/ui/overflow-menu.tsx:38-72` — OverflowMenu with non-token hover
+- `apps/web/src/components/hp-adjust-popover.tsx:117-129` — Hardcoded red/green hover colors
+- `apps/web/src/components/action-bar.tsx:80-188` — Mixed token and accent-based hovers
+- `apps/web/src/components/combatant-row.tsx:147-629` — Inline buttons with token hovers
+- `apps/web/src/components/player-management.tsx:58-98` — Non-token hover patterns
+- `apps/web/src/components/stat-block-panel.tsx:55-109` — Consistent token usage
+- `apps/web/src/lib/utils.ts:1-5` — `cn()` utility (clsx + twMerge)
+
+## Architecture Documentation
+
+The styling architecture follows this pattern:
+
+1. **Theme layer**: `index.css` defines all color tokens via `@theme`, including semantic hover tokens
+2. **Component layer**: `Button` (CVA) provides the shared button abstraction with three variants
+3. **Composite layer**: `ConfirmButton` and `OverflowMenu` wrap `Button` with additional behavior
+4. **Usage layer**: Components use either `Button` component or raw `<button>` elements with inline Tailwind classes
+
+The `cn()` utility from `lib/utils.ts` is used in 9+ components for conditional class merging.
+
+Custom animations are defined in `index.css` via `@keyframes` + `@utility` pairs: slide-in-right, confirm-pulse, settle-to-bottom, rise-to-center, slide-down-in, slide-up-out, concentration-pulse.
+
+## Open Questions
+
+1. The `hover-action` and `hover-action-bg` tokens are defined but rarely used — `hover-action` appears only once in `action-bar.tsx:565`. Is this intentional or an incomplete migration?
+2. The `accent` color (`#3b82f6`) is identical to `primary` — are they intended to diverge in the future, or is this redundancy?
+3. Should the hardcoded HP adjust colors (red/emerald) be promoted to theme tokens (e.g., `hover-damage`, `hover-heal`)?

nginx.conf

@@ -0,0 +1,9 @@
+server {
+    listen 80;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}

package.json

@@ -3,6 +3,8 @@
 	"packageManager": "pnpm@10.6.0",
 	"devDependencies": {
 		"@biomejs/biome": "2.0.0",
+		"@vitest/coverage-v8": "^3.2.4",
+		"jscpd": "^4.0.8",
 		"knip": "^5.85.0",
 		"lefthook": "^1.11.0",
 		"typescript": "^5.8.0",
@@ -18,6 +20,7 @@
 		"test": "vitest run",
 		"test:watch": "vitest",
 		"knip": "knip",
-		"check": "knip && biome check . && tsc --build && vitest run"
+		"jscpd": "jscpd",
+		"check": "pnpm audit --audit-level=high && knip && biome check . && tsc --build && vitest run && jscpd"
 	}
 }

packages/application/src/adjust-hp-use-case.ts

@@ -0,0 +1,24 @@
+import {
+	adjustHp,
+	type CombatantId,
+	type DomainError,
+	type DomainEvent,
+	isDomainError,
+} from "@initiative/domain";
+import type { EncounterStore } from "./ports.js";
+
+export function adjustHpUseCase(
+	store: EncounterStore,
+	combatantId: CombatantId,
+	delta: number,
+): DomainEvent[] | DomainError {
+	const encounter = store.get();
+	const result = adjustHp(encounter, combatantId, delta);
+
+	if (isDomainError(result)) {
+		return result;
+	}
+
+	store.save(result.encounter);
+	return result.events;
+}

packages/application/src/clear-encounter-use-case.ts

@@ -0,0 +1,21 @@
+import {
+	clearEncounter,
+	type DomainError,
+	type DomainEvent,
+	isDomainError,
+} from "@initiative/domain";
+import type { EncounterStore } from "./ports.js";
+
+export function clearEncounterUseCase(
+	store: EncounterStore,
+): DomainEvent[] | DomainError {
+	const encounter = store.get();
+	const result = clearEncounter(encounter);
+
+	if (isDomainError(result)) {
+		return result;
+	}
+
+	store.save(result.encounter);
+	return result.events;
+}

packages/application/src/create-player-character-use-case.ts

@@ -0,0 +1,36 @@
+import {
+	createPlayerCharacter,
+	type DomainError,
+	type DomainEvent,
+	isDomainError,
+	type PlayerCharacterId,
+} from "@initiative/domain";
+import type { PlayerCharacterStore } from "./ports.js";
+
+export function createPlayerCharacterUseCase(
+	store: PlayerCharacterStore,
+	id: PlayerCharacterId,
+	name: string,
+	ac: number,
+	maxHp: number,
+	color: string,
+	icon: string,
+): DomainEvent[] | DomainError {
+	const characters = store.getAll();
+	const result = createPlayerCharacter(
+		characters,
+		id,
+		name,
+		ac,
+		maxHp,
+		color,
+		icon,
+	);
+
+	if (isDomainError(result)) {
+		return result;
+	}
+
+	store.save([...result.characters]);
+	return result.events;
+}

packages/application/src/delete-player-character-use-case.ts

@@ -0,0 +1,23 @@
+import {
+	type DomainError,
+	type DomainEvent,
+	deletePlayerCharacter,
+	isDomainError,
+	type PlayerCharacterId,
+} from "@initiative/domain";
+import type { PlayerCharacterStore } from "./ports.js";
+
+export function deletePlayerCharacterUseCase(
+	store: PlayerCharacterStore,
+	id: PlayerCharacterId,
+): DomainEvent[] | DomainError {
+	const characters = store.getAll();
+	const result = deletePlayerCharacter(characters, id);
+
+	if (isDomainError(result)) {
+		return result;
+	}
+
+	store.save([...result.characters]);
+	return result.events;
+}

packages/application/src/edit-player-character-use-case.ts

@@ -0,0 +1,32 @@
+import {
+	type DomainError,
+	type DomainEvent,
+	editPlayerCharacter,
+	isDomainError,
+	type PlayerCharacterId,
+} from "@initiative/domain";
+import type { PlayerCharacterStore } from "./ports.js";
+
+interface EditFields {
+	readonly name?: string;
+	readonly ac?: number;
+	readonly maxHp?: number;
+	readonly color?: string;
+	readonly icon?: string;
+}
+
+export function editPlayerCharacterUseCase(
+	store: PlayerCharacterStore,
+	id: PlayerCharacterId,
+	fields: EditFields,
+): DomainEvent[] | DomainError {
+	const characters = store.getAll();
+	const result = editPlayerCharacter(characters, id, fields);
+
+	if (isDomainError(result)) {
+		return result;
+	}
+
+	store.save([...result.characters]);
+	return result.events;
+}

packages/application/src/index.ts

@@ -1,6 +1,22 @@
 export { addCombatantUseCase } from "./add-combatant-use-case.js";
+export { adjustHpUseCase } from "./adjust-hp-use-case.js";
 export { advanceTurnUseCase } from "./advance-turn-use-case.js";
+export { clearEncounterUseCase } from "./clear-encounter-use-case.js";
+export { createPlayerCharacterUseCase } from "./create-player-character-use-case.js";
+export { deletePlayerCharacterUseCase } from "./delete-player-character-use-case.js";
 export { editCombatantUseCase } from "./edit-combatant-use-case.js";
-export type { EncounterStore } from "./ports.js";
+export { editPlayerCharacterUseCase } from "./edit-player-character-use-case.js";
+export type {
+	BestiarySourceCache,
+	EncounterStore,
+	PlayerCharacterStore,
+} from "./ports.js";
 export { removeCombatantUseCase } from "./remove-combatant-use-case.js";
+export { retreatTurnUseCase } from "./retreat-turn-use-case.js";
+export { rollAllInitiativeUseCase } from "./roll-all-initiative-use-case.js";
+export { rollInitiativeUseCase } from "./roll-initiative-use-case.js";
+export { setAcUseCase } from "./set-ac-use-case.js";
+export { setHpUseCase } from "./set-hp-use-case.js";
 export { setInitiativeUseCase } from "./set-initiative-use-case.js";
+export { toggleConcentrationUseCase } from "./toggle-concentration-use-case.js";
+export { toggleConditionUseCase } from "./toggle-condition-use-case.js";

packages/application/src/ports.ts

@@ -1,6 +1,21 @@
-import type { Encounter } from "@initiative/domain";
+import type {
+	Creature,
+	CreatureId,
+	Encounter,
+	PlayerCharacter,
+} from "@initiative/domain";
 
 export interface EncounterStore {
 	get(): Encounter;
 	save(encounter: Encounter): void;
 }
+
+export interface BestiarySourceCache {
+	getCreature(creatureId: CreatureId): Creature | undefined;
+	isSourceCached(sourceCode: string): boolean;
+}
+
+export interface PlayerCharacterStore {
+	getAll(): PlayerCharacter[];
+	save(characters: PlayerCharacter[]): void;
+}

packages/application/src/retreat-turn-use-case.ts

@@ -0,0 +1,21 @@
+import {
+	type DomainError,
+	type DomainEvent,
+	isDomainError,
+	retreatTurn,
+} from "@initiative/domain";
+import type { EncounterStore } from "./ports.js";
+
+export function retreatTurnUseCase(
+	store: EncounterStore,
+): DomainEvent[] | DomainError {
+	const encounter = store.get();
+	const result = retreatTurn(encounter);
+
+	if (isDomainError(result)) {
+		return result;
+	}
+
+	store.save(result.encounter);
+	return result.events;
+}

packages/application/src/roll-all-initiative-use-case.ts

@@ -0,0 +1,51 @@
+import {
+	type Creature,
+	type CreatureId,
+	calculateInitiative,
+	type DomainError,
+	type DomainEvent,
+	isDomainError,
+	rollInitiative,
+	setInitiative,
+} from "@initiative/domain";
+import type { EncounterStore } from "./ports.js";
+
+export function rollAllInitiativeUseCase(
+	store: EncounterStore,
+	rollDice: () => number,
+	getCreature: (id: CreatureId) => Creature | undefined,
+): DomainEvent[] | DomainError {
+	let encounter = store.get();
+	const allEvents: DomainEvent[] = [];
+
+	for (const combatant of encounter.combatants) {
+		if (!combatant.creatureId) continue;
+		if (combatant.initiative !== undefined) continue;
+
+		const creature = getCreature(combatant.creatureId);
+		if (!creature) continue;
+
+		const { modifier } = calculateInitiative({
+			dexScore: creature.abilities.dex,
+			cr: creature.cr,
+			initiativeProficiency: creature.initiativeProficiency,
+		});
+		const value = rollInitiative(rollDice(), modifier);
+
+		if (isDomainError(value)) {
+			return value;
+		}
+
+		const result = setInitiative(encounter, combatant.id, value);
+
+		if (isDomainError(result)) {
+			return result;
+		}
+
+		encounter = result.encounter;
+		allEvents.push(...result.events);
+	}
+
+	store.save(encounter);
+	return allEvents;
+}

packages/application/src/roll-initiative-use-case.ts

@@ -0,0 +1,67 @@
+import {
+	type CombatantId,
+	type Creature,
+	type CreatureId,
+	calculateInitiative,
+	type DomainError,
+	type DomainEvent,
+	isDomainError,
+	rollInitiative,
+	setInitiative,
+} from "@initiative/domain";
+import type { EncounterStore } from "./ports.js";
+
+export function rollInitiativeUseCase(
+	store: EncounterStore,
+	combatantId: CombatantId,
+	diceRoll: number,
+	getCreature: (id: CreatureId) => Creature | undefined,
+): DomainEvent[] | DomainError {
+	const encounter = store.get();
+	const combatant = encounter.combatants.find((c) => c.id === combatantId);
+
+	if (!combatant) {
+		return {
+			kind: "domain-error",
+			code: "combatant-not-found",
+			message: `No combatant found with ID "${combatantId}"`,
+		};
+	}
+
+	if (!combatant.creatureId) {
+		return {
+			kind: "domain-error",
+			code: "no-creature-link",
+			message: `Combatant "${combatant.name}" has no linked creature`,
+		};
+	}
+
+	const creature = getCreature(combatant.creatureId);
+	if (!creature) {
+		return {
+			kind: "domain-error",
+			code: "creature-not-found",
+			message: `Creature not found for ID "${combatant.creatureId}"`,
+		};
+	}
+
+	const { modifier } = calculateInitiative({
+		dexScore: creature.abilities.dex,
+		cr: creature.cr,
+		initiativeProficiency: creature.initiativeProficiency,
+	});
+	const value = rollInitiative(diceRoll, modifier);
+
+	if (isDomainError(value)) {
+		return value;
+	}
+
+	const result = setInitiative(encounter, combatantId, value);
+
+	if (isDomainError(result)) {
+		return result;
+	}
+
+	store.save(result.encounter);
+	return result.events;
+}

packages/application/src/set-ac-use-case.ts

@@ -0,0 +1,24 @@
+import {
+	type CombatantId,
+	type DomainError,
+	type DomainEvent,
+	isDomainError,
+	setAc,
+} from "@initiative/domain";
+import type { EncounterStore } from "./ports.js";
+
+export function setAcUseCase(
+	store: EncounterStore,
+	combatantId: CombatantId,
+	value: number | undefined,
+): DomainEvent[] | DomainError {
+	const encounter = store.get();
+	const result = setAc(encounter, combatantId, value);
+
+	if (isDomainError(result)) {
+		return result;
+	}
+
+	store.save(result.encounter);
+	return result.events;
+}

packages/application/src/set-hp-use-case.ts

@@ -0,0 +1,24 @@
+import {
+	type CombatantId,
+	type DomainError,
+	type DomainEvent,
+	isDomainError,
+	setHp,
+} from "@initiative/domain";
+import type { EncounterStore } from "./ports.js";
+
+export function setHpUseCase(
+	store: EncounterStore,
+	combatantId: CombatantId,
+	maxHp: number | undefined,
+): DomainEvent[] | DomainError {
+	const encounter = store.get();
+	const result = setHp(encounter, combatantId, maxHp);
+
+	if (isDomainError(result)) {
+		return result;
+	}
+
+	store.save(result.encounter);
+	return result.events;
+}

packages/application/src/toggle-concentration-use-case.ts

@@ -0,0 +1,23 @@
+import {
+	type CombatantId,
+	type DomainError,
+	type DomainEvent,
+	isDomainError,
+	toggleConcentration,
+} from "@initiative/domain";
+import type { EncounterStore } from "./ports.js";
+
+export function toggleConcentrationUseCase(
+	store: EncounterStore,
+	combatantId: CombatantId,
+): DomainEvent[] | DomainError {
+	const encounter = store.get();
+	const result = toggleConcentration(encounter, combatantId);
+
+	if (isDomainError(result)) {
+		return result;
+	}
+
+	store.save(result.encounter);
+	return result.events;
+}

packages/application/src/toggle-condition-use-case.ts

@@ -0,0 +1,25 @@
+import {
+	type CombatantId,
+	type ConditionId,
+	type DomainError,
+	type DomainEvent,
+	isDomainError,
+	toggleCondition,
+} from "@initiative/domain";
+import type { EncounterStore } from "./ports.js";
+
+export function toggleConditionUseCase(
+	store: EncounterStore,
+	combatantId: CombatantId,
+	conditionId: ConditionId,
+): DomainEvent[] | DomainError {
+	const encounter = store.get();
+	const result = toggleCondition(encounter, combatantId, conditionId);
+
+	if (isDomainError(result)) {
+		return result;
+	}
+
+	store.save(result.encounter);
+	return result.events;
+}

packages/domain/src/__tests__/adjust-hp.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it } from "vitest";
+import { adjustHp } from "../adjust-hp.js";
+import type { Combatant, Encounter } from "../types.js";
+import { combatantId, isDomainError } from "../types.js";
+
+function makeCombatant(
+	name: string,
+	opts?: { maxHp: number; currentHp: number },
+): Combatant {
+	return {
+		id: combatantId(name),
+		name,
+		...(opts ? { maxHp: opts.maxHp, currentHp: opts.currentHp } : {}),
+	};
+}
+
+function enc(combatants: Combatant[]): Encounter {
+	return { combatants, activeIndex: 0, roundNumber: 1 };
+}
+
+function successResult(encounter: Encounter, id: string, delta: number) {
+	const result = adjustHp(encounter, combatantId(id), delta);
+	if (isDomainError(result)) {
+		throw new Error(`Expected success, got error: ${result.message}`);
+	}
+	return result;
+}
+
+describe("adjustHp", () => {
+	describe("acceptance scenarios", () => {
+		it("+1 increases currentHp by 1", () => {
+			const e = enc([makeCombatant("A", { maxHp: 20, currentHp: 15 })]);
+			const { encounter } = successResult(e, "A", 1);
+			expect(encounter.combatants[0].currentHp).toBe(16);
+		});
+
+		it("-1 decreases currentHp by 1", () => {
+			const e = enc([makeCombatant("A", { maxHp: 20, currentHp: 15 })]);
+			const { encounter } = successResult(e, "A", -1);
+			expect(encounter.combatants[0].currentHp).toBe(14);
+		});
+
+		it("clamps at 0 — cannot go below zero", () => {
+			const e = enc([makeCombatant("A", { maxHp: 20, currentHp: 3 })]);
+			const { encounter } = successResult(e, "A", -10);
+			expect(encounter.combatants[0].currentHp).toBe(0);
+		});
+
+		it("clamps at maxHp — cannot exceed max", () => {
+			const e = enc([makeCombatant("A", { maxHp: 20, currentHp: 18 })]);
+			const { encounter } = successResult(e, "A", 10);
+			expect(encounter.combatants[0].currentHp).toBe(20);
+		});
+	});
+
+	describe("invariants", () => {
+		it("is pure — same input produces same output", () => {
+			const e = enc([makeCombatant("A", { maxHp: 20, currentHp: 10 })]);
+			const r1 = adjustHp(e, combatantId("A"), -5);
+			const r2 = adjustHp(e, combatantId("A"), -5);
+			expect(r1).toEqual(r2);
+		});
+
+		it("does not mutate input encounter", () => {
+			const e = enc([makeCombatant("A", { maxHp: 20, currentHp: 10 })]);
+			const original = JSON.parse(JSON.stringify(e));
+			adjustHp(e, combatantId("A"), -3);
+			expect(e).toEqual(original);
+		});
+
+		it("emits CurrentHpAdjusted event with delta", () => {
+			const e = enc([makeCombatant("A", { maxHp: 20, currentHp: 15 })]);
+			const { events } = successResult(e, "A", -5);
+			expect(events).toEqual([
+				{
+					type: "CurrentHpAdjusted",
+					combatantId: combatantId("A"),
+					previousHp: 15,
+					newHp: 10,
+					delta: -5,
+				},
+			]);
+		});
+
+		it("preserves activeIndex and roundNumber", () => {
+			const e = {
+				combatants: [
+					makeCombatant("A", { maxHp: 20, currentHp: 10 }),
+					makeCombatant("B"),
+				],
+				activeIndex: 1,
+				roundNumber: 5,
+			};
+			const { encounter } = successResult(e, "A", -3);
+			expect(encounter.activeIndex).toBe(1);
+			expect(encounter.roundNumber).toBe(5);
+		});
+	});
+
+	describe("error cases", () => {
+		it("returns error for nonexistent combatant", () => {
+			const e = enc([makeCombatant("A", { maxHp: 20, currentHp: 10 })]);
+			const result = adjustHp(e, combatantId("Z"), -1);
+			expect(isDomainError(result)).toBe(true);
+			if (isDomainError(result)) {
+				expect(result.code).toBe("combatant-not-found");
+			}
+		});
+
+		it("returns error when combatant has no HP tracking", () => {
+			const e = enc([makeCombatant("A")]);
+			const result = adjustHp(e, combatantId("A"), -1);
+			expect(isDomainError(result)).toBe(true);
+			if (isDomainError(result)) {
+				expect(result.code).toBe("no-hp-tracking");
+			}
+		});
+
+		it("returns error for zero delta", () => {
+			const e = enc([makeCombatant("A", { maxHp: 20, currentHp: 10 })]);
+			const result = adjustHp(e, combatantId("A"), 0);
+			expect(isDomainError(result)).toBe(true);
+			if (isDomainError(result)) {
+				expect(result.code).toBe("zero-delta");
+			}
+		});
+
+		it("returns error for non-integer delta", () => {
+			const e = enc([makeCombatant("A", { maxHp: 20, currentHp: 10 })]);
+			const result = adjustHp(e, combatantId("A"), 1.5);
+			expect(isDomainError(result)).toBe(true);
+			if (isDomainError(result)) {
+				expect(result.code).toBe("invalid-delta");
+			}
+		});
+	});
+
+	describe("edge cases", () => {
+		it("large negative delta beyond currentHp clamps to 0", () => {
+			const e = enc([makeCombatant("A", { maxHp: 100, currentHp: 50 })]);
+			const { encounter } = successResult(e, "A", -9999);
+			expect(encounter.combatants[0].currentHp).toBe(0);
+		});
+
+		it("large positive delta beyond maxHp clamps to maxHp", () => {
+			const e = enc([makeCombatant("A", { maxHp: 100, currentHp: 50 })]);
+			const { encounter } = successResult(e, "A", 9999);
+			expect(encounter.combatants[0].currentHp).toBe(100);
+		});
+
+		it("does not affect other combatants", () => {
+			const e = enc([
+				makeCombatant("A", { maxHp: 20, currentHp: 15 }),
+				makeCombatant("B", { maxHp: 30, currentHp: 25 }),
+			]);
+			const { encounter } = successResult(e, "A", -5);
+			expect(encounter.combatants[1].currentHp).toBe(25);
+		});
+
+		it("adjusting from 0 upward works", () => {
+			const e = enc([makeCombatant("A", { maxHp: 20, currentHp: 0 })]);
+			const { encounter } = successResult(e, "A", 5);
+			expect(encounter.combatants[0].currentHp).toBe(5);
+		});
+	});
+});

packages/domain/src/__tests__/advance-turn.test.ts

@@ -169,9 +169,9 @@ describe("advanceTurn", () => {
 	});
 
 	describe("invariants", () => {
-		it("INV-1: createEncounter rejects empty combatant list", () => {
+		it("INV-1: createEncounter accepts empty combatant list", () => {
 			const result = createEncounter([]);
-			expect(isDomainError(result)).toBe(true);
+			expect(isDomainError(result)).toBe(false);
 		});
 
 		it("INV-2: activeIndex always in bounds across all scenarios", () => {

packages/domain/src/__tests__/auto-number.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { resolveCreatureName } from "../auto-number.js";
+
+describe("resolveCreatureName", () => {
+	it("returns name as-is when no conflict exists", () => {
+		const result = resolveCreatureName("Goblin", ["Orc", "Dragon"]);
+		expect(result).toEqual({ newName: "Goblin", renames: [] });
+	});
+
+	it("returns name as-is when existing list is empty", () => {
+		const result = resolveCreatureName("Goblin", []);
+		expect(result).toEqual({ newName: "Goblin", renames: [] });
+	});
+
+	it("renames existing to 'Name 1' and new to 'Name 2' on first conflict", () => {
+		const result = resolveCreatureName("Goblin", ["Orc", "Goblin", "Dragon"]);
+		expect(result).toEqual({
+			newName: "Goblin 2",
+			renames: [{ from: "Goblin", to: "Goblin 1" }],
+		});
+	});
+
+	it("appends next number when numbered variants already exist", () => {
+		const result = resolveCreatureName("Goblin", ["Goblin 1", "Goblin 2"]);
+		expect(result).toEqual({ newName: "Goblin 3", renames: [] });
+	});
+
+	it("handles mixed exact and numbered matches", () => {
+		const result = resolveCreatureName("Goblin", [
+			"Goblin",
+			"Goblin 1",
+			"Goblin 2",
+		]);
+		expect(result).toEqual({ newName: "Goblin 3", renames: [] });
+	});
+
+	it("handles names with special regex characters", () => {
+		const result = resolveCreatureName("Goblin (Boss)", ["Goblin (Boss)"]);
+		expect(result).toEqual({
+			newName: "Goblin (Boss) 2",
+			renames: [{ from: "Goblin (Boss)", to: "Goblin (Boss) 1" }],
+		});
+	});
+
+	it("does not match partial name overlaps", () => {
+		const result = resolveCreatureName("Goblin", ["Goblin Boss"]);
+		expect(result).toEqual({ newName: "Goblin", renames: [] });
+	});
+});

packages/domain/src/__tests__/clear-encounter.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "vitest";
+import { clearEncounter } from "../clear-encounter.js";
+import type { DomainError, Encounter } from "../types.js";
+import { combatantId, createEncounter, isDomainError } from "../types.js";
+
+function makeEncounter(
+	count: number,
+	overrides?: Partial<Encounter>,
+): Encounter {
+	const combatants = Array.from({ length: count }, (_, i) => ({
+		id: combatantId(`c-${i + 1}`),
+		name: `Combatant ${i + 1}`,
+	}));
+
+	const result = createEncounter(combatants);
+	if (isDomainError(result)) {
+		throw new Error("Failed to create encounter in test helper");
+	}
+
+	return { ...result, ...overrides };
+}
+
+describe("clearEncounter", () => {
+	it("clears encounter with multiple combatants at round 3 — returns empty encounter with roundNumber 1 and activeIndex 0", () => {
+		const encounter = makeEncounter(4, { roundNumber: 3, activeIndex: 2 });
+
+		const result = clearEncounter(encounter);
+
+		expect(isDomainError(result)).toBe(false);
+		const success = result as Exclude<typeof result, DomainError>;
+		expect(success.encounter.combatants).toEqual([]);
+		expect(success.encounter.roundNumber).toBe(1);
+		expect(success.encounter.activeIndex).toBe(0);
+	});
+
+	it("clears encounter with a single combatant", () => {
+		const encounter = makeEncounter(1);
+
+		const result = clearEncounter(encounter);
+
+		expect(isDomainError(result)).toBe(false);
+		const success = result as Exclude<typeof result, DomainError>;
+		expect(success.encounter.combatants).toEqual([]);
+		expect(success.encounter.activeIndex).toBe(0);
+		expect(success.encounter.roundNumber).toBe(1);
+	});
+
+	it("clears encounter with combatants that have HP/AC/conditions/concentration", () => {
+		const encounter: Encounter = {
+			combatants: [
+				{
+					id: combatantId("c-1"),
+					name: "Fighter",
+					maxHp: 50,
+					currentHp: 30,
+					ac: 18,
+					conditions: ["blinded", "poisoned"],
+					isConcentrating: true,
+				},
+				{
+					id: combatantId("c-2"),
+					name: "Wizard",
+					maxHp: 25,
+					currentHp: 0,
+					ac: 12,
+					conditions: ["unconscious"],
+				},
+			],
+			activeIndex: 0,
+			roundNumber: 5,
+		};
+
+		const result = clearEncounter(encounter);
+
+		expect(isDomainError(result)).toBe(false);
+		const success = result as Exclude<typeof result, DomainError>;
+		expect(success.encounter.combatants).toEqual([]);
+	});
+
+	it("returns DomainError with code 'encounter-already-empty' when encounter has no combatants", () => {
+		const encounter: Encounter = {
+			combatants: [],
+			activeIndex: 0,
+			roundNumber: 1,
+		};
+
+		const result = clearEncounter(encounter);
+
+		expect(isDomainError(result)).toBe(true);
+		const error = result as DomainError;
+		expect(error.code).toBe("encounter-already-empty");
+	});
+
+	it("emits EncounterCleared event with correct combatantCount", () => {
+		const encounter = makeEncounter(3);
+
+		const result = clearEncounter(encounter);
+
+		expect(isDomainError(result)).toBe(false);
+		const success = result as Exclude<typeof result, DomainError>;
+		expect(success.events).toEqual([
+			{ type: "EncounterCleared", combatantCount: 3 },
+		]);
+	});
+
+	it("is deterministic — same input always produces same output", () => {
+		const encounter = makeEncounter(2, { roundNumber: 4, activeIndex: 1 });
+
+		const result1 = clearEncounter(encounter);
+		const result2 = clearEncounter(encounter);
+
+		expect(result1).toEqual(result2);
+	});
+});

packages/domain/src/__tests__/create-player-character.test.ts

@@ -0,0 +1,227 @@
+import { describe, expect, it } from "vitest";
+import { createPlayerCharacter } from "../create-player-character.js";
+import type { PlayerCharacter } from "../player-character-types.js";
+import { playerCharacterId } from "../player-character-types.js";
+import { isDomainError } from "../types.js";
+
+const id = playerCharacterId("pc-1");
+
+function success(
+	characters: readonly PlayerCharacter[],
+	name: string,
+	ac: number,
+	maxHp: number,
+	color = "blue",
+	icon = "sword",
+) {
+	const result = createPlayerCharacter(
+		characters,
+		id,
+		name,
+		ac,
+		maxHp,
+		color,
+		icon,
+	);
+	if (isDomainError(result)) {
+		throw new Error(`Expected success, got error: ${result.message}`);
+	}
+	return result;
+}
+
+describe("createPlayerCharacter", () => {
+	it("creates a valid player character", () => {
+		const { characters, events } = success(
+			[],
+			"Aragorn",
+			16,
+			120,
+			"green",
+			"shield",
+		);
+
+		expect(characters).toHaveLength(1);
+		expect(characters[0]).toEqual({
+			id,
+			name: "Aragorn",
+			ac: 16,
+			maxHp: 120,
+			color: "green",
+			icon: "shield",
+		});
+		expect(events).toEqual([
+			{
+				type: "PlayerCharacterCreated",
+				playerCharacterId: id,
+				name: "Aragorn",
+			},
+		]);
+	});
+
+	it("trims whitespace from name", () => {
+		const { characters } = success([], "  Gandalf  ", 12, 80);
+		expect(characters[0].name).toBe("Gandalf");
+	});
+
+	it("appends to existing characters", () => {
+		const existing: PlayerCharacter = {
+			id: playerCharacterId("pc-0"),
+			name: "Legolas",
+			ac: 14,
+			maxHp: 90,
+			color: "green",
+			icon: "eye",
+		};
+		const { characters } = success([existing], "Gimli", 18, 100, "red", "axe");
+		expect(characters).toHaveLength(2);
+		expect(characters[0]).toEqual(existing);
+		expect(characters[1].name).toBe("Gimli");
+	});
+
+	it("rejects empty name", () => {
+		const result = createPlayerCharacter([], id, "", 10, 50, "blue", "sword");
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("invalid-name");
+		}
+	});
+
+	it("rejects whitespace-only name", () => {
+		const result = createPlayerCharacter(
+			[],
+			id,
+			"   ",
+			10,
+			50,
+			"blue",
+			"sword",
+		);
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("invalid-name");
+		}
+	});
+
+	it("rejects negative AC", () => {
+		const result = createPlayerCharacter(
+			[],
+			id,
+			"Test",
+			-1,
+			50,
+			"blue",
+			"sword",
+		);
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("invalid-ac");
+		}
+	});
+
+	it("rejects non-integer AC", () => {
+		const result = createPlayerCharacter(
+			[],
+			id,
+			"Test",
+			10.5,
+			50,
+			"blue",
+			"sword",
+		);
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("invalid-ac");
+		}
+	});
+
+	it("allows AC of 0", () => {
+		const { characters } = success([], "Test", 0, 50);
+		expect(characters[0].ac).toBe(0);
+	});
+
+	it("rejects maxHp of 0", () => {
+		const result = createPlayerCharacter(
+			[],
+			id,
+			"Test",
+			10,
+			0,
+			"blue",
+			"sword",
+		);
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("invalid-max-hp");
+		}
+	});
+
+	it("rejects negative maxHp", () => {
+		const result = createPlayerCharacter(
+			[],
+			id,
+			"Test",
+			10,
+			-5,
+			"blue",
+			"sword",
+		);
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("invalid-max-hp");
+		}
+	});
+
+	it("rejects non-integer maxHp", () => {
+		const result = createPlayerCharacter(
+			[],
+			id,
+			"Test",
+			10,
+			50.5,
+			"blue",
+			"sword",
+		);
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("invalid-max-hp");
+		}
+	});
+
+	it("rejects invalid color", () => {
+		const result = createPlayerCharacter(
+			[],
+			id,
+			"Test",
+			10,
+			50,
+			"neon",
+			"sword",
+		);
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("invalid-color");
+		}
+	});
+
+	it("rejects invalid icon", () => {
+		const result = createPlayerCharacter(
+			[],
+			id,
+			"Test",
+			10,
+			50,
+			"blue",
+			"banana",
+		);
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("invalid-icon");
+		}
+	});
+
+	it("emits exactly one event on success", () => {
+		const { events } = success([], "Test", 10, 50);
+		expect(events).toHaveLength(1);
+		expect(events[0].type).toBe("PlayerCharacterCreated");
+	});
+});

packages/domain/src/__tests__/delete-player-character.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { deletePlayerCharacter } from "../delete-player-character.js";
+import type { PlayerCharacter } from "../player-character-types.js";
+import { playerCharacterId } from "../player-character-types.js";
+import { isDomainError } from "../types.js";
+
+const id1 = playerCharacterId("pc-1");
+const id2 = playerCharacterId("pc-2");
+
+function makePC(overrides?: Partial<PlayerCharacter>): PlayerCharacter {
+	return {
+		id: id1,
+		name: "Aragorn",
+		ac: 16,
+		maxHp: 120,
+		color: "green",
+		icon: "sword",
+		...overrides,
+	};
+}
+
+describe("deletePlayerCharacter", () => {
+	it("deletes an existing character", () => {
+		const result = deletePlayerCharacter([makePC()], id1);
+		if (isDomainError(result)) throw new Error(result.message);
+		expect(result.characters).toHaveLength(0);
+	});
+
+	it("returns error for not-found id", () => {
+		const result = deletePlayerCharacter([makePC()], id2);
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("player-character-not-found");
+		}
+	});
+
+	it("emits PlayerCharacterDeleted event", () => {
+		const result = deletePlayerCharacter([makePC()], id1);
+		if (isDomainError(result)) throw new Error(result.message);
+		expect(result.events).toHaveLength(1);
+		expect(result.events[0].type).toBe("PlayerCharacterDeleted");
+	});
+
+	it("preserves other characters when deleting one", () => {
+		const pc1 = makePC({ id: id1, name: "Aragorn" });
+		const pc2 = makePC({ id: id2, name: "Legolas" });
+		const result = deletePlayerCharacter([pc1, pc2], id1);
+		if (isDomainError(result)) throw new Error(result.message);
+		expect(result.characters).toHaveLength(1);
+		expect(result.characters[0].name).toBe("Legolas");
+	});
+
+	it("event includes deleted character name", () => {
+		const result = deletePlayerCharacter([makePC()], id1);
+		if (isDomainError(result)) throw new Error(result.message);
+		const event = result.events[0];
+		if (event.type !== "PlayerCharacterDeleted") throw new Error("wrong event");
+		expect(event.name).toBe("Aragorn");
+	});
+});

packages/domain/src/__tests__/edit-player-character.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from "vitest";
+import { editPlayerCharacter } from "../edit-player-character.js";
+import type { PlayerCharacter } from "../player-character-types.js";
+import { playerCharacterId } from "../player-character-types.js";
+import { isDomainError } from "../types.js";
+
+const id = playerCharacterId("pc-1");
+
+function makePC(overrides?: Partial<PlayerCharacter>): PlayerCharacter {
+	return {
+		id,
+		name: "Aragorn",
+		ac: 16,
+		maxHp: 120,
+		color: "green",
+		icon: "sword",
+		...overrides,
+	};
+}
+
+describe("editPlayerCharacter", () => {
+	it("edits name successfully", () => {
+		const result = editPlayerCharacter([makePC()], id, { name: "Strider" });
+		if (isDomainError(result)) throw new Error(result.message);
+		expect(result.characters[0].name).toBe("Strider");
+		expect(result.events[0].type).toBe("PlayerCharacterUpdated");
+	});
+
+	it("edits multiple fields", () => {
+		const result = editPlayerCharacter([makePC()], id, {
+			name: "Strider",
+			ac: 18,
+		});
+		if (isDomainError(result)) throw new Error(result.message);
+		expect(result.characters[0].name).toBe("Strider");
+		expect(result.characters[0].ac).toBe(18);
+	});
+
+	it("returns error for not-found id", () => {
+		const result = editPlayerCharacter(
+			[makePC()],
+			playerCharacterId("pc-999"),
+			{ name: "Nope" },
+		);
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("player-character-not-found");
+		}
+	});
+
+	it("rejects empty name", () => {
+		const result = editPlayerCharacter([makePC()], id, { name: "" });
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("invalid-name");
+		}
+	});
+
+	it("rejects invalid AC", () => {
+		const result = editPlayerCharacter([makePC()], id, { ac: -1 });
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("invalid-ac");
+		}
+	});
+
+	it("rejects invalid maxHp", () => {
+		const result = editPlayerCharacter([makePC()], id, { maxHp: 0 });
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("invalid-max-hp");
+		}
+	});
+
+	it("rejects invalid color", () => {
+		const result = editPlayerCharacter([makePC()], id, { color: "neon" });
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("invalid-color");
+		}
+	});
+
+	it("rejects invalid icon", () => {
+		const result = editPlayerCharacter([makePC()], id, { icon: "banana" });
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("invalid-icon");
+		}
+	});
+
+	it("returns error when no fields changed", () => {
+		const pc = makePC();
+		const result = editPlayerCharacter([pc], id, {
+			name: pc.name,
+			ac: pc.ac,
+		});
+		expect(isDomainError(result)).toBe(true);
+		if (isDomainError(result)) {
+			expect(result.code).toBe("no-changes");
+		}
+	});
+
+	it("emits exactly one event on success", () => {
+		const result = editPlayerCharacter([makePC()], id, { name: "Strider" });
+		if (isDomainError(result)) throw new Error(result.message);
+		expect(result.events).toHaveLength(1);
+	});
+
+	it("event includes old and new name", () => {
+		const result = editPlayerCharacter([makePC()], id, { name: "Strider" });
+		if (isDomainError(result)) throw new Error(result.message);
+		const event = result.events[0];
+		if (event.type !== "PlayerCharacterUpdated") throw new Error("wrong event");
+		expect(event.oldName).toBe("Aragorn");
+		expect(event.newName).toBe("Strider");
+	});
+});

packages/domain/src/__tests__/hp-status.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import { deriveHpStatus } from "../hp-status.js";
+
+describe("deriveHpStatus", () => {
+	it("returns healthy when currentHp >= maxHp / 2", () => {
+		expect(deriveHpStatus(10, 20)).toBe("healthy");
+		expect(deriveHpStatus(15, 20)).toBe("healthy");
+		expect(deriveHpStatus(20, 20)).toBe("healthy");
+	});
+
+	it("returns bloodied when 0 < currentHp < maxHp / 2", () => {
+		expect(deriveHpStatus(9, 20)).toBe("bloodied");
+		expect(deriveHpStatus(1, 20)).toBe("bloodied");
+		expect(deriveHpStatus(5, 20)).toBe("bloodied");
+	});
+
+	it("returns unconscious when currentHp <= 0", () => {
+		expect(deriveHpStatus(0, 20)).toBe("unconscious");
+	});
+
+	it("returns unconscious with negative HP", () => {
+		expect(deriveHpStatus(-5, 20)).toBe("unconscious");
+	});
+
+	it("returns undefined when maxHp is undefined", () => {
+		expect(deriveHpStatus(10, undefined)).toBeUndefined();
+	});
+
+	it("returns undefined when currentHp is undefined", () => {
+		expect(deriveHpStatus(undefined, 20)).toBeUndefined();
+	});
+
+	it("returns undefined when both are undefined", () => {
+		expect(deriveHpStatus(undefined, undefined)).toBeUndefined();
+	});
+
+	it("handles maxHp=1 (no bloodied state possible)", () => {
+		expect(deriveHpStatus(1, 1)).toBe("healthy");
+		expect(deriveHpStatus(0, 1)).toBe("unconscious");
+	});
+
+	it("handles maxHp=2 (1/2 is healthy, not bloodied)", () => {
+		expect(deriveHpStatus(1, 2)).toBe("healthy");
+		expect(deriveHpStatus(0, 2)).toBe("unconscious");
+	});
+
+	it("handles odd maxHp=21 (10 is bloodied since 10 < 10.5)", () => {
+		expect(deriveHpStatus(10, 21)).toBe("bloodied");
+		expect(deriveHpStatus(11, 21)).toBe("healthy");
+	});
+
+	it("returns healthy when currentHp exceeds maxHp", () => {
+		expect(deriveHpStatus(25, 20)).toBe("healthy");
+	});
+});

packages/domain/src/__tests__/initiative.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import {
+	calculateInitiative,
+	formatInitiativeModifier,
+} from "../initiative.js";
+
+describe("calculateInitiative", () => {
+	it("returns positive modifier for creature with expertise (Aboleth: DEX 9, CR 10, proficiency 2)", () => {
+		const result = calculateInitiative({
+			dexScore: 9,
+			cr: "10",
+			initiativeProficiency: 2,
+		});
+		// DEX mod = floor((9-10)/2) = -1, PB for CR 10 = 4, -1 + 2*4 = +7
+		expect(result.modifier).toBe(7);
+		expect(result.passive).toBe(17);
+	});
+
+	it("returns negative modifier for low DEX with no proficiency", () => {
+		const result = calculateInitiative({
+			dexScore: 8,
+			cr: "1",
+			initiativeProficiency: 0,
+		});
+		// DEX mod = floor((8-10)/2) = -1, 0 * PB = 0, -1 + 0 = -1
+		expect(result.modifier).toBe(-1);
+		expect(result.passive).toBe(9);
+	});
+
+	it("returns zero modifier for DEX 10 with no proficiency", () => {
+		const result = calculateInitiative({
+			dexScore: 10,
+			cr: "1",
+			initiativeProficiency: 0,
+		});
+		expect(result.modifier).toBe(0);
+		expect(result.passive).toBe(10);
+	});
+
+	it("adds single proficiency bonus (multiplier 1)", () => {
+		const result = calculateInitiative({
+			dexScore: 14,
+			cr: "5",
+			initiativeProficiency: 1,
+		});
+		// DEX mod = +2, PB for CR 5 = 3, 2 + 1*3 = 5
+		expect(result.modifier).toBe(5);
+		expect(result.passive).toBe(15);
+	});
+
+	it("adds double proficiency bonus (multiplier 2 / expertise)", () => {
+		const result = calculateInitiative({
+			dexScore: 14,
+			cr: "5",
+			initiativeProficiency: 2,
+		});
+		// DEX mod = +2, PB for CR 5 = 3, 2 + 2*3 = 8
+		expect(result.modifier).toBe(8);
+		expect(result.passive).toBe(18);
+	});
+
+	it("handles no proficiency (multiplier 0) — reduces to raw DEX modifier", () => {
+		const result = calculateInitiative({
+			dexScore: 14,
+			cr: "5",
+			initiativeProficiency: 0,
+		});
+		// DEX mod = +2, 0 * PB = 0, 2 + 0 = 2
+		expect(result.modifier).toBe(2);
+		expect(result.passive).toBe(12);
+	});
+
+	it("handles negative result even with proficiency (very low DEX)", () => {
+		const result = calculateInitiative({
+			dexScore: 3,
+			cr: "0",
+			initiativeProficiency: 1,
+		});
+		// DEX mod = floor((3-10)/2) = -4, PB for CR 0 = 2, -4 + 1*2 = -2
+		expect(result.modifier).toBe(-2);
+		expect(result.passive).toBe(8);
+	});
+
+	it("handles fractional CR values", () => {
+		const result = calculateInitiative({
+			dexScore: 12,
+			cr: "1/4",
+			initiativeProficiency: 1,
+		});
+		// DEX mod = +1, PB for CR 1/4 = 2, 1 + 1*2 = 3
+		expect(result.modifier).toBe(3);
+		expect(result.passive).toBe(13);
+	});
+});
+
+describe("formatInitiativeModifier", () => {
+	it("formats positive modifier with plus sign", () => {
+		expect(formatInitiativeModifier(7)).toBe("+7");
+	});
+
+	it("formats negative modifier with U+2212 minus sign", () => {
+		expect(formatInitiativeModifier(-1)).toBe("\u22121");
+	});
+
+	it("formats zero modifier with plus sign", () => {
+		expect(formatInitiativeModifier(0)).toBe("+0");
+	});
+});