Exclude agent plan files from version control

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

.gitignore

@@ -11,3 +11,4 @@ Thumbs.db
 .idea/
 coverage/
 *.tsbuildinfo
+docs/agents/plans/

.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

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,48 @@ 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.
+
+## Self-Review Checklist
+
+Before finishing a change, consider:
+- Is this the simplest approach that solves the current problem?
+- Is there duplication that hurts readability? (But don't abstract prematurely.)
+- Are errors handled correctly and communicated sensibly to the user?
+- Does the UI follow modern patterns and feel intuitive to interact with?
+
+## 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,38 +119,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.x (strict mode, verbatimModuleSyntax) + React 19, Vite 6, Biome 2.0, existing domain/application packages (008-persist-encounter)
-- Browser localStorage (adapter layer only) (008-persist-encounter)
-- TypeScript 5.x (strict mode, verbatimModuleSyntax) + React 19, Vite 6, Biome 2.0, Vites (009-combatant-hp)
-- TypeScript 5.8 (strict mode, verbatimModuleSyntax) + React 19, Vite 6, Tailwind CSS v4, shadcn/ui, Lucide React (icons) (010-ui-baseline)
-- N/A (no storage changes — localStorage persistence unchanged) (010-ui-baseline)
-- TypeScript 5.8 (strict mode, verbatimModuleSyntax) + React 19, Vite 6, Tailwind CSS v4, shadcn/ui-style components, Lucide React (icons) (011-quick-hp-input)
-- N/A (no storage changes -- existing localStorage persistence handles HP via `adjustHpUseCase`) (011-quick-hp-input)
-- N/A (no storage changes -- existing localStorage persistence unchanged) (012-turn-navigation)
-- N/A (no storage changes -- purely derived state, existing localStorage persistence unchanged) (013-hp-status-indicators)
-- TypeScript 5.8 (strict mode, verbatimModuleSyntax) + jscpd (new dev dependency), Lefthook (existing), Biome 2.0 (existing), Knip (existing) (015-add-jscpd-gate)
-- N/A (no storage changes) (015-add-jscpd-gate)
-- Browser localStorage (existing adapter, transparent JSON serialization) (016-combatant-ac)
-- TypeScript 5.8 (strict mode, verbatimModuleSyntax) + React 19, Vite 6, Tailwind CSS v4, Lucide React (icons) (017-combat-conditions)
-- N/A (no storage changes — existing localStorage persistence unchanged) (019-combatant-row-declutter)
-- TypeScript 5.8 (strict mode, verbatimModuleSyntax) + React 19, Tailwind CSS v4, Lucide React (icons) (020-fix-zero-hp-opacity)
-- Browser localStorage (existing adapter, extended for creatureId) (021-bestiary-statblock)
-- TypeScript 5.8 (strict mode, verbatimModuleSyntax) + React 19, Tailwind CSS v4 + React 19, Tailwind CSS v4, Vite 6 (022-fixed-layout-bars)
-- N/A (no storage changes -- purely presentational) (022-fixed-layout-bars)
-- Browser localStorage (existing adapter, updated to handle empty encounters) (023-clear-encounter)
-- N/A (no storage changes — purely presentational fix) (024-fix-hp-popover-overflow)
-- N/A (no storage changes — purely derived from existing bestiary data) (025-display-initiative)
-- TypeScript 5.8 (strict mode, verbatimModuleSyntax) + React 19, Tailwind CSS v4, Lucide React (icons), Vite 6 (026-roll-initiative)
-- N/A (no storage changes — existing localStorage persistence handles initiative via `setInitiativeUseCase`) (026-roll-initiative)
-- N/A (no storage changes — purely presentational) (027-ui-polish)
-- TypeScript 5.8 (strict mode, verbatimModuleSyntax) + React 19, Tailwind CSS v4, Vite 6 + Tailwind CSS v4 (CSS-native `@theme` theming), Lucide React (icons) (028-semantic-hover-tokens)
+- 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

@@ -13,6 +13,7 @@
 		"@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",
@@ -20,9 +21,12 @@
 	},
 	"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

@@ -2,22 +2,83 @@ import {
 	rollAllInitiativeUseCase,
 	rollInitiativeUseCase,
 } from "@initiative/application";
-import type { CombatantId, Creature, CreatureId } from "@initiative/domain";
-import { useCallback, useEffect, useRef, useState } from "react";
+import {
+	type CombatantId,
+	type Creature,
+	type CreatureId,
+	isDomainError,
+} from "@initiative/domain";
+import {
+	useCallback,
+	useEffect,
+	useLayoutEffect,
+	useRef,
+	useState,
+} from "react";
 import { ActionBar } from "./components/action-bar";
+import { BulkImportToasts } from "./components/bulk-import-toasts";
 import { CombatantRow } from "./components/combatant-row";
+import {
+	PlayerCharacterSection,
+	type PlayerCharacterSectionHandle,
+} from "./components/player-character-section";
 import { StatBlockPanel } from "./components/stat-block-panel";
+import { Toast } from "./components/toast";
 import { TurnNavigation } from "./components/turn-navigation";
-import { useBestiary } from "./hooks/use-bestiary";
+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";
+import { useSidePanelState } from "./hooks/use-side-panel-state";
 
 function rollDice(): number {
 	return Math.floor(Math.random() * 20) + 1;
 }
 
+function useActionBarAnimation(combatantCount: number) {
+	const wasEmptyRef = useRef(combatantCount === 0);
+	const [settling, setSettling] = useState(false);
+	const [rising, setRising] = useState(false);
+	const [topBarExiting, setTopBarExiting] = useState(false);
+
+	useLayoutEffect(() => {
+		const nowEmpty = combatantCount === 0;
+		if (wasEmptyRef.current && !nowEmpty) {
+			setSettling(true);
+		} else if (!wasEmptyRef.current && nowEmpty) {
+			setRising(true);
+			setTopBarExiting(true);
+		}
+		wasEmptyRef.current = nowEmpty;
+	}, [combatantCount]);
+
+	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;
+
+	return {
+		risingClass,
+		settlingClass,
+		topBarClass,
+		showTopBar,
+		onSettleEnd: () => setSettling(false),
+		onRiseEnd: () => setRising(false),
+		onTopBarExitEnd: () => setTopBarExiting(false),
+	};
+}
+
 export function App() {
 	const {
 		encounter,
+		isEmpty,
+		hasCreatureCombatants,
+		canRollAllInitiative,
 		advanceTurn,
 		retreatTurn,
 		addCombatant,
@@ -31,45 +92,52 @@ export function App() {
 		toggleCondition,
 		toggleConcentration,
 		addFromBestiary,
+		addFromPlayerCharacter,
 		makeStore,
 	} = useEncounter();
 
-	const { search, getCreature, isLoaded } = useBestiary();
+	const {
+		characters: playerCharacters,
+		createCharacter: createPlayerCharacter,
+		editCharacter: editPlayerCharacter,
+		deleteCharacter: deletePlayerCharacter,
+	} = usePlayerCharacters();
 
-	const [selectedCreature, setSelectedCreature] = useState<Creature | null>(
-		null,
-	);
-	const [suggestions, setSuggestions] = useState<Creature[]>([]);
+	const {
+		search,
+		getCreature,
+		isLoaded,
+		isSourceCached,
+		fetchAndCacheSource,
+		uploadAndCacheSource,
+		refreshCache,
+	} = useBestiary();
+
+	const bulkImport = useBulkImport();
+	const sidePanel = useSidePanelState();
+
+	const [rollSkippedCount, setRollSkippedCount] = useState(0);
+
+	const selectedCreature: Creature | null = sidePanel.selectedCreatureId
+		? (getCreature(sidePanel.selectedCreatureId) ?? null)
+		: null;
+
+	const pinnedCreature: Creature | null = sidePanel.pinnedCreatureId
+		? (getCreature(sidePanel.pinnedCreatureId) ?? null)
+		: null;
 
 	const handleAddFromBestiary = useCallback(
-		(creature: Creature) => {
-			addFromBestiary(creature);
-			setSelectedCreature(creature);
+		(result: SearchResult) => {
+			addFromBestiary(result);
 		},
 		[addFromBestiary],
 	);
 
-	const handleShowStatBlock = useCallback((creature: Creature) => {
-		setSelectedCreature(creature);
-	}, []);
-
 	const handleCombatantStatBlock = useCallback(
 		(creatureId: string) => {
-			const creature = getCreature(creatureId as CreatureId);
-			if (creature) setSelectedCreature(creature);
+			sidePanel.showCreature(creatureId as CreatureId);
 		},
-		[getCreature],
-	);
-
-	const handleSearchChange = useCallback(
-		(query: string) => {
-			if (!isLoaded || query.length < 2) {
-				setSuggestions([]);
-				return;
-			}
-			setSuggestions(search(query));
-		},
-		[isLoaded, search],
+		[sidePanel.showCreature],
 	);
 
 	const handleRollInitiative = useCallback(
@@ -80,9 +148,45 @@ export function App() {
 	);
 
 	const handleRollAllInitiative = useCallback(() => {
-		rollAllInitiativeUseCase(makeStore(), rollDice, getCreature);
+		const result = rollAllInitiativeUseCase(makeStore(), rollDice, getCreature);
+		if (!isDomainError(result) && result.skippedNoSource > 0) {
+			setRollSkippedCount(result.skippedNoSource);
+		}
 	}, [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;
+			sidePanel.showCreature(cId);
+		},
+		[sidePanel.showCreature],
+	);
+
+	const handleStartBulkImport = useCallback(
+		(baseUrl: string) => {
+			bulkImport.startImport(
+				baseUrl,
+				fetchAndCacheSource,
+				isSourceCached,
+				refreshCache,
+			);
+		},
+		[bulkImport.startImport, fetchAndCacheSource, isSourceCached, refreshCache],
+	);
+
+	const handleBulkImportDone = useCallback(() => {
+		sidePanel.dismissPanel();
+		bulkImport.reset();
+	}, [sidePanel.dismissPanel, bulkImport.reset]);
+
+	const actionBarInputRef = useRef<HTMLInputElement>(null);
+	const playerCharacterRef = useRef<PlayerCharacterSectionHandle>(null);
+	const actionBarAnim = useActionBarAnimation(encounter.combatants.length);
+
 	// Auto-scroll to the active combatant when the turn changes
 	const activeRowRef = useRef<HTMLDivElement>(null);
 	useEffect(() => {
@@ -102,33 +206,66 @@ export function App() {
 		if (!window.matchMedia("(min-width: 1024px)").matches) return;
 		const active = encounter.combatants[encounter.activeIndex];
 		if (!active?.creatureId || !isLoaded) return;
-		const creature = getCreature(active.creatureId as CreatureId);
-		if (creature) setSelectedCreature(creature);
-	}, [encounter.activeIndex, encounter.combatants, getCreature, isLoaded]);
+		sidePanel.showCreature(active.creatureId as CreatureId);
+	}, [
+		encounter.activeIndex,
+		encounter.combatants,
+		isLoaded,
+		sidePanel.showCreature,
+	]);
 
 	return (
 		<div className="flex h-screen flex-col">
-			<div className="mx-auto flex w-full max-w-2xl flex-1 flex-col gap-3 px-4 min-h-0">
-				{/* Turn Navigation — fixed at top */}
-				<div className="shrink-0 pt-8">
+			<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}
-						onRollAllInitiative={handleRollAllInitiative}
 						/>
 					</div>
+				)}
 
+				{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={sidePanel.showBulkImport}
+								bulkImportDisabled={bulkImport.state.status === "loading"}
+								inputRef={actionBarInputRef}
+								playerCharacters={playerCharacters}
+								onAddFromPlayerCharacter={addFromPlayerCharacter}
+								onManagePlayers={() =>
+									playerCharacterRef.current?.openManagement()
+								}
+								onRollAllInitiative={handleRollAllInitiative}
+								showRollAllInitiative={hasCreatureCombatants}
+								rollAllInitiativeDisabled={!canRollAllInitiative}
+								onOpenSourceManager={sidePanel.showSourceManager}
+								autoFocus
+							/>
+						</div>
+					</div>
+				) : (
+					<>
 						{/* Scrollable area — combatant list */}
 						<div className="flex-1 overflow-y-auto min-h-0">
-					<div className="flex flex-col pb-2">
-						{encounter.combatants.length === 0 ? (
-							<p className="py-12 text-center text-sm text-muted-foreground">
-								No combatants yet — add one to get started
-							</p>
-						) : (
-							encounter.combatants.map((c, i) => (
+							<div className="flex flex-col px-2 py-2">
+								{encounter.combatants.map((c, i) => (
 									<CombatantRow
 										key={c.id}
 										ref={i === encounter.activeIndex ? activeRowRef : null}
@@ -151,29 +288,102 @@ export function App() {
 											c.creatureId ? handleRollInitiative : undefined
 										}
 									/>
-							))
-						)}
+								))}
 							</div>
 						</div>
 
 						{/* Action Bar — fixed at bottom */}
-				<div className="shrink-0 pb-8">
+						<div
+							className={`shrink-0 pb-8${actionBarAnim.settlingClass}`}
+							onAnimationEnd={actionBarAnim.onSettleEnd}
+						>
 							<ActionBar
 								onAddCombatant={addCombatant}
 								onAddFromBestiary={handleAddFromBestiary}
 								bestiarySearch={search}
 								bestiaryLoaded={isLoaded}
-						suggestions={suggestions}
-						onSearchChange={handleSearchChange}
-						onShowStatBlock={handleShowStatBlock}
+								onViewStatBlock={handleViewStatBlock}
+								onBulkImport={sidePanel.showBulkImport}
+								bulkImportDisabled={bulkImport.state.status === "loading"}
+								inputRef={actionBarInputRef}
+								playerCharacters={playerCharacters}
+								onAddFromPlayerCharacter={addFromPlayerCharacter}
+								onManagePlayers={() =>
+									playerCharacterRef.current?.openManagement()
+								}
+								onRollAllInitiative={handleRollAllInitiative}
+								showRollAllInitiative={hasCreatureCombatants}
+								rollAllInitiativeDisabled={!canRollAllInitiative}
+								onOpenSourceManager={sidePanel.showSourceManager}
 							/>
 						</div>
+					</>
+				)}
 			</div>
 
-			{/* Stat Block Panel */}
+			{/* Pinned Stat Block Panel (left) */}
+			{sidePanel.pinnedCreatureId && sidePanel.isWideDesktop && (
 				<StatBlockPanel
+					creatureId={sidePanel.pinnedCreatureId}
+					creature={pinnedCreature}
+					isSourceCached={isSourceCached}
+					fetchAndCacheSource={fetchAndCacheSource}
+					uploadAndCacheSource={uploadAndCacheSource}
+					refreshCache={refreshCache}
+					panelRole="pinned"
+					isCollapsed={false}
+					onToggleCollapse={() => {}}
+					onPin={() => {}}
+					onUnpin={sidePanel.unpin}
+					showPinButton={false}
+					side="left"
+					onDismiss={() => {}}
+				/>
+			)}
+
+			{/* Browse Stat Block Panel (right) */}
+			<StatBlockPanel
+				creatureId={sidePanel.selectedCreatureId}
 				creature={selectedCreature}
-				onClose={() => setSelectedCreature(null)}
+				isSourceCached={isSourceCached}
+				fetchAndCacheSource={fetchAndCacheSource}
+				uploadAndCacheSource={uploadAndCacheSource}
+				refreshCache={refreshCache}
+				panelRole="browse"
+				isCollapsed={sidePanel.isRightPanelCollapsed}
+				onToggleCollapse={sidePanel.toggleCollapse}
+				onPin={sidePanel.togglePin}
+				onUnpin={() => {}}
+				showPinButton={sidePanel.isWideDesktop && !!selectedCreature}
+				side="right"
+				onDismiss={sidePanel.dismissPanel}
+				bulkImportMode={sidePanel.bulkImportMode}
+				bulkImportState={bulkImport.state}
+				onStartBulkImport={handleStartBulkImport}
+				onBulkImportDone={handleBulkImportDone}
+				sourceManagerMode={sidePanel.sourceManagerMode}
+			/>
+
+			<BulkImportToasts
+				state={bulkImport.state}
+				visible={!sidePanel.bulkImportMode || sidePanel.isRightPanelCollapsed}
+				onReset={bulkImport.reset}
+			/>
+
+			{rollSkippedCount > 0 && (
+				<Toast
+					message={`${rollSkippedCount} skipped — bestiary source not loaded`}
+					onDismiss={() => setRollSkippedCount(0)}
+					autoDismissMs={4000}
+				/>
+			)}
+
+			<PlayerCharacterSection
+				ref={playerCharacterRef}
+				characters={playerCharacters}
+				onCreateCharacter={createPlayerCharacter}
+				onEditCharacter={editPlayerCharacter}
+				onDeleteCharacter={deletePlayerCharacter}
 			/>
 		</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-collapse-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";
+	isCollapsed?: boolean;
+	onToggleCollapse?: () => 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,
+		isCollapsed: false,
+		onToggleCollapse: 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 Collapse/Expand and Pin", () => {
+	beforeEach(() => {
+		mockMatchMedia(true); // desktop by default
+	});
+
+	afterEach(cleanup);
+
+	describe("US1: Collapse and Expand", () => {
+		it("shows collapse button instead of close button on desktop", () => {
+			renderPanel();
+			expect(
+				screen.getByRole("button", { name: "Collapse 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 collapsed tab with creature name when isCollapsed is true", () => {
+			renderPanel({ isCollapsed: true });
+			expect(screen.getByText("Goblin")).toBeInTheDocument();
+			expect(
+				screen.getByRole("button", { name: "Expand stat block panel" }),
+			).toBeInTheDocument();
+		});
+
+		it("calls onToggleCollapse when collapse button is clicked", () => {
+			const props = renderPanel();
+			fireEvent.click(
+				screen.getByRole("button", { name: "Collapse stat block panel" }),
+			);
+			expect(props.onToggleCollapse).toHaveBeenCalledTimes(1);
+		});
+
+		it("calls onToggleCollapse when collapsed tab is clicked", () => {
+			const props = renderPanel({ isCollapsed: true });
+			fireEvent.click(
+				screen.getByRole("button", { name: "Expand stat block panel" }),
+			);
+			expect(props.onToggleCollapse).toHaveBeenCalledTimes(1);
+		});
+
+		it("applies translate-x class when collapsed (right side)", () => {
+			renderPanel({ isCollapsed: true, side: "right" });
+			const panel = screen
+				.getByRole("button", { name: "Expand stat block panel" })
+				.closest("div");
+			expect(panel?.className).toContain("translate-x-[calc(100%-40px)]");
+		});
+
+		it("applies translate-x-0 when expanded", () => {
+			renderPanel({ isCollapsed: false });
+			const foldBtn = screen.getByRole("button", {
+				name: "Collapse 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 collapse button instead of X close button on mobile drawer", () => {
+			renderPanel();
+			expect(
+				screen.getByRole("button", { name: "Collapse stat block panel" }),
+			).toBeInTheDocument();
+			// No X close icon button — only backdrop dismiss and collapse 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"
+					isCollapsed={false}
+					onToggleCollapse={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: "Collapse 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: Collapse independence with pinned panel", () => {
+		it("pinned panel has no collapse button", () => {
+			renderPanel({ panelRole: "pinned", side: "left" });
+			expect(
+				screen.queryByRole("button", { name: /collapse/i }),
+			).not.toBeInTheDocument();
+		});
+
+		it("pinned panel is always expanded (no translate offset)", () => {
+			renderPanel({ panelRole: "pinned", side: "left", isCollapsed: 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

@@ -1,5 +1,12 @@
-import { describe, expect, it } from "vitest";
-import { normalizeBestiary } from "../bestiary-adapter.js";
+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", () => {

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

@@ -1,16 +0,0 @@
-import { expect, it } from "vitest";
-import rawData from "../../../../../data/bestiary/xmm.json";
-import { normalizeBestiary } from "../bestiary-adapter.js";
-
-it("normalizes all 503 monsters without error", () => {
-	const creatures = normalizeBestiary(
-		rawData as unknown as Parameters<typeof normalizeBestiary>[0],
-	);
-	expect(creatures.length).toBe(503);
-	for (const c of creatures) {
-		expect(c.name).toBeTruthy();
-		expect(c.id).toBeTruthy();
-		expect(c.ac).toBeGreaterThanOrEqual(0);
-		expect(c.hp.average).toBeGreaterThan(0);
-	}
-});

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

@@ -17,8 +17,8 @@ interface RawMonster {
 	size: string[];
 	type: string | { type: string; tags?: string[]; swarmSize?: string };
 	alignment?: string[];
-	ac: (number | { ac: number; from?: string[] })[];
-	hp: { average: number; formula: 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
@@ -38,7 +38,7 @@ interface RawMonster {
 	vulnerable?: (string | { special: string })[];
 	conditionImmune?: string[];
 	languages?: string[];
-	cr: string | { cr: string };
+	cr?: string | { cr: string };
 	trait?: RawEntry[];
 	action?: RawEntry[];
 	bonus?: RawEntry[];
@@ -81,9 +81,11 @@ interface RawSpellcasting {
 
 // --- Source mapping ---
 
-const SOURCE_DISPLAY_NAMES: Record<string, string> = {
-	XMM: "MM 2024",
-};
+let sourceDisplayNames: Record<string, string> = {};
+
+export function setSourceDisplayNames(names: Record<string, string>): void {
+	sourceDisplayNames = names;
+}
 
 // --- Size mapping ---
 
@@ -138,7 +140,12 @@ function formatType(
 
 	let result = baseType;
 	if (type.tags && type.tags.length > 0) {
-		result += ` (${type.tags.map(capitalize).join(", ")})`;
+		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;
@@ -159,6 +166,14 @@ function extractAc(ac: RawMonster["ac"]): {
 	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,
@@ -239,20 +254,21 @@ function formatConditionImmunities(
 		.join(", ");
 }
 
-function renderEntries(entries: (string | RawEntryObject)[]): string {
-	const parts: string[] = [];
-	for (const entry of entries) {
-		if (typeof entry === "string") {
-			parts.push(stripTags(entry));
-		} else if (entry.type === "list") {
-			for (const item of entry.items ?? []) {
+function renderListItem(item: string | RawEntryObject): string | undefined {
 	if (typeof item === "string") {
-					parts.push(`• ${stripTags(item)}`);
-				} else if (item.name && item.entries) {
-					parts.push(
-						`• ${stripTags(item.name)}: ${renderEntries(item.entries)}`,
-					);
+		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)}`);
@@ -260,6 +276,16 @@ function renderEntries(entries: (string | RawEntryObject)[]): string {
 		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(" ");
 }
 
@@ -337,7 +363,8 @@ function normalizeLegendary(
 	};
 }
 
-function extractCr(cr: string | { cr: string }): string {
+function extractCr(cr: string | { cr: string } | undefined): string {
+	if (cr === undefined) return "—";
 	return typeof cr === "string" ? cr : cr.cr;
 }
 
@@ -353,7 +380,32 @@ function makeCreatureId(source: string, name: string): CreatureId {
  * Normalizes raw 5etools bestiary JSON into domain Creature[].
  */
 export function normalizeBestiary(raw: { monster: RawMonster[] }): Creature[] {
-	return raw.monster.map((m) => {
+	// 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);
 
@@ -361,13 +413,16 @@ export function normalizeBestiary(raw: { monster: RawMonster[] }): Creature[] {
 		id: makeCreatureId(m.source, m.name),
 		name: m.name,
 		source: m.source,
-			sourceDisplayName: SOURCE_DISPLAY_NAMES[m.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, formula: m.hp.formula },
+		hp: {
+			average: m.hp.average ?? 0,
+			formula: m.hp.formula ?? m.hp.special ?? "",
+		},
 		speed: formatSpeed(m.speed),
 		abilities: {
 			str: m.str,
@@ -402,5 +457,4 @@ export function normalizeBestiary(raw: { monster: RawMonster[] }): Creature[] {
 		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

@@ -20,6 +20,7 @@ const ATKR_MAP: Record<string, string> = {
  * 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;
 

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/action-bar.tsx

@@ -1,18 +1,257 @@
-import type { Creature } from "@initiative/domain";
-import { Search } from "lucide-react";
-import { type FormEvent, useState } from "react";
-import { BestiarySearch } from "./bestiary-search.js";
+import type { PlayerCharacter, PlayerIcon } from "@initiative/domain";
+import {
+	Check,
+	Eye,
+	EyeOff,
+	Import,
+	Library,
+	Minus,
+	Plus,
+	Users,
+} from "lucide-react";
+import {
+	type FormEvent,
+	type RefObject,
+	useDeferredValue,
+	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) => void;
-	onAddFromBestiary: (creature: Creature) => void;
-	bestiarySearch: (query: string) => Creature[];
+	onAddCombatant: (
+		name: string,
+		opts?: { initiative?: number; ac?: number; maxHp?: number },
+	) => void;
+	onAddFromBestiary: (result: SearchResult) => void;
+	bestiarySearch: (query: string) => SearchResult[];
 	bestiaryLoaded: boolean;
-	suggestions: Creature[];
-	onSearchChange: (query: string) => void;
-	onShowStatBlock?: (creature: Creature) => void;
+	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;
+	rollAllInitiativeDisabled?: 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,
+	onClear,
+}: {
+	nameInput: string;
+	suggestions: SearchResult[];
+	pcMatches: PlayerCharacter[];
+	suggestionIndex: number;
+	queued: QueuedCreature | null;
+	onDismiss: () => void;
+	onClear: () => 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 = pc.icon
+									? PLAYER_ICON_MAP[pc.icon as PlayerIcon]
+									: undefined;
+								const pcColor = pc.color
+									? PLAYER_COLOR_HEX[pc.color as keyof typeof PLAYER_COLOR_HEX]
+									: undefined;
+								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);
+												onClear();
+											}}
+										>
+											{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: "Import All Sources",
+			onClick: opts.onBulkImport,
+			disabled: opts.bulkImportDisabled,
+		});
+	}
+	return items;
 }
 
 export function ActionBar({
@@ -20,46 +259,175 @@ export function ActionBar({
 	onAddFromBestiary,
 	bestiarySearch,
 	bestiaryLoaded,
-	suggestions,
-	onSearchChange,
-	onShowStatBlock,
+	onViewStatBlock,
+	onBulkImport,
+	bulkImportDisabled,
+	inputRef,
+	playerCharacters,
+	onAddFromPlayerCharacter,
+	onManagePlayers,
+	onRollAllInitiative,
+	showRollAllInitiative,
+	rollAllInitiativeDisabled,
+	onOpenSourceManager,
+	autoFocus,
 }: ActionBarProps) {
 	const [nameInput, setNameInput] = useState("");
-	const [searchOpen, setSearchOpen] = useState(false);
+	const [suggestions, setSuggestions] = useState<SearchResult[]>([]);
+	const [pcMatches, setPcMatches] = useState<PlayerCharacter[]>([]);
+	const deferredSuggestions = useDeferredValue(suggestions);
+	const deferredPcMatches = useDeferredValue(pcMatches);
 	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;
-		onAddCombatant(nameInput);
+		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("");
-		onSearchChange("");
+		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);
-		onSearchChange(value);
+		if (browseMode) {
+			handleBrowseSearch(value);
+		} else {
+			handleAddSearch(value);
+		}
 	};
 
-	const handleSelectCreature = (creature: Creature) => {
-		onAddFromBestiary(creature);
-		setSearchOpen(false);
-		setNameInput("");
-		onSearchChange("");
-		onShowStatBlock?.(creature);
+	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 handleSelectSuggestion = (creature: Creature) => {
-		onAddFromBestiary(creature);
-		setNameInput("");
-		onSearchChange("");
-		onShowStatBlock?.(creature);
+	const handleEnter = () => {
+		if (queued) {
+			confirmQueued();
+		} else if (suggestionIndex >= 0) {
+			handleClickSuggestion(suggestions[suggestionIndex]);
+		}
 	};
 
+	const hasSuggestions =
+		deferredSuggestions.length > 0 || deferredPcMatches.length > 0;
+
 	const handleKeyDown = (e: React.KeyboardEvent) => {
-		if (suggestions.length === 0) return;
+		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));
@@ -68,40 +436,78 @@ export function ActionBar({
 			setSuggestionIndex((i) => (i > 0 ? i - 1 : suggestions.length - 1));
 		} else if (e.key === "Enter" && suggestionIndex >= 0) {
 			e.preventDefault();
-			handleSelectSuggestion(suggestions[suggestionIndex]);
-		} else if (e.key === "Escape") {
-			setSuggestionIndex(-1);
-			onSearchChange("");
+			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">
-			{searchOpen ? (
-				<BestiarySearch
-					onSelectCreature={handleSelectCreature}
-					onClose={() => setSearchOpen(false)}
-					searchFn={bestiarySearch}
-				/>
-			) : (
 			<form
 				onSubmit={handleAdd}
 				className="relative flex flex-1 items-center gap-2"
 			>
-					<div className="relative flex-1">
+				<div className="flex-1">
+					<div className="relative max-w-xs">
 						<Input
+							ref={inputRef}
 							type="text"
 							value={nameInput}
 							onChange={(e) => handleNameChange(e.target.value)}
-							onKeyDown={handleKeyDown}
-							placeholder="Combatant name"
-							className="max-w-xs"
+							onKeyDown={browseMode ? handleBrowseKeyDown : handleKeyDown}
+							placeholder={
+								browseMode ? "Search stat blocks..." : "+ Add combatants"
+							}
+							className="pr-8"
+							autoFocus={autoFocus}
 						/>
-						{suggestions.length > 0 && (
-							<div className="absolute bottom-full z-50 mb-1 w-full max-w-xs rounded-md border border-border bg-card shadow-lg">
+						{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 && deferredSuggestions.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((creature, i) => (
-										<li key={creature.id}>
+									{deferredSuggestions.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 ${
@@ -109,12 +515,13 @@ export function ActionBar({
 														? "bg-accent/20 text-foreground"
 														: "text-foreground hover:bg-hover-neutral-bg"
 												}`}
-												onClick={() => handleSelectSuggestion(creature)}
+												onMouseDown={(e) => e.preventDefault()}
+												onClick={() => handleBrowseSelect(result)}
 												onMouseEnter={() => setSuggestionIndex(i)}
 											>
-												<span>{creature.name}</span>
+												<span>{result.name}</span>
 												<span className="text-xs text-muted-foreground">
-													{creature.sourceDisplayName}
+													{result.sourceDisplayName}
 												</span>
 											</button>
 										</li>
@@ -122,22 +529,71 @@ export function ActionBar({
 								</ul>
 							</div>
 						)}
+						{!browseMode && hasSuggestions && (
+							<AddModeSuggestions
+								nameInput={nameInput}
+								suggestions={deferredSuggestions}
+								pcMatches={deferredPcMatches}
+								suggestionIndex={suggestionIndex}
+								queued={queued}
+								onDismiss={dismissSuggestions}
+								onClear={clearInput}
+								onClickSuggestion={handleClickSuggestion}
+								onSetSuggestionIndex={setSuggestionIndex}
+								onSetQueued={setQueued}
+								onConfirmQueued={confirmQueued}
+								onAddFromPlayerCharacter={onAddFromPlayerCharacter}
+							/>
+						)}
 					</div>
-					<Button type="submit" size="sm">
-						Add
-					</Button>
-					{bestiaryLoaded && (
+				</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="sm"
+						size="icon"
 						variant="ghost"
-							onClick={() => setSearchOpen(true)}
+						className="text-muted-foreground hover:text-hover-action"
+						onClick={onRollAllInitiative}
+						disabled={rollAllInitiativeDisabled}
+						title="Roll all initiative"
+						aria-label="Roll all initiative"
 					>
-							<Search className="h-4 w-4" />
+						<D20Icon className="h-6 w-6" />
 					</Button>
 				)}
+				{overflowItems.length > 0 && <OverflowMenu items={overflowItems} />}
 			</form>
-			)}
 		</div>
 	);
 }

apps/web/src/components/bestiary-search.tsx

@@ -1,129 +0,0 @@
-import type { Creature } from "@initiative/domain";
-import { Search, X } from "lucide-react";
-import {
-	type KeyboardEvent,
-	useCallback,
-	useEffect,
-	useRef,
-	useState,
-} from "react";
-import { Input } from "./ui/input.js";
-
-interface BestiarySearchProps {
-	onSelectCreature: (creature: Creature) => void;
-	onClose: () => void;
-	searchFn: (query: string) => Creature[];
-}
-
-export function BestiarySearch({
-	onSelectCreature,
-	onClose,
-	searchFn,
-}: BestiarySearchProps) {
-	const [query, setQuery] = useState("");
-	const [highlightIndex, setHighlightIndex] = useState(-1);
-	const inputRef = useRef<HTMLInputElement>(null);
-	const containerRef = useRef<HTMLDivElement>(null);
-	const results = query.length >= 2 ? searchFn(query) : [];
-
-	useEffect(() => {
-		inputRef.current?.focus();
-	}, []);
-
-	useEffect(() => {
-		setHighlightIndex(-1);
-	}, [query]);
-
-	useEffect(() => {
-		function handleClickOutside(e: MouseEvent) {
-			if (
-				containerRef.current &&
-				!containerRef.current.contains(e.target as Node)
-			) {
-				onClose();
-			}
-		}
-		document.addEventListener("mousedown", handleClickOutside);
-		return () => document.removeEventListener("mousedown", handleClickOutside);
-	}, [onClose]);
-
-	const handleKeyDown = useCallback(
-		(e: KeyboardEvent) => {
-			if (e.key === "Escape") {
-				onClose();
-				return;
-			}
-			if (e.key === "ArrowDown") {
-				e.preventDefault();
-				setHighlightIndex((i) => (i < results.length - 1 ? i + 1 : 0));
-				return;
-			}
-			if (e.key === "ArrowUp") {
-				e.preventDefault();
-				setHighlightIndex((i) => (i > 0 ? i - 1 : results.length - 1));
-				return;
-			}
-			if (e.key === "Enter" && highlightIndex >= 0) {
-				e.preventDefault();
-				onSelectCreature(results[highlightIndex]);
-			}
-		},
-		[results, highlightIndex, onClose, onSelectCreature],
-	);
-
-	return (
-		<div ref={containerRef} className="relative w-full max-w-sm">
-			<div className="flex items-center gap-2">
-				<Search className="h-4 w-4 text-muted-foreground" />
-				<Input
-					ref={inputRef}
-					type="text"
-					value={query}
-					onChange={(e) => setQuery(e.target.value)}
-					onKeyDown={handleKeyDown}
-					placeholder="Search bestiary..."
-					className="flex-1"
-				/>
-				<button
-					type="button"
-					onClick={onClose}
-					className="text-muted-foreground hover:text-hover-neutral"
-				>
-					<X className="h-4 w-4" />
-				</button>
-			</div>
-
-			{query.length >= 2 && (
-				<div className="absolute bottom-full z-50 mb-1 w-full rounded-md border border-border bg-card shadow-lg">
-					{results.length === 0 ? (
-						<div className="px-3 py-2 text-sm text-muted-foreground">
-							No creatures found
-						</div>
-					) : (
-						<ul className="max-h-60 overflow-y-auto py-1">
-							{results.map((creature, i) => (
-								<li key={creature.id}>
-									<button
-										type="button"
-										className={`flex w-full items-center justify-between px-3 py-1.5 text-left text-sm ${
-											i === highlightIndex
-												? "bg-accent/20 text-foreground"
-												: "text-foreground hover:bg-hover-neutral-bg"
-										}`}
-										onClick={() => onSelectCreature(creature)}
-										onMouseEnter={() => setHighlightIndex(i)}
-									>
-										<span>{creature.name}</span>
-										<span className="text-xs text-muted-foreground">
-											{creature.sourceDisplayName}
-										</span>
-									</button>
-								</li>
-							))}
-						</ul>
-					)}
-				</div>
-			)}
-		</div>
-	);
-}

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

@@ -0,0 +1,106 @@
+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">
+					Import All Sources
+				</h3>
+				<p className="mt-1 text-xs text-muted-foreground">
+					Load stat block data for all {totalSources} sources at once.
+				</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/bulk-import-toasts.tsx

@@ -0,0 +1,49 @@
+import type { BulkImportState } from "../hooks/use-bulk-import.js";
+import { Toast } from "./toast.js";
+
+interface BulkImportToastsProps {
+	state: BulkImportState;
+	visible: boolean;
+	onReset: () => void;
+}
+
+export function BulkImportToasts({
+	state,
+	visible,
+	onReset,
+}: BulkImportToastsProps) {
+	if (!visible) return null;
+
+	if (state.status === "loading") {
+		return (
+			<Toast
+				message={`Loading sources... ${state.completed + state.failed}/${state.total}`}
+				progress={
+					state.total > 0 ? (state.completed + state.failed) / state.total : 0
+				}
+				onDismiss={() => {}}
+			/>
+		);
+	}
+
+	if (state.status === "complete") {
+		return (
+			<Toast
+				message="All sources loaded"
+				onDismiss={onReset}
+				autoDismissMs={3000}
+			/>
+		);
+	}
+
+	if (state.status === "partial-failure") {
+		return (
+			<Toast
+				message={`Loaded ${state.completed}/${state.total} sources (${state.failed} failed)`}
+				onDismiss={onReset}
+			/>
+		);
+	}
+
+	return null;
+}

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(value === color ? "" : 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

@@ -2,6 +2,7 @@ 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";
@@ -11,7 +12,8 @@ import { ConditionPicker } from "./condition-picker";
 import { ConditionTags } from "./condition-tags";
 import { D20Icon } from "./d20-icon";
 import { HpAdjustPopover } from "./hp-adjust-popover";
-import { Button } from "./ui/button";
+import { PLAYER_COLOR_HEX, PLAYER_ICON_MAP } from "./player-icon-map";
+import { ConfirmButton } from "./ui/confirm-button";
 import { Input } from "./ui/input";
 
 interface Combatant {
@@ -23,6 +25,8 @@ interface Combatant {
 	readonly ac?: number;
 	readonly conditions?: readonly ConditionId[];
 	readonly isConcentrating?: boolean;
+	readonly color?: string;
+	readonly icon?: string;
 }
 
 interface CombatantRowProps {
@@ -44,14 +48,21 @@ 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();
@@ -67,6 +78,46 @@ function EditableName({
 		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
@@ -85,16 +136,20 @@ function EditableName({
 	}
 
 	return (
+		<>
 			<button
 				type="button"
-			onClick={(e) => {
-				e.stopPropagation();
-				startEditing();
-			}}
-			className="truncate text-left text-sm text-foreground hover:text-hover-neutral transition-colors"
+				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>
+		</>
 	);
 }
 
@@ -354,6 +409,35 @@ function InitiativeDisplay({
 	);
 }
 
+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,
@@ -401,22 +485,26 @@ export function CombatantRow({
 		}
 	}, [combatant.isConcentrating]);
 
+	const pcColor = combatant.color
+		? PLAYER_COLOR_HEX[combatant.color as keyof typeof PLAYER_COLOR_HEX]
+		: undefined;
+
 	return (
-		/* biome-ignore lint/a11y/useKeyWithClickEvents: row click opens stat block */
-		/* biome-ignore lint/a11y/noStaticElementInteractions: row click opens stat block */
+		/* 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",
-				isActive
-					? "border-l-2 border-l-accent bg-accent/10"
-					: combatant.isConcentrating
-						? "border-l-2 border-l-purple-400"
-						: "border-l-2 border-l-transparent",
+				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 */}
@@ -430,20 +518,18 @@ export function CombatantRow({
 					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",
-						combatant.isConcentrating
-							? dimmed
-								? "opacity-50 text-purple-400"
-								: "opacity-100 text-purple-400"
-							: "opacity-0 group-hover:opacity-50 text-muted-foreground",
+						concentrationIconClass(combatant.isConcentrating, dimmed),
 					)}
 				>
 					<Brain size={16} />
 				</button>
 
 				{/* Initiative */}
-				{/* biome-ignore lint/a11y/useKeyWithClickEvents: stopPropagation wrapper */}
-				{/* biome-ignore lint/a11y/noStaticElementInteractions: stopPropagation wrapper */}
-				<div onClick={(e) => e.stopPropagation()}>
+				{/* biome-ignore lint/a11y/noStaticElementInteractions: stopPropagation wrapper for interactive children */}
+				<div
+					onClick={(e) => e.stopPropagation()}
+					onKeyDown={(e) => e.stopPropagation()}
+				>
 					<InitiativeDisplay
 						initiative={initiative}
 						combatantId={id}
@@ -460,9 +546,29 @@ export function CombatantRow({
 						dimmed && "opacity-50",
 					)}
 				>
-					<span className="min-w-0 truncate">
-						<EditableName name={name} combatantId={id} onRename={onRename} />
-					</span>
+					{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)}
@@ -478,21 +584,21 @@ export function CombatantRow({
 				</div>
 
 				{/* AC */}
-				{/* biome-ignore lint/a11y/useKeyWithClickEvents: stopPropagation wrapper */}
-				{/* biome-ignore lint/a11y/noStaticElementInteractions: stopPropagation wrapper */}
+				{/* 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/useKeyWithClickEvents: stopPropagation wrapper */}
-				{/* biome-ignore lint/a11y/noStaticElementInteractions: stopPropagation wrapper */}
+				{/* 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}
@@ -516,19 +622,12 @@ export function CombatantRow({
 				</div>
 
 				{/* Actions */}
-				<Button
-					variant="ghost"
-					size="icon"
-					className="h-7 w-7 text-muted-foreground hover:text-hover-destructive opacity-0 pointer-events-none group-hover:opacity-100 group-hover:pointer-events-auto focus:opacity-100 focus:pointer-events-auto transition-opacity"
-					onClick={(e) => {
-						e.stopPropagation();
-						onRemove(id);
-					}}
-					title="Remove combatant"
-					aria-label="Remove combatant"
-				>
-					<X size={16} />
-				</Button>
+				<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

@@ -64,12 +64,21 @@ export function ConditionPicker({
 }: 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();
-		setFlipped(rect.bottom > window.innerHeight);
+		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(() => {
@@ -88,9 +97,10 @@ export function ConditionPicker({
 		<div
 			ref={ref}
 			className={cn(
-				"absolute z-10 w-fit rounded-md border border-border bg-background p-1 shadow-lg",
-				flipped ? "bottom-full mb-1" : "mt-1",
+				"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];

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

@@ -89,7 +89,7 @@ export function ConditionTags({
 				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 transition-opacity"
+				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();

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 | undefined,
+		icon: string | undefined,
+	) => 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("");
+				setIcon("");
+			}
+			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 || undefined, icon || undefined);
+		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/hp-adjust-popover.tsx

@@ -6,7 +6,6 @@ import {
 	useRef,
 	useState,
 } from "react";
-import { Button } from "./ui/button";
 import { Input } from "./ui/input";
 
 interface HpAdjustPopoverProps {
@@ -109,30 +108,26 @@ export function HpAdjustPopover({ onAdjust, onClose }: HpAdjustPopoverProps) {
 					}}
 					onKeyDown={handleKeyDown}
 				/>
-				<Button
+				<button
 					type="button"
-					variant="ghost"
-					size="icon"
 					disabled={!isValid}
-					className="h-7 w-7 shrink-0 text-red-400 hover:bg-red-950 hover:text-red-300"
+					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
+				</button>
+				<button
 					type="button"
-					variant="ghost"
-					size="icon"
 					disabled={!isValid}
-					className="h-7 w-7 shrink-0 text-emerald-400 hover:bg-emerald-950 hover:text-emerald-300"
+					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>
+				</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(value === iconId ? "" : 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-character-section.tsx

@@ -0,0 +1,91 @@
+import type { PlayerCharacter, PlayerCharacterId } from "@initiative/domain";
+import { forwardRef, useImperativeHandle, useState } from "react";
+import { CreatePlayerModal } from "./create-player-modal.js";
+import { PlayerManagement } from "./player-management.js";
+
+export interface PlayerCharacterSectionHandle {
+	openManagement: () => void;
+}
+
+interface PlayerCharacterSectionProps {
+	characters: readonly PlayerCharacter[];
+	onCreateCharacter: (
+		name: string,
+		ac: number,
+		maxHp: number,
+		color: string | undefined,
+		icon: string | undefined,
+	) => void;
+	onEditCharacter: (
+		id: PlayerCharacterId,
+		fields: {
+			name?: string;
+			ac?: number;
+			maxHp?: number;
+			color?: string | null;
+			icon?: string | null;
+		},
+	) => void;
+	onDeleteCharacter: (id: PlayerCharacterId) => void;
+}
+
+export const PlayerCharacterSection = forwardRef<
+	PlayerCharacterSectionHandle,
+	PlayerCharacterSectionProps
+>(function PlayerCharacterSection(
+	{ characters, onCreateCharacter, onEditCharacter, onDeleteCharacter },
+	ref,
+) {
+	const [managementOpen, setManagementOpen] = useState(false);
+	const [createOpen, setCreateOpen] = useState(false);
+	const [editingPlayer, setEditingPlayer] = useState<
+		PlayerCharacter | undefined
+	>();
+
+	useImperativeHandle(ref, () => ({
+		openManagement: () => setManagementOpen(true),
+	}));
+
+	return (
+		<>
+			<CreatePlayerModal
+				open={createOpen}
+				onClose={() => {
+					setCreateOpen(false);
+					setEditingPlayer(undefined);
+					setManagementOpen(true);
+				}}
+				onSave={(name, ac, maxHp, color, icon) => {
+					if (editingPlayer) {
+						onEditCharacter(editingPlayer.id, {
+							name,
+							ac,
+							maxHp,
+							color: color ?? null,
+							icon: icon ?? null,
+						});
+					} else {
+						onCreateCharacter(name, ac, maxHp, color, icon);
+					}
+				}}
+				playerCharacter={editingPlayer}
+			/>
+			<PlayerManagement
+				open={managementOpen}
+				onClose={() => setManagementOpen(false)}
+				characters={characters}
+				onEdit={(pc) => {
+					setEditingPlayer(pc);
+					setCreateOpen(true);
+					setManagementOpen(false);
+				}}
+				onDelete={(id) => onDeleteCharacter(id)}
+				onCreate={() => {
+					setEditingPlayer(undefined);
+					setCreateOpen(true);
+					setManagementOpen(false);
+				}}
+			/>
+		</>
+	);
+});

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,121 @@
+import type { PlayerCharacter, PlayerCharacterId } 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 = pc.icon ? PLAYER_ICON_MAP[pc.icon] : undefined;
+							const color = pc.color ? PLAYER_COLOR_HEX[pc.color] : undefined;
+							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,97 @@
+import { Database, Trash2 } from "lucide-react";
+import { useCallback, useEffect, useOptimistic, 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 [optimisticSources, applyOptimistic] = useOptimistic(
+		sources,
+		(
+			state,
+			action: { type: "remove"; sourceCode: string } | { type: "clear" },
+		) =>
+			action.type === "clear"
+				? []
+				: state.filter((s) => s.sourceCode !== action.sourceCode),
+	);
+
+	const loadSources = useCallback(async () => {
+		const cached = await bestiaryCache.getCachedSources();
+		setSources(cached);
+	}, []);
+
+	useEffect(() => {
+		loadSources();
+	}, [loadSources]);
+
+	const handleClearSource = async (sourceCode: string) => {
+		applyOptimistic({ type: "remove", sourceCode });
+		await bestiaryCache.clearSource(sourceCode);
+		await loadSources();
+		onCacheCleared();
+	};
+
+	const handleClearAll = async () => {
+		applyOptimistic({ type: "clear" });
+		await bestiaryCache.clearAll();
+		await loadSources();
+		onCacheCleared();
+	};
+
+	if (optimisticSources.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">
+				{optimisticSources.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

@@ -1,17 +1,250 @@
-import type { Creature } from "@initiative/domain";
-import { X } from "lucide-react";
+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 { SourceManager } from "./source-manager.js";
 import { StatBlock } from "./stat-block.js";
+import { Button } from "./ui/button.js";
 
 interface StatBlockPanelProps {
+	creatureId: CreatureId | null;
 	creature: Creature | null;
-	onClose: () => void;
+	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";
+	isCollapsed: boolean;
+	onToggleCollapse: () => void;
+	onPin: () => void;
+	onUnpin: () => void;
+	showPinButton: boolean;
+	side: "left" | "right";
+	onDismiss: () => void;
+	bulkImportMode?: boolean;
+	bulkImportState?: BulkImportState;
+	onStartBulkImport?: (baseUrl: string) => void;
+	onBulkImportDone?: () => void;
+	sourceManagerMode?: boolean;
 }
 
-export function StatBlockPanel({ creature, onClose }: StatBlockPanelProps) {
+function extractSourceCode(cId: CreatureId): string {
+	const colonIndex = cId.indexOf(":");
+	if (colonIndex === -1) return "";
+	return cId.slice(0, colonIndex).toUpperCase();
+}
+
+function CollapsedTab({
+	creatureName,
+	side,
+	onToggleCollapse,
+}: {
+	creatureName: string;
+	side: "left" | "right";
+	onToggleCollapse: () => void;
+}) {
+	return (
+		<button
+			type="button"
+			onClick={onToggleCollapse}
+			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="Expand stat block panel"
+		>
+			<span className="writing-vertical-rl text-sm font-medium">
+				{creatureName}
+			</span>
+		</button>
+	);
+}
+
+function PanelHeader({
+	panelRole,
+	showPinButton,
+	onToggleCollapse,
+	onPin,
+	onUnpin,
+}: {
+	panelRole: "browse" | "pinned";
+	showPinButton: boolean;
+	onToggleCollapse: () => 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={onToggleCollapse}
+						className="text-muted-foreground"
+						aria-label="Collapse 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({
+	isCollapsed,
+	side,
+	creatureName,
+	panelRole,
+	showPinButton,
+	onToggleCollapse,
+	onPin,
+	onUnpin,
+	children,
+}: {
+	isCollapsed: boolean;
+	side: "left" | "right";
+	creatureName: string;
+	panelRole: "browse" | "pinned";
+	showPinButton: boolean;
+	onToggleCollapse: () => void;
+	onPin: () => void;
+	onUnpin: () => void;
+	children: ReactNode;
+}) {
+	const sideClasses = side === "left" ? "left-0 border-r" : "right-0 border-l";
+	const collapsedTranslate =
+		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} ${isCollapsed ? collapsedTranslate : "translate-x-0"}`}
+		>
+			{isCollapsed ? (
+				<CollapsedTab
+					creatureName={creatureName}
+					side={side}
+					onToggleCollapse={onToggleCollapse}
+				/>
+			) : (
+				<>
+					<PanelHeader
+						panelRole={panelRole}
+						showPinButton={showPinButton}
+						onToggleCollapse={onToggleCollapse}
+						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="Collapse 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,
+	isCollapsed,
+	onToggleCollapse,
+	onPin,
+	onUnpin,
+	showPinButton,
+	side,
+	onDismiss,
+	bulkImportMode,
+	bulkImportState,
+	onStartBulkImport,
+	onBulkImportDone,
+	sourceManagerMode,
+}: 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)");
@@ -20,58 +253,109 @@ export function StatBlockPanel({ creature, onClose }: StatBlockPanelProps) {
 		return () => mq.removeEventListener("change", handler);
 	}, []);
 
-	if (!creature) return null;
+	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 && !sourceManagerMode) return null;
+
+	const sourceCode = creatureId ? extractSourceCode(creatureId) : "";
+
+	const handleSourceLoaded = async () => {
+		await refreshCache();
+		setNeedsFetch(false);
+	};
+
+	const renderContent = () => {
+		if (sourceManagerMode) {
+			return <SourceManager onCacheCleared={refreshCache} />;
+		}
+
+		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 ??
+		(sourceManagerMode
+			? "Sources"
+			: bulkImportMode
+				? "Import All Sources"
+				: "Creature");
 
 	if (isDesktop) {
 		return (
-			<div className="fixed top-0 right-0 bottom-0 flex w-[400px] flex-col border-l border-border bg-card">
-				<div className="flex items-center justify-between border-b border-border px-4 py-2">
-					<span className="text-sm font-semibold text-muted-foreground">
-						Stat Block
-					</span>
-					<button
-						type="button"
-						onClick={onClose}
-						className="text-muted-foreground hover:text-hover-neutral"
+			<DesktopPanel
+				isCollapsed={isCollapsed}
+				side={side}
+				creatureName={creatureName}
+				panelRole={panelRole}
+				showPinButton={showPinButton}
+				onToggleCollapse={onToggleCollapse}
+				onPin={onPin}
+				onUnpin={onUnpin}
 			>
-						<X className="h-4 w-4" />
-					</button>
-				</div>
-				<div className="flex-1 overflow-y-auto p-4">
-					<StatBlock creature={creature} />
-				</div>
-			</div>
+				{renderContent()}
+			</DesktopPanel>
 		);
 	}
 
-	// Mobile drawer
-	return (
-		<div className="fixed inset-0 z-50">
-			{/* Backdrop */}
-			<button
-				type="button"
-				className="absolute inset-0 bg-black/50 animate-in fade-in"
-				onClick={onClose}
-				aria-label="Close stat block"
-			/>
-			{/* Drawer */}
-			<div className="absolute top-0 right-0 bottom-0 w-[85%] max-w-md animate-slide-in-right border-l border-border bg-card shadow-xl">
-				<div className="flex items-center justify-between border-b border-border px-4 py-2">
-					<span className="text-sm font-semibold text-muted-foreground">
-						Stat Block
-					</span>
-					<button
-						type="button"
-						onClick={onClose}
-						className="text-muted-foreground hover:text-hover-neutral"
-					>
-						<X className="h-4 w-4" />
-					</button>
-				</div>
-				<div className="h-[calc(100%-41px)] overflow-y-auto p-4">
-					<StatBlock creature={creature} />
-				</div>
-			</div>
-		</div>
-	);
+	if (panelRole === "pinned") return null;
+
+	return <MobileDrawer onDismiss={onDismiss}>{renderContent()}</MobileDrawer>;
 }

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-4 z-50">
+			<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

@@ -1,14 +1,13 @@
 import type { Encounter } from "@initiative/domain";
 import { StepBack, StepForward, Trash2 } from "lucide-react";
-import { D20Icon } from "./d20-icon";
 import { Button } from "./ui/button";
+import { ConfirmButton } from "./ui/confirm-button";
 
 interface TurnNavigationProps {
 	encounter: Encounter;
 	onAdvanceTurn: () => void;
 	onRetreatTurn: () => void;
 	onClearEncounter: () => void;
-	onRollAllInitiative: () => void;
 }
 
 export function TurnNavigation({
@@ -16,18 +15,16 @@ export function TurnNavigation({
 	onAdvanceTurn,
 	onRetreatTurn,
 	onClearEncounter,
-	onRollAllInitiative,
 }: 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 justify-between rounded-md border border-border bg-card px-4 py-3">
+		<div className="flex items-center gap-3 rounded-md border border-border bg-card px-4 py-3">
 			<Button
 				variant="outline"
 				size="icon"
-				className="h-8 w-8 text-foreground border-foreground hover:text-hover-action hover:border-hover-action hover:bg-transparent"
 				onClick={onRetreatTurn}
 				disabled={!hasCombatants || isAtStart}
 				title="Previous turn"
@@ -36,46 +33,28 @@ export function TurnNavigation({
 				<StepBack className="h-5 w-5" />
 			</Button>
 
-			<div className="text-center text-sm">
-				{activeCombatant ? (
-					<>
-						<span className="font-medium">Round {encounter.roundNumber}</span>
-						<span className="text-muted-foreground">
-							{" "}
-							— {activeCombatant.name}
+			<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 items-center gap-3">
-				<div className="flex items-center gap-0">
-					<Button
-						variant="ghost"
-						size="icon"
-						className="h-8 w-8 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>
-					<Button
-						variant="ghost"
-						size="icon"
-						className="h-8 w-8 text-muted-foreground hover:text-hover-destructive"
-						onClick={onClearEncounter}
+			<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}
-					>
-						<Trash2 className="h-5 w-5" />
-					</Button>
-				</div>
+					className="text-muted-foreground"
+				/>
 				<Button
 					variant="outline"
 					size="icon"
-					className="h-8 w-8 text-foreground border-foreground hover:text-hover-action hover:border-hover-action hover:bg-transparent"
 					onClick={onAdvanceTurn}
 					disabled={!hasCombatants}
 					title="Next turn"

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

@@ -13,9 +13,9 @@ const buttonVariants = cva(
 				ghost: "hover:bg-hover-neutral-bg hover:text-hover-neutral",
 			},
 			size: {
-				default: "h-9 px-4 py-2",
-				sm: "h-8 px-3 text-xs",
+				default: "h-8 px-3 text-xs",
 				icon: "h-8 w-8",
+				"icon-sm": "h-6 w-6",
 			},
 		},
 		defaultVariants: {

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/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

@@ -1,62 +1,134 @@
-import type { Creature, CreatureId } from "@initiative/domain";
-import { useEffect, useMemo, useRef, useState } from "react";
-import { normalizeBestiary } from "../adapters/bestiary-adapter.js";
+import type {
+	BestiaryIndexEntry,
+	Creature,
+	CreatureId,
+} from "@initiative/domain";
+import { useCallback, useEffect, 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) => Creature[];
+	search: (query: string) => SearchResult[];
 	getCreature: (id: CreatureId) => Creature | undefined;
-	allCreatures: Creature[];
 	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 [creatures, setCreatures] = useState<Creature[]>([]);
 	const [isLoaded, setIsLoaded] = useState(false);
-	const creatureMapRef = useRef<Map<string, Creature>>(new Map());
-	const loadAttempted = useRef(false);
+	const [creatureMap, setCreatureMap] = useState(
+		() => new Map<CreatureId, Creature>(),
+	);
 
 	useEffect(() => {
-		if (loadAttempted.current) return;
-		loadAttempted.current = true;
-
-		import("../../../../data/bestiary/xmm.json")
-			// biome-ignore lint/suspicious/noExplicitAny: raw JSON shape varies per entry
-			.then((mod: any) => {
-				const raw = mod.default ?? mod;
-				try {
-					const normalized = normalizeBestiary(raw);
-					const map = new Map<string, Creature>();
-					for (const c of normalized) {
-						map.set(c.id, c);
-					}
-					creatureMapRef.current = map;
-					setCreatures(normalized);
+		const index = loadBestiaryIndex();
+		setSourceDisplayNames(index.sources as Record<string, string>);
+		if (index.creatures.length > 0) {
 			setIsLoaded(true);
-				} catch {
-					// Normalization failed — bestiary unavailable
 		}
-			})
-			.catch(() => {
-				// Import failed — bestiary unavailable
+
+		bestiaryCache.loadAllCachedCreatures().then((map) => {
+			setCreatureMap(map);
 		});
 	}, []);
 
-	const search = useMemo(() => {
-		return (query: string): Creature[] => {
+	const search = useCallback((query: string): SearchResult[] => {
 		if (query.length < 2) return [];
 		const lower = query.toLowerCase();
-			return creatures
+		const index = loadBestiaryIndex();
+		return index.creatures
 			.filter((c) => c.name.toLowerCase().includes(lower))
 			.sort((a, b) => a.name.localeCompare(b.name))
-				.slice(0, 10);
-		};
-	}, [creatures]);
-
-	const getCreature = useMemo(() => {
-		return (id: CreatureId): Creature | undefined => {
-			return creatureMapRef.current.get(id);
-		};
+			.slice(0, 10)
+			.map((c) => ({
+				...c,
+				sourceDisplayName: getSourceDisplayName(c.source),
+			}));
 	}, []);
 
-	return { search, getCreature, allCreatures: creatures, isLoaded };
+	const getCreature = useCallback(
+		(id: CreatureId): Creature | undefined => {
+			return creatureMap.get(id);
+		},
+		[creatureMap],
+	);
+
+	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);
+			setCreatureMap((prev) => {
+				const next = new Map(prev);
+				for (const c of creatures) {
+					next.set(c.id, c);
+				}
+				return next;
+			});
+		},
+		[],
+	);
+
+	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);
+			setCreatureMap((prev) => {
+				const next = new Map(prev);
+				for (const c of creatures) {
+					next.set(c.id, c);
+				}
+				return next;
+			});
+		},
+		[],
+	);
+
+	const refreshCache = useCallback(async (): Promise<void> => {
+		const map = await bestiaryCache.loadAllCachedCreatures();
+		setCreatureMap(map);
+	}, []);
+
+	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

@@ -14,16 +14,17 @@ import {
 	toggleConditionUseCase,
 } from "@initiative/application";
 import type {
+	BestiaryIndexEntry,
 	CombatantId,
 	ConditionId,
-	Creature,
 	DomainEvent,
 	Encounter,
+	PlayerCharacter,
 } from "@initiative/domain";
 import {
 	combatantId,
-	createEncounter,
 	isDomainError,
+	creatureId as makeCreatureId,
 	resolveCreatureName,
 } from "@initiative/domain";
 import { useCallback, useEffect, useRef, useState } from "react";
@@ -32,24 +33,16 @@ import {
 	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" },
-	]);
-
-	if (isDomainError(result)) {
-		throw new Error(`Failed to create demo encounter: ${result.message}`);
-	}
-
-	return result;
-}
+const EMPTY_ENCOUNTER: Encounter = {
+	combatants: [],
+	activeIndex: 0,
+	roundNumber: 1,
+};
 
 function initializeEncounter(): Encounter {
 	const stored = loadEncounter();
 	if (stored !== null) return stored;
-	return createDemoEncounter();
+	return EMPTY_ENCOUNTER;
 }
 
 function deriveNextId(encounter: Encounter): number {
@@ -64,6 +57,33 @@ function deriveNextId(encounter: Encounter): number {
 	return max;
 }
 
+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>(initializeEncounter);
 	const [events, setEvents] = useState<DomainEvent[]>([]);
@@ -107,7 +127,7 @@ export function useEncounter() {
 	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);
 
@@ -115,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],
@@ -225,10 +252,6 @@ export function useEncounter() {
 	);
 
 	const clearEncounter = useCallback(() => {
-		if (!window.confirm("Clear the entire encounter? This cannot be undone.")) {
-			return;
-		}
-
 		const result = clearEncounterUseCase(makeStore());
 
 		if (isDomainError(result)) {
@@ -240,11 +263,11 @@ export function useEncounter() {
 	}, [makeStore]);
 
 	const addFromBestiary = useCallback(
-		(creature: Creature) => {
+		(entry: BestiaryIndexEntry) => {
 			const store = makeStore();
 			const existingNames = store.get().combatants.map((c) => c.name);
 			const { newName, renames } = resolveCreatureName(
-				creature.name,
+				entry.name,
 				existingNames,
 			);
 
@@ -262,37 +285,106 @@ export function useEncounter() {
 			if (isDomainError(addResult)) return;
 
 			// Set HP
-			const hpResult = setHpUseCase(makeStore(), id, creature.hp.average);
+			const hpResult = setHpUseCase(makeStore(), id, entry.hp);
 			if (!isDomainError(hpResult)) {
 				setEvents((prev) => [...prev, ...hpResult]);
 			}
 
 			// Set AC
-			if (creature.ac > 0) {
-				const acResult = setAcUseCase(makeStore(), id, creature.ac);
+			if (entry.ac > 0) {
+				const acResult = setAcUseCase(makeStore(), id, entry.ac);
 				if (!isDomainError(acResult)) {
 					setEvents((prev) => [...prev, ...acResult]);
 				}
 			}
 
-			// Set creatureId on the combatant
+			// 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();
-			const updated = {
+			store.save({
 				...currentEncounter,
 				combatants: currentEncounter.combatants.map((c) =>
-					c.id === id ? { ...c, creatureId: creature.id } : c,
+					c.id === id ? { ...c, creatureId: cId } : c,
 				),
-			};
-			setEncounter(updated);
+			});
 
 			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],
+	);
+
+	const isEmpty = encounter.combatants.length === 0;
+	const hasCreatureCombatants = encounter.combatants.some(
+		(c) => c.creatureId != null,
+	);
+	const canRollAllInitiative = encounter.combatants.some(
+		(c) => c.creatureId != null && c.initiative == null,
+	);
+
 	return {
 		encounter,
 		events,
+		isEmpty,
+		hasCreatureCombatants,
+		canRollAllInitiative,
 		advanceTurn,
 		retreatTurn,
 		addCombatant,
@@ -306,6 +398,7 @@ export function useEncounter() {
 		toggleCondition,
 		toggleConcentration,
 		addFromBestiary,
+		addFromPlayerCharacter,
 		makeStore,
 	} as const;
 }

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

@@ -0,0 +1,108 @@
+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 | null;
+	readonly icon?: string | null;
+}
+
+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 | undefined,
+			icon: string | undefined,
+		) => {
+			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-side-panel-state.ts

@@ -0,0 +1,101 @@
+import type { CreatureId } from "@initiative/domain";
+import { useCallback, useEffect, useState } from "react";
+
+type PanelView =
+	| { mode: "closed" }
+	| { mode: "creature"; creatureId: CreatureId }
+	| { mode: "bulk-import" }
+	| { mode: "source-manager" };
+
+interface SidePanelState {
+	panelView: PanelView;
+	selectedCreatureId: CreatureId | null;
+	bulkImportMode: boolean;
+	sourceManagerMode: boolean;
+	isRightPanelCollapsed: boolean;
+	pinnedCreatureId: CreatureId | null;
+	isWideDesktop: boolean;
+}
+
+interface SidePanelActions {
+	showCreature: (creatureId: CreatureId) => void;
+	showBulkImport: () => void;
+	showSourceManager: () => void;
+	dismissPanel: () => void;
+	toggleCollapse: () => void;
+	togglePin: () => void;
+	unpin: () => void;
+}
+
+export function useSidePanelState(): SidePanelState & SidePanelActions {
+	const [panelView, setPanelView] = useState<PanelView>({ mode: "closed" });
+	const [isRightPanelCollapsed, setIsRightPanelCollapsed] = 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 selectedCreatureId =
+		panelView.mode === "creature" ? panelView.creatureId : null;
+
+	const showCreature = useCallback((creatureId: CreatureId) => {
+		setPanelView({ mode: "creature", creatureId });
+		setIsRightPanelCollapsed(false);
+	}, []);
+
+	const showBulkImport = useCallback(() => {
+		setPanelView({ mode: "bulk-import" });
+		setIsRightPanelCollapsed(false);
+	}, []);
+
+	const showSourceManager = useCallback(() => {
+		setPanelView({ mode: "source-manager" });
+		setIsRightPanelCollapsed(false);
+	}, []);
+
+	const dismissPanel = useCallback(() => {
+		setPanelView({ mode: "closed" });
+	}, []);
+
+	const toggleCollapse = useCallback(() => {
+		setIsRightPanelCollapsed((f) => !f);
+	}, []);
+
+	const togglePin = useCallback(() => {
+		if (selectedCreatureId) {
+			setPinnedCreatureId((prev) =>
+				prev === selectedCreatureId ? null : selectedCreatureId,
+			);
+		}
+	}, [selectedCreatureId]);
+
+	const unpin = useCallback(() => {
+		setPinnedCreatureId(null);
+	}, []);
+
+	return {
+		panelView,
+		selectedCreatureId,
+		bulkImportMode: panelView.mode === "bulk-import",
+		sourceManagerMode: panelView.mode === "source-manager",
+		isRightPanelCollapsed,
+		pinnedCreatureId,
+		isWideDesktop,
+		showCreature,
+		showBulkImport,
+		showSourceManager,
+		dismissPanel,
+		toggleCollapse,
+		togglePin,
+		unpin,
+	};
+}

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

@@ -16,7 +16,7 @@
 	--color-hover-neutral: var(--color-primary);
 	--color-hover-action: var(--color-primary);
 	--color-hover-destructive: var(--color-destructive);
-	--color-hover-neutral-bg: var(--color-card);
+	--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;
@@ -68,6 +68,101 @@
 	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,

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

@@ -5,7 +5,10 @@ import {
 	creatureId,
 	type Encounter,
 	isDomainError,
+	playerCharacterId,
 	VALID_CONDITION_IDS,
+	VALID_PLAYER_COLORS,
+	VALID_PLAYER_ICONS,
 } from "@initiative/domain";
 
 const STORAGE_KEY = "initiative:encounter";
@@ -18,6 +21,93 @@ export function saveEncounter(encounter: Encounter): void {
 	}
 }
 
+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);
@@ -45,82 +135,9 @@ export function loadEncounter(): Encounter | null {
 			};
 		}
 
-		for (const c of combatants) {
-			if (typeof c !== "object" || c === null || Array.isArray(c)) return null;
-			const entry = c as Record<string, unknown>;
-			if (typeof entry.id !== "string") return null;
-			if (typeof entry.name !== "string") return null;
-		}
+		if (!combatants.every(isValidCombatantEntry)) return null;
 
-		const rehydrated = combatants.map((c) => {
-			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,
-			};
-
-			// Validate AC field
-			const ac = entry.ac;
-			const validAc =
-				typeof ac === "number" && Number.isInteger(ac) && ac >= 0
-					? ac
-					: undefined;
-
-			// Validate conditions field
-			const rawConditions = entry.conditions;
-			const validConditions: ConditionId[] | undefined = Array.isArray(
-				rawConditions,
-			)
-				? (rawConditions.filter(
-						(v): v is ConditionId =>
-							typeof v === "string" && VALID_CONDITION_IDS.has(v),
-					) as ConditionId[])
-				: undefined;
-			const conditions =
-				validConditions && validConditions.length > 0
-					? validConditions
-					: undefined;
-
-			// Validate isConcentrating field
-			const isConcentrating = entry.isConcentrating === true ? true : undefined;
-
-			// Validate creatureId field
-			const rawCreatureId = entry.creatureId;
-			const validCreatureId =
-				typeof rawCreatureId === "string" && rawCreatureId.length > 0
-					? creatureId(rawCreatureId)
-					: undefined;
-
-			// Validate and attach HP fields if valid
-			const maxHp = entry.maxHp;
-			const currentHp = entry.currentHp;
-			if (typeof maxHp === "number" && Number.isInteger(maxHp) && maxHp >= 1) {
-				const validCurrentHp =
-					typeof currentHp === "number" &&
-					Number.isInteger(currentHp) &&
-					currentHp >= 0 &&
-					currentHp <= maxHp;
-				return {
-					...base,
-					ac: validAc,
-					conditions,
-					isConcentrating,
-					creatureId: validCreatureId,
-					maxHp,
-					currentHp: validCurrentHp ? currentHp : maxHp,
-				};
-			}
-
-			return {
-				...base,
-				ac: validAc,
-				conditions,
-				isConcentrating,
-				creatureId: validCreatureId,
-			};
-		});
+		const rehydrated = combatants.map(rehydrateCombatant);
 
 		const result = createEncounter(
 			rehydrated,

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

@@ -0,0 +1,77 @@
+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 isValidOptionalMember(
+	value: unknown,
+	valid: ReadonlySet<string>,
+): boolean {
+	return value === undefined || (typeof value === "string" && valid.has(value));
+}
+
+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 (!isValidOptionalMember(entry.color, VALID_PLAYER_COLORS)) return null;
+	if (!isValidOptionalMember(entry.icon, VALID_PLAYER_ICONS)) 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 [];
+	}
+}

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
+					}
+				}
+			}
 		}
 	}
 }

docs/agents/.gitkeep

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

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

@@ -1,8 +1,14 @@
 {
 	"private": true,
 	"packageManager": "pnpm@10.6.0",
+	"pnpm": {
+		"overrides": {
+			"undici": ">=7.24.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",
@@ -20,6 +26,6 @@
 		"test:watch": "vitest",
 		"knip": "knip",
 		"jscpd": "jscpd",
-		"check": "knip && biome check . && tsc --build && vitest run && jscpd"
+		"check": "pnpm audit --audit-level=high && knip && biome check . && tsc --build && vitest run && jscpd"
 	}
 }

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 | undefined,
+	icon: string | undefined,
+): 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 | null;
+	readonly icon?: string | null;
+}
+
+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

@@ -2,11 +2,21 @@ 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 {
+	type RollAllResult,
+	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";

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/roll-all-initiative-use-case.ts

@@ -10,20 +10,29 @@ import {
 } from "@initiative/domain";
 import type { EncounterStore } from "./ports.js";
 
+export interface RollAllResult {
+	events: DomainEvent[];
+	skippedNoSource: number;
+}
+
 export function rollAllInitiativeUseCase(
 	store: EncounterStore,
 	rollDice: () => number,
 	getCreature: (id: CreatureId) => Creature | undefined,
-): DomainEvent[] | DomainError {
+): RollAllResult | DomainError {
 	let encounter = store.get();
 	const allEvents: DomainEvent[] = [];
+	let skippedNoSource = 0;
 
 	for (const combatant of encounter.combatants) {
 		if (!combatant.creatureId) continue;
 		if (combatant.initiative !== undefined) continue;
 
 		const creature = getCreature(combatant.creatureId);
-		if (!creature) continue;
+		if (!creature) {
+			skippedNoSource++;
+			continue;
+		}
 
 		const { modifier } = calculateInitiative({
 			dexScore: creature.abilities.dex,
@@ -47,5 +56,5 @@ export function rollAllInitiativeUseCase(
 	}
 
 	store.save(encounter);
-	return allEvents;
+	return { events: allEvents, skippedNoSource };
 }

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__/create-player-character.test.ts

@@ -0,0 +1,270 @@
+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("allows undefined color", () => {
+		const result = createPlayerCharacter(
+			[],
+			id,
+			"Test",
+			10,
+			50,
+			undefined,
+			"sword",
+		);
+		if (isDomainError(result)) throw new Error(result.message);
+		expect(result.characters[0].color).toBeUndefined();
+	});
+
+	it("allows undefined icon", () => {
+		const result = createPlayerCharacter(
+			[],
+			id,
+			"Test",
+			10,
+			50,
+			"blue",
+			undefined,
+		);
+		if (isDomainError(result)) throw new Error(result.message);
+		expect(result.characters[0].icon).toBeUndefined();
+	});
+
+	it("allows both color and icon undefined", () => {
+		const result = createPlayerCharacter(
+			[],
+			id,
+			"Test",
+			10,
+			50,
+			undefined,
+			undefined,
+		);
+		if (isDomainError(result)) throw new Error(result.message);
+		expect(result.characters[0].color).toBeUndefined();
+		expect(result.characters[0].icon).toBeUndefined();
+	});
+
+	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,133 @@
+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("clears color when set to null", () => {
+		const result = editPlayerCharacter([makePC({ color: "green" })], id, {
+			color: null,
+		});
+		if (isDomainError(result)) throw new Error(result.message);
+		expect(result.characters[0].color).toBeUndefined();
+	});
+
+	it("clears icon when set to null", () => {
+		const result = editPlayerCharacter([makePC({ icon: "sword" })], id, {
+			icon: null,
+		});
+		if (isDomainError(result)) throw new Error(result.message);
+		expect(result.characters[0].icon).toBeUndefined();
+	});
+
+	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/create-player-character.ts

@@ -0,0 +1,87 @@
+import type { DomainEvent } from "./events.js";
+import type {
+	PlayerCharacter,
+	PlayerCharacterId,
+} from "./player-character-types.js";
+import {
+	VALID_PLAYER_COLORS,
+	VALID_PLAYER_ICONS,
+} from "./player-character-types.js";
+import type { DomainError } from "./types.js";
+
+export interface CreatePlayerCharacterSuccess {
+	readonly characters: readonly PlayerCharacter[];
+	readonly events: DomainEvent[];
+}
+
+export function createPlayerCharacter(
+	characters: readonly PlayerCharacter[],
+	id: PlayerCharacterId,
+	name: string,
+	ac: number,
+	maxHp: number,
+	color: string | undefined,
+	icon: string | undefined,
+): CreatePlayerCharacterSuccess | DomainError {
+	const trimmed = name.trim();
+
+	if (trimmed === "") {
+		return {
+			kind: "domain-error",
+			code: "invalid-name",
+			message: "Player character name must not be empty",
+		};
+	}
+
+	if (!Number.isInteger(ac) || ac < 0) {
+		return {
+			kind: "domain-error",
+			code: "invalid-ac",
+			message: "AC must be a non-negative integer",
+		};
+	}
+
+	if (!Number.isInteger(maxHp) || maxHp < 1) {
+		return {
+			kind: "domain-error",
+			code: "invalid-max-hp",
+			message: "Max HP must be a positive integer",
+		};
+	}
+
+	if (color !== undefined && !VALID_PLAYER_COLORS.has(color)) {
+		return {
+			kind: "domain-error",
+			code: "invalid-color",
+			message: `Invalid color: ${color}`,
+		};
+	}
+
+	if (icon !== undefined && !VALID_PLAYER_ICONS.has(icon)) {
+		return {
+			kind: "domain-error",
+			code: "invalid-icon",
+			message: `Invalid icon: ${icon}`,
+		};
+	}
+
+	const newCharacter: PlayerCharacter = {
+		id,
+		name: trimmed,
+		ac,
+		maxHp,
+		color: color as PlayerCharacter["color"],
+		icon: icon as PlayerCharacter["icon"],
+	};
+
+	return {
+		characters: [...characters, newCharacter],
+		events: [
+			{
+				type: "PlayerCharacterCreated",
+				playerCharacterId: id,
+				name: trimmed,
+			},
+		],
+	};
+}

packages/domain/src/creature-types.ts

@@ -75,6 +75,23 @@ export interface Creature {
 	readonly spellcasting?: readonly SpellcastingBlock[];
 }
 
+export interface BestiaryIndexEntry {
+	readonly name: string;
+	readonly source: string;
+	readonly ac: number;
+	readonly hp: number;
+	readonly dex: number;
+	readonly cr: string;
+	readonly initiativeProficiency: number;
+	readonly size: string;
+	readonly type: string;
+}
+
+export interface BestiaryIndex {
+	readonly sources: Readonly<Record<string, string>>;
+	readonly creatures: readonly BestiaryIndexEntry[];
+}
+
 /** Maps a CR string to the corresponding proficiency bonus. */
 export function proficiencyBonus(cr: string): number {
 	const numericCr = cr.includes("/")

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

@@ -0,0 +1,39 @@
+import type { DomainEvent } from "./events.js";
+import type {
+	PlayerCharacter,
+	PlayerCharacterId,
+} from "./player-character-types.js";
+import type { DomainError } from "./types.js";
+
+export interface DeletePlayerCharacterSuccess {
+	readonly characters: readonly PlayerCharacter[];
+	readonly events: DomainEvent[];
+}
+
+export function deletePlayerCharacter(
+	characters: readonly PlayerCharacter[],
+	id: PlayerCharacterId,
+): DeletePlayerCharacterSuccess | DomainError {
+	const index = characters.findIndex((c) => c.id === id);
+	if (index === -1) {
+		return {
+			kind: "domain-error",
+			code: "player-character-not-found",
+			message: `Player character not found: ${id}`,
+		};
+	}
+
+	const removed = characters[index];
+	const newList = characters.filter((_, i) => i !== index);
+
+	return {
+		characters: newList,
+		events: [
+			{
+				type: "PlayerCharacterDeleted",
+				playerCharacterId: id,
+				name: removed.name,
+			},
+		],
+	};
+}

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

@@ -0,0 +1,145 @@
+import type { DomainEvent } from "./events.js";
+import type {
+	PlayerCharacter,
+	PlayerCharacterId,
+} from "./player-character-types.js";
+import {
+	VALID_PLAYER_COLORS,
+	VALID_PLAYER_ICONS,
+} from "./player-character-types.js";
+import type { DomainError } from "./types.js";
+
+export interface EditPlayerCharacterSuccess {
+	readonly characters: readonly PlayerCharacter[];
+	readonly events: DomainEvent[];
+}
+
+interface EditFields {
+	readonly name?: string;
+	readonly ac?: number;
+	readonly maxHp?: number;
+	readonly color?: string | null;
+	readonly icon?: string | null;
+}
+
+function validateFields(fields: EditFields): DomainError | null {
+	if (fields.name !== undefined && fields.name.trim() === "") {
+		return {
+			kind: "domain-error",
+			code: "invalid-name",
+			message: "Player character name must not be empty",
+		};
+	}
+	if (
+		fields.ac !== undefined &&
+		(!Number.isInteger(fields.ac) || fields.ac < 0)
+	) {
+		return {
+			kind: "domain-error",
+			code: "invalid-ac",
+			message: "AC must be a non-negative integer",
+		};
+	}
+	if (
+		fields.maxHp !== undefined &&
+		(!Number.isInteger(fields.maxHp) || fields.maxHp < 1)
+	) {
+		return {
+			kind: "domain-error",
+			code: "invalid-max-hp",
+			message: "Max HP must be a positive integer",
+		};
+	}
+	if (
+		fields.color !== undefined &&
+		fields.color !== null &&
+		!VALID_PLAYER_COLORS.has(fields.color)
+	) {
+		return {
+			kind: "domain-error",
+			code: "invalid-color",
+			message: `Invalid color: ${fields.color}`,
+		};
+	}
+	if (
+		fields.icon !== undefined &&
+		fields.icon !== null &&
+		!VALID_PLAYER_ICONS.has(fields.icon)
+	) {
+		return {
+			kind: "domain-error",
+			code: "invalid-icon",
+			message: `Invalid icon: ${fields.icon}`,
+		};
+	}
+	return null;
+}
+
+function applyFields(
+	existing: PlayerCharacter,
+	fields: EditFields,
+): PlayerCharacter {
+	return {
+		id: existing.id,
+		name: fields.name !== undefined ? fields.name.trim() : existing.name,
+		ac: fields.ac !== undefined ? fields.ac : existing.ac,
+		maxHp: fields.maxHp !== undefined ? fields.maxHp : existing.maxHp,
+		color:
+			fields.color !== undefined
+				? ((fields.color as PlayerCharacter["color"]) ?? undefined)
+				: existing.color,
+		icon:
+			fields.icon !== undefined
+				? ((fields.icon as PlayerCharacter["icon"]) ?? undefined)
+				: existing.icon,
+	};
+}
+
+export function editPlayerCharacter(
+	characters: readonly PlayerCharacter[],
+	id: PlayerCharacterId,
+	fields: EditFields,
+): EditPlayerCharacterSuccess | DomainError {
+	const index = characters.findIndex((c) => c.id === id);
+	if (index === -1) {
+		return {
+			kind: "domain-error",
+			code: "player-character-not-found",
+			message: `Player character not found: ${id}`,
+		};
+	}
+
+	const validationError = validateFields(fields);
+	if (validationError) return validationError;
+
+	const existing = characters[index];
+	const updated = applyFields(existing, fields);
+
+	if (
+		updated.name === existing.name &&
+		updated.ac === existing.ac &&
+		updated.maxHp === existing.maxHp &&
+		updated.color === existing.color &&
+		updated.icon === existing.icon
+	) {
+		return {
+			kind: "domain-error",
+			code: "no-changes",
+			message: "No fields changed",
+		};
+	}
+
+	const newList = characters.map((c, i) => (i === index ? updated : c));
+
+	return {
+		characters: newList,
+		events: [
+			{
+				type: "PlayerCharacterUpdated",
+				playerCharacterId: id,
+				oldName: existing.name,
+				newName: updated.name,
+			},
+		],
+	};
+}

packages/domain/src/events.ts

@@ -1,4 +1,5 @@
 import type { ConditionId } from "./conditions.js";
+import type { PlayerCharacterId } from "./player-character-types.js";
 import type { CombatantId } from "./types.js";
 
 export interface TurnAdvanced {
@@ -103,6 +104,25 @@ export interface EncounterCleared {
 	readonly combatantCount: number;
 }
 
+export interface PlayerCharacterCreated {
+	readonly type: "PlayerCharacterCreated";
+	readonly playerCharacterId: PlayerCharacterId;
+	readonly name: string;
+}
+
+export interface PlayerCharacterUpdated {
+	readonly type: "PlayerCharacterUpdated";
+	readonly playerCharacterId: PlayerCharacterId;
+	readonly oldName: string;
+	readonly newName: string;
+}
+
+export interface PlayerCharacterDeleted {
+	readonly type: "PlayerCharacterDeleted";
+	readonly playerCharacterId: PlayerCharacterId;
+	readonly name: string;
+}
+
 export type DomainEvent =
 	| TurnAdvanced
 	| RoundAdvanced
@@ -119,4 +139,7 @@ export type DomainEvent =
 	| ConditionRemoved
 	| ConcentrationStarted
 	| ConcentrationEnded
-	| EncounterCleared;
+	| EncounterCleared
+	| PlayerCharacterCreated
+	| PlayerCharacterUpdated
+	| PlayerCharacterDeleted;

packages/domain/src/index.ts

@@ -13,6 +13,12 @@ export {
 	VALID_CONDITION_IDS,
 } from "./conditions.js";
 export {
+	type CreatePlayerCharacterSuccess,
+	createPlayerCharacter,
+} from "./create-player-character.js";
+export {
+	type BestiaryIndex,
+	type BestiaryIndexEntry,
 	type BestiarySource,
 	type Creature,
 	type CreatureId,
@@ -23,10 +29,18 @@ export {
 	type SpellcastingBlock,
 	type TraitBlock,
 } from "./creature-types.js";
+export {
+	type DeletePlayerCharacterSuccess,
+	deletePlayerCharacter,
+} from "./delete-player-character.js";
 export {
 	type EditCombatantSuccess,
 	editCombatant,
 } from "./edit-combatant.js";
+export {
+	type EditPlayerCharacterSuccess,
+	editPlayerCharacter,
+} from "./edit-player-character.js";
 export type {
 	AcSet,
 	CombatantAdded,
@@ -41,6 +55,9 @@ export type {
 	EncounterCleared,
 	InitiativeSet,
 	MaxHpSet,
+	PlayerCharacterCreated,
+	PlayerCharacterDeleted,
+	PlayerCharacterUpdated,
 	RoundAdvanced,
 	RoundRetreated,
 	TurnAdvanced,
@@ -52,6 +69,16 @@ export {
 	formatInitiativeModifier,
 	type InitiativeResult,
 } from "./initiative.js";
+export {
+	type PlayerCharacter,
+	type PlayerCharacterId,
+	type PlayerCharacterList,
+	type PlayerColor,
+	type PlayerIcon,
+	playerCharacterId,
+	VALID_PLAYER_COLORS,
+	VALID_PLAYER_ICONS,
+} from "./player-character-types.js";
 export {
 	type RemoveCombatantSuccess,
 	removeCombatant,

packages/domain/src/player-character-types.ts

@@ -0,0 +1,81 @@
+/** Branded string type for player character identity. */
+export type PlayerCharacterId = string & {
+	readonly __brand: "PlayerCharacterId";
+};
+
+export function playerCharacterId(id: string): PlayerCharacterId {
+	return id as PlayerCharacterId;
+}
+
+export type PlayerColor =
+	| "red"
+	| "blue"
+	| "green"
+	| "purple"
+	| "orange"
+	| "pink"
+	| "cyan"
+	| "yellow"
+	| "emerald"
+	| "indigo";
+
+export const VALID_PLAYER_COLORS: ReadonlySet<string> = new Set<PlayerColor>([
+	"red",
+	"blue",
+	"green",
+	"purple",
+	"orange",
+	"pink",
+	"cyan",
+	"yellow",
+	"emerald",
+	"indigo",
+]);
+
+export type PlayerIcon =
+	| "sword"
+	| "shield"
+	| "skull"
+	| "heart"
+	| "wand"
+	| "flame"
+	| "crown"
+	| "star"
+	| "moon"
+	| "sun"
+	| "axe"
+	| "crosshair"
+	| "eye"
+	| "feather"
+	| "zap";
+
+export const VALID_PLAYER_ICONS: ReadonlySet<string> = new Set<PlayerIcon>([
+	"sword",
+	"shield",
+	"skull",
+	"heart",
+	"wand",
+	"flame",
+	"crown",
+	"star",
+	"moon",
+	"sun",
+	"axe",
+	"crosshair",
+	"eye",
+	"feather",
+	"zap",
+]);
+
+export interface PlayerCharacter {
+	readonly id: PlayerCharacterId;
+	readonly name: string;
+	readonly ac: number;
+	readonly maxHp: number;
+	readonly color?: PlayerColor;
+	readonly icon?: PlayerIcon;
+}
+
+export interface PlayerCharacterList {
+	readonly characters: readonly PlayerCharacter[];
+}

packages/domain/src/set-initiative.ts

@@ -62,8 +62,9 @@ export function setInitiative(
 		const bHas = b.c.initiative !== undefined;
 
 		if (aHas && bHas) {
-			// biome-ignore lint: both checked above
-			const diff = b.c.initiative! - a.c.initiative!;
+			const aInit = a.c.initiative as number;
+			const bInit = b.c.initiative as number;
+			const diff = bInit - aInit;
 			return diff !== 0 ? diff : a.i - b.i;
 		}
 		if (aHas && !bHas) return -1;

packages/domain/src/types.ts

@@ -7,6 +7,7 @@ export function combatantId(id: string): CombatantId {
 
 import type { ConditionId } from "./conditions.js";
 import type { CreatureId } from "./creature-types.js";
+import type { PlayerCharacterId } from "./player-character-types.js";
 
 export interface Combatant {
 	readonly id: CombatantId;
@@ -18,6 +19,9 @@ export interface Combatant {
 	readonly conditions?: readonly ConditionId[];
 	readonly isConcentrating?: boolean;
 	readonly creatureId?: CreatureId;
+	readonly color?: string;
+	readonly icon?: string;
+	readonly playerCharacterId?: PlayerCharacterId;
 }
 
 export interface Encounter {
@@ -38,8 +42,8 @@ function domainError(code: string, message: string): DomainError {
 
 /**
  * Creates a valid Encounter, enforcing INV-1, INV-2, INV-3.
- * - INV-1: At least one combatant required.
- * - INV-2: activeIndex defaults to 0 (always in bounds).
+ * - INV-1: An encounter MAY have zero combatants.
+ * - INV-2: activeIndex defaults to 0 (always in bounds when combatants exist).
  * - INV-3: roundNumber defaults to 1 (positive integer).
  */
 export function createEncounter(
@@ -47,13 +51,10 @@ export function createEncounter(
 	activeIndex = 0,
 	roundNumber = 1,
 ): Encounter | DomainError {
-	if (combatants.length === 0) {
-		return domainError(
-			"invalid-encounter",
-			"An encounter must have at least one combatant",
-		);
-	}
-	if (activeIndex < 0 || activeIndex >= combatants.length) {
+	if (
+		combatants.length > 0 &&
+		(activeIndex < 0 || activeIndex >= combatants.length)
+	) {
 		return domainError(
 			"invalid-encounter",
 			`activeIndex ${activeIndex} out of bounds for ${combatants.length} combatants`,

scripts/check-layer-boundaries.mjs

@@ -47,29 +47,25 @@ function matchesForbidden(importPath, forbidden) {
 	return importPath === forbidden || importPath.startsWith(`${forbidden}/`);
 }
 
-/** @returns {{ file: string, line: number, importPath: string, forbidden: string }[]} */
-export function checkLayerBoundaries() {
+const IMPORT_RE =
+	/(?:import|from)\s+["']([^"']+)["']|require\s*\(\s*["']([^"']+)["']\s*\)/;
+
+/**
+ * Check a single file for forbidden imports.
+ * @param {string} file
+ * @param {string[]} forbidden
+ * @returns {{ file: string, line: number, importPath: string, forbidden: string }[]}
+ */
+function checkFile(file, forbidden) {
 	/** @type {{ file: string, line: number, importPath: string, forbidden: string }[]} */
 	const violations = [];
-
-	for (const [srcDir, forbidden] of Object.entries(FORBIDDEN)) {
-		const absDir = join(ROOT, srcDir);
-		let files;
-		try {
-			files = collectTsFiles(absDir);
-		} catch {
-			continue;
-		}
-
-		for (const file of files) {
 	const content = readFileSync(file, "utf-8");
 	const lines = content.split("\n");
+
 	for (let i = 0; i < lines.length; i++) {
-				const line = lines[i];
-				const match = line.match(
-					/(?:import|from)\s+["']([^"']+)["']|require\s*\(\s*["']([^"']+)["']\s*\)/,
-				);
+		const match = lines[i].match(IMPORT_RE);
 		if (!match) continue;
+
 		const importPath = match[1] || match[2];
 		for (const f of forbidden) {
 			if (matchesForbidden(importPath, f)) {
@@ -82,12 +78,34 @@ export function checkLayerBoundaries() {
 			}
 		}
 	}
-		}
-	}
 
 	return violations;
 }
 
+/**
+ * Check all files in a layer directory for forbidden imports.
+ * @param {string} srcDir
+ * @param {string[]} forbidden
+ * @returns {{ file: string, line: number, importPath: string, forbidden: string }[]}
+ */
+function checkLayer(srcDir, forbidden) {
+	const absDir = join(ROOT, srcDir);
+	let files;
+	try {
+		files = collectTsFiles(absDir);
+	} catch {
+		return [];
+	}
+	return files.flatMap((file) => checkFile(file, forbidden));
+}
+
+/** @returns {{ file: string, line: number, importPath: string, forbidden: string }[]} */
+export function checkLayerBoundaries() {
+	return Object.entries(FORBIDDEN).flatMap(([srcDir, forbidden]) =>
+		checkLayer(srcDir, forbidden),
+	);
+}
+
 // Run as CLI if invoked directly
 if (
 	process.argv[1] &&

scripts/generate-bestiary-index.mjs

@@ -0,0 +1,166 @@
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Usage: node scripts/generate-bestiary-index.mjs <path-to-5etools-src>
+//
+// Requires a local clone/checkout of https://github.com/5etools-mirror-3/5etools-src
+// with at least data/bestiary/, data/books.json, and data/adventures.json.
+//
+// Example:
+//   git clone --depth 1 --sparse https://github.com/5etools-mirror-3/5etools-src.git /tmp/5etools
+//   cd /tmp/5etools && git sparse-checkout set data/bestiary data
+//   node scripts/generate-bestiary-index.mjs /tmp/5etools
+
+const TOOLS_ROOT = process.argv[2];
+if (!TOOLS_ROOT) {
+	console.error(
+		"Usage: node scripts/generate-bestiary-index.mjs <5etools-src-path>",
+	);
+	process.exit(1);
+}
+
+const PROJECT_ROOT = join(import.meta.dirname, "..");
+const BESTIARY_DIR = join(TOOLS_ROOT, "data/bestiary");
+const BOOKS_PATH = join(TOOLS_ROOT, "data/books.json");
+const ADVENTURES_PATH = join(TOOLS_ROOT, "data/adventures.json");
+const OUTPUT_PATH = join(PROJECT_ROOT, "data/bestiary/index.json");
+
+// --- Build source display name map from books.json + adventures.json ---
+
+/** Populate map from a list of entries that have source/id + name. */
+function addEntriesToMap(map, entries) {
+	for (const entry of entries) {
+		if (!entry.name) continue;
+		if (entry.source) {
+			map[entry.source] = entry.name;
+		}
+		// Some entries use "id" instead of "source"
+		if (entry.id && !map[entry.id]) {
+			map[entry.id] = entry.name;
+		}
+	}
+}
+
+function buildSourceMap() {
+	const map = {};
+
+	const books = JSON.parse(readFileSync(BOOKS_PATH, "utf-8"));
+	addEntriesToMap(map, books.book ?? []);
+
+	const adventures = JSON.parse(readFileSync(ADVENTURES_PATH, "utf-8"));
+	addEntriesToMap(map, adventures.adventure ?? []);
+
+	// Manual additions for sources missing from books.json / adventures.json
+	const manual = {
+		ESK: "Essentials Kit",
+		MCV1SC: "Monstrous Compendium Volume 1: Spelljammer Creatures",
+		MCV2DC: "Monstrous Compendium Volume 2: Dragonlance Creatures",
+		MCV3MC: "Monstrous Compendium Volume 3: Minecraft Creatures",
+		MCV4EC: "Monstrous Compendium Volume 4: Eldraine Creatures",
+		MFF: "Mordenkainen's Fiendish Folio",
+		MisMV1: "Misplaced Monsters: Volume 1",
+		SADS: "Sapphire Anniversary Dice Set",
+		TftYP: "Tales from the Yawning Portal",
+		VD: "Vecna Dossier",
+	};
+	for (const [k, v] of Object.entries(manual)) {
+		if (!map[k]) map[k] = v;
+	}
+
+	return map;
+}
+
+// --- Extract type string from raw type field ---
+
+function extractType(type) {
+	if (typeof type === "string") return type;
+	if (typeof type?.type === "string") return type.type;
+	if (typeof type?.type === "object" && Array.isArray(type.type.choose)) {
+		return type.type.choose.join("/");
+	}
+	return "unknown";
+}
+
+// --- Extract AC from raw ac field ---
+
+function extractAc(ac) {
+	if (!Array.isArray(ac) || ac.length === 0) return 0;
+	const first = ac[0];
+	if (typeof first === "number") return first;
+	if (typeof first === "object" && typeof first.ac === "number")
+		return first.ac;
+	return 0;
+}
+
+// --- Extract CR from raw cr field ---
+
+function extractCr(cr) {
+	if (typeof cr === "string") return cr;
+	if (typeof cr === "object" && typeof cr.cr === "string") return cr.cr;
+	return "0";
+}
+
+// --- Main ---
+
+const sourceMap = buildSourceMap();
+const files = readdirSync(BESTIARY_DIR).filter(
+	(f) => f.startsWith("bestiary-") && f.endsWith(".json"),
+);
+
+const creatures = [];
+const unmappedSources = new Set();
+
+for (const file of files.sort()) {
+	const raw = JSON.parse(readFileSync(join(BESTIARY_DIR, file), "utf-8"));
+	const monsters = raw.monster ?? [];
+
+	for (const m of monsters) {
+		// Skip creatures that are copies/references (no actual stats)
+		if (m._copy || m.hp == null || m.ac == null) continue;
+
+		const source = m.source ?? "";
+		if (source && !sourceMap[source]) {
+			unmappedSources.add(source);
+		}
+
+		creatures.push({
+			n: m.name,
+			s: source,
+			ac: extractAc(m.ac),
+			hp: m.hp.average ?? 0,
+			dx: m.dex ?? 10,
+			cr: extractCr(m.cr),
+			ip: m.initiative?.proficiency ?? 0,
+			sz: Array.isArray(m.size) ? m.size[0] : (m.size ?? "M"),
+			tp: extractType(m.type),
+		});
+	}
+}
+
+// Sort by name then source for stable output
+creatures.sort((a, b) => a.n.localeCompare(b.n) || a.s.localeCompare(b.s));
+
+// Filter sourceMap to only include sources that appear in the index
+const usedSources = new Set(creatures.map((c) => c.s));
+const filteredSourceMap = {};
+for (const [key, value] of Object.entries(sourceMap)) {
+	if (usedSources.has(key)) {
+		filteredSourceMap[key] = value;
+	}
+}
+
+const output = {
+	sources: filteredSourceMap,
+	creatures,
+};
+
+writeFileSync(OUTPUT_PATH, JSON.stringify(output));
+
+// Stats
+const rawSize = Buffer.byteLength(JSON.stringify(output));
+console.log(`Sources: ${Object.keys(filteredSourceMap).length}`);
+console.log(`Creatures: ${creatures.length}`);
+console.log(`Output size: ${(rawSize / 1024).toFixed(1)} KB`);
+if (unmappedSources.size > 0) {
+	console.log(`Unmapped sources: ${[...unmappedSources].sort().join(", ")}`);
+}

specs/001-advance-turn/plan.md

@@ -1,349 +0,0 @@
-# Implementation Plan: Advance Turn
-
-**Branch**: `001-advance-turn` | **Date**: 2026-03-03 | **Spec**: [spec.md](./spec.md)
-**Input**: Feature specification from `/specs/001-advance-turn/spec.md`
-
-## Summary
-
-Implement the AdvanceTurn domain operation as a pure function that
-transitions an Encounter to the next combatant, wrapping rounds and
-emitting TurnAdvanced / RoundAdvanced domain events. Stand up the
-pnpm monorepo skeleton, Biome tooling, and Vitest test harness so
-that all constitution merge-gate requirements are satisfied from the
-first commit.
-
-## Technical Context
-
-**Node**: 22 LTS (pinned via `.nvmrc`)
-**Language/Version**: TypeScript 5.8 (strict mode)
-**Primary Dependencies**: React 19 (pin to major; minor upgrades
-allowed), Vite 6.2
-**Storage**: In-memory only (MVP baseline)
-**Testing**: Vitest 3.0
-**Lint/Format**: Biome 2.0.0 (exact version, single tool — no
-Prettier, no ESLint)
-**Package Manager**: pnpm 10.6 (pinned via `packageManager` field
-in root `package.json`)
-**Target Platform**: Static web app (modern browsers)
-**Project Type**: Monorepo — library packages + web app
-**Performance Goals**: N/A (walking skeleton)
-**Constraints**: Domain package must have zero React/Vite imports
-**Scale/Scope**: Single feature, ~5 source files, ~1 test file
-
-## Constitution Check
-
-| Principle | Status | Notes |
-|-----------|--------|-------|
-| I. Deterministic Domain Core | PASS | `advanceTurn` is a pure function; no I/O, randomness, or clocks |
-| II. Layered Architecture | PASS | `packages/domain` → `packages/application` → `apps/web`; strict dependency direction enforced by automated import check |
-| III. Agent Boundary | N/A | Agent layer out of scope for this feature |
-| IV. Clarification-First | PASS | No ambiguous decisions remain; spec fully clarified |
-| V. Escalation Gates | PASS | Scope strictly limited to spec; out-of-scope items listed |
-| VI. MVP Baseline Language | PASS | No permanent bans; "MVP baseline does not include" used |
-| VII. No Gameplay Rules | PASS | No gameplay mechanics in plan or constitution |
-| Merge Gate | PASS | `pnpm check` script runs format, lint, typecheck, test |
-
-## Project Structure
-
-### Documentation (this feature)
-
-```text
-specs/001-advance-turn/
-├── spec.md
-└── plan.md
-```
-
-### Source Code (repository root)
-
-```text
-packages/
-├── domain/
-│   ├── package.json
-│   ├── tsconfig.json
-│   └── src/
-│       ├── types.ts          # CombatantId, Combatant, Encounter
-│       ├── events.ts         # TurnAdvanced, RoundAdvanced, DomainEvent
-│       ├── advance-turn.ts   # advanceTurn pure function
-│       └── index.ts          # public barrel export
-├── application/
-│   ├── package.json
-│   ├── tsconfig.json
-│   └── src/
-│       ├── ports.ts          # EncounterStore port interface
-│       ├── advance-turn-use-case.ts
-│       └── index.ts
-apps/
-└── web/
-    ├── package.json
-    ├── tsconfig.json
-    ├── vite.config.ts
-    ├── index.html
-    └── src/
-        ├── main.tsx
-        ├── App.tsx
-        └── hooks/
-            └── use-encounter.ts
-
-# Testing (co-located with domain package)
-packages/domain/
-└── src/
-    └── __tests__/
-        └── advance-turn.test.ts
-
-# Root config
-├── .nvmrc                    # pins Node 22
-├── pnpm-workspace.yaml
-├── biome.json
-├── tsconfig.base.json
-└── package.json              # packageManager field pins pnpm; root scripts
-```
-
-**Structure Decision**: pnpm workspace monorepo with two packages
-(`domain`, `application`) and one app (`web`). Domain is
-framework-agnostic TypeScript. Application imports domain only.
-Web app (React + Vite) imports both.
-
-## Tooling & Merge Gate
-
-### Scripts (root package.json)
-
-```jsonc
-{
-  "scripts": {
-    "format": "biome format --write .",
-    "format:check": "biome format .",
-    "lint": "biome lint .",
-    "lint:fix": "biome lint --write .",
-    "typecheck": "tsc --build",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "check": "biome check . && tsc --build && vitest run"
-  }
-}
-```
-
-`pnpm check` is the single merge gate: format + lint + typecheck +
-test. The layer boundary check runs as a Vitest test (see below),
-so it executes as part of `vitest run` — no separate script needed.
-
-### Layer Boundary Enforcement
-
-Biome does not natively support cross-package import restrictions.
-A lightweight `scripts/check-layer-boundaries.mjs` script will:
-
-1. Scan `packages/domain/src/**/*.ts` — assert zero imports from
-   `@initiative/application`, `apps/`, `react`, `vite`.
-2. Scan `packages/application/src/**/*.ts` — assert zero imports
-   from `apps/`, `react`, `vite`.
-3. Exit non-zero on violation with a clear error message.
-
-This script is invoked by a Vitest test
-(`packages/domain/src/__tests__/layer-boundaries.test.ts`) so it
-runs automatically as part of `vitest run` inside `pnpm check`.
-No separate `check:layer` script is needed — the layer boundary
-check is guaranteed to execute on every merge-gate run.
-
-### Biome Configuration (biome.json)
-
-```jsonc
-{
-  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
-  "organizeImports": { "enabled": true },
-  "formatter": {
-    "enabled": true,
-    "indentStyle": "tab",
-    "lineWidth": 80
-  },
-  "linter": {
-    "enabled": true,
-    "rules": {
-      "recommended": true
-    }
-  }
-}
-```
-
-### TypeScript Configuration
-
-- `tsconfig.base.json` at root: strict mode, composite projects,
-  path aliases (`@initiative/domain`, `@initiative/application`).
-- Each package extends `tsconfig.base.json` with its own
-  `include`/`references`.
-- `apps/web/tsconfig.json` references both packages.
-
-## Milestones
-
-### Milestone 1: Tooling & Domain (walking skeleton)
-
-Stand up monorepo, Biome, Vitest, TypeScript project references,
-and implement the complete AdvanceTurn domain logic with all tests.
-
-**Exit criteria**: `pnpm check` passes. All 8 acceptance scenarios
-green. Layer boundary check green. No React or Vite dependencies in
-`packages/domain` or `packages/application`.
-
-### Milestone 2: Application + Minimal Web Shell
-
-Wire up the application use case and a minimal React UI that
-displays the encounter state and has a single "Next Turn" button.
-
-**Exit criteria**: `pnpm check` passes. Clicking "Next Turn" in the
-browser advances the turn with correct round wrapping. The app
-builds with `vite build`.
-
-## Task List
-
-### Phase 1: Setup (Milestone 1)
-
-- [X] **T001** Initialize pnpm workspace and root config
-  - Create `pnpm-workspace.yaml` listing `packages/*` and `apps/*`
-  - Create `.nvmrc` pinning Node 22
-  - Create root `package.json` with `packageManager` field pinning
-    pnpm 10.6 and scripts (check, test, lint, format, typecheck)
-  - Create `biome.json` at root
-  - Create `tsconfig.base.json` (strict, composite, path aliases)
-  - **Acceptance**: `pnpm install` succeeds; `biome check .` runs
-    without config errors
-
-- [X] **T002** [P] Create `packages/domain` package skeleton
-  - `package.json` (name: `@initiative/domain`, no dependencies)
-  - `tsconfig.json` extending base, composite: true
-  - Empty `src/index.ts`
-  - **Acceptance**: `tsc --build packages/domain` succeeds
-
-- [X] **T003** [P] Create `packages/application` package skeleton
-  - `package.json` (name: `@initiative/application`,
-    depends on `@initiative/domain`)
-  - `tsconfig.json` extending base, references domain
-  - Empty `src/index.ts`
-  - **Acceptance**: `tsc --build packages/application` succeeds
-
-- [X] **T004** [P] Create `apps/web` package skeleton
-  - `package.json` with React, Vite, depends on both packages
-  - `tsconfig.json` referencing both packages
-  - `vite.config.ts` (minimal)
-  - `index.html` + `src/main.tsx` + `src/App.tsx` (placeholder)
-  - **Acceptance**: `pnpm --filter web dev` starts; `vite build`
-    succeeds
-
-- [X] **T005** Configure Vitest
-  - Add `vitest` as root dev dependency
-  - Create `vitest.config.ts` at root (workspace mode) or per
-    package as needed
-  - Verify `pnpm test` runs (0 tests, exits clean)
-  - **Acceptance**: `pnpm test` exits 0
-
-- [X] **T006** Create layer boundary check script
-  - `scripts/check-layer-boundaries.mjs`: scans domain and
-    application source for forbidden imports
-  - `packages/domain/src/__tests__/layer-boundaries.test.ts`:
-    wraps the script as a Vitest test
-  - **Acceptance**: test passes on clean skeleton; fails if a
-    forbidden import is manually added (verify, then remove)
-
-### Phase 2: Domain Implementation (Milestone 1)
-
-- [ ] **T007** Define domain types in `packages/domain/src/types.ts`
-  - `CombatantId` (branded string or opaque type)
-  - `Combatant` (carries a CombatantId)
-  - `Encounter` (combatants array, activeIndex, roundNumber)
-  - Factory function `createEncounter` that validates INV-1, INV-2,
-    INV-3
-  - **Acceptance**: types compile; `createEncounter([])` returns
-    error; `createEncounter([a])` returns valid Encounter
-
-- [ ] **T008** [P] Define domain events in
-  `packages/domain/src/events.ts`
-  - `TurnAdvanced { previousCombatantId, newCombatantId,
-    roundNumber }`
-  - `RoundAdvanced { newRoundNumber }`
-  - `DomainEvent = TurnAdvanced | RoundAdvanced`
-  - **Acceptance**: types compile; events are plain data (no
-    classes with methods)
-
-- [ ] **T009** Implement `advanceTurn` in
-  `packages/domain/src/advance-turn.ts`
-  - Signature: `(encounter: Encounter) =>
-    { encounter: Encounter; events: DomainEvent[] } | DomainError`
-  - Implements FR-001 through FR-005
-  - Returns error for empty combatant list (INV-1)
-  - Emits TurnAdvanced on every call (INV-5)
-  - Emits TurnAdvanced then RoundAdvanced on wrap (event order
-    contract)
-  - **Acceptance**: compiles; satisfies type contract
-
-- [ ] **T010** Write tests for all 8 acceptance scenarios +
-  invariants in
-  `packages/domain/src/__tests__/advance-turn.test.ts`
-  - Scenarios 1–8 from spec (Given/When/Then)
-  - INV-1: empty encounter rejected
-  - INV-2: activeIndex always in bounds (property check across
-    scenarios)
-  - INV-3: roundNumber never decreases
-  - INV-4: determinism — same input produces same output (call
-    twice, assert deep equal)
-  - INV-5: every success emits at least TurnAdvanced
-  - Event ordering: on wrap, events array is
-    [TurnAdvanced, RoundAdvanced] in that order
-  - **Acceptance**: `pnpm test` — all tests green; `pnpm check` —
-    full pipeline green
-
-- [ ] **T011** Export public API from `packages/domain/src/index.ts`
-  - Re-export types, events, `advanceTurn`, `createEncounter`
-  - **Acceptance**: consuming packages can
-    `import { advanceTurn } from "@initiative/domain"`
-
-**Milestone 1 checkpoint**: `pnpm check` passes (format + lint +
-typecheck + test + layer boundaries). All 8 scenarios + invariants
-green.
-
-### Phase 3: Application + Web Shell (Milestone 2)
-
-- [ ] **T012** Define port interface in
-  `packages/application/src/ports.ts`
-  - `EncounterStore` port: `get(): Encounter`, `save(e: Encounter)`
-  - **Acceptance**: compiles; no imports from adapters or React
-
-- [ ] **T013** Implement `AdvanceTurnUseCase` in
-  `packages/application/src/advance-turn-use-case.ts`
-  - Accepts `EncounterStore` port
-  - Calls `advanceTurn` from domain, saves result, returns events
-  - **Acceptance**: compiles; imports only from `@initiative/domain`
-    and local ports
-
-- [ ] **T014** Export public API from
-  `packages/application/src/index.ts`
-  - Re-export use case and port types
-  - **Acceptance**: consuming app can import from
-    `@initiative/application`
-
-- [ ] **T015** Implement `useEncounter` hook in
-  `apps/web/src/hooks/use-encounter.ts`
-  - In-memory implementation of `EncounterStore` port (React state)
-  - Exposes current encounter state + `advanceTurn` action
-  - Initializes with a hardcoded 3-combatant encounter for demo
-  - **Acceptance**: hook compiles; usable in a React component
-
-- [ ] **T016** Wire up `App.tsx`
-  - Display: current combatant name, round number, combatant list
-    with active indicator
-  - Single "Next Turn" button calling the use case
-  - Display emitted events (optional, for demo clarity)
-  - **Acceptance**: `vite build` succeeds; clicking "Next Turn"
-    cycles through combatants and increments rounds correctly
-
-**Milestone 2 checkpoint**: `pnpm check` passes. App runs in
-browser. Full round-trip from button click → domain pure function →
-UI update verified manually.
-
-## Risks & Open Questions
-
-| # | Item | Severity | Mitigation |
-|---|------|----------|------------|
-| 1 | pnpm workspace + TypeScript project references can have path resolution quirks with Vite | Low | Use `vite-tsconfig-paths` plugin if needed; test early in T004 |
-| 2 | Biome config format may change across versions | Low | Pinned to exact 2.0.0; `$schema` in config validates structure |
-| 3 | Layer boundary script is a lightweight grep — not a full architectural fitness function | Low | Sufficient for walking skeleton; can upgrade to a Biome plugin or `dependency-cruiser` later if needed |
-
-## Complexity Tracking
-
-No constitution violations. No complexity justifications needed.

specs/001-advance-turn/spec.md

@@ -1,172 +0,0 @@
-# Feature Specification: Advance Turn
-
-**Feature Branch**: `001-advance-turn`
-**Created**: 2026-03-03
-**Status**: Draft
-**Input**: Walking-skeleton domain feature — deterministic turn advancement
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Advance Turn (Priority: P1)
-
-A game master running an encounter advances the turn to the next
-combatant in initiative order. When the last combatant in the round
-finishes, the round number increments and play wraps to the first
-combatant.
-
-**Why this priority**: This is the irreducible core of an initiative
-tracker. Without turn advancement, no other feature has meaning.
-
-**Independent Test**: Can be fully tested as a pure state transition
-with no I/O, persistence, or UI. Given an Encounter value and an
-AdvanceTurn action, assert the resulting Encounter value and emitted
-domain events.
-
-**Acceptance Scenarios**:
-
-1. **Given** an encounter with combatants [A, B, C], activeIndex 0,
-   roundNumber 1,
-   **When** AdvanceTurn,
-   **Then** activeIndex is 1, roundNumber is 1,
-   and a TurnAdvanced event is emitted with
-   previousCombatantId A, newCombatantId B, roundNumber 1.
-
-2. **Given** an encounter with combatants [A, B, C], activeIndex 1,
-   roundNumber 1,
-   **When** AdvanceTurn,
-   **Then** activeIndex is 2, roundNumber is 1,
-   and a TurnAdvanced event is emitted with
-   previousCombatantId B, newCombatantId C, roundNumber 1.
-
-3. **Given** an encounter with combatants [A, B, C], activeIndex 2,
-   roundNumber 1,
-   **When** AdvanceTurn,
-   **Then** activeIndex is 0, roundNumber is 2,
-   and events are emitted in order: TurnAdvanced
-   (previousCombatantId C, newCombatantId A, roundNumber 2) then
-   RoundAdvanced (newRoundNumber 2).
-
-4. **Given** an encounter with combatants [A, B, C], activeIndex 2,
-   roundNumber 5,
-   **When** AdvanceTurn,
-   **Then** activeIndex is 0, roundNumber is 6,
-   and events are emitted in order: TurnAdvanced then RoundAdvanced
-   (verifies round increment is not hardcoded to 2).
-
-5. **Given** an encounter with a single combatant [A], activeIndex 0,
-   roundNumber 1,
-   **When** AdvanceTurn,
-   **Then** activeIndex is 0, roundNumber is 2,
-   and events are emitted in order: TurnAdvanced
-   (previousCombatantId A, newCombatantId A, roundNumber 2) then
-   RoundAdvanced (newRoundNumber 2).
-
-6. **Given** an encounter with combatants [A, B], activeIndex 0,
-   roundNumber 1,
-   **When** AdvanceTurn is applied twice in sequence,
-   **Then** after the first: activeIndex 1, roundNumber 1;
-   after the second: activeIndex 0, roundNumber 2.
-
-7. **Given** an encounter with an empty combatant list,
-   **When** AdvanceTurn,
-   **Then** the operation MUST fail with an invalid-encounter error.
-   No events are emitted. State is unchanged.
-
-8. **Given** an encounter with combatants [A, B, C], activeIndex 0,
-   roundNumber 1,
-   **When** AdvanceTurn is applied three times,
-   **Then** the encounter completes a full round cycle:
-   activeIndex returns to 0 and roundNumber is 2.
-
----
-
-### Edge Cases
-
-- Empty combatant list: valid aggregate state, but AdvanceTurn MUST
-  return a DomainError (no state change, no events).
-- Single combatant: every advance wraps and increments the round.
-- Large round numbers: no overflow or special-case behavior; round
-  increments uniformly.
-
-## Clarifications
-
-### Session 2026-03-03
-
-- Q: Should an encounter with zero combatants be a valid aggregate state? → A: Yes. Empty encounter is valid; AdvanceTurn returns DomainError.
-- Q: What is activeIndex when combatants list is empty? → A: activeIndex MUST be 0.
-- Q: Does this change any non-empty encounter behavior? → A: No. All existing acceptance scenarios and event contracts remain unchanged.
-
-## Domain Model *(mandatory)*
-
-### Key Entities
-
-- **Combatant**: An identified participant in the encounter. For this
-  feature, a combatant is an opaque identity (e.g., a name or id).
-  The MVP baseline does not include HP, conditions, or stats.
-- **Encounter**: The aggregate root. Contains an ordered list of
-  combatants (pre-sorted by initiative), an activeIndex pointing to
-  the current combatant, and a roundNumber (positive integer,
-  starting at 1).
-
-### Domain Events
-
-- **TurnAdvanced**: Emitted on every successful AdvanceTurn.
-  Carries: previousCombatantId, newCombatantId, roundNumber.
-- **RoundAdvanced**: Emitted when activeIndex wraps past the last
-  combatant. Carries: newRoundNumber.
-
-When a round boundary is crossed, both TurnAdvanced and
-RoundAdvanced MUST be emitted in that order (TurnAdvanced first).
-This emission order is part of the observable domain contract and
-MUST be verified by tests.
-
-### Invariants
-
-- **INV-1**: An encounter MAY have zero combatants (an empty
-  encounter is a valid aggregate state). AdvanceTurn on an empty
-  encounter MUST return a DomainError with no state change and no
-  events.
-- **INV-2**: If combatants.length > 0, activeIndex MUST satisfy
-  0 <= activeIndex < combatants.length. If combatants.length == 0,
-  activeIndex MUST be 0.
-- **INV-3**: roundNumber MUST be a positive integer (>= 1) and MUST
-  only increase (never decrease or reset).
-- **INV-4**: AdvanceTurn MUST be a pure function of the current
-  encounter state. Given identical input, output MUST be identical.
-- **INV-5**: Every successful AdvanceTurn MUST emit at least one
-  domain event (TurnAdvanced). No silent state changes.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The domain MUST expose an AdvanceTurn operation that
-  accepts an Encounter and returns the next Encounter state plus
-  emitted domain events.
-- **FR-002**: AdvanceTurn MUST increment activeIndex by 1, wrapping
-  to 0 when past the last combatant.
-- **FR-003**: When activeIndex wraps to 0, roundNumber MUST
-  increment by 1.
-- **FR-004**: AdvanceTurn on an empty encounter MUST return an error
-  without modifying state or emitting events.
-- **FR-005**: Domain events MUST be returned as values from the
-  operation, not dispatched via side effects.
-
-### Out of Scope (MVP baseline does not include)
-
-- Initiative rolling or combatant ordering logic
-- Hit points, damage, conditions, or status effects
-- Adding or removing combatants mid-encounter
-- Persistence, serialization, or storage
-- UI, CLI, or any adapter layer
-- Agent behavior or suggestions
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: All 8 acceptance scenarios pass as deterministic,
-  pure-function tests with no I/O dependencies.
-- **SC-002**: Invariants INV-1 through INV-5 are verified by tests.
-- **SC-003**: The domain module has zero imports from application,
-  adapter, or agent layers (layer boundary compliance).

specs/001-advance-turn/tasks.md

@@ -1,128 +0,0 @@
-# Tasks: Advance Turn
-
-**Input**: Design documents from `/specs/001-advance-turn/`
-**Prerequisites**: plan.md (required), spec.md (required)
-
-**Organization**: Tasks follow the phased structure from plan.md. There is only one user story (US1 — Advance Turn, P1), so phases map directly to the plan's milestones.
-
-## Format: `[ID] [P?] [Story?] Description`
-
-- **[P]**: Can run in parallel (different files, no dependencies)
-- **[US1]**: User Story 1 — Advance Turn
-- Exact file paths included in every task
-
----
-
-## Phase 1: Setup (Milestone 1 — Tooling)
-
-**Purpose**: Initialize pnpm monorepo, Biome, TypeScript, Vitest, and layer boundary enforcement
-
-- [X] T001 Initialize pnpm workspace and root config — create `pnpm-workspace.yaml`, `.nvmrc` (Node 22), root `package.json` (with `packageManager` pinning pnpm 10.6 and scripts: check, test, lint, format, typecheck), `biome.json`, and `tsconfig.base.json` (strict, composite, path aliases)
-- [X] T002 [P] Create `packages/domain` package skeleton — `packages/domain/package.json` (`@initiative/domain`, no deps), `packages/domain/tsconfig.json` (extends base, composite), empty `packages/domain/src/index.ts`
-- [X] T003 [P] Create `packages/application` package skeleton — `packages/application/package.json` (`@initiative/application`, depends on `@initiative/domain`), `packages/application/tsconfig.json` (extends base, references domain), empty `packages/application/src/index.ts`
-- [X] T004 [P] Create `apps/web` package skeleton — `apps/web/package.json` (React 19, Vite 6.2, depends on both packages), `apps/web/tsconfig.json`, `apps/web/vite.config.ts`, `apps/web/index.html`, `apps/web/src/main.tsx`, `apps/web/src/App.tsx` (placeholder)
-- [X] T005 Configure Vitest — add `vitest` as root dev dependency, create `vitest.config.ts` at root (workspace mode or per-package), verify `pnpm test` exits 0
-- [X] T006 Create layer boundary check — `scripts/check-layer-boundaries.mjs` (scans domain/application for forbidden imports) and `packages/domain/src/__tests__/layer-boundaries.test.ts` (wraps script as Vitest test)
-
-**Checkpoint**: `pnpm install` succeeds, `biome check .` runs, `tsc --build` compiles, `pnpm test` exits 0 with layer boundary test green.
-
----
-
-## Phase 2: Domain Implementation — User Story 1: Advance Turn (Priority: P1) (Milestone 1)
-
-**Goal**: Implement the complete AdvanceTurn domain logic as a pure function with all 8 acceptance scenarios and invariant tests.
-
-**Independent Test**: Pure state transition — given an Encounter value and AdvanceTurn action, assert resulting Encounter and emitted domain events. No I/O, persistence, or UI needed.
-
-- [X] T007 [US1] Define domain types in `packages/domain/src/types.ts` — `CombatantId` (branded/opaque), `Combatant`, `Encounter` (combatants, activeIndex, roundNumber), factory `createEncounter` enforcing INV-1, INV-2, INV-3
-- [X] T008 [P] [US1] Define domain events in `packages/domain/src/events.ts` — `TurnAdvanced`, `RoundAdvanced`, `DomainEvent` union (plain data, no classes)
-- [X] T009 [US1] Implement `advanceTurn` in `packages/domain/src/advance-turn.ts` — pure function `(Encounter) => { encounter, events } | DomainError`, implements FR-001 through FR-005
-- [X] T010 [US1] Write tests for all 8 acceptance scenarios + invariants in `packages/domain/src/__tests__/advance-turn.test.ts` — scenarios 1–8, INV-1 through INV-5, event ordering on round wrap
-- [X] T011 [US1] Export public API from `packages/domain/src/index.ts` — re-export types, events, `advanceTurn`, `createEncounter`
-
-**Checkpoint (Milestone 1)**: `pnpm check` passes (format + lint + typecheck + test + layer boundaries). All 8 scenarios + invariants green. No React/Vite imports in domain or application.
-
----
-
-## Phase 3: Application + Web Shell (Milestone 2)
-
-**Goal**: Wire up the application use case and minimal React UI with a "Next Turn" button.
-
-- [X] T012 Define port interface in `packages/application/src/ports.ts` — `EncounterStore` port: `get(): Encounter`, `save(e: Encounter)`
-- [X] T013 Implement `AdvanceTurnUseCase` in `packages/application/src/advance-turn-use-case.ts` — accepts `EncounterStore`, calls `advanceTurn`, saves result, returns events
-- [X] T014 Export public API from `packages/application/src/index.ts` — re-export use case and port types
-- [X] T015 Implement `useEncounter` hook in `apps/web/src/hooks/use-encounter.ts` — in-memory `EncounterStore` via React state, exposes encounter state + `advanceTurn` action, hardcoded 3-combatant demo
-- [X] T016 Wire up `apps/web/src/App.tsx` — display current combatant, round number, combatant list with active indicator, "Next Turn" button, emitted events
-
-**Checkpoint (Milestone 2)**: `pnpm check` passes. `vite build` succeeds. Clicking "Next Turn" cycles combatants and increments rounds correctly.
-
----
-
-## Dependencies & Execution Order
-
-### Phase Dependencies
-
-- **Phase 1 (Setup)**: No dependencies — start immediately
-- **Phase 2 (Domain)**: Depends on Phase 1 completion
-- **Phase 3 (App + Web)**: Depends on Phase 2 completion (needs domain types and `advanceTurn`)
-
-### Within Phase 1
-
-- T001 must complete first (workspace and root config)
-- T002, T003, T004 can run in parallel [P] after T001
-- T005 depends on T001 (needs root package.json)
-- T006 depends on T002 and T005 (needs domain package + Vitest)
-
-### Within Phase 2
-
-- T007 must complete first (types needed by everything)
-- T008 can run in parallel [P] with T007 (events are independent types)
-- T009 depends on T007 and T008 (uses types and events)
-- T010 depends on T009 (tests the implementation)
-- T011 depends on T007, T008, T009 (exports all public API)
-
-### Within Phase 3
-
-- T012 first (port interface)
-- T013 depends on T012 (uses port)
-- T014 depends on T013 (exports use case)
-- T015 depends on T014 (uses application layer)
-- T016 depends on T015 (uses hook)
-
----
-
-## Parallel Opportunities
-
-```text
-# After T001 completes:
-T002, T003, T004 — all package skeletons in parallel
-
-# After T007 starts:
-T008 — domain events can be written in parallel with types
-
-# Independent stories: only one user story (US1), so parallelism is within-phase only
-```
-
----
-
-## Implementation Strategy
-
-### MVP First (Milestone 1)
-
-1. Complete Phase 1: Setup (T001–T006)
-2. Complete Phase 2: Domain (T007–T011)
-3. **STOP and VALIDATE**: `pnpm check` passes, all 8 scenarios green
-
-### Full Feature (Milestone 2)
-
-4. Complete Phase 3: App + Web Shell (T012–T016)
-5. **VALIDATE**: `pnpm check` passes, app runs in browser
-
----
-
-## Notes
-
-- All task IDs (T001–T016) match plan.md — no scope expansion
-- Single user story (US1: Advance Turn) — no cross-story dependencies
-- Tests (T010) are included as specified in plan.md and spec.md
-- Domain package must have zero React/Vite imports (enforced by T006)

specs/001-combatant-management/spec.md

@@ -0,0 +1,404 @@
+# Feature Specification: Combatant Management
+
+**Feature Branch**: `001-combatant-management`
+**Created**: 2026-03-03
+**Status**: Implemented
+
+## Overview
+
+Combatant Management covers the complete lifecycle of combatants within an encounter: adding (individually or in batch), editing, removing, clearing the entire encounter, persisting encounter state across page reloads, and the confirmation UX applied to all destructive actions.
+
+---
+
+## User Scenarios & Testing *(mandatory)*
+
+### Adding Combatants
+
+**Story A1 — Add a single combatant (Priority: P1)**
+
+A game master adds a new combatant to an existing encounter. The new combatant is appended to the end of the initiative order, allowing late-joining participants or newly discovered enemies to enter combat.
+
+**Acceptance Scenarios**:
+
+1. **Given** an empty encounter (no combatants, activeIndex 0, roundNumber 1), **When** AddCombatant with name "Gandalf", **Then** combatants is [Gandalf], activeIndex is 0, roundNumber is 1, and a CombatantAdded event is emitted with the new combatant's id, name "Gandalf", and position 0.
+
+2. **Given** an encounter with combatants [A, B], activeIndex 0, roundNumber 1, **When** AddCombatant with name "C", **Then** combatants is [A, B, C], activeIndex is 0, roundNumber is 1, and a CombatantAdded event is emitted with position 2.
+
+3. **Given** an encounter with combatants [A, B, C], activeIndex 2, roundNumber 3, **When** AddCombatant with name "D", **Then** combatants is [A, B, C, D], activeIndex is 2, roundNumber is 3, and a CombatantAdded event is emitted with position 3. The active combatant does not change.
+
+4. **Given** an encounter with combatants [A], **When** AddCombatant is applied twice with names "B" then "C", **Then** combatants is [A, B, C] in that order. Each operation emits its own CombatantAdded event.
+
+5. **Given** an encounter with combatants [A, B], **When** AddCombatant with an empty name "", **Then** the operation MUST fail with a validation error. No events are emitted. State is unchanged.
+
+6. **Given** an encounter with combatants [A, B], **When** AddCombatant with a whitespace-only name "   ", **Then** the operation MUST fail with a validation error. No events are emitted. State is unchanged.
+
+---
+
+> **Batch add and custom creature workflows** are defined in `specs/004-bestiary/spec.md` (Stories US-S2, US-S3). Those stories cover the bestiary search dropdown, count badge, batch confirm, and custom creature stat fields. This spec covers only the domain-level AddCombatant operation that those workflows invoke.
+
+---
+
+### Removing Combatants
+
+**Story B1 — Remove a combatant from an active encounter (Priority: P1)**
+
+A game master is running a combat encounter and a combatant is defeated or leaves. The GM removes that combatant. The combatant disappears from the initiative order and the turn continues correctly without disruption.
+
+**Acceptance Scenarios**:
+
+1. **Given** an encounter with combatants [A, B, C] and activeIndex 1 (B's turn), **When** the GM removes combatant C (index 2, after active), **Then** the encounter has [A, B], activeIndex remains 1, roundNumber unchanged, and a CombatantRemoved event is emitted.
+
+2. **Given** an encounter with combatants [A, B, C] and activeIndex 2 (C's turn), **When** the GM removes combatant A (index 0, before active), **Then** the encounter has [B, C], activeIndex becomes 1 (still C's turn), roundNumber unchanged.
+
+3. **Given** an encounter with combatants [A, B, C] and activeIndex 1 (B's turn), **When** the GM removes combatant B (the active combatant), **Then** the encounter has [A, C], activeIndex becomes 1 (C is now active), roundNumber unchanged.
+
+4. **Given** an encounter with combatants [A, B, C] and activeIndex 2 (C's turn, last position), **When** the GM removes combatant C (active and last), **Then** the encounter has [A, B], activeIndex wraps to 0 (A is now active), roundNumber unchanged.
+
+5. **Given** an encounter with combatants [A] and activeIndex 0, **When** the GM removes combatant A, **Then** the encounter has [], activeIndex is 0, roundNumber unchanged.
+
+6. **Given** an encounter with combatants [A, B, C], **When** the GM attempts to remove a combatant with an ID that does not exist, **Then** a domain error is returned with code `"combatant-not-found"`, and the encounter is unchanged.
+
+---
+
+**Story B2 — Inline confirmation before removing (Priority: P1)**
+
+A user clicking the remove (X) button on a combatant row is protected from accidental deletion by a two-step inline confirmation flow.
+
+**Acceptance Scenarios**:
+
+1. **Given** a combatant row is visible, **When** the user clicks the remove (X) button once, **Then** the button transitions to a confirm state showing a checkmark icon on a red/danger background with a scale pulse animation.
+
+2. **Given** the remove button is in confirm state, **When** the user clicks it again, **Then** the combatant is removed from the encounter.
+
+3. **Given** the remove button is in confirm state, **When** 5 seconds elapse without a second click, **Then** the button reverts to its original X icon and default styling.
+
+4. **Given** the remove button is in confirm state, **When** the user clicks outside the button, **Then** the button reverts to its original state without removing the combatant.
+
+5. **Given** the remove button is in confirm state, **When** the user presses Escape, **Then** the button reverts to its original state without removing the combatant.
+
+6. **Given** a destructive button has keyboard focus, **When** the user presses Enter or Space, **Then** the button enters confirm state.
+
+7. **Given** a destructive button is in confirm state with focus, **When** the user presses Enter or Space, **Then** the destructive action executes.
+
+8. **Given** a destructive button is in confirm state with focus, **When** the user presses Escape, **Then** the button reverts to its original state.
+
+9. **Given** a destructive button is in confirm state, **When** the button loses focus (e.g., Tab away), **Then** the button reverts to its original state.
+
+---
+
+### Editing Combatants
+
+**Story C1 — Rename a combatant (Priority: P1)**
+
+A user running an encounter realizes a combatant's name is misspelled or wants to change it. They select the combatant by its identity, provide a new name, and the system updates the combatant in-place while preserving turn order and round state.
+
+**Acceptance Scenarios**:
+
+1. **Given** an encounter with combatants [Alice, Bob], **When** the user updates Bob's name to "Robert", **Then** the encounter contains [Alice, Robert] and a `CombatantUpdated` event is emitted with the combatant's id, old name, and new name.
+
+2. **Given** an encounter with combatants [Alice, Bob] where Bob is the active combatant, **When** the user updates Bob's name to "Robert", **Then** Bob remains the active combatant (active index unchanged) and the round number is preserved.
+
+---
+
+**Story C2 — Error feedback on invalid edit (Priority: P2)**
+
+A user attempts to edit a combatant that no longer exists or provides an invalid name. The system returns a clear error without modifying the encounter.
+
+**Acceptance Scenarios**:
+
+1. **Given** an encounter with combatants [Alice, Bob], **When** the user attempts to update a combatant with a non-existent id, **Then** the system returns a "combatant not found" error and the encounter is unchanged.
+
+2. **Given** an encounter with combatants [Alice, Bob], **When** the user attempts to update Alice's name to an empty string, **Then** the system returns an "invalid name" error and the encounter is unchanged.
+
+3. **Given** an encounter with combatants [Alice, Bob], **When** the user attempts to update Alice's name to a whitespace-only string, **Then** the system returns an "invalid name" error and the encounter is unchanged.
+
+---
+
+**Story C3 — Rename trigger UX (Priority: P1)**
+
+A user wants to rename a combatant. Single-clicking the name opens the stat block panel instead of entering edit mode. To rename, the user double-clicks the name or long-presses on touch devices. A `cursor-text` cursor on hover signals that the name is editable.
+
+**Acceptance Scenarios**:
+
+1. **Given** a combatant row is visible, **When** the user single-clicks the combatant name, **Then** the stat block panel opens or toggles — inline edit mode is NOT entered.
+
+2. **Given** a combatant row is visible, **When** the user double-clicks the combatant name, **Then** inline edit mode is entered for that combatant's name.
+
+3. **Given** a combatant row is visible on a pointer device, **When** the user hovers over the combatant name, **Then** the cursor changes to a text cursor (`cursor-text`) to signal editability.
+
+4. **Given** a combatant row is visible on a touch device, **When** the user long-presses the combatant name, **Then** inline edit mode is entered for that combatant's name.
+
+7. **Given** inline edit mode has been entered (via any trigger), **When** the user types a new name and presses Enter or blurs the field, **Then** the name is committed. **When** the user presses Escape, **Then** the edit is cancelled and the original name is restored.
+
+---
+
+### Clearing the Encounter
+
+**Story D1 — Clear encounter to start fresh (Priority: P1)**
+
+As a DM who has just finished a combat encounter, I want to clear the entire encounter with a single confirmed action so that I can quickly set up a new combat without manually removing each combatant one by one.
+
+**Acceptance Scenarios**:
+
+1. **Given** an encounter with multiple combatants at round 3, **When** the user activates the clear encounter action and confirms, **Then** all combatants are removed, the round number resets to 1, and the active turn index resets to 0.
+
+2. **Given** an encounter with a single combatant, **When** the user activates the clear encounter action and confirms, **Then** the encounter is fully cleared.
+
+3. **Given** an encounter has no combatants, **When** the user views the clear button, **Then** it is disabled and cannot be activated.
+
+---
+
+**Story D2 — Inline confirmation before clearing (Priority: P1)**
+
+A user clicks the trash button to clear the entire encounter. Instead of a browser confirm dialog, the trash button itself transitions into a red confirm state with a checkmark icon and a scale pulse. A second click clears the encounter; otherwise the button reverts after 5 seconds or on dismiss.
+
+**Acceptance Scenarios**:
+
+1. **Given** an encounter has combatants, **When** the user clicks the clear encounter (trash) button once, **Then** the button transitions to a confirm state with a checkmark icon on a red/danger background with a scale pulse animation.
+
+2. **Given** the trash button is in confirm state, **When** the user clicks it again, **Then** the entire encounter is cleared.
+
+3. **Given** the trash button is in confirm state, **When** 5 seconds pass, the user clicks outside, or the user presses Escape, **Then** the button reverts to its original trash icon and default styling without clearing the encounter.
+
+4. **Given** a confirmation prompt is displayed, **When** the user cancels, **Then** the encounter remains unchanged.
+
+---
+
+### Persistence
+
+**Story E1 — Encounter survives page reload (Priority: P1)**
+
+A user is managing a combat encounter. They accidentally refresh the page or their browser restarts. When the page reloads, the encounter is restored exactly as it was — same combatants, same active turn, same round number.
+
+**Acceptance Scenarios**:
+
+1. **Given** an encounter with combatants, active turn, and round number, **When** the user reloads the page, **Then** the encounter is restored with all state intact.
+
+2. **Given** an encounter that has been modified (combatant added, removed, or renamed), **When** the user reloads the page, **Then** the latest state is reflected.
+
+3. **Given** the user advances the turn multiple times, **When** the user reloads the page, **Then** the active turn and round number are preserved.
+
+---
+
+**Story E2 — Fresh start with no saved data (Priority: P2)**
+
+A first-time user opens the application with no previously saved encounter. The application shows the default demo encounter so the user can immediately start exploring.
+
+**Acceptance Scenarios**:
+
+1. **Given** no saved encounter exists in the browser, **When** the user opens the application, **Then** the default demo encounter is displayed.
+
+2. **Given** saved encounter data has been manually cleared from the browser, **When** the user opens the application, **Then** the default demo encounter is displayed.
+
+---
+
+**Story E3 — Graceful handling of corrupt data (Priority: P3)**
+
+Saved data may become invalid (e.g., manually edited in dev tools, schema changes between versions). The application handles this gracefully rather than crashing.
+
+**Acceptance Scenarios**:
+
+1. **Given** the saved encounter data is malformed or unparseable, **When** the user opens the application, **Then** the default demo encounter is displayed and the corrupt data is discarded.
+
+2. **Given** the saved data is missing required fields, **When** the user opens the application, **Then** the default demo encounter is displayed.
+
+---
+
+## Domain Model
+
+### Key Entities
+
+- **Combatant**: An identified participant with a unique `CombatantId` (branded string), a required non-empty `name`, and optional `initiative`, `maxHp`, `currentHp`, `ac`, `conditions`, `isConcentrating`, and `creatureId` fields.
+- **Encounter**: The aggregate root. Contains an ordered `readonly` list of combatants, an `activeIndex` (zero-based integer), and a `roundNumber` (positive integer, starting at 1).
+> Queued Creature and Custom Creature Input entities are defined in `specs/004-bestiary/spec.md`.
+
+### Domain Events
+
+- **CombatantAdded**: Emitted on every successful AddCombatant. Carries: `combatantId`, `name`, `position` (zero-based index).
+- **CombatantRemoved**: Emitted on every successful RemoveCombatant. Carries: `combatantId`, `name`.
+- **CombatantUpdated**: Emitted on every successful EditCombatant. Carries: `combatantId`, `oldName`, `newName`.
+
+### Invariants
+
+- **INV-1**: An encounter MAY have zero combatants (after clearing or removing the last combatant).
+- **INV-2**: If `combatants.length > 0`, `activeIndex` MUST satisfy `0 <= activeIndex < combatants.length`. If `combatants.length == 0`, `activeIndex` MUST be 0.
+- **INV-3**: `roundNumber` MUST be a positive integer (>= 1) and MUST only increase during normal turn advancement. Clearing resets it to 1.
+- **INV-4**: `CombatantId` values MUST be unique within an encounter.
+- **INV-5**: All domain state transitions (add, remove, edit, clear) are pure functions; no I/O, randomness, or clocks.
+- **INV-6**: Every successful state transition emits exactly one corresponding domain event. No silent state changes.
+- **INV-7**: AddCombatant and RemoveCombatant MUST NOT change the `roundNumber`.
+- **INV-8**: EditCombatant MUST NOT change `activeIndex`, `roundNumber`, or the combatant's position in the list.
+
+---
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+#### FR-001 — Add: Append combatant
+The domain MUST expose an AddCombatant operation that accepts an Encounter and a combatant name (plus a pre-generated `CombatantId`), and returns the updated Encounter plus emitted domain events. The new combatant MUST be appended to the end of the combatants list.
+
+#### FR-002 — Add: Reject invalid names
+AddCombatant MUST reject empty or whitespace-only names by returning a `DomainError` without modifying state or emitting events. Name validation trims whitespace; a name that is empty after trimming is invalid.
+
+#### FR-003 — Add: Preserve activeIndex and roundNumber
+AddCombatant MUST NOT alter the `activeIndex` or `roundNumber` of the encounter.
+
+#### FR-004 — Add: Unique CombatantId
+AddCombatant MUST assign a unique `CombatantId` to the new combatant. Id generation is the caller's responsibility (application layer), keeping the domain function pure.
+
+#### FR-005 — Add: Duplicate names allowed
+Duplicate combatant names are permitted. Combatants are distinguished solely by their unique `CombatantId`.
+
+#### FR-006 — Add: UI form
+The UI MUST provide an add-combatant form accessible from the bottom bar. The search field MUST display action-oriented placeholder text (e.g., "Search creatures to add...").
+
+> FR-007 through FR-013 (batch add and custom creature) are defined in `specs/004-bestiary/spec.md` (FR-007–FR-015).
+
+#### FR-014 — Remove: Domain operation
+The domain MUST expose a RemoveCombatant operation that accepts an Encounter and a `CombatantId`, and returns the updated Encounter plus emitted domain events.
+
+#### FR-015 — Remove: Error on unknown ID
+RemoveCombatant MUST return a domain error with code `"combatant-not-found"` when the given `CombatantId` does not match any combatant in the encounter.
+
+#### FR-016 — Remove: activeIndex adjustment
+RemoveCombatant MUST adjust `activeIndex` according to these rules:
+- Removed combatant is **after** the active one: `activeIndex` unchanged.
+- Removed combatant is **before** the active one: `activeIndex` decrements by 1.
+- Removed combatant **is** the active one and is not last: `activeIndex` stays at the same integer value (the next combatant in line becomes active).
+- Removed combatant **is** the active one and **is last**: `activeIndex` wraps to 0.
+- Last remaining combatant is removed (encounter becomes empty): `activeIndex` is set to 0.
+
+#### FR-017 — Remove: roundNumber preserved
+RemoveCombatant MUST preserve `roundNumber` unchanged.
+
+#### FR-018 — Remove: UI control
+The UI MUST provide a remove control for each combatant row.
+
+#### FR-019 — Remove: ConfirmButton
+The remove control MUST use the `ConfirmButton` two-step confirmation pattern (see FR-025 through FR-030). Silent no-op on domain error (combatant already gone).
+
+#### FR-020 — Edit: Domain operation
+The domain MUST expose an EditCombatant operation that accepts an Encounter, a `CombatantId`, and a new name, and returns the updated Encounter plus emitted domain events.
+
+#### FR-021 — Edit: Error on unknown ID
+EditCombatant MUST return a `"combatant-not-found"` error when the provided id does not match any combatant.
+
+#### FR-022 — Edit: Reject invalid names
+EditCombatant MUST return an `"invalid-name"` error when the new name is empty or whitespace-only. The same trimming rules as AddCombatant apply.
+
+#### FR-023 — Edit: Preserve position and counters
+EditCombatant MUST preserve the combatant's position in the list, `activeIndex`, and `roundNumber`. Setting a name to the same value it already has is treated as a valid update; a `CombatantUpdated` event is still emitted.
+
+#### FR-024 — Edit: UI
+The UI MUST provide an inline name-edit mechanism for each combatant, activated by double-clicking the name or long-pressing on touch devices. The name MUST display a `cursor-text` cursor on hover to signal editability. Single-clicking the name MUST open/toggle the stat block panel, not enter edit mode. The updated name MUST be immediately visible after submission.
+
+#### FR-025 — ConfirmButton: Reusable component
+The system MUST provide a reusable `ConfirmButton` component that wraps any icon button to add a two-step confirmation flow.
+
+#### FR-026 — ConfirmButton: Confirm state on first activation
+On first activation (click, Enter, or Space), the button MUST transition to a confirm state displaying a checkmark icon on a red/danger background with a scale pulse animation.
+
+#### FR-027 — ConfirmButton: Auto-revert after 5 seconds
+The button MUST automatically revert to its original state after 5 seconds if not confirmed.
+
+#### FR-028 — ConfirmButton: Cancel on outside click, Escape, or focus loss
+Clicking outside the button, pressing Escape, or moving focus away MUST cancel the confirm state and revert the button.
+
+#### FR-029 — ConfirmButton: Execute on second activation
+A second activation (click, Enter, or Space) while in confirm state MUST execute the destructive action.
+
+#### FR-030 — ConfirmButton: Independent state per instance
+Each `ConfirmButton` instance MUST manage its confirm state independently of other instances.
+
+#### FR-031 — Clear: Domain operation
+The domain MUST expose a ClearEncounter operation that removes all combatants, resets `roundNumber` to 1, and resets `activeIndex` to 0.
+
+#### FR-032 — Clear: UI button with ConfirmButton
+The UI MUST provide a clear encounter button that uses the `ConfirmButton` pattern. The button MUST be disabled when the encounter has no combatants.
+
+#### FR-033 — Clear: Cancellation leaves state unchanged
+Cancelling the confirmation (via timeout, outside click, Escape, or focus loss) MUST leave the encounter completely unchanged.
+
+#### FR-034 — Clear: Cleared state persisted
+After clearing, the empty encounter state MUST be persisted so that a page refresh does not restore the previous encounter.
+
+#### FR-035 — Persistence: Save on every change
+The system MUST save the full encounter state (combatants, `activeIndex`, `roundNumber`) to browser `localStorage` after every state change.
+
+#### FR-036 — Persistence: Restore on load
+The system MUST restore the saved encounter state when the application loads, if valid saved data exists.
+
+#### FR-037 — Persistence: Fallback to demo encounter
+The system MUST fall back to the default demo encounter when no saved data exists or saved data is invalid/corrupt.
+
+#### FR-038 — Persistence: No crash on storage failure
+The system MUST NOT crash or show an error to the user when storage is unavailable or data is corrupt. When storage is unavailable, the application falls back to in-memory-only behavior.
+
+#### FR-039 — Persistence: Preserve combatant identity across reloads
+The system MUST preserve combatant `CombatantId` values, names, and any other persisted fields across reloads, so that new combatants added after a reload do not collide with existing IDs.
+
+#### FR-040 — Domain events as values
+All domain events MUST be returned as plain data values from operations, not dispatched via side effects.
+
+---
+
+## Edge Cases
+
+- **Empty name**: AddCombatant and EditCombatant return a `DomainError`; state and events are unchanged.
+- **Whitespace-only name**: Treated identically to empty name after trimming.
+- **Adding to an empty encounter**: The new combatant becomes the first and only participant; `activeIndex` remains 0.
+- **Adding during mid-round**: `activeIndex` is never shifted by an add operation.
+- **Duplicate combatant names**: Permitted. Combatants are distinguished by `CombatantId`.
+- **Removing the last combatant**: Encounter becomes empty; `activeIndex` is set to 0.
+- **Removing with unknown ID**: Returns `"combatant-not-found"` error; state unchanged. Removing the same ID twice: second call returns an error.
+- **Removing from empty encounter**: Covered by the unknown-ID error (no IDs exist).
+- **Editing a combatant to the same name**: Valid; `CombatantUpdated` event is still emitted.
+- **Editing a combatant in an empty encounter**: Returns `"combatant-not-found"` error.
+- **Clearing an already empty encounter**: The clear button is disabled; no operation is executed.
+- **Clearing and reloading**: The empty (cleared) state is persisted; the previous encounter is not restored.
+- **Storage quota exceeded**: Persistence silently fails; current in-memory session continues normally.
+- **Multiple browser tabs**: MVP baseline does not include cross-tab synchronization. Each tab operates independently; the last tab to save wins.
+> Batch add and custom creature edge cases are defined in `specs/004-bestiary/spec.md`.
+- **ConfirmButton: rapid triple-click**: First click enters confirm state; second executes the action; subsequent clicks are no-ops.
+- **ConfirmButton: component unmounts in confirm state**: The auto-revert timer MUST be cleaned up to prevent memory leaks or stale state updates.
+- **ConfirmButton: two instances in confirm state simultaneously**: Each manages its own state independently.
+- **ConfirmButton: combatant row re-renders while in confirm state**: Confirm state persists through re-renders as long as combatant identity is stable.
+- **Name single-click vs double-click**: A single click on the combatant name opens the stat block panel; only a completed double-click enters inline edit mode. The system must disambiguate between the two gestures.
+- **Touch edit affordance**: No hover-dependent affordance is shown on touch devices. Long-press is the touch equivalent for entering edit mode.
+- **Long-press threshold**: The long-press duration should follow platform conventions (typically ~500ms). A short tap must not trigger edit mode.
+
+---
+
+## Success Criteria *(mandatory)*
+
+- **SC-001**: All add-combatant acceptance scenarios pass as deterministic, pure-function tests with no I/O dependencies.
+- **SC-002**: Adding a combatant to an encounter preserves all existing combatants, their order, `activeIndex`, and `roundNumber` unchanged.
+- **SC-003**: All six remove-combatant acceptance scenarios pass as automated tests covering every `activeIndex` adjustment rule.
+- **SC-004**: The round number never changes as a result of a remove operation.
+- **SC-005**: Users can rename any combatant in the encounter in a single action without disrupting turn order, active combatant, or round number.
+- **SC-006**: Invalid edit attempts (missing combatant, empty or whitespace-only name) produce a domain error with no state change and no emitted events.
+- **SC-007**: All destructive actions (remove combatant, clear encounter) require exactly two deliberate user interactions to execute, eliminating single-click accidental mutations.
+- **SC-008**: The `ConfirmButton` confirm state auto-reverts reliably after 5 seconds. All confirmation flows are fully operable via keyboard alone.
+> SC-009 and SC-010 (batch add and custom creature success criteria) are defined in `specs/004-bestiary/spec.md`.
+- **SC-011**: Users can reload the page and see their encounter fully restored, with zero data loss.
+- **SC-012**: First-time users see the demo encounter immediately on first visit with no extra steps.
+- **SC-013**: 100% of corrupt or missing data scenarios result in a usable application (demo encounter displayed), never a crash or blank screen.
+- **SC-014**: After clearing, the encounter tracker displays an empty state with round and turn counters at their initial values, and this state persists across page refreshes.
+- **SC-015**: The domain module has zero imports from the application, adapter, or UI layers (layer boundary compliance verified by automated check).
+
+---
+
+## Assumptions
+
+- `CombatantId` generation is the caller's responsibility (application layer), keeping domain functions pure and deterministic.
+- Name validation trims whitespace; a name that is empty after trimming is invalid.
+- No uniqueness constraint on combatant names — multiple combatants may share the same name.
+- Clearing results in an empty encounter state (no combatants, `roundNumber` 1, `activeIndex` 0). The user will then add new combatants using the existing add-combatant flow.
+- MVP baseline does not include undo/restore functionality after clearing or removing. Once confirmed, the action is final.
+- MVP baseline does not include encounter history or the ability to save/archive encounters before clearing.
+- A single `localStorage` key is sufficient for the MVP (one encounter at a time).
+- Cross-tab synchronization is not required for the MVP baseline.
+- The `ConfirmButton` 5-second timeout is a fixed value and is not configurable in the MVP baseline.
+- The `Check` icon from the Lucide icon library is used for the `ConfirmButton` confirm state.
+- The inline name-edit mechanism is activated by double-click or long-press (touch). A `cursor-text` cursor on hover signals editability. Single-clicking the name opens the stat block panel.

specs/002-add-combatant/checklists/requirements.md

@@ -1,35 +0,0 @@
-# Specification Quality Checklist: Add Combatant
-
-**Purpose**: Validate specification completeness and quality before proceeding to planning
-**Created**: 2026-03-03
-**Feature**: [spec.md](../spec.md)
-
-## Content Quality
-
-- [x] No implementation details (languages, frameworks, APIs)
-- [x] Focused on user value and business needs
-- [x] Written for non-technical stakeholders
-- [x] All mandatory sections completed
-
-## Requirement Completeness
-
-- [x] No [NEEDS CLARIFICATION] markers remain
-- [x] Requirements are testable and unambiguous
-- [x] Success criteria are measurable
-- [x] Success criteria are technology-agnostic (no implementation details)
-- [x] All acceptance scenarios are defined
-- [x] Edge cases are identified
-- [x] Scope is clearly bounded
-- [x] Dependencies and assumptions identified
-
-## Feature Readiness
-
-- [x] All functional requirements have clear acceptance criteria
-- [x] User scenarios cover primary flows
-- [x] Feature meets measurable outcomes defined in Success Criteria
-- [x] No implementation details leak into specification
-
-## Notes
-
-- All items pass. Spec is ready for `/speckit.clarify` or `/speckit.plan`.
-- Assumption documented: CombatantId is passed in rather than generated internally, keeping domain pure.

specs/002-add-combatant/data-model.md

@@ -1,77 +0,0 @@
-# Data Model: Add Combatant
-
-**Feature**: 002-add-combatant
-**Date**: 2026-03-03
-
-## Entities
-
-### Combatant (existing, unchanged)
-
-| Field | Type | Constraints |
-|-------|------|-------------|
-| id | CombatantId (branded string) | Unique, required |
-| name | string | Non-empty after trimming, required |
-
-### Encounter (existing, unchanged)
-
-| Field | Type | Constraints |
-|-------|------|-------------|
-| combatants | readonly Combatant[] | Ordered list, may be empty |
-| activeIndex | number | 0 <= activeIndex < combatants.length (or 0 if empty) |
-| roundNumber | number | Positive integer >= 1, only increases |
-
-## Domain Events
-
-### CombatantAdded (new)
-
-| Field | Type | Description |
-|-------|------|-------------|
-| type | "CombatantAdded" (literal) | Discriminant for the DomainEvent union |
-| combatantId | CombatantId | Id of the newly added combatant |
-| name | string | Name of the newly added combatant |
-| position | number | Zero-based index where the combatant was placed |
-
-## State Transitions
-
-### AddCombatant
-
-**Input**: Encounter + CombatantId + name (string)
-
-**Preconditions**:
-- Name must be non-empty after trimming
-
-**Transition**:
-- New combatant `{ id, name: trimmedName }` appended to end of combatants list
-- activeIndex unchanged
-- roundNumber unchanged
-
-**Postconditions**:
-- combatants.length increased by 1
-- New combatant is at index `combatants.length - 1`
-- All existing combatants preserve their order and index positions
-- INV-2 satisfied (activeIndex still valid for the now-larger list)
-
-**Events emitted**: Exactly one `CombatantAdded`
-
-**Error cases**:
-- Empty or whitespace-only name → DomainError `{ code: "invalid-name" }`
-
-## Function Signatures
-
-### Domain Layer
-
-```
-addCombatant(encounter, id, name) → { encounter, events } | DomainError
-```
-
-### Application Layer
-
-```
-addCombatantUseCase(store, id, name) → DomainEvent[] | DomainError
-```
-
-## Validation Rules
-
-| Rule | Layer | Error Code |
-|------|-------|------------|
-| Name non-empty after trim | Domain | invalid-name |

specs/002-add-combatant/plan.md

@@ -1,76 +0,0 @@
-# Implementation Plan: Add Combatant
-
-**Branch**: `002-add-combatant` | **Date**: 2026-03-03 | **Spec**: [spec.md](./spec.md)
-**Input**: Feature specification from `/specs/002-add-combatant/spec.md`
-
-## Summary
-
-Add a pure domain function `addCombatant` that appends a new combatant to the end of an encounter's combatant list without altering the active turn or round. The feature follows the same pattern as `advanceTurn`: a pure function returning updated state plus domain events, with an application-layer use case and a React adapter hook.
-
-## Technical Context
-
-**Language/Version**: TypeScript 5.x (strict mode, verbatimModuleSyntax)
-**Primary Dependencies**: None for domain; React 19 for web adapter
-**Storage**: In-memory (React state via hook)
-**Testing**: Vitest
-**Target Platform**: Browser (Vite dev server)
-**Project Type**: Monorepo (pnpm workspaces): domain library + application library + web app
-**Performance Goals**: N/A (pure synchronous function)
-**Constraints**: Domain must remain pure — no I/O, no randomness
-**Scale/Scope**: Single-user local app
-
-## Constitution Check
-
-*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
-
-| Principle | Status | Notes |
-|-----------|--------|-------|
-| I. Deterministic Domain Core | PASS | `addCombatant` is a pure function. CombatantId is passed in as input, not generated internally. |
-| II. Layered Architecture | PASS | Domain function in `packages/domain`, use case in `packages/application`, hook in `apps/web`. No reverse imports. |
-| III. Agent Boundary | PASS | No agent layer involvement in this feature. |
-| IV. Clarification-First | PASS | Spec has no NEEDS CLARIFICATION markers. Key assumption (id passed in) is documented. |
-| V. Escalation Gates | PASS | Implementation stays within spec scope. |
-| VI. MVP Baseline Language | PASS | Out-of-scope items use "MVP baseline does not include". |
-| VII. No Gameplay Rules | PASS | No gameplay mechanics in constitution. |
-
-All gates pass. No violations to justify.
-
-## Project Structure
-
-### Documentation (this feature)
-
-```text
-specs/002-add-combatant/
-├── plan.md              # This file
-├── research.md          # Phase 0 output
-├── data-model.md        # Phase 1 output
-├── quickstart.md        # Phase 1 output
-└── tasks.md             # Phase 2 output (via /speckit.tasks)
-```
-
-### Source Code (repository root)
-
-```text
-packages/domain/src/
-├── types.ts             # Encounter, Combatant, CombatantId (existing)
-├── events.ts            # DomainEvent union (add CombatantAdded)
-├── add-combatant.ts     # NEW: addCombatant pure function
-├── advance-turn.ts      # Existing (unchanged)
-├── index.ts             # Re-exports (add new exports)
-└── __tests__/
-    ├── advance-turn.test.ts  # Existing (unchanged)
-    └── add-combatant.test.ts # NEW: acceptance + invariant tests
-
-packages/application/src/
-├── ports.ts                      # EncounterStore (unchanged)
-├── add-combatant-use-case.ts     # NEW: orchestrates addCombatant
-├── advance-turn-use-case.ts      # Existing (unchanged)
-└── index.ts                      # Re-exports (add new exports)
-
-apps/web/src/
-├── App.tsx              # Update: add combatant input + button
-└── hooks/
-    └── use-encounter.ts # Update: expose addCombatant callback
-```
-
-**Structure Decision**: Follows the established monorepo layout. Each domain operation gets its own file (matching `advance-turn.ts` pattern). No new packages or directories needed beyond the existing structure.