Fix bestiary creatures with zero HP silently failing to add

Bestiary sources like AWM store 0 for unknown HP. Passing maxHp: 0
into addCombatant triggered domain validation rejection, silently
dropping the creature. Treat hp: 0 as undefined, matching existing
ac: 0 handling.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude/skills/browser-interactive-testing/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: browser-interactive-testing
+description: >
+  This skill should be used when the user asks to "test a web page",
+  "take a screenshot of a site", "automate browser interaction",
+  "create a test report", "verify a page works", or mentions
+  rodney, showboat, headless Chrome testing, or browser automation.
+version: 0.1.0
+---
+
+# Browser Interactive Testing
+
+Test web pages interactively using **rodney** (headless Chrome automation) and document results with **showboat** (executable demo reports).
+
+## Prerequisites
+
+Ensure `uv` is installed. If missing, instruct the user to run:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Do NOT install rodney or showboat globally. Run them via `uvx`:
+
+```bash
+uvx rodney <command>
+uvx showboat <command>
+```
+
+## Rodney Quick Reference
+
+### Start a browser session
+
+```bash
+uvx rodney start            # Launch headless Chrome
+uvx rodney start --show     # Launch visible browser (for debugging)
+uvx rodney connect host:port # Connect to existing Chrome with remote debugging
+```
+
+Use `--local` on all commands to scope the session to the current directory.
+
+### Navigate and inspect
+
+```bash
+uvx rodney open "https://example.com"
+uvx rodney waitload
+uvx rodney title
+uvx rodney url
+uvx rodney text "h1"
+uvx rodney html "#content"
+```
+
+### Interact with elements
+
+```bash
+uvx rodney click "#submit-btn"
+uvx rodney input "#email" "user@example.com"
+uvx rodney select "#country" "US"
+uvx rodney js "document.querySelector('#app').dataset.ready"
+```
+
+### Assert and verify
+
+```bash
+uvx rodney assert "document.title" "My App" -m "Title must match"
+uvx rodney exists ".error-banner"
+uvx rodney visible "#loading-spinner"
+uvx rodney count ".list-item"
+```
+
+Exit code `0` = pass, `1` = fail, `2` = error.
+
+### Screenshots and cleanup
+
+```bash
+uvx rodney screenshot -w 1280 -h 720 page.png
+uvx rodney screenshot-el "#chart" chart.png
+uvx rodney stop
+```
+
+Run `uvx rodney --help` for the full command list, including tab management, navigation, waiting, accessibility tree inspection, and PDF export.
+
+## Showboat Quick Reference
+
+```bash
+uvx showboat init report.md "Test Report Title"
+uvx showboat note report.md "Description of what we are testing."
+uvx showboat exec report.md bash "uvx rodney title --local"
+uvx showboat image report.md '![Page screenshot](screenshot.png)'
+uvx showboat pop report.md          # Remove last entry (fix mistakes)
+uvx showboat verify report.md       # Re-run all code blocks and diff
+uvx showboat extract report.md      # Print commands that recreate the document
+```
+
+Run `uvx showboat --help` for details on `--workdir`, `--output`, `--filename`, and stdin piping.
+
+## Output Directory
+
+Save all reports under `.agent-tests/` in the project root:
+
+```
+.agent-tests/
+└── YYYY-MM-DD-<slug>/
+    ├── report.md
+    └── screenshots/
+```
+
+Derive the slug from the test subject (e.g., `login-flow`, `homepage-layout`). Keep it lowercase, hyphen-separated, max ~30 chars. If a directory with the same date and slug already exists, append a numeric suffix (e.g., `tetris-game-2`) or choose a more specific slug (e.g., `tetris-controls` instead of reusing `tetris-game`).
+
+### Setup Script
+
+Run the bundled `scripts/setup.py` to create the directory, init the report, start the browser, and capture `DIR` in one step. Replace `<SKILL_DIR>` with the actual path to the directory containing this skill's files:
+
+```bash
+DIR=$(python3 <SKILL_DIR>/scripts/setup.py "<slug>" "<Report Title>")
+```
+
+This single command:
+1. Creates `.agent-tests/YYYY-MM-DD-<slug>/screenshots/`
+2. Adds `.rodney/` to `.gitignore` (if `.gitignore` exists)
+3. Runs `showboat init` for the report
+4. Starts a browser (connects to existing, launches system Chrome/Chromium, or falls back to rodney's built-in launcher)
+5. Prints the directory path to stdout (all status messages go to stderr)
+
+After setup, `$DIR` is ready for use with all subsequent commands.
+
+**Important:** The `--local` flag stores session data in `.rodney/` relative to the current working directory. Do NOT `cd` to a different directory during the session, or rodney will lose the connection. Use absolute paths for file arguments instead.
+
+## Workflow
+
+1. **Setup** — Run the setup script to create the dir, init the report, start the browser, and set `$DIR`
+2. **Describe the test** — `uvx showboat note "$DIR/report.md" "Testing [subject] for [goals]."` so the report has context up front
+3. **Open page** — `uvx showboat exec "$DIR/report.md" bash "uvx rodney open --local 'URL' && uvx rodney waitload --local"`
+4. **Add a note** before each test group — Use a heading followed by a short explanation of what the tests in this section verify and why it matters. Use unique section titles; avoid duplicating headings within the same report.
+   ```bash
+   uvx showboat note "$DIR/report.md" "## Keyboard Controls"
+   uvx showboat note "$DIR/report.md" "Verify arrow keys move and rotate the active piece, and that soft/hard drop work correctly."
+   ```
+5. **Run assertions** — Before each assertion, add a short `showboat note` explaining what it checks. Then wrap the `rodney assert` / `rodney js` call in `showboat exec`:
+   ```bash
+   uvx showboat note "$DIR/report.md" "The left arrow key should move the piece one cell to the left."
+   uvx showboat exec "$DIR/report.md" bash "uvx rodney assert --local '...' '...' -m 'Piece moved left'"
+   ```
+6. **Capture screenshots** — Take the screenshot with `rodney screenshot`, then embed with `showboat image`. **Important:** `showboat image` resolves image paths relative to the current working directory, NOT relative to the report file. Always use absolute paths (`$DIR/screenshots/...`) in the markdown image reference to avoid "image file not found" errors:
+   ```bash
+   uvx rodney screenshot --local -w 1280 -h 720 "$DIR/screenshots/01-initial-load.png"
+   uvx showboat image "$DIR/report.md" "![Initial load]($DIR/screenshots/01-initial-load.png)"
+   ```
+   Number screenshots sequentially (`01-`, `02-`, ...) and use descriptive filenames.
+7. **Pop on failure** — If a command fails, run `showboat pop` then retry
+8. **Stop browser** — `uvx rodney stop --local`
+9. **Write summary** — Add a final `showboat note` with a summary section listing all pass/fail results and any bugs found. Every report must end with a summary.
+10. **Verify report** — `uvx showboat verify "$DIR/report.md"`
+
+### Best Practices
+
+- Use `uvx rodney waitload` or `uvx rodney wait <selector>` before interacting with page content.
+- Run `uvx showboat pop` immediately after a failed `exec` to keep the report clean.
+- Prefer `rodney assert` for checks — clear exit codes and self-documenting output.
+- Use `rodney js` only for complex checks or state manipulation that `assert` cannot express.
+- Take screenshots at key stages (initial load, after interaction, error states) for visual evidence.
+- Add a `showboat note` before each logical group of tests with a heading and a short explanation of what the section tests. Use unique heading titles — duplicate headings make the report confusing.
+- Always end reports with a summary `showboat note` listing pass/fail results and any bugs found. This is required, not optional.
+
+## Quoting Rules for `rodney js`
+
+`rodney js` evaluates a single JS **expression** (not statements). Nested shell quoting with `showboat exec` causes most errors. Follow these rules strictly:
+
+1. **Wrap multi-statement JS in an IIFE** — bare `const`, `let`, `for` fail at top level:
+   ```bash
+   # WRONG
+   uvx rodney js --local 'const x = 1; x + 2'
+   # CORRECT
+   uvx rodney js --local '(function(){ var x = 1; return x + 2; })()'
+   ```
+
+2. **Use `var` instead of `const`/`let`** inside IIFEs to avoid strict-mode eval scoping issues.
+
+3. **Direct `rodney js` calls** — use single quotes for the outer shell, double quotes inside JS:
+   ```bash
+   uvx rodney js --local '(function(){ var el = document.querySelector("#app"); return el.textContent; })()'
+   ```
+
+4. **Inside `showboat exec`** — use a heredoc with a **quoted delimiter** (`<<'JSEOF'`) to prevent all shell expansion (`$`, backticks, etc.):
+   ```bash
+   uvx showboat exec "$DIR/report.md" bash "$(cat <<'JSEOF'
+   uvx rodney js --local '
+   (function(){
+     var x = score;
+     hardDrop();
+     return "before:" + x + ",after:" + score;
+   })()
+   '
+   JSEOF
+   )"
+   ```
+   For simple one-liners, single quotes inside the double-quoted bash arg also work:
+   ```bash
+   uvx showboat exec "$DIR/report.md" bash "uvx rodney js --local '(function(){ return String(score); })()'"
+   ```
+
+5. **Avoid without heredoc**: backticks, `$` signs, unescaped double quotes. The heredoc pattern avoids all of these.
+
+6. **Prefer `rodney assert` over `rodney js`** when possible — separate arguments avoid quoting entirely.
+
+7. **Pop after syntax errors** — always `showboat pop` before retrying to keep the report clean.

.claude/skills/browser-interactive-testing/scripts/setup.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""Set up a browser-interactive-testing session.
+
+Creates the output directory, inits the showboat report, starts a browser,
+and prints the DIR path. Automatically detects whether rodney can launch
+its own Chromium or falls back to a system-installed browser.
+"""
+
+import datetime
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import time
+
+REMOTE_DEBUG_PORT = 9222
+
+
+def find_system_browser():
+    """Return the path to a system Chrome/Chromium binary, or None."""
+    for name in ["chromium", "chromium-browser", "google-chrome", "google-chrome-stable"]:
+        path = shutil.which(name)
+        if path:
+            return path
+    return None
+
+
+def port_listening(port):
+    """Check if something is already listening on the given port."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.settimeout(1)
+        return s.connect_ex(("localhost", port)) == 0
+
+
+def try_connect(port):
+    """Try to connect rodney to a browser on the given port. Returns True on success."""
+    result = subprocess.run(
+        ["uvx", "rodney", "connect", "--local", f"localhost:{port}"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0:
+        print(f"Connected to existing browser on port {port}", file=sys.stderr)
+        return True
+    return False
+
+
+def launch_system_browser(browser_path):
+    """Launch a system browser with remote debugging and wait for it to be ready."""
+    subprocess.Popen(
+        [
+            browser_path,
+            "--headless",
+            "--disable-gpu",
+            f"--remote-debugging-port={REMOTE_DEBUG_PORT}",
+            "--no-sandbox",
+        ],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    # Wait for the browser to start listening
+    for _ in range(20):
+        if port_listening(REMOTE_DEBUG_PORT):
+            return True
+        time.sleep(0.25)
+    return False
+
+
+def start_browser():
+    """Start a headless browser and connect rodney to it.
+
+    Strategy order (fastest path first):
+    1. Connect to an already-running browser on the debug port.
+    2. Launch a system Chrome/Chromium (avoids rodney's Chromium download,
+       which fails on some architectures like Linux ARM64).
+    3. Let rodney launch its own browser as a last resort.
+    """
+    # Strategy 1: connect to an already-running browser
+    if port_listening(REMOTE_DEBUG_PORT) and try_connect(REMOTE_DEBUG_PORT):
+        return
+
+    # Strategy 2: launch a system browser (most reliable on Linux)
+    browser = find_system_browser()
+    if browser:
+        print(f"Launching system browser: {browser}", file=sys.stderr)
+        if launch_system_browser(browser):
+            if try_connect(REMOTE_DEBUG_PORT):
+                return
+            print("WARNING: system browser started but rodney could not connect", file=sys.stderr)
+        else:
+            print("WARNING: system browser did not start in time", file=sys.stderr)
+
+    # Strategy 3: let rodney try its built-in launcher
+    result = subprocess.run(
+        ["uvx", "rodney", "start", "--local"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0:
+        print("Browser started via rodney", file=sys.stderr)
+        return
+
+    print(
+        "ERROR: Could not start a browser. Tried:\n"
+        f"  - Connecting to localhost:{REMOTE_DEBUG_PORT} (no browser found)\n"
+        f"  - System browser: {browser or 'not found'}\n"
+        "  - rodney start (failed)\n"
+        "Install chromium or google-chrome and try again.",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+
+def ensure_gitignore_entry(entry):
+    """Add entry to .gitignore if the file exists and the entry is missing."""
+    gitignore = ".gitignore"
+    if not os.path.isfile(gitignore):
+        return
+    with open(gitignore, "r") as f:
+        content = f.read()
+    # Check if the entry (with or without trailing slash/newline variations) is already present
+    lines = content.splitlines()
+    if any(line.strip() == entry or line.strip() == entry.rstrip("/") for line in lines):
+        return
+    # Append the entry
+    with open(gitignore, "a") as f:
+        if content and not content.endswith("\n"):
+            f.write("\n")
+        f.write(f"{entry}\n")
+    print(f"Added '{entry}' to .gitignore", file=sys.stderr)
+
+
+def main():
+    if len(sys.argv) < 3:
+        print(f"Usage: {sys.argv[0]} <slug> <report-title>", file=sys.stderr)
+        sys.exit(1)
+
+    slug = sys.argv[1]
+    title = sys.argv[2]
+
+    # Create output directory
+    d = f".agent-tests/{datetime.date.today()}-{slug}"
+    os.makedirs(f"{d}/screenshots", exist_ok=True)
+
+    # Ensure .rodney/ is in .gitignore (rodney stores session files there)
+    ensure_gitignore_entry(".rodney/")
+
+    # Init showboat report
+    subprocess.run(["uvx", "showboat", "init", f"{d}/report.md", title], check=True)
+
+    # Start browser
+    start_browser()
+
+    # Print the directory path (only real stdout, everything else goes to stderr)
+    print(d)
+
+
+if __name__ == "__main__":
+    main()

.claude/skills/commit/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: commit
+description: Create a git commit with pre-commit hooks (bypasses sandbox restrictions).
+disable-model-invocation: true
+allowed-tools: Bash(git *), Bash(pnpm *)
+---
+
+## Instructions
+
+Create a git commit for the current staged and/or unstaged changes.
+
+### Step 1 — Assess changes
+
+Run these in parallel:
+
+```bash
+git status
+```
+
+```bash
+git diff
+```
+
+```bash
+git log --oneline -5
+```
+
+### Step 2 — Draft commit message
+
+- Summarize the nature of the changes (new feature, enhancement, bug fix, refactor, test, docs, etc.)
+- Keep the first line concise (under 72 chars), use imperative mood
+- Add a blank line and a short body if the "why" isn't obvious from the first line
+- Match the style of recent commits in the log
+- Do not commit files that likely contain secrets (.env, credentials, etc.)
+
+### Step 3 — Stage and commit
+
+Stage relevant files by name (avoid `git add -A` or `git add .`). Then commit.
+
+**CRITICAL:** Always use `dangerouslyDisableSandbox: true` for the commit command. Lefthook pre-commit hooks spawn subprocesses (biome, oxlint, vitest, etc.) that require filesystem access beyond what the sandbox allows. They will always fail with "operation not permitted" in sandbox mode.
+
+Append the co-author trailer:
+
+```
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+```
+
+Use a HEREDOC for the commit message:
+
+```bash
+git commit -m "$(cat <<'EOF'
+<first line>
+
+<optional body>
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+### Step 4 — Verify
+
+Run `git status` after the commit to confirm success.
+
+### If the commit fails
+
+If a pre-commit hook fails, fix the issue, re-stage, and create a **new** commit. Never amend unless explicitly asked — amending after a hook failure would modify the previous commit.
+
+## User arguments
+
+```text
+$ARGUMENTS
+```
+
+If the user provided arguments, treat them as the commit message or guidance for what to commit.

.gitignore

@@ -12,3 +12,6 @@ Thumbs.db
 coverage/
 *.tsbuildinfo
 docs/agents/plans/
+docs/agents/research/
+.agent-tests/
+.rodney/

.jsinspectrc

@@ -0,0 +1,9 @@
+{
+	"threshold": 50,
+	"minInstances": 3,
+	"identifiers": false,
+	"literals": false,
+	"ignore": "dist|__tests__|node_modules",
+	"reporter": "default",
+	"truncate": 100
+}

.specify/memory/constitution.md

@@ -1,9 +1,9 @@
 <!--
   Sync Impact Report
   ───────────────────
-  Version change: 3.0.0 → 3.1.0 (MINOR — new principle II-A: context-based state flow)
+  Version change: 3.1.0 → 3.2.0 (MINOR — artifact lifecycle guidance)
   Modified sections:
-    - Core Principles: added II-A. Context-Based State Flow (max 8 props, context over prop drilling)
+    - Development Workflow: added artifact lifecycle rules (spec.md living, plan/tasks bounded, tests authoritative)
   Templates requiring updates: none
 -->
 # Encounter Console Constitution
@@ -113,6 +113,18 @@ architecture, and quality — not product behavior.
   (which creates a feature branch for the full speckit pipeline);
   changes to existing features update the existing spec via
   `/integrate-issue`.
+- **Artifact lifecycles differ by type**:
+  - `spec.md` is a **living capability document** — it describes what
+    the feature does and is updated whenever the feature meaningfully
+    changes. It survives across multiple rounds of work.
+  - `plan.md` and `tasks.md` are **bounded work packages** — they
+    describe what to do for a specific increment of work. After
+    completion they become historical records. The next round of work
+    on the same feature gets a new plan, not an update to the old one.
+  - Tests are the **executable ground truth**. When a spec's
+    acceptance criteria and the tests disagree, the tests are
+    authoritative. Spec prose captures intent and context; tests
+    capture actual behavior.
 - 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.
@@ -156,4 +168,4 @@ MUST comply with its principles.
 **Compliance review**: Every spec and plan MUST include a
 Constitution Check section validating adherence to all principles.
 
-**Version**: 3.1.0 | **Ratified**: 2026-03-03 | **Last Amended**: 2026-03-19
+**Version**: 3.2.0 | **Ratified**: 2026-03-03 | **Last Amended**: 2026-03-30

CLAUDE.md

@@ -1,11 +1,11 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+**Initiative** is a browser-based combat encounter tracker for tabletop RPGs (D&D 5.5e, Pathfinder 2e). It runs entirely client-side — no backend, no accounts — with localStorage and IndexedDB for persistence.
 
 ## Commands
 
 ```bash
-pnpm check              # Merge gate — must pass before every commit (audit + knip + biome + oxlint + typecheck + test/coverage + jscpd)
+pnpm check              # Merge gate — must pass before every commit (audit + knip + biome + oxlint + typecheck + test/coverage + jscpd + jsinspect)
 pnpm oxlint             # Type-aware linting (oxlint — complements Biome)
 pnpm knip               # Unused code detection (Knip)
 pnpm test               # Run all tests (Vitest)
@@ -30,7 +30,7 @@ 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 (`EncounterStore`, `BestiarySourceCache`). No business logic here.
-- **Web** — React adapter. Implements ports using hooks/state. All UI components, routing, and user interaction live here.
+- **Web** — React adapter. Implements ports using hooks/state. All UI components 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.
 
@@ -60,20 +60,20 @@ docs/agents/               RPI skill artifacts (research reports, plans)
 - React 19, Vite 6, Tailwind CSS v4
 - Lucide React (icons)
 - `idb` (IndexedDB wrapper for bestiary cache)
-- Biome 2.4 (formatting + linting), oxlint (type-aware linting), Knip (unused code), jscpd (copy-paste detection)
+- Biome 2.4 (formatting + linting), oxlint (type-aware linting), Knip (unused code), jscpd (copy-paste detection), jsinspect-plus (structural duplication)
 - Vitest (testing, v8 coverage), Lefthook (pre-commit hooks)
 
 ## Conventions
 
 - **Biome 2.4** for formatting and linting (no Prettier, no ESLint). Tab indentation, 80-char lines. Imports are auto-organized alphabetically.
-- **oxlint** for type-aware linting that Biome can't do (unnecessary type assertions, deprecated APIs, `replaceAll` preference, `String.raw`). Configured in `.oxlintrc.json`.
-- **TypeScript strict mode** with `verbatimModuleSyntax`. Use `.js` extensions in relative imports when required by the repo's ESM settings (e.g., `./types.js`).
+- **oxlint** for type-aware linting that Biome can't do. Configured in `.oxlintrc.json`.
+- **TypeScript strict mode** with `verbatimModuleSyntax`. Use `.js` extensions in relative imports.
 - **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/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`.
-- **Component props** — max 8 explicitly declared props per component interface (enforced by `scripts/check-component-props.mjs`). Use React context for shared state; reserve props for per-instance config (data items, layout variants, refs).
-- **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.
+- **Tests** live in `packages/*/src/__tests__/*.test.ts`. Test pure functions directly; map acceptance scenarios from specs to individual `it()` blocks.
+- **Quality gates** are enforced at pre-commit via Lefthook (parallel jobs). No gate may exist only as a CI step or manual process.
+
+For component prop rules, export format compatibility, and ADRs, see [`docs/conventions.md`](docs/conventions.md).
 
 ## Self-Review Checklist
 
@@ -85,19 +85,7 @@ Before finishing a change, consider:
 
 ## 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
+Specs are **living documents** in `specs/NNN-feature-name/` that describe features, not individual changes. Use `/speckit.*` and RPI skills (`rpi-research`, `rpi-plan`, `rpi-implement`) to manage them — skill descriptions have full usage details.
 
 | Scope | Workflow |
 |---|---|
@@ -106,28 +94,8 @@ Speckit (`/speckit.*` skills) manages the spec-driven development pipeline. Spec
 | 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.
+**Research scope**: Always scan for existing patterns similar to what the feature needs. Identify extraction and consolidation opportunities before implementation, not during.
 
-### 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
 
-## Constitution (key principles)
-
-The constitution (`.specify/memory/constitution.md`) governs all feature work:
-
-1. **Deterministic Domain Core** — Pure state transitions only; no I/O, randomness, or clocks in domain.
-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. **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.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
-- 005-player-characters: Added TypeScript 5.8 (strict mode, `verbatimModuleSyntax`) + React 19, Vite 6, Tailwind CSS v4, Lucide Reac
+Project principles governing all feature work are in [`.specify/memory/constitution.md`](.specify/memory/constitution.md). Key rules: deterministic domain core, strict layer boundaries, clarification before assumptions.

README.md

@@ -1,4 +1,4 @@
-# Encounter Console
+# Initiative
 
 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.
 
@@ -7,7 +7,10 @@ A local-first initiative tracker and encounter manager for tabletop RPGs (D&D 5e
 - **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
+- **Player characters** — create reusable player character templates with name, AC, HP, level, color, and icon; search and add them to encounters with pre-filled stats; manage (edit/delete) from a dedicated panel
+- **Encounter difficulty** — live 3-bar indicator in the top bar showing encounter difficulty (Trivial/Low/Moderate/High) based on the 2024 5.5e XP budget system; automatically derived from PC levels and bestiary creature CRs
+- **Undo/redo** — reverse any encounter action with Undo/Redo buttons or keyboard shortcuts (Ctrl+Z / Ctrl+Shift+Z, Cmd on Mac); history persists across page reloads
+- **Import/export** — export the full encounter state (combatants, undo/redo history, player characters) as a JSON file or copy to clipboard; import from file upload or pasted JSON with validation and confirmation
 - **Persistent** — encounters survive page reloads via localStorage; bestiary data cached in IndexedDB; player characters stored independently
 
 ## Prerequisites
@@ -31,16 +34,42 @@ Open `http://localhost:5173`.
 | `pnpm --filter web dev` | Start the dev server |
 | `pnpm --filter web build` | Production build |
 | `pnpm test` | Run all tests (Vitest) |
-| `pnpm check` | Full merge gate (knip, biome, typecheck, test, jscpd) |
+| `pnpm test:watch` | Tests in watch mode |
+| `pnpm vitest run path/to/test.ts` | Run a single test file |
+| `pnpm typecheck` | TypeScript type checking |
+| `pnpm lint` | Biome lint |
+| `pnpm format` | Biome format (writes changes) |
+| `pnpm check` | Full merge gate (see below) |
+
+### Merge gate (`pnpm check`)
+
+All of these run at pre-commit via Lefthook (in parallel where possible):
+
+- `pnpm audit` — security audit
+- `knip` — unused code detection
+- `biome check` — formatting + linting
+- `oxlint` — type-aware linting (complements Biome)
+- Custom scripts — lint-ignore caps, className enforcement, component prop limits
+- `tsc --build` — TypeScript strict mode
+- `vitest run` — tests with per-path coverage thresholds
+- `jscpd` + `jsinspect` — copy-paste and structural duplication detection
+
+## Tech Stack
+
+- TypeScript 5.8 (strict mode), React 19, Vite 6
+- Tailwind CSS v4 (dark/light theme)
+- Biome 2.4 (formatting + linting), oxlint (type-aware linting)
+- Vitest (testing, v8 coverage), Lefthook (pre-commit hooks)
+- Knip (unused code), jscpd + jsinspect (duplication detection)
 
 ## 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)
+packages/application/      Use cases — orchestrates domain via port interfaces
+data/bestiary/             Pre-built bestiary search index (~10k creatures)
+scripts/                   Build tooling (layer checks, index generation)
 specs/                     Feature specifications (spec → plan → tasks)
 ```
 
@@ -52,5 +81,45 @@ 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.
+- **Domain** — pure functions, no I/O, no randomness, no framework imports. Errors returned as values (`DomainError`), never thrown.
+- **Application** — orchestrates domain calls via port interfaces (`EncounterStore`, `PlayerCharacterStore`, etc.). No business logic.
+- **Web** — React adapter. Implements ports using hooks/state. All UI components, persistence, and external data access live here.
 
+Layer boundaries are enforced by automated import checks that run as part of the test suite.
+
+## Contributing
+
+### Workflow
+
+Development is spec-driven. Feature specs live in `specs/NNN-feature-name/` and are managed through Claude Code skills (see [CLAUDE.md](./CLAUDE.md) for full details).
+
+| Scope | What to do |
+|-------|-----------|
+| Bug fix / CSS tweak | Fix it, run `pnpm check`, commit. Optionally use `/browser-interactive-testing` for visual verification. |
+| Change to existing feature | Update the feature spec, then implement |
+| Larger change to existing feature | Update the spec → `/rpi-research` → `/rpi-plan` → `/rpi-implement` |
+| New feature | `/speckit.specify` → `/speckit.clarify` → `/speckit.plan` → `/speckit.tasks` → `/speckit.implement` |
+
+Use `/write-issue` to create well-structured Gitea issues, and `/integrate-issue` to pull an existing issue's requirements into the relevant feature spec.
+
+### Before committing
+
+Run `pnpm check` — Lefthook runs this automatically at pre-commit, but running it manually first saves time. All checks must pass.
+
+### Conventions
+
+- **Biome** for formatting and linting — tab indentation, 80-char lines
+- **TypeScript strict mode** with `verbatimModuleSyntax` (type-only imports must use `import type`)
+- **Max 8 props** per component interface — use React context for shared state
+- **Tests** in `__tests__/` directories — test pure functions directly, use `renderHook` for hooks
+
+See [CLAUDE.md](./CLAUDE.md) for the full conventions and project constitution.
+
+## Bestiary Index
+
+The bestiary search index (`data/bestiary/index.json`) is pre-built and checked into the repo. To regenerate it (e.g., after a new source book release):
+
+1. Clone [5etools-mirror-3/5etools-src](https://github.com/5etools-mirror-3/5etools-src) locally
+2. Run `node scripts/generate-bestiary-index.mjs /path/to/5etools-src`
+
+The script extracts creature names, stats, and source info into a compact search index.

apps/web/index.html

@@ -2,7 +2,7 @@
 <html lang="en">
 	<head>
 		<meta charset="UTF-8" />
-		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
 		<meta name="theme-color" content="#0e1a2e" />
 		<link rel="manifest" href="/manifest.json" />
 		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />

apps/web/src/App.tsx

@@ -30,6 +30,13 @@ export function App() {
 	const activeRowRef = useRef<HTMLDivElement>(null);
 	const actionBarAnim = useActionBarAnimation(encounter.combatants.length);
 
+	// Close the side panel when the encounter becomes empty
+	useEffect(() => {
+		if (isEmpty) {
+			sidePanel.dismissPanel();
+		}
+	}, [isEmpty, sidePanel.dismissPanel]);
+
 	// Auto-scroll to active combatant when turn changes
 	const activeIndex = encounter.activeIndex;
 	useEffect(() => {
@@ -46,7 +53,10 @@ export function App() {
 			<div className="relative mx-auto flex min-h-0 w-full flex-1 flex-col gap-3 sm:max-w-2xl sm:px-4">
 				{!!actionBarAnim.showTopBar && (
 					<div
-						className={cn("shrink-0 sm:pt-8", actionBarAnim.topBarClass)}
+						className={cn(
+							"shrink-0 pt-[env(safe-area-inset-top)] sm:pt-[max(env(safe-area-inset-top),2rem)]",
+							actionBarAnim.topBarClass,
+						)}
 						onAnimationEnd={actionBarAnim.onTopBarExitEnd}
 					>
 						<TurnNavigation />
@@ -85,7 +95,10 @@ export function App() {
 						</div>
 
 						<div
-							className={cn("shrink-0 sm:pb-8", actionBarAnim.settlingClass)}
+							className={cn(
+								"shrink-0 pb-[env(safe-area-inset-bottom)] sm:pb-[max(env(safe-area-inset-bottom),2rem)]",
+								actionBarAnim.settlingClass,
+							)}
 							onAnimationEnd={actionBarAnim.onSettleEnd}
 						>
 							<ActionBar

apps/web/src/__tests__/export-import.test.ts

@@ -0,0 +1,233 @@
+import {
+	combatantId,
+	type Encounter,
+	type ExportBundle,
+	type PlayerCharacter,
+	playerCharacterId,
+	type UndoRedoState,
+} from "@initiative/domain";
+import { describe, expect, it } from "vitest";
+import {
+	assembleExportBundle,
+	bundleToJson,
+	resolveFilename,
+	validateImportBundle,
+} from "../persistence/export-import.js";
+
+const ISO_TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
+const DEFAULT_FILENAME_RE = /^initiative-export-\d{4}-\d{2}-\d{2}\.json$/;
+
+const encounter: Encounter = {
+	combatants: [
+		{
+			id: combatantId("c-1"),
+			name: "Goblin",
+			initiative: 15,
+			maxHp: 7,
+			currentHp: 7,
+			ac: 15,
+		},
+		{
+			id: combatantId("c-2"),
+			name: "Aria",
+			initiative: 18,
+			maxHp: 45,
+			currentHp: 40,
+			ac: 16,
+			color: "blue",
+			icon: "sword",
+			playerCharacterId: playerCharacterId("pc-1"),
+		},
+	],
+	activeIndex: 0,
+	roundNumber: 2,
+};
+
+const undoRedoState: UndoRedoState = {
+	undoStack: [
+		{
+			combatants: [{ id: combatantId("c-1"), name: "Goblin", initiative: 15 }],
+			activeIndex: 0,
+			roundNumber: 1,
+		},
+	],
+	redoStack: [],
+};
+
+const playerCharacters: PlayerCharacter[] = [
+	{
+		id: playerCharacterId("pc-1"),
+		name: "Aria",
+		ac: 16,
+		maxHp: 45,
+		color: "blue",
+		icon: "sword",
+	},
+];
+
+describe("assembleExportBundle", () => {
+	it("returns a bundle with version 1", () => {
+		const bundle = assembleExportBundle(
+			encounter,
+			undoRedoState,
+			playerCharacters,
+		);
+		expect(bundle.version).toBe(1);
+	});
+
+	it("includes an ISO timestamp", () => {
+		const bundle = assembleExportBundle(
+			encounter,
+			undoRedoState,
+			playerCharacters,
+		);
+		expect(bundle.exportedAt).toMatch(ISO_TIMESTAMP_RE);
+	});
+
+	it("includes the encounter", () => {
+		const bundle = assembleExportBundle(
+			encounter,
+			undoRedoState,
+			playerCharacters,
+		);
+		expect(bundle.encounter).toEqual(encounter);
+	});
+
+	it("includes undo and redo stacks", () => {
+		const bundle = assembleExportBundle(
+			encounter,
+			undoRedoState,
+			playerCharacters,
+		);
+		expect(bundle.undoStack).toEqual(undoRedoState.undoStack);
+		expect(bundle.redoStack).toEqual(undoRedoState.redoStack);
+	});
+
+	it("includes player characters", () => {
+		const bundle = assembleExportBundle(
+			encounter,
+			undoRedoState,
+			playerCharacters,
+		);
+		expect(bundle.playerCharacters).toEqual(playerCharacters);
+	});
+});
+
+describe("assembleExportBundle with includeHistory", () => {
+	it("excludes undo/redo stacks when includeHistory is false", () => {
+		const bundle = assembleExportBundle(
+			encounter,
+			undoRedoState,
+			playerCharacters,
+			false,
+		);
+		expect(bundle.undoStack).toHaveLength(0);
+		expect(bundle.redoStack).toHaveLength(0);
+	});
+
+	it("includes undo/redo stacks when includeHistory is true", () => {
+		const bundle = assembleExportBundle(
+			encounter,
+			undoRedoState,
+			playerCharacters,
+			true,
+		);
+		expect(bundle.undoStack).toEqual(undoRedoState.undoStack);
+		expect(bundle.redoStack).toEqual(undoRedoState.redoStack);
+	});
+
+	it("includes undo/redo stacks by default", () => {
+		const bundle = assembleExportBundle(
+			encounter,
+			undoRedoState,
+			playerCharacters,
+		);
+		expect(bundle.undoStack).toEqual(undoRedoState.undoStack);
+	});
+});
+
+describe("bundleToJson", () => {
+	it("produces valid JSON that round-trips through validateImportBundle", () => {
+		const bundle = assembleExportBundle(
+			encounter,
+			undoRedoState,
+			playerCharacters,
+		);
+		const json = bundleToJson(bundle);
+		const parsed: unknown = JSON.parse(json);
+		const result = validateImportBundle(parsed);
+		expect(typeof result).toBe("object");
+	});
+});
+
+describe("resolveFilename", () => {
+	it("uses date-based default when no name provided", () => {
+		const result = resolveFilename();
+		expect(result).toMatch(DEFAULT_FILENAME_RE);
+	});
+
+	it("uses date-based default for empty string", () => {
+		const result = resolveFilename("");
+		expect(result).toMatch(DEFAULT_FILENAME_RE);
+	});
+
+	it("uses date-based default for whitespace-only string", () => {
+		const result = resolveFilename("   ");
+		expect(result).toMatch(DEFAULT_FILENAME_RE);
+	});
+
+	it("appends .json to a custom name", () => {
+		expect(resolveFilename("my-encounter")).toBe("my-encounter.json");
+	});
+
+	it("does not double-append .json", () => {
+		expect(resolveFilename("my-encounter.json")).toBe("my-encounter.json");
+	});
+
+	it("trims whitespace from custom name", () => {
+		expect(resolveFilename("  my-encounter  ")).toBe("my-encounter.json");
+	});
+});
+
+describe("round-trip: export then import", () => {
+	it("produces identical state after round-trip", () => {
+		const bundle = assembleExportBundle(
+			encounter,
+			undoRedoState,
+			playerCharacters,
+		);
+
+		const serialized = JSON.parse(JSON.stringify(bundle));
+		const result = validateImportBundle(serialized);
+
+		expect(typeof result).toBe("object");
+		const imported = result as ExportBundle;
+		expect(imported.version).toBe(bundle.version);
+		expect(imported.encounter).toEqual(bundle.encounter);
+		expect(imported.undoStack).toEqual(bundle.undoStack);
+		expect(imported.redoStack).toEqual(bundle.redoStack);
+		expect(imported.playerCharacters).toEqual(bundle.playerCharacters);
+	});
+
+	it("round-trips an empty encounter", () => {
+		const emptyEncounter: Encounter = {
+			combatants: [],
+			activeIndex: 0,
+			roundNumber: 1,
+		};
+		const emptyUndoRedo: UndoRedoState = {
+			undoStack: [],
+			redoStack: [],
+		};
+		const bundle = assembleExportBundle(emptyEncounter, emptyUndoRedo, []);
+		const serialized = JSON.parse(JSON.stringify(bundle));
+		const result = validateImportBundle(serialized);
+
+		expect(typeof result).toBe("object");
+		const imported = result as ExportBundle;
+		expect(imported.encounter.combatants).toHaveLength(0);
+		expect(imported.undoStack).toHaveLength(0);
+		expect(imported.redoStack).toHaveLength(0);
+		expect(imported.playerCharacters).toHaveLength(0);
+	});
+});

apps/web/src/__tests__/polyfill-dialog.ts

@@ -0,0 +1,16 @@
+/**
+ * jsdom doesn't implement HTMLDialogElement.showModal/close.
+ * Call this in beforeAll() for tests that render <Dialog>.
+ */
+export function polyfillDialog(): void {
+	if (typeof HTMLDialogElement.prototype.showModal !== "function") {
+		HTMLDialogElement.prototype.showModal = function showModal() {
+			this.setAttribute("open", "");
+		};
+	}
+	if (typeof HTMLDialogElement.prototype.close !== "function") {
+		HTMLDialogElement.prototype.close = function close() {
+			this.removeAttribute("open");
+		};
+	}
+}

apps/web/src/__tests__/validate-import-bundle.test.ts

@@ -0,0 +1,249 @@
+import type { ExportBundle } from "@initiative/domain";
+import { describe, expect, it } from "vitest";
+import { validateImportBundle } from "../persistence/export-import.js";
+
+function validBundle(): Record<string, unknown> {
+	return {
+		version: 1,
+		exportedAt: "2026-03-27T12:00:00.000Z",
+		encounter: {
+			combatants: [{ id: "c-1", name: "Goblin", initiative: 15 }],
+			activeIndex: 0,
+			roundNumber: 1,
+		},
+		undoStack: [],
+		redoStack: [],
+		playerCharacters: [],
+	};
+}
+
+describe("validateImportBundle", () => {
+	it("accepts a valid bundle", () => {
+		const result = validateImportBundle(validBundle());
+		expect(typeof result).toBe("object");
+		const bundle = result as ExportBundle;
+		expect(bundle.version).toBe(1);
+		expect(bundle.encounter.combatants).toHaveLength(1);
+		expect(bundle.encounter.combatants[0].name).toBe("Goblin");
+	});
+
+	it("accepts a valid bundle with empty encounter", () => {
+		const input = {
+			...validBundle(),
+			encounter: { combatants: [], activeIndex: 0, roundNumber: 1 },
+		};
+		const result = validateImportBundle(input);
+		expect(typeof result).toBe("object");
+		const bundle = result as ExportBundle;
+		expect(bundle.encounter.combatants).toHaveLength(0);
+	});
+
+	it("accepts a bundle with undo/redo stacks", () => {
+		const enc = {
+			combatants: [{ id: "c-1", name: "Orc" }],
+			activeIndex: 0,
+			roundNumber: 1,
+		};
+		const input = {
+			...validBundle(),
+			undoStack: [enc],
+			redoStack: [enc],
+		};
+		const result = validateImportBundle(input);
+		expect(typeof result).toBe("object");
+		const bundle = result as ExportBundle;
+		expect(bundle.undoStack).toHaveLength(1);
+		expect(bundle.redoStack).toHaveLength(1);
+	});
+
+	it("accepts a bundle with player characters", () => {
+		const input = {
+			...validBundle(),
+			playerCharacters: [
+				{
+					id: "pc-1",
+					name: "Aria",
+					ac: 16,
+					maxHp: 45,
+					color: "blue",
+					icon: "sword",
+				},
+			],
+		};
+		const result = validateImportBundle(input);
+		expect(typeof result).toBe("object");
+		const bundle = result as ExportBundle;
+		expect(bundle.playerCharacters).toHaveLength(1);
+		expect(bundle.playerCharacters[0].name).toBe("Aria");
+	});
+
+	it("rejects non-object input", () => {
+		expect(validateImportBundle(null)).toBe("Invalid file format");
+		expect(validateImportBundle(42)).toBe("Invalid file format");
+		expect(validateImportBundle("string")).toBe("Invalid file format");
+		expect(validateImportBundle([])).toBe("Invalid file format");
+		expect(validateImportBundle(undefined)).toBe("Invalid file format");
+	});
+
+	it("rejects missing version field", () => {
+		const input = validBundle();
+		delete input.version;
+		expect(validateImportBundle(input)).toBe("Invalid file format");
+	});
+
+	it("rejects version 0 or negative", () => {
+		expect(validateImportBundle({ ...validBundle(), version: 0 })).toBe(
+			"Invalid file format",
+		);
+		expect(validateImportBundle({ ...validBundle(), version: -1 })).toBe(
+			"Invalid file format",
+		);
+	});
+
+	it("rejects unknown version", () => {
+		expect(validateImportBundle({ ...validBundle(), version: 99 })).toBe(
+			"Invalid file format",
+		);
+	});
+
+	it("rejects missing encounter field", () => {
+		const input = validBundle();
+		delete input.encounter;
+		expect(validateImportBundle(input)).toBe("Invalid encounter data");
+	});
+
+	it("rejects invalid encounter data", () => {
+		expect(
+			validateImportBundle({ ...validBundle(), encounter: "not an object" }),
+		).toBe("Invalid encounter data");
+	});
+
+	it("rejects missing undoStack", () => {
+		const input = validBundle();
+		delete input.undoStack;
+		expect(validateImportBundle(input)).toBe("Invalid file format");
+	});
+
+	it("rejects missing redoStack", () => {
+		const input = validBundle();
+		delete input.redoStack;
+		expect(validateImportBundle(input)).toBe("Invalid file format");
+	});
+
+	it("rejects missing playerCharacters", () => {
+		const input = validBundle();
+		delete input.playerCharacters;
+		expect(validateImportBundle(input)).toBe("Invalid file format");
+	});
+
+	it("rejects non-string exportedAt", () => {
+		expect(validateImportBundle({ ...validBundle(), exportedAt: 12345 })).toBe(
+			"Invalid file format",
+		);
+	});
+
+	it("drops invalid entries from undo stack", () => {
+		const valid = {
+			combatants: [{ id: "c-1", name: "Orc" }],
+			activeIndex: 0,
+			roundNumber: 1,
+		};
+		const input = {
+			...validBundle(),
+			undoStack: [valid, "invalid", { bad: true }, valid],
+		};
+		const result = validateImportBundle(input);
+		expect(typeof result).toBe("object");
+		const bundle = result as ExportBundle;
+		expect(bundle.undoStack).toHaveLength(2);
+	});
+
+	it("drops invalid player characters", () => {
+		const input = {
+			...validBundle(),
+			playerCharacters: [
+				{ id: "pc-1", name: "Valid", ac: 10, maxHp: 20 },
+				{ id: "", name: "Bad ID" },
+				"not an object",
+				{ id: "pc-3", name: "Also Valid", ac: 15, maxHp: 30 },
+			],
+		};
+		const result = validateImportBundle(input);
+		expect(typeof result).toBe("object");
+		const bundle = result as ExportBundle;
+		expect(bundle.playerCharacters).toHaveLength(2);
+	});
+
+	it("rejects JSON array instead of object", () => {
+		expect(validateImportBundle([1, 2, 3])).toBe("Invalid file format");
+	});
+
+	it("rejects encounter that fails rehydration (missing combatant fields)", () => {
+		const input = {
+			...validBundle(),
+			encounter: {
+				combatants: [{ noId: true }],
+				activeIndex: 0,
+				roundNumber: 1,
+			},
+		};
+		expect(validateImportBundle(input)).toBe("Invalid encounter data");
+	});
+
+	it("strips invalid color/icon from player characters but keeps the character", () => {
+		const input = {
+			...validBundle(),
+			playerCharacters: [
+				{
+					id: "pc-1",
+					name: "Test",
+					ac: 10,
+					maxHp: 20,
+					color: "neon-pink",
+					icon: "bazooka",
+				},
+			],
+		};
+		const result = validateImportBundle(input);
+		// rehydrateCharacter rejects characters with invalid color/icon members
+		// that are not in the valid sets, so this character is dropped
+		expect(typeof result).toBe("object");
+		const bundle = result as ExportBundle;
+		expect(bundle.playerCharacters).toHaveLength(0);
+	});
+
+	it("keeps player characters with valid optional color and icon", () => {
+		const input = {
+			...validBundle(),
+			playerCharacters: [
+				{
+					id: "pc-1",
+					name: "Aria",
+					ac: 16,
+					maxHp: 45,
+					color: "blue",
+					icon: "sword",
+				},
+			],
+		};
+		const result = validateImportBundle(input);
+		expect(typeof result).toBe("object");
+		const bundle = result as ExportBundle;
+		expect(bundle.playerCharacters).toHaveLength(1);
+		expect(bundle.playerCharacters[0].color).toBe("blue");
+		expect(bundle.playerCharacters[0].icon).toBe("sword");
+	});
+
+	it("ignores unknown extra fields on the bundle", () => {
+		const input = {
+			...validBundle(),
+			unknownField: "should be ignored",
+			anotherExtra: 42,
+		};
+		const result = validateImportBundle(input);
+		expect(typeof result).toBe("object");
+		const bundle = result as ExportBundle;
+		expect(bundle.version).toBe(1);
+		expect("unknownField" in bundle).toBe(false);
+	});
+});

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

@@ -40,7 +40,7 @@ async function getDb(): Promise<IDBPDatabase | null> {
 				}
 				if (oldVersion < 2 && database.objectStoreNames.contains(STORE_NAME)) {
 					// Clear cached creatures to pick up improved tag processing
-					transaction.objectStore(STORE_NAME).clear();
+					void transaction.objectStore(STORE_NAME).clear();
 				}
 			},
 		});

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

@@ -4,6 +4,7 @@ import "@testing-library/jest-dom/vitest";
 import { cleanup, render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { polyfillDialog } from "../../__tests__/polyfill-dialog.js";
 import { AllProviders } from "../../__tests__/test-providers.js";
 import { ActionBar } from "../action-bar.js";
 
@@ -50,6 +51,7 @@ beforeAll(() => {
 			dispatchEvent: vi.fn(),
 		})),
 	});
+	polyfillDialog();
 });
 
 afterEach(cleanup);
@@ -118,4 +120,61 @@ describe("ActionBar", () => {
 			screen.getByRole("button", { name: "More actions" }),
 		).toBeInTheDocument();
 	});
+
+	it("opens export method dialog via overflow menu", async () => {
+		const user = userEvent.setup();
+		renderBar();
+		await user.click(screen.getByRole("button", { name: "More actions" }));
+		// Click the menu item
+		const items = screen.getAllByText("Export Encounter");
+		await user.click(items[0]);
+		// Dialog should now be open — it renders a second "Export Encounter" as heading
+		expect(
+			screen.getAllByText("Export Encounter").length,
+		).toBeGreaterThanOrEqual(1);
+	});
+
+	it("opens import method dialog via overflow menu", async () => {
+		const user = userEvent.setup();
+		renderBar();
+		await user.click(screen.getByRole("button", { name: "More actions" }));
+		const items = screen.getAllByText("Import Encounter");
+		await user.click(items[0]);
+		expect(
+			screen.getAllByText("Import Encounter").length,
+		).toBeGreaterThanOrEqual(1);
+	});
+
+	it("calls onManagePlayers from overflow menu", async () => {
+		const onManagePlayers = vi.fn();
+		const user = userEvent.setup();
+		renderBar({ onManagePlayers });
+		await user.click(screen.getByRole("button", { name: "More actions" }));
+		await user.click(screen.getByText("Player Characters"));
+		expect(onManagePlayers).toHaveBeenCalledOnce();
+	});
+
+	it("calls onOpenSettings from overflow menu", async () => {
+		const onOpenSettings = vi.fn();
+		const user = userEvent.setup();
+		renderBar({ onOpenSettings });
+		await user.click(screen.getByRole("button", { name: "More actions" }));
+		await user.click(screen.getByText("Settings"));
+		expect(onOpenSettings).toHaveBeenCalledOnce();
+	});
+
+	it("submits custom stats with combatant", async () => {
+		const user = userEvent.setup();
+		renderBar();
+		const input = screen.getByPlaceholderText("+ Add combatants");
+		await user.type(input, "Fighter");
+		const initInput = screen.getByPlaceholderText("Init");
+		const acInput = screen.getByPlaceholderText("AC");
+		const hpInput = screen.getByPlaceholderText("MaxHP");
+		await user.type(initInput, "15");
+		await user.type(acInput, "18");
+		await user.type(hpInput, "45");
+		await user.click(screen.getByRole("button", { name: "Add" }));
+		expect(input).toHaveValue("");
+	});
 });

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

@@ -0,0 +1,146 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { BulkImportPrompt } from "../bulk-import-prompt.js";
+
+const THREE_SOURCES_REGEX = /3 sources/;
+const GITHUB_URL_REGEX = /raw\.githubusercontent/;
+const LOADING_PROGRESS_REGEX = /Loading sources\.\.\. 4\/10/;
+const SEVEN_OF_TEN_REGEX = /7\/10 sources/;
+const THREE_FAILED_REGEX = /3 failed/;
+
+afterEach(cleanup);
+
+const mockFetchAndCacheSource = vi.fn();
+const mockIsSourceCached = vi.fn().mockResolvedValue(false);
+const mockRefreshCache = vi.fn();
+const mockStartImport = vi.fn();
+const mockReset = vi.fn();
+const mockDismissPanel = vi.fn();
+
+let mockImportState = {
+	status: "idle" as string,
+	total: 0,
+	completed: 0,
+	failed: 0,
+};
+
+vi.mock("../../contexts/bestiary-context.js", () => ({
+	useBestiaryContext: () => ({
+		fetchAndCacheSource: mockFetchAndCacheSource,
+		isSourceCached: mockIsSourceCached,
+		refreshCache: mockRefreshCache,
+	}),
+}));
+
+vi.mock("../../contexts/bulk-import-context.js", () => ({
+	useBulkImportContext: () => ({
+		state: mockImportState,
+		startImport: mockStartImport,
+		reset: mockReset,
+	}),
+}));
+
+vi.mock("../../contexts/side-panel-context.js", () => ({
+	useSidePanelContext: () => ({
+		dismissPanel: mockDismissPanel,
+	}),
+}));
+
+vi.mock("../../adapters/bestiary-index-adapter.js", () => ({
+	getAllSourceCodes: () => ["MM", "VGM", "XGE"],
+	getDefaultFetchUrl: () => "",
+	getSourceDisplayName: (code: string) => code,
+	loadBestiaryIndex: () => ({ sources: {}, creatures: [] }),
+}));
+
+describe("BulkImportPrompt", () => {
+	afterEach(() => {
+		vi.clearAllMocks();
+		mockImportState = { status: "idle", total: 0, completed: 0, failed: 0 };
+	});
+
+	it("idle: shows base URL input, source count, Load All button", () => {
+		render(<BulkImportPrompt />);
+		expect(screen.getByText(THREE_SOURCES_REGEX)).toBeInTheDocument();
+		expect(screen.getByDisplayValue(GITHUB_URL_REGEX)).toBeInTheDocument();
+		expect(
+			screen.getByRole("button", { name: "Load All" }),
+		).toBeInTheDocument();
+	});
+
+	it("idle: clearing URL disables the button", async () => {
+		const user = userEvent.setup();
+		render(<BulkImportPrompt />);
+
+		const input = screen.getByDisplayValue(GITHUB_URL_REGEX);
+		await user.clear(input);
+		expect(screen.getByRole("button", { name: "Load All" })).toBeDisabled();
+	});
+
+	it("idle: clicking Load All calls startImport with URL", async () => {
+		const user = userEvent.setup();
+		render(<BulkImportPrompt />);
+
+		await user.click(screen.getByRole("button", { name: "Load All" }));
+		expect(mockStartImport).toHaveBeenCalledWith(
+			expect.stringContaining("raw.githubusercontent"),
+			mockFetchAndCacheSource,
+			mockIsSourceCached,
+			mockRefreshCache,
+		);
+	});
+
+	it("loading: shows progress text and progress bar", () => {
+		mockImportState = {
+			status: "loading",
+			total: 10,
+			completed: 3,
+			failed: 1,
+		};
+		render(<BulkImportPrompt />);
+		expect(screen.getByText(LOADING_PROGRESS_REGEX)).toBeInTheDocument();
+	});
+
+	it("complete: shows success message and Done button", () => {
+		mockImportState = {
+			status: "complete",
+			total: 10,
+			completed: 10,
+			failed: 0,
+		};
+		render(<BulkImportPrompt />);
+		expect(screen.getByText("All sources loaded")).toBeInTheDocument();
+		expect(screen.getByRole("button", { name: "Done" })).toBeInTheDocument();
+	});
+
+	it("complete: Done calls dismissPanel and reset", async () => {
+		mockImportState = {
+			status: "complete",
+			total: 10,
+			completed: 10,
+			failed: 0,
+		};
+		const user = userEvent.setup();
+		render(<BulkImportPrompt />);
+
+		await user.click(screen.getByRole("button", { name: "Done" }));
+		expect(mockDismissPanel).toHaveBeenCalled();
+		expect(mockReset).toHaveBeenCalled();
+	});
+
+	it("partial-failure: shows loaded/failed counts", () => {
+		mockImportState = {
+			status: "partial-failure",
+			total: 10,
+			completed: 7,
+			failed: 3,
+		};
+		render(<BulkImportPrompt />);
+		expect(screen.getByText(SEVEN_OF_TEN_REGEX)).toBeInTheDocument();
+		expect(screen.getByText(THREE_FAILED_REGEX)).toBeInTheDocument();
+	});
+});

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

@@ -0,0 +1,56 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import { VALID_PLAYER_COLORS } from "@initiative/domain";
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+afterEach(cleanup);
+
+import { ColorPalette } from "../color-palette.js";
+
+describe("ColorPalette", () => {
+	it("renders a button for each valid color", () => {
+		render(<ColorPalette value="" onChange={() => {}} />);
+		const buttons = screen.getAllByRole("button");
+		expect(buttons).toHaveLength(VALID_PLAYER_COLORS.size);
+	});
+
+	it("each button has an aria-label matching the color name", () => {
+		render(<ColorPalette value="" onChange={() => {}} />);
+		for (const color of VALID_PLAYER_COLORS) {
+			expect(screen.getByRole("button", { name: color })).toBeInTheDocument();
+		}
+	});
+
+	it("clicking a color calls onChange with that color", async () => {
+		const user = userEvent.setup();
+		const onChange = vi.fn();
+		render(<ColorPalette value="" onChange={onChange} />);
+
+		await user.click(screen.getByRole("button", { name: "blue" }));
+		expect(onChange).toHaveBeenCalledWith("blue");
+	});
+
+	it("clicking the selected color deselects it", async () => {
+		const user = userEvent.setup();
+		const onChange = vi.fn();
+		render(<ColorPalette value="red" onChange={onChange} />);
+
+		await user.click(screen.getByRole("button", { name: "red" }));
+		expect(onChange).toHaveBeenCalledWith("");
+	});
+
+	it("selected color has ring styling", () => {
+		render(<ColorPalette value="green" onChange={() => {}} />);
+		const selected = screen.getByRole("button", { name: "green" });
+		expect(selected.className).toContain("ring-2");
+	});
+
+	it("non-selected colors do not have ring styling", () => {
+		render(<ColorPalette value="green" onChange={() => {}} />);
+		const other = screen.getByRole("button", { name: "blue" });
+		expect(other.className).not.toContain("ring-2");
+	});
+});

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

@@ -10,6 +10,8 @@ import { CombatantRow } from "../combatant-row.js";
 import { PLAYER_COLOR_HEX } from "../player-icon-map.js";
 
 const TEMP_HP_REGEX = /^\+\d/;
+const CURRENT_HP_7_REGEX = /Current HP: 7/;
+const CURRENT_HP_REGEX = /Current HP/;
 
 // Mock persistence — no localStorage interaction
 vi.mock("../../persistence/encounter-storage.js", () => ({
@@ -257,6 +259,172 @@ describe("CombatantRow", () => {
 		});
 	});
 
+	describe("inline name editing", () => {
+		it("click rename → type new name → blur commits rename", async () => {
+			const user = userEvent.setup();
+			renderRow();
+
+			await user.click(screen.getByRole("button", { name: "Rename" }));
+			const input = screen.getByDisplayValue("Goblin");
+			await user.clear(input);
+			await user.type(input, "Hobgoblin");
+			await user.tab(); // blur
+			// The input should be gone, name committed
+			expect(screen.queryByDisplayValue("Hobgoblin")).not.toBeInTheDocument();
+		});
+
+		it("Escape cancels without renaming", async () => {
+			const user = userEvent.setup();
+			renderRow();
+
+			await user.click(screen.getByRole("button", { name: "Rename" }));
+			const input = screen.getByDisplayValue("Goblin");
+			await user.clear(input);
+			await user.type(input, "Changed");
+			await user.keyboard("{Escape}");
+			// Should revert to showing the original name
+			expect(screen.getByText("Goblin")).toBeInTheDocument();
+		});
+	});
+
+	describe("inline AC editing", () => {
+		it("click AC → type value → Enter commits", async () => {
+			const user = userEvent.setup();
+			renderRow({
+				combatant: {
+					id: combatantId("1"),
+					name: "Goblin",
+					ac: 13,
+				},
+			});
+
+			// Click the AC shield button
+			const acButton = screen.getByText("13").closest("button");
+			expect(acButton).not.toBeNull();
+			await user.click(acButton as HTMLElement);
+			const input = screen.getByDisplayValue("13");
+			await user.clear(input);
+			await user.type(input, "16");
+			await user.keyboard("{Enter}");
+			expect(screen.queryByDisplayValue("16")).not.toBeInTheDocument();
+		});
+	});
+
+	describe("inline max HP editing", () => {
+		it("click max HP → type value → blur commits", async () => {
+			const user = userEvent.setup();
+			renderRow({
+				combatant: {
+					id: combatantId("1"),
+					name: "Goblin",
+					maxHp: 10,
+					currentHp: 10,
+				},
+			});
+
+			// The max HP button shows "10" as muted text
+			const maxHpButton = screen
+				.getAllByText("10")
+				.find(
+					(el) => el.closest("button") && el.className.includes("text-muted"),
+				);
+			expect(maxHpButton).toBeDefined();
+			const maxHpBtn = (maxHpButton as HTMLElement).closest("button");
+			expect(maxHpBtn).not.toBeNull();
+			await user.click(maxHpBtn as HTMLElement);
+			const input = screen.getByDisplayValue("10");
+			await user.clear(input);
+			await user.type(input, "25");
+			await user.tab();
+			expect(screen.queryByDisplayValue("25")).not.toBeInTheDocument();
+		});
+	});
+
+	describe("inline initiative editing", () => {
+		it("click initiative → type value → Enter commits", async () => {
+			const user = userEvent.setup();
+			renderRow({
+				combatant: {
+					id: combatantId("1"),
+					name: "Goblin",
+					initiative: 15,
+				},
+			});
+
+			await user.click(screen.getByText("15"));
+			const input = screen.getByDisplayValue("15");
+			await user.clear(input);
+			await user.type(input, "20");
+			await user.keyboard("{Enter}");
+			expect(screen.queryByDisplayValue("20")).not.toBeInTheDocument();
+		});
+
+		it("clearing initiative and pressing Enter commits the edit", async () => {
+			const user = userEvent.setup();
+			renderRow({
+				combatant: {
+					id: combatantId("1"),
+					name: "Goblin",
+					initiative: 15,
+				},
+			});
+
+			await user.click(screen.getByText("15"));
+			const input = screen.getByDisplayValue("15");
+			await user.clear(input);
+			await user.keyboard("{Enter}");
+			// Input should be dismissed (editing mode exited)
+			expect(screen.queryByRole("textbox")).not.toBeInTheDocument();
+		});
+	});
+
+	describe("HP popover", () => {
+		it("clicking current HP opens the HP adjust popover", async () => {
+			const user = userEvent.setup();
+			renderRow({
+				combatant: {
+					id: combatantId("1"),
+					name: "Goblin",
+					maxHp: 10,
+					currentHp: 7,
+				},
+			});
+
+			const hpButton = screen.getByLabelText(CURRENT_HP_7_REGEX);
+			await user.click(hpButton);
+			// The popover should appear with damage/heal controls
+			expect(
+				screen.getByRole("button", { name: "Apply damage" }),
+			).toBeInTheDocument();
+			expect(
+				screen.getByRole("button", { name: "Apply healing" }),
+			).toBeInTheDocument();
+		});
+
+		it("HP section is absent when maxHp is undefined", () => {
+			renderRow({
+				combatant: {
+					id: combatantId("1"),
+					name: "Goblin",
+				},
+			});
+			expect(screen.queryByLabelText(CURRENT_HP_REGEX)).not.toBeInTheDocument();
+		});
+	});
+
+	describe("condition picker", () => {
+		it("clicking Add condition button opens the picker", async () => {
+			const user = userEvent.setup();
+			renderRow();
+			const addButton = screen.getByRole("button", {
+				name: "Add condition",
+			});
+			await user.click(addButton);
+			// Condition picker should render with condition options
+			expect(screen.getByText("Blinded")).toBeInTheDocument();
+		});
+	});
+
 	describe("temp HP display", () => {
 		it("shows +N when combatant has temp HP", () => {
 			renderRow({

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

@@ -0,0 +1,87 @@
+// @vitest-environment jsdom
+import type { ConditionId } from "@initiative/domain";
+import { cleanup, render, screen } from "@testing-library/react";
+import { userEvent } from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ConditionTags } from "../condition-tags.js";
+
+vi.mock("../../contexts/rules-edition-context.js", () => ({
+	useRulesEditionContext: () => ({ edition: "5.5e" }),
+}));
+
+afterEach(cleanup);
+
+describe("ConditionTags", () => {
+	it("renders nothing when conditions is undefined", () => {
+		const { container } = render(
+			<ConditionTags
+				conditions={undefined}
+				onRemove={() => {}}
+				onOpenPicker={() => {}}
+			/>,
+		);
+		// Only the add button should be present
+		expect(container.querySelectorAll("button")).toHaveLength(1);
+	});
+
+	it("renders a button per condition", () => {
+		const conditions: ConditionId[] = ["blinded", "prone"];
+		render(
+			<ConditionTags
+				conditions={conditions}
+				onRemove={() => {}}
+				onOpenPicker={() => {}}
+			/>,
+		);
+		expect(
+			screen.getByRole("button", { name: "Remove Blinded" }),
+		).toBeDefined();
+		expect(screen.getByRole("button", { name: "Remove Prone" })).toBeDefined();
+	});
+
+	it("calls onRemove with condition id when clicked", async () => {
+		const onRemove = vi.fn();
+		render(
+			<ConditionTags
+				conditions={["blinded"] as ConditionId[]}
+				onRemove={onRemove}
+				onOpenPicker={() => {}}
+			/>,
+		);
+
+		await userEvent.click(
+			screen.getByRole("button", { name: "Remove Blinded" }),
+		);
+
+		expect(onRemove).toHaveBeenCalledWith("blinded");
+	});
+
+	it("calls onOpenPicker when add button is clicked", async () => {
+		const onOpenPicker = vi.fn();
+		render(
+			<ConditionTags
+				conditions={[]}
+				onRemove={() => {}}
+				onOpenPicker={onOpenPicker}
+			/>,
+		);
+
+		await userEvent.click(
+			screen.getByRole("button", { name: "Add condition" }),
+		);
+
+		expect(onOpenPicker).toHaveBeenCalledOnce();
+	});
+
+	it("renders empty conditions array without errors", () => {
+		render(
+			<ConditionTags
+				conditions={[]}
+				onRemove={() => {}}
+				onOpenPicker={() => {}}
+			/>,
+		);
+		// Only add button
+		expect(screen.getByRole("button", { name: "Add condition" })).toBeDefined();
+	});
+});

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

@@ -0,0 +1,165 @@
+// @vitest-environment jsdom
+import type { PlayerCharacter } from "@initiative/domain";
+import { playerCharacterId } from "@initiative/domain";
+import { cleanup, render, screen } from "@testing-library/react";
+import { userEvent } from "@testing-library/user-event";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { polyfillDialog } from "../../__tests__/polyfill-dialog.js";
+import { CreatePlayerModal } from "../create-player-modal.js";
+
+beforeAll(() => {
+	polyfillDialog();
+});
+
+afterEach(cleanup);
+
+function renderModal(
+	overrides: Partial<Parameters<typeof CreatePlayerModal>[0]> = {},
+) {
+	const defaults = {
+		open: true,
+		onClose: vi.fn(),
+		onSave: vi.fn(),
+	};
+	const props = { ...defaults, ...overrides };
+	return { ...render(<CreatePlayerModal {...props} />), ...props };
+}
+
+describe("CreatePlayerModal", () => {
+	it("renders create form with defaults", () => {
+		renderModal();
+		expect(screen.getByText("Create Player")).toBeDefined();
+		expect(screen.getByLabelText("Name")).toBeDefined();
+		expect(screen.getByLabelText("AC")).toBeDefined();
+		expect(screen.getByLabelText("Max HP")).toBeDefined();
+		expect(screen.getByLabelText("Level")).toBeDefined();
+		expect(screen.getByRole("button", { name: "Create" })).toBeDefined();
+	});
+
+	it("renders edit form when playerCharacter is provided", () => {
+		const pc: PlayerCharacter = {
+			id: playerCharacterId("pc-1"),
+			name: "Gandalf",
+			ac: 15,
+			maxHp: 40,
+			color: "blue",
+			icon: "wand",
+			level: 10,
+		};
+		renderModal({ playerCharacter: pc });
+		expect(screen.getByText("Edit Player")).toBeDefined();
+		expect(screen.getByLabelText("Name")).toHaveProperty("value", "Gandalf");
+		expect(screen.getByLabelText("AC")).toHaveProperty("value", "15");
+		expect(screen.getByLabelText("Max HP")).toHaveProperty("value", "40");
+		expect(screen.getByLabelText("Level")).toHaveProperty("value", "10");
+		expect(screen.getByRole("button", { name: "Save" })).toBeDefined();
+	});
+
+	it("calls onSave with valid data", async () => {
+		const { onSave, onClose } = renderModal();
+		const user = userEvent.setup();
+
+		await user.type(screen.getByLabelText("Name"), "Aria");
+		await user.clear(screen.getByLabelText("AC"));
+		await user.type(screen.getByLabelText("AC"), "16");
+		await user.clear(screen.getByLabelText("Max HP"));
+		await user.type(screen.getByLabelText("Max HP"), "30");
+		await user.type(screen.getByLabelText("Level"), "5");
+		await user.click(screen.getByRole("button", { name: "Create" }));
+
+		expect(onSave).toHaveBeenCalledWith(
+			"Aria",
+			16,
+			30,
+			undefined,
+			undefined,
+			5,
+		);
+		expect(onClose).toHaveBeenCalled();
+	});
+
+	it("shows error for empty name", async () => {
+		const { onSave } = renderModal();
+		const user = userEvent.setup();
+
+		await user.click(screen.getByRole("button", { name: "Create" }));
+
+		expect(screen.getByText("Name is required")).toBeDefined();
+		expect(onSave).not.toHaveBeenCalled();
+	});
+
+	it("shows error for invalid AC", async () => {
+		const { onSave } = renderModal();
+		const user = userEvent.setup();
+
+		await user.type(screen.getByLabelText("Name"), "Test");
+		await user.clear(screen.getByLabelText("AC"));
+		await user.type(screen.getByLabelText("AC"), "abc");
+		await user.click(screen.getByRole("button", { name: "Create" }));
+
+		expect(screen.getByText("AC must be a non-negative number")).toBeDefined();
+		expect(onSave).not.toHaveBeenCalled();
+	});
+
+	it("shows error for invalid Max HP", async () => {
+		const { onSave } = renderModal();
+		const user = userEvent.setup();
+
+		await user.type(screen.getByLabelText("Name"), "Test");
+		await user.clear(screen.getByLabelText("Max HP"));
+		await user.type(screen.getByLabelText("Max HP"), "0");
+		await user.click(screen.getByRole("button", { name: "Create" }));
+
+		expect(screen.getByText("Max HP must be at least 1")).toBeDefined();
+		expect(onSave).not.toHaveBeenCalled();
+	});
+
+	it("shows error for invalid level", async () => {
+		const { onSave } = renderModal();
+		const user = userEvent.setup();
+
+		await user.type(screen.getByLabelText("Name"), "Test");
+		await user.type(screen.getByLabelText("Level"), "25");
+		await user.click(screen.getByRole("button", { name: "Create" }));
+
+		expect(screen.getByText("Level must be between 1 and 20")).toBeDefined();
+		expect(onSave).not.toHaveBeenCalled();
+	});
+
+	it("clears error when name is edited", async () => {
+		renderModal();
+		const user = userEvent.setup();
+
+		await user.click(screen.getByRole("button", { name: "Create" }));
+		expect(screen.getByText("Name is required")).toBeDefined();
+
+		await user.type(screen.getByLabelText("Name"), "A");
+		expect(screen.queryByText("Name is required")).toBeNull();
+	});
+
+	it("calls onClose when cancel is clicked", async () => {
+		const { onClose } = renderModal();
+		const user = userEvent.setup();
+
+		await user.click(screen.getByRole("button", { name: "Cancel" }));
+
+		expect(onClose).toHaveBeenCalledOnce();
+	});
+
+	it("omits level when field is empty", async () => {
+		const { onSave } = renderModal();
+		const user = userEvent.setup();
+
+		await user.type(screen.getByLabelText("Name"), "Aria");
+		await user.click(screen.getByRole("button", { name: "Create" }));
+
+		expect(onSave).toHaveBeenCalledWith(
+			"Aria",
+			10,
+			10,
+			undefined,
+			undefined,
+			undefined,
+		);
+	});
+});

apps/web/src/components/__tests__/dialog.test.tsx

@@ -0,0 +1,63 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { userEvent } from "@testing-library/user-event";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { polyfillDialog } from "../../__tests__/polyfill-dialog.js";
+import { Dialog, DialogHeader } from "../ui/dialog.js";
+
+beforeAll(() => {
+	polyfillDialog();
+});
+
+afterEach(cleanup);
+
+describe("Dialog", () => {
+	it("opens when open=true", () => {
+		render(
+			<Dialog open={true} onClose={() => {}}>
+				Content
+			</Dialog>,
+		);
+		expect(screen.getByText("Content")).toBeDefined();
+	});
+
+	it("closes when open changes from true to false", () => {
+		const { rerender } = render(
+			<Dialog open={true} onClose={() => {}}>
+				Content
+			</Dialog>,
+		);
+		const dialog = document.querySelector("dialog");
+		expect(dialog?.hasAttribute("open")).toBe(true);
+
+		rerender(
+			<Dialog open={false} onClose={() => {}}>
+				Content
+			</Dialog>,
+		);
+		expect(dialog?.hasAttribute("open")).toBe(false);
+	});
+
+	it("calls onClose on cancel event", () => {
+		const onClose = vi.fn();
+		render(
+			<Dialog open={true} onClose={onClose}>
+				Content
+			</Dialog>,
+		);
+		const dialog = document.querySelector("dialog");
+		dialog?.dispatchEvent(new Event("cancel"));
+		expect(onClose).toHaveBeenCalledOnce();
+	});
+});
+
+describe("DialogHeader", () => {
+	it("renders title and close button", async () => {
+		const onClose = vi.fn();
+		render(<DialogHeader title="Test Title" onClose={onClose} />);
+
+		expect(screen.getByText("Test Title")).toBeDefined();
+		await userEvent.click(screen.getByRole("button"));
+		expect(onClose).toHaveBeenCalledOnce();
+	});
+});

apps/web/src/components/__tests__/difficulty-indicator.test.tsx

@@ -0,0 +1,59 @@
+// @vitest-environment jsdom
+import type { DifficultyResult } from "@initiative/domain";
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { DifficultyIndicator } from "../difficulty-indicator.js";
+
+afterEach(cleanup);
+
+function makeResult(tier: DifficultyResult["tier"]): DifficultyResult {
+	return {
+		tier,
+		totalMonsterXp: 100,
+		partyBudget: { low: 50, moderate: 100, high: 200 },
+	};
+}
+
+describe("DifficultyIndicator", () => {
+	it("renders 3 bars", () => {
+		const { container } = render(
+			<DifficultyIndicator result={makeResult("moderate")} />,
+		);
+		const bars = container.querySelectorAll("[class*='rounded-sm']");
+		expect(bars).toHaveLength(3);
+	});
+
+	it("shows 'Trivial encounter difficulty' label for trivial tier", () => {
+		render(<DifficultyIndicator result={makeResult("trivial")} />);
+		expect(
+			screen.getByRole("img", {
+				name: "Trivial encounter difficulty",
+			}),
+		).toBeDefined();
+	});
+
+	it("shows 'Low encounter difficulty' label for low tier", () => {
+		render(<DifficultyIndicator result={makeResult("low")} />);
+		expect(
+			screen.getByRole("img", { name: "Low encounter difficulty" }),
+		).toBeDefined();
+	});
+
+	it("shows 'Moderate encounter difficulty' label for moderate tier", () => {
+		render(<DifficultyIndicator result={makeResult("moderate")} />);
+		expect(
+			screen.getByRole("img", {
+				name: "Moderate encounter difficulty",
+			}),
+		).toBeDefined();
+	});
+
+	it("shows 'High encounter difficulty' label for high tier", () => {
+		render(<DifficultyIndicator result={makeResult("high")} />);
+		expect(
+			screen.getByRole("img", {
+				name: "High encounter difficulty",
+			}),
+		).toBeDefined();
+	});
+});

apps/web/src/components/__tests__/export-method-dialog.test.tsx

@@ -0,0 +1,86 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { polyfillDialog } from "../../__tests__/polyfill-dialog.js";
+import { ExportMethodDialog } from "../export-method-dialog.js";
+
+afterEach(cleanup);
+
+beforeAll(() => {
+	polyfillDialog();
+});
+
+function renderDialog(open = true) {
+	const onDownload = vi.fn();
+	const onCopyToClipboard = vi.fn();
+	const onClose = vi.fn();
+	const result = render(
+		<ExportMethodDialog
+			open={open}
+			onDownload={onDownload}
+			onCopyToClipboard={onCopyToClipboard}
+			onClose={onClose}
+		/>,
+	);
+	return { ...result, onDownload, onCopyToClipboard, onClose };
+}
+
+describe("ExportMethodDialog", () => {
+	it("renders filename input and unchecked history checkbox", () => {
+		renderDialog();
+		expect(
+			screen.getByPlaceholderText("Filename (optional)"),
+		).toBeInTheDocument();
+		const checkbox = screen.getByRole("checkbox");
+		expect(checkbox).not.toBeChecked();
+	});
+
+	it("download button calls onDownload with defaults", async () => {
+		const user = userEvent.setup();
+		const { onDownload } = renderDialog();
+
+		await user.click(screen.getByText("Download file"));
+		expect(onDownload).toHaveBeenCalledWith(false, "");
+	});
+
+	it("download with filename and history checked", async () => {
+		const user = userEvent.setup();
+		const { onDownload } = renderDialog();
+
+		await user.type(
+			screen.getByPlaceholderText("Filename (optional)"),
+			"my-encounter",
+		);
+		await user.click(screen.getByRole("checkbox"));
+		await user.click(screen.getByText("Download file"));
+		expect(onDownload).toHaveBeenCalledWith(true, "my-encounter");
+	});
+
+	it("copy to clipboard calls onCopyToClipboard and shows Copied", async () => {
+		const user = userEvent.setup();
+		const { onCopyToClipboard } = renderDialog();
+
+		await user.click(screen.getByText("Copy to clipboard"));
+		expect(onCopyToClipboard).toHaveBeenCalledWith(false);
+		expect(screen.getByText("Copied!")).toBeInTheDocument();
+	});
+
+	it("Copied! reverts after 2 seconds", async () => {
+		const user = userEvent.setup();
+		renderDialog();
+
+		await user.click(screen.getByText("Copy to clipboard"));
+		expect(screen.getByText("Copied!")).toBeInTheDocument();
+
+		await waitFor(
+			() => {
+				expect(screen.queryByText("Copied!")).not.toBeInTheDocument();
+			},
+			{ timeout: 3000 },
+		);
+		expect(screen.getByText("Copy to clipboard")).toBeInTheDocument();
+	});
+});

apps/web/src/components/__tests__/import-method-dialog.test.tsx

@@ -0,0 +1,98 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { polyfillDialog } from "../../__tests__/polyfill-dialog.js";
+import { ImportMethodDialog } from "../import-method-dialog.js";
+
+beforeAll(() => {
+	polyfillDialog();
+});
+
+afterEach(cleanup);
+
+function renderDialog(open = true) {
+	const onSelectFile = vi.fn();
+	const onSubmitClipboard = vi.fn();
+	const onClose = vi.fn();
+	const result = render(
+		<ImportMethodDialog
+			open={open}
+			onSelectFile={onSelectFile}
+			onSubmitClipboard={onSubmitClipboard}
+			onClose={onClose}
+		/>,
+	);
+	return { ...result, onSelectFile, onSubmitClipboard, onClose };
+}
+
+describe("ImportMethodDialog", () => {
+	it("opens in pick mode with two method buttons", () => {
+		renderDialog();
+		expect(screen.getByText("From file")).toBeInTheDocument();
+		expect(screen.getByText("Paste content")).toBeInTheDocument();
+	});
+
+	it("From file button calls onSelectFile and closes", async () => {
+		const user = userEvent.setup();
+		const { onSelectFile, onClose } = renderDialog();
+
+		await user.click(screen.getByText("From file"));
+		expect(onSelectFile).toHaveBeenCalled();
+		expect(onClose).toHaveBeenCalled();
+	});
+
+	it("Paste content button switches to paste mode", async () => {
+		const user = userEvent.setup();
+		renderDialog();
+
+		await user.click(screen.getByText("Paste content"));
+		expect(
+			screen.getByPlaceholderText("Paste exported JSON here..."),
+		).toBeInTheDocument();
+		expect(screen.getByRole("button", { name: "Import" })).toBeDisabled();
+	});
+
+	it("typing text enables Import button", async () => {
+		const user = userEvent.setup();
+		renderDialog();
+
+		await user.click(screen.getByText("Paste content"));
+		const textarea = screen.getByPlaceholderText("Paste exported JSON here...");
+		await user.type(textarea, "test-data");
+		expect(screen.getByRole("button", { name: "Import" })).not.toBeDisabled();
+	});
+
+	it("Import calls onSubmitClipboard with text and closes", async () => {
+		const user = userEvent.setup();
+		const { onSubmitClipboard, onClose } = renderDialog();
+
+		await user.click(screen.getByText("Paste content"));
+		await user.type(
+			screen.getByPlaceholderText("Paste exported JSON here..."),
+			"some-json-content",
+		);
+		await user.click(screen.getByRole("button", { name: "Import" }));
+		expect(onSubmitClipboard).toHaveBeenCalledWith("some-json-content");
+		expect(onClose).toHaveBeenCalled();
+	});
+
+	it("Back button returns to pick mode and clears text", async () => {
+		const user = userEvent.setup();
+		renderDialog();
+
+		await user.click(screen.getByText("Paste content"));
+		await user.type(
+			screen.getByPlaceholderText("Paste exported JSON here..."),
+			"some text",
+		);
+		await user.click(screen.getByRole("button", { name: "Back" }));
+
+		expect(screen.getByText("From file")).toBeInTheDocument();
+		expect(
+			screen.queryByPlaceholderText("Paste exported JSON here..."),
+		).not.toBeInTheDocument();
+	});
+});

apps/web/src/components/__tests__/overflow-menu.test.tsx

@@ -0,0 +1,89 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { userEvent } from "@testing-library/user-event";
+import { Circle } from "lucide-react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { OverflowMenu } from "../ui/overflow-menu.js";
+
+afterEach(cleanup);
+
+const items = [
+	{ icon: <Circle />, label: "Action A", onClick: vi.fn() },
+	{ icon: <Circle />, label: "Action B", onClick: vi.fn() },
+];
+
+describe("OverflowMenu", () => {
+	it("renders toggle button", () => {
+		render(<OverflowMenu items={items} />);
+		expect(screen.getByRole("button", { name: "More actions" })).toBeDefined();
+	});
+
+	it("does not show menu items when closed", () => {
+		render(<OverflowMenu items={items} />);
+		expect(screen.queryByText("Action A")).toBeNull();
+	});
+
+	it("shows menu items when toggled open", async () => {
+		render(<OverflowMenu items={items} />);
+
+		await userEvent.click(screen.getByRole("button", { name: "More actions" }));
+
+		expect(screen.getByText("Action A")).toBeDefined();
+		expect(screen.getByText("Action B")).toBeDefined();
+	});
+
+	it("closes menu after clicking an item", async () => {
+		const onClick = vi.fn();
+		render(
+			<OverflowMenu items={[{ icon: <Circle />, label: "Do it", onClick }]} />,
+		);
+
+		await userEvent.click(screen.getByRole("button", { name: "More actions" }));
+		await userEvent.click(screen.getByText("Do it"));
+
+		expect(onClick).toHaveBeenCalledOnce();
+		expect(screen.queryByText("Do it")).toBeNull();
+	});
+
+	it("keeps menu open when keepOpen is true", async () => {
+		const onClick = vi.fn();
+		render(
+			<OverflowMenu
+				items={[
+					{
+						icon: <Circle />,
+						label: "Stay",
+						onClick,
+						keepOpen: true,
+					},
+				]}
+			/>,
+		);
+
+		await userEvent.click(screen.getByRole("button", { name: "More actions" }));
+		await userEvent.click(screen.getByText("Stay"));
+
+		expect(onClick).toHaveBeenCalledOnce();
+		expect(screen.getByText("Stay")).toBeDefined();
+	});
+
+	it("disables items when disabled is true", async () => {
+		const onClick = vi.fn();
+		render(
+			<OverflowMenu
+				items={[
+					{
+						icon: <Circle />,
+						label: "Nope",
+						onClick,
+						disabled: true,
+					},
+				]}
+			/>,
+		);
+
+		await userEvent.click(screen.getByRole("button", { name: "More actions" }));
+		const item = screen.getByText("Nope");
+		expect(item.closest("button")?.hasAttribute("disabled")).toBe(true);
+	});
+});

apps/web/src/components/__tests__/player-character-section.test.tsx

@@ -0,0 +1,134 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { createRef } from "react";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { polyfillDialog } from "../../__tests__/polyfill-dialog.js";
+import { AllProviders } from "../../__tests__/test-providers.js";
+import {
+	PlayerCharacterSection,
+	type PlayerCharacterSectionHandle,
+} from "../player-character-section.js";
+
+const CREATE_FIRST_PC_REGEX = /create your first player character/i;
+
+beforeAll(() => {
+	polyfillDialog();
+	Object.defineProperty(globalThis, "matchMedia", {
+		writable: true,
+		value: vi.fn().mockImplementation((query: string) => ({
+			matches: false,
+			media: query,
+			onchange: null,
+			addListener: vi.fn(),
+			removeListener: vi.fn(),
+			addEventListener: vi.fn(),
+			removeEventListener: vi.fn(),
+			dispatchEvent: vi.fn(),
+		})),
+	});
+});
+
+afterEach(cleanup);
+
+vi.mock("../../persistence/encounter-storage.js", () => ({
+	loadEncounter: () => null,
+	saveEncounter: () => {},
+}));
+
+vi.mock("../../persistence/player-character-storage.js", () => ({
+	loadPlayerCharacters: () => [],
+	savePlayerCharacters: () => {},
+}));
+
+vi.mock("../../adapters/bestiary-cache.js", () => ({
+	loadAllCachedCreatures: () => Promise.resolve(new Map()),
+	isSourceCached: () => Promise.resolve(false),
+	cacheSource: () => Promise.resolve(),
+	getCachedSources: () => Promise.resolve([]),
+	clearSource: () => Promise.resolve(),
+	clearAll: () => Promise.resolve(),
+}));
+
+vi.mock("../../adapters/bestiary-index-adapter.js", () => ({
+	loadBestiaryIndex: () => ({ sources: {}, creatures: [] }),
+	getAllSourceCodes: () => [],
+	getDefaultFetchUrl: () => "",
+	getSourceDisplayName: (code: string) => code,
+}));
+
+function renderSection() {
+	const ref = createRef<PlayerCharacterSectionHandle>();
+	const result = render(<PlayerCharacterSection ref={ref} />, {
+		wrapper: AllProviders,
+	});
+	return { ...result, ref };
+}
+
+describe("PlayerCharacterSection", () => {
+	it("openManagement ref handle opens the management dialog", async () => {
+		const { ref } = renderSection();
+
+		const handle = ref.current;
+		if (!handle) throw new Error("ref not set");
+		act(() => handle.openManagement());
+
+		// Management dialog should now be open with its title visible
+		await waitFor(() => {
+			const dialogs = document.querySelectorAll("dialog");
+			const managementDialog = Array.from(dialogs).find((d) =>
+				d.textContent?.includes("Player Characters"),
+			);
+			expect(managementDialog).toHaveAttribute("open");
+		});
+	});
+
+	it("creating a character from management opens create modal", async () => {
+		const user = userEvent.setup();
+		const { ref } = renderSection();
+
+		const handle = ref.current;
+		if (!handle) throw new Error("ref not set");
+		act(() => handle.openManagement());
+
+		await user.click(
+			screen.getByRole("button", {
+				name: CREATE_FIRST_PC_REGEX,
+			}),
+		);
+
+		// Create modal should now be visible
+		await waitFor(() => {
+			expect(screen.getByPlaceholderText("Character name")).toBeInTheDocument();
+		});
+	});
+
+	it("saving a new character and returning to management", async () => {
+		const user = userEvent.setup();
+		const { ref } = renderSection();
+
+		const handle = ref.current;
+		if (!handle) throw new Error("ref not set");
+		act(() => handle.openManagement());
+
+		await user.click(
+			screen.getByRole("button", {
+				name: CREATE_FIRST_PC_REGEX,
+			}),
+		);
+
+		// Fill in the create form
+		await user.type(screen.getByPlaceholderText("Character name"), "Aria");
+		await user.type(screen.getByPlaceholderText("AC"), "16");
+		await user.type(screen.getByPlaceholderText("Max HP"), "30");
+
+		await user.click(screen.getByRole("button", { name: "Create" }));
+
+		// Should return to management dialog showing the new character
+		await waitFor(() => {
+			expect(screen.getByText("Aria")).toBeInTheDocument();
+		});
+	});
+});

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

@@ -0,0 +1,120 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import { type PlayerCharacter, playerCharacterId } from "@initiative/domain";
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { polyfillDialog } from "../../__tests__/polyfill-dialog.js";
+
+afterEach(cleanup);
+
+const CREATE_FIRST_PC_REGEX = /create your first player character/i;
+const LEVEL_REGEX = /^Lv /;
+
+import { PlayerManagement } from "../player-management.js";
+
+beforeAll(() => {
+	polyfillDialog();
+});
+
+const PC_WARRIOR: PlayerCharacter = {
+	id: playerCharacterId("pc-1"),
+	name: "Thorin",
+	ac: 18,
+	maxHp: 45,
+	color: "red",
+	icon: "sword",
+};
+
+const PC_WIZARD: PlayerCharacter = {
+	id: playerCharacterId("pc-2"),
+	name: "Gandalf",
+	ac: 12,
+	maxHp: 30,
+	color: "blue",
+	icon: "wand",
+	level: 10,
+};
+
+function renderManagement(
+	overrides: Partial<Parameters<typeof PlayerManagement>[0]> = {},
+) {
+	const props = {
+		open: true,
+		onClose: vi.fn(),
+		characters: [] as readonly PlayerCharacter[],
+		onEdit: vi.fn(),
+		onDelete: vi.fn(),
+		onCreate: vi.fn(),
+		...overrides,
+	};
+	return { ...render(<PlayerManagement {...props} />), props };
+}
+
+describe("PlayerManagement", () => {
+	it("shows empty state when no characters", () => {
+		renderManagement();
+		expect(screen.getByText("No player characters yet")).toBeInTheDocument();
+	});
+
+	it("shows create button in empty state that calls onCreate", async () => {
+		const user = userEvent.setup();
+		const { props } = renderManagement();
+
+		await user.click(
+			screen.getByRole("button", {
+				name: CREATE_FIRST_PC_REGEX,
+			}),
+		);
+		expect(props.onCreate).toHaveBeenCalled();
+	});
+
+	it("renders each character with name, AC, HP", () => {
+		renderManagement({ characters: [PC_WARRIOR, PC_WIZARD] });
+		expect(screen.getByText("Thorin")).toBeInTheDocument();
+		expect(screen.getByText("Gandalf")).toBeInTheDocument();
+		expect(screen.getByText("AC 18")).toBeInTheDocument();
+		expect(screen.getByText("HP 45")).toBeInTheDocument();
+		expect(screen.getByText("AC 12")).toBeInTheDocument();
+		expect(screen.getByText("HP 30")).toBeInTheDocument();
+	});
+
+	it("shows level when present, omits when undefined", () => {
+		renderManagement({ characters: [PC_WARRIOR, PC_WIZARD] });
+		expect(screen.getByText("Lv 10")).toBeInTheDocument();
+		// Thorin has no level — there should be only one "Lv" text
+		expect(screen.queryAllByText(LEVEL_REGEX)).toHaveLength(1);
+	});
+
+	it("edit button calls onEdit with the character", async () => {
+		const user = userEvent.setup();
+		const { props } = renderManagement({ characters: [PC_WARRIOR] });
+
+		await user.click(screen.getByRole("button", { name: "Edit" }));
+		expect(props.onEdit).toHaveBeenCalledWith(PC_WARRIOR);
+	});
+
+	it("delete button calls onDelete after confirmation", async () => {
+		const user = userEvent.setup();
+		const { props } = renderManagement({ characters: [PC_WARRIOR] });
+
+		const deleteBtn = screen.getByRole("button", {
+			name: "Delete player character",
+		});
+		await user.click(deleteBtn);
+		const confirmBtn = screen.getByRole("button", {
+			name: "Confirm delete player character",
+		});
+		await user.click(confirmBtn);
+		expect(props.onDelete).toHaveBeenCalledWith(PC_WARRIOR.id);
+	});
+
+	it("add button calls onCreate", async () => {
+		const user = userEvent.setup();
+		const { props } = renderManagement({ characters: [PC_WARRIOR] });
+
+		await user.click(screen.getByRole("button", { name: "Add" }));
+		expect(props.onCreate).toHaveBeenCalled();
+	});
+});

apps/web/src/components/__tests__/roll-mode-menu.test.tsx

@@ -0,0 +1,55 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { userEvent } from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { RollModeMenu } from "../roll-mode-menu.js";
+
+afterEach(cleanup);
+
+describe("RollModeMenu", () => {
+	it("renders advantage and disadvantage buttons", () => {
+		render(
+			<RollModeMenu
+				position={{ x: 100, y: 100 }}
+				onSelect={() => {}}
+				onClose={() => {}}
+			/>,
+		);
+		expect(screen.getByText("Advantage")).toBeDefined();
+		expect(screen.getByText("Disadvantage")).toBeDefined();
+	});
+
+	it("calls onSelect with 'advantage' and onClose when clicked", async () => {
+		const onSelect = vi.fn();
+		const onClose = vi.fn();
+		render(
+			<RollModeMenu
+				position={{ x: 100, y: 100 }}
+				onSelect={onSelect}
+				onClose={onClose}
+			/>,
+		);
+
+		await userEvent.click(screen.getByText("Advantage"));
+
+		expect(onSelect).toHaveBeenCalledWith("advantage");
+		expect(onClose).toHaveBeenCalled();
+	});
+
+	it("calls onSelect with 'disadvantage' and onClose when clicked", async () => {
+		const onSelect = vi.fn();
+		const onClose = vi.fn();
+		render(
+			<RollModeMenu
+				position={{ x: 100, y: 100 }}
+				onSelect={onSelect}
+				onClose={onClose}
+			/>,
+		);
+
+		await userEvent.click(screen.getByText("Disadvantage"));
+
+		expect(onSelect).toHaveBeenCalledWith("disadvantage");
+		expect(onClose).toHaveBeenCalled();
+	});
+});

apps/web/src/components/__tests__/settings-modal.test.tsx

@@ -0,0 +1,110 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+
+afterEach(cleanup);
+
+import { polyfillDialog } from "../../__tests__/polyfill-dialog.js";
+import { AllProviders } from "../../__tests__/test-providers.js";
+import { SettingsModal } from "../settings-modal.js";
+
+beforeAll(() => {
+	polyfillDialog();
+	Object.defineProperty(globalThis, "matchMedia", {
+		writable: true,
+		value: vi.fn().mockImplementation((query: string) => ({
+			matches: false,
+			media: query,
+			onchange: null,
+			addListener: vi.fn(),
+			removeListener: vi.fn(),
+			addEventListener: vi.fn(),
+			removeEventListener: vi.fn(),
+			dispatchEvent: vi.fn(),
+		})),
+	});
+});
+
+vi.mock("../../persistence/encounter-storage.js", () => ({
+	loadEncounter: () => null,
+	saveEncounter: () => {},
+}));
+
+vi.mock("../../persistence/player-character-storage.js", () => ({
+	loadPlayerCharacters: () => [],
+	savePlayerCharacters: () => {},
+}));
+
+vi.mock("../../adapters/bestiary-cache.js", () => ({
+	loadAllCachedCreatures: () => Promise.resolve(new Map()),
+	isSourceCached: () => Promise.resolve(false),
+	cacheSource: () => Promise.resolve(),
+	getCachedSources: () => Promise.resolve([]),
+	clearSource: () => Promise.resolve(),
+	clearAll: () => Promise.resolve(),
+}));
+
+vi.mock("../../adapters/bestiary-index-adapter.js", () => ({
+	loadBestiaryIndex: () => ({ sources: {}, creatures: [] }),
+	getAllSourceCodes: () => [],
+	getDefaultFetchUrl: () => "",
+	getSourceDisplayName: (code: string) => code,
+}));
+
+function renderModal(open = true) {
+	const onClose = vi.fn();
+	const result = render(<SettingsModal open={open} onClose={onClose} />, {
+		wrapper: AllProviders,
+	});
+	return { ...result, onClose };
+}
+
+describe("SettingsModal", () => {
+	it("renders edition toggle buttons", () => {
+		renderModal();
+		expect(
+			screen.getByRole("button", { name: "5e (2014)" }),
+		).toBeInTheDocument();
+		expect(
+			screen.getByRole("button", { name: "5.5e (2024)" }),
+		).toBeInTheDocument();
+	});
+
+	it("renders theme toggle buttons", () => {
+		renderModal();
+		expect(screen.getByRole("button", { name: "System" })).toBeInTheDocument();
+		expect(screen.getByRole("button", { name: "Light" })).toBeInTheDocument();
+		expect(screen.getByRole("button", { name: "Dark" })).toBeInTheDocument();
+	});
+
+	it("clicking an edition button switches the active edition", async () => {
+		const user = userEvent.setup();
+		renderModal();
+		const btn5e = screen.getByRole("button", { name: "5e (2014)" });
+		await user.click(btn5e);
+		// After clicking 5e, it should have the active style
+		expect(btn5e.className).toContain("bg-accent");
+	});
+
+	it("clicking a theme button switches the active theme", async () => {
+		const user = userEvent.setup();
+		renderModal();
+		const darkBtn = screen.getByRole("button", { name: "Dark" });
+		await user.click(darkBtn);
+		expect(darkBtn.className).toContain("bg-accent");
+	});
+
+	it("close button calls onClose", async () => {
+		const user = userEvent.setup();
+		const { onClose } = renderModal();
+		// DialogHeader renders an X button
+		const buttons = screen.getAllByRole("button");
+		const closeBtn = buttons.find((b) => b.querySelector(".h-4.w-4") !== null);
+		expect(closeBtn).toBeDefined();
+		await user.click(closeBtn as HTMLElement);
+		expect(onClose).toHaveBeenCalled();
+	});
+});

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

@@ -0,0 +1,124 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { SourceFetchPrompt } from "../source-fetch-prompt.js";
+
+const MONSTER_MANUAL_REGEX = /Monster Manual/;
+
+afterEach(cleanup);
+
+const mockFetchAndCacheSource = vi.fn();
+const mockUploadAndCacheSource = vi.fn();
+
+vi.mock("../../contexts/bestiary-context.js", () => ({
+	useBestiaryContext: () => ({
+		fetchAndCacheSource: mockFetchAndCacheSource,
+		uploadAndCacheSource: mockUploadAndCacheSource,
+	}),
+}));
+
+vi.mock("../../adapters/bestiary-index-adapter.js", () => ({
+	getDefaultFetchUrl: (code: string) =>
+		`https://example.com/bestiary/${code}.json`,
+	getSourceDisplayName: (code: string) =>
+		code === "MM" ? "Monster Manual" : code,
+	loadBestiaryIndex: () => ({ sources: {}, creatures: [] }),
+	getAllSourceCodes: () => [],
+}));
+
+function renderPrompt(sourceCode = "MM") {
+	const onSourceLoaded = vi.fn();
+	const result = render(
+		<SourceFetchPrompt
+			sourceCode={sourceCode}
+			onSourceLoaded={onSourceLoaded}
+		/>,
+	);
+	return { ...result, onSourceLoaded };
+}
+
+describe("SourceFetchPrompt", () => {
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it("renders source name, URL input, Load and Upload buttons", () => {
+		renderPrompt();
+		expect(screen.getByText(MONSTER_MANUAL_REGEX)).toBeInTheDocument();
+		expect(
+			screen.getByDisplayValue("https://example.com/bestiary/MM.json"),
+		).toBeInTheDocument();
+		expect(screen.getByText("Load")).toBeInTheDocument();
+		expect(screen.getByText("Upload file")).toBeInTheDocument();
+	});
+
+	it("Load calls fetchAndCacheSource and onSourceLoaded on success", async () => {
+		mockFetchAndCacheSource.mockResolvedValueOnce(undefined);
+		const user = userEvent.setup();
+		const { onSourceLoaded } = renderPrompt();
+
+		await user.click(screen.getByText("Load"));
+
+		await waitFor(() => {
+			expect(mockFetchAndCacheSource).toHaveBeenCalledWith(
+				"MM",
+				"https://example.com/bestiary/MM.json",
+			);
+			expect(onSourceLoaded).toHaveBeenCalled();
+		});
+	});
+
+	it("fetch error shows error message", async () => {
+		mockFetchAndCacheSource.mockRejectedValueOnce(new Error("Network error"));
+		const user = userEvent.setup();
+		renderPrompt();
+
+		await user.click(screen.getByText("Load"));
+
+		await waitFor(() => {
+			expect(screen.getByText("Network error")).toBeInTheDocument();
+		});
+	});
+
+	it("upload file calls uploadAndCacheSource and onSourceLoaded", async () => {
+		mockUploadAndCacheSource.mockResolvedValueOnce(undefined);
+		const user = userEvent.setup();
+		const { onSourceLoaded } = renderPrompt();
+
+		const file = new File(['{"monster":[]}'], "bestiary-mm.json", {
+			type: "application/json",
+		});
+		const fileInput = document.querySelector(
+			'input[type="file"]',
+		) as HTMLInputElement;
+		await user.upload(fileInput, file);
+
+		await waitFor(() => {
+			expect(mockUploadAndCacheSource).toHaveBeenCalledWith("MM", {
+				monster: [],
+			});
+			expect(onSourceLoaded).toHaveBeenCalled();
+		});
+	});
+
+	it("upload error shows error message", async () => {
+		mockUploadAndCacheSource.mockRejectedValueOnce(new Error("Invalid format"));
+		const user = userEvent.setup();
+		renderPrompt();
+
+		const file = new File(['{"bad": true}'], "bad.json", {
+			type: "application/json",
+		});
+		const fileInput = document.querySelector(
+			'input[type="file"]',
+		) as HTMLInputElement;
+		await user.upload(fileInput, file);
+
+		await waitFor(() => {
+			expect(screen.getByText("Invalid format")).toBeInTheDocument();
+		});
+	});
+});

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

@@ -0,0 +1,273 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import type { Creature } from "@initiative/domain";
+import { creatureId } from "@initiative/domain";
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { StatBlock } from "../stat-block.js";
+
+afterEach(cleanup);
+
+const ARMOR_CLASS_REGEX = /Armor Class/;
+const DEX_PLUS_4_REGEX = /Dex \+4/;
+const CR_QUARTER_REGEX = /1\/4/;
+const PROF_BONUS_2_REGEX = /Proficiency Bonus \+2/;
+const NIMBLE_ESCAPE_REGEX = /Nimble Escape\./;
+const SCIMITAR_REGEX = /Scimitar\./;
+const DETECT_REGEX = /Detect\./;
+const TAIL_ATTACK_REGEX = /Tail Attack\./;
+const INNATE_SPELLCASTING_REGEX = /Innate Spellcasting\./;
+const AT_WILL_REGEX = /At Will:/;
+const DETECT_MAGIC_REGEX = /detect magic, suggestion/;
+const DAILY_REGEX = /3\/day each:/;
+const FIREBALL_REGEX = /fireball, wall of fire/;
+const LONG_REST_REGEX = /1\/long rest:/;
+const WISH_REGEX = /wish/;
+
+const GOBLIN: Creature = {
+	id: creatureId("srd:goblin"),
+	name: "Goblin",
+	source: "MM",
+	sourceDisplayName: "Monster Manual",
+	size: "Small",
+	type: "humanoid",
+	alignment: "neutral evil",
+	ac: 15,
+	acSource: "leather armor, shield",
+	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,
+	savingThrows: "Dex +4",
+	skills: "Stealth +6",
+	senses: "darkvision 60 ft., passive Perception 9",
+	languages: "Common, Goblin",
+	traits: [{ name: "Nimble Escape", text: "Disengage or Hide as bonus." }],
+	actions: [{ name: "Scimitar", text: "Melee: +4 to hit, 5 slashing." }],
+	bonusActions: [{ name: "Nimble", text: "Disengage or Hide." }],
+	reactions: [{ name: "Redirect", text: "Redirect attack to ally." }],
+};
+
+const DRAGON: Creature = {
+	id: creatureId("srd:dragon"),
+	name: "Ancient Red Dragon",
+	source: "MM",
+	sourceDisplayName: "Monster Manual",
+	size: "Gargantuan",
+	type: "dragon",
+	alignment: "chaotic evil",
+	ac: 22,
+	hp: { average: 546, formula: "28d20 + 252" },
+	speed: "40 ft., climb 40 ft., fly 80 ft.",
+	abilities: { str: 30, dex: 10, con: 29, int: 18, wis: 15, cha: 23 },
+	cr: "24",
+	initiativeProficiency: 0,
+	proficiencyBonus: 7,
+	passive: 26,
+	resist: "fire",
+	immune: "fire",
+	vulnerable: "cold",
+	conditionImmune: "frightened",
+	legendaryActions: {
+		preamble: "The dragon can take 3 legendary actions.",
+		entries: [
+			{ name: "Detect", text: "Wisdom (Perception) check." },
+			{ name: "Tail Attack", text: "Tail attack." },
+		],
+	},
+	spellcasting: [
+		{
+			name: "Innate Spellcasting",
+			headerText: "The dragon's spellcasting ability is Charisma.",
+			atWill: ["detect magic", "suggestion"],
+			daily: [{ uses: 3, each: true, spells: ["fireball", "wall of fire"] }],
+			restLong: [{ uses: 1, each: false, spells: ["wish"] }],
+		},
+	],
+};
+
+function renderStatBlock(creature: Creature) {
+	return render(<StatBlock creature={creature} />);
+}
+
+describe("StatBlock", () => {
+	describe("header", () => {
+		it("renders creature name", () => {
+			renderStatBlock(GOBLIN);
+			expect(
+				screen.getByRole("heading", { name: "Goblin" }),
+			).toBeInTheDocument();
+		});
+
+		it("renders size, type, alignment", () => {
+			renderStatBlock(GOBLIN);
+			expect(
+				screen.getByText("Small humanoid, neutral evil"),
+			).toBeInTheDocument();
+		});
+
+		it("renders source display name", () => {
+			renderStatBlock(GOBLIN);
+			expect(screen.getByText("Monster Manual")).toBeInTheDocument();
+		});
+	});
+
+	describe("stats bar", () => {
+		it("renders AC with source", () => {
+			renderStatBlock(GOBLIN);
+			expect(screen.getByText(ARMOR_CLASS_REGEX)).toBeInTheDocument();
+			expect(screen.getByText("15")).toBeInTheDocument();
+			expect(screen.getByText("(leather armor, shield)")).toBeInTheDocument();
+		});
+
+		it("renders AC without source when acSource is undefined", () => {
+			renderStatBlock(DRAGON);
+			expect(screen.getByText("22")).toBeInTheDocument();
+		});
+
+		it("renders HP average and formula", () => {
+			renderStatBlock(GOBLIN);
+			expect(screen.getByText("7")).toBeInTheDocument();
+			expect(screen.getByText("(2d6)")).toBeInTheDocument();
+		});
+
+		it("renders speed", () => {
+			renderStatBlock(GOBLIN);
+			expect(screen.getByText("30 ft.")).toBeInTheDocument();
+		});
+	});
+
+	describe("ability scores", () => {
+		it("renders all 6 ability labels", () => {
+			renderStatBlock(GOBLIN);
+			for (const label of ["STR", "DEX", "CON", "INT", "WIS", "CHA"]) {
+				expect(screen.getByText(label)).toBeInTheDocument();
+			}
+		});
+
+		it("renders ability scores with modifier notation", () => {
+			renderStatBlock(GOBLIN);
+			expect(screen.getByText("(+2)")).toBeInTheDocument();
+		});
+	});
+
+	describe("properties", () => {
+		it("renders saving throws when present", () => {
+			renderStatBlock(GOBLIN);
+			expect(screen.getByText("Saving Throws")).toBeInTheDocument();
+			expect(screen.getByText(DEX_PLUS_4_REGEX)).toBeInTheDocument();
+		});
+
+		it("renders skills when present", () => {
+			renderStatBlock(GOBLIN);
+			expect(screen.getByText("Skills")).toBeInTheDocument();
+		});
+
+		it("renders damage resistances, immunities, vulnerabilities", () => {
+			renderStatBlock(DRAGON);
+			expect(screen.getByText("Damage Resistances")).toBeInTheDocument();
+			expect(screen.getByText("Damage Immunities")).toBeInTheDocument();
+			expect(screen.getByText("Damage Vulnerabilities")).toBeInTheDocument();
+			expect(screen.getByText("Condition Immunities")).toBeInTheDocument();
+		});
+
+		it("omits properties when undefined", () => {
+			renderStatBlock(GOBLIN);
+			expect(screen.queryByText("Damage Resistances")).not.toBeInTheDocument();
+			expect(screen.queryByText("Damage Immunities")).not.toBeInTheDocument();
+		});
+
+		it("renders CR and proficiency bonus", () => {
+			renderStatBlock(GOBLIN);
+			expect(screen.getByText("Challenge")).toBeInTheDocument();
+			expect(screen.getByText(CR_QUARTER_REGEX)).toBeInTheDocument();
+			expect(screen.getByText(PROF_BONUS_2_REGEX)).toBeInTheDocument();
+		});
+	});
+
+	describe("traits", () => {
+		it("renders trait entries", () => {
+			renderStatBlock(GOBLIN);
+			expect(screen.getByText(NIMBLE_ESCAPE_REGEX)).toBeInTheDocument();
+		});
+	});
+
+	describe("actions / bonus actions / reactions", () => {
+		it("renders actions heading and entries", () => {
+			renderStatBlock(GOBLIN);
+			expect(
+				screen.getByRole("heading", { name: "Actions" }),
+			).toBeInTheDocument();
+			expect(screen.getByText(SCIMITAR_REGEX)).toBeInTheDocument();
+		});
+
+		it("renders bonus actions heading and entries", () => {
+			renderStatBlock(GOBLIN);
+			expect(
+				screen.getByRole("heading", { name: "Bonus Actions" }),
+			).toBeInTheDocument();
+		});
+
+		it("renders reactions heading and entries", () => {
+			renderStatBlock(GOBLIN);
+			expect(
+				screen.getByRole("heading", { name: "Reactions" }),
+			).toBeInTheDocument();
+		});
+	});
+
+	describe("legendary actions", () => {
+		it("renders legendary actions with preamble", () => {
+			renderStatBlock(DRAGON);
+			expect(
+				screen.getByRole("heading", { name: "Legendary Actions" }),
+			).toBeInTheDocument();
+			expect(
+				screen.getByText("The dragon can take 3 legendary actions."),
+			).toBeInTheDocument();
+			expect(screen.getByText(DETECT_REGEX)).toBeInTheDocument();
+			expect(screen.getByText(TAIL_ATTACK_REGEX)).toBeInTheDocument();
+		});
+
+		it("omits legendary actions when undefined", () => {
+			renderStatBlock(GOBLIN);
+			expect(
+				screen.queryByRole("heading", { name: "Legendary Actions" }),
+			).not.toBeInTheDocument();
+		});
+	});
+
+	describe("spellcasting", () => {
+		it("renders spellcasting block with header", () => {
+			renderStatBlock(DRAGON);
+			expect(screen.getByText(INNATE_SPELLCASTING_REGEX)).toBeInTheDocument();
+		});
+
+		it("renders at-will spells", () => {
+			renderStatBlock(DRAGON);
+			expect(screen.getByText(AT_WILL_REGEX)).toBeInTheDocument();
+			expect(screen.getByText(DETECT_MAGIC_REGEX)).toBeInTheDocument();
+		});
+
+		it("renders daily spells", () => {
+			renderStatBlock(DRAGON);
+			expect(screen.getByText(DAILY_REGEX)).toBeInTheDocument();
+			expect(screen.getByText(FIREBALL_REGEX)).toBeInTheDocument();
+		});
+
+		it("renders long rest spells", () => {
+			renderStatBlock(DRAGON);
+			expect(screen.getByText(LONG_REST_REGEX)).toBeInTheDocument();
+			expect(screen.getByText(WISH_REGEX)).toBeInTheDocument();
+		});
+
+		it("omits spellcasting when undefined", () => {
+			renderStatBlock(GOBLIN);
+			expect(screen.queryByText(AT_WILL_REGEX)).not.toBeInTheDocument();
+		});
+	});
+});

apps/web/src/components/__tests__/toast.test.tsx

@@ -0,0 +1,68 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { userEvent } from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Toast } from "../toast.js";
+
+afterEach(cleanup);
+
+describe("Toast", () => {
+	it("renders message text", () => {
+		render(<Toast message="Hello" onDismiss={() => {}} />);
+		expect(screen.getByText("Hello")).toBeDefined();
+	});
+
+	it("renders progress bar when progress is provided", () => {
+		render(<Toast message="Loading" progress={0.5} onDismiss={() => {}} />);
+		const bar = document.body.querySelector("[style*='width']") as HTMLElement;
+		expect(bar).not.toBeNull();
+		expect(bar.style.width).toBe("50%");
+	});
+
+	it("does not render progress bar when progress is omitted", () => {
+		render(<Toast message="Done" onDismiss={() => {}} />);
+		const bar = document.body.querySelector("[style*='width']");
+		expect(bar).toBeNull();
+	});
+
+	it("calls onDismiss when close button is clicked", async () => {
+		const onDismiss = vi.fn();
+		render(<Toast message="Hi" onDismiss={onDismiss} />);
+
+		const toast = screen.getByText("Hi").closest("div");
+		const button = toast?.querySelector("button");
+		expect(button).not.toBeNull();
+		await userEvent.click(button as HTMLElement);
+
+		expect(onDismiss).toHaveBeenCalledOnce();
+	});
+
+	describe("auto-dismiss", () => {
+		beforeEach(() => {
+			vi.useFakeTimers();
+		});
+
+		afterEach(() => {
+			vi.useRealTimers();
+		});
+
+		it("auto-dismisses after specified timeout", () => {
+			const onDismiss = vi.fn();
+			render(
+				<Toast message="Auto" onDismiss={onDismiss} autoDismissMs={3000} />,
+			);
+
+			expect(onDismiss).not.toHaveBeenCalled();
+			vi.advanceTimersByTime(3000);
+			expect(onDismiss).toHaveBeenCalledOnce();
+		});
+
+		it("does not auto-dismiss when autoDismissMs is omitted", () => {
+			const onDismiss = vi.fn();
+			render(<Toast message="Stay" onDismiss={onDismiss} />);
+
+			vi.advanceTimersByTime(10000);
+			expect(onDismiss).not.toHaveBeenCalled();
+		});
+	});
+});

apps/web/src/components/__tests__/tooltip.test.tsx

@@ -0,0 +1,42 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { Tooltip } from "../ui/tooltip.js";
+
+afterEach(cleanup);
+
+describe("Tooltip", () => {
+	it("renders children", () => {
+		render(
+			<Tooltip content="Hint">
+				<button type="button">Hover me</button>
+			</Tooltip>,
+		);
+		expect(screen.getByText("Hover me")).toBeDefined();
+	});
+
+	it("does not show tooltip initially", () => {
+		render(
+			<Tooltip content="Hint">
+				<span>Target</span>
+			</Tooltip>,
+		);
+		expect(screen.queryByRole("tooltip")).toBeNull();
+	});
+
+	it("shows tooltip on pointer enter and hides on pointer leave", () => {
+		render(
+			<Tooltip content="Hint text">
+				<span>Target</span>
+			</Tooltip>,
+		);
+
+		const wrapper = screen.getByText("Target").closest("span");
+		fireEvent.pointerEnter(wrapper as HTMLElement);
+		expect(screen.getByRole("tooltip")).toBeDefined();
+		expect(screen.getByText("Hint text")).toBeDefined();
+
+		fireEvent.pointerLeave(wrapper as HTMLElement);
+		expect(screen.queryByRole("tooltip")).toBeNull();
+	});
+});

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

@@ -6,11 +6,19 @@ import { combatantId } from "@initiative/domain";
 import { cleanup, render, screen } from "@testing-library/react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
-// Mock the context module
+// Mock the context modules
 vi.mock("../../contexts/encounter-context.js", () => ({
 	useEncounterContext: vi.fn(),
 }));
 
+vi.mock("../../contexts/player-characters-context.js", () => ({
+	usePlayerCharactersContext: vi.fn().mockReturnValue({ characters: [] }),
+}));
+
+vi.mock("../../contexts/bestiary-context.js", () => ({
+	useBestiaryContext: vi.fn().mockReturnValue({ getCreature: () => undefined }),
+}));
+
 import { useEncounterContext } from "../../contexts/encounter-context.js";
 import { TurnNavigation } from "../turn-navigation.js";
 
@@ -52,9 +60,19 @@ function mockContext(overrides: Partial<Encounter> = {}) {
 		toggleCondition: vi.fn(),
 		toggleConcentration: vi.fn(),
 		addFromBestiary: vi.fn(),
+		addMultipleFromBestiary: vi.fn(),
 		addFromPlayerCharacter: vi.fn(),
 		makeStore: vi.fn(),
+		withUndo: vi.fn((action: () => unknown) => action()),
+		undo: vi.fn(),
+		redo: vi.fn(),
+		canUndo: false,
+		canRedo: false,
+		undoRedoState: { undoStack: [], redoStack: [] },
+		setEncounter: vi.fn(),
+		setUndoRedoState: vi.fn(),
 		events: [],
+		lastCreatureId: null,
 	};
 
 	mockUseEncounterContext.mockReturnValue(

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

@@ -1,6 +1,7 @@
-import type { CreatureId, PlayerCharacter } from "@initiative/domain";
+import type { PlayerCharacter } from "@initiative/domain";
 import {
 	Check,
+	Download,
 	Eye,
 	EyeOff,
 	Import,
@@ -8,35 +9,41 @@ import {
 	Minus,
 	Plus,
 	Settings,
+	Upload,
 	Users,
 } from "lucide-react";
-import React, {
-	type RefObject,
-	useCallback,
-	useDeferredValue,
-	useState,
-} from "react";
+import React, { type RefObject, useCallback, useRef, useState } from "react";
 import type { SearchResult } from "../contexts/bestiary-context.js";
-import { useBestiaryContext } from "../contexts/bestiary-context.js";
 import { useBulkImportContext } from "../contexts/bulk-import-context.js";
 import { useEncounterContext } from "../contexts/encounter-context.js";
 import { useInitiativeRollsContext } from "../contexts/initiative-rolls-context.js";
 import { usePlayerCharactersContext } from "../contexts/player-characters-context.js";
-import { useSidePanelContext } from "../contexts/side-panel-context.js";
+import {
+	creatureKey,
+	type QueuedCreature,
+	type SuggestionActions,
+	useActionBarState,
+} from "../hooks/use-action-bar-state.js";
 import { useLongPress } from "../hooks/use-long-press.js";
 import { cn } from "../lib/utils.js";
+import {
+	assembleExportBundle,
+	bundleToJson,
+	readImportFile,
+	triggerDownload,
+	validateImportBundle,
+} from "../persistence/export-import.js";
 import { D20Icon } from "./d20-icon.js";
+import { ExportMethodDialog } from "./export-method-dialog.js";
+import { ImportConfirmDialog } from "./import-confirm-prompt.js";
+import { ImportMethodDialog } from "./import-method-dialog.js";
 import { PLAYER_COLOR_HEX, PLAYER_ICON_MAP } from "./player-icon-map.js";
 import { RollModeMenu } from "./roll-mode-menu.js";
+import { Toast } from "./toast.js";
 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 {
 	inputRef?: RefObject<HTMLInputElement | null>;
 	autoFocus?: boolean;
@@ -44,8 +51,13 @@ interface ActionBarProps {
 	onOpenSettings?: () => void;
 }
 
-function creatureKey(r: SearchResult): string {
-	return `${r.source}:${r.name}`;
+interface AddModeSuggestionsProps {
+	nameInput: string;
+	suggestions: SearchResult[];
+	pcMatches: PlayerCharacter[];
+	suggestionIndex: number;
+	queued: QueuedCreature | null;
+	actions: SuggestionActions;
 }
 
 function AddModeSuggestions({
@@ -54,34 +66,15 @@ function AddModeSuggestions({
 	pcMatches,
 	suggestionIndex,
 	queued,
-	onDismiss,
-	onClickSuggestion,
-	onSetSuggestionIndex,
-	onSetQueued,
-	onConfirmQueued,
-	onAddFromPlayerCharacter,
-	onClear,
-}: Readonly<{
-	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;
-}>) {
+	actions,
+}: Readonly<AddModeSuggestionsProps>) {
 	return (
 		<div className="card-glow absolute bottom-full z-50 mb-1 w-full max-w-xs rounded-lg border border-border bg-card">
 			<button
 				type="button"
 				className="flex w-full items-center gap-1.5 border-border border-b px-3 py-2 text-left text-accent text-sm hover:bg-accent/20"
 				onMouseDown={(e) => e.preventDefault()}
-				onClick={onDismiss}
+				onClick={actions.dismiss}
 			>
 				<Plus className="h-3.5 w-3.5" />
 				<span className="flex-1">Add "{nameInput}" as custom</span>
@@ -108,8 +101,8 @@ function AddModeSuggestions({
 											className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-foreground text-sm hover:bg-hover-neutral-bg"
 											onMouseDown={(e) => e.preventDefault()}
 											onClick={() => {
-												onAddFromPlayerCharacter?.(pc);
-												onClear();
+												actions.addFromPlayerCharacter?.(pc);
+												actions.clear();
 											}}
 										>
 											{!!PcIcon && (
@@ -145,8 +138,8 @@ function AddModeSuggestions({
 												"hover:bg-hover-neutral-bg",
 										)}
 										onMouseDown={(e) => e.preventDefault()}
-										onClick={() => onClickSuggestion(result)}
-										onMouseEnter={() => onSetSuggestionIndex(i)}
+										onClick={() => actions.clickSuggestion(result)}
+										onMouseEnter={() => actions.setSuggestionIndex(i)}
 									>
 										<span>{result.name}</span>
 										<span className="flex items-center gap-1 text-muted-foreground text-xs">
@@ -159,9 +152,9 @@ function AddModeSuggestions({
 														onClick={(e) => {
 															e.stopPropagation();
 															if (queued.count <= 1) {
-																onSetQueued(null);
+																actions.setQueued(null);
 															} else {
-																onSetQueued({
+																actions.setQueued({
 																	...queued,
 																	count: queued.count - 1,
 																});
@@ -179,7 +172,7 @@ function AddModeSuggestions({
 														onMouseDown={(e) => e.preventDefault()}
 														onClick={(e) => {
 															e.stopPropagation();
-															onSetQueued({
+															actions.setQueued({
 																...queued,
 																count: queued.count + 1,
 															});
@@ -193,7 +186,7 @@ function AddModeSuggestions({
 														onMouseDown={(e) => e.preventDefault()}
 														onClick={(e) => {
 															e.stopPropagation();
-															onConfirmQueued();
+															actions.confirmQueued();
 														}}
 													>
 														<Check className="h-3.5 w-3.5" />
@@ -214,12 +207,160 @@ function AddModeSuggestions({
 	);
 }
 
+interface BrowseSuggestionsProps {
+	suggestions: SearchResult[];
+	suggestionIndex: number;
+	onSelect: (result: SearchResult) => void;
+	onHover: (index: number) => void;
+}
+
+function BrowseSuggestions({
+	suggestions,
+	suggestionIndex,
+	onSelect,
+	onHover,
+}: Readonly<BrowseSuggestionsProps>) {
+	if (suggestions.length === 0) return null;
+
+	return (
+		<div className="card-glow absolute bottom-full z-50 mb-1 w-full rounded-lg border border-border bg-card">
+			<ul className="max-h-48 overflow-y-auto py-1">
+				{suggestions.map((result, i) => (
+					<li key={creatureKey(result)}>
+						<button
+							type="button"
+							className={cn(
+								"flex w-full items-center justify-between px-3 py-1.5 text-left text-sm",
+								i === suggestionIndex
+									? "bg-accent/20 text-foreground"
+									: "text-foreground hover:bg-hover-neutral-bg",
+							)}
+							onMouseDown={(e) => e.preventDefault()}
+							onClick={() => onSelect(result)}
+							onMouseEnter={() => onHover(i)}
+						>
+							<span>{result.name}</span>
+							<span className="text-muted-foreground text-xs">
+								{result.sourceDisplayName}
+							</span>
+						</button>
+					</li>
+				))}
+			</ul>
+		</div>
+	);
+}
+
+interface CustomStatFieldsProps {
+	customInit: string;
+	customAc: string;
+	customMaxHp: string;
+	onInitChange: (v: string) => void;
+	onAcChange: (v: string) => void;
+	onMaxHpChange: (v: string) => void;
+}
+
+function CustomStatFields({
+	customInit,
+	customAc,
+	customMaxHp,
+	onInitChange,
+	onAcChange,
+	onMaxHpChange,
+}: Readonly<CustomStatFieldsProps>) {
+	return (
+		<div className="hidden items-center gap-2 sm:flex">
+			<Input
+				type="text"
+				inputMode="numeric"
+				value={customInit}
+				onChange={(e) => onInitChange(e.target.value)}
+				placeholder="Init"
+				className="w-16 text-center"
+			/>
+			<Input
+				type="text"
+				inputMode="numeric"
+				value={customAc}
+				onChange={(e) => onAcChange(e.target.value)}
+				placeholder="AC"
+				className="w-16 text-center"
+			/>
+			<Input
+				type="text"
+				inputMode="numeric"
+				value={customMaxHp}
+				onChange={(e) => onMaxHpChange(e.target.value)}
+				placeholder="MaxHP"
+				className="w-18 text-center"
+			/>
+		</div>
+	);
+}
+
+function RollAllButton() {
+	const { hasCreatureCombatants, canRollAllInitiative } = useEncounterContext();
+	const { handleRollAllInitiative } = useInitiativeRollsContext();
+
+	const [menuPos, setMenuPos] = useState<{
+		x: number;
+		y: number;
+	} | null>(null);
+
+	const openMenu = useCallback((x: number, y: number) => {
+		setMenuPos({ x, y });
+	}, []);
+
+	const longPress = useLongPress(
+		useCallback(
+			(e: React.TouchEvent) => {
+				const touch = e.touches[0];
+				if (touch) openMenu(touch.clientX, touch.clientY);
+			},
+			[openMenu],
+		),
+	);
+
+	if (!hasCreatureCombatants) return null;
+
+	return (
+		<>
+			<Button
+				type="button"
+				size="icon"
+				variant="ghost"
+				className="text-muted-foreground hover:text-hover-action"
+				onClick={() => handleRollAllInitiative()}
+				onContextMenu={(e) => {
+					e.preventDefault();
+					openMenu(e.clientX, e.clientY);
+				}}
+				{...longPress}
+				disabled={!canRollAllInitiative}
+				title="Roll all initiative"
+				aria-label="Roll all initiative"
+			>
+				<D20Icon className="h-6 w-6" />
+			</Button>
+			{!!menuPos && (
+				<RollModeMenu
+					position={menuPos}
+					onSelect={(mode) => handleRollAllInitiative(mode)}
+					onClose={() => setMenuPos(null)}
+				/>
+			)}
+		</>
+	);
+}
+
 function buildOverflowItems(opts: {
 	onManagePlayers?: () => void;
 	onOpenSourceManager?: () => void;
 	bestiaryLoaded: boolean;
 	onBulkImport?: () => void;
 	bulkImportDisabled?: boolean;
+	onExportEncounter: () => void;
+	onImportEncounter: () => void;
 	onOpenSettings?: () => void;
 }): OverflowMenuItem[] {
 	const items: OverflowMenuItem[] = [];
@@ -245,6 +386,16 @@ function buildOverflowItems(opts: {
 			disabled: opts.bulkImportDisabled,
 		});
 	}
+	items.push({
+		icon: <Download className="h-4 w-4" />,
+		label: "Export Encounter",
+		onClick: opts.onExportEncounter,
+	});
+	items.push({
+		icon: <Upload className="h-4 w-4" />,
+		label: "Import Encounter",
+		onClick: opts.onImportEncounter,
+	});
 	if (opts.onOpenSettings) {
 		items.push({
 			icon: <Settings className="h-4 w-4" />,
@@ -262,258 +413,151 @@ export function ActionBar({
 	onOpenSettings,
 }: Readonly<ActionBarProps>) {
 	const {
-		addCombatant,
-		addFromBestiary,
-		addFromPlayerCharacter,
-		hasCreatureCombatants,
-		canRollAllInitiative,
-	} = useEncounterContext();
-	const { search: bestiarySearch, isLoaded: bestiaryLoaded } =
-		useBestiaryContext();
-	const { characters: playerCharacters } = usePlayerCharactersContext();
-	const { showBulkImport, showSourceManager, showCreature, panelView } =
-		useSidePanelContext();
-	const { handleRollAllInitiative } = useInitiativeRollsContext();
+		nameInput,
+		suggestions,
+		pcMatches,
+		suggestionIndex,
+		queued,
+		customInit,
+		customAc,
+		customMaxHp,
+		browseMode,
+		bestiaryLoaded,
+		hasSuggestions,
+		showBulkImport,
+		showSourceManager,
+		suggestionActions,
+		handleNameChange,
+		handleKeyDown,
+		handleBrowseKeyDown,
+		handleAdd,
+		handleBrowseSelect,
+		toggleBrowseMode,
+		setCustomInit,
+		setCustomAc,
+		setCustomMaxHp,
+	} = useActionBarState();
+
 	const { state: bulkImportState } = useBulkImportContext();
+	const {
+		encounter,
+		undoRedoState,
+		isEmpty: encounterIsEmpty,
+		setEncounter,
+		setUndoRedoState,
+	} = useEncounterContext();
+	const { characters: playerCharacters, replacePlayerCharacters } =
+		usePlayerCharactersContext();
 
-	const handleAddFromBestiary = useCallback(
-		(result: SearchResult) => {
-			const creatureId = addFromBestiary(result);
-			if (creatureId && panelView.mode === "closed") {
-				showCreature(creatureId);
-			}
+	const importFileRef = useRef<HTMLInputElement>(null);
+	const [importError, setImportError] = useState<string | null>(null);
+	const [showExportMethod, setShowExportMethod] = useState(false);
+	const [showImportMethod, setShowImportMethod] = useState(false);
+	const [showImportConfirm, setShowImportConfirm] = useState(false);
+	const pendingBundleRef = useRef<
+		import("@initiative/domain").ExportBundle | null
+	>(null);
+
+	const handleExportDownload = useCallback(
+		(includeHistory: boolean, filename: string) => {
+			const bundle = assembleExportBundle(
+				encounter,
+				undoRedoState,
+				playerCharacters,
+				includeHistory,
+			);
+			triggerDownload(bundle, filename);
 		},
-		[addFromBestiary, panelView.mode, showCreature],
+		[encounter, undoRedoState, playerCharacters],
 	);
 
-	const handleViewStatBlock = useCallback(
-		(result: SearchResult) => {
-			const slug = result.name
-				.toLowerCase()
-				.replaceAll(/[^a-z0-9]+/g, "-")
-				.replaceAll(/(^-|-$)/g, "");
-			const cId = `${result.source.toLowerCase()}:${slug}` as CreatureId;
-			showCreature(cId);
+	const handleExportClipboard = useCallback(
+		(includeHistory: boolean) => {
+			const bundle = assembleExportBundle(
+				encounter,
+				undoRedoState,
+				playerCharacters,
+				includeHistory,
+			);
+			void navigator.clipboard.writeText(bundleToJson(bundle));
 		},
-		[showCreature],
+		[encounter, undoRedoState, playerCharacters],
 	);
 
-	const [nameInput, setNameInput] = useState("");
-	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++) {
-			handleAddFromBestiary(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: React.SubmitEvent<HTMLFormElement>) => {
-		e.preventDefault();
-		if (browseMode) return;
-		if (queued) {
-			confirmQueued();
-			return;
-		}
-		if (nameInput.trim() === "") return;
-		const opts: { initiative?: number; ac?: number; maxHp?: number } = {};
-		const init = parseNum(customInit);
-		const ac = parseNum(customAc);
-		const maxHp = parseNum(customMaxHp);
-		if (init !== undefined) opts.initiative = init;
-		if (ac !== undefined) opts.ac = ac;
-		if (maxHp !== undefined) opts.maxHp = maxHp;
-		addCombatant(nameInput, Object.keys(opts).length > 0 ? opts : undefined);
-		setNameInput("");
-		setSuggestions([]);
-		setPcMatches([]);
-		clearCustomFields();
-	};
-
-	const handleBrowseSearch = (value: string) => {
-		setSuggestions(value.length >= 2 ? bestiarySearch(value) : []);
-	};
-
-	const handleAddSearch = (value: string) => {
-		let newSuggestions: SearchResult[] = [];
-		let newPcMatches: PlayerCharacter[] = [];
-		if (value.length >= 2) {
-			newSuggestions = bestiarySearch(value);
-			setSuggestions(newSuggestions);
-			if (playerCharacters && playerCharacters.length > 0) {
-				const lower = value.toLowerCase();
-				newPcMatches = playerCharacters.filter((pc) =>
-					pc.name.toLowerCase().includes(lower),
-				);
-			}
-			setPcMatches(newPcMatches);
-		} else {
-			setSuggestions([]);
-			setPcMatches([]);
-		}
-		if (newSuggestions.length > 0 || newPcMatches.length > 0) {
-			clearCustomFields();
-		}
-		if (queued) {
-			const qKey = creatureKey(queued.result);
-			const stillVisible = newSuggestions.some((s) => creatureKey(s) === qKey);
-			if (!stillVisible) {
-				setQueued(null);
-			}
-		}
-	};
-
-	const handleNameChange = (value: string) => {
-		setNameInput(value);
-		setSuggestionIndex(-1);
-		if (browseMode) {
-			handleBrowseSearch(value);
-		} else {
-			handleAddSearch(value);
-		}
-	};
-
-	const handleClickSuggestion = (result: SearchResult) => {
-		const key = creatureKey(result);
-		if (queued && creatureKey(queued.result) === key) {
-			setQueued({ ...queued, count: queued.count + 1 });
-		} else {
-			setQueued({ result, count: 1 });
-		}
-	};
-
-	const handleEnter = () => {
-		if (queued) {
-			confirmQueued();
-		} else if (suggestionIndex >= 0) {
-			handleClickSuggestion(suggestions[suggestionIndex]);
-		}
-	};
-
-	const hasSuggestions =
-		deferredSuggestions.length > 0 || deferredPcMatches.length > 0;
-
-	const handleKeyDown = (e: React.KeyboardEvent) => {
-		if (!hasSuggestions) return;
-
-		if (e.key === "ArrowDown") {
-			e.preventDefault();
-			setSuggestionIndex((i) => (i < suggestions.length - 1 ? i + 1 : 0));
-		} else if (e.key === "ArrowUp") {
-			e.preventDefault();
-			setSuggestionIndex((i) => (i > 0 ? i - 1 : suggestions.length - 1));
-		} else if (e.key === "Enter") {
-			e.preventDefault();
-			handleEnter();
-		} else if (e.key === "Escape") {
-			dismissSuggestions();
-		}
-	};
-
-	const handleBrowseKeyDown = (e: React.KeyboardEvent) => {
-		if (e.key === "Escape") {
-			setBrowseMode(false);
-			clearInput();
-			return;
-		}
-		if (suggestions.length === 0) return;
-		if (e.key === "ArrowDown") {
-			e.preventDefault();
-			setSuggestionIndex((i) => (i < suggestions.length - 1 ? i + 1 : 0));
-		} else if (e.key === "ArrowUp") {
-			e.preventDefault();
-			setSuggestionIndex((i) => (i > 0 ? i - 1 : suggestions.length - 1));
-		} else if (e.key === "Enter" && suggestionIndex >= 0) {
-			e.preventDefault();
-			handleViewStatBlock(suggestions[suggestionIndex]);
-			setBrowseMode(false);
-			clearInput();
-		}
-	};
-
-	const handleBrowseSelect = (result: SearchResult) => {
-		handleViewStatBlock(result);
-		setBrowseMode(false);
-		clearInput();
-	};
-
-	const toggleBrowseMode = () => {
-		setBrowseMode((prev) => {
-			const next = !prev;
-			setSuggestionIndex(-1);
-			setQueued(null);
-			if (next) {
-				handleBrowseSearch(nameInput);
-			} else {
-				handleAddSearch(nameInput);
-			}
-			return next;
+	const applyImport = useCallback(
+		(bundle: import("@initiative/domain").ExportBundle) => {
+			setEncounter(bundle.encounter);
+			setUndoRedoState({
+				undoStack: bundle.undoStack,
+				redoStack: bundle.redoStack,
 			});
-		clearCustomFields();
-	};
-
-	const [rollAllMenuPos, setRollAllMenuPos] = useState<{
-		x: number;
-		y: number;
-	} | null>(null);
-
-	const openRollAllMenu = useCallback((x: number, y: number) => {
-		setRollAllMenuPos({ x, y });
-	}, []);
-
-	const rollAllLongPress = useLongPress(
-		useCallback(
-			(e: React.TouchEvent) => {
-				const touch = e.touches[0];
-				if (touch) openRollAllMenu(touch.clientX, touch.clientY);
+			replacePlayerCharacters([...bundle.playerCharacters]);
 		},
-			[openRollAllMenu],
-		),
+		[setEncounter, setUndoRedoState, replacePlayerCharacters],
 	);
 
+	const handleValidatedBundle = useCallback(
+		(result: import("@initiative/domain").ExportBundle | string) => {
+			if (typeof result === "string") {
+				setImportError(result);
+				return;
+			}
+			if (encounterIsEmpty) {
+				applyImport(result);
+			} else {
+				pendingBundleRef.current = result;
+				setShowImportConfirm(true);
+			}
+		},
+		[encounterIsEmpty, applyImport],
+	);
+
+	const handleImportFile = useCallback(
+		async (e: React.ChangeEvent<HTMLInputElement>) => {
+			const file = e.target.files?.[0];
+			if (!file) return;
+			if (importFileRef.current) importFileRef.current.value = "";
+
+			setImportError(null);
+			handleValidatedBundle(await readImportFile(file));
+		},
+		[handleValidatedBundle],
+	);
+
+	const handleImportClipboard = useCallback(
+		(text: string) => {
+			setImportError(null);
+			try {
+				const parsed: unknown = JSON.parse(text);
+				handleValidatedBundle(validateImportBundle(parsed));
+			} catch {
+				setImportError("Invalid file format");
+			}
+		},
+		[handleValidatedBundle],
+	);
+
+	const handleImportConfirm = useCallback(() => {
+		if (pendingBundleRef.current) {
+			applyImport(pendingBundleRef.current);
+			pendingBundleRef.current = null;
+		}
+		setShowImportConfirm(false);
+	}, [applyImport]);
+
+	const handleImportCancel = useCallback(() => {
+		pendingBundleRef.current = null;
+		setShowImportConfirm(false);
+	}, []);
+
 	const overflowItems = buildOverflowItems({
 		onManagePlayers,
 		onOpenSourceManager: showSourceManager,
 		bestiaryLoaded,
 		onBulkImport: showBulkImport,
 		bulkImportDisabled: bulkImportState.status === "loading",
+		onExportEncounter: () => setShowExportMethod(true),
+		onImportEncounter: () => setShowImportMethod(true),
 		onOpenSettings,
 	});
 
@@ -521,7 +565,7 @@ export function ActionBar({
 		<div className="card-glow flex items-center gap-3 border-border border-t bg-card px-4 py-3 sm:rounded-lg sm:border">
 			<form
 				onSubmit={handleAdd}
-				className="relative flex flex-1 items-center gap-2"
+				className="relative flex flex-1 flex-wrap items-center gap-3 sm:flex-nowrap"
 			>
 				<div className="flex-1">
 					<div className="relative max-w-xs">
@@ -559,112 +603,73 @@ export function ActionBar({
 								)}
 							</button>
 						)}
-						{browseMode && deferredSuggestions.length > 0 && (
-							<div className="card-glow absolute bottom-full z-50 mb-1 w-full rounded-lg border border-border bg-card">
-								<ul className="max-h-48 overflow-y-auto py-1">
-									{deferredSuggestions.map((result, i) => (
-										<li key={creatureKey(result)}>
-											<button
-												type="button"
-												className={cn(
-													"flex w-full items-center justify-between px-3 py-1.5 text-left text-sm",
-													i === suggestionIndex
-														? "bg-accent/20 text-foreground"
-														: "text-foreground hover:bg-hover-neutral-bg",
-												)}
-												onMouseDown={(e) => e.preventDefault()}
-												onClick={() => handleBrowseSelect(result)}
-												onMouseEnter={() => setSuggestionIndex(i)}
-											>
-												<span>{result.name}</span>
-												<span className="text-muted-foreground text-xs">
-													{result.sourceDisplayName}
-												</span>
-											</button>
-										</li>
-									))}
-								</ul>
-							</div>
+						{!!browseMode && (
+							<BrowseSuggestions
+								suggestions={suggestions}
+								suggestionIndex={suggestionIndex}
+								onSelect={handleBrowseSelect}
+								onHover={suggestionActions.setSuggestionIndex}
+							/>
 						)}
 						{!browseMode && hasSuggestions && (
 							<AddModeSuggestions
 								nameInput={nameInput}
-								suggestions={deferredSuggestions}
-								pcMatches={deferredPcMatches}
+								suggestions={suggestions}
+								pcMatches={pcMatches}
 								suggestionIndex={suggestionIndex}
 								queued={queued}
-								onDismiss={dismissSuggestions}
-								onClear={clearInput}
-								onClickSuggestion={handleClickSuggestion}
-								onSetSuggestionIndex={setSuggestionIndex}
-								onSetQueued={setQueued}
-								onConfirmQueued={confirmQueued}
-								onAddFromPlayerCharacter={addFromPlayerCharacter}
+								actions={suggestionActions}
 							/>
 						)}
 					</div>
 				</div>
 				{!browseMode && nameInput.length >= 2 && !hasSuggestions && (
-					<div className="flex items-center gap-2">
-						<Input
-							type="text"
-							inputMode="numeric"
-							value={customInit}
-							onChange={(e) => setCustomInit(e.target.value)}
-							placeholder="Init"
-							className="w-16 text-center"
+					<CustomStatFields
+						customInit={customInit}
+						customAc={customAc}
+						customMaxHp={customMaxHp}
+						onInitChange={setCustomInit}
+						onAcChange={setCustomAc}
+						onMaxHpChange={setCustomMaxHp}
 					/>
-						<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>
 				)}
-				{!!hasCreatureCombatants && (
-					<>
-						<Button
-							type="button"
-							size="icon"
-							variant="ghost"
-							className="text-muted-foreground hover:text-hover-action"
-							onClick={() => handleRollAllInitiative()}
-							onContextMenu={(e) => {
-								e.preventDefault();
-								openRollAllMenu(e.clientX, e.clientY);
-							}}
-							{...rollAllLongPress}
-							disabled={!canRollAllInitiative}
-							title="Roll all initiative"
-							aria-label="Roll all initiative"
-						>
-							<D20Icon className="h-6 w-6" />
-						</Button>
-						{!!rollAllMenuPos && (
-							<RollModeMenu
-								position={rollAllMenuPos}
-								onSelect={(mode) => handleRollAllInitiative(mode)}
-								onClose={() => setRollAllMenuPos(null)}
-							/>
-						)}
-					</>
-				)}
+				<RollAllButton />
 				{overflowItems.length > 0 && <OverflowMenu items={overflowItems} />}
 			</form>
+			<input
+				ref={importFileRef}
+				type="file"
+				accept=".json"
+				className="hidden"
+				onChange={handleImportFile}
+			/>
+			{!!importError && (
+				<Toast
+					message={importError}
+					onDismiss={() => setImportError(null)}
+					autoDismissMs={5000}
+				/>
+			)}
+			<ExportMethodDialog
+				open={showExportMethod}
+				onDownload={handleExportDownload}
+				onCopyToClipboard={handleExportClipboard}
+				onClose={() => setShowExportMethod(false)}
+			/>
+			<ImportMethodDialog
+				open={showImportMethod}
+				onSelectFile={() => importFileRef.current?.click()}
+				onSubmitClipboard={handleImportClipboard}
+				onClose={() => setShowImportMethod(false)}
+			/>
+			<ImportConfirmDialog
+				open={showImportConfirm}
+				onConfirm={handleImportConfirm}
+				onCancel={handleImportCancel}
+			/>
 		</div>
 	);
 }

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

@@ -112,7 +112,7 @@ function EditableName({
 				onClick={startEditing}
 				title="Rename"
 				aria-label="Rename"
-				className="inline-flex shrink-0 items-center rounded p-0.5 text-muted-foreground opacity-0 pointer-coarse:opacity-100 transition-colors transition-opacity hover:bg-hover-neutral-bg hover:text-hover-neutral focus:opacity-100 group-hover:opacity-100"
+				className="inline-flex pointer-coarse:w-auto w-0 shrink-0 items-center overflow-hidden pointer-coarse:overflow-visible rounded p-0.5 text-muted-foreground opacity-0 pointer-coarse:opacity-100 transition-all duration-150 hover:bg-hover-neutral-bg hover:text-hover-neutral focus:w-auto focus:overflow-visible focus:opacity-100 group-hover:w-auto group-hover:overflow-visible group-hover:opacity-100"
 			>
 				<Pencil size={14} />
 			</button>
@@ -157,7 +157,7 @@ function MaxHpDisplay({
 				inputMode="numeric"
 				value={draft}
 				placeholder="Max"
-				className="h-7 w-[7ch] text-center text-sm tabular-nums"
+				className="h-7 w-[7ch] text-center tabular-nums"
 				onChange={(e) => setDraft(e.target.value)}
 				onBlur={commit}
 				onKeyDown={(e) => {
@@ -272,7 +272,7 @@ function AcDisplay({
 				inputMode="numeric"
 				value={draft}
 				placeholder="AC"
-				className="h-7 w-[6ch] text-center text-sm tabular-nums"
+				className="h-7 w-[6ch] text-center tabular-nums"
 				onChange={(e) => setDraft(e.target.value)}
 				onBlur={commit}
 				onKeyDown={(e) => {
@@ -348,7 +348,7 @@ function InitiativeDisplay({
 				value={draft}
 				placeholder="--"
 				className={cn(
-					"h-7 w-full text-center text-sm tabular-nums",
+					"h-7 w-full text-center tabular-nums",
 					dimmed && "opacity-50",
 				)}
 				onChange={(e) => setDraft(e.target.value)}
@@ -520,7 +520,7 @@ export function CombatantRow({
 				isPulsing && "animate-concentration-pulse",
 			)}
 		>
-			<div className="grid grid-cols-[2rem_3rem_auto_1fr_auto_2rem] items-center gap-1.5 py-2 sm:grid-cols-[2rem_3.5rem_auto_1fr_auto_2rem] sm:gap-3">
+			<div className="grid grid-cols-[2rem_3rem_auto_1fr_auto_2rem] items-center gap-1.5 py-3 sm:grid-cols-[2rem_3.5rem_auto_1fr_auto_2rem] sm:gap-3 sm:py-2">
 				{/* Concentration */}
 				<button
 					type="button"

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

@@ -1,63 +1,19 @@
 import {
-	CONDITION_DEFINITIONS,
 	type ConditionId,
 	getConditionDescription,
+	getConditionsForEdition,
 } from "@initiative/domain";
-import type { LucideIcon } from "lucide-react";
-import {
-	ArrowDown,
-	Ban,
-	BatteryLow,
-	Droplet,
-	EarOff,
-	EyeOff,
-	Gem,
-	Ghost,
-	Hand,
-	Heart,
-	Link,
-	Moon,
-	Siren,
-	Sparkles,
-	ZapOff,
-} from "lucide-react";
-import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { useLayoutEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import { useRulesEditionContext } from "../contexts/rules-edition-context.js";
+import { useClickOutside } from "../hooks/use-click-outside.js";
 import { cn } from "../lib/utils";
+import {
+	CONDITION_COLOR_CLASSES,
+	CONDITION_ICON_MAP,
+} from "./condition-styles.js";
 import { Tooltip } from "./ui/tooltip.js";
 
-const ICON_MAP: Record<string, LucideIcon> = {
-	EyeOff,
-	Heart,
-	EarOff,
-	BatteryLow,
-	Siren,
-	Hand,
-	Ban,
-	Ghost,
-	ZapOff,
-	Gem,
-	Droplet,
-	ArrowDown,
-	Link,
-	Sparkles,
-	Moon,
-};
-
-const COLOR_CLASSES: Record<string, string> = {
-	neutral: "text-muted-foreground",
-	pink: "text-pink-400",
-	amber: "text-amber-400",
-	orange: "text-orange-400",
-	gray: "text-gray-400",
-	violet: "text-violet-400",
-	yellow: "text-yellow-400",
-	slate: "text-slate-400",
-	green: "text-green-400",
-	indigo: "text-indigo-400",
-};
-
 interface ConditionPickerProps {
 	anchorRef: React.RefObject<HTMLElement | null>;
 	activeConditions: readonly ConditionId[] | undefined;
@@ -99,17 +55,10 @@ export function ConditionPicker({
 		setPos({ top, left: anchorRect.left, maxHeight });
 	}, [anchorRef]);
 
-	useEffect(() => {
-		function handleClickOutside(e: MouseEvent) {
-			if (ref.current && !ref.current.contains(e.target as Node)) {
-				onClose();
-			}
-		}
-		document.addEventListener("mousedown", handleClickOutside);
-		return () => document.removeEventListener("mousedown", handleClickOutside);
-	}, [onClose]);
+	useClickOutside(ref, onClose);
 
 	const { edition } = useRulesEditionContext();
+	const conditions = getConditionsForEdition(edition);
 	const active = new Set(activeConditions ?? []);
 
 	return createPortal(
@@ -122,11 +71,12 @@ export function ConditionPicker({
 					: { visibility: "hidden" as const }
 			}
 		>
-			{CONDITION_DEFINITIONS.map((def) => {
-				const Icon = ICON_MAP[def.iconName];
+			{conditions.map((def) => {
+				const Icon = CONDITION_ICON_MAP[def.iconName];
 				if (!Icon) return null;
 				const isActive = active.has(def.id);
-				const colorClass = COLOR_CLASSES[def.color] ?? "text-muted-foreground";
+				const colorClass =
+					CONDITION_COLOR_CLASSES[def.color] ?? "text-muted-foreground";
 				return (
 					<Tooltip
 						key={def.id}

apps/web/src/components/condition-styles.ts

@@ -0,0 +1,54 @@
+import type { LucideIcon } from "lucide-react";
+import {
+	ArrowDown,
+	Ban,
+	BatteryLow,
+	Droplet,
+	EarOff,
+	EyeOff,
+	Gem,
+	Ghost,
+	Hand,
+	Heart,
+	Link,
+	Moon,
+	ShieldMinus,
+	Siren,
+	Snail,
+	Sparkles,
+	ZapOff,
+} from "lucide-react";
+
+export const CONDITION_ICON_MAP: Record<string, LucideIcon> = {
+	EyeOff,
+	Heart,
+	EarOff,
+	BatteryLow,
+	Siren,
+	Hand,
+	Ban,
+	Ghost,
+	ZapOff,
+	Gem,
+	Droplet,
+	ArrowDown,
+	Link,
+	ShieldMinus,
+	Snail,
+	Sparkles,
+	Moon,
+};
+
+export const CONDITION_COLOR_CLASSES: Record<string, string> = {
+	neutral: "text-muted-foreground",
+	pink: "text-pink-400",
+	amber: "text-amber-400",
+	orange: "text-orange-400",
+	gray: "text-gray-400",
+	violet: "text-violet-400",
+	yellow: "text-yellow-400",
+	slate: "text-slate-400",
+	green: "text-green-400",
+	indigo: "text-indigo-400",
+	sky: "text-sky-400",
+};

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

@@ -3,60 +3,15 @@ import {
 	type ConditionId,
 	getConditionDescription,
 } from "@initiative/domain";
-import type { LucideIcon } from "lucide-react";
-import {
-	ArrowDown,
-	Ban,
-	BatteryLow,
-	Droplet,
-	EarOff,
-	EyeOff,
-	Gem,
-	Ghost,
-	Hand,
-	Heart,
-	Link,
-	Moon,
-	Plus,
-	Siren,
-	Sparkles,
-	ZapOff,
-} from "lucide-react";
+import { Plus } from "lucide-react";
 import { useRulesEditionContext } from "../contexts/rules-edition-context.js";
 import { cn } from "../lib/utils.js";
+import {
+	CONDITION_COLOR_CLASSES,
+	CONDITION_ICON_MAP,
+} from "./condition-styles.js";
 import { Tooltip } from "./ui/tooltip.js";
 
-const ICON_MAP: Record<string, LucideIcon> = {
-	EyeOff,
-	Heart,
-	EarOff,
-	BatteryLow,
-	Siren,
-	Hand,
-	Ban,
-	Ghost,
-	ZapOff,
-	Gem,
-	Droplet,
-	ArrowDown,
-	Link,
-	Sparkles,
-	Moon,
-};
-
-const COLOR_CLASSES: Record<string, string> = {
-	neutral: "text-muted-foreground",
-	pink: "text-pink-400",
-	amber: "text-amber-400",
-	orange: "text-orange-400",
-	gray: "text-gray-400",
-	violet: "text-violet-400",
-	yellow: "text-yellow-400",
-	slate: "text-slate-400",
-	green: "text-green-400",
-	indigo: "text-indigo-400",
-};
-
 interface ConditionTagsProps {
 	conditions: readonly ConditionId[] | undefined;
 	onRemove: (conditionId: ConditionId) => void;
@@ -74,9 +29,10 @@ export function ConditionTags({
 			{conditions?.map((condId) => {
 				const def = CONDITION_DEFINITIONS.find((d) => d.id === condId);
 				if (!def) return null;
-				const Icon = ICON_MAP[def.iconName];
+				const Icon = CONDITION_ICON_MAP[def.iconName];
 				if (!Icon) return null;
-				const colorClass = COLOR_CLASSES[def.color] ?? "text-muted-foreground";
+				const colorClass =
+					CONDITION_COLOR_CLASSES[def.color] ?? "text-muted-foreground";
 				return (
 					<Tooltip
 						key={condId}
@@ -103,7 +59,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 opacity-0 pointer-coarse:opacity-100 transition-colors transition-opacity hover:bg-hover-neutral-bg hover:text-hover-neutral focus:opacity-100 group-hover:opacity-100"
+				className="inline-flex pointer-coarse:w-auto w-0 items-center overflow-hidden pointer-coarse:overflow-visible rounded p-0.5 text-muted-foreground opacity-0 pointer-coarse:opacity-100 transition-all duration-150 hover:bg-hover-neutral-bg hover:text-hover-neutral focus:w-auto focus:overflow-visible focus:opacity-100 group-hover:w-auto group-hover:overflow-visible group-hover:opacity-100"
 				onClick={(e) => {
 					e.stopPropagation();
 					onOpenPicker();

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

@@ -1,11 +1,19 @@
 import type { PlayerCharacter } from "@initiative/domain";
 import { X } from "lucide-react";
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useState } from "react";
 import { ColorPalette } from "./color-palette";
 import { IconGrid } from "./icon-grid";
 import { Button } from "./ui/button";
+import { Dialog } from "./ui/dialog";
 import { Input } from "./ui/input";
 
+function parseLevel(value: string): number | undefined | "invalid" {
+	if (value.trim() === "") return undefined;
+	const n = Number.parseInt(value, 10);
+	if (Number.isNaN(n) || n < 1 || n > 20) return "invalid";
+	return n;
+}
+
 interface CreatePlayerModalProps {
 	open: boolean;
 	onClose: () => void;
@@ -15,6 +23,7 @@ interface CreatePlayerModalProps {
 		maxHp: number,
 		color: string | undefined,
 		icon: string | undefined,
+		level: number | undefined,
 	) => void;
 	playerCharacter?: PlayerCharacter;
 }
@@ -25,12 +34,12 @@ export function CreatePlayerModal({
 	onSave,
 	playerCharacter,
 }: Readonly<CreatePlayerModalProps>) {
-	const dialogRef = useRef<HTMLDialogElement>(null);
 	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 [level, setLevel] = useState("");
 	const [error, setError] = useState("");
 
 	const isEdit = !!playerCharacter;
@@ -43,45 +52,23 @@ export function CreatePlayerModal({
 				setMaxHp(String(playerCharacter.maxHp));
 				setColor(playerCharacter.color ?? "");
 				setIcon(playerCharacter.icon ?? "");
+				setLevel(
+					playerCharacter.level === undefined
+						? ""
+						: String(playerCharacter.level),
+				);
 			} else {
 				setName("");
 				setAc("10");
 				setMaxHp("10");
 				setColor("");
 				setIcon("");
+				setLevel("");
 			}
 			setError("");
 		}
 	}, [open, playerCharacter]);
 
-	useEffect(() => {
-		const dialog = dialogRef.current;
-		if (!dialog) return;
-		if (open && !dialog.open) {
-			dialog.showModal();
-		} else if (!open && dialog.open) {
-			dialog.close();
-		}
-	}, [open]);
-
-	useEffect(() => {
-		const dialog = dialogRef.current;
-		if (!dialog) return;
-		function handleCancel(e: Event) {
-			e.preventDefault();
-			onClose();
-		}
-		function handleBackdropClick(e: MouseEvent) {
-			if (e.target === dialog) onClose();
-		}
-		dialog.addEventListener("cancel", handleCancel);
-		dialog.addEventListener("mousedown", handleBackdropClick);
-		return () => {
-			dialog.removeEventListener("cancel", handleCancel);
-			dialog.removeEventListener("mousedown", handleBackdropClick);
-		};
-	}, [onClose]);
-
 	const handleSubmit = (e: React.SubmitEvent<HTMLFormElement>) => {
 		e.preventDefault();
 		const trimmed = name.trim();
@@ -99,15 +86,24 @@ export function CreatePlayerModal({
 			setError("Max HP must be at least 1");
 			return;
 		}
-		onSave(trimmed, acNum, hpNum, color || undefined, icon || undefined);
+		const levelNum = parseLevel(level);
+		if (levelNum === "invalid") {
+			setError("Level must be between 1 and 20");
+			return;
+		}
+		onSave(
+			trimmed,
+			acNum,
+			hpNum,
+			color || undefined,
+			icon || undefined,
+			levelNum,
+		);
 		onClose();
 	};
 
 	return (
-		<dialog
-			ref={dialogRef}
-			className="card-glow m-auto w-full max-w-md rounded-lg border border-border bg-card p-6 backdrop:bg-black/50"
-		>
+		<Dialog open={open} onClose={onClose} className="card-glow w-full max-w-md">
 			<div className="mb-4 flex items-center justify-between">
 				<h2 className="font-semibold text-foreground text-lg">
 					{isEdit ? "Edit Player" : "Create Player"}
@@ -166,6 +162,20 @@ export function CreatePlayerModal({
 							className="text-center"
 						/>
 					</div>
+					<div className="flex-1">
+						<span className="mb-1 block text-muted-foreground text-sm">
+							Level
+						</span>
+						<Input
+							type="text"
+							inputMode="numeric"
+							value={level}
+							onChange={(e) => setLevel(e.target.value)}
+							placeholder="1-20"
+							aria-label="Level"
+							className="text-center"
+						/>
+					</div>
 				</div>
 
 				<div>
@@ -187,6 +197,6 @@ export function CreatePlayerModal({
 					<Button type="submit">{isEdit ? "Save" : "Create"}</Button>
 				</div>
 			</form>
-		</dialog>
+		</Dialog>
 	);
 }

apps/web/src/components/difficulty-indicator.tsx

@@ -0,0 +1,39 @@
+import type { DifficultyResult, DifficultyTier } from "@initiative/domain";
+import { cn } from "../lib/utils.js";
+
+const TIER_CONFIG: Record<
+	DifficultyTier,
+	{ filledBars: number; color: string; label: string }
+> = {
+	trivial: { filledBars: 0, color: "", label: "Trivial" },
+	low: { filledBars: 1, color: "bg-green-500", label: "Low" },
+	moderate: { filledBars: 2, color: "bg-yellow-500", label: "Moderate" },
+	high: { filledBars: 3, color: "bg-red-500", label: "High" },
+};
+
+const BAR_HEIGHTS = ["h-2", "h-3", "h-4"] as const;
+
+export function DifficultyIndicator({ result }: { result: DifficultyResult }) {
+	const config = TIER_CONFIG[result.tier];
+	const tooltip = `${config.label} encounter difficulty`;
+
+	return (
+		<div
+			className="flex items-end gap-0.5"
+			title={tooltip}
+			role="img"
+			aria-label={tooltip}
+		>
+			{BAR_HEIGHTS.map((height, i) => (
+				<div
+					key={height}
+					className={cn(
+						"w-1 rounded-sm",
+						height,
+						i < config.filledBars ? config.color : "bg-muted",
+					)}
+				/>
+			))}
+		</div>
+	);
+}

apps/web/src/components/export-method-dialog.tsx

@@ -0,0 +1,93 @@
+import { Check, ClipboardCopy, Download } from "lucide-react";
+import { useCallback, useState } from "react";
+import { Dialog, DialogHeader } from "./ui/dialog.js";
+import { Input } from "./ui/input.js";
+
+interface ExportMethodDialogProps {
+	open: boolean;
+	onDownload: (includeHistory: boolean, filename: string) => void;
+	onCopyToClipboard: (includeHistory: boolean) => void;
+	onClose: () => void;
+}
+
+export function ExportMethodDialog({
+	open,
+	onDownload,
+	onCopyToClipboard,
+	onClose,
+}: Readonly<ExportMethodDialogProps>) {
+	const [includeHistory, setIncludeHistory] = useState(false);
+	const [filename, setFilename] = useState("");
+	const [copied, setCopied] = useState(false);
+
+	const handleClose = useCallback(() => {
+		setIncludeHistory(false);
+		setFilename("");
+		setCopied(false);
+		onClose();
+	}, [onClose]);
+
+	return (
+		<Dialog open={open} onClose={handleClose} className="w-80">
+			<DialogHeader title="Export Encounter" onClose={handleClose} />
+			<div className="mb-3">
+				<Input
+					type="text"
+					value={filename}
+					onChange={(e) => setFilename(e.target.value)}
+					placeholder="Filename (optional)"
+				/>
+			</div>
+			<label className="mb-4 flex items-center gap-2 text-sm">
+				<input
+					type="checkbox"
+					checked={includeHistory}
+					onChange={(e) => setIncludeHistory(e.target.checked)}
+					className="accent-accent"
+				/>
+				<span className="text-foreground">Include undo/redo history</span>
+			</label>
+			<div className="flex flex-col gap-2">
+				<button
+					type="button"
+					className="flex items-center gap-3 rounded-lg border border-border px-4 py-3 text-left text-foreground text-sm hover:bg-hover-neutral-bg"
+					onClick={() => {
+						onDownload(includeHistory, filename);
+						handleClose();
+					}}
+				>
+					<Download className="h-5 w-5 text-muted-foreground" />
+					<div>
+						<div className="font-medium">Download file</div>
+						<div className="text-muted-foreground text-xs">
+							Save as a JSON file
+						</div>
+					</div>
+				</button>
+				<button
+					type="button"
+					className="flex items-center gap-3 rounded-lg border border-border px-4 py-3 text-left text-foreground text-sm hover:bg-hover-neutral-bg"
+					onClick={() => {
+						onCopyToClipboard(includeHistory);
+						setCopied(true);
+						setTimeout(() => setCopied(false), 2000);
+					}}
+				>
+					{copied ? (
+						<Check className="h-5 w-5 text-green-400" />
+					) : (
+						<ClipboardCopy className="h-5 w-5 text-muted-foreground" />
+					)}
+					<div>
+						<div className="font-medium">
+							{copied ? "Copied!" : "Copy to clipboard"}
+						</div>
+						<div className="text-muted-foreground text-xs">
+							Copy JSON to your clipboard
+						</div>
+					</div>
+				</button>
+			</div>
+		</Dialog>
+	);
+}

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

@@ -6,6 +6,7 @@ import {
 	useRef,
 	useState,
 } from "react";
+import { useClickOutside } from "../hooks/use-click-outside.js";
 import { Input } from "./ui/input";
 
 const DIGITS_ONLY_REGEX = /^\d+$/;
@@ -48,15 +49,7 @@ export function HpAdjustPopover({
 		requestAnimationFrame(() => inputRef.current?.focus());
 	}, []);
 
-	useEffect(() => {
-		function handleClickOutside(e: MouseEvent) {
-			if (ref.current && !ref.current.contains(e.target as Node)) {
-				onClose();
-			}
-		}
-		document.addEventListener("mousedown", handleClickOutside);
-		return () => document.removeEventListener("mousedown", handleClickOutside);
-	}, [onClose]);
+	useClickOutside(ref, onClose);
 
 	const parsedValue =
 		inputValue === "" ? null : Number.parseInt(inputValue, 10);
@@ -106,7 +99,7 @@ export function HpAdjustPopover({
 					inputMode="numeric"
 					value={inputValue}
 					placeholder="HP"
-					className="h-7 w-[7ch] text-center text-sm tabular-nums"
+					className="h-7 w-[7ch] text-center tabular-nums"
 					onChange={(e) => {
 						const v = e.target.value;
 						if (v === "" || DIGITS_ONLY_REGEX.test(v)) {

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

@@ -0,0 +1,32 @@
+import { Button } from "./ui/button.js";
+import { Dialog } from "./ui/dialog.js";
+
+interface ImportConfirmDialogProps {
+	open: boolean;
+	onConfirm: () => void;
+	onCancel: () => void;
+}
+
+export function ImportConfirmDialog({
+	open,
+	onConfirm,
+	onCancel,
+}: Readonly<ImportConfirmDialogProps>) {
+	return (
+		<Dialog open={open} onClose={onCancel}>
+			<h2 className="mb-2 font-semibold text-lg">Replace current encounter?</h2>
+			<p className="mb-4 text-muted-foreground text-sm">
+				Importing will replace your current encounter, undo/redo history, and
+				player characters. This cannot be undone.
+			</p>
+			<div className="flex justify-end gap-2">
+				<Button type="button" variant="ghost" onClick={onCancel}>
+					Cancel
+				</Button>
+				<Button type="button" onClick={onConfirm}>
+					Import
+				</Button>
+			</div>
+		</Dialog>
+	);
+}

apps/web/src/components/import-method-dialog.tsx

@@ -0,0 +1,114 @@
+import { ClipboardPaste, FileUp } from "lucide-react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Button } from "./ui/button.js";
+import { Dialog, DialogHeader } from "./ui/dialog.js";
+
+interface ImportMethodDialogProps {
+	open: boolean;
+	onSelectFile: () => void;
+	onSubmitClipboard: (text: string) => void;
+	onClose: () => void;
+}
+
+export function ImportMethodDialog({
+	open,
+	onSelectFile,
+	onSubmitClipboard,
+	onClose,
+}: Readonly<ImportMethodDialogProps>) {
+	const textareaRef = useRef<HTMLTextAreaElement>(null);
+	const [mode, setMode] = useState<"pick" | "paste">("pick");
+	const [pasteText, setPasteText] = useState("");
+
+	const handleClose = useCallback(() => {
+		setMode("pick");
+		setPasteText("");
+		onClose();
+	}, [onClose]);
+
+	useEffect(() => {
+		if (!open) {
+			setMode("pick");
+			setPasteText("");
+		}
+	}, [open]);
+
+	useEffect(() => {
+		if (mode === "paste") {
+			textareaRef.current?.focus();
+		}
+	}, [mode]);
+
+	return (
+		<Dialog open={open} onClose={handleClose} className="w-80">
+			<DialogHeader title="Import Encounter" onClose={handleClose} />
+			{mode === "pick" && (
+				<div className="flex flex-col gap-2">
+					<button
+						type="button"
+						className="flex items-center gap-3 rounded-lg border border-border px-4 py-3 text-left text-foreground text-sm hover:bg-hover-neutral-bg"
+						onClick={() => {
+							handleClose();
+							onSelectFile();
+						}}
+					>
+						<FileUp className="h-5 w-5 text-muted-foreground" />
+						<div>
+							<div className="font-medium">From file</div>
+							<div className="text-muted-foreground text-xs">
+								Upload a JSON file
+							</div>
+						</div>
+					</button>
+					<button
+						type="button"
+						className="flex items-center gap-3 rounded-lg border border-border px-4 py-3 text-left text-foreground text-sm hover:bg-hover-neutral-bg"
+						onClick={() => setMode("paste")}
+					>
+						<ClipboardPaste className="h-5 w-5 text-muted-foreground" />
+						<div>
+							<div className="font-medium">Paste content</div>
+							<div className="text-muted-foreground text-xs">
+								Paste JSON content directly
+							</div>
+						</div>
+					</button>
+				</div>
+			)}
+			{mode === "paste" && (
+				<div className="flex flex-col gap-3">
+					<textarea
+						ref={textareaRef}
+						value={pasteText}
+						onChange={(e) => setPasteText(e.target.value)}
+						placeholder="Paste exported JSON here..."
+						className="h-32 w-full resize-none rounded-md border border-border bg-background px-3 py-2 font-mono text-foreground text-xs placeholder:text-muted-foreground focus:border-accent focus:outline-none"
+					/>
+					<div className="flex justify-end gap-2">
+						<Button
+							type="button"
+							variant="ghost"
+							onClick={() => {
+								setMode("pick");
+								setPasteText("");
+							}}
+						>
+							Back
+						</Button>
+						<Button
+							type="button"
+							disabled={pasteText.trim().length === 0}
+							onClick={() => {
+								const text = pasteText;
+								handleClose();
+								onSubmitClipboard(text);
+							}}
+						>
+							Import
+						</Button>
+					</div>
+				</div>
+			)}
+		</Dialog>
+	);
+}

apps/web/src/components/player-character-section.tsx

@@ -35,7 +35,7 @@ export const PlayerCharacterSection = function PlayerCharacterSectionInner({
 					setEditingPlayer(undefined);
 					setManagementOpen(true);
 				}}
-				onSave={(name, ac, maxHp, color, icon) => {
+				onSave={(name, ac, maxHp, color, icon, level) => {
 					if (editingPlayer) {
 						editCharacter(editingPlayer.id, {
 							name,
@@ -43,9 +43,10 @@ export const PlayerCharacterSection = function PlayerCharacterSectionInner({
 							maxHp,
 							color: color ?? null,
 							icon: icon ?? null,
+							level: level ?? null,
 						});
 					} else {
-						createCharacter(name, ac, maxHp, color, icon);
+						createCharacter(name, ac, maxHp, color, icon, level);
 					}
 				}}
 				playerCharacter={editingPlayer}

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

@@ -1,9 +1,9 @@
 import type { PlayerCharacter, PlayerCharacterId } from "@initiative/domain";
-import { Pencil, Plus, Trash2, X } from "lucide-react";
-import { useEffect, useRef } from "react";
+import { Pencil, Plus, Trash2 } from "lucide-react";
 import { PLAYER_COLOR_HEX, PLAYER_ICON_MAP } from "./player-icon-map";
 import { Button } from "./ui/button";
 import { ConfirmButton } from "./ui/confirm-button";
+import { Dialog, DialogHeader } from "./ui/dialog";
 
 interface PlayerManagementProps {
 	open: boolean;
@@ -22,54 +22,9 @@ export function PlayerManagement({
 	onDelete,
 	onCreate,
 }: Readonly<PlayerManagementProps>) {
-	const dialogRef = useRef<HTMLDialogElement>(null);
-
-	useEffect(() => {
-		const dialog = dialogRef.current;
-		if (!dialog) return;
-		if (open && !dialog.open) {
-			dialog.showModal();
-		} else if (!open && dialog.open) {
-			dialog.close();
-		}
-	}, [open]);
-
-	useEffect(() => {
-		const dialog = dialogRef.current;
-		if (!dialog) return;
-		function handleCancel(e: Event) {
-			e.preventDefault();
-			onClose();
-		}
-		function handleBackdropClick(e: MouseEvent) {
-			if (e.target === dialog) onClose();
-		}
-		dialog.addEventListener("cancel", handleCancel);
-		dialog.addEventListener("mousedown", handleBackdropClick);
-		return () => {
-			dialog.removeEventListener("cancel", handleCancel);
-			dialog.removeEventListener("mousedown", handleBackdropClick);
-		};
-	}, [onClose]);
-
 	return (
-		<dialog
-			ref={dialogRef}
-			className="card-glow m-auto w-full max-w-md rounded-lg border border-border bg-card p-6 backdrop:bg-black/50"
-		>
-			<div className="mb-4 flex items-center justify-between">
-				<h2 className="font-semibold text-foreground text-lg">
-					Player Characters
-				</h2>
-				<Button
-					variant="ghost"
-					size="icon"
-					onClick={onClose}
-					className="text-muted-foreground"
-				>
-					<X size={20} />
-				</Button>
-			</div>
+		<Dialog open={open} onClose={onClose} className="card-glow w-full max-w-md">
+			<DialogHeader title="Player Characters" onClose={onClose} />
 
 			{characters.length === 0 ? (
 				<div className="flex flex-col items-center gap-3 py-8 text-center">
@@ -101,6 +56,11 @@ export function PlayerManagement({
 								<span className="text-muted-foreground text-xs tabular-nums">
 									HP {pc.maxHp}
 								</span>
+								{pc.level !== undefined && (
+									<span className="text-muted-foreground text-xs tabular-nums">
+										Lv {pc.level}
+									</span>
+								)}
 								<Button
 									variant="ghost"
 									size="icon-sm"
@@ -128,6 +88,6 @@ export function PlayerManagement({
 					</div>
 				</div>
 			)}
-		</dialog>
+		</Dialog>
 	);
 }

apps/web/src/components/roll-mode-menu.tsx

@@ -1,6 +1,7 @@
 import type { RollMode } from "@initiative/domain";
 import { ChevronsDown, ChevronsUp } from "lucide-react";
-import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { useLayoutEffect, useRef, useState } from "react";
+import { useClickOutside } from "../hooks/use-click-outside.js";
 
 interface RollModeMenuProps {
 	readonly position: { x: number; y: number };
@@ -34,22 +35,7 @@ export function RollModeMenu({
 		setPos({ top, left });
 	}, [position.x, position.y]);
 
-	useEffect(() => {
-		function handleMouseDown(e: MouseEvent) {
-			if (ref.current && !ref.current.contains(e.target as Node)) {
-				onClose();
-			}
-		}
-		function handleKeyDown(e: KeyboardEvent) {
-			if (e.key === "Escape") onClose();
-		}
-		document.addEventListener("mousedown", handleMouseDown);
-		document.addEventListener("keydown", handleKeyDown);
-		return () => {
-			document.removeEventListener("mousedown", handleMouseDown);
-			document.removeEventListener("keydown", handleKeyDown);
-		};
-	}, [onClose]);
+	useClickOutside(ref, onClose);
 
 	return (
 		<div

apps/web/src/components/settings-modal.tsx

@@ -1,10 +1,9 @@
 import type { RulesEdition } from "@initiative/domain";
-import { Monitor, Moon, Sun, X } from "lucide-react";
-import { useEffect, useRef } from "react";
+import { Monitor, Moon, Sun } from "lucide-react";
 import { useRulesEditionContext } from "../contexts/rules-edition-context.js";
 import { useThemeContext } from "../contexts/theme-context.js";
 import { cn } from "../lib/utils.js";
-import { Button } from "./ui/button.js";
+import { Dialog, DialogHeader } from "./ui/dialog.js";
 
 interface SettingsModalProps {
 	open: boolean;
@@ -27,51 +26,12 @@ const THEME_OPTIONS: {
 ];
 
 export function SettingsModal({ open, onClose }: Readonly<SettingsModalProps>) {
-	const dialogRef = useRef<HTMLDialogElement>(null);
 	const { edition, setEdition } = useRulesEditionContext();
 	const { preference, setPreference } = useThemeContext();
 
-	useEffect(() => {
-		const dialog = dialogRef.current;
-		if (!dialog) return;
-		if (open && !dialog.open) dialog.showModal();
-		else if (!open && dialog.open) dialog.close();
-	}, [open]);
-
-	useEffect(() => {
-		const dialog = dialogRef.current;
-		if (!dialog) return;
-		function handleCancel(e: Event) {
-			e.preventDefault();
-			onClose();
-		}
-		function handleBackdropClick(e: MouseEvent) {
-			if (e.target === dialog) onClose();
-		}
-		dialog.addEventListener("cancel", handleCancel);
-		dialog.addEventListener("mousedown", handleBackdropClick);
-		return () => {
-			dialog.removeEventListener("cancel", handleCancel);
-			dialog.removeEventListener("mousedown", handleBackdropClick);
-		};
-	}, [onClose]);
-
 	return (
-		<dialog
-			ref={dialogRef}
-			className="card-glow m-auto w-full max-w-sm rounded-lg border border-border bg-card p-6 backdrop:bg-black/50"
-		>
-			<div className="mb-4 flex items-center justify-between">
-				<h2 className="font-semibold text-foreground text-lg">Settings</h2>
-				<Button
-					variant="ghost"
-					size="icon"
-					onClick={onClose}
-					className="text-muted-foreground"
-				>
-					<X size={20} />
-				</Button>
-			</div>
+		<Dialog open={open} onClose={onClose} className="card-glow w-full max-w-sm">
+			<DialogHeader title="Settings" onClose={onClose} />
 
 			<div className="flex flex-col gap-5">
 				<div>
@@ -124,6 +84,6 @@ export function SettingsModal({ open, onClose }: Readonly<SettingsModalProps>) {
 					</div>
 				</div>
 			</div>
-		</dialog>
+		</Dialog>
 	);
 }

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

@@ -34,6 +34,31 @@ function SectionDivider() {
 	);
 }
 
+function TraitSection({
+	entries,
+	heading,
+}: Readonly<{
+	entries: readonly { name: string; text: string }[] | undefined;
+	heading?: string;
+}>) {
+	if (!entries || entries.length === 0) return null;
+	return (
+		<>
+			<SectionDivider />
+			{heading ? (
+				<h3 className="font-bold text-base text-stat-heading">{heading}</h3>
+			) : null}
+			<div className="space-y-2">
+				{entries.map((e) => (
+					<div key={e.name} className="text-sm">
+						<span className="font-semibold italic">{e.name}.</span> {e.text}
+					</div>
+				))}
+			</div>
+		</>
+	);
+}
+
 export function StatBlock({ creature }: Readonly<StatBlockProps>) {
 	const abilities = [
 		{ label: "STR", score: creature.abilities.str },
@@ -134,19 +159,7 @@ export function StatBlock({ creature }: Readonly<StatBlockProps>) {
 				</div>
 			</div>
 
-			{/* Traits */}
-			{creature.traits && creature.traits.length > 0 && (
-				<>
-					<SectionDivider />
-					<div className="space-y-2">
-						{creature.traits.map((t) => (
-							<div key={t.name} className="text-sm">
-								<span className="font-semibold italic">{t.name}.</span> {t.text}
-							</div>
-						))}
-					</div>
-				</>
-			)}
+			<TraitSection entries={creature.traits} />
 
 			{/* Spellcasting */}
 			{creature.spellcasting && creature.spellcasting.length > 0 && (
@@ -190,52 +203,9 @@ export function StatBlock({ creature }: Readonly<StatBlockProps>) {
 				</>
 			)}
 
-			{/* Actions */}
-			{creature.actions && creature.actions.length > 0 && (
-				<>
-					<SectionDivider />
-					<h3 className="font-bold text-base text-stat-heading">Actions</h3>
-					<div className="space-y-2">
-						{creature.actions.map((a) => (
-							<div key={a.name} className="text-sm">
-								<span className="font-semibold italic">{a.name}.</span> {a.text}
-							</div>
-						))}
-					</div>
-				</>
-			)}
-
-			{/* Bonus Actions */}
-			{creature.bonusActions && creature.bonusActions.length > 0 && (
-				<>
-					<SectionDivider />
-					<h3 className="font-bold text-base text-stat-heading">
-						Bonus Actions
-					</h3>
-					<div className="space-y-2">
-						{creature.bonusActions.map((a) => (
-							<div key={a.name} className="text-sm">
-								<span className="font-semibold italic">{a.name}.</span> {a.text}
-							</div>
-						))}
-					</div>
-				</>
-			)}
-
-			{/* Reactions */}
-			{creature.reactions && creature.reactions.length > 0 && (
-				<>
-					<SectionDivider />
-					<h3 className="font-bold text-base text-stat-heading">Reactions</h3>
-					<div className="space-y-2">
-						{creature.reactions.map((a) => (
-							<div key={a.name} className="text-sm">
-								<span className="font-semibold italic">{a.name}.</span> {a.text}
-							</div>
-						))}
-					</div>
-				</>
-			)}
+			<TraitSection entries={creature.actions} heading="Actions" />
+			<TraitSection entries={creature.bonusActions} heading="Bonus Actions" />
+			<TraitSection entries={creature.reactions} heading="Reactions" />
 
 			{/* Legendary Actions */}
 			{!!creature.legendaryActions && (

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

@@ -1,12 +1,23 @@
-import { StepBack, StepForward, Trash2 } from "lucide-react";
+import { Redo2, StepBack, StepForward, Trash2, Undo2 } from "lucide-react";
 import { useEncounterContext } from "../contexts/encounter-context.js";
+import { useDifficulty } from "../hooks/use-difficulty.js";
+import { DifficultyIndicator } from "./difficulty-indicator.js";
 import { Button } from "./ui/button.js";
 import { ConfirmButton } from "./ui/confirm-button.js";
 
 export function TurnNavigation() {
-	const { encounter, advanceTurn, retreatTurn, clearEncounter } =
-		useEncounterContext();
+	const {
+		encounter,
+		advanceTurn,
+		retreatTurn,
+		clearEncounter,
+		undo,
+		redo,
+		canUndo,
+		canRedo,
+	} = useEncounterContext();
 
+	const difficulty = useDifficulty();
 	const hasCombatants = encounter.combatants.length > 0;
 	const isAtStart = encounter.roundNumber === 1 && encounter.activeIndex === 0;
 	const activeCombatant = encounter.combatants[encounter.activeIndex];
@@ -24,6 +35,29 @@ export function TurnNavigation() {
 				<StepBack className="h-5 w-5" />
 			</Button>
 
+			<div className="flex items-center gap-1">
+				<Button
+					variant="ghost"
+					size="icon"
+					onClick={undo}
+					disabled={!canUndo}
+					title="Undo"
+					aria-label="Undo"
+				>
+					<Undo2 className="h-4 w-4" />
+				</Button>
+				<Button
+					variant="ghost"
+					size="icon"
+					onClick={redo}
+					disabled={!canRedo}
+					title="Redo"
+					aria-label="Redo"
+				>
+					<Redo2 className="h-4 w-4" />
+				</Button>
+			</div>
+
 			<div className="flex min-w-0 flex-1 items-center justify-center gap-2 text-sm">
 				<span className="shrink-0 rounded-md bg-muted px-2 py-0.5 font-semibold text-foreground text-sm">
 					<span className="-mt-[3px] inline-block">
@@ -35,6 +69,7 @@ export function TurnNavigation() {
 				) : (
 					<span className="text-muted-foreground">No combatants</span>
 				)}
+				{difficulty && <DifficultyIndicator result={difficulty} />}
 			</div>
 
 			<div className="flex flex-shrink-0 items-center gap-3">

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

@@ -6,6 +6,7 @@ import {
 	useRef,
 	useState,
 } from "react";
+import { useClickOutside } from "../../hooks/use-click-outside.js";
 import { cn } from "../../lib/utils";
 import { Button } from "./button";
 
@@ -42,32 +43,7 @@ export function ConfirmButton({
 		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 handleEscapeKey(e: KeyboardEvent) {
-			if (e.key === "Escape") {
-				revert();
-			}
-		}
-
-		document.addEventListener("mousedown", handleMouseDown);
-		document.addEventListener("keydown", handleEscapeKey);
-		return () => {
-			document.removeEventListener("mousedown", handleMouseDown);
-			document.removeEventListener("keydown", handleEscapeKey);
-		};
-	}, [isConfirming, revert]);
+	useClickOutside(wrapperRef, revert, isConfirming);
 
 	const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
 		if (e.key === "Enter" || e.key === " ") {

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

@@ -0,0 +1,71 @@
+import { X } from "lucide-react";
+import { type ReactNode, useEffect, useRef } from "react";
+import { cn } from "../../lib/utils.js";
+import { Button } from "./button.js";
+
+interface DialogProps {
+	open: boolean;
+	onClose: () => void;
+	className?: string;
+	children: ReactNode;
+}
+
+export function Dialog({ open, onClose, className, children }: DialogProps) {
+	const dialogRef = useRef<HTMLDialogElement>(null);
+
+	useEffect(() => {
+		const dialog = dialogRef.current;
+		if (!dialog) return;
+		if (open && !dialog.open) dialog.showModal();
+		else if (!open && dialog.open) dialog.close();
+	}, [open]);
+
+	useEffect(() => {
+		const dialog = dialogRef.current;
+		if (!dialog) return;
+		function handleCancel(e: Event) {
+			e.preventDefault();
+			onClose();
+		}
+		function handleBackdropClick(e: MouseEvent) {
+			if (e.target === dialog) onClose();
+		}
+		dialog.addEventListener("cancel", handleCancel);
+		dialog.addEventListener("mousedown", handleBackdropClick);
+		return () => {
+			dialog.removeEventListener("cancel", handleCancel);
+			dialog.removeEventListener("mousedown", handleBackdropClick);
+		};
+	}, [onClose]);
+
+	return (
+		<dialog
+			ref={dialogRef}
+			className={cn(
+				"m-auto rounded-lg border border-border bg-card text-foreground shadow-xl backdrop:bg-black/50",
+				className,
+			)}
+		>
+			<div className="p-6">{children}</div>
+		</dialog>
+	);
+}
+
+export function DialogHeader({
+	title,
+	onClose,
+}: Readonly<{ title: string; onClose: () => void }>) {
+	return (
+		<div className="mb-4 flex items-center justify-between">
+			<h2 className="font-semibold text-foreground text-lg">{title}</h2>
+			<Button
+				variant="ghost"
+				size="icon-sm"
+				onClick={onClose}
+				className="text-muted-foreground"
+			>
+				<X className="h-4 w-4" />
+			</Button>
+		</div>
+	);
+}

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

@@ -12,7 +12,7 @@ export const Input = ({
 		<input
 			ref={ref}
 			className={cn(
-				"flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-foreground text-sm shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-primary disabled:cursor-not-allowed disabled:opacity-50",
+				"flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-base text-foreground shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-primary disabled:cursor-not-allowed disabled:opacity-50 sm:text-sm",
 				className,
 			)}
 			{...props}

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

@@ -1,5 +1,6 @@
 import { EllipsisVertical } from "lucide-react";
-import { type ReactNode, useEffect, useRef, useState } from "react";
+import { type ReactNode, useRef, useState } from "react";
+import { useClickOutside } from "../../hooks/use-click-outside.js";
 import { Button } from "./button";
 
 export interface OverflowMenuItem {
@@ -18,23 +19,7 @@ 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]);
+	useClickOutside(ref, () => setOpen(false), open);
 
 	return (
 		<div ref={ref} className="relative">

apps/web/src/contexts/encounter-context.tsx

@@ -1,5 +1,6 @@
 import { createContext, type ReactNode, useContext } from "react";
 import { useEncounter } from "../hooks/use-encounter.js";
+import { useUndoRedoShortcuts } from "../hooks/use-undo-redo-shortcuts.js";
 
 type EncounterContextValue = ReturnType<typeof useEncounter>;
 
@@ -7,6 +8,7 @@ const EncounterContext = createContext<EncounterContextValue | null>(null);
 
 export function EncounterProvider({ children }: { children: ReactNode }) {
 	const value = useEncounter();
+	useUndoRedoShortcuts(value.undo, value.redo, value.canUndo, value.canRedo);
 	return (
 		<EncounterContext.Provider value={value}>
 			{children}

apps/web/src/hooks/__tests__/encounter-reducer.test.ts

@@ -0,0 +1,416 @@
+import type {
+	BestiaryIndexEntry,
+	ConditionId,
+	PlayerCharacter,
+} from "@initiative/domain";
+import {
+	combatantId,
+	createEncounter,
+	EMPTY_UNDO_REDO_STATE,
+	isDomainError,
+	playerCharacterId,
+} from "@initiative/domain";
+import { describe, expect, it, vi } from "vitest";
+import { type EncounterState, encounterReducer } from "../use-encounter.js";
+
+vi.mock("../../persistence/encounter-storage.js", () => ({
+	loadEncounter: vi.fn().mockReturnValue(null),
+	saveEncounter: vi.fn(),
+}));
+
+vi.mock("../../persistence/undo-redo-storage.js", () => ({
+	loadUndoRedoStacks: vi.fn().mockReturnValue(EMPTY_UNDO_REDO_STATE),
+	saveUndoRedoStacks: vi.fn(),
+}));
+
+function emptyState(): EncounterState {
+	return {
+		encounter: {
+			combatants: [],
+			activeIndex: 0,
+			roundNumber: 1,
+		},
+		undoRedoState: EMPTY_UNDO_REDO_STATE,
+		events: [],
+		nextId: 0,
+		lastCreatureId: null,
+	};
+}
+
+function stateWith(...names: string[]): EncounterState {
+	let state = emptyState();
+	for (const name of names) {
+		state = encounterReducer(state, { type: "add-combatant", name });
+	}
+	return state;
+}
+
+function stateWithHp(name: string, maxHp: number): EncounterState {
+	const state = stateWith(name);
+	const id = state.encounter.combatants[0].id;
+	return encounterReducer(state, {
+		type: "set-hp",
+		id,
+		maxHp,
+	});
+}
+
+const BESTIARY_ENTRY: BestiaryIndexEntry = {
+	name: "Goblin",
+	source: "MM",
+	ac: 15,
+	hp: 7,
+	dex: 14,
+	cr: "1/4",
+	initiativeProficiency: 0,
+	size: "Small",
+	type: "humanoid",
+};
+
+describe("encounterReducer", () => {
+	describe("add-combatant", () => {
+		it("adds a combatant and pushes undo", () => {
+			const next = encounterReducer(emptyState(), {
+				type: "add-combatant",
+				name: "Goblin",
+			});
+
+			expect(next.encounter.combatants).toHaveLength(1);
+			expect(next.encounter.combatants[0].name).toBe("Goblin");
+			expect(next.undoRedoState.undoStack).toHaveLength(1);
+			expect(next.nextId).toBe(1);
+		});
+
+		it("applies optional init values", () => {
+			const next = encounterReducer(emptyState(), {
+				type: "add-combatant",
+				name: "Goblin",
+				init: { initiative: 15, ac: 13, maxHp: 7 },
+			});
+
+			const c = next.encounter.combatants[0];
+			expect(c.initiative).toBe(15);
+			expect(c.ac).toBe(13);
+			expect(c.maxHp).toBe(7);
+			expect(c.currentHp).toBe(7);
+		});
+
+		it("increments IDs", () => {
+			const s1 = encounterReducer(emptyState(), {
+				type: "add-combatant",
+				name: "A",
+			});
+			const s2 = encounterReducer(s1, {
+				type: "add-combatant",
+				name: "B",
+			});
+
+			expect(s2.encounter.combatants[0].id).toBe("c-1");
+			expect(s2.encounter.combatants[1].id).toBe("c-2");
+		});
+
+		it("returns unchanged state for invalid name", () => {
+			const state = emptyState();
+			const next = encounterReducer(state, {
+				type: "add-combatant",
+				name: "",
+			});
+
+			expect(next).toBe(state);
+		});
+	});
+
+	describe("remove-combatant", () => {
+		it("removes combatant and pushes undo", () => {
+			const state = stateWith("Goblin");
+			const id = state.encounter.combatants[0].id;
+			const next = encounterReducer(state, {
+				type: "remove-combatant",
+				id,
+			});
+
+			expect(next.encounter.combatants).toHaveLength(0);
+			expect(next.undoRedoState.undoStack).toHaveLength(2);
+		});
+	});
+
+	describe("edit-combatant", () => {
+		it("renames combatant", () => {
+			const state = stateWith("Goblin");
+			const id = state.encounter.combatants[0].id;
+			const next = encounterReducer(state, {
+				type: "edit-combatant",
+				id,
+				newName: "Hobgoblin",
+			});
+
+			expect(next.encounter.combatants[0].name).toBe("Hobgoblin");
+		});
+	});
+
+	describe("advance-turn / retreat-turn", () => {
+		it("advances and retreats turn", () => {
+			const state = stateWith("A", "B");
+			const advanced = encounterReducer(state, {
+				type: "advance-turn",
+			});
+			expect(advanced.encounter.activeIndex).toBe(1);
+
+			const retreated = encounterReducer(advanced, {
+				type: "retreat-turn",
+			});
+			expect(retreated.encounter.activeIndex).toBe(0);
+		});
+
+		it("returns unchanged state on empty encounter", () => {
+			const state = emptyState();
+			const next = encounterReducer(state, { type: "advance-turn" });
+			expect(next).toBe(state);
+		});
+	});
+
+	describe("set-hp / adjust-hp / set-temp-hp", () => {
+		it("sets max HP", () => {
+			const state = stateWith("Goblin");
+			const id = state.encounter.combatants[0].id;
+			const next = encounterReducer(state, {
+				type: "set-hp",
+				id,
+				maxHp: 20,
+			});
+
+			expect(next.encounter.combatants[0].maxHp).toBe(20);
+			expect(next.encounter.combatants[0].currentHp).toBe(20);
+		});
+
+		it("adjusts HP", () => {
+			const state = stateWithHp("Goblin", 20);
+			const id = state.encounter.combatants[0].id;
+			const next = encounterReducer(state, {
+				type: "adjust-hp",
+				id,
+				delta: -5,
+			});
+
+			expect(next.encounter.combatants[0].currentHp).toBe(15);
+		});
+
+		it("sets temp HP", () => {
+			const state = stateWithHp("Goblin", 20);
+			const id = state.encounter.combatants[0].id;
+			const next = encounterReducer(state, {
+				type: "set-temp-hp",
+				id,
+				tempHp: 5,
+			});
+
+			expect(next.encounter.combatants[0].tempHp).toBe(5);
+		});
+	});
+
+	describe("set-ac", () => {
+		it("sets AC", () => {
+			const state = stateWith("Goblin");
+			const id = state.encounter.combatants[0].id;
+			const next = encounterReducer(state, {
+				type: "set-ac",
+				id,
+				value: 15,
+			});
+
+			expect(next.encounter.combatants[0].ac).toBe(15);
+		});
+	});
+
+	describe("set-initiative", () => {
+		it("sets initiative", () => {
+			const state = stateWith("Goblin");
+			const id = state.encounter.combatants[0].id;
+			const next = encounterReducer(state, {
+				type: "set-initiative",
+				id,
+				value: 18,
+			});
+
+			expect(next.encounter.combatants[0].initiative).toBe(18);
+		});
+	});
+
+	describe("toggle-condition / toggle-concentration", () => {
+		it("toggles condition", () => {
+			const state = stateWith("Goblin");
+			const id = state.encounter.combatants[0].id;
+			const next = encounterReducer(state, {
+				type: "toggle-condition",
+				id,
+				conditionId: "blinded" as ConditionId,
+			});
+
+			expect(next.encounter.combatants[0].conditions).toContain("blinded");
+		});
+
+		it("toggles concentration", () => {
+			const state = stateWith("Wizard");
+			const id = state.encounter.combatants[0].id;
+			const next = encounterReducer(state, {
+				type: "toggle-concentration",
+				id,
+			});
+
+			expect(next.encounter.combatants[0].isConcentrating).toBe(true);
+		});
+	});
+
+	describe("clear-encounter", () => {
+		it("clears combatants, resets history and nextId", () => {
+			const state = stateWith("A", "B");
+			const next = encounterReducer(state, {
+				type: "clear-encounter",
+			});
+
+			expect(next.encounter.combatants).toHaveLength(0);
+			expect(next.undoRedoState.undoStack).toHaveLength(0);
+			expect(next.undoRedoState.redoStack).toHaveLength(0);
+			expect(next.nextId).toBe(0);
+		});
+	});
+
+	describe("undo / redo", () => {
+		it("undo restores previous state", () => {
+			const state = stateWith("Goblin");
+			const next = encounterReducer(state, { type: "undo" });
+
+			expect(next.encounter.combatants).toHaveLength(0);
+			expect(next.undoRedoState.undoStack).toHaveLength(0);
+			expect(next.undoRedoState.redoStack).toHaveLength(1);
+		});
+
+		it("redo restores undone state", () => {
+			const state = stateWith("Goblin");
+			const undone = encounterReducer(state, { type: "undo" });
+			const redone = encounterReducer(undone, { type: "redo" });
+
+			expect(redone.encounter.combatants).toHaveLength(1);
+			expect(redone.encounter.combatants[0].name).toBe("Goblin");
+		});
+
+		it("undo returns unchanged state when stack is empty", () => {
+			const state = emptyState();
+			const next = encounterReducer(state, { type: "undo" });
+			expect(next).toBe(state);
+		});
+
+		it("redo returns unchanged state when stack is empty", () => {
+			const state = emptyState();
+			const next = encounterReducer(state, { type: "redo" });
+			expect(next).toBe(state);
+		});
+	});
+
+	describe("add-from-bestiary", () => {
+		it("adds creature with HP, AC, and creatureId", () => {
+			const next = encounterReducer(emptyState(), {
+				type: "add-from-bestiary",
+				entry: BESTIARY_ENTRY,
+			});
+
+			const c = next.encounter.combatants[0];
+			expect(c.name).toBe("Goblin");
+			expect(c.maxHp).toBe(7);
+			expect(c.ac).toBe(15);
+			expect(c.creatureId).toBe("mm:goblin");
+			expect(next.lastCreatureId).toBe("mm:goblin");
+			expect(next.undoRedoState.undoStack).toHaveLength(1);
+		});
+
+		it("auto-numbers duplicate names", () => {
+			const s1 = encounterReducer(emptyState(), {
+				type: "add-from-bestiary",
+				entry: BESTIARY_ENTRY,
+			});
+			const s2 = encounterReducer(s1, {
+				type: "add-from-bestiary",
+				entry: BESTIARY_ENTRY,
+			});
+
+			const names = s2.encounter.combatants.map((c) => c.name);
+			expect(names).toContain("Goblin 1");
+			expect(names).toContain("Goblin 2");
+		});
+	});
+
+	describe("add-multiple-from-bestiary", () => {
+		it("adds multiple creatures in one action", () => {
+			const next = encounterReducer(emptyState(), {
+				type: "add-multiple-from-bestiary",
+				entry: BESTIARY_ENTRY,
+				count: 3,
+			});
+
+			expect(next.encounter.combatants).toHaveLength(3);
+			expect(next.undoRedoState.undoStack).toHaveLength(1);
+			expect(next.lastCreatureId).toBe("mm:goblin");
+		});
+	});
+
+	describe("add-from-player-character", () => {
+		it("adds combatant with PC attributes", () => {
+			const pc: PlayerCharacter = {
+				id: playerCharacterId("pc-1"),
+				name: "Aria",
+				ac: 16,
+				maxHp: 30,
+				color: "blue",
+				icon: "sword",
+			};
+			const next = encounterReducer(emptyState(), {
+				type: "add-from-player-character",
+				pc,
+			});
+
+			const c = next.encounter.combatants[0];
+			expect(c.name).toBe("Aria");
+			expect(c.maxHp).toBe(30);
+			expect(c.ac).toBe(16);
+			expect(c.color).toBe("blue");
+			expect(c.icon).toBe("sword");
+			expect(c.playerCharacterId).toBe("pc-1");
+			expect(next.lastCreatureId).toBeNull();
+		});
+	});
+
+	describe("import", () => {
+		it("replaces encounter and undo/redo state", () => {
+			const state = stateWith("A", "B");
+			const enc = createEncounter([
+				{ id: combatantId("c-5"), name: "Imported" },
+			]);
+			if (isDomainError(enc)) throw new Error("Setup failed");
+
+			const next = encounterReducer(state, {
+				type: "import",
+				encounter: enc,
+				undoRedoState: EMPTY_UNDO_REDO_STATE,
+			});
+
+			expect(next.encounter.combatants).toHaveLength(1);
+			expect(next.encounter.combatants[0].name).toBe("Imported");
+			expect(next.nextId).toBe(5);
+		});
+	});
+
+	describe("events accumulation", () => {
+		it("accumulates events across actions", () => {
+			const s1 = encounterReducer(emptyState(), {
+				type: "add-combatant",
+				name: "A",
+			});
+			const s2 = encounterReducer(s1, {
+				type: "add-combatant",
+				name: "B",
+			});
+
+			expect(s2.events.length).toBeGreaterThanOrEqual(2);
+		});
+	});
+});

apps/web/src/hooks/__tests__/use-action-bar-state.test.ts

@@ -0,0 +1,328 @@
+// @vitest-environment jsdom
+import type { PlayerCharacter } from "@initiative/domain";
+import { playerCharacterId } from "@initiative/domain";
+import { act, renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { SearchResult } from "../../contexts/bestiary-context.js";
+import { useActionBarState } from "../use-action-bar-state.js";
+
+const mockAddCombatant = vi.fn();
+const mockAddFromBestiary = vi.fn();
+const mockAddMultipleFromBestiary = vi.fn();
+const mockAddFromPlayerCharacter = vi.fn();
+const mockBestiarySearch = vi.fn<(q: string) => SearchResult[]>();
+const mockShowCreature = vi.fn();
+const mockShowBulkImport = vi.fn();
+const mockShowSourceManager = vi.fn();
+
+vi.mock("../../contexts/encounter-context.js", () => ({
+	useEncounterContext: () => ({
+		addCombatant: mockAddCombatant,
+		addFromBestiary: mockAddFromBestiary,
+		addMultipleFromBestiary: mockAddMultipleFromBestiary,
+		addFromPlayerCharacter: mockAddFromPlayerCharacter,
+		lastCreatureId: null,
+	}),
+}));
+
+vi.mock("../../contexts/bestiary-context.js", () => ({
+	useBestiaryContext: () => ({
+		search: mockBestiarySearch,
+		isLoaded: true,
+	}),
+}));
+
+vi.mock("../../contexts/player-characters-context.js", () => ({
+	usePlayerCharactersContext: () => ({
+		characters: mockPlayerCharacters,
+	}),
+}));
+
+vi.mock("../../contexts/side-panel-context.js", () => ({
+	useSidePanelContext: () => ({
+		showCreature: mockShowCreature,
+		showBulkImport: mockShowBulkImport,
+		showSourceManager: mockShowSourceManager,
+		panelView: { mode: "closed" },
+	}),
+}));
+
+let mockPlayerCharacters: PlayerCharacter[] = [];
+
+const GOBLIN: SearchResult = {
+	name: "Goblin",
+	source: "MM",
+	sourceDisplayName: "Monster Manual",
+	ac: 15,
+	hp: 7,
+	dex: 14,
+	cr: "1/4",
+	initiativeProficiency: 0,
+	size: "Small",
+	type: "humanoid",
+};
+
+const ORC: SearchResult = {
+	name: "Orc",
+	source: "MM",
+	sourceDisplayName: "Monster Manual",
+	ac: 13,
+	hp: 15,
+	dex: 12,
+	cr: "1/2",
+	initiativeProficiency: 0,
+	size: "Medium",
+	type: "humanoid",
+};
+
+function renderActionBar() {
+	return renderHook(() => useActionBarState());
+}
+
+describe("useActionBarState", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockBestiarySearch.mockReturnValue([]);
+		mockPlayerCharacters = [];
+	});
+
+	describe("search and suggestions", () => {
+		it("starts with empty state", () => {
+			const { result } = renderActionBar();
+
+			expect(result.current.nameInput).toBe("");
+			expect(result.current.suggestions).toEqual([]);
+			expect(result.current.queued).toBeNull();
+			expect(result.current.browseMode).toBe(false);
+		});
+
+		it("searches bestiary when input >= 2 chars", () => {
+			mockBestiarySearch.mockReturnValue([GOBLIN]);
+			const { result } = renderActionBar();
+
+			act(() => result.current.handleNameChange("go"));
+
+			expect(mockBestiarySearch).toHaveBeenCalledWith("go");
+			expect(result.current.nameInput).toBe("go");
+		});
+
+		it("does not search when input < 2 chars", () => {
+			const { result } = renderActionBar();
+
+			act(() => result.current.handleNameChange("g"));
+
+			expect(mockBestiarySearch).not.toHaveBeenCalled();
+		});
+
+		it("matches player characters by name", () => {
+			mockPlayerCharacters = [
+				{
+					id: playerCharacterId("pc-1"),
+					name: "Gandalf",
+					ac: 15,
+					maxHp: 40,
+				},
+			];
+			mockBestiarySearch.mockReturnValue([]);
+			const { result } = renderActionBar();
+
+			act(() => result.current.handleNameChange("gan"));
+
+			expect(result.current.pcMatches).toHaveLength(1);
+		});
+	});
+
+	describe("queued creatures", () => {
+		it("queues a creature on click", () => {
+			const { result } = renderActionBar();
+
+			act(() => result.current.suggestionActions.clickSuggestion(GOBLIN));
+
+			expect(result.current.queued).toEqual({
+				result: GOBLIN,
+				count: 1,
+			});
+		});
+
+		it("increments count when same creature clicked again", () => {
+			const { result } = renderActionBar();
+
+			act(() => result.current.suggestionActions.clickSuggestion(GOBLIN));
+			act(() => result.current.suggestionActions.clickSuggestion(GOBLIN));
+
+			expect(result.current.queued?.count).toBe(2);
+		});
+
+		it("resets queue when different creature clicked", () => {
+			const { result } = renderActionBar();
+
+			act(() => result.current.suggestionActions.clickSuggestion(GOBLIN));
+			act(() => result.current.suggestionActions.clickSuggestion(ORC));
+
+			expect(result.current.queued).toEqual({
+				result: ORC,
+				count: 1,
+			});
+		});
+
+		it("confirmQueued calls addFromBestiary for count=1", () => {
+			const { result } = renderActionBar();
+
+			act(() => result.current.suggestionActions.clickSuggestion(GOBLIN));
+			act(() => result.current.suggestionActions.confirmQueued());
+
+			expect(mockAddFromBestiary).toHaveBeenCalledWith(GOBLIN);
+			expect(result.current.queued).toBeNull();
+		});
+
+		it("confirmQueued calls addMultipleFromBestiary for count>1", () => {
+			const { result } = renderActionBar();
+
+			act(() => result.current.suggestionActions.clickSuggestion(GOBLIN));
+			act(() => result.current.suggestionActions.clickSuggestion(GOBLIN));
+			act(() => result.current.suggestionActions.clickSuggestion(GOBLIN));
+			act(() => result.current.suggestionActions.confirmQueued());
+
+			expect(mockAddMultipleFromBestiary).toHaveBeenCalledWith(GOBLIN, 3);
+		});
+
+		it("clears queued when search text changes and creature no longer visible", () => {
+			mockBestiarySearch.mockReturnValue([GOBLIN]);
+			const { result } = renderActionBar();
+
+			act(() => result.current.handleNameChange("go"));
+			act(() => result.current.suggestionActions.clickSuggestion(GOBLIN));
+
+			// Change search to something that won't match
+			mockBestiarySearch.mockReturnValue([]);
+			act(() => result.current.handleNameChange("xyz"));
+
+			expect(result.current.queued).toBeNull();
+		});
+	});
+
+	describe("form submission", () => {
+		it("adds custom combatant on submit", () => {
+			const { result } = renderActionBar();
+
+			act(() => result.current.handleNameChange("Fighter"));
+
+			const event = {
+				preventDefault: vi.fn(),
+			} as unknown as React.SubmitEvent<HTMLFormElement>;
+			act(() => result.current.handleAdd(event));
+
+			expect(mockAddCombatant).toHaveBeenCalledWith("Fighter", undefined);
+			expect(result.current.nameInput).toBe("");
+		});
+
+		it("does not add when name is empty", () => {
+			const { result } = renderActionBar();
+
+			const event = {
+				preventDefault: vi.fn(),
+			} as unknown as React.SubmitEvent<HTMLFormElement>;
+			act(() => result.current.handleAdd(event));
+
+			expect(mockAddCombatant).not.toHaveBeenCalled();
+		});
+
+		it("passes custom init/ac/maxHp when set", () => {
+			const { result } = renderActionBar();
+
+			act(() => result.current.handleNameChange("Fighter"));
+			act(() => result.current.setCustomInit("15"));
+			act(() => result.current.setCustomAc("18"));
+			act(() => result.current.setCustomMaxHp("45"));
+
+			const event = {
+				preventDefault: vi.fn(),
+			} as unknown as React.SubmitEvent<HTMLFormElement>;
+			act(() => result.current.handleAdd(event));
+
+			expect(mockAddCombatant).toHaveBeenCalledWith("Fighter", {
+				initiative: 15,
+				ac: 18,
+				maxHp: 45,
+			});
+		});
+
+		it("does not submit in browse mode", () => {
+			const { result } = renderActionBar();
+
+			act(() => result.current.toggleBrowseMode());
+			act(() => result.current.handleNameChange("Fighter"));
+
+			const event = {
+				preventDefault: vi.fn(),
+			} as unknown as React.SubmitEvent<HTMLFormElement>;
+			act(() => result.current.handleAdd(event));
+
+			expect(mockAddCombatant).not.toHaveBeenCalled();
+		});
+
+		it("confirms queued on submit instead of adding by name", () => {
+			const { result } = renderActionBar();
+
+			act(() => result.current.suggestionActions.clickSuggestion(GOBLIN));
+
+			const event = {
+				preventDefault: vi.fn(),
+			} as unknown as React.SubmitEvent<HTMLFormElement>;
+			act(() => result.current.handleAdd(event));
+
+			expect(mockAddFromBestiary).toHaveBeenCalledWith(GOBLIN);
+			expect(mockAddCombatant).not.toHaveBeenCalled();
+		});
+	});
+
+	describe("browse mode", () => {
+		it("toggles browse mode", () => {
+			const { result } = renderActionBar();
+
+			act(() => result.current.toggleBrowseMode());
+			expect(result.current.browseMode).toBe(true);
+
+			act(() => result.current.toggleBrowseMode());
+			expect(result.current.browseMode).toBe(false);
+		});
+
+		it("handleBrowseSelect shows creature and exits browse mode", () => {
+			const { result } = renderActionBar();
+
+			act(() => result.current.toggleBrowseMode());
+			act(() => result.current.handleBrowseSelect(GOBLIN));
+
+			expect(mockShowCreature).toHaveBeenCalledWith("mm:goblin");
+			expect(result.current.browseMode).toBe(false);
+			expect(result.current.nameInput).toBe("");
+		});
+	});
+
+	describe("dismiss and clear", () => {
+		it("dismissSuggestions clears suggestions and queued", () => {
+			mockBestiarySearch.mockReturnValue([GOBLIN]);
+			const { result } = renderActionBar();
+
+			act(() => result.current.handleNameChange("go"));
+			act(() => result.current.suggestionActions.clickSuggestion(GOBLIN));
+			act(() => result.current.suggestionActions.dismiss());
+
+			expect(result.current.queued).toBeNull();
+			expect(result.current.suggestionIndex).toBe(-1);
+		});
+
+		it("clear resets everything", () => {
+			mockBestiarySearch.mockReturnValue([GOBLIN]);
+			const { result } = renderActionBar();
+
+			act(() => result.current.handleNameChange("go"));
+			act(() => result.current.suggestionActions.clickSuggestion(GOBLIN));
+			act(() => result.current.suggestionActions.clear());
+
+			expect(result.current.nameInput).toBe("");
+			expect(result.current.queued).toBeNull();
+			expect(result.current.suggestionIndex).toBe(-1);
+		});
+	});
+});

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

@@ -0,0 +1,145 @@
+// @vitest-environment jsdom
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useBulkImport } from "../use-bulk-import.js";
+
+vi.mock("../../adapters/bestiary-index-adapter.js", () => ({
+	getAllSourceCodes: () => ["MM", "VGM", "XGE"],
+	getDefaultFetchUrl: (code: string, baseUrl: string) =>
+		`${baseUrl}${code}.json`,
+	loadBestiaryIndex: () => ({ sources: {}, creatures: [] }),
+	getSourceDisplayName: (code: string) => code,
+}));
+
+/** Flush microtasks so the internal async IIFE inside startImport settles. */
+function flushMicrotasks(): Promise<void> {
+	return new Promise((resolve) => {
+		setTimeout(resolve, 0);
+	});
+}
+
+describe("useBulkImport", () => {
+	it("starts in idle state with all counters at 0", () => {
+		const { result } = renderHook(() => useBulkImport());
+		expect(result.current.state).toEqual({
+			status: "idle",
+			total: 0,
+			completed: 0,
+			failed: 0,
+		});
+	});
+
+	it("reset returns to idle state", async () => {
+		const { result } = renderHook(() => useBulkImport());
+
+		const isSourceCached = vi.fn().mockResolvedValue(true);
+		const fetchAndCacheSource = vi.fn();
+		const refreshCache = vi.fn();
+
+		await act(async () => {
+			result.current.startImport(
+				"https://example.com/",
+				fetchAndCacheSource,
+				isSourceCached,
+				refreshCache,
+			);
+			await flushMicrotasks();
+		});
+
+		act(() => result.current.reset());
+		expect(result.current.state.status).toBe("idle");
+	});
+
+	it("goes straight to complete when all sources are cached", async () => {
+		const { result } = renderHook(() => useBulkImport());
+
+		const isSourceCached = vi.fn().mockResolvedValue(true);
+		const fetchAndCacheSource = vi.fn();
+		const refreshCache = vi.fn();
+
+		await act(async () => {
+			result.current.startImport(
+				"https://example.com/",
+				fetchAndCacheSource,
+				isSourceCached,
+				refreshCache,
+			);
+			await flushMicrotasks();
+		});
+
+		expect(result.current.state.status).toBe("complete");
+		expect(result.current.state.completed).toBe(3);
+		expect(fetchAndCacheSource).not.toHaveBeenCalled();
+	});
+
+	it("fetches uncached sources and completes", async () => {
+		const { result } = renderHook(() => useBulkImport());
+
+		const isSourceCached = vi.fn().mockResolvedValue(false);
+		const fetchAndCacheSource = vi.fn().mockResolvedValue(undefined);
+		const refreshCache = vi.fn().mockResolvedValue(undefined);
+
+		await act(async () => {
+			result.current.startImport(
+				"https://example.com/",
+				fetchAndCacheSource,
+				isSourceCached,
+				refreshCache,
+			);
+			await flushMicrotasks();
+		});
+
+		expect(result.current.state.status).toBe("complete");
+		expect(result.current.state.completed).toBe(3);
+		expect(result.current.state.failed).toBe(0);
+		expect(fetchAndCacheSource).toHaveBeenCalledTimes(3);
+		expect(refreshCache).toHaveBeenCalled();
+	});
+
+	it("reports partial-failure when some sources fail", async () => {
+		const { result } = renderHook(() => useBulkImport());
+
+		const isSourceCached = vi.fn().mockResolvedValue(false);
+		const fetchAndCacheSource = vi
+			.fn()
+			.mockResolvedValueOnce(undefined)
+			.mockRejectedValueOnce(new Error("fail"))
+			.mockResolvedValueOnce(undefined);
+		const refreshCache = vi.fn().mockResolvedValue(undefined);
+
+		await act(async () => {
+			result.current.startImport(
+				"https://example.com/",
+				fetchAndCacheSource,
+				isSourceCached,
+				refreshCache,
+			);
+			await flushMicrotasks();
+		});
+
+		expect(result.current.state.status).toBe("partial-failure");
+		expect(result.current.state.completed).toBe(2);
+		expect(result.current.state.failed).toBe(1);
+		expect(refreshCache).toHaveBeenCalled();
+	});
+
+	it("calls refreshCache after all batches complete", async () => {
+		const { result } = renderHook(() => useBulkImport());
+
+		const isSourceCached = vi.fn().mockResolvedValue(false);
+		const fetchAndCacheSource = vi.fn().mockResolvedValue(undefined);
+		const refreshCache = vi.fn().mockResolvedValue(undefined);
+
+		await act(async () => {
+			result.current.startImport(
+				"https://example.com/",
+				fetchAndCacheSource,
+				isSourceCached,
+				refreshCache,
+			);
+			await flushMicrotasks();
+		});
+
+		expect(refreshCache).toHaveBeenCalledOnce();
+	});
+});

apps/web/src/hooks/__tests__/use-difficulty.test.ts

@@ -0,0 +1,220 @@
+// @vitest-environment jsdom
+import type {
+	Combatant,
+	CreatureId,
+	Encounter,
+	PlayerCharacter,
+} from "@initiative/domain";
+import { combatantId, creatureId, playerCharacterId } from "@initiative/domain";
+import { renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../../contexts/encounter-context.js", () => ({
+	useEncounterContext: vi.fn(),
+}));
+
+vi.mock("../../contexts/player-characters-context.js", () => ({
+	usePlayerCharactersContext: vi.fn(),
+}));
+
+vi.mock("../../contexts/bestiary-context.js", () => ({
+	useBestiaryContext: vi.fn(),
+}));
+
+import { useBestiaryContext } from "../../contexts/bestiary-context.js";
+import { useEncounterContext } from "../../contexts/encounter-context.js";
+import { usePlayerCharactersContext } from "../../contexts/player-characters-context.js";
+import { useDifficulty } from "../use-difficulty.js";
+
+const mockEncounterContext = vi.mocked(useEncounterContext);
+const mockPlayerCharactersContext = vi.mocked(usePlayerCharactersContext);
+const mockBestiaryContext = vi.mocked(useBestiaryContext);
+
+const pcId1 = playerCharacterId("pc-1");
+const pcId2 = playerCharacterId("pc-2");
+const crId1 = creatureId("creature-1");
+const _crId2 = creatureId("creature-2");
+
+function setup(options: {
+	combatants: Combatant[];
+	characters: PlayerCharacter[];
+	creatures: Map<CreatureId, { cr: string }>;
+}) {
+	const encounter = {
+		combatants: options.combatants,
+		activeIndex: 0,
+		roundNumber: 1,
+	} as Encounter;
+
+	mockEncounterContext.mockReturnValue({
+		encounter,
+	} as ReturnType<typeof useEncounterContext>);
+
+	mockPlayerCharactersContext.mockReturnValue({
+		characters: options.characters,
+	} as ReturnType<typeof usePlayerCharactersContext>);
+
+	mockBestiaryContext.mockReturnValue({
+		getCreature: (id: CreatureId) => options.creatures.get(id),
+	} as ReturnType<typeof useBestiaryContext>);
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+});
+
+describe("useDifficulty", () => {
+	it("returns difficulty result for leveled PCs and bestiary monsters", () => {
+		setup({
+			combatants: [
+				{ id: combatantId("c1"), name: "Hero", playerCharacterId: pcId1 },
+				{ id: combatantId("c2"), name: "Goblin", creatureId: crId1 },
+			],
+			characters: [{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 1 }],
+			creatures: new Map([[crId1, { cr: "1/4" }]]),
+		});
+
+		const { result } = renderHook(() => useDifficulty());
+
+		expect(result.current).not.toBeNull();
+		expect(result.current?.tier).toBe("low");
+		expect(result.current?.totalMonsterXp).toBe(50);
+	});
+
+	describe("returns null when data is insufficient (ED-2)", () => {
+		it("returns null when encounter has no combatants", () => {
+			setup({ combatants: [], characters: [], creatures: new Map() });
+
+			const { result } = renderHook(() => useDifficulty());
+			expect(result.current).toBeNull();
+		});
+
+		it("returns null when only custom combatants (no creatureId)", () => {
+			setup({
+				combatants: [
+					{
+						id: combatantId("c1"),
+						name: "Custom",
+						playerCharacterId: pcId1,
+					},
+				],
+				characters: [{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 }],
+				creatures: new Map(),
+			});
+
+			const { result } = renderHook(() => useDifficulty());
+			expect(result.current).toBeNull();
+		});
+
+		it("returns null when bestiary monsters present but no PC combatants", () => {
+			setup({
+				combatants: [
+					{ id: combatantId("c1"), name: "Goblin", creatureId: crId1 },
+				],
+				characters: [],
+				creatures: new Map([[crId1, { cr: "1" }]]),
+			});
+
+			const { result } = renderHook(() => useDifficulty());
+			expect(result.current).toBeNull();
+		});
+
+		it("returns null when PC combatants have no level", () => {
+			setup({
+				combatants: [
+					{
+						id: combatantId("c1"),
+						name: "Hero",
+						playerCharacterId: pcId1,
+					},
+					{ id: combatantId("c2"), name: "Goblin", creatureId: crId1 },
+				],
+				characters: [{ id: pcId1, name: "Hero", ac: 15, maxHp: 30 }],
+				creatures: new Map([[crId1, { cr: "1" }]]),
+			});
+
+			const { result } = renderHook(() => useDifficulty());
+			expect(result.current).toBeNull();
+		});
+
+		it("returns null when PC combatant references unknown player character", () => {
+			setup({
+				combatants: [
+					{
+						id: combatantId("c1"),
+						name: "Hero",
+						playerCharacterId: pcId2,
+					},
+					{ id: combatantId("c2"), name: "Goblin", creatureId: crId1 },
+				],
+				characters: [{ id: pcId1, name: "Other", ac: 15, maxHp: 30, level: 5 }],
+				creatures: new Map([[crId1, { cr: "1" }]]),
+			});
+
+			const { result } = renderHook(() => useDifficulty());
+			expect(result.current).toBeNull();
+		});
+	});
+
+	it("handles mixed combatants: only leveled PCs and bestiary monsters contribute", () => {
+		// Party: one leveled PC, one without level (excluded)
+		// Monsters: one bestiary creature, one custom (excluded)
+		setup({
+			combatants: [
+				{
+					id: combatantId("c1"),
+					name: "Leveled",
+					playerCharacterId: pcId1,
+				},
+				{
+					id: combatantId("c2"),
+					name: "No Level",
+					playerCharacterId: pcId2,
+				},
+				{ id: combatantId("c3"), name: "Goblin", creatureId: crId1 },
+				{ id: combatantId("c4"), name: "Custom Monster" },
+			],
+			characters: [
+				{ id: pcId1, name: "Leveled", ac: 15, maxHp: 30, level: 1 },
+				{ id: pcId2, name: "No Level", ac: 12, maxHp: 20 },
+			],
+			creatures: new Map([[crId1, { cr: "1" }]]),
+		});
+
+		const { result } = renderHook(() => useDifficulty());
+
+		expect(result.current).not.toBeNull();
+		// 1 level-1 PC: budget low=50, mod=75, high=100
+		// 1 CR 1 monster: 200 XP → high (200 >= 100)
+		expect(result.current?.tier).toBe("high");
+		expect(result.current?.totalMonsterXp).toBe(200);
+		expect(result.current?.partyBudget.low).toBe(50);
+	});
+
+	it("includes duplicate PC combatants in budget", () => {
+		// Same PC added twice → counts twice
+		setup({
+			combatants: [
+				{
+					id: combatantId("c1"),
+					name: "Hero 1",
+					playerCharacterId: pcId1,
+				},
+				{
+					id: combatantId("c2"),
+					name: "Hero 2",
+					playerCharacterId: pcId1,
+				},
+				{ id: combatantId("c3"), name: "Goblin", creatureId: crId1 },
+			],
+			characters: [{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 1 }],
+			creatures: new Map([[crId1, { cr: "1/4" }]]),
+		});
+
+		const { result } = renderHook(() => useDifficulty());
+
+		expect(result.current).not.toBeNull();
+		// 2x level 1: budget low=100
+		expect(result.current?.partyBudget.low).toBe(100);
+	});
+});

apps/web/src/hooks/__tests__/use-initiative-rolls.test.ts

@@ -0,0 +1,118 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import { type CreatureId, combatantId } from "@initiative/domain";
+import { act, renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { useInitiativeRolls } from "../use-initiative-rolls.js";
+
+const mockMakeStore = vi.fn(() => ({}));
+const mockWithUndo = vi.fn((fn: () => unknown) => fn());
+const mockGetCreature = vi.fn();
+const mockShowCreature = vi.fn();
+
+vi.mock("../../contexts/encounter-context.js", () => ({
+	useEncounterContext: () => ({
+		encounter: {
+			combatants: [
+				{
+					id: combatantId("c1"),
+					name: "Goblin",
+					creatureId: "srd:goblin" as CreatureId,
+				},
+			],
+			activeIndex: 0,
+			roundNumber: 1,
+		},
+		makeStore: mockMakeStore,
+		withUndo: mockWithUndo,
+	}),
+}));
+
+vi.mock("../../contexts/bestiary-context.js", () => ({
+	useBestiaryContext: () => ({
+		getCreature: mockGetCreature,
+	}),
+}));
+
+vi.mock("../../contexts/side-panel-context.js", () => ({
+	useSidePanelContext: () => ({
+		showCreature: mockShowCreature,
+	}),
+}));
+
+const mockRollInitiativeUseCase = vi.fn();
+const mockRollAllInitiativeUseCase = vi.fn();
+
+vi.mock("@initiative/application", () => ({
+	rollInitiativeUseCase: (...args: unknown[]) =>
+		mockRollInitiativeUseCase(...args),
+	rollAllInitiativeUseCase: (...args: unknown[]) =>
+		mockRollAllInitiativeUseCase(...args),
+}));
+
+function wrapper({ children }: { children: ReactNode }) {
+	return children;
+}
+
+describe("useInitiativeRolls", () => {
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it("handleRollInitiative calls rollInitiativeUseCase via withUndo", () => {
+		mockRollInitiativeUseCase.mockReturnValue({ initiative: 15 });
+		const { result } = renderHook(() => useInitiativeRolls(), { wrapper });
+
+		act(() => result.current.handleRollInitiative(combatantId("c1")));
+
+		expect(mockWithUndo).toHaveBeenCalled();
+		expect(mockRollInitiativeUseCase).toHaveBeenCalled();
+	});
+
+	it("sets rollSingleSkipped on domain error", () => {
+		mockRollInitiativeUseCase.mockReturnValue({
+			kind: "domain-error",
+			code: "missing-source",
+			message: "no source",
+		});
+		const { result } = renderHook(() => useInitiativeRolls(), { wrapper });
+
+		act(() => result.current.handleRollInitiative(combatantId("c1")));
+		expect(result.current.rollSingleSkipped).toBe(true);
+		expect(mockShowCreature).toHaveBeenCalledWith("srd:goblin");
+	});
+
+	it("dismissRollSingleSkipped resets the flag", () => {
+		mockRollInitiativeUseCase.mockReturnValue({
+			kind: "domain-error",
+			code: "missing-source",
+			message: "no source",
+		});
+		const { result } = renderHook(() => useInitiativeRolls(), { wrapper });
+
+		act(() => result.current.handleRollInitiative(combatantId("c1")));
+		expect(result.current.rollSingleSkipped).toBe(true);
+
+		act(() => result.current.dismissRollSingleSkipped());
+		expect(result.current.rollSingleSkipped).toBe(false);
+	});
+
+	it("handleRollAllInitiative sets rollSkippedCount when sources missing", () => {
+		mockRollAllInitiativeUseCase.mockReturnValue({ skippedNoSource: 3 });
+		const { result } = renderHook(() => useInitiativeRolls(), { wrapper });
+
+		act(() => result.current.handleRollAllInitiative());
+		expect(result.current.rollSkippedCount).toBe(3);
+	});
+
+	it("dismissRollSkipped resets the count", () => {
+		mockRollAllInitiativeUseCase.mockReturnValue({ skippedNoSource: 2 });
+		const { result } = renderHook(() => useInitiativeRolls(), { wrapper });
+
+		act(() => result.current.handleRollAllInitiative());
+		act(() => result.current.dismissRollSkipped());
+		expect(result.current.rollSkippedCount).toBe(0);
+	});
+});

apps/web/src/hooks/__tests__/use-long-press.test.ts

@@ -0,0 +1,104 @@
+// @vitest-environment jsdom
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useLongPress } from "../use-long-press.js";
+
+function touchEvent(overrides?: Partial<React.TouchEvent>): React.TouchEvent {
+	return {
+		preventDefault: vi.fn(),
+		...overrides,
+	} as unknown as React.TouchEvent;
+}
+
+describe("useLongPress", () => {
+	beforeEach(() => {
+		vi.useFakeTimers();
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+	});
+
+	it("returns onTouchStart, onTouchEnd, onTouchMove handlers", () => {
+		const { result } = renderHook(() => useLongPress(vi.fn()));
+		expect(result.current.onTouchStart).toBeInstanceOf(Function);
+		expect(result.current.onTouchEnd).toBeInstanceOf(Function);
+		expect(result.current.onTouchMove).toBeInstanceOf(Function);
+	});
+
+	it("fires onLongPress after 500ms hold", () => {
+		const onLongPress = vi.fn();
+		const { result } = renderHook(() => useLongPress(onLongPress));
+
+		const e = touchEvent();
+		act(() => result.current.onTouchStart(e));
+		expect(onLongPress).not.toHaveBeenCalled();
+
+		act(() => {
+			vi.advanceTimersByTime(500);
+		});
+		expect(onLongPress).toHaveBeenCalledOnce();
+	});
+
+	it("does not fire if released before 500ms", () => {
+		const onLongPress = vi.fn();
+		const { result } = renderHook(() => useLongPress(onLongPress));
+
+		act(() => result.current.onTouchStart(touchEvent()));
+		act(() => {
+			vi.advanceTimersByTime(300);
+		});
+		act(() => result.current.onTouchEnd(touchEvent()));
+		act(() => {
+			vi.advanceTimersByTime(500);
+		});
+
+		expect(onLongPress).not.toHaveBeenCalled();
+	});
+
+	it("cancels on touch move", () => {
+		const onLongPress = vi.fn();
+		const { result } = renderHook(() => useLongPress(onLongPress));
+
+		act(() => result.current.onTouchStart(touchEvent()));
+		act(() => {
+			vi.advanceTimersByTime(200);
+		});
+		act(() => result.current.onTouchMove());
+		act(() => {
+			vi.advanceTimersByTime(500);
+		});
+
+		expect(onLongPress).not.toHaveBeenCalled();
+	});
+
+	it("onTouchEnd calls preventDefault after long press fires", () => {
+		const onLongPress = vi.fn();
+		const { result } = renderHook(() => useLongPress(onLongPress));
+
+		act(() => result.current.onTouchStart(touchEvent()));
+		act(() => {
+			vi.advanceTimersByTime(500);
+		});
+
+		const preventDefaultSpy = vi.fn();
+		const endEvent = touchEvent({ preventDefault: preventDefaultSpy });
+		act(() => result.current.onTouchEnd(endEvent));
+		expect(preventDefaultSpy).toHaveBeenCalled();
+	});
+
+	it("onTouchEnd does not preventDefault when long press did not fire", () => {
+		const onLongPress = vi.fn();
+		const { result } = renderHook(() => useLongPress(onLongPress));
+
+		act(() => result.current.onTouchStart(touchEvent()));
+		act(() => {
+			vi.advanceTimersByTime(100);
+		});
+
+		const preventDefaultSpy = vi.fn();
+		const endEvent = touchEvent({ preventDefault: preventDefaultSpy });
+		act(() => result.current.onTouchEnd(endEvent));
+		expect(preventDefaultSpy).not.toHaveBeenCalled();
+	});
+});

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

@@ -42,7 +42,14 @@ describe("usePlayerCharacters", () => {
 		const { result } = renderHook(() => usePlayerCharacters());
 
 		act(() => {
-			result.current.createCharacter("Vex", 15, 28, undefined, undefined);
+			result.current.createCharacter(
+				"Vex",
+				15,
+				28,
+				undefined,
+				undefined,
+				undefined,
+			);
 		});
 
 		expect(result.current.characters).toHaveLength(1);
@@ -57,7 +64,14 @@ describe("usePlayerCharacters", () => {
 
 		let error: unknown;
 		act(() => {
-			error = result.current.createCharacter("", 15, 28, undefined, undefined);
+			error = result.current.createCharacter(
+				"",
+				15,
+				28,
+				undefined,
+				undefined,
+				undefined,
+			);
 		});
 
 		expect(error).toMatchObject({ kind: "domain-error" });
@@ -68,7 +82,14 @@ describe("usePlayerCharacters", () => {
 		const { result } = renderHook(() => usePlayerCharacters());
 
 		act(() => {
-			result.current.createCharacter("Vex", 15, 28, undefined, undefined);
+			result.current.createCharacter(
+				"Vex",
+				15,
+				28,
+				undefined,
+				undefined,
+				undefined,
+			);
 		});
 
 		const id = result.current.characters[0].id;
@@ -85,7 +106,14 @@ describe("usePlayerCharacters", () => {
 		const { result } = renderHook(() => usePlayerCharacters());
 
 		act(() => {
-			result.current.createCharacter("Vex", 15, 28, undefined, undefined);
+			result.current.createCharacter(
+				"Vex",
+				15,
+				28,
+				undefined,
+				undefined,
+				undefined,
+			);
 		});
 
 		const id = result.current.characters[0].id;

apps/web/src/hooks/__tests__/use-rules-edition.test.ts

@@ -0,0 +1,45 @@
+// @vitest-environment jsdom
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { useRulesEdition } from "../use-rules-edition.js";
+
+const STORAGE_KEY = "initiative:rules-edition";
+
+describe("useRulesEdition", () => {
+	afterEach(() => {
+		// Reset to default
+		const { result } = renderHook(() => useRulesEdition());
+		act(() => result.current.setEdition("5.5e"));
+		localStorage.removeItem(STORAGE_KEY);
+	});
+
+	it("defaults to 5.5e", () => {
+		const { result } = renderHook(() => useRulesEdition());
+		expect(result.current.edition).toBe("5.5e");
+	});
+
+	it("setEdition updates value", () => {
+		const { result } = renderHook(() => useRulesEdition());
+
+		act(() => result.current.setEdition("5e"));
+
+		expect(result.current.edition).toBe("5e");
+	});
+
+	it("setEdition persists to localStorage", () => {
+		const { result } = renderHook(() => useRulesEdition());
+
+		act(() => result.current.setEdition("5e"));
+
+		expect(localStorage.getItem(STORAGE_KEY)).toBe("5e");
+	});
+
+	it("multiple hooks stay in sync", () => {
+		const { result: r1 } = renderHook(() => useRulesEdition());
+		const { result: r2 } = renderHook(() => useRulesEdition());
+
+		act(() => r1.current.setEdition("5e"));
+
+		expect(r2.current.edition).toBe("5e");
+	});
+});

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

@@ -0,0 +1,116 @@
+// @vitest-environment jsdom
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useSwipeToDismiss } from "../use-swipe-to-dismiss.js";
+
+const PANEL_WIDTH = 300;
+
+function makeTouchEvent(clientX: number, clientY = 0): React.TouchEvent {
+	return {
+		touches: [{ clientX, clientY }],
+		currentTarget: {
+			getBoundingClientRect: () => ({ width: PANEL_WIDTH }),
+		},
+	} as unknown as React.TouchEvent;
+}
+
+describe("useSwipeToDismiss", () => {
+	beforeEach(() => {
+		vi.spyOn(Date, "now").mockReturnValue(0);
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("starts with offsetX 0 and isSwiping false", () => {
+		const { result } = renderHook(() => useSwipeToDismiss(vi.fn()));
+		expect(result.current.offsetX).toBe(0);
+		expect(result.current.isSwiping).toBe(false);
+	});
+
+	it("horizontal drag updates offsetX and sets isSwiping", () => {
+		const { result } = renderHook(() => useSwipeToDismiss(vi.fn()));
+
+		act(() => result.current.handlers.onTouchStart(makeTouchEvent(0)));
+		act(() => result.current.handlers.onTouchMove(makeTouchEvent(50)));
+
+		expect(result.current.offsetX).toBe(50);
+		expect(result.current.isSwiping).toBe(true);
+	});
+
+	it("vertical drag is ignored after direction lock", () => {
+		const { result } = renderHook(() => useSwipeToDismiss(vi.fn()));
+
+		act(() => result.current.handlers.onTouchStart(makeTouchEvent(0, 0)));
+		// Move vertically > 10px to lock vertical
+		act(() => result.current.handlers.onTouchMove(makeTouchEvent(0, 20)));
+
+		expect(result.current.offsetX).toBe(0);
+	});
+
+	it("small movement does not lock direction", () => {
+		const { result } = renderHook(() => useSwipeToDismiss(vi.fn()));
+
+		act(() => result.current.handlers.onTouchStart(makeTouchEvent(0)));
+		act(() => result.current.handlers.onTouchMove(makeTouchEvent(5)));
+
+		// No direction locked yet, no update
+		expect(result.current.offsetX).toBe(0);
+		expect(result.current.isSwiping).toBe(false);
+	});
+
+	it("leftward drag is clamped to 0", () => {
+		const { result } = renderHook(() => useSwipeToDismiss(vi.fn()));
+
+		act(() => result.current.handlers.onTouchStart(makeTouchEvent(100)));
+		act(() => result.current.handlers.onTouchMove(makeTouchEvent(50)));
+
+		expect(result.current.offsetX).toBe(0);
+	});
+
+	it("calls onDismiss when ratio exceeds threshold", () => {
+		const onDismiss = vi.fn();
+		const { result } = renderHook(() => useSwipeToDismiss(onDismiss));
+
+		act(() => result.current.handlers.onTouchStart(makeTouchEvent(0)));
+		// Move > 35% of panel width (300 * 0.35 = 105)
+		act(() => result.current.handlers.onTouchMove(makeTouchEvent(120)));
+
+		vi.spyOn(Date, "now").mockReturnValue(5000); // slow swipe
+		act(() => result.current.handlers.onTouchEnd());
+
+		expect(onDismiss).toHaveBeenCalled();
+	});
+
+	it("calls onDismiss with fast velocity", () => {
+		const onDismiss = vi.fn();
+		const { result } = renderHook(() => useSwipeToDismiss(onDismiss));
+
+		act(() => result.current.handlers.onTouchStart(makeTouchEvent(0)));
+		// Small distance but fast
+		act(() => result.current.handlers.onTouchMove(makeTouchEvent(30)));
+
+		// Very fast: 30px in 0.1s = 300px/s, velocity = 300/300 = 1.0 > 0.5
+		vi.spyOn(Date, "now").mockReturnValue(100);
+		act(() => result.current.handlers.onTouchEnd());
+
+		expect(onDismiss).toHaveBeenCalled();
+	});
+
+	it("does not dismiss when below thresholds", () => {
+		const onDismiss = vi.fn();
+		const { result } = renderHook(() => useSwipeToDismiss(onDismiss));
+
+		act(() => result.current.handlers.onTouchStart(makeTouchEvent(0)));
+		// Small distance, slow speed
+		act(() => result.current.handlers.onTouchMove(makeTouchEvent(20)));
+
+		vi.spyOn(Date, "now").mockReturnValue(5000);
+		act(() => result.current.handlers.onTouchEnd());
+
+		expect(onDismiss).not.toHaveBeenCalled();
+		expect(result.current.offsetX).toBe(0);
+		expect(result.current.isSwiping).toBe(false);
+	});
+});

apps/web/src/hooks/__tests__/use-theme.test.ts

@@ -0,0 +1,63 @@
+// @vitest-environment jsdom
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { useTheme } from "../use-theme.js";
+
+const STORAGE_KEY = "initiative:theme";
+
+describe("useTheme", () => {
+	afterEach(() => {
+		// Reset to default
+		const { result } = renderHook(() => useTheme());
+		act(() => result.current.setPreference("system"));
+		localStorage.removeItem(STORAGE_KEY);
+	});
+
+	it("defaults to system preference", () => {
+		const { result } = renderHook(() => useTheme());
+		expect(result.current.preference).toBe("system");
+	});
+
+	it("setPreference updates to light", () => {
+		const { result } = renderHook(() => useTheme());
+
+		act(() => result.current.setPreference("light"));
+
+		expect(result.current.preference).toBe("light");
+		expect(result.current.resolved).toBe("light");
+	});
+
+	it("setPreference updates to dark", () => {
+		const { result } = renderHook(() => useTheme());
+
+		act(() => result.current.setPreference("dark"));
+
+		expect(result.current.preference).toBe("dark");
+		expect(result.current.resolved).toBe("dark");
+	});
+
+	it("persists preference to localStorage", () => {
+		const { result } = renderHook(() => useTheme());
+
+		act(() => result.current.setPreference("light"));
+
+		expect(localStorage.getItem(STORAGE_KEY)).toBe("light");
+	});
+
+	it("applies theme to document element", () => {
+		const { result } = renderHook(() => useTheme());
+
+		act(() => result.current.setPreference("light"));
+
+		expect(document.documentElement.dataset.theme).toBe("light");
+	});
+
+	it("multiple hooks stay in sync", () => {
+		const { result: r1 } = renderHook(() => useTheme());
+		const { result: r2 } = renderHook(() => useTheme());
+
+		act(() => r1.current.setPreference("dark"));
+
+		expect(r2.current.preference).toBe("dark");
+	});
+});

apps/web/src/hooks/use-action-bar-state.ts

@@ -0,0 +1,323 @@
+import type { CreatureId, PlayerCharacter } from "@initiative/domain";
+import {
+	useCallback,
+	useDeferredValue,
+	useEffect,
+	useMemo,
+	useRef,
+	useState,
+} from "react";
+import type { SearchResult } from "../contexts/bestiary-context.js";
+import { useBestiaryContext } from "../contexts/bestiary-context.js";
+import { useEncounterContext } from "../contexts/encounter-context.js";
+import { usePlayerCharactersContext } from "../contexts/player-characters-context.js";
+import { useSidePanelContext } from "../contexts/side-panel-context.js";
+
+export interface QueuedCreature {
+	result: SearchResult;
+	count: number;
+}
+
+export interface SuggestionActions {
+	dismiss: () => void;
+	clear: () => void;
+	clickSuggestion: (result: SearchResult) => void;
+	setSuggestionIndex: (i: number) => void;
+	setQueued: (q: QueuedCreature | null) => void;
+	confirmQueued: () => void;
+	addFromPlayerCharacter?: (pc: PlayerCharacter) => void;
+}
+
+export function creatureKey(r: SearchResult): string {
+	return `${r.source}:${r.name}`;
+}
+
+export function useActionBarState() {
+	const {
+		addCombatant,
+		addFromBestiary,
+		addMultipleFromBestiary,
+		addFromPlayerCharacter,
+		lastCreatureId,
+	} = useEncounterContext();
+	const { search: bestiarySearch, isLoaded: bestiaryLoaded } =
+		useBestiaryContext();
+	const { characters: playerCharacters } = usePlayerCharactersContext();
+	const { showBulkImport, showSourceManager, showCreature, panelView } =
+		useSidePanelContext();
+
+	// Auto-show stat block when a bestiary creature is added on desktop
+	const prevCreatureIdRef = useRef(lastCreatureId);
+	useEffect(() => {
+		if (
+			lastCreatureId &&
+			lastCreatureId !== prevCreatureIdRef.current &&
+			panelView.mode === "closed" &&
+			globalThis.matchMedia("(min-width: 1024px)").matches
+		) {
+			showCreature(lastCreatureId);
+		}
+		prevCreatureIdRef.current = lastCreatureId;
+	}, [lastCreatureId, panelView.mode, showCreature]);
+
+	const [nameInput, setNameInput] = useState("");
+	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 = useCallback(() => {
+		setNameInput("");
+		setSuggestions([]);
+		setPcMatches([]);
+		setQueued(null);
+		setSuggestionIndex(-1);
+	}, []);
+
+	const dismissSuggestions = useCallback(() => {
+		setSuggestions([]);
+		setPcMatches([]);
+		setQueued(null);
+		setSuggestionIndex(-1);
+	}, []);
+
+	const handleAddFromBestiary = useCallback(
+		(result: SearchResult) => {
+			addFromBestiary(result);
+		},
+		[addFromBestiary],
+	);
+
+	const handleViewStatBlock = useCallback(
+		(result: SearchResult) => {
+			const slug = result.name
+				.toLowerCase()
+				.replaceAll(/[^a-z0-9]+/g, "-")
+				.replaceAll(/(^-|-$)/g, "");
+			const cId = `${result.source.toLowerCase()}:${slug}` as CreatureId;
+			showCreature(cId);
+		},
+		[showCreature],
+	);
+
+	const confirmQueued = useCallback(() => {
+		if (!queued) return;
+		if (queued.count === 1) {
+			handleAddFromBestiary(queued.result);
+		} else {
+			addMultipleFromBestiary(queued.result, queued.count);
+		}
+		clearInput();
+	}, [queued, handleAddFromBestiary, addMultipleFromBestiary, 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: React.SubmitEvent<HTMLFormElement>) => {
+		e.preventDefault();
+		if (browseMode) return;
+		if (queued) {
+			confirmQueued();
+			return;
+		}
+		if (nameInput.trim() === "") return;
+		const opts: { initiative?: number; ac?: number; maxHp?: number } = {};
+		const init = parseNum(customInit);
+		const ac = parseNum(customAc);
+		const maxHp = parseNum(customMaxHp);
+		if (init !== undefined) opts.initiative = init;
+		if (ac !== undefined) opts.ac = ac;
+		if (maxHp !== undefined) opts.maxHp = maxHp;
+		addCombatant(nameInput, Object.keys(opts).length > 0 ? opts : undefined);
+		setNameInput("");
+		setSuggestions([]);
+		setPcMatches([]);
+		clearCustomFields();
+	};
+
+	const handleBrowseSearch = (value: string) => {
+		setSuggestions(value.length >= 2 ? bestiarySearch(value) : []);
+	};
+
+	const handleAddSearch = (value: string) => {
+		let newSuggestions: SearchResult[] = [];
+		let newPcMatches: PlayerCharacter[] = [];
+		if (value.length >= 2) {
+			newSuggestions = bestiarySearch(value);
+			setSuggestions(newSuggestions);
+			if (playerCharacters && playerCharacters.length > 0) {
+				const lower = value.toLowerCase();
+				newPcMatches = playerCharacters.filter((pc) =>
+					pc.name.toLowerCase().includes(lower),
+				);
+			}
+			setPcMatches(newPcMatches);
+		} else {
+			setSuggestions([]);
+			setPcMatches([]);
+		}
+		if (newSuggestions.length > 0 || newPcMatches.length > 0) {
+			clearCustomFields();
+		}
+		if (queued) {
+			const qKey = creatureKey(queued.result);
+			const stillVisible = newSuggestions.some((s) => creatureKey(s) === qKey);
+			if (!stillVisible) {
+				setQueued(null);
+			}
+		}
+	};
+
+	const handleNameChange = (value: string) => {
+		setNameInput(value);
+		setSuggestionIndex(-1);
+		if (browseMode) {
+			handleBrowseSearch(value);
+		} else {
+			handleAddSearch(value);
+		}
+	};
+
+	const handleClickSuggestion = useCallback((result: SearchResult) => {
+		const key = creatureKey(result);
+		setQueued((prev) => {
+			if (prev && creatureKey(prev.result) === key) {
+				return { ...prev, count: prev.count + 1 };
+			}
+			return { result, count: 1 };
+		});
+	}, []);
+
+	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 (!hasSuggestions) return;
+
+		if (e.key === "ArrowDown") {
+			e.preventDefault();
+			setSuggestionIndex((i) => (i < suggestions.length - 1 ? i + 1 : 0));
+		} else if (e.key === "ArrowUp") {
+			e.preventDefault();
+			setSuggestionIndex((i) => (i > 0 ? i - 1 : suggestions.length - 1));
+		} else if (e.key === "Enter") {
+			e.preventDefault();
+			handleEnter();
+		} else if (e.key === "Escape") {
+			dismissSuggestions();
+		}
+	};
+
+	const handleBrowseKeyDown = (e: React.KeyboardEvent) => {
+		if (e.key === "Escape") {
+			setBrowseMode(false);
+			clearInput();
+			return;
+		}
+		if (suggestions.length === 0) return;
+		if (e.key === "ArrowDown") {
+			e.preventDefault();
+			setSuggestionIndex((i) => (i < suggestions.length - 1 ? i + 1 : 0));
+		} else if (e.key === "ArrowUp") {
+			e.preventDefault();
+			setSuggestionIndex((i) => (i > 0 ? i - 1 : suggestions.length - 1));
+		} else if (e.key === "Enter" && suggestionIndex >= 0) {
+			e.preventDefault();
+			handleViewStatBlock(suggestions[suggestionIndex]);
+			setBrowseMode(false);
+			clearInput();
+		}
+	};
+
+	const handleBrowseSelect = (result: SearchResult) => {
+		handleViewStatBlock(result);
+		setBrowseMode(false);
+		clearInput();
+	};
+
+	const toggleBrowseMode = () => {
+		setBrowseMode((prev) => {
+			const next = !prev;
+			setSuggestionIndex(-1);
+			setQueued(null);
+			if (next) {
+				handleBrowseSearch(nameInput);
+			} else {
+				handleAddSearch(nameInput);
+			}
+			return next;
+		});
+		clearCustomFields();
+	};
+
+	const suggestionActions: SuggestionActions = useMemo(
+		() => ({
+			dismiss: dismissSuggestions,
+			clear: clearInput,
+			clickSuggestion: handleClickSuggestion,
+			setSuggestionIndex,
+			setQueued,
+			confirmQueued,
+			addFromPlayerCharacter,
+		}),
+		[
+			dismissSuggestions,
+			clearInput,
+			handleClickSuggestion,
+			confirmQueued,
+			addFromPlayerCharacter,
+		],
+	);
+
+	return {
+		// State
+		nameInput,
+		suggestions: deferredSuggestions,
+		pcMatches: deferredPcMatches,
+		suggestionIndex,
+		queued,
+		customInit,
+		customAc,
+		customMaxHp,
+		browseMode,
+		bestiaryLoaded,
+		hasSuggestions,
+		showBulkImport,
+		showSourceManager,
+
+		// Actions
+		suggestionActions,
+		handleNameChange,
+		handleKeyDown,
+		handleBrowseKeyDown,
+		handleAdd,
+		handleBrowseSelect,
+		toggleBrowseMode,
+		setCustomInit,
+		setCustomAc,
+		setCustomMaxHp,
+	} as const;
+}

apps/web/src/hooks/use-auto-stat-block.ts

@@ -1,4 +1,4 @@
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
 import { useEncounterContext } from "../contexts/encounter-context.js";
 import { useSidePanelContext } from "../contexts/side-panel-context.js";
 
@@ -8,10 +8,20 @@ export function useAutoStatBlock(): void {
 
 	const activeCreatureId =
 		encounter.combatants[encounter.activeIndex]?.creatureId;
+	const prevActiveIndexRef = useRef(encounter.activeIndex);
 
 	useEffect(() => {
-		if (activeCreatureId && panelView.mode === "creature") {
+		const prevIndex = prevActiveIndexRef.current;
+		prevActiveIndexRef.current = encounter.activeIndex;
+
+		// Only auto-update when the active turn changes (advance/retreat),
+		// not when the panel mode changes (user clicking a different creature).
+		if (
+			encounter.activeIndex !== prevIndex &&
+			activeCreatureId &&
+			panelView.mode === "creature"
+		) {
 			updateCreature(activeCreatureId);
 		}
-	}, [activeCreatureId, panelView.mode, updateCreature]);
+	}, [encounter.activeIndex, activeCreatureId, panelView.mode, updateCreature]);
 }

apps/web/src/hooks/use-click-outside.ts

@@ -0,0 +1,27 @@
+import type { RefObject } from "react";
+import { useEffect } from "react";
+
+export function useClickOutside(
+	ref: RefObject<HTMLElement | null>,
+	onClose: () => void,
+	active = true,
+): void {
+	useEffect(() => {
+		if (!active) return;
+
+		function handleMouseDown(e: MouseEvent) {
+			if (ref.current && !ref.current.contains(e.target as Node)) {
+				onClose();
+			}
+		}
+		function handleKeyDown(e: KeyboardEvent) {
+			if (e.key === "Escape") onClose();
+		}
+		document.addEventListener("mousedown", handleMouseDown);
+		document.addEventListener("keydown", handleKeyDown);
+		return () => {
+			document.removeEventListener("mousedown", handleMouseDown);
+			document.removeEventListener("keydown", handleKeyDown);
+		};
+	}, [ref, onClose, active]);
+}

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

@@ -0,0 +1,54 @@
+import type {
+	Combatant,
+	CreatureId,
+	DifficultyResult,
+	PlayerCharacter,
+} from "@initiative/domain";
+import { calculateEncounterDifficulty } from "@initiative/domain";
+import { useMemo } from "react";
+import { useBestiaryContext } from "../contexts/bestiary-context.js";
+import { useEncounterContext } from "../contexts/encounter-context.js";
+import { usePlayerCharactersContext } from "../contexts/player-characters-context.js";
+
+function derivePartyLevels(
+	combatants: readonly Combatant[],
+	characters: readonly PlayerCharacter[],
+): number[] {
+	const levels: number[] = [];
+	for (const c of combatants) {
+		if (!c.playerCharacterId) continue;
+		const pc = characters.find((p) => p.id === c.playerCharacterId);
+		if (pc?.level !== undefined) levels.push(pc.level);
+	}
+	return levels;
+}
+
+function deriveMonsterCrs(
+	combatants: readonly Combatant[],
+	getCreature: (id: CreatureId) => { cr: string } | undefined,
+): string[] {
+	const crs: string[] = [];
+	for (const c of combatants) {
+		if (!c.creatureId) continue;
+		const creature = getCreature(c.creatureId);
+		if (creature) crs.push(creature.cr);
+	}
+	return crs;
+}
+
+export function useDifficulty(): DifficultyResult | null {
+	const { encounter } = useEncounterContext();
+	const { characters } = usePlayerCharactersContext();
+	const { getCreature } = useBestiaryContext();
+
+	return useMemo(() => {
+		const partyLevels = derivePartyLevels(encounter.combatants, characters);
+		const monsterCrs = deriveMonsterCrs(encounter.combatants, getCreature);
+
+		if (partyLevels.length === 0 || monsterCrs.length === 0) {
+			return null;
+		}
+
+		return calculateEncounterDifficulty(partyLevels, monsterCrs);
+	}, [encounter.combatants, characters, getCreature]);
+}

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

@@ -1,10 +1,11 @@
-import type { EncounterStore } from "@initiative/application";
+import type { EncounterStore, UndoRedoStore } from "@initiative/application";
 import {
 	addCombatantUseCase,
 	adjustHpUseCase,
 	advanceTurnUseCase,
 	clearEncounterUseCase,
 	editCombatantUseCase,
+	redoUseCase,
 	removeCombatantUseCase,
 	retreatTurnUseCase,
 	setAcUseCase,
@@ -13,27 +14,82 @@ import {
 	setTempHpUseCase,
 	toggleConcentrationUseCase,
 	toggleConditionUseCase,
+	undoUseCase,
 } from "@initiative/application";
 import type {
 	BestiaryIndexEntry,
 	CombatantId,
+	CombatantInit,
 	ConditionId,
 	CreatureId,
+	DomainError,
 	DomainEvent,
 	Encounter,
 	PlayerCharacter,
+	UndoRedoState,
 } from "@initiative/domain";
 import {
+	clearHistory,
 	combatantId,
 	isDomainError,
 	creatureId as makeCreatureId,
+	pushUndo,
 	resolveCreatureName,
 } from "@initiative/domain";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useReducer, useRef } from "react";
 import {
 	loadEncounter,
 	saveEncounter,
 } from "../persistence/encounter-storage.js";
+import {
+	loadUndoRedoStacks,
+	saveUndoRedoStacks,
+} from "../persistence/undo-redo-storage.js";
+
+// -- Types --
+
+type EncounterAction =
+	| { type: "advance-turn" }
+	| { type: "retreat-turn" }
+	| { type: "add-combatant"; name: string; init?: CombatantInit }
+	| { type: "remove-combatant"; id: CombatantId }
+	| { type: "edit-combatant"; id: CombatantId; newName: string }
+	| { type: "set-initiative"; id: CombatantId; value: number | undefined }
+	| { type: "set-hp"; id: CombatantId; maxHp: number | undefined }
+	| { type: "adjust-hp"; id: CombatantId; delta: number }
+	| { type: "set-temp-hp"; id: CombatantId; tempHp: number | undefined }
+	| { type: "set-ac"; id: CombatantId; value: number | undefined }
+	| {
+			type: "toggle-condition";
+			id: CombatantId;
+			conditionId: ConditionId;
+	  }
+	| { type: "toggle-concentration"; id: CombatantId }
+	| { type: "clear-encounter" }
+	| { type: "undo" }
+	| { type: "redo" }
+	| { type: "add-from-bestiary"; entry: BestiaryIndexEntry }
+	| {
+			type: "add-multiple-from-bestiary";
+			entry: BestiaryIndexEntry;
+			count: number;
+	  }
+	| { type: "add-from-player-character"; pc: PlayerCharacter }
+	| {
+			type: "import";
+			encounter: Encounter;
+			undoRedoState: UndoRedoState;
+	  };
+
+export interface EncounterState {
+	readonly encounter: Encounter;
+	readonly undoRedoState: UndoRedoState;
+	readonly events: readonly DomainEvent[];
+	readonly nextId: number;
+	readonly lastCreatureId: CreatureId | null;
+}
+
+// -- Initialization --
 
 const COMBATANT_ID_REGEX = /^c-(\d+)$/;
 
@@ -43,12 +99,6 @@ const EMPTY_ENCOUNTER: Encounter = {
 	roundNumber: 1,
 };
 
-function initializeEncounter(): Encounter {
-	const stored = loadEncounter();
-	if (stored !== null) return stored;
-	return EMPTY_ENCOUNTER;
-}
-
 function deriveNextId(encounter: Encounter): number {
 	let max = 0;
 	for (const c of encounter.combatants) {
@@ -61,339 +111,332 @@ 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[]>([]);
-	const encounterRef = useRef(encounter);
-	encounterRef.current = encounter;
-
-	useEffect(() => {
-		saveEncounter(encounter);
-	}, [encounter]);
-
-	const makeStore = useCallback((): EncounterStore => {
+function initializeState(): EncounterState {
+	const encounter = loadEncounter() ?? EMPTY_ENCOUNTER;
 	return {
-			get: () => encounterRef.current,
-			save: (e) => {
-				encounterRef.current = e;
-				setEncounter(e);
-			},
+		encounter,
+		undoRedoState: loadUndoRedoStacks(),
+		events: [],
+		nextId: deriveNextId(encounter),
+		lastCreatureId: null,
 	};
-	}, []);
+}
 
-	const advanceTurn = useCallback(() => {
-		const result = advanceTurnUseCase(makeStore());
+// -- Helpers --
 
-		if (isDomainError(result)) {
-			return;
-		}
-
-		setEvents((prev) => [...prev, ...result]);
-	}, [makeStore]);
-
-	const retreatTurn = useCallback(() => {
-		const result = retreatTurnUseCase(makeStore());
-
-		if (isDomainError(result)) {
-			return;
-		}
-
-		setEvents((prev) => [...prev, ...result]);
-	}, [makeStore]);
-
-	const nextId = useRef(deriveNextId(encounter));
-
-	const addCombatant = useCallback(
-		(name: string, opts?: CombatantOpts) => {
-			const id = combatantId(`c-${++nextId.current}`);
-			const result = addCombatantUseCase(makeStore(), id, name);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			if (opts) {
-				const optEvents = applyCombatantOpts(makeStore, id, opts);
-				if (optEvents.length > 0) {
-					setEvents((prev) => [...prev, ...optEvents]);
-				}
-			}
-
-			setEvents((prev) => [...prev, ...result]);
+function makeStoreFromState(state: EncounterState): {
+	store: EncounterStore;
+	getEncounter: () => Encounter;
+} {
+	let current = state.encounter;
+	return {
+		store: {
+			get: () => current,
+			save: (e) => {
+				current = e;
 			},
-		[makeStore],
-	);
-
-	const removeCombatant = useCallback(
-		(id: CombatantId) => {
-			const result = removeCombatantUseCase(makeStore(), id);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
 		},
-		[makeStore],
-	);
+		getEncounter: () => current,
+	};
+}
 
-	const editCombatant = useCallback(
-		(id: CombatantId, newName: string) => {
-			const result = editCombatantUseCase(makeStore(), id, newName);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
-	);
-
-	const setInitiative = useCallback(
-		(id: CombatantId, value: number | undefined) => {
-			const result = setInitiativeUseCase(makeStore(), id, value);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
-	);
-
-	const setHp = useCallback(
-		(id: CombatantId, maxHp: number | undefined) => {
-			const result = setHpUseCase(makeStore(), id, maxHp);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
-	);
-
-	const adjustHp = useCallback(
-		(id: CombatantId, delta: number) => {
-			const result = adjustHpUseCase(makeStore(), id, delta);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
-	);
-
-	const setTempHp = useCallback(
-		(id: CombatantId, tempHp: number | undefined) => {
-			const result = setTempHpUseCase(makeStore(), id, tempHp);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
-	);
-
-	const setAc = useCallback(
-		(id: CombatantId, value: number | undefined) => {
-			const result = setAcUseCase(makeStore(), id, value);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
-	);
-
-	const toggleCondition = useCallback(
-		(id: CombatantId, conditionId: ConditionId) => {
-			const result = toggleConditionUseCase(makeStore(), id, conditionId);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
-	);
-
-	const toggleConcentration = useCallback(
-		(id: CombatantId) => {
-			const result = toggleConcentrationUseCase(makeStore(), id);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
-	);
-
-	const clearEncounter = useCallback(() => {
-		const result = clearEncounterUseCase(makeStore());
-
-		if (isDomainError(result)) {
-			return;
-		}
-
-		nextId.current = 0;
-		setEvents((prev) => [...prev, ...result]);
-	}, [makeStore]);
-
-	const addFromBestiary = useCallback(
-		(entry: BestiaryIndexEntry): CreatureId | null => {
-			const store = makeStore();
+function resolveAndRename(store: EncounterStore, name: string): string {
 	const existingNames = store.get().combatants.map((c) => c.name);
-			const { newName, renames } = resolveCreatureName(
-				entry.name,
-				existingNames,
-			);
+	const { newName, renames } = resolveCreatureName(name, existingNames);
 
-			// Apply renames (e.g., "Goblin" → "Goblin 1")
 	for (const { from, to } of renames) {
 		const target = store.get().combatants.find((c) => c.name === from);
 		if (target) {
-					editCombatantUseCase(makeStore(), target.id, to);
+			editCombatantUseCase(store, target.id, to);
 		}
 	}
 
-			// Add combatant with resolved name
-			const id = combatantId(`c-${++nextId.current}`);
-			const addResult = addCombatantUseCase(makeStore(), id, newName);
-			if (isDomainError(addResult)) return null;
+	return newName;
+}
 
-			// Set HP
-			const hpResult = setHpUseCase(makeStore(), id, entry.hp);
-			if (!isDomainError(hpResult)) {
-				setEvents((prev) => [...prev, ...hpResult]);
-			}
+function addOneFromBestiary(
+	store: EncounterStore,
+	entry: BestiaryIndexEntry,
+	nextId: number,
+): {
+	cId: CreatureId;
+	events: DomainEvent[];
+	nextId: number;
+} | null {
+	const newName = resolveAndRename(store, entry.name);
 
-			// Set AC
-			if (entry.ac > 0) {
-				const acResult = setAcUseCase(makeStore(), id, entry.ac);
-				if (!isDomainError(acResult)) {
-					setEvents((prev) => [...prev, ...acResult]);
-				}
-			}
-
-			// Derive creatureId from source + name
 	const slug = entry.name
 		.toLowerCase()
 		.replaceAll(/[^a-z0-9]+/g, "-")
 		.replaceAll(/(^-|-$)/g, "");
 	const cId = makeCreatureId(`${entry.source.toLowerCase()}:${slug}`);
 
-			// Set creatureId on the combatant (use store.save to keep ref in sync for batch calls)
-			const currentEncounter = store.get();
-			store.save({
-				...currentEncounter,
-				combatants: currentEncounter.combatants.map((c) =>
-					c.id === id ? { ...c, creatureId: cId } : c,
-				),
+	const id = combatantId(`c-${nextId + 1}`);
+	const result = addCombatantUseCase(store, id, newName, {
+		maxHp: entry.hp > 0 ? entry.hp : undefined,
+		ac: entry.ac > 0 ? entry.ac : undefined,
+		creatureId: cId,
 	});
 
-			setEvents((prev) => [...prev, ...addResult]);
+	if (isDomainError(result)) return null;
 
-			return cId;
+	return { cId, events: result, nextId: nextId + 1 };
+}
+
+// -- Reducer case handlers --
+
+function handleUndoRedo(
+	state: EncounterState,
+	direction: "undo" | "redo",
+): EncounterState {
+	const { store, getEncounter } = makeStoreFromState(state);
+	const undoRedoStore: UndoRedoStore = {
+		get: () => state.undoRedoState,
+		save: () => {},
+	};
+	const applyFn = direction === "undo" ? undoUseCase : redoUseCase;
+	const result = applyFn(store, undoRedoStore);
+	if (isDomainError(result)) return state;
+
+	const isUndo = direction === "undo";
+	return {
+		...state,
+		encounter: getEncounter(),
+		undoRedoState: {
+			undoStack: isUndo
+				? state.undoRedoState.undoStack.slice(0, -1)
+				: [...state.undoRedoState.undoStack, state.encounter],
+			redoStack: isUndo
+				? [...state.undoRedoState.redoStack, state.encounter]
+				: state.undoRedoState.redoStack.slice(0, -1),
 		},
-		[makeStore],
-	);
+	};
+}
 
-	const addFromPlayerCharacter = useCallback(
-		(pc: PlayerCharacter) => {
-			const store = makeStore();
-			const existingNames = store.get().combatants.map((c) => c.name);
-			const { newName, renames } = resolveCreatureName(pc.name, existingNames);
+function handleAddFromBestiary(
+	state: EncounterState,
+	entry: BestiaryIndexEntry,
+	count: number,
+): EncounterState {
+	const { store, getEncounter } = makeStoreFromState(state);
+	const allEvents: DomainEvent[] = [];
+	let nextId = state.nextId;
+	let lastCId: CreatureId | null = null;
 
-			for (const { from, to } of renames) {
-				const target = store.get().combatants.find((c) => c.name === from);
-				if (target) {
-					editCombatantUseCase(makeStore(), target.id, to);
-				}
+	for (let i = 0; i < count; i++) {
+		const added = addOneFromBestiary(store, entry, nextId);
+		if (!added) return state;
+		allEvents.push(...added.events);
+		nextId = added.nextId;
+		lastCId = added.cId;
 	}
 
-			const id = combatantId(`c-${++nextId.current}`);
-			const addResult = addCombatantUseCase(makeStore(), id, newName);
-			if (isDomainError(addResult)) return;
+	return {
+		...state,
+		encounter: getEncounter(),
+		undoRedoState: pushUndo(state.undoRedoState, state.encounter),
+		events: [...state.events, ...allEvents],
+		nextId,
+		lastCreatureId: lastCId,
+	};
+}
 
-			// 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,
+function handleAddFromPlayerCharacter(
+	state: EncounterState,
+	pc: PlayerCharacter,
+): EncounterState {
+	const { store, getEncounter } = makeStoreFromState(state);
+	const newName = resolveAndRename(store, pc.name);
+	const id = combatantId(`c-${state.nextId + 1}`);
+	const result = addCombatantUseCase(store, id, newName, {
+		maxHp: pc.maxHp,
+		ac: pc.ac > 0 ? pc.ac : undefined,
 		color: pc.color,
 		icon: pc.icon,
 		playerCharacterId: pc.id,
-							}
-						: c,
-				),
 	});
+	if (isDomainError(result)) return state;
+	return {
+		...state,
+		encounter: getEncounter(),
+		undoRedoState: pushUndo(state.undoRedoState, state.encounter),
+		events: [...state.events, ...result],
+		nextId: state.nextId + 1,
+		lastCreatureId: null,
+	};
+}
 
-			setEvents((prev) => [...prev, ...addResult]);
+// -- Reducer --
+
+export function encounterReducer(
+	state: EncounterState,
+	action: EncounterAction,
+): EncounterState {
+	switch (action.type) {
+		case "import":
+			return {
+				...state,
+				encounter: action.encounter,
+				undoRedoState: action.undoRedoState,
+				nextId: deriveNextId(action.encounter),
+				lastCreatureId: null,
+			};
+		case "undo":
+		case "redo":
+			return handleUndoRedo(state, action.type);
+		case "clear-encounter": {
+			const { store, getEncounter } = makeStoreFromState(state);
+			const result = clearEncounterUseCase(store);
+			if (isDomainError(result)) return state;
+			return {
+				...state,
+				encounter: getEncounter(),
+				undoRedoState: clearHistory(),
+				events: [...state.events, ...result],
+				nextId: 0,
+				lastCreatureId: null,
+			};
+		}
+		case "add-from-bestiary":
+			return handleAddFromBestiary(state, action.entry, 1);
+		case "add-multiple-from-bestiary":
+			return handleAddFromBestiary(state, action.entry, action.count);
+		case "add-from-player-character":
+			return handleAddFromPlayerCharacter(state, action.pc);
+		default:
+			return dispatchEncounterAction(state, action);
+	}
+}
+
+function dispatchEncounterAction(
+	state: EncounterState,
+	action: Extract<
+		EncounterAction,
+		| { type: "advance-turn" }
+		| { type: "retreat-turn" }
+		| { type: "add-combatant" }
+		| { type: "remove-combatant" }
+		| { type: "edit-combatant" }
+		| { type: "set-initiative" }
+		| { type: "set-hp" }
+		| { type: "adjust-hp" }
+		| { type: "set-temp-hp" }
+		| { type: "set-ac" }
+		| { type: "toggle-condition" }
+		| { type: "toggle-concentration" }
+	>,
+): EncounterState {
+	const { store, getEncounter } = makeStoreFromState(state);
+	let result: DomainEvent[] | DomainError;
+
+	switch (action.type) {
+		case "advance-turn":
+			result = advanceTurnUseCase(store);
+			break;
+		case "retreat-turn":
+			result = retreatTurnUseCase(store);
+			break;
+		case "add-combatant": {
+			const id = combatantId(`c-${state.nextId + 1}`);
+			result = addCombatantUseCase(store, id, action.name, action.init);
+			break;
+		}
+		case "remove-combatant":
+			result = removeCombatantUseCase(store, action.id);
+			break;
+		case "edit-combatant":
+			result = editCombatantUseCase(store, action.id, action.newName);
+			break;
+		case "set-initiative":
+			result = setInitiativeUseCase(store, action.id, action.value);
+			break;
+		case "set-hp":
+			result = setHpUseCase(store, action.id, action.maxHp);
+			break;
+		case "adjust-hp":
+			result = adjustHpUseCase(store, action.id, action.delta);
+			break;
+		case "set-temp-hp":
+			result = setTempHpUseCase(store, action.id, action.tempHp);
+			break;
+		case "set-ac":
+			result = setAcUseCase(store, action.id, action.value);
+			break;
+		case "toggle-condition":
+			result = toggleConditionUseCase(store, action.id, action.conditionId);
+			break;
+		case "toggle-concentration":
+			result = toggleConcentrationUseCase(store, action.id);
+			break;
+	}
+
+	if (isDomainError(result)) return state;
+
+	return {
+		...state,
+		encounter: getEncounter(),
+		undoRedoState: pushUndo(state.undoRedoState, state.encounter),
+		events: [...state.events, ...result],
+		nextId: action.type === "add-combatant" ? state.nextId + 1 : state.nextId,
+		lastCreatureId: null,
+	};
+}
+
+// -- Hook --
+
+export function useEncounter() {
+	const [state, dispatch] = useReducer(encounterReducer, null, initializeState);
+	const { encounter, undoRedoState, events } = state;
+
+	const encounterRef = useRef(encounter);
+	encounterRef.current = encounter;
+	const undoRedoRef = useRef(undoRedoState);
+	undoRedoRef.current = undoRedoState;
+
+	useEffect(() => {
+		saveEncounter(encounter);
+	}, [encounter]);
+
+	useEffect(() => {
+		saveUndoRedoStacks(undoRedoState);
+	}, [undoRedoState]);
+
+	// Escape hatches for useInitiativeRolls (needs raw port access)
+	const makeStore = useCallback((): EncounterStore => {
+		return {
+			get: () => encounterRef.current,
+			save: (e) => {
+				encounterRef.current = e;
+				dispatch({
+					type: "import",
+					encounter: e,
+					undoRedoState: undoRedoRef.current,
+				});
 			},
-		[makeStore],
-	);
+		};
+	}, []);
 
+	const withUndo = useCallback(<T>(action: () => T): T => {
+		const snapshot = encounterRef.current;
+		const result = action();
+		if (!isDomainError(result)) {
+			const newState = pushUndo(undoRedoRef.current, snapshot);
+			undoRedoRef.current = newState;
+			dispatch({
+				type: "import",
+				encounter: encounterRef.current,
+				undoRedoState: newState,
+			});
+		}
+		return result;
+	}, []);
+
+	// Derived state
+	const canUndo = undoRedoState.undoStack.length > 0;
+	const canRedo = undoRedoState.redoStack.length > 0;
 	const hasTempHp = encounter.combatants.some(
 		(c) => c.tempHp !== undefined && c.tempHp > 0,
 	);
-
 	const isEmpty = encounter.combatants.length === 0;
 	const hasCreatureCombatants = encounter.combatants.some(
 		(c) => c.creatureId != null,
@@ -404,26 +447,113 @@ export function useEncounter() {
 
 	return {
 		encounter,
+		undoRedoState,
 		events,
 		isEmpty,
 		hasTempHp,
 		hasCreatureCombatants,
 		canRollAllInitiative,
-		advanceTurn,
-		retreatTurn,
-		addCombatant,
-		clearEncounter,
-		removeCombatant,
-		editCombatant,
-		setInitiative,
-		setHp,
-		adjustHp,
-		setTempHp,
-		setAc,
-		toggleCondition,
-		toggleConcentration,
-		addFromBestiary,
-		addFromPlayerCharacter,
+		canUndo,
+		canRedo,
+		advanceTurn: useCallback(() => dispatch({ type: "advance-turn" }), []),
+		retreatTurn: useCallback(() => dispatch({ type: "retreat-turn" }), []),
+		addCombatant: useCallback(
+			(name: string, init?: CombatantInit) =>
+				dispatch({ type: "add-combatant", name, init }),
+			[],
+		),
+		removeCombatant: useCallback(
+			(id: CombatantId) => dispatch({ type: "remove-combatant", id }),
+			[],
+		),
+		editCombatant: useCallback(
+			(id: CombatantId, newName: string) =>
+				dispatch({ type: "edit-combatant", id, newName }),
+			[],
+		),
+		setInitiative: useCallback(
+			(id: CombatantId, value: number | undefined) =>
+				dispatch({ type: "set-initiative", id, value }),
+			[],
+		),
+		setHp: useCallback(
+			(id: CombatantId, maxHp: number | undefined) =>
+				dispatch({ type: "set-hp", id, maxHp }),
+			[],
+		),
+		adjustHp: useCallback(
+			(id: CombatantId, delta: number) =>
+				dispatch({ type: "adjust-hp", id, delta }),
+			[],
+		),
+		setTempHp: useCallback(
+			(id: CombatantId, tempHp: number | undefined) =>
+				dispatch({ type: "set-temp-hp", id, tempHp }),
+			[],
+		),
+		setAc: useCallback(
+			(id: CombatantId, value: number | undefined) =>
+				dispatch({ type: "set-ac", id, value }),
+			[],
+		),
+		toggleCondition: useCallback(
+			(id: CombatantId, conditionId: ConditionId) =>
+				dispatch({ type: "toggle-condition", id, conditionId }),
+			[],
+		),
+		toggleConcentration: useCallback(
+			(id: CombatantId) => dispatch({ type: "toggle-concentration", id }),
+			[],
+		),
+		clearEncounter: useCallback(
+			() => dispatch({ type: "clear-encounter" }),
+			[],
+		),
+		addFromBestiary: useCallback(
+			(entry: BestiaryIndexEntry): CreatureId | null => {
+				dispatch({ type: "add-from-bestiary", entry });
+				return null;
+			},
+			[],
+		),
+		addMultipleFromBestiary: useCallback(
+			(entry: BestiaryIndexEntry, count: number): CreatureId | null => {
+				dispatch({
+					type: "add-multiple-from-bestiary",
+					entry,
+					count,
+				});
+				return null;
+			},
+			[],
+		),
+		addFromPlayerCharacter: useCallback(
+			(pc: PlayerCharacter) =>
+				dispatch({ type: "add-from-player-character", pc }),
+			[],
+		),
+		undo: useCallback(() => dispatch({ type: "undo" }), []),
+		redo: useCallback(() => dispatch({ type: "redo" }), []),
+		setEncounter: useCallback(
+			(enc: Encounter) =>
+				dispatch({
+					type: "import",
+					encounter: enc,
+					undoRedoState: undoRedoRef.current,
+				}),
+			[],
+		),
+		setUndoRedoState: useCallback(
+			(urs: UndoRedoState) =>
+				dispatch({
+					type: "import",
+					encounter: encounterRef.current,
+					undoRedoState: urs,
+				}),
+			[],
+		),
 		makeStore,
+		withUndo,
+		lastCreatureId: state.lastCreatureId,
 	} as const;
 }

apps/web/src/hooks/use-initiative-rolls.ts

@@ -17,7 +17,7 @@ function rollDice(): number {
 }
 
 export function useInitiativeRolls() {
-	const { encounter, makeStore } = useEncounterContext();
+	const { encounter, makeStore, withUndo } = useEncounterContext();
 	const { getCreature } = useBestiaryContext();
 	const { showCreature } = useSidePanelContext();
 
@@ -28,12 +28,8 @@ export function useInitiativeRolls() {
 		(id: CombatantId, mode: RollMode = "normal") => {
 			const diceRolls: [number, ...number[]] =
 				mode === "normal" ? [rollDice()] : [rollDice(), rollDice()];
-			const result = rollInitiativeUseCase(
-				makeStore(),
-				id,
-				diceRolls,
-				getCreature,
-				mode,
+			const result = withUndo(() =>
+				rollInitiativeUseCase(makeStore(), id, diceRolls, getCreature, mode),
 			);
 			if (isDomainError(result)) {
 				setRollSingleSkipped(true);
@@ -43,22 +39,19 @@ export function useInitiativeRolls() {
 				}
 			}
 		},
-		[makeStore, getCreature, encounter.combatants, showCreature],
+		[makeStore, getCreature, withUndo, encounter.combatants, showCreature],
 	);
 
 	const handleRollAllInitiative = useCallback(
 		(mode: RollMode = "normal") => {
-			const result = rollAllInitiativeUseCase(
-				makeStore(),
-				rollDice,
-				getCreature,
-				mode,
+			const result = withUndo(() =>
+				rollAllInitiativeUseCase(makeStore(), rollDice, getCreature, mode),
 			);
 			if (!isDomainError(result) && result.skippedNoSource > 0) {
 				setRollSkippedCount(result.skippedNoSource);
 			}
 		},
-		[makeStore, getCreature],
+		[makeStore, getCreature, withUndo],
 	);
 
 	return {

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

@@ -28,6 +28,7 @@ interface EditFields {
 	readonly maxHp?: number;
 	readonly color?: string | null;
 	readonly icon?: string | null;
+	readonly level?: number | null;
 }
 
 export function usePlayerCharacters() {
@@ -57,6 +58,7 @@ export function usePlayerCharacters() {
 			maxHp: number,
 			color: string | undefined,
 			icon: string | undefined,
+			level: number | undefined,
 		) => {
 			const id = generatePcId();
 			const result = createPlayerCharacterUseCase(
@@ -67,6 +69,7 @@ export function usePlayerCharacters() {
 				maxHp,
 				color,
 				icon,
+				level,
 			);
 			if (isDomainError(result)) {
 				return result;
@@ -103,6 +106,7 @@ export function usePlayerCharacters() {
 		createCharacter,
 		editCharacter,
 		deleteCharacter,
+		replacePlayerCharacters: setCharacters,
 		makeStore,
 	} as const;
 }

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

@@ -39,6 +39,9 @@ function resolve(pref: ThemePreference): ResolvedTheme {
 
 function applyTheme(resolved: ResolvedTheme): void {
 	document.documentElement.dataset.theme = resolved;
+	document
+		.querySelector('meta[name="theme-color"]')
+		?.setAttribute("content", resolved === "light" ? "#eeecea" : "#0e1a2e");
 }
 
 function notifyAll(): void {

apps/web/src/hooks/use-undo-redo-shortcuts.ts

@@ -0,0 +1,42 @@
+import { useEffect } from "react";
+
+const SUPPRESSED_TAGS = new Set(["INPUT", "TEXTAREA", "SELECT"]);
+
+function isTextInputFocused(): boolean {
+	const active = document.activeElement;
+	if (!active) return false;
+	if (SUPPRESSED_TAGS.has(active.tagName)) return true;
+	return active instanceof HTMLElement && active.isContentEditable;
+}
+
+function isUndoShortcut(e: KeyboardEvent): boolean {
+	return (e.ctrlKey || e.metaKey) && e.key.toLowerCase() === "z" && !e.shiftKey;
+}
+
+function isRedoShortcut(e: KeyboardEvent): boolean {
+	return (e.ctrlKey || e.metaKey) && e.key.toLowerCase() === "z" && e.shiftKey;
+}
+
+export function useUndoRedoShortcuts(
+	undo: () => void,
+	redo: () => void,
+	canUndo: boolean,
+	canRedo: boolean,
+): void {
+	useEffect(() => {
+		function handleKeyDown(e: KeyboardEvent) {
+			if (isTextInputFocused()) return;
+
+			if (isUndoShortcut(e) && canUndo) {
+				e.preventDefault();
+				undo();
+			} else if (isRedoShortcut(e) && canRedo) {
+				e.preventDefault();
+				redo();
+			}
+		}
+
+		document.addEventListener("keydown", handleKeyDown);
+		return () => document.removeEventListener("keydown", handleKeyDown);
+	}, [undo, redo, canUndo, canRedo]);
+}

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

@@ -122,64 +122,7 @@ describe("loadEncounter", () => {
 		expect(loadEncounter()).toBeNull();
 	});
 
-	// US3: Corrupt data scenarios
-	it("returns null for non-object JSON (string)", () => {
-		localStorage.setItem(STORAGE_KEY, JSON.stringify("hello"));
-		expect(loadEncounter()).toBeNull();
-	});
-
-	it("returns null for non-object JSON (number)", () => {
-		localStorage.setItem(STORAGE_KEY, JSON.stringify(42));
-		expect(loadEncounter()).toBeNull();
-	});
-
-	it("returns null for non-object JSON (array)", () => {
-		localStorage.setItem(STORAGE_KEY, JSON.stringify([1, 2, 3]));
-		expect(loadEncounter()).toBeNull();
-	});
-
-	it("returns null for non-object JSON (null)", () => {
-		localStorage.setItem(STORAGE_KEY, "null");
-		expect(loadEncounter()).toBeNull();
-	});
-
-	it("returns null when combatants is a string instead of array", () => {
-		localStorage.setItem(
-			STORAGE_KEY,
-			JSON.stringify({
-				combatants: "not-array",
-				activeIndex: 0,
-				roundNumber: 1,
-			}),
-		);
-		expect(loadEncounter()).toBeNull();
-	});
-
-	it("returns null when activeIndex is a string instead of number", () => {
-		localStorage.setItem(
-			STORAGE_KEY,
-			JSON.stringify({
-				combatants: [{ id: "1", name: "Aria" }],
-				activeIndex: "zero",
-				roundNumber: 1,
-			}),
-		);
-		expect(loadEncounter()).toBeNull();
-	});
-
-	it("returns null when combatant entry is missing id", () => {
-		localStorage.setItem(
-			STORAGE_KEY,
-			JSON.stringify({
-				combatants: [{ name: "Aria" }],
-				activeIndex: 0,
-				roundNumber: 1,
-			}),
-		);
-		expect(loadEncounter()).toBeNull();
-	});
-
-	it("returns null when combatant entry is missing name", () => {
+	it("returns null when combatant has invalid required fields", () => {
 		localStorage.setItem(
 			STORAGE_KEY,
 			JSON.stringify({
@@ -191,88 +134,6 @@ describe("loadEncounter", () => {
 		expect(loadEncounter()).toBeNull();
 	});
 
-	it("returns null for negative roundNumber", () => {
-		localStorage.setItem(
-			STORAGE_KEY,
-			JSON.stringify({
-				combatants: [{ id: "1", name: "Aria" }],
-				activeIndex: 0,
-				roundNumber: -1,
-			}),
-		);
-		expect(loadEncounter()).toBeNull();
-	});
-
-	it("returns empty encounter for zero combatants (cleared state)", () => {
-		localStorage.setItem(
-			STORAGE_KEY,
-			JSON.stringify({ combatants: [], activeIndex: 0, roundNumber: 1 }),
-		);
-		const result = loadEncounter();
-		expect(result).toEqual({
-			combatants: [],
-			activeIndex: 0,
-			roundNumber: 1,
-		});
-	});
-
-	it("round-trip preserves combatant AC value", () => {
-		const result = createEncounter(
-			[{ id: combatantId("1"), name: "Aria", ac: 18 }],
-			0,
-			1,
-		);
-		if (isDomainError(result)) throw new Error("unreachable");
-		saveEncounter(result);
-		const loaded = loadEncounter();
-		expect(loaded?.combatants[0].ac).toBe(18);
-	});
-
-	it("round-trip preserves combatant without AC", () => {
-		const result = createEncounter(
-			[{ id: combatantId("1"), name: "Aria" }],
-			0,
-			1,
-		);
-		if (isDomainError(result)) throw new Error("unreachable");
-		saveEncounter(result);
-		const loaded = loadEncounter();
-		expect(loaded?.combatants[0].ac).toBeUndefined();
-	});
-
-	it("discards invalid AC values during rehydration", () => {
-		localStorage.setItem(
-			STORAGE_KEY,
-			JSON.stringify({
-				combatants: [
-					{ id: "1", name: "Neg", ac: -1 },
-					{ id: "2", name: "Float", ac: 3.5 },
-					{ id: "3", name: "Str", ac: "high" },
-				],
-				activeIndex: 0,
-				roundNumber: 1,
-			}),
-		);
-		const loaded = loadEncounter();
-		expect(loaded).not.toBeNull();
-		expect(loaded?.combatants[0].ac).toBeUndefined();
-		expect(loaded?.combatants[1].ac).toBeUndefined();
-		expect(loaded?.combatants[2].ac).toBeUndefined();
-	});
-
-	it("preserves AC of 0 during rehydration", () => {
-		localStorage.setItem(
-			STORAGE_KEY,
-			JSON.stringify({
-				combatants: [{ id: "1", name: "Aria", ac: 0 }],
-				activeIndex: 0,
-				roundNumber: 1,
-			}),
-		);
-		const loaded = loadEncounter();
-		expect(loaded?.combatants[0].ac).toBe(0);
-	});
-
 	it("saving after modifications persists the latest state", () => {
 		const encounter = makeEncounter();
 		saveEncounter(encounter);

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

@@ -90,102 +90,7 @@ describe("player-character-storage", () => {
 		});
 	});
 
-	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([]);
-		});
-
+	describe("delegation to domain rehydration", () => {
 		it("keeps valid characters and discards invalid ones", () => {
 			mockStorage.setItem(
 				STORAGE_KEY,

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

@@ -1,14 +1,9 @@
 import {
-	type ConditionId,
-	combatantId,
+	type Combatant,
 	createEncounter,
-	creatureId,
 	type Encounter,
 	isDomainError,
-	playerCharacterId,
-	VALID_CONDITION_IDS,
-	VALID_PLAYER_COLORS,
-	VALID_PLAYER_ICONS,
+	rehydrateCombatant,
 } from "@initiative/domain";
 
 const STORAGE_KEY = "initiative:encounter";
@@ -21,100 +16,7 @@ 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);
-		if (raw === null) return null;
-
-		const parsed: unknown = JSON.parse(raw);
-
+export function rehydrateEncounter(parsed: unknown): Encounter | null {
 	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
 		return null;
 
@@ -135,18 +37,30 @@ export function loadEncounter(): Encounter | null {
 		};
 	}
 
-		if (!combatants.every(isValidCombatantEntry)) return null;
+	const rehydrated: Combatant[] = [];
+	for (const c of combatants) {
+		const result = rehydrateCombatant(c);
+		if (result === null) return null;
+		rehydrated.push(result);
+	}
 
-		const rehydrated = combatants.map(rehydrateCombatant);
-
-		const result = createEncounter(
+	const encounter = createEncounter(
 		rehydrated,
 		obj.activeIndex,
 		obj.roundNumber,
 	);
-		if (isDomainError(result)) return null;
+	if (isDomainError(encounter)) return null;
 
-		return result;
+	return encounter;
+}
+
+export function loadEncounter(): Encounter | null {
+	try {
+		const raw = localStorage.getItem(STORAGE_KEY);
+		if (raw === null) return null;
+
+		const parsed: unknown = JSON.parse(raw);
+		return rehydrateEncounter(parsed);
 	} catch {
 		return null;
 	}

apps/web/src/persistence/export-import.ts

@@ -0,0 +1,118 @@
+import type {
+	Encounter,
+	ExportBundle,
+	PlayerCharacter,
+	UndoRedoState,
+} from "@initiative/domain";
+import { rehydratePlayerCharacter } from "@initiative/domain";
+import { rehydrateEncounter } from "./encounter-storage.js";
+
+function rehydrateStack(raw: unknown[]): Encounter[] {
+	const result: Encounter[] = [];
+	for (const entry of raw) {
+		const rehydrated = rehydrateEncounter(entry);
+		if (rehydrated !== null) {
+			result.push(rehydrated);
+		}
+	}
+	return result;
+}
+
+function rehydrateCharacters(raw: unknown[]): PlayerCharacter[] {
+	const result: PlayerCharacter[] = [];
+	for (const entry of raw) {
+		const rehydrated = rehydratePlayerCharacter(entry);
+		if (rehydrated !== null) {
+			result.push(rehydrated);
+		}
+	}
+	return result;
+}
+
+export function validateImportBundle(data: unknown): ExportBundle | string {
+	if (typeof data !== "object" || data === null || Array.isArray(data)) {
+		return "Invalid file format";
+	}
+
+	const obj = data as Record<string, unknown>;
+
+	if (typeof obj.version !== "number" || obj.version !== 1) {
+		return "Invalid file format";
+	}
+	if (typeof obj.exportedAt !== "string") {
+		return "Invalid file format";
+	}
+	if (!Array.isArray(obj.undoStack) || !Array.isArray(obj.redoStack)) {
+		return "Invalid file format";
+	}
+	if (!Array.isArray(obj.playerCharacters)) {
+		return "Invalid file format";
+	}
+
+	const encounter = rehydrateEncounter(obj.encounter);
+	if (encounter === null) {
+		return "Invalid encounter data";
+	}
+
+	return {
+		version: 1,
+		exportedAt: obj.exportedAt,
+		encounter,
+		undoStack: rehydrateStack(obj.undoStack),
+		redoStack: rehydrateStack(obj.redoStack),
+		playerCharacters: rehydrateCharacters(obj.playerCharacters),
+	};
+}
+
+export function assembleExportBundle(
+	encounter: Encounter,
+	undoRedoState: UndoRedoState,
+	playerCharacters: readonly PlayerCharacter[],
+	includeHistory = true,
+): ExportBundle {
+	return {
+		version: 1,
+		exportedAt: new Date().toISOString(),
+		encounter,
+		undoStack: includeHistory ? undoRedoState.undoStack : [],
+		redoStack: includeHistory ? undoRedoState.redoStack : [],
+		playerCharacters: [...playerCharacters],
+	};
+}
+
+export function bundleToJson(bundle: ExportBundle): string {
+	return JSON.stringify(bundle, null, 2);
+}
+
+export function resolveFilename(name?: string): string {
+	const base =
+		name?.trim() ||
+		`initiative-export-${new Date().toISOString().slice(0, 10)}`;
+	return base.endsWith(".json") ? base : `${base}.json`;
+}
+
+export function triggerDownload(bundle: ExportBundle, name?: string): void {
+	const blob = new Blob([bundleToJson(bundle)], { type: "application/json" });
+	const url = URL.createObjectURL(blob);
+
+	const filename = resolveFilename(name);
+
+	const anchor = document.createElement("a");
+	anchor.href = url;
+	anchor.download = filename;
+	anchor.click();
+
+	URL.revokeObjectURL(url);
+}
+
+export async function readImportFile(
+	file: File,
+): Promise<ExportBundle | string> {
+	try {
+		const text = await file.text();
+		const parsed: unknown = JSON.parse(text);
+		return validateImportBundle(parsed);
+	} catch {
+		return "Invalid file format";
+	}
+}

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

@@ -1,9 +1,5 @@
 import type { PlayerCharacter } from "@initiative/domain";
-import {
-	playerCharacterId,
-	VALID_PLAYER_COLORS,
-	VALID_PLAYER_ICONS,
-} from "@initiative/domain";
+import { rehydratePlayerCharacter } from "@initiative/domain";
 
 const STORAGE_KEY = "initiative:player-characters";
 
@@ -15,46 +11,6 @@ export function savePlayerCharacters(characters: PlayerCharacter[]): void {
 	}
 }
 
-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);
@@ -65,7 +21,7 @@ export function loadPlayerCharacters(): PlayerCharacter[] {
 
 		const characters: PlayerCharacter[] = [];
 		for (const item of parsed) {
-			const pc = rehydrateCharacter(item);
+			const pc = rehydratePlayerCharacter(item);
 			if (pc !== null) {
 				characters.push(pc);
 			}

apps/web/src/persistence/undo-redo-storage.ts

@@ -0,0 +1,45 @@
+import type { Encounter, UndoRedoState } from "@initiative/domain";
+import { EMPTY_UNDO_REDO_STATE } from "@initiative/domain";
+import { rehydrateEncounter } from "./encounter-storage.js";
+
+const UNDO_KEY = "initiative:encounter:undo";
+const REDO_KEY = "initiative:encounter:redo";
+
+export function saveUndoRedoStacks(state: UndoRedoState): void {
+	try {
+		localStorage.setItem(UNDO_KEY, JSON.stringify(state.undoStack));
+		localStorage.setItem(REDO_KEY, JSON.stringify(state.redoStack));
+	} catch {
+		// Silently swallow errors (quota exceeded, storage unavailable)
+	}
+}
+
+function loadStack(key: string): readonly Encounter[] {
+	try {
+		const raw = localStorage.getItem(key);
+		if (raw === null) return [];
+
+		const parsed: unknown = JSON.parse(raw);
+		if (!Array.isArray(parsed)) return [];
+
+		const valid: Encounter[] = [];
+		for (const entry of parsed) {
+			const rehydrated = rehydrateEncounter(entry);
+			if (rehydrated !== null) {
+				valid.push(rehydrated);
+			}
+		}
+		return valid;
+	} catch {
+		return [];
+	}
+}
+
+export function loadUndoRedoStacks(): UndoRedoState {
+	const undoStack = loadStack(UNDO_KEY);
+	const redoStack = loadStack(REDO_KEY);
+	if (undoStack.length === 0 && redoStack.length === 0) {
+		return EMPTY_UNDO_REDO_STATE;
+	}
+	return { undoStack, redoStack };
+}

biome.json

@@ -8,7 +8,9 @@
 			"!.specify",
 			"!specs",
 			"!coverage",
-			"!.pnpm-store"
+			"!.pnpm-store",
+			"!.rodney",
+			"!.agent-tests"
 		]
 	},
 	"assist": {

docs/adr/000-template.md

@@ -0,0 +1,20 @@
+# ADR-NNN: [Title]
+
+**Date**: YYYY-MM-DD
+**Status**: accepted | superseded | deprecated
+
+## Context
+
+What is the problem or situation that motivates this decision?
+
+## Decision
+
+What did we decide, and why?
+
+## Alternatives Considered
+
+What other approaches were evaluated?
+
+## Consequences
+
+What are the trade-offs — both positive and negative?

docs/adr/001-errors-as-values.md

@@ -0,0 +1,45 @@
+# ADR-001: Errors as Values, Not Exceptions
+
+**Date**: 2026-03-25
+**Status**: accepted
+
+## Context
+
+Domain functions need to communicate failure (invalid input, missing combatant, violated invariants). The standard JavaScript approach is to throw exceptions, but thrown exceptions are invisible to TypeScript's type system — nothing in a function's signature tells the caller that it can fail or what errors to expect.
+
+This project's domain layer is designed to be pure and deterministic. Thrown exceptions break both properties: they alter control flow (a side effect) and make the function's output unpredictable from the caller's perspective.
+
+## Decision
+
+All domain functions return `SuccessType | DomainError` unions. `DomainError` is a plain data object with a `kind` discriminant, a machine-readable `code`, and a human-readable `message`:
+
+```typescript
+interface DomainError {
+  readonly kind: "domain-error";
+  readonly code: string;
+  readonly message: string;
+}
+```
+
+Callers check results with the `isDomainError()` type guard before accessing success data. Errors are never thrown in the domain layer (adapter-layer code may throw for programmer errors like missing providers).
+
+## Alternatives Considered
+
+**Thrown exceptions** — the JavaScript default. Simpler to write (`throw new Error(...)`) but error paths are invisible to the type system. The caller has no compile-time indication that a function can fail, and `catch` blocks lose type information about which errors are possible. Would also make domain functions impure.
+
+**Result wrapper types** (e.g., `neverthrow`, `ts-results`) — formalizes the pattern with `.map()`, `.unwrap()`, `.match()` methods. More ergonomic for chaining operations, but adds a library dependency and a layer of indirection. The project's use cases are simple enough (call domain function, check error, save or return) that raw unions are sufficient.
+
+**Validation libraries** (Zod, io-ts) — useful for input parsing but don't cover domain logic errors like "combatant not found" or "no previous turn". Would only address a subset of the problem.
+
+## Consequences
+
+**Positive:**
+- Error handling is compiler-enforced. Forgetting to check for an error produces a type error when accessing success fields.
+- Domain functions remain pure — they return data, never alter control flow.
+- Error codes are stable, machine-readable identifiers that UI code can match on.
+- Testing is straightforward: assert the return value, no try/catch in tests.
+
+**Negative:**
+- Every call site must check `isDomainError()` before proceeding. This is slightly more verbose than a try/catch that wraps multiple calls.
+- Composing multiple fallible operations requires manual chaining (check error, then call next function). A Result wrapper would make this more ergonomic if the codebase grows significantly.
+- Contributors familiar with JavaScript conventions may initially find the pattern unfamiliar.

docs/adr/002-domain-events-as-plain-data.md

@@ -0,0 +1,46 @@
+# ADR-002: Domain Events as Plain Data Objects
+
+**Date**: 2026-03-25
+**Status**: accepted
+
+## Context
+
+Domain state transitions need to communicate what happened (not just the new state) so the UI layer can react — showing toasts, auto-scrolling, opening panels, etc. The project needs an event mechanism that stays consistent with the pure, deterministic domain core.
+
+## Decision
+
+Domain events are plain data objects with a `type` string discriminant. They form a discriminated union (`DomainEvent`) of 18 event types. Events are returned alongside the new state from domain functions, not emitted through a pub/sub system:
+
+```typescript
+// Example event
+{ type: "TurnAdvanced", previousCombatantId: "abc", newCombatantId: "def", roundNumber: 2 }
+
+// Domain function returns both state and events
+function advanceTurn(encounter: Encounter): { encounter: Encounter; events: DomainEvent[] } | DomainError
+```
+
+Events are consumed ephemerally by the UI layer and are not persisted.
+
+## Alternatives Considered
+
+**Class-based events** (e.g., `class TurnAdvanced extends DomainEvent { ... }`) — common in OOP-style domain-driven design. Adds inheritance hierarchies, constructors, and `instanceof` checks. No benefit here: TypeScript's discriminated union narrowing (`switch (event.type)`) provides the same exhaustiveness checking without classes. Classes also can't be serialized/deserialized without custom logic.
+
+**Event emitter / pub-sub** (Node `EventEmitter`, custom bus, RxJS) — events are broadcast and listeners subscribe. Decouples producers from consumers, but introduces implicit coupling (who's listening?), ordering concerns, and makes the domain impure (emitting is a side effect). Harder to test — you'd need to set up listeners and collect results instead of just asserting on a return value.
+
+**Observable streams** (RxJS) — powerful for async event processing and composition. Massive overkill for this use case: events are synchronous, produced one batch at a time, and consumed immediately. Would add a significant dependency and conceptual overhead.
+
+**No events** (just compare old and new state) — the UI could diff states to determine what changed. Works for simple cases, but can't express intent (did HP drop because of damage or because max HP was lowered?) and gets unwieldy as the state model grows.
+
+## Consequences
+
+**Positive:**
+- Events are serializable (JSON-compatible). If the project ever adds undo/redo or event logging, no changes to the event format are needed.
+- TypeScript's `switch (event.type)` provides exhaustiveness checking — the compiler warns if a new event type is added but not handled.
+- No framework coupling. Events are just data; any consumer (React, a test, a CLI) can process them identically.
+- Domain functions remain pure — events are returned, not emitted.
+- Testing is trivial: assert that `result.events` contains the expected objects.
+
+**Negative:**
+- Events are currently consumed and discarded. There is no event log, replay, or undo capability. The architecture supports it, but it's not built.
+- Adding a new event type requires updating the `DomainEvent` union, which touches a central file. This is intentional (forces explicit acknowledgment) but adds friction.
+- No built-in mechanism for event handlers to communicate back (e.g., "veto this event"). Events are informational, not transactional.

docs/adr/003-branded-types-for-identity.md

@@ -0,0 +1,53 @@
+# ADR-003: Branded Types for Identity Safety
+
+**Date**: 2026-03-25
+**Status**: accepted
+
+## Context
+
+The domain model has multiple entity types with string-based identifiers: combatants, creatures, and player characters. All IDs are strings at runtime (UUIDs or slug-based), making it easy to accidentally pass one ID type where another is expected. Such bugs are silent — the code compiles, runs, and only fails at runtime when a lookup returns `undefined` or mutates the wrong entity.
+
+TypeScript's structural type system treats all `string` values as interchangeable, so a plain `string` type alias provides no protection.
+
+## Decision
+
+Identity types use TypeScript branded types — a `string` intersected with a phantom `readonly __brand` property that exists only at the type level:
+
+```typescript
+type CombatantId = string & { readonly __brand: "CombatantId" };
+type CreatureId = string & { readonly __brand: "CreatureId" };
+type PlayerCharacterId = string & { readonly __brand: "PlayerCharacterId" };
+```
+
+Each type has a factory function that casts a plain string into the branded type:
+
+```typescript
+function combatantId(id: string): CombatantId {
+  return id as CombatantId;
+}
+```
+
+The `__brand` property is never assigned at runtime — it's a compile-time-only construct. The cast in the factory is the single point where the type system is "convinced" that the string carries the brand.
+
+## Alternatives Considered
+
+**Plain `string` type aliases** (`type CombatantId = string`) — provides documentation value but zero type safety. TypeScript treats the alias as fully interchangeable with `string` and with all other string aliases. This is what most TypeScript codebases do, accepting the risk of ID confusion.
+
+**Opaque types via unique symbols** (`declare const brand: unique symbol; type CombatantId = string & { [brand]: void }`) — stricter than the `__brand` approach because the symbol is truly unique and unexportable. Slightly more boilerplate and harder to read. The simpler `__brand` string approach provides sufficient safety for this codebase's scale.
+
+**Wrapper classes** (`class CombatantId { constructor(public readonly value: string) {} }`) — provides nominal typing naturally, but introduces runtime overhead (object allocation, `.value` access everywhere), breaks JSON serialization, and doesn't play well with the project's preference for plain data over classes.
+
+**Runtime validation** (check ID format at every function boundary) — catches errors at runtime but not at compile time. Adds overhead and doesn't prevent the bug from being written in the first place.
+
+## Consequences
+
+**Positive:**
+- Passing a `CreatureId` where a `CombatantId` is expected produces a compile-time error — the bug is caught before the code runs.
+- Zero runtime cost. The brand is erased during compilation; at runtime, IDs are plain strings.
+- JSON serialization works naturally — no custom serializers needed for persistence or network transport.
+- Factory functions (`combatantId()`, `creatureId()`) serve as explicit construction points, making it clear where IDs originate.
+
+**Negative:**
+- The `as CombatantId` cast in factory functions is an escape hatch from the type system. If misused (casting arbitrary strings elsewhere), the safety guarantee is undermined. In practice, casts are confined to factory functions and adapter-layer deserialization.
+- The `__brand` property appears in IDE autocomplete and hover tooltips, which can be confusing for developers unfamiliar with the pattern.
+- Branded types are a community convention, not a TypeScript language feature. There is no official syntax or standard library support.

docs/adr/004-on-demand-bestiary-loading.md

@@ -0,0 +1,42 @@
+# ADR-004: On-Demand Bestiary Loading via Compact Index and IndexedDB Cache
+
+**Date**: 2026-03-25
+**Status**: accepted
+
+## Context
+
+The application integrates a D&D creature bestiary containing 3,300+ creatures from the 5etools dataset. The full bestiary data (stat blocks, traits, actions, spellcasting) is several megabytes of JSON. Bundling it directly into the application would create two problems: a large initial download for every user, and the distribution of copyrighted game content as part of the application bundle.
+
+## Decision
+
+The bestiary is split into two tiers:
+
+1. **Compact search index** (`data/bestiary/index.json`, ~350KB) — shipped with the application bundle. Contains only the fields needed for search and display in the autocomplete dropdown: name, source, AC, HP, DEX, CR, initiative proficiency, size, and type. Field names are abbreviated (`n`, `s`, `ac`, `hp`, `dx`, `cr`, `ip`, `sz`, `tp`) to minimize file size. Generated offline by `scripts/generate-bestiary-index.mjs` from a local clone of the 5etools repository.
+
+2. **On-demand source data** — full creature stat blocks are fetched per-source when a user first needs them (e.g., when viewing a stat block or adding a creature with HP/AC pre-fill). Fetched data is cached in IndexedDB (`initiative-bestiary` database) via the `idb` library, with an in-memory Map fallback when IndexedDB is unavailable. Users can also upload source files directly or bulk-import all sources.
+
+The application never bundles or redistributes the full creature data. Users fetch it themselves from their own configured source URLs.
+
+## Alternatives Considered
+
+**Bundle all bestiary data** — simplest approach, used during early development. Eliminated because it would distribute copyrighted content in the application bundle and inflate the initial download by several megabytes. Most users only need a fraction of the available sources.
+
+**Server-side API** — a backend service could serve creature data on demand. This would keep the client lightweight and solve the bundle size concern, but the copyright issue remains — we would still be distributing copyrighted content, just from a server instead of a bundle. It also contradicts the project's local-first, single-user, no-backend architecture and would require hosting infrastructure and a network dependency for basic functionality.
+
+**Service Worker with lazy caching** — fetch and cache bestiary data transparently via a Service Worker. More complex to implement and debug than explicit IndexedDB caching. The explicit approach gives users visibility and control over which sources are cached (via the source manager UI).
+
+**localStorage for caching** — simpler API than IndexedDB, but localStorage has a ~5MB limit per origin, which is insufficient for multiple bestiary sources. IndexedDB has no practical storage limit.
+
+## Consequences
+
+**Positive:**
+- The application does not distribute copyrighted game content. Users fetch data from their own sources.
+- Initial bundle stays small (~350KB for the search index). The full bestiary data is only downloaded when needed and then cached locally.
+- Offline capability: once sources are cached in IndexedDB, creature data is available without network access.
+- Users have explicit control over cached sources (import, clear, manage via UI).
+
+**Negative:**
+- First-time use requires fetching source data before full stat blocks are available. The bulk import feature mitigates this but requires an initial download.
+- The search index must be regenerated manually when the upstream 5etools dataset changes. In practice this is infrequent (new D&D source books release a few times per year), so a manual process triggered by a new book release is sufficient at this scale.
+- Two separate data representations (compact index vs full source) must be kept conceptually in sync. A creature that appears in the index but whose source hasn't been fetched will show limited information until the source is cached.
+- IndexedDB adds adapter complexity (async API, database versioning, migration handling) compared to the synchronous localStorage used for encounter persistence.

docs/adr/005-all-quality-gates-at-pre-commit.md

@@ -0,0 +1,58 @@
+# ADR-005: All Quality Gates at Pre-Commit
+
+**Date**: 2026-03-25
+**Status**: accepted
+
+## Context
+
+This project is developed primarily through agentic coding — AI coding agents generate and modify code under human supervision. Agents are highly productive but can drift from established conventions, introduce subtle style inconsistencies, or produce code that compiles but doesn't meet the project's quality standards.
+
+The conventional approach in most software projects is to keep pre-commit hooks lightweight (formatting, maybe linting) and defer heavier checks (tests, type checking, coverage, copy-paste detection) to CI pipelines. This optimizes for developer speed at commit time.
+
+However, when working with AI agents, the dynamics are different. Agents iterate quickly and can fix issues immediately — but only if they receive feedback immediately. A failing CI pipeline minutes later breaks the feedback loop: the agent's context has moved on, and the human must re-engage to address the failure.
+
+## Decision
+
+All quality gates run at pre-commit via Lefthook, as a single sequential `pnpm check` command. No gate may exist only as a CI step or as a manual process. The full gate sequence is:
+
+1. `pnpm audit --audit-level=high` — security vulnerability scan
+2. `knip` — unused code detection
+3. `biome check .` — linting and formatting (50+ rules)
+4. `oxlint --tsconfig ... --type-aware` — type-aware linting
+5. `check-lint-ignores.mjs` — caps biome-ignore directives
+6. `check-cn-classnames.mjs` — bans template-literal classNames
+7. `check-component-props.mjs` — max 8 props per component
+8. `tsc --build` — TypeScript type checking
+9. `vitest run` — tests with per-path coverage thresholds
+10. `jscpd` — copy-paste detection
+
+Layer boundary enforcement runs as a Vitest test within step 9.
+
+This takes ~8 seconds on the current codebase. Every commit is guaranteed to pass all checks.
+
+## Alternatives Considered
+
+**Lightweight pre-commit, full checks in CI** — the industry default. Pre-commit runs only formatting and basic linting; tests, type checking, and coverage run in a CI pipeline. This is faster at commit time but creates a delayed feedback loop. For agentic coding workflows, this delay is costly: the agent produces a commit, moves on, and the CI failure arrives minutes later when context has shifted. The human must re-engage the agent with the failure context, losing the tight iteration loop.
+
+**No pre-commit hooks, CI only** — maximum commit speed, all enforcement in CI. Risks accumulating multiple broken commits before issues surface. Particularly problematic with agents that commit frequently.
+
+**Selective pre-commit (fast checks only)** — run formatting, linting, and type checking at pre-commit; defer tests and coverage to CI as a compromise. Still breaks the feedback loop for test failures and coverage regressions, which are the checks most likely to catch agent-introduced bugs.
+
+**Per-change hooks (e.g., Claude Code hooks)** — run checks after every file edit or tool call, not just at commit time. This is an even tighter feedback loop than pre-commit: the agent learns about a violation seconds after introducing it, before more code is written on top of it. Claude Code supports hooks that trigger on events like `PostToolUse`, which could run linting or type checking after every file write.
+
+However, running the full gate after every edit breaks test-driven workflows: writing a test before its implementation, or updating implementation before updating tests, produces intermediate states that legitimately fail type checking or tests. Scoping hooks to only fast, non-breaking checks (formatting, linting) would avoid this, but splits the gate into two tiers — adding complexity for unclear benefit when pre-commit already catches everything within ~8 seconds.
+
+Pre-commit is the current sweet spot: tight enough that agents get feedback in the same context window, but not so tight that it interferes with red-green-refactor or incremental editing. Per-change hooks remain a future option if the codebase grows to a point where pre-commit becomes too slow.
+
+## Consequences
+
+**Positive:**
+- Early backpressure in short feedback loops. Agents receive immediate, comprehensive feedback on every commit attempt. If a check fails, the agent can fix it in the same context window, maintaining continuity.
+- Every commit on `main` is guaranteed to pass all quality gates. There is no state where "it compiled but the tests are broken" or "formatting drifted."
+- No CI/local divergence. The same checks run everywhere, eliminating "works on my machine" or "CI caught something pre-commit didn't."
+- Enforces discipline incrementally: each commit is small, clean, and complete rather than "I'll fix the tests later."
+
+**Negative:**
+- ~8 seconds per commit attempt. This is acceptable for the current codebase size but will grow with the test suite. If it exceeds ~15 seconds, selective pre-commit with CI for the rest may become necessary.
+- Developers (or agents) cannot make quick "WIP" or "checkpoint" commits without passing all gates. This is intentional — every commit should be a valid state — but it prevents some workflows like committing broken code to switch branches.
+- The sequential chain means a failure in step 1 (audit) prevents discovering failures in step 9 (tests). In practice, this rarely matters because failures are fixed immediately and the chain is re-run.

docs/agents/research/2026-03-28-entity-rehydration.md

@@ -0,0 +1,238 @@
+---
+date: 2026-03-28T01:35:07.925247+00:00
+git_commit: f4fb69dbc763fefe4a73b3491c27093bbd06af0d
+branch: main
+topic: "Entity rehydration: current implementation and migration surface"
+tags: [research, codebase, rehydration, persistence, domain, player-character, combatant]
+status: complete
+---
+
+# Research: Entity Rehydration — Current Implementation and Migration Surface
+
+## Research Question
+
+Map all entity rehydration logic (reconstructing typed domain objects from untyped JSON) across the codebase. Document what validation each rehydration function performs, where it lives, how functions cross-reference each other, and what the domain layer already provides that could replace adapter-level validation. This research supports Issue #20: Move entity rehydration to domain layer.
+
+## Summary
+
+Entity rehydration currently lives entirely in `apps/web/src/persistence/`. Two primary rehydration functions exist:
+
+1. **`rehydrateCharacter`** in `player-character-storage.ts` — validates and reconstructs `PlayerCharacter` from unknown JSON
+2. **`rehydrateCombatant`** (private) + **`rehydrateEncounter`** (exported) in `encounter-storage.ts` — validates and reconstructs `Combatant`/`Encounter` from unknown JSON
+
+These are consumed by three call sites: localStorage loading, undo/redo stack loading, and JSON import validation. The domain layer already contains parallel validation logic in `createPlayerCharacter`, `addCombatant`/`validateInit`, and `createEncounter`, but the rehydration functions duplicate this validation with subtly different rules (rehydration is lenient/recovering; creation is strict/rejecting).
+
+## Detailed Findings
+
+### 1. PlayerCharacter Rehydration
+
+**File**: `apps/web/src/persistence/player-character-storage.ts:25-65`
+
+`rehydrateCharacter(raw: unknown): PlayerCharacter | null` performs:
+
+| Field | Validation | Behavior on invalid |
+|-------|-----------|-------------------|
+| `id` | `typeof string`, non-empty | Return `null` (reject entire PC) |
+| `name` | `typeof string`, non-empty after trim | Return `null` |
+| `ac` | `typeof number`, integer, `>= 0` | Return `null` |
+| `maxHp` | `typeof number`, integer, `>= 1` | Return `null` |
+| `color` | Optional; if present, must be in `VALID_PLAYER_COLORS` | Return `null` |
+| `icon` | Optional; if present, must be in `VALID_PLAYER_ICONS` | Return `null` |
+| `level` | Optional; if present, must be integer 1-20 | Return `null` |
+
+Constructs result via branded `playerCharacterId()` and type assertions for color/icon.
+
+**Helper**: `isValidOptionalMember(value, validSet)` — shared check for optional set-membership fields (lines 18-23).
+
+**Callers**:
+- `loadPlayerCharacters()` (same file, line 67) — loads from localStorage
+- `rehydrateCharacters()` in `export-import.ts:21-30` — filters PCs during import validation
+
+### 2. Combatant Rehydration
+
+**File**: `apps/web/src/persistence/encounter-storage.ts:67-103`
+
+`rehydrateCombatant(c: unknown)` (private, no return type annotation) performs:
+
+| Field | Validation | Behavior on invalid |
+|-------|-----------|-------------------|
+| `id` | Cast directly (`entry.id as string`) | No validation (relies on `isValidCombatantEntry` pre-check) |
+| `name` | Cast directly (`entry.name as string`) | No validation (relies on pre-check) |
+| `initiative` | `typeof number` or `undefined` | Defaults to `undefined` |
+| `ac` | Via `validateAc`: integer `>= 0` | Defaults to `undefined` |
+| `conditions` | Via `validateConditions`: array, each in `VALID_CONDITION_IDS` | Defaults to `undefined` |
+| `isConcentrating` | Strictly `=== true` | Defaults to `undefined` |
+| `creatureId` | Via `validateCreatureId`: non-empty string | Defaults to `undefined` |
+| `color` | String in `VALID_PLAYER_COLORS` | Defaults to `undefined` |
+| `icon` | String in `VALID_PLAYER_ICONS` | Defaults to `undefined` |
+| `playerCharacterId` | Non-empty string | Defaults to `undefined` |
+| `maxHp` / `currentHp` | Via `validateHp`: maxHp integer >= 1, currentHp integer 0..maxHp | Defaults to `undefined`; invalid currentHp falls back to maxHp |
+
+**Key difference from PC rehydration**: Combatant rehydration is *lenient* — invalid optional fields are silently dropped rather than rejecting the entire entity. Only `id` and `name` are required (checked by `isValidCombatantEntry` at line 105-109 before `rehydrateCombatant` is called).
+
+**Helper functions** (all private):
+- `validateAc(value)` — lines 24-28
+- `validateConditions(value)` — lines 30-37
+- `validateCreatureId(value)` — lines 39-43
+- `validateHp(rawMaxHp, rawCurrentHp)` — lines 45-65
+
+### 3. Encounter Rehydration
+
+**File**: `apps/web/src/persistence/encounter-storage.ts:111-140`
+
+`rehydrateEncounter(parsed: unknown): Encounter | null` validates the encounter envelope:
+- Must be a non-null, non-array object
+- `combatants` must be an array
+- `activeIndex` must be a number
+- `roundNumber` must be a number
+- Empty combatant array → returns hardcoded `{ combatants: [], activeIndex: 0, roundNumber: 1 }`
+- All entries must pass `isValidCombatantEntry` (id + name check)
+- Maps entries through `rehydrateCombatant`, then passes to domain's `createEncounter` for invariant enforcement
+
+**Callers**:
+- `loadEncounter()` (same file, line 142) — localStorage
+- `loadStack()` in `undo-redo-storage.ts:17-36` — undo/redo stacks from localStorage
+- `rehydrateStack()` in `export-import.ts:10-19` — import validation
+- `validateImportBundle()` in `export-import.ts:32-65` — import validation (direct call for the main encounter)
+
+### 4. Import Bundle Validation
+
+**File**: `apps/web/src/persistence/export-import.ts:32-65`
+
+`validateImportBundle(data: unknown): ExportBundle | string` validates the bundle envelope:
+- Version must be `1`
+- `exportedAt` must be a string
+- `undoStack` and `redoStack` must be arrays
+- `playerCharacters` must be an array
+- Delegates to `rehydrateEncounter` for the encounter
+- Delegates to `rehydrateStack` (which calls `rehydrateEncounter`) for undo/redo
+- Delegates to `rehydrateCharacters` (which calls `rehydrateCharacter`) for PCs
+
+This function validates the *envelope* structure. Entity-level validation is fully delegated.
+
+### 5. Domain Layer Validation (Existing)
+
+The domain already contains validation for the same fields, but in *creation* context (typed inputs, DomainError returns):
+
+**`createPlayerCharacter`** (`packages/domain/src/create-player-character.ts:17-100`):
+- Same field rules as `rehydrateCharacter`: name non-empty, ac >= 0 integer, maxHp >= 1 integer, color/icon in valid sets, level 1-20
+- Returns `DomainError` on invalid input (not `null`)
+
+**`validateInit`** in `addCombatant` (`packages/domain/src/add-combatant.ts:27-53`):
+- Validates maxHp (positive integer), ac (non-negative integer), initiative (integer)
+- Does NOT validate conditions, color, icon, playerCharacterId, creatureId, isConcentrating
+
+**`createEncounter`** (`packages/domain/src/types.ts:50-71`):
+- Validates activeIndex bounds and roundNumber (positive integer)
+- Already used by `rehydrateEncounter` as the final step
+
+**`editPlayerCharacter`** (`packages/domain/src/edit-player-character.ts`):
+- `validateFields` validates the same PC fields for edits
+
+### 6. Validation Overlap and Gaps
+
+| Field | Rehydration validates | Domain validates |
+|-------|----------------------|-----------------|
+| PC.id | Non-empty string | N/A (caller provides) |
+| PC.name | Non-empty string | Non-empty (trimmed) |
+| PC.ac | Integer >= 0 | Integer >= 0 |
+| PC.maxHp | Integer >= 1 | Integer >= 1 |
+| PC.color | In VALID_PLAYER_COLORS | In VALID_PLAYER_COLORS |
+| PC.icon | In VALID_PLAYER_ICONS | In VALID_PLAYER_ICONS |
+| PC.level | Integer 1-20 | Integer 1-20 |
+| Combatant.id | Non-empty string (via pre-check) | N/A (caller provides) |
+| Combatant.name | String type (via pre-check) | Non-empty (trimmed) |
+| Combatant.initiative | `typeof number` | Integer |
+| Combatant.ac | Integer >= 0 | Integer >= 0 |
+| Combatant.maxHp | Integer >= 1 | Integer >= 1 |
+| Combatant.currentHp | Integer 0..maxHp | N/A (set = maxHp on add) |
+| Combatant.tempHp | **Not validated** | N/A |
+| Combatant.conditions | Each in VALID_CONDITION_IDS | N/A (toggleCondition checks) |
+| Combatant.isConcentrating | Strictly `true` or dropped | N/A (toggleConcentration) |
+| Combatant.creatureId | Non-empty string | N/A (passed through) |
+| Combatant.color | In VALID_PLAYER_COLORS | N/A (passed through) |
+| Combatant.icon | In VALID_PLAYER_ICONS | N/A (passed through) |
+| Combatant.playerCharacterId | Non-empty string | N/A (passed through) |
+
+Key observations:
+- Rehydration validates `id` (required for identity); domain creation functions receive `id` as a typed parameter
+- Combatant rehydration does NOT validate `tempHp` at all — it's silently passed through or ignored
+- Combatant rehydration checks `initiative` as `typeof number` but domain checks `Number.isInteger` — slightly different strictness
+- Domain validation for combatant optional fields is scattered across individual mutation functions, not centralized
+
+### 7. Test Coverage
+
+**Persistence tests** (adapter layer):
+- `encounter-storage.test.ts` — ~27 tests covering round-trip, corrupt data, AC validation, edge cases
+- `player-character-storage.test.ts` — ~17 tests covering round-trip, corrupt data, field validation, level
+
+**Import tests** (adapter layer):
+- `validate-import-bundle.test.ts` — ~21 tests covering envelope validation, graceful recovery, PC filtering
+- `export-import.test.ts` — ~15 tests covering bundle assembly, round-trip, filename resolution
+
+**Domain tests**: No rehydration tests exist in `packages/domain/` — all rehydration testing is in the adapter layer.
+
+### 8. Cross-Reference Map
+
+```
+loadPlayerCharacters() ──→ rehydrateCharacter()
+                                    ↑
+validateImportBundle() ──→ rehydrateCharacters() ──┘
+                       ├─→ rehydrateEncounter() ──→ isValidCombatantEntry()
+                       │                       ├─→ rehydrateCombatant() ──→ validateAc()
+                       │                       │                       ├─→ validateConditions()
+                       │                       │                       ├─→ validateCreatureId()
+                       │                       │                       └─→ validateHp()
+                       │                       └─→ createEncounter() [domain]
+                       └─→ rehydrateStack() ───→ rehydrateEncounter() [same as above]
+
+loadEncounter() ───────→ rehydrateEncounter() [same as above]
+
+loadUndoRedoStacks() ──→ loadStack() ──→ rehydrateEncounter() [same as above]
+```
+
+## Code References
+
+- `apps/web/src/persistence/player-character-storage.ts:25-65` — `rehydrateCharacter` (PC rehydration)
+- `apps/web/src/persistence/player-character-storage.ts:18-23` — `isValidOptionalMember` helper
+- `apps/web/src/persistence/encounter-storage.ts:24-28` — `validateAc` helper
+- `apps/web/src/persistence/encounter-storage.ts:30-37` — `validateConditions` helper
+- `apps/web/src/persistence/encounter-storage.ts:39-43` — `validateCreatureId` helper
+- `apps/web/src/persistence/encounter-storage.ts:45-65` — `validateHp` helper
+- `apps/web/src/persistence/encounter-storage.ts:67-103` — `rehydrateCombatant` (combatant rehydration)
+- `apps/web/src/persistence/encounter-storage.ts:105-109` — `isValidCombatantEntry` (pre-check)
+- `apps/web/src/persistence/encounter-storage.ts:111-140` — `rehydrateEncounter` (encounter envelope rehydration)
+- `apps/web/src/persistence/export-import.ts:10-30` — `rehydrateStack` / `rehydrateCharacters` (collection wrappers)
+- `apps/web/src/persistence/export-import.ts:32-65` — `validateImportBundle` (import envelope validation)
+- `apps/web/src/persistence/undo-redo-storage.ts:17-36` — `loadStack` (undo/redo rehydration)
+- `packages/domain/src/create-player-character.ts:17-100` — PC creation validation
+- `packages/domain/src/add-combatant.ts:27-53` — `validateInit` (combatant creation validation)
+- `packages/domain/src/types.ts:50-71` — `createEncounter` (encounter invariant enforcement)
+- `packages/domain/src/types.ts:12-26` — `Combatant` type definition
+- `packages/domain/src/player-character-types.ts:70-83` — `PlayerCharacter` type definition
+
+## Architecture Documentation
+
+### Current pattern
+Rehydration is an adapter concern — persistence adapters validate raw JSON and construct typed domain objects. The domain provides creation functions that validate typed inputs for new entities, but no functions for reconstructing entities from untyped serialized data.
+
+### Rehydration vs. creation semantics
+Rehydration and creation serve different purposes:
+- **Creation** (domain): Validates business rules for *new* entities. Receives typed parameters. Returns `DomainError` on failure.
+- **Rehydration** (adapter): Reconstructs *previously valid* entities from serialized JSON. Receives `unknown`. Returns `null` on failure. May be lenient (combatants drop invalid optional fields) or strict (PCs reject on any invalid field).
+
+### Delegation chain
+`rehydrateEncounter` already delegates to `createEncounter` for encounter-level invariants. The entity-level rehydration functions (`rehydrateCharacter`, `rehydrateCombatant`) do NOT delegate to any domain function — they re-implement field validation inline.
+
+### tempHp gap
+`Combatant.tempHp` is defined in the domain type but has no validation in the current rehydration code. It appears to be silently included or excluded depending on what `rehydrateCombatant` constructs (it's not in the explicit field list, so it would be dropped during rehydration).
+
+## Open Questions
+
+1. **Should `rehydrateCombatant` remain lenient (drop invalid optional fields) or become strict like `rehydrateCharacter` (reject on any invalid field)?** The current asymmetry is intentional: combatants can exist with minimal data (just id + name), while PCs always require ac/maxHp.
+
+2. **Should `tempHp` be validated during rehydration?** It's currently missing from combatant rehydration but is a valid field on the type.
+
+3. **Should `rehydrateEncounter` move to domain too, or only the entity-level functions?** The issue acceptance criteria says "validateImportBundle and rehydrateEncounter are unchanged" — but `rehydrateEncounter` currently lives alongside `rehydrateCombatant` and would need to import from domain instead of calling the local function.
+
+4. **Should `isValidCombatantEntry` (the pre-check) be part of the domain rehydration or remain in the adapter?** It's currently the gate that ensures `id` and `name` exist before `rehydrateCombatant` is called.

docs/conventions.md

@@ -0,0 +1,20 @@
+# Conventions (detailed)
+
+These conventions supplement the overview in `CLAUDE.md`. Load this file when working in the relevant areas.
+
+## Component Props
+
+Max 8 explicitly declared props per component interface, enforced by `scripts/check-component-props.mjs` (uses the TypeScript compiler API). Run `pnpm check:props` to verify.
+
+- Use React context for shared state
+- Reserve props for per-instance config (data items, layout variants, refs)
+
+## Export Format Compatibility
+
+When changing `Encounter`, `Combatant`, `PlayerCharacter`, or `UndoRedoState` types, verify that previously exported JSON files (version 1) still import correctly. If not, bump the `ExportBundle` version and add migration logic in `validateImportBundle()`.
+
+## Domain Patterns
+
+- **Branded types** for identity values (e.g., `CombatantId`). Prefer immutability/`readonly` where practical. See [ADR-003](adr/003-branded-types-for-identity.md).
+- **Domain events** are plain data objects with a `type` discriminant — no classes. See [ADR-002](adr/002-domain-events-as-plain-data.md).
+- **Errors as values** (`DomainError`), never thrown. See [ADR-001](adr/001-errors-as-values.md).

lefthook.yml

@@ -1,4 +1,29 @@
 pre-commit:
+  parallel: true
   jobs:
-    - name: check
-      run: pnpm check
+    - name: audit
+      run: pnpm audit --audit-level=high
+    - name: knip
+      run: pnpm exec knip
+    - name: biome
+      run: pnpm exec biome check .
+    - name: check-ignores
+      run: node scripts/check-lint-ignores.mjs
+    - name: check-classnames
+      run: node scripts/check-cn-classnames.mjs
+    - name: check-props
+      run: node scripts/check-component-props.mjs
+    - name: jscpd
+      run: pnpm exec jscpd
+    - name: jsinspect
+      run: pnpm jsinspect
+    - name: typecheck-oxlint-test
+      group:
+        piped: true
+        jobs:
+          - name: typecheck
+            run: pnpm exec tsc --build
+          - name: oxlint
+            run: pnpm oxlint -- --deny warnings
+          - name: test
+            run: pnpm vitest run --reporter=dot --coverage.reporter=text-summary

package.json

@@ -3,13 +3,15 @@
 	"packageManager": "pnpm@10.32.1+sha512.a706938f0e89ac1456b6563eab4edf1d1faf3368d1191fc5c59790e96dc918e4456ab2e67d613de1043d2e8c81f87303e6b40d4ffeca9df15ef1ad567348f2be",
 	"pnpm": {
 		"overrides": {
-			"undici": ">=7.24.0"
+			"undici": ">=7.24.0",
+			"picomatch": ">=4.0.4"
 		}
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.4.8",
 		"@vitest/coverage-v8": "^4.1.0",
 		"jscpd": "^4.0.8",
+		"jsinspect-plus": "^3.1.3",
 		"knip": "^5.88.1",
 		"lefthook": "^2.1.4",
 		"oxlint": "^1.56.0",
@@ -28,10 +30,11 @@
 		"test:watch": "vitest",
 		"knip": "knip",
 		"jscpd": "jscpd",
-		"oxlint": "oxlint --tsconfig apps/web/tsconfig.json --type-aware",
+		"jsinspect": "jsinspect -c .jsinspectrc apps/web/src packages/domain/src packages/application/src",
+		"oxlint": "oxlint --tsconfig apps/web/tsconfig.json --type-aware --deny warnings",
 		"check:ignores": "node scripts/check-lint-ignores.mjs",
 		"check:classnames": "node scripts/check-cn-classnames.mjs",
 		"check:props": "node scripts/check-component-props.mjs",
-		"check": "pnpm audit --audit-level=high && knip && biome check . && oxlint --tsconfig apps/web/tsconfig.json --type-aware && node scripts/check-lint-ignores.mjs && node scripts/check-cn-classnames.mjs && node scripts/check-component-props.mjs && tsc --build && vitest run && jscpd"
+		"check": "pnpm audit --audit-level=high && knip && biome check . && node scripts/check-lint-ignores.mjs && node scripts/check-cn-classnames.mjs && node scripts/check-component-props.mjs && jscpd && pnpm jsinspect && tsc --build && oxlint --tsconfig apps/web/tsconfig.json --type-aware --deny warnings && vitest run"
 	}
 }

packages/application/src/__tests__/helpers.ts

@@ -1,6 +1,14 @@
-import type { Encounter, PlayerCharacter } from "@initiative/domain";
-import { isDomainError } from "@initiative/domain";
-import type { EncounterStore, PlayerCharacterStore } from "../ports.js";
+import type {
+	Encounter,
+	PlayerCharacter,
+	UndoRedoState,
+} from "@initiative/domain";
+import { EMPTY_UNDO_REDO_STATE, isDomainError } from "@initiative/domain";
+import type {
+	EncounterStore,
+	PlayerCharacterStore,
+	UndoRedoStore,
+} from "../ports.js";
 
 export function requireSaved<T>(value: T | null): T {
 	if (value === null) throw new Error("Expected store.saved to be non-null");
@@ -52,3 +60,17 @@ export function stubPlayerCharacterStore(
 	};
 	return stub;
 }
+
+export function stubUndoRedoStore(
+	initial: UndoRedoState = EMPTY_UNDO_REDO_STATE,
+): UndoRedoStore & { saved: UndoRedoState | null } {
+	const stub = {
+		saved: null as UndoRedoState | null,
+		get: () => initial,
+		save: (state: UndoRedoState) => {
+			stub.saved = state;
+			stub.get = () => state;
+		},
+	};
+	return stub;
+}

packages/application/src/__tests__/use-cases.test.ts

@@ -2,8 +2,10 @@ import {
 	type ConditionId,
 	combatantId,
 	createEncounter,
+	EMPTY_UNDO_REDO_STATE,
 	isDomainError,
 	playerCharacterId,
+	pushUndo,
 } from "@initiative/domain";
 import { describe, expect, it } from "vitest";
 import { addCombatantUseCase } from "../add-combatant-use-case.js";
@@ -14,17 +16,21 @@ import { createPlayerCharacterUseCase } from "../create-player-character-use-cas
 import { deletePlayerCharacterUseCase } from "../delete-player-character-use-case.js";
 import { editCombatantUseCase } from "../edit-combatant-use-case.js";
 import { editPlayerCharacterUseCase } from "../edit-player-character-use-case.js";
+import { redoUseCase } from "../redo-use-case.js";
 import { removeCombatantUseCase } from "../remove-combatant-use-case.js";
 import { retreatTurnUseCase } from "../retreat-turn-use-case.js";
 import { setAcUseCase } from "../set-ac-use-case.js";
 import { setHpUseCase } from "../set-hp-use-case.js";
 import { setInitiativeUseCase } from "../set-initiative-use-case.js";
+import { setTempHpUseCase } from "../set-temp-hp-use-case.js";
 import { toggleConcentrationUseCase } from "../toggle-concentration-use-case.js";
 import { toggleConditionUseCase } from "../toggle-condition-use-case.js";
+import { undoUseCase } from "../undo-use-case.js";
 import {
 	requireSaved,
 	stubEncounterStore,
 	stubPlayerCharacterStore,
+	stubUndoRedoStore,
 } from "./helpers.js";
 
 const ID_A = combatantId("a");
@@ -386,3 +392,80 @@ describe("editPlayerCharacterUseCase", () => {
 		expect(store.saved).toBeNull();
 	});
 });
+
+describe("setTempHpUseCase", () => {
+	it("sets temp HP and saves", () => {
+		const enc = encounterWithHp("Goblin", 10);
+		const store = stubEncounterStore(enc);
+		const result = setTempHpUseCase(store, combatantId("Goblin"), 5);
+
+		expect(isDomainError(result)).toBe(false);
+		expect(requireSaved(store.saved).combatants[0].tempHp).toBe(5);
+	});
+
+	it("returns domain error for unknown combatant", () => {
+		const store = stubEncounterStore(emptyEncounter());
+		const result = setTempHpUseCase(store, ID_A, 5);
+
+		expect(isDomainError(result)).toBe(true);
+		expect(store.saved).toBeNull();
+	});
+});
+
+describe("undoUseCase", () => {
+	it("restores previous encounter and saves both stores", () => {
+		const previous = encounterWith("A");
+		const current = encounterWith("A", "B");
+		const undoRedoState = pushUndo(EMPTY_UNDO_REDO_STATE, previous);
+		const encounterStore = stubEncounterStore(current);
+		const undoRedoStore = stubUndoRedoStore(undoRedoState);
+
+		const result = undoUseCase(encounterStore, undoRedoStore);
+
+		expect(isDomainError(result)).toBe(false);
+		expect(requireSaved(encounterStore.saved).combatants).toHaveLength(1);
+		expect(undoRedoStore.saved).not.toBeNull();
+	});
+
+	it("returns domain error when nothing to undo", () => {
+		const encounterStore = stubEncounterStore(emptyEncounter());
+		const undoRedoStore = stubUndoRedoStore();
+
+		const result = undoUseCase(encounterStore, undoRedoStore);
+
+		expect(isDomainError(result)).toBe(true);
+		expect(encounterStore.saved).toBeNull();
+		expect(undoRedoStore.saved).toBeNull();
+	});
+});
+
+describe("redoUseCase", () => {
+	it("restores next encounter and saves both stores", () => {
+		const previous = encounterWith("A");
+		const current = encounterWith("A", "B");
+		// Simulate: undo pushed current to redoStack
+		const undoRedoState = {
+			undoStack: [],
+			redoStack: [current],
+		};
+		const encounterStore = stubEncounterStore(previous);
+		const undoRedoStore = stubUndoRedoStore(undoRedoState);
+
+		const result = redoUseCase(encounterStore, undoRedoStore);
+
+		expect(isDomainError(result)).toBe(false);
+		expect(requireSaved(encounterStore.saved).combatants).toHaveLength(2);
+		expect(undoRedoStore.saved).not.toBeNull();
+	});
+
+	it("returns domain error when nothing to redo", () => {
+		const encounterStore = stubEncounterStore(emptyEncounter());
+		const undoRedoStore = stubUndoRedoStore();
+
+		const result = redoUseCase(encounterStore, undoRedoStore);
+
+		expect(isDomainError(result)).toBe(true);
+		expect(encounterStore.saved).toBeNull();
+		expect(undoRedoStore.saved).toBeNull();
+	});
+});

packages/application/src/add-combatant-use-case.ts

@@ -1,24 +1,20 @@
 import {
 	addCombatant,
 	type CombatantId,
+	type CombatantInit,
 	type DomainError,
 	type DomainEvent,
-	isDomainError,
 } from "@initiative/domain";
 import type { EncounterStore } from "./ports.js";
+import { runEncounterAction } from "./run-encounter-action.js";
 
 export function addCombatantUseCase(
 	store: EncounterStore,
 	id: CombatantId,
 	name: string,
+	init?: CombatantInit,
 ): DomainEvent[] | DomainError {
-	const encounter = store.get();
-	const result = addCombatant(encounter, id, name);
-
-	if (isDomainError(result)) {
-		return result;
-	}
-
-	store.save(result.encounter);
-	return result.events;
+	return runEncounterAction(store, (encounter) =>
+		addCombatant(encounter, id, name, init),
+	);
 }

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

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

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

@@ -2,20 +2,12 @@ import {
 	advanceTurn,
 	type DomainError,
 	type DomainEvent,
-	isDomainError,
 } from "@initiative/domain";
 import type { EncounterStore } from "./ports.js";
+import { runEncounterAction } from "./run-encounter-action.js";
 
 export function advanceTurnUseCase(
 	store: EncounterStore,
 ): DomainEvent[] | DomainError {
-	const encounter = store.get();
-	const result = advanceTurn(encounter);
-
-	if (isDomainError(result)) {
-		return result;
-	}
-
-	store.save(result.encounter);
-	return result.events;
+	return runEncounterAction(store, (encounter) => advanceTurn(encounter));
 }

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

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

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

@@ -15,6 +15,7 @@ export function createPlayerCharacterUseCase(
 	maxHp: number,
 	color: string | undefined,
 	icon: string | undefined,
+	level?: number,
 ): DomainEvent[] | DomainError {
 	const characters = store.getAll();
 	const result = createPlayerCharacter(
@@ -25,6 +26,7 @@ export function createPlayerCharacterUseCase(
 		maxHp,
 		color,
 		icon,
+		level,
 	);
 
 	if (isDomainError(result)) {

packages/application/src/edit-combatant-use-case.ts

@@ -3,22 +3,16 @@ import {
 	type DomainError,
 	type DomainEvent,
 	editCombatant,
-	isDomainError,
 } from "@initiative/domain";
 import type { EncounterStore } from "./ports.js";
+import { runEncounterAction } from "./run-encounter-action.js";
 
 export function editCombatantUseCase(
 	store: EncounterStore,
 	id: CombatantId,
 	newName: string,
 ): DomainEvent[] | DomainError {
-	const encounter = store.get();
-	const result = editCombatant(encounter, id, newName);
-
-	if (isDomainError(result)) {
-		return result;
-	}
-
-	store.save(result.encounter);
-	return result.events;
+	return runEncounterAction(store, (encounter) =>
+		editCombatant(encounter, id, newName),
+	);
 }