Add import/export to README, research scope guidance to CLAUDE.md

Add import/export feature bullet to README.md (constitution requires
README updates when user-facing capabilities change). Add research
scope note to CLAUDE.md RPI section: research phases should scan for
existing patterns and consolidation opportunities, not just what the
feature needs. Remove auto-generated Active Technologies / Recent
Changes sections that duplicated Tech Stack.

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()

.gitignore

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

.oxlintrc.json

@@ -0,0 +1,27 @@
+{
+	"$schema": "https://raw.githubusercontent.com/nicolo-ribaudo/tc39-proposal-type-annotations/refs/heads/main/packages/oxlint/configuration_file_schema.json",
+	"plugins": ["typescript", "unicorn", "jest"],
+	"categories": {},
+	"rules": {
+		"typescript/no-unnecessary-type-assertion": "error",
+		"typescript/no-deprecated": "warn",
+		"typescript/prefer-regexp-exec": "error",
+		"unicorn/prefer-string-replace-all": "error",
+		"unicorn/prefer-string-raw": "error",
+		"jest/expect-expect": [
+			"error",
+			{
+				"assertFunctionNames": ["expect", "expectDomainError"]
+			}
+		]
+	},
+	"ignorePatterns": [
+		"dist",
+		"coverage",
+		".claude",
+		".specify",
+		"specs",
+		".pnpm-store",
+		"scripts"
+	]
+}

.specify/memory/constitution.md

@@ -1,9 +1,9 @@
 <!--
   Sync Impact Report
   ───────────────────
-  Version change: 2.2.1 → 3.0.0 (MAJOR — specs describe features not changes, proportional workflow)
+  Version change: 3.0.0 → 3.1.0 (MINOR — new principle II-A: context-based state flow)
   Modified sections:
-    - Development Workflow: specs are living feature documents; full pipeline for new features only
+    - Core Principles: added II-A. Context-Based State Flow (max 8 props, context over prop drilling)
   Templates requiring updates: none
 -->
 # Encounter Console Constitution
@@ -38,6 +38,22 @@ dependency direction:
 
 A module in an inner layer MUST NOT import from an outer layer.
 
+### II-A. Context-Based State Flow
+
+UI components MUST consume shared application state via React context
+providers, not prop drilling. Props are reserved for per-instance
+configuration (e.g., a specific data item, a layout variant, a ref).
+
+- Components MUST NOT declare more than 8 explicit props in their
+  own interface. This is enforced by `scripts/check-component-props.mjs`
+  at pre-commit.
+- Generic UI primitives (`components/ui/`) that extend HTML element
+  attributes are exempt — only explicitly declared props count, not
+  inherited HTML attributes.
+- Coordinating hooks that consume multiple contexts (e.g.,
+  `useInitiativeRolls`) are preferred over wiring callbacks through
+  a parent component.
+
 ### III. Clarification-First
 
 Before making any non-trivial assumption during specification,
@@ -140,4 +156,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.0.0 | **Ratified**: 2026-03-03 | **Last Amended**: 2026-03-11
+**Version**: 3.1.0 | **Ratified**: 2026-03-03 | **Last Amended**: 2026-03-19

CLAUDE.md

@@ -5,13 +5,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Commands
 
 ```bash
-pnpm check              # Merge gate — must pass before every commit (audit + knip + biome + typecheck + test/coverage + jscpd)
+pnpm check              # Merge gate — must pass before every commit (audit + knip + biome + oxlint + typecheck + test/coverage + jscpd)
+pnpm oxlint             # Type-aware linting (oxlint — complements Biome)
 pnpm knip               # Unused code detection (Knip)
 pnpm test               # Run all tests (Vitest)
 pnpm test:watch         # Tests in watch mode
 pnpm typecheck          # tsc --build (project references)
 pnpm lint               # Biome lint
 pnpm format             # Biome format (writes)
+pnpm check:props        # Component prop count enforcement (max 8)
 pnpm --filter web dev   # Vite dev server (localhost:5173)
 pnpm --filter web build # Production build
 ```
@@ -58,19 +60,30 @@ 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.0 (formatting + linting), Knip (unused code), jscpd (copy-paste detection)
+- Biome 2.4 (formatting + linting), oxlint (type-aware linting), Knip (unused code), jscpd (copy-paste detection)
 - Vitest (testing, v8 coverage), Lefthook (pre-commit hooks)
 
 ## Conventions
 
-- **Biome 2.0** for formatting and linting (no Prettier, no ESLint). Tab indentation, 80-char lines. Imports are auto-organized alphabetically.
+- **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`).
 - **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).
+- **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()`.
 - **Quality gates** are enforced at pre-commit via Lefthook's `pnpm check` — the project's single earliest enforcement point. No gate may exist only as a CI step or manual process.
 
+## Self-Review Checklist
+
+Before finishing a change, consider:
+- Is this the simplest approach that solves the current problem?
+- Is there duplication that hurts readability? (But don't abstract prematurely.)
+- Are errors handled correctly and communicated sensibly to the user?
+- Does the UI follow modern patterns and feel intuitive to interact with?
+
 ## Speckit Workflow
 
 Speckit (`/speckit.*` skills) manages the spec-driven development pipeline. Specs are **living documents** that describe features, not individual changes.
@@ -85,6 +98,8 @@ Speckit (`/speckit.*` skills) manages the spec-driven development pipeline. Spec
 - `rpi-plan` — interactive phased implementation plan in `docs/agents/plans/`
 - `rpi-implement` — execute a plan file phase by phase with automated + manual verification
 
+**Research scope**: Research should include a scan for existing patterns similar to what the feature needs (e.g., shared UI primitives, duplicated validation logic, repeated state management patterns). Identify extraction and consolidation opportunities before implementation, not during.
+
 ### Choosing the right workflow by scope
 
 | Scope | Workflow |
@@ -102,6 +117,8 @@ Speckit manages **what** to build (specs as living documents). RPI manages **how
 - `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
+- `specs/006-undo-redo/` — undo/redo for encounter state mutations
+- `specs/007-json-import-export/` — JSON import/export for full encounter state (encounter, undo/redo, player characters)
 
 ## Constitution (key principles)
 
@@ -112,10 +129,3 @@ The constitution (`.specify/memory/constitution.md`) governs all feature work:
 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

README.md

@@ -8,6 +8,8 @@ A local-first initiative tracker and encounter manager for tabletop RPGs (D&D 5e
 - **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
+- **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

apps/web/index.html

@@ -2,7 +2,16 @@
 <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" />
+		<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+		<meta property="og:title" content="Initiative Tracker" />
+		<meta property="og:description" content="D&D combat initiative tracker" />
+		<meta property="og:image" content="https://initiative.dostulata.rocks/icon-512.png" />
+		<meta property="og:url" content="https://initiative.dostulata.rocks/" />
+		<meta property="og:type" content="website" />
 		<title>Initiative Tracker</title>
 	</head>
 	<body>

apps/web/package.json

@@ -20,14 +20,15 @@
 		"tailwind-merge": "^3.5.0"
 	},
 	"devDependencies": {
-		"@tailwindcss/vite": "^4.2.1",
+		"@tailwindcss/vite": "^4.2.2",
 		"@testing-library/jest-dom": "^6.9.1",
 		"@testing-library/react": "^16.3.2",
+		"@testing-library/user-event": "^14.6.1",
 		"@types/react": "^19.0.0",
 		"@types/react-dom": "^19.0.0",
-		"@vitejs/plugin-react": "^4.3.0",
-		"jsdom": "^28.1.0",
-		"tailwindcss": "^4.2.1",
-		"vite": "^6.2.0"
+		"@vitejs/plugin-react": "^6.0.1",
+		"jsdom": "^29.0.1",
+		"tailwindcss": "^4.2.2",
+		"vite": "^8.0.1"
 	}
 }

apps/web/public/favicon.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+  <defs>
+    <linearGradient id="f" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#60a5fa"/>
+      <stop offset="100%" stop-color="#2563eb"/>
+    </linearGradient>
+  </defs>
+  <g transform="translate(16 15) scale(1.55)" fill="none" stroke="url(#f)" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round">
+    <polygon points="8.18 4.76 8.18 -4.74 -0.01 -9.49 -8.19 -4.74 -8.19 4.76 -0.01 9.51 8.18 4.76" fill="url(#f)" fill-opacity="0.15"/>
+    <polygon points="-0.01 -9.49 -4.75 -2.74 4.75 -2.74 -0.01 -9.49" fill="url(#f)" fill-opacity="0.25"/>
+    <polygon points="-0.01 5.44 8.18 4.76 4.75 -2.74 -0.01 5.44" fill="url(#f)" fill-opacity="0.2"/>
+    <polygon points="-0.01 5.44 -4.75 -2.74 -8.19 4.76 -0.01 5.44" fill="url(#f)" fill-opacity="0.1"/>
+    <line x1="-4.75" y1="-2.74" x2="-8.19" y2="-4.74"/>
+    <line x1="8.18" y1="-4.74" x2="4.75" y2="-2.74"/>
+    <line x1="-0.01" y1="5.44" x2="-0.01" y2="9.51"/>
+    <polygon points="8.18 4.76 8.18 -4.74 -0.01 -9.49 -8.19 -4.74 -8.19 4.76 -0.01 9.51 8.18 4.76"/>
+    <polygon points="-0.01 -9.49 -4.75 -2.74 4.75 -2.74 -0.01 -9.49"/>
+    <polygon points="-0.01 5.44 8.18 4.76 4.75 -2.74 -0.01 5.44"/>
+    <polygon points="-0.01 5.44 -4.75 -2.74 -8.19 4.76 -0.01 5.44"/>
+  </g>
+</svg>

apps/web/public/icon.svg

@@ -0,0 +1,31 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512">
+  <defs>
+    <radialGradient id="bg" cx="50%" cy="40%" r="70%">
+      <stop offset="0%" stop-color="#1a2e4a"/>
+      <stop offset="100%" stop-color="#0e1a2e"/>
+    </radialGradient>
+    <linearGradient id="d20fill" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#60a5fa"/>
+      <stop offset="100%" stop-color="#2563eb"/>
+    </linearGradient>
+    <linearGradient id="d20stroke" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#93c5fd"/>
+      <stop offset="100%" stop-color="#3b82f6"/>
+    </linearGradient>
+  </defs>
+  <rect width="512" height="512" rx="96" fill="url(#bg)"/>
+  <g transform="translate(256 256) scale(8.5)" fill="none" stroke="url(#d20stroke)" stroke-width="1.2" stroke-linecap="round" stroke-linejoin="round">
+    <polygon points="8.18 4.76 8.18 -4.74 -0.01 -9.49 -8.19 -4.74 -8.19 4.76 -0.01 9.51 8.18 4.76" fill="url(#d20fill)" fill-opacity="0.15"/>
+    <polygon points="-0.01 -9.49 -4.75 -2.74 4.75 -2.74 -0.01 -9.49" fill="url(#d20fill)" fill-opacity="0.25"/>
+    <polygon points="-0.01 5.44 8.18 4.76 4.75 -2.74 -0.01 5.44" fill="url(#d20fill)" fill-opacity="0.2"/>
+    <polygon points="-0.01 5.44 -4.75 -2.74 -8.19 4.76 -0.01 5.44" fill="url(#d20fill)" fill-opacity="0.1"/>
+    <line x1="-4.75" y1="-2.74" x2="-8.19" y2="-4.74"/>
+    <line x1="8.18" y1="-4.74" x2="4.75" y2="-2.74"/>
+    <line x1="-0.01" y1="5.44" x2="-0.01" y2="9.51"/>
+    <polygon points="8.18 4.76 8.18 -4.74 -0.01 -9.49 -8.19 -4.74 -8.19 4.76 -0.01 9.51 8.18 4.76"/>
+    <polygon points="-0.01 -9.49 -4.75 -2.74 4.75 -2.74 -0.01 -9.49"/>
+    <polygon points="-0.01 5.44 8.18 4.76 4.75 -2.74 -0.01 5.44"/>
+    <polygon points="-0.01 5.44 -4.75 -2.74 -8.19 4.76 -0.01 5.44"/>
+  </g>
+  <text x="256" y="278" text-anchor="middle" dominant-baseline="central" font-family="Inter, system-ui, sans-serif" font-weight="700" font-size="52" fill="#93c5fd" letter-spacing="1">20</text>
+</svg>

apps/web/public/manifest.json

@@ -0,0 +1,21 @@
+{
+	"name": "Initiative Tracker",
+	"short_name": "Initiative",
+	"description": "D&D combat initiative tracker",
+	"start_url": "/",
+	"display": "standalone",
+	"background_color": "#0e1a2e",
+	"theme_color": "#0e1a2e",
+	"icons": [
+		{
+			"src": "/icon-192.png",
+			"sizes": "192x192",
+			"type": "image/png"
+		},
+		{
+			"src": "/icon-512.png",
+			"sizes": "512x512",
+			"type": "image/png"
+		}
+	]
+}

apps/web/src/App.tsx

@@ -1,387 +1,147 @@
+import { useEffect, useRef, useState } from "react";
+import { ActionBar } from "./components/action-bar.js";
+import { BulkImportToasts } from "./components/bulk-import-toasts.js";
+import { CombatantRow } from "./components/combatant-row.js";
 import {
-	rollAllInitiativeUseCase,
-	rollInitiativeUseCase,
-} from "@initiative/application";
-import type { CombatantId, Creature, CreatureId } from "@initiative/domain";
-import { Plus } from "lucide-react";
-import { useCallback, useEffect, useRef, useState } from "react";
-import { ActionBar } from "./components/action-bar";
-import { CombatantRow } from "./components/combatant-row";
-import { CreatePlayerModal } from "./components/create-player-modal";
-import { PlayerManagement } from "./components/player-management";
-import { SourceManager } from "./components/source-manager";
-import { StatBlockPanel } from "./components/stat-block-panel";
-import { Toast } from "./components/toast";
-import { TurnNavigation } from "./components/turn-navigation";
-import { type SearchResult, useBestiary } from "./hooks/use-bestiary";
-import { useBulkImport } from "./hooks/use-bulk-import";
-import { useEncounter } from "./hooks/use-encounter";
-import { usePlayerCharacters } from "./hooks/use-player-characters";
-
-function rollDice(): number {
-	return Math.floor(Math.random() * 20) + 1;
-}
+	PlayerCharacterSection,
+	type PlayerCharacterSectionHandle,
+} from "./components/player-character-section.js";
+import { SettingsModal } from "./components/settings-modal.js";
+import { StatBlockPanel } from "./components/stat-block-panel.js";
+import { Toast } from "./components/toast.js";
+import { TurnNavigation } from "./components/turn-navigation.js";
+import { useEncounterContext } from "./contexts/encounter-context.js";
+import { useInitiativeRollsContext } from "./contexts/initiative-rolls-context.js";
+import { useSidePanelContext } from "./contexts/side-panel-context.js";
+import { useActionBarAnimation } from "./hooks/use-action-bar-animation.js";
+import { useAutoStatBlock } from "./hooks/use-auto-stat-block.js";
+import { cn } from "./lib/utils.js";
 
 export function App() {
-	const {
-		encounter,
-		advanceTurn,
-		retreatTurn,
-		addCombatant,
-		clearEncounter,
-		removeCombatant,
-		editCombatant,
-		setInitiative,
-		setHp,
-		adjustHp,
-		setAc,
-		toggleCondition,
-		toggleConcentration,
-		addFromBestiary,
-		addFromPlayerCharacter,
-		makeStore,
-	} = useEncounter();
+	const { encounter, isEmpty } = useEncounterContext();
+	const sidePanel = useSidePanelContext();
+	const rolls = useInitiativeRollsContext();
 
-	const {
-		characters: playerCharacters,
-		createCharacter: createPlayerCharacter,
-		editCharacter: editPlayerCharacter,
-		deleteCharacter: deletePlayerCharacter,
-	} = usePlayerCharacters();
-
-	const [createPlayerOpen, setCreatePlayerOpen] = useState(false);
-	const [managementOpen, setManagementOpen] = useState(false);
-	const [editingPlayer, setEditingPlayer] = useState<
-		(typeof playerCharacters)[number] | undefined
-	>(undefined);
-
-	const {
-		search,
-		getCreature,
-		isLoaded,
-		isSourceCached,
-		fetchAndCacheSource,
-		uploadAndCacheSource,
-		refreshCache,
-	} = useBestiary();
-
-	const bulkImport = useBulkImport();
-
-	const [selectedCreatureId, setSelectedCreatureId] =
-		useState<CreatureId | null>(null);
-	const [bulkImportMode, setBulkImportMode] = useState(false);
-	const [sourceManagerOpen, setSourceManagerOpen] = useState(false);
-	const [isRightPanelFolded, setIsRightPanelFolded] = useState(false);
-	const [pinnedCreatureId, setPinnedCreatureId] = useState<CreatureId | null>(
-		null,
-	);
-	const [isWideDesktop, setIsWideDesktop] = useState(
-		() => window.matchMedia("(min-width: 1280px)").matches,
-	);
-
-	useEffect(() => {
-		const mq = window.matchMedia("(min-width: 1280px)");
-		const handler = (e: MediaQueryListEvent) => setIsWideDesktop(e.matches);
-		mq.addEventListener("change", handler);
-		return () => mq.removeEventListener("change", handler);
-	}, []);
-
-	const selectedCreature: Creature | null = selectedCreatureId
-		? (getCreature(selectedCreatureId) ?? null)
-		: null;
-
-	const pinnedCreature: Creature | null = pinnedCreatureId
-		? (getCreature(pinnedCreatureId) ?? null)
-		: null;
-
-	const handleAddFromBestiary = useCallback(
-		(result: SearchResult) => {
-			addFromBestiary(result);
-		},
-		[addFromBestiary],
-	);
-
-	const handleCombatantStatBlock = useCallback((creatureId: string) => {
-		setSelectedCreatureId(creatureId as CreatureId);
-		setIsRightPanelFolded(false);
-	}, []);
-
-	const handleRollInitiative = useCallback(
-		(id: CombatantId) => {
-			rollInitiativeUseCase(makeStore(), id, rollDice(), getCreature);
-		},
-		[makeStore, getCreature],
-	);
-
-	const handleRollAllInitiative = useCallback(() => {
-		rollAllInitiativeUseCase(makeStore(), rollDice, getCreature);
-	}, [makeStore, getCreature]);
-
-	const handleViewStatBlock = useCallback((result: SearchResult) => {
-		const slug = result.name
-			.toLowerCase()
-			.replace(/[^a-z0-9]+/g, "-")
-			.replace(/(^-|-$)/g, "");
-		const cId = `${result.source.toLowerCase()}:${slug}` as CreatureId;
-		setSelectedCreatureId(cId);
-		setIsRightPanelFolded(false);
-	}, []);
-
-	const handleBulkImport = useCallback(() => {
-		setBulkImportMode(true);
-		setSelectedCreatureId(null);
-	}, []);
-
-	const handleStartBulkImport = useCallback(
-		(baseUrl: string) => {
-			bulkImport.startImport(
-				baseUrl,
-				fetchAndCacheSource,
-				isSourceCached,
-				refreshCache,
-			);
-		},
-		[bulkImport.startImport, fetchAndCacheSource, isSourceCached, refreshCache],
-	);
-
-	const handleBulkImportDone = useCallback(() => {
-		setBulkImportMode(false);
-		bulkImport.reset();
-	}, [bulkImport.reset]);
-
-	const handleDismissBrowsePanel = useCallback(() => {
-		setSelectedCreatureId(null);
-		setBulkImportMode(false);
-	}, []);
-
-	const handleToggleFold = useCallback(() => {
-		setIsRightPanelFolded((f) => !f);
-	}, []);
-
-	const handlePin = useCallback(() => {
-		if (selectedCreatureId) {
-			setPinnedCreatureId((prev) =>
-				prev === selectedCreatureId ? null : selectedCreatureId,
-			);
-		}
-	}, [selectedCreatureId]);
-
-	const handleUnpin = useCallback(() => {
-		setPinnedCreatureId(null);
-	}, []);
+	useAutoStatBlock();
 
+	const [settingsOpen, setSettingsOpen] = useState(false);
+	const playerCharacterRef = useRef<PlayerCharacterSectionHandle>(null);
 	const actionBarInputRef = useRef<HTMLInputElement>(null);
-
-	// Auto-scroll to the active combatant when the turn changes
 	const activeRowRef = useRef<HTMLDivElement>(null);
-	useEffect(() => {
-		activeRowRef.current?.scrollIntoView({
-			block: "nearest",
-			behavior: "smooth",
-		});
-	}, [encounter.activeIndex]);
+	const actionBarAnim = useActionBarAnimation(encounter.combatants.length);
 
-	// Auto-show stat block for the active combatant when turn changes,
-	// but only when the viewport is wide enough to show it alongside the tracker.
-	// Only react to activeIndex changes — not combatant reordering (e.g. Roll All).
-	const prevActiveIndexRef = useRef(encounter.activeIndex);
+	// Close the side panel when the encounter becomes empty
 	useEffect(() => {
-		if (prevActiveIndexRef.current === encounter.activeIndex) return;
-		prevActiveIndexRef.current = encounter.activeIndex;
-		if (!window.matchMedia("(min-width: 1024px)").matches) return;
-		const active = encounter.combatants[encounter.activeIndex];
-		if (!active?.creatureId || !isLoaded) return;
-		setSelectedCreatureId(active.creatureId as CreatureId);
-	}, [encounter.activeIndex, encounter.combatants, isLoaded]);
+		if (isEmpty) {
+			sidePanel.dismissPanel();
+		}
+	}, [isEmpty, sidePanel.dismissPanel]);
+
+	// Auto-scroll to active combatant when turn changes
+	const activeIndex = encounter.activeIndex;
+	useEffect(() => {
+		if (activeIndex >= 0) {
+			activeRowRef.current?.scrollIntoView({
+				block: "nearest",
+				behavior: "smooth",
+			});
+		}
+	}, [activeIndex]);
 
 	return (
-		<div className="flex h-screen flex-col">
-			<div className="mx-auto flex w-full max-w-2xl flex-1 flex-col gap-3 px-4 min-h-0">
-				{/* Turn Navigation — fixed at top */}
-				<div className="shrink-0 pt-8">
-					<TurnNavigation
-						encounter={encounter}
-						onAdvanceTurn={advanceTurn}
-						onRetreatTurn={retreatTurn}
-						onClearEncounter={clearEncounter}
-						onRollAllInitiative={handleRollAllInitiative}
-						onOpenSourceManager={() => setSourceManagerOpen((o) => !o)}
-					/>
-				</div>
-
-				{sourceManagerOpen && (
-					<div className="shrink-0 rounded-md border border-border bg-card px-4 py-3">
-						<SourceManager onCacheCleared={refreshCache} />
+		<div className="flex h-dvh flex-col">
+			<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 pt-[env(safe-area-inset-top)] sm:pt-[max(env(safe-area-inset-top),2rem)]",
+							actionBarAnim.topBarClass,
+						)}
+						onAnimationEnd={actionBarAnim.onTopBarExitEnd}
+					>
+						<TurnNavigation />
 					</div>
 				)}
 
-				{/* Scrollable area — combatant list */}
-				<div className="flex-1 overflow-y-auto min-h-0">
-					<div
-						className={`flex flex-col px-2 py-2${encounter.combatants.length === 0 ? " h-full items-center justify-center" : ""}`}
-					>
-						{encounter.combatants.length === 0 ? (
-							<button
-								type="button"
-								onClick={() => actionBarInputRef.current?.focus()}
-								className="animate-breathe cursor-pointer text-muted-foreground transition-colors hover:text-primary"
-							>
-								<Plus className="size-14" />
-							</button>
-						) : (
-							encounter.combatants.map((c, i) => (
-								<CombatantRow
-									key={c.id}
-									ref={i === encounter.activeIndex ? activeRowRef : null}
-									combatant={c}
-									isActive={i === encounter.activeIndex}
-									onRename={editCombatant}
-									onSetInitiative={setInitiative}
-									onRemove={removeCombatant}
-									onSetHp={setHp}
-									onAdjustHp={adjustHp}
-									onSetAc={setAc}
-									onToggleCondition={toggleCondition}
-									onToggleConcentration={toggleConcentration}
-									onShowStatBlock={
-										c.creatureId
-											? () => handleCombatantStatBlock(c.creatureId as string)
-											: undefined
-									}
-									onRollInitiative={
-										c.creatureId ? handleRollInitiative : undefined
-									}
-								/>
-							))
-						)}
+				{isEmpty ? (
+					<div className="flex min-h-0 flex-1 items-center justify-center pt-8 pb-[15%]">
+						<div
+							className={cn("w-full", actionBarAnim.risingClass)}
+							onAnimationEnd={actionBarAnim.onRiseEnd}
+						>
+							<ActionBar
+								inputRef={actionBarInputRef}
+								onManagePlayers={() =>
+									playerCharacterRef.current?.openManagement()
+								}
+								onOpenSettings={() => setSettingsOpen(true)}
+								autoFocus
+							/>
+						</div>
 					</div>
-				</div>
+				) : (
+					<>
+						<div className="min-h-0 flex-1 overflow-y-auto">
+							<div className="flex flex-col px-2 py-2">
+								{encounter.combatants.map((c, i) => (
+									<CombatantRow
+										key={c.id}
+										ref={i === encounter.activeIndex ? activeRowRef : null}
+										combatant={c}
+										isActive={i === encounter.activeIndex}
+									/>
+								))}
+							</div>
+						</div>
 
-				{/* Action Bar — fixed at bottom */}
-				<div className="shrink-0 pb-8">
-					<ActionBar
-						onAddCombatant={addCombatant}
-						onAddFromBestiary={handleAddFromBestiary}
-						bestiarySearch={search}
-						bestiaryLoaded={isLoaded}
-						onViewStatBlock={handleViewStatBlock}
-						onBulkImport={handleBulkImport}
-						bulkImportDisabled={bulkImport.state.status === "loading"}
-						inputRef={actionBarInputRef}
-						playerCharacters={playerCharacters}
-						onAddFromPlayerCharacter={addFromPlayerCharacter}
-						onManagePlayers={() => setManagementOpen(true)}
-					/>
-				</div>
+						<div
+							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
+								inputRef={actionBarInputRef}
+								onManagePlayers={() =>
+									playerCharacterRef.current?.openManagement()
+								}
+								onOpenSettings={() => setSettingsOpen(true)}
+							/>
+						</div>
+					</>
+				)}
 			</div>
 
-			{/* Pinned Stat Block Panel (left) */}
-			{pinnedCreatureId && isWideDesktop && (
-				<StatBlockPanel
-					creatureId={pinnedCreatureId}
-					creature={pinnedCreature}
-					isSourceCached={isSourceCached}
-					fetchAndCacheSource={fetchAndCacheSource}
-					uploadAndCacheSource={uploadAndCacheSource}
-					refreshCache={refreshCache}
-					panelRole="pinned"
-					isFolded={false}
-					onToggleFold={() => {}}
-					onPin={() => {}}
-					onUnpin={handleUnpin}
-					showPinButton={false}
-					side="left"
-					onDismiss={() => {}}
-				/>
+			{!!sidePanel.pinnedCreatureId && sidePanel.isWideDesktop && (
+				<StatBlockPanel panelRole="pinned" side="left" />
 			)}
 
-			{/* Browse Stat Block Panel (right) */}
-			<StatBlockPanel
-				creatureId={selectedCreatureId}
-				creature={selectedCreature}
-				isSourceCached={isSourceCached}
-				fetchAndCacheSource={fetchAndCacheSource}
-				uploadAndCacheSource={uploadAndCacheSource}
-				refreshCache={refreshCache}
-				panelRole="browse"
-				isFolded={isRightPanelFolded}
-				onToggleFold={handleToggleFold}
-				onPin={handlePin}
-				onUnpin={() => {}}
-				showPinButton={isWideDesktop && !!selectedCreature}
-				side="right"
-				onDismiss={handleDismissBrowsePanel}
-				bulkImportMode={bulkImportMode}
-				bulkImportState={bulkImport.state}
-				onStartBulkImport={handleStartBulkImport}
-				onBulkImportDone={handleBulkImportDone}
-			/>
+			<StatBlockPanel panelRole="browse" side="right" />
 
-			{/* Toast for bulk import progress when panel is closed */}
-			{bulkImport.state.status === "loading" && !bulkImportMode && (
+			<BulkImportToasts />
+
+			{rolls.rollSkippedCount > 0 && (
 				<Toast
-					message={`Loading sources... ${bulkImport.state.completed + bulkImport.state.failed}/${bulkImport.state.total}`}
-					progress={
-						bulkImport.state.total > 0
-							? (bulkImport.state.completed + bulkImport.state.failed) /
-								bulkImport.state.total
-							: 0
-					}
-					onDismiss={() => {}}
-				/>
-			)}
-			{bulkImport.state.status === "complete" && !bulkImportMode && (
-				<Toast
-					message="All sources loaded"
-					onDismiss={bulkImport.reset}
-					autoDismissMs={3000}
-				/>
-			)}
-			{bulkImport.state.status === "partial-failure" && !bulkImportMode && (
-				<Toast
-					message={`Loaded ${bulkImport.state.completed}/${bulkImport.state.total} sources (${bulkImport.state.failed} failed)`}
-					onDismiss={bulkImport.reset}
+					message={`${rolls.rollSkippedCount} skipped — bestiary source not loaded`}
+					onDismiss={rolls.dismissRollSkipped}
+					autoDismissMs={4000}
 				/>
 			)}
 
-			<CreatePlayerModal
-				open={createPlayerOpen}
-				onClose={() => {
-					setCreatePlayerOpen(false);
-					setEditingPlayer(undefined);
-				}}
-				onSave={(name, ac, maxHp, color, icon) => {
-					if (editingPlayer) {
-						editPlayerCharacter?.(editingPlayer.id, {
-							name,
-							ac,
-							maxHp,
-							color,
-							icon,
-						});
-					} else {
-						createPlayerCharacter(name, ac, maxHp, color, icon);
-					}
-				}}
-				playerCharacter={editingPlayer}
-			/>
+			{!!rolls.rollSingleSkipped && (
+				<Toast
+					message="Can't roll — bestiary source not loaded"
+					onDismiss={rolls.dismissRollSingleSkipped}
+					autoDismissMs={4000}
+				/>
+			)}
 
-			<PlayerManagement
-				open={managementOpen}
-				onClose={() => setManagementOpen(false)}
-				characters={playerCharacters}
-				onEdit={(pc) => {
-					setEditingPlayer(pc);
-					setCreatePlayerOpen(true);
-					setManagementOpen(false);
-				}}
-				onDelete={(id) => deletePlayerCharacter?.(id)}
-				onCreate={() => {
-					setEditingPlayer(undefined);
-					setCreatePlayerOpen(true);
-					setManagementOpen(false);
-				}}
+			<SettingsModal
+				open={settingsOpen}
+				onClose={() => setSettingsOpen(false)}
 			/>
+			<PlayerCharacterSection ref={playerCharacterRef} />
 		</div>
 	);
 }

apps/web/src/__tests__/app-integration.test.tsx

@@ -0,0 +1,163 @@
+// @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 { App } from "../App.js";
+import { AllProviders } from "./test-providers.js";
+
+// Mock persistence — no localStorage interaction
+vi.mock("../persistence/encounter-storage.js", () => ({
+	loadEncounter: () => null,
+	saveEncounter: () => {},
+}));
+
+vi.mock("../persistence/player-character-storage.js", () => ({
+	loadPlayerCharacters: () => [],
+	savePlayerCharacters: () => {},
+}));
+
+// Mock bestiary — no IndexedDB or JSON index
+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,
+}));
+
+// DOM API stubs — jsdom doesn't implement these
+beforeAll(() => {
+	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(),
+		})),
+	});
+	Element.prototype.scrollIntoView = vi.fn();
+});
+
+afterEach(cleanup);
+
+async function addCombatant(
+	user: ReturnType<typeof userEvent.setup>,
+	name: string,
+	opts?: { maxHp?: string },
+) {
+	const inputs = screen.getAllByPlaceholderText("+ Add combatants");
+	// biome-ignore lint/style/noNonNullAssertion: getAllBy always returns at least one
+	const input = inputs.at(-1)!;
+	await user.type(input, name);
+
+	if (opts?.maxHp) {
+		const maxHpInput = screen.getByPlaceholderText("MaxHP");
+		await user.type(maxHpInput, opts.maxHp);
+	}
+
+	const addButton = screen.getByRole("button", { name: "Add" });
+	await user.click(addButton);
+}
+
+describe("App integration", () => {
+	it("adds a combatant and removes it, returning to empty state", async () => {
+		const user = userEvent.setup();
+		render(<App />, { wrapper: AllProviders });
+
+		// Empty state: centered input visible, no TurnNavigation
+		expect(screen.getByPlaceholderText("+ Add combatants")).toBeInTheDocument();
+		expect(screen.queryByText("R1")).not.toBeInTheDocument();
+
+		// Add a combatant
+		await addCombatant(user, "Goblin");
+
+		// Verify combatant appears and TurnNavigation shows
+		expect(screen.getByRole("button", { name: "Goblin" })).toBeInTheDocument();
+		expect(screen.getByText("R1")).toBeInTheDocument();
+		expect(screen.getAllByText("Goblin").length).toBeGreaterThanOrEqual(2);
+
+		// Remove combatant via ConfirmButton (two clicks)
+		const removeBtn = screen.getByRole("button", {
+			name: "Remove combatant",
+		});
+		await user.click(removeBtn);
+		const confirmBtn = screen.getByRole("button", {
+			name: "Confirm remove combatant",
+		});
+		await user.click(confirmBtn);
+
+		// Back to empty state (R1 badge may linger due to exit animation in jsdom)
+		expect(
+			screen.queryByRole("button", { name: "Goblin" }),
+		).not.toBeInTheDocument();
+		expect(screen.getByPlaceholderText("+ Add combatants")).toBeInTheDocument();
+	});
+
+	it("advances and retreats turns across two combatants", async () => {
+		const user = userEvent.setup();
+		render(<App />, { wrapper: AllProviders });
+
+		await addCombatant(user, "Fighter");
+		await addCombatant(user, "Wizard");
+
+		// Initial state — R1, Fighter active (Previous turn disabled)
+		expect(screen.getByText("R1")).toBeInTheDocument();
+		expect(
+			screen.getByRole("button", { name: "Previous turn" }),
+		).toBeDisabled();
+
+		// Advance turn — Wizard becomes active
+		await user.click(screen.getByRole("button", { name: "Next turn" }));
+		expect(screen.getByText("R1")).toBeInTheDocument();
+		expect(screen.getByRole("button", { name: "Previous turn" })).toBeEnabled();
+
+		// Advance again — wraps to R2, Fighter active
+		await user.click(screen.getByRole("button", { name: "Next turn" }));
+		expect(screen.getByText("R2")).toBeInTheDocument();
+		expect(screen.getByRole("button", { name: "Previous turn" })).toBeEnabled();
+
+		// Retreat — back to R1, Wizard active
+		await user.click(screen.getByRole("button", { name: "Previous turn" }));
+		expect(screen.getByText("R1")).toBeInTheDocument();
+	});
+
+	it("adds a combatant with HP, applies damage, and shows unconscious state", async () => {
+		const user = userEvent.setup();
+		render(<App />, { wrapper: AllProviders });
+
+		await addCombatant(user, "Ogre", { maxHp: "59" });
+
+		// Verify HP displays — currentHp and maxHp both show "59"
+		const hpButton = screen.getByRole("button", {
+			name: "Current HP: 59 (healthy)",
+		});
+		expect(hpButton).toBeInTheDocument();
+
+		// Click currentHp to open HpAdjustPopover, apply full damage
+		await user.click(hpButton);
+		const hpInput = screen.getByPlaceholderText("HP");
+		expect(hpInput).toBeInTheDocument();
+		await user.type(hpInput, "59");
+		await user.click(screen.getByRole("button", { name: "Apply damage" }));
+
+		// Verify HP decreased to 0 and unconscious state
+		expect(
+			screen.getByRole("button", { name: "Current HP: 0 (unconscious)" }),
+		).toBeInTheDocument();
+	});
+});

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

@@ -200,6 +200,7 @@ describe("ConfirmButton", () => {
 		const parentHandler = vi.fn();
 		render(
 			// biome-ignore lint/a11y/noStaticElementInteractions: test wrapper
+			// biome-ignore lint/a11y/noNoninteractiveElementInteractions: test wrapper
 			<div onKeyDown={parentHandler}>
 				<ConfirmButton
 					icon={<XIcon />}

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__/stat-block-collapse-pin.test.tsx

@@ -0,0 +1,317 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import type { Creature, CreatureId } from "@initiative/domain";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock the context modules
+vi.mock("../contexts/side-panel-context.js", () => ({
+	useSidePanelContext: vi.fn(),
+}));
+
+vi.mock("../contexts/bestiary-context.js", () => ({
+	useBestiaryContext: vi.fn(),
+}));
+
+// Mock adapters to avoid IndexedDB
+vi.mock("../adapters/bestiary-index-adapter.js", () => ({
+	loadBestiaryIndex: () => ({ sources: {}, creatures: [] }),
+	getAllSourceCodes: () => [],
+	getDefaultFetchUrl: () => "",
+	getSourceDisplayName: (code: string) => code,
+}));
+
+import { StatBlockPanel } from "../components/stat-block-panel.js";
+import { useBestiaryContext } from "../contexts/bestiary-context.js";
+import { useSidePanelContext } from "../contexts/side-panel-context.js";
+
+const mockUseSidePanelContext = vi.mocked(useSidePanelContext);
+const mockUseBestiaryContext = vi.mocked(useBestiaryContext);
+
+const CLOSE_REGEX = /close/i;
+const COLLAPSE_REGEX = /collapse/i;
+const CREATURE_ID = "srd:goblin" as CreatureId;
+const CREATURE: Creature = {
+	id: CREATURE_ID,
+	name: "Goblin",
+	source: "SRD",
+	sourceDisplayName: "SRD",
+	size: "Small",
+	type: "humanoid",
+	alignment: "neutral evil",
+	ac: 15,
+	hp: { average: 7, formula: "2d6" },
+	speed: "30 ft.",
+	abilities: { str: 8, dex: 14, con: 10, int: 10, wis: 8, cha: 8 },
+	cr: "1/4",
+	initiativeProficiency: 0,
+	proficiencyBonus: 2,
+	passive: 9,
+};
+
+function mockMatchMedia(matches: boolean) {
+	Object.defineProperty(globalThis, "matchMedia", {
+		writable: true,
+		value: vi.fn().mockImplementation((query: string) => ({
+			matches,
+			media: query,
+			onchange: null,
+			addListener: vi.fn(),
+			removeListener: vi.fn(),
+			addEventListener: vi.fn(),
+			removeEventListener: vi.fn(),
+			dispatchEvent: vi.fn(),
+		})),
+	});
+}
+
+interface PanelOverrides {
+	creatureId?: CreatureId | null;
+	creature?: Creature | null;
+	panelRole?: "browse" | "pinned";
+	isCollapsed?: boolean;
+	side?: "left" | "right";
+	bulkImportMode?: boolean;
+}
+
+function setupMocks(overrides: PanelOverrides = {}) {
+	const panelRole = overrides.panelRole ?? "browse";
+	const creatureId = overrides.creatureId ?? CREATURE_ID;
+	const creature = overrides.creature ?? CREATURE;
+	const isCollapsed = overrides.isCollapsed ?? false;
+
+	const onToggleCollapse = vi.fn();
+	const onPin = vi.fn();
+	const onUnpin = vi.fn();
+	const onDismiss = vi.fn();
+
+	mockUseSidePanelContext.mockReturnValue({
+		selectedCreatureId: panelRole === "browse" ? creatureId : null,
+		pinnedCreatureId: panelRole === "pinned" ? creatureId : null,
+		isRightPanelCollapsed: panelRole === "browse" ? isCollapsed : false,
+		isWideDesktop: false,
+		bulkImportMode: overrides.bulkImportMode ?? false,
+		sourceManagerMode: false,
+		panelView: creatureId
+			? { mode: "creature" as const, creatureId }
+			: { mode: "closed" as const },
+		showCreature: vi.fn(),
+		updateCreature: vi.fn(),
+		showBulkImport: vi.fn(),
+		showSourceManager: vi.fn(),
+		dismissPanel: onDismiss,
+		toggleCollapse: onToggleCollapse,
+		togglePin: onPin,
+		unpin: onUnpin,
+	} as ReturnType<typeof useSidePanelContext>);
+
+	mockUseBestiaryContext.mockReturnValue({
+		getCreature: (id: CreatureId) => (id === creatureId ? creature : undefined),
+		isSourceCached: vi.fn().mockResolvedValue(true),
+		search: vi.fn().mockReturnValue([]),
+		isLoaded: true,
+		fetchAndCacheSource: vi.fn(),
+		uploadAndCacheSource: vi.fn(),
+		refreshCache: vi.fn(),
+	} as ReturnType<typeof useBestiaryContext>);
+
+	return { onToggleCollapse, onPin, onUnpin, onDismiss };
+}
+
+function renderPanel(overrides: PanelOverrides = {}) {
+	const callbacks = setupMocks(overrides);
+	const panelRole = overrides.panelRole ?? "browse";
+	const side = overrides.side ?? (panelRole === "pinned" ? "left" : "right");
+	render(<StatBlockPanel panelRole={panelRole} side={side} />);
+	return callbacks;
+}
+
+describe("Stat Block Panel Collapse/Expand and Pin", () => {
+	beforeEach(() => {
+		mockMatchMedia(true); // desktop by default
+	});
+
+	afterEach(cleanup);
+
+	describe("US1: Collapse and Expand", () => {
+		it("shows collapse button instead of close button on desktop", () => {
+			renderPanel();
+			expect(
+				screen.getByRole("button", { name: "Collapse stat block panel" }),
+			).toBeInTheDocument();
+			expect(
+				screen.queryByRole("button", { name: CLOSE_REGEX }),
+			).not.toBeInTheDocument();
+		});
+
+		it("does not show 'Stat Block' heading", () => {
+			renderPanel();
+			expect(screen.queryByText("Stat Block")).not.toBeInTheDocument();
+		});
+
+		it("renders collapsed tab with creature name when isCollapsed is true", () => {
+			renderPanel({ isCollapsed: true });
+			expect(screen.getByText("Goblin")).toBeInTheDocument();
+			expect(
+				screen.getByRole("button", { name: "Expand stat block panel" }),
+			).toBeInTheDocument();
+		});
+
+		it("calls onToggleCollapse when collapse button is clicked", () => {
+			const callbacks = renderPanel();
+			fireEvent.click(
+				screen.getByRole("button", { name: "Collapse stat block panel" }),
+			);
+			expect(callbacks.onToggleCollapse).toHaveBeenCalledTimes(1);
+		});
+
+		it("calls onToggleCollapse when collapsed tab is clicked", () => {
+			const callbacks = renderPanel({ isCollapsed: true });
+			fireEvent.click(
+				screen.getByRole("button", { name: "Expand stat block panel" }),
+			);
+			expect(callbacks.onToggleCollapse).toHaveBeenCalledTimes(1);
+		});
+
+		it("applies translate-x class when collapsed (right side)", () => {
+			renderPanel({ isCollapsed: true, side: "right" });
+			const panel = screen
+				.getByRole("button", { name: "Expand stat block panel" })
+				.closest("div");
+			expect(panel?.className).toContain("translate-x-[calc(100%-40px)]");
+		});
+
+		it("applies translate-x-0 when expanded", () => {
+			renderPanel({ isCollapsed: false });
+			const foldBtn = screen.getByRole("button", {
+				name: "Collapse stat block panel",
+			});
+			const panel = foldBtn.closest("div.fixed") as HTMLElement;
+			expect(panel?.className).toContain("translate-x-0");
+		});
+	});
+
+	describe("US1: Mobile behavior", () => {
+		beforeEach(() => {
+			mockMatchMedia(false); // mobile
+		});
+
+		it("shows collapse button instead of X close button on mobile drawer", () => {
+			renderPanel();
+			expect(
+				screen.getByRole("button", { name: "Collapse stat block panel" }),
+			).toBeInTheDocument();
+			// No X close icon button — only backdrop dismiss and collapse toggle
+			const buttons = screen.getAllByRole("button");
+			const buttonLabels = buttons.map((b) => b.getAttribute("aria-label"));
+			expect(buttonLabels).not.toContain("Close");
+		});
+
+		it("calls onDismiss when backdrop is clicked on mobile", () => {
+			const callbacks = renderPanel();
+			fireEvent.click(screen.getByRole("button", { name: "Close stat block" }));
+			expect(callbacks.onDismiss).toHaveBeenCalledTimes(1);
+		});
+
+		it("does not render pinned panel on mobile", () => {
+			const { container } = render(
+				(() => {
+					setupMocks({ panelRole: "pinned" });
+					return <StatBlockPanel panelRole="pinned" side="left" />;
+				})(),
+			);
+			expect(container.innerHTML).toBe("");
+		});
+	});
+
+	describe("US2: Pin and Unpin", () => {
+		it("shows pin button when isWideDesktop is true on desktop", () => {
+			setupMocks();
+			// Override to set isWideDesktop
+			const ctx = mockUseSidePanelContext.mock.results[0]?.value as ReturnType<
+				typeof useSidePanelContext
+			>;
+			mockUseSidePanelContext.mockReturnValue({
+				...ctx,
+				isWideDesktop: true,
+			});
+			render(<StatBlockPanel panelRole="browse" side="right" />);
+			expect(
+				screen.getByRole("button", { name: "Pin creature" }),
+			).toBeInTheDocument();
+		});
+
+		it("hides pin button when isWideDesktop is false", () => {
+			renderPanel();
+			expect(
+				screen.queryByRole("button", { name: "Pin creature" }),
+			).not.toBeInTheDocument();
+		});
+
+		it("calls onPin when pin button is clicked", () => {
+			setupMocks();
+			const ctx = mockUseSidePanelContext.mock.results[0]?.value as ReturnType<
+				typeof useSidePanelContext
+			>;
+			mockUseSidePanelContext.mockReturnValue({
+				...ctx,
+				isWideDesktop: true,
+			});
+			render(<StatBlockPanel panelRole="browse" side="right" />);
+			fireEvent.click(screen.getByRole("button", { name: "Pin creature" }));
+			expect(ctx.togglePin).toHaveBeenCalledTimes(1);
+		});
+
+		it("shows unpin button for pinned role", () => {
+			renderPanel({ panelRole: "pinned", side: "left" });
+			expect(
+				screen.getByRole("button", { name: "Unpin creature" }),
+			).toBeInTheDocument();
+		});
+
+		it("calls onUnpin when unpin button is clicked", () => {
+			const callbacks = renderPanel({ panelRole: "pinned", side: "left" });
+			fireEvent.click(screen.getByRole("button", { name: "Unpin creature" }));
+			expect(callbacks.onUnpin).toHaveBeenCalledTimes(1);
+		});
+
+		it("positions pinned panel on the left side", () => {
+			renderPanel({ panelRole: "pinned", side: "left" });
+			const unpinBtn = screen.getByRole("button", {
+				name: "Unpin creature",
+			});
+			const panel = unpinBtn.closest("div.fixed") as HTMLElement;
+			expect(panel?.className).toContain("left-0");
+			expect(panel?.className).toContain("border-r");
+		});
+
+		it("positions browse panel on the right side", () => {
+			renderPanel({ panelRole: "browse", side: "right" });
+			const foldBtn = screen.getByRole("button", {
+				name: "Collapse stat block panel",
+			});
+			const panel = foldBtn.closest("div.fixed") as HTMLElement;
+			expect(panel?.className).toContain("right-0");
+			expect(panel?.className).toContain("border-l");
+		});
+	});
+
+	describe("US3: Collapse independence with pinned panel", () => {
+		it("pinned panel has no collapse button", () => {
+			renderPanel({ panelRole: "pinned", side: "left" });
+			expect(
+				screen.queryByRole("button", { name: COLLAPSE_REGEX }),
+			).not.toBeInTheDocument();
+		});
+
+		it("pinned panel is always expanded (no translate offset)", () => {
+			renderPanel({ panelRole: "pinned", side: "left" });
+			const unpinBtn = screen.getByRole("button", {
+				name: "Unpin creature",
+			});
+			const panel = unpinBtn.closest("div.fixed") as HTMLElement;
+			expect(panel?.className).toContain("translate-x-0");
+		});
+	});
+});

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

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

apps/web/src/__tests__/test-providers.tsx

@@ -0,0 +1,31 @@
+import type { ReactNode } from "react";
+import {
+	BestiaryProvider,
+	BulkImportProvider,
+	EncounterProvider,
+	InitiativeRollsProvider,
+	PlayerCharactersProvider,
+	RulesEditionProvider,
+	SidePanelProvider,
+	ThemeProvider,
+} from "../contexts/index.js";
+
+export function AllProviders({ children }: { children: ReactNode }) {
+	return (
+		<ThemeProvider>
+			<RulesEditionProvider>
+				<EncounterProvider>
+					<BestiaryProvider>
+						<PlayerCharactersProvider>
+							<BulkImportProvider>
+								<SidePanelProvider>
+									<InitiativeRollsProvider>{children}</InitiativeRollsProvider>
+								</SidePanelProvider>
+							</BulkImportProvider>
+						</PlayerCharactersProvider>
+					</BestiaryProvider>
+				</EncounterProvider>
+			</RulesEditionProvider>
+		</ThemeProvider>
+	);
+}

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/__tests__/bestiary-adapter.test.ts

@@ -300,6 +300,44 @@ describe("normalizeBestiary", () => {
 		expect(creatures[0].proficiencyBonus).toBe(6);
 	});
 
+	it("normalizes pre-2024 {@atk mw} tags to full attack type text", () => {
+		const raw = {
+			monster: [
+				{
+					name: "Adult Black Dragon",
+					source: "MM",
+					size: ["H"],
+					type: "dragon",
+					ac: [19],
+					hp: { average: 195, formula: "17d12 + 85" },
+					speed: { walk: 40, fly: 80, swim: 40 },
+					str: 23,
+					dex: 14,
+					con: 21,
+					int: 14,
+					wis: 13,
+					cha: 17,
+					passive: 21,
+					cr: "14",
+					action: [
+						{
+							name: "Bite",
+							entries: [
+								"{@atk mw} {@hit 11} to hit, reach 10 ft., one target. {@h}17 ({@damage 2d10 + 6}) piercing damage plus 4 ({@damage 1d8}) acid damage.",
+							],
+						},
+					],
+				},
+			],
+		};
+
+		const creatures = normalizeBestiary(raw);
+		const bite = creatures[0].actions?.[0];
+		expect(bite?.text).toContain("Melee Weapon Attack:");
+		expect(bite?.text).not.toContain("mw");
+		expect(bite?.text).not.toContain("{@");
+	});
+
 	it("handles fly speed with hover condition", () => {
 		const raw = {
 			monster: [

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

@@ -30,11 +30,11 @@ describe("stripTags", () => {
 		expect(stripTags("{@hit 5}")).toBe("+5");
 	});
 
-	it("strips {@h} to Hit: ", () => {
+	it("strips {@h} to Hit:", () => {
 		expect(stripTags("{@h}")).toBe("Hit: ");
 	});
 
-	it("strips {@hom} to Hit or Miss: ", () => {
+	it("strips {@hom} to Hit or Miss:", () => {
 		expect(stripTags("{@hom}")).toBe("Hit or Miss: ");
 	});
 
@@ -50,6 +50,26 @@ describe("stripTags", () => {
 		expect(stripTags("{@atkr m,r}")).toBe("Melee or Ranged Attack Roll:");
 	});
 
+	it("strips {@atk mw} to Melee Weapon Attack:", () => {
+		expect(stripTags("{@atk mw}")).toBe("Melee Weapon Attack:");
+	});
+
+	it("strips {@atk rw} to Ranged Weapon Attack:", () => {
+		expect(stripTags("{@atk rw}")).toBe("Ranged Weapon Attack:");
+	});
+
+	it("strips {@atk ms} to Melee Spell Attack:", () => {
+		expect(stripTags("{@atk ms}")).toBe("Melee Spell Attack:");
+	});
+
+	it("strips {@atk rs} to Ranged Spell Attack:", () => {
+		expect(stripTags("{@atk rs}")).toBe("Ranged Spell Attack:");
+	});
+
+	it("strips {@atk mw,rw} to Melee or Ranged Weapon Attack:", () => {
+		expect(stripTags("{@atk mw,rw}")).toBe("Melee or Ranged Weapon Attack:");
+	});
+
 	it("strips {@recharge 5} to (Recharge 5-6)", () => {
 		expect(stripTags("{@recharge 5}")).toBe("(Recharge 5-6)");
 	});

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

@@ -9,6 +9,8 @@ import type {
 import { creatureId, proficiencyBonus } from "@initiative/domain";
 import { stripTags } from "./strip-tags.js";
 
+const LEADING_DIGITS_REGEX = /^(\d+)/;
+
 // --- Raw 5etools types (minimal, for parsing) ---
 
 interface RawMonster {
@@ -49,6 +51,7 @@ interface RawMonster {
 	legendaryHeader?: string[];
 	spellcasting?: RawSpellcasting[];
 	initiative?: { proficiency?: number };
+	_copy?: unknown;
 }
 
 interface RawEntry {
@@ -168,7 +171,7 @@ function extractAc(ac: RawMonster["ac"]): {
 	}
 	if ("special" in first) {
 		// Variable AC (e.g. spell summons) — parse leading number if possible
-		const match = first.special.match(/^(\d+)/);
+		const match = LEADING_DIGITS_REGEX.exec(first.special);
 		return {
 			value: match ? Number(match[1]) : 0,
 			source: first.special,
@@ -371,8 +374,8 @@ function extractCr(cr: string | { cr: string } | undefined): string {
 function makeCreatureId(source: string, name: string): CreatureId {
 	const slug = name
 		.toLowerCase()
-		.replace(/[^a-z0-9]+/g, "-")
-		.replace(/(^-|-$)/g, "");
+		.replaceAll(/[^a-z0-9]+/g, "-")
+		.replaceAll(/(^-|-$)/g, "");
 	return creatureId(`${source.toLowerCase()}:${slug}`);
 }
 
@@ -383,8 +386,7 @@ export function normalizeBestiary(raw: { monster: RawMonster[] }): Creature[] {
 	// Filter out _copy entries (reference another source's monster) and
 	// monsters missing required fields (ac, hp, size, type)
 	const monsters = raw.monster.filter((m) => {
-		// biome-ignore lint/suspicious/noExplicitAny: raw JSON may have _copy field
-		if ((m as any)._copy) return false;
+		if (m._copy) return false;
 		return (
 			Array.isArray(m.ac) &&
 			m.ac.length > 0 &&

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

@@ -3,7 +3,7 @@ import { type IDBPDatabase, openDB } from "idb";
 
 const DB_NAME = "initiative-bestiary";
 const STORE_NAME = "sources";
-const DB_VERSION = 1;
+const DB_VERSION = 2;
 
 export interface CachedSourceInfo {
 	readonly sourceCode: string;
@@ -32,12 +32,16 @@ async function getDb(): Promise<IDBPDatabase | null> {
 
 	try {
 		db = await openDB(DB_NAME, DB_VERSION, {
-			upgrade(database) {
-				if (!database.objectStoreNames.contains(STORE_NAME)) {
+			upgrade(database, oldVersion, _newVersion, transaction) {
+				if (oldVersion < 1) {
 					database.createObjectStore(STORE_NAME, {
 						keyPath: "sourceCode",
 					});
 				}
+				if (oldVersion < 2 && database.objectStoreNames.contains(STORE_NAME)) {
+					// Clear cached creatures to pick up improved tag processing
+					transaction.objectStore(STORE_NAME).clear();
+				}
 			},
 		});
 		return db;

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

@@ -14,6 +14,15 @@ const ATKR_MAP: Record<string, string> = {
 	"r,m": "Melee or Ranged Attack Roll:",
 };
 
+const ATK_MAP: Record<string, string> = {
+	mw: "Melee Weapon Attack:",
+	rw: "Ranged Weapon Attack:",
+	ms: "Melee Spell Attack:",
+	rs: "Ranged Spell Attack:",
+	"mw,rw": "Melee or Ranged Weapon Attack:",
+	"rw,mw": "Melee or Ranged Weapon Attack:",
+};
+
 /**
  * Strips 5etools {@tag ...} markup from text, converting to plain readable text.
  *
@@ -25,55 +34,63 @@ export function stripTags(text: string): string {
 	let result = text;
 
 	// {@h} → "Hit: "
-	result = result.replace(/\{@h\}/g, "Hit: ");
+	result = result.replaceAll("{@h}", "Hit: ");
 
 	// {@hom} → "Hit or Miss: "
-	result = result.replace(/\{@hom\}/g, "Hit or Miss: ");
+	result = result.replaceAll("{@hom}", "Hit or Miss: ");
 
 	// {@actTrigger} → "Trigger:"
-	result = result.replace(/\{@actTrigger\}/g, "Trigger:");
+	result = result.replaceAll("{@actTrigger}", "Trigger:");
 
 	// {@actResponse} → "Response:"
-	result = result.replace(/\{@actResponse\}/g, "Response:");
+	result = result.replaceAll("{@actResponse}", "Response:");
 
 	// {@actSaveSuccess} → "Success:"
-	result = result.replace(/\{@actSaveSuccess\}/g, "Success:");
+	result = result.replaceAll("{@actSaveSuccess}", "Success:");
 
 	// {@actSaveSuccessOrFail} → handled below as parameterized
 
 	// {@recharge 5} → "(Recharge 5-6)", {@recharge} → "(Recharge 6)"
-	result = result.replace(/\{@recharge\s+(\d)\}/g, "(Recharge $1-6)");
-	result = result.replace(/\{@recharge\}/g, "(Recharge 6)");
+	result = result.replaceAll(/\{@recharge\s+(\d)\}/g, "(Recharge $1-6)");
+	result = result.replaceAll("{@recharge}", "(Recharge 6)");
 
 	// {@dc N} → "DC N"
-	result = result.replace(/\{@dc\s+(\d+)\}/g, "DC $1");
+	result = result.replaceAll(/\{@dc\s+(\d+)\}/g, "DC $1");
 
 	// {@hit N} → "+N"
-	result = result.replace(/\{@hit\s+(\d+)\}/g, "+$1");
+	result = result.replaceAll(/\{@hit\s+(\d+)\}/g, "+$1");
 
-	// {@atkr type} → mapped attack roll text
-	result = result.replace(/\{@atkr\s+([^}]+)\}/g, (_, type: string) => {
-		return ATKR_MAP[type.trim()] ?? `Attack Roll:`;
+	// {@atkr type} → mapped attack roll text (2024 rules)
+	result = result.replaceAll(/\{@atkr\s+([^}]+)\}/g, (_, type: string) => {
+		return ATKR_MAP[type.trim()] ?? "Attack Roll:";
+	});
+
+	// {@atk type} → mapped attack type text (pre-2024 data)
+	result = result.replaceAll(/\{@atk\s+([^}]+)\}/g, (_, type: string) => {
+		return ATK_MAP[type.trim()] ?? "Attack:";
 	});
 
 	// {@actSave ability} → "Ability saving throw"
-	result = result.replace(/\{@actSave\s+([^}]+)\}/g, (_, ability: string) => {
-		const name = ABILITY_MAP[ability.trim().toLowerCase()];
-		return name ? `${name} saving throw` : `${ability} saving throw`;
-	});
+	result = result.replaceAll(
+		/\{@actSave\s+([^}]+)\}/g,
+		(_, ability: string) => {
+			const name = ABILITY_MAP[ability.trim().toLowerCase()];
+			return name ? `${name} saving throw` : `${ability} saving throw`;
+		},
+	);
 
 	// {@actSaveFail} → "Failure:" or {@actSaveFail N} → "Failure by N or More:"
-	result = result.replace(
+	result = result.replaceAll(
 		/\{@actSaveFail\s+(\d+)\}/g,
 		"Failure by $1 or More:",
 	);
-	result = result.replace(/\{@actSaveFail\}/g, "Failure:");
+	result = result.replaceAll("{@actSaveFail}", "Failure:");
 
 	// {@actSaveSuccessOrFail} → keep as-is label
-	result = result.replace(/\{@actSaveSuccessOrFail\}/g, "Success or Failure:");
+	result = result.replaceAll("{@actSaveSuccessOrFail}", "Success or Failure:");
 
 	// {@actSaveFailBy N} → "Failure by N or More:"
-	result = result.replace(
+	result = result.replaceAll(
 		/\{@actSaveFailBy\s+(\d+)\}/g,
 		"Failure by $1 or More:",
 	);
@@ -81,7 +98,7 @@ export function stripTags(text: string): string {
 	// Generic tags: {@tag Display|Source|...} → Display (first segment before |)
 	// Covers: spell, condition, damage, dice, variantrule, action, skill,
 	//         creature, hazard, status, plus any unknown tags
-	result = result.replace(
+	result = result.replaceAll(
 		/\{@(\w+)\s+([^}]+)\}/g,
 		(_, tag: string, content: string) => {
 			// For tags with Display|Source format, extract first segment

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

@@ -0,0 +1,121 @@
+// @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 { AllProviders } from "../../__tests__/test-providers.js";
+import { ActionBar } from "../action-bar.js";
+
+// Mock persistence — no localStorage interaction
+vi.mock("../../persistence/encounter-storage.js", () => ({
+	loadEncounter: () => null,
+	saveEncounter: () => {},
+}));
+
+vi.mock("../../persistence/player-character-storage.js", () => ({
+	loadPlayerCharacters: () => [],
+	savePlayerCharacters: () => {},
+}));
+
+// Mock bestiary — no IndexedDB or JSON index
+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,
+}));
+
+// DOM API stubs — jsdom doesn't implement these
+beforeAll(() => {
+	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);
+
+function renderBar(props: Partial<Parameters<typeof ActionBar>[0]> = {}) {
+	return render(<ActionBar {...props} />, { wrapper: AllProviders });
+}
+
+describe("ActionBar", () => {
+	it("renders input with placeholder '+ Add combatants'", () => {
+		renderBar();
+		expect(screen.getByPlaceholderText("+ Add combatants")).toBeInTheDocument();
+	});
+
+	it("submitting with a name adds a combatant", async () => {
+		const user = userEvent.setup();
+		renderBar();
+		const input = screen.getByPlaceholderText("+ Add combatants");
+		await user.type(input, "Goblin");
+		// The Add button appears when name >= 2 chars and no suggestions
+		const addButton = screen.getByRole("button", { name: "Add" });
+		await user.click(addButton);
+		// Input is cleared after adding (context handles the state)
+		expect(input).toHaveValue("");
+	});
+
+	it("submitting with empty name does nothing", async () => {
+		const user = userEvent.setup();
+		renderBar();
+		// Submit the form directly (Enter on empty input)
+		const input = screen.getByPlaceholderText("+ Add combatants");
+		await user.type(input, "{Enter}");
+		// Input stays empty, no error
+		expect(input).toHaveValue("");
+	});
+
+	it("shows custom fields (Init, AC, MaxHP) when name >= 2 chars and no bestiary suggestions", async () => {
+		const user = userEvent.setup();
+		renderBar();
+		const input = screen.getByPlaceholderText("+ Add combatants");
+		await user.type(input, "Go");
+		expect(screen.getByPlaceholderText("Init")).toBeInTheDocument();
+		expect(screen.getByPlaceholderText("AC")).toBeInTheDocument();
+		expect(screen.getByPlaceholderText("MaxHP")).toBeInTheDocument();
+	});
+
+	it("shows Add button when name >= 2 chars and no suggestions", async () => {
+		const user = userEvent.setup();
+		renderBar();
+		const input = screen.getByPlaceholderText("+ Add combatants");
+		await user.type(input, "Go");
+		expect(screen.getByRole("button", { name: "Add" })).toBeInTheDocument();
+	});
+
+	it("does not show roll all initiative button when no creature combatants", () => {
+		renderBar();
+		expect(
+			screen.queryByRole("button", { name: "Roll all initiative" }),
+		).not.toBeInTheDocument();
+	});
+
+	it("shows overflow menu items", () => {
+		renderBar({ onManagePlayers: vi.fn() });
+		// The overflow menu should be present (it contains Player Characters etc.)
+		expect(
+			screen.getByRole("button", { name: "More actions" }),
+		).toBeInTheDocument();
+	});
+});

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

@@ -0,0 +1,300 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import { type CreatureId, combatantId } 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 { AllProviders } from "../../__tests__/test-providers.js";
+import { CombatantRow } from "../combatant-row.js";
+import { PLAYER_COLOR_HEX } from "../player-icon-map.js";
+
+const TEMP_HP_REGEX = /^\+\d/;
+
+// Mock persistence — no localStorage interaction
+vi.mock("../../persistence/encounter-storage.js", () => ({
+	loadEncounter: () => null,
+	saveEncounter: () => {},
+}));
+
+vi.mock("../../persistence/player-character-storage.js", () => ({
+	loadPlayerCharacters: () => [],
+	savePlayerCharacters: () => {},
+}));
+
+// Mock bestiary — no IndexedDB or JSON index
+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,
+}));
+
+// DOM API stubs
+beforeAll(() => {
+	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);
+
+function renderRow(
+	overrides: Partial<{
+		combatant: Parameters<typeof CombatantRow>[0]["combatant"];
+		isActive: boolean;
+	}> = {},
+) {
+	const combatant = overrides.combatant ?? {
+		id: combatantId("1"),
+		name: "Goblin",
+		initiative: 15,
+		maxHp: 10,
+		currentHp: 10,
+		ac: 13,
+	};
+	return render(
+		<CombatantRow
+			combatant={combatant}
+			isActive={overrides.isActive ?? false}
+		/>,
+		{ wrapper: AllProviders },
+	);
+}
+
+describe("CombatantRow", () => {
+	it("renders combatant name", () => {
+		renderRow();
+		expect(screen.getByText("Goblin")).toBeInTheDocument();
+	});
+
+	it("renders initiative value", () => {
+		renderRow();
+		expect(screen.getByText("15")).toBeInTheDocument();
+	});
+
+	it("renders current HP", () => {
+		renderRow({
+			combatant: {
+				id: combatantId("1"),
+				name: "Goblin",
+				maxHp: 10,
+				currentHp: 7,
+			},
+		});
+		expect(screen.getByText("7")).toBeInTheDocument();
+	});
+
+	it("active combatant gets active border styling", () => {
+		const { container } = renderRow({ isActive: true });
+		const row = container.firstElementChild;
+		expect(row?.className).toContain("border-active-row-border");
+	});
+
+	it("unconscious combatant (currentHp === 0) gets dimmed styling", () => {
+		renderRow({
+			combatant: {
+				id: combatantId("1"),
+				name: "Goblin",
+				maxHp: 10,
+				currentHp: 0,
+			},
+		});
+		// The name area should have opacity-50
+		const nameEl = screen.getByText("Goblin");
+		const nameContainer = nameEl.closest(".opacity-50");
+		expect(nameContainer).not.toBeNull();
+	});
+
+	it("shows 'Max' placeholder when no maxHp is set", () => {
+		renderRow({
+			combatant: {
+				id: combatantId("1"),
+				name: "Goblin",
+			},
+		});
+		expect(screen.getByText("Max")).toBeInTheDocument();
+	});
+
+	it("shows concentration icon when isConcentrating is true", () => {
+		renderRow({
+			combatant: {
+				id: combatantId("1"),
+				name: "Goblin",
+				isConcentrating: true,
+			},
+		});
+		const concButton = screen.getByRole("button", {
+			name: "Toggle concentration",
+		});
+		expect(concButton.className).toContain("text-purple-400");
+	});
+
+	it("shows player character icon and color when set", () => {
+		const { container } = renderRow({
+			combatant: {
+				id: combatantId("1"),
+				name: "Aragorn",
+				color: "red",
+				icon: "sword",
+			},
+		});
+		// The icon should be rendered with the player color
+		const svgIcon = container.querySelector("svg[style]");
+		expect(svgIcon).not.toBeNull();
+		expect(svgIcon).toHaveStyle({ color: PLAYER_COLOR_HEX.red });
+	});
+
+	it("remove button removes after confirmation", async () => {
+		const user = userEvent.setup();
+		renderRow();
+		const removeBtn = screen.getByRole("button", {
+			name: "Remove combatant",
+		});
+		// First click enters confirm state
+		await user.click(removeBtn);
+		// Second click confirms
+		const confirmBtn = screen.getByRole("button", {
+			name: "Confirm remove combatant",
+		});
+		await user.click(confirmBtn);
+		// After confirming, the button returns to its initial state
+		expect(
+			screen.queryByRole("button", { name: "Confirm remove combatant" }),
+		).not.toBeInTheDocument();
+	});
+
+	it("shows d20 roll button when initiative is undefined and combatant has creatureId", () => {
+		renderRow({
+			combatant: {
+				id: combatantId("1"),
+				name: "Goblin",
+				creatureId: "srd:goblin" as CreatureId,
+			},
+		});
+		expect(
+			screen.getByRole("button", { name: "Roll initiative" }),
+		).toBeInTheDocument();
+	});
+
+	describe("concentration pulse", () => {
+		it("pulses when currentHp drops on a concentrating combatant", () => {
+			const combatant = {
+				id: combatantId("1"),
+				name: "Goblin",
+				maxHp: 20,
+				currentHp: 15,
+				isConcentrating: true,
+			};
+			const { rerender, container } = renderRow({ combatant });
+			rerender(
+				<CombatantRow
+					combatant={{ ...combatant, currentHp: 10 }}
+					isActive={false}
+				/>,
+			);
+			const row = container.firstElementChild;
+			expect(row?.className).toContain("animate-concentration-pulse");
+		});
+
+		it("does not pulse when not concentrating", () => {
+			const combatant = {
+				id: combatantId("1"),
+				name: "Goblin",
+				maxHp: 20,
+				currentHp: 15,
+				isConcentrating: false,
+			};
+			const { rerender, container } = renderRow({ combatant });
+			rerender(
+				<CombatantRow
+					combatant={{ ...combatant, currentHp: 10 }}
+					isActive={false}
+				/>,
+			);
+			const row = container.firstElementChild;
+			expect(row?.className).not.toContain("animate-concentration-pulse");
+		});
+
+		it("pulses when temp HP absorbs all damage on a concentrating combatant", () => {
+			const combatant = {
+				id: combatantId("1"),
+				name: "Goblin",
+				maxHp: 20,
+				currentHp: 15,
+				tempHp: 8,
+				isConcentrating: true,
+			};
+			const { rerender, container } = renderRow({ combatant });
+			// Temp HP absorbs all damage, currentHp unchanged
+			rerender(
+				<CombatantRow
+					combatant={{ ...combatant, tempHp: 3 }}
+					isActive={false}
+				/>,
+			);
+			const row = container.firstElementChild;
+			expect(row?.className).toContain("animate-concentration-pulse");
+		});
+	});
+
+	describe("temp HP display", () => {
+		it("shows +N when combatant has temp HP", () => {
+			renderRow({
+				combatant: {
+					id: combatantId("1"),
+					name: "Goblin",
+					maxHp: 20,
+					currentHp: 15,
+					tempHp: 5,
+				},
+			});
+			expect(screen.getByText("+5")).toBeInTheDocument();
+		});
+
+		it("does not show +N when combatant has no temp HP", () => {
+			renderRow({
+				combatant: {
+					id: combatantId("1"),
+					name: "Goblin",
+					maxHp: 20,
+					currentHp: 15,
+				},
+			});
+			expect(screen.queryByText(TEMP_HP_REGEX)).not.toBeInTheDocument();
+		});
+
+		it("temp HP display uses cyan color", () => {
+			renderRow({
+				combatant: {
+					id: combatantId("1"),
+					name: "Goblin",
+					maxHp: 20,
+					currentHp: 15,
+					tempHp: 8,
+				},
+			});
+			const tempHpEl = screen.getByText("+8");
+			expect(tempHpEl.className).toContain("text-cyan-400");
+		});
+	});
+});

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

@@ -0,0 +1,72 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import { CONDITION_DEFINITIONS, type ConditionId } from "@initiative/domain";
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { createRef, type RefObject } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { RulesEditionProvider } from "../../contexts/index.js";
+import { ConditionPicker } from "../condition-picker";
+
+afterEach(cleanup);
+
+function renderPicker(
+	overrides: Partial<{
+		activeConditions: readonly ConditionId[];
+		onToggle: (conditionId: ConditionId) => void;
+		onClose: () => void;
+	}> = {},
+) {
+	const onToggle = overrides.onToggle ?? vi.fn();
+	const onClose = overrides.onClose ?? vi.fn();
+	const anchorRef = createRef<HTMLElement>() as RefObject<HTMLElement>;
+	const anchor = document.createElement("div");
+	document.body.appendChild(anchor);
+	(anchorRef as { current: HTMLElement }).current = anchor;
+	const result = render(
+		<RulesEditionProvider>
+			<ConditionPicker
+				anchorRef={anchorRef}
+				activeConditions={overrides.activeConditions ?? []}
+				onToggle={onToggle}
+				onClose={onClose}
+			/>
+		</RulesEditionProvider>,
+	);
+	return { ...result, onToggle, onClose };
+}
+
+describe("ConditionPicker", () => {
+	it("renders all condition definitions from domain", () => {
+		renderPicker();
+		for (const def of CONDITION_DEFINITIONS) {
+			expect(screen.getByText(def.label)).toBeInTheDocument();
+		}
+	});
+
+	it("active conditions are visually distinguished", () => {
+		renderPicker({ activeConditions: ["blinded"] });
+		const blindedButton = screen.getByText("Blinded").closest("button");
+		expect(blindedButton?.className).toContain("bg-card/50");
+	});
+
+	it("clicking a condition calls onToggle with that condition's ID", async () => {
+		const user = userEvent.setup();
+		const { onToggle } = renderPicker();
+		await user.click(screen.getByText("Poisoned"));
+		expect(onToggle).toHaveBeenCalledWith("poisoned");
+	});
+
+	it("non-active conditions render with muted styling", () => {
+		renderPicker({ activeConditions: [] });
+		const label = screen.getByText("Charmed");
+		expect(label.className).toContain("text-muted-foreground");
+	});
+
+	it("active condition labels use foreground color", () => {
+		renderPicker({ activeConditions: ["charmed"] });
+		const label = screen.getByText("Charmed");
+		expect(label.className).toContain("text-foreground");
+	});
+});

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

@@ -0,0 +1,148 @@
+// @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 { HpAdjustPopover } from "../hp-adjust-popover";
+
+afterEach(cleanup);
+
+function renderPopover(
+	overrides: Partial<{
+		onAdjust: (delta: number) => void;
+		onSetTempHp: (value: number) => void;
+		onClose: () => void;
+	}> = {},
+) {
+	const onAdjust = overrides.onAdjust ?? vi.fn();
+	const onSetTempHp = overrides.onSetTempHp ?? vi.fn();
+	const onClose = overrides.onClose ?? vi.fn();
+	const result = render(
+		<HpAdjustPopover
+			onAdjust={onAdjust}
+			onSetTempHp={onSetTempHp}
+			onClose={onClose}
+		/>,
+	);
+	return { ...result, onAdjust, onSetTempHp, onClose };
+}
+
+describe("HpAdjustPopover", () => {
+	it("renders input with placeholder 'HP'", () => {
+		renderPopover();
+		expect(screen.getByPlaceholderText("HP")).toBeInTheDocument();
+	});
+
+	it("damage and heal buttons are disabled when input is empty", () => {
+		renderPopover();
+		expect(screen.getByRole("button", { name: "Apply damage" })).toBeDisabled();
+		expect(
+			screen.getByRole("button", { name: "Apply healing" }),
+		).toBeDisabled();
+	});
+
+	it("damage and heal buttons are disabled when input is '0'", async () => {
+		const user = userEvent.setup();
+		renderPopover();
+		await user.type(screen.getByPlaceholderText("HP"), "0");
+		expect(screen.getByRole("button", { name: "Apply damage" })).toBeDisabled();
+		expect(
+			screen.getByRole("button", { name: "Apply healing" }),
+		).toBeDisabled();
+	});
+
+	it("typing a valid number enables both buttons", async () => {
+		const user = userEvent.setup();
+		renderPopover();
+		await user.type(screen.getByPlaceholderText("HP"), "5");
+		expect(
+			screen.getByRole("button", { name: "Apply damage" }),
+		).not.toBeDisabled();
+		expect(
+			screen.getByRole("button", { name: "Apply healing" }),
+		).not.toBeDisabled();
+	});
+
+	it("clicking damage button calls onAdjust with negative value and onClose", async () => {
+		const user = userEvent.setup();
+		const { onAdjust, onClose } = renderPopover();
+		await user.type(screen.getByPlaceholderText("HP"), "7");
+		await user.click(screen.getByRole("button", { name: "Apply damage" }));
+		expect(onAdjust).toHaveBeenCalledWith(-7);
+		expect(onClose).toHaveBeenCalled();
+	});
+
+	it("clicking heal button calls onAdjust with positive value and onClose", async () => {
+		const user = userEvent.setup();
+		const { onAdjust, onClose } = renderPopover();
+		await user.type(screen.getByPlaceholderText("HP"), "3");
+		await user.click(screen.getByRole("button", { name: "Apply healing" }));
+		expect(onAdjust).toHaveBeenCalledWith(3);
+		expect(onClose).toHaveBeenCalled();
+	});
+
+	it("Enter key applies damage (negative)", async () => {
+		const user = userEvent.setup();
+		const { onAdjust, onClose } = renderPopover();
+		const input = screen.getByPlaceholderText("HP");
+		await user.type(input, "4");
+		await user.keyboard("{Enter}");
+		expect(onAdjust).toHaveBeenCalledWith(-4);
+		expect(onClose).toHaveBeenCalled();
+	});
+
+	it("Shift+Enter applies healing (positive)", async () => {
+		const user = userEvent.setup();
+		const { onAdjust, onClose } = renderPopover();
+		const input = screen.getByPlaceholderText("HP");
+		await user.type(input, "6");
+		await user.keyboard("{Shift>}{Enter}{/Shift}");
+		expect(onAdjust).toHaveBeenCalledWith(6);
+		expect(onClose).toHaveBeenCalled();
+	});
+
+	it("Escape key calls onClose", async () => {
+		const user = userEvent.setup();
+		const { onClose } = renderPopover();
+		const input = screen.getByPlaceholderText("HP");
+		await user.type(input, "2");
+		await user.keyboard("{Escape}");
+		expect(onClose).toHaveBeenCalled();
+	});
+
+	it("only accepts digit characters in input", async () => {
+		const user = userEvent.setup();
+		renderPopover();
+		const input = screen.getByPlaceholderText("HP");
+		await user.type(input, "12abc34");
+		expect(input).toHaveValue("1234");
+	});
+
+	describe("temp HP", () => {
+		it("shield button calls onSetTempHp with entered value and closes", async () => {
+			const user = userEvent.setup();
+			const { onSetTempHp, onClose } = renderPopover();
+			await user.type(screen.getByPlaceholderText("HP"), "8");
+			await user.click(screen.getByRole("button", { name: "Set temp HP" }));
+			expect(onSetTempHp).toHaveBeenCalledWith(8);
+			expect(onClose).toHaveBeenCalled();
+		});
+
+		it("shield button is disabled when input is empty", () => {
+			renderPopover();
+			expect(
+				screen.getByRole("button", { name: "Set temp HP" }),
+			).toBeDisabled();
+		});
+
+		it("shield button is disabled when input is '0'", async () => {
+			const user = userEvent.setup();
+			renderPopover();
+			await user.type(screen.getByPlaceholderText("HP"), "0");
+			expect(
+				screen.getByRole("button", { name: "Set temp HP" }),
+			).toBeDisabled();
+		});
+	});
+});

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

@@ -0,0 +1,150 @@
+// @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";
+
+vi.mock("../../adapters/bestiary-cache.js", () => ({
+	getCachedSources: vi.fn(),
+	clearSource: vi.fn(),
+	clearAll: vi.fn(),
+}));
+
+// Mock the context module
+vi.mock("../../contexts/bestiary-context.js", () => ({
+	useBestiaryContext: vi.fn(),
+}));
+
+import * as bestiaryCache from "../../adapters/bestiary-cache.js";
+import { useBestiaryContext } from "../../contexts/bestiary-context.js";
+import { SourceManager } from "../source-manager.js";
+
+const mockGetCachedSources = vi.mocked(bestiaryCache.getCachedSources);
+const mockClearSource = vi.mocked(bestiaryCache.clearSource);
+const mockClearAll = vi.mocked(bestiaryCache.clearAll);
+const mockUseBestiaryContext = vi.mocked(useBestiaryContext);
+
+afterEach(() => {
+	cleanup();
+	vi.clearAllMocks();
+});
+
+function setupMockContext() {
+	const refreshCache = vi.fn().mockResolvedValue(undefined);
+	mockUseBestiaryContext.mockReturnValue({
+		refreshCache,
+		search: vi.fn().mockReturnValue([]),
+		getCreature: vi.fn(),
+		isLoaded: true,
+		isSourceCached: vi.fn().mockResolvedValue(false),
+		fetchAndCacheSource: vi.fn(),
+		uploadAndCacheSource: vi.fn(),
+	} as ReturnType<typeof useBestiaryContext>);
+	return { refreshCache };
+}
+
+describe("SourceManager", () => {
+	it("shows 'No cached sources' empty state when no sources", async () => {
+		setupMockContext();
+		mockGetCachedSources.mockResolvedValue([]);
+		render(<SourceManager />);
+		await waitFor(() => {
+			expect(screen.getByText("No cached sources")).toBeInTheDocument();
+		});
+	});
+
+	it("lists cached sources with display name and creature count", async () => {
+		setupMockContext();
+		mockGetCachedSources.mockResolvedValue([
+			{
+				sourceCode: "mm",
+				displayName: "Monster Manual",
+				creatureCount: 300,
+				cachedAt: Date.now(),
+			},
+			{
+				sourceCode: "vgm",
+				displayName: "Volo's Guide",
+				creatureCount: 100,
+				cachedAt: Date.now(),
+			},
+		]);
+		render(<SourceManager />);
+		await waitFor(() => {
+			expect(screen.getByText("Monster Manual")).toBeInTheDocument();
+		});
+		expect(screen.getByText("300 creatures")).toBeInTheDocument();
+		expect(screen.getByText("Volo's Guide")).toBeInTheDocument();
+		expect(screen.getByText("100 creatures")).toBeInTheDocument();
+	});
+
+	it("Clear All button calls cache clear and refreshCache", async () => {
+		const user = userEvent.setup();
+		const { refreshCache } = setupMockContext();
+		mockGetCachedSources
+			.mockResolvedValueOnce([
+				{
+					sourceCode: "mm",
+					displayName: "Monster Manual",
+					creatureCount: 300,
+					cachedAt: Date.now(),
+				},
+			])
+			.mockResolvedValue([]);
+		mockClearAll.mockResolvedValue(undefined);
+		render(<SourceManager />);
+
+		await waitFor(() => {
+			expect(screen.getByText("Monster Manual")).toBeInTheDocument();
+		});
+
+		await user.click(screen.getByRole("button", { name: "Clear All" }));
+		await waitFor(() => {
+			expect(mockClearAll).toHaveBeenCalled();
+		});
+		expect(refreshCache).toHaveBeenCalled();
+	});
+
+	it("individual source delete button calls clear for that source", async () => {
+		const user = userEvent.setup();
+		const { refreshCache } = setupMockContext();
+		mockGetCachedSources
+			.mockResolvedValueOnce([
+				{
+					sourceCode: "mm",
+					displayName: "Monster Manual",
+					creatureCount: 300,
+					cachedAt: Date.now(),
+				},
+				{
+					sourceCode: "vgm",
+					displayName: "Volo's Guide",
+					creatureCount: 100,
+					cachedAt: Date.now(),
+				},
+			])
+			.mockResolvedValue([
+				{
+					sourceCode: "vgm",
+					displayName: "Volo's Guide",
+					creatureCount: 100,
+					cachedAt: Date.now(),
+				},
+			]);
+		mockClearSource.mockResolvedValue(undefined);
+
+		render(<SourceManager />);
+		await waitFor(() => {
+			expect(screen.getByText("Monster Manual")).toBeInTheDocument();
+		});
+
+		await user.click(
+			screen.getByRole("button", { name: "Remove Monster Manual" }),
+		);
+		await waitFor(() => {
+			expect(mockClearSource).toHaveBeenCalledWith("mm");
+		});
+		expect(refreshCache).toHaveBeenCalled();
+	});
+});

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

@@ -5,11 +5,23 @@ import type { Encounter } from "@initiative/domain";
 import { combatantId } from "@initiative/domain";
 import { cleanup, render, screen } from "@testing-library/react";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { TurnNavigation } from "../turn-navigation";
 
-afterEach(cleanup);
+// Mock the context module
+vi.mock("../../contexts/encounter-context.js", () => ({
+	useEncounterContext: vi.fn(),
+}));
 
-function renderNav(overrides: Partial<Encounter> = {}) {
+import { useEncounterContext } from "../../contexts/encounter-context.js";
+import { TurnNavigation } from "../turn-navigation.js";
+
+const mockUseEncounterContext = vi.mocked(useEncounterContext);
+
+afterEach(() => {
+	cleanup();
+	vi.clearAllMocks();
+});
+
+function mockContext(overrides: Partial<Encounter> = {}) {
 	const encounter: Encounter = {
 		combatants: [
 			{ id: combatantId("1"), name: "Goblin" },
@@ -20,16 +32,49 @@ function renderNav(overrides: Partial<Encounter> = {}) {
 		...overrides,
 	};
 
-	return render(
-		<TurnNavigation
-			encounter={encounter}
-			onAdvanceTurn={vi.fn()}
-			onRetreatTurn={vi.fn()}
-			onClearEncounter={vi.fn()}
-			onRollAllInitiative={vi.fn()}
-			onOpenSourceManager={vi.fn()}
-		/>,
+	const value = {
+		encounter,
+		advanceTurn: vi.fn(),
+		retreatTurn: vi.fn(),
+		clearEncounter: vi.fn(),
+		isEmpty: encounter.combatants.length === 0,
+		hasCreatureCombatants: false,
+		canRollAllInitiative: false,
+		addCombatant: vi.fn(),
+		removeCombatant: vi.fn(),
+		editCombatant: vi.fn(),
+		setInitiative: vi.fn(),
+		setHp: vi.fn(),
+		adjustHp: vi.fn(),
+		setTempHp: vi.fn(),
+		hasTempHp: false,
+		setAc: vi.fn(),
+		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: [],
+	};
+
+	mockUseEncounterContext.mockReturnValue(
+		value as ReturnType<typeof useEncounterContext>,
 	);
+	return value;
+}
+
+function renderNav(overrides: Partial<Encounter> = {}) {
+	mockContext(overrides);
+	return render(<TurnNavigation />);
 }
 
 describe("TurnNavigation", () => {
@@ -51,88 +96,39 @@ describe("TurnNavigation", () => {
 
 		it("does not render an em dash between round and name", () => {
 			const { container } = renderNav();
-			expect(container.textContent).not.toContain("—");
+			expect(container.textContent).not.toContain("\u2014");
 		});
 
 		it("round badge and combatant name are siblings in the center area", () => {
 			renderNav();
 			const badge = screen.getByText("R1");
 			const name = screen.getByText("Goblin");
-			expect(badge.parentElement).toBe(name.parentElement);
+			// badge text is inside inner span > outer span, name is a direct child
+			expect(badge.closest(".flex")).toBe(name.parentElement);
 		});
 
 		it("updates the round badge when round changes", () => {
-			const { rerender } = render(
-				<TurnNavigation
-					encounter={{
-						combatants: [{ id: combatantId("1"), name: "Goblin" }],
-						activeIndex: 0,
-						roundNumber: 2,
-					}}
-					onAdvanceTurn={vi.fn()}
-					onRetreatTurn={vi.fn()}
-					onClearEncounter={vi.fn()}
-					onRollAllInitiative={vi.fn()}
-					onOpenSourceManager={vi.fn()}
-				/>,
-			);
+			mockContext({ roundNumber: 2 });
+			const { rerender } = render(<TurnNavigation />);
 			expect(screen.getByText("R2")).toBeInTheDocument();
 
-			rerender(
-				<TurnNavigation
-					encounter={{
-						combatants: [{ id: combatantId("1"), name: "Goblin" }],
-						activeIndex: 0,
-						roundNumber: 3,
-					}}
-					onAdvanceTurn={vi.fn()}
-					onRetreatTurn={vi.fn()}
-					onClearEncounter={vi.fn()}
-					onRollAllInitiative={vi.fn()}
-					onOpenSourceManager={vi.fn()}
-				/>,
-			);
+			mockContext({ roundNumber: 3 });
+			rerender(<TurnNavigation />);
 			expect(screen.getByText("R3")).toBeInTheDocument();
 			expect(screen.queryByText("R2")).not.toBeInTheDocument();
 		});
 
 		it("renders the next combatant name when turn advances", () => {
-			const { rerender } = render(
-				<TurnNavigation
-					encounter={{
-						combatants: [
-							{ id: combatantId("1"), name: "Goblin" },
-							{ id: combatantId("2"), name: "Conjurer" },
-						],
-						activeIndex: 0,
-						roundNumber: 1,
-					}}
-					onAdvanceTurn={vi.fn()}
-					onRetreatTurn={vi.fn()}
-					onClearEncounter={vi.fn()}
-					onRollAllInitiative={vi.fn()}
-					onOpenSourceManager={vi.fn()}
-				/>,
-			);
+			const combatants = [
+				{ id: combatantId("1"), name: "Goblin" },
+				{ id: combatantId("2"), name: "Conjurer" },
+			];
+			mockContext({ combatants, activeIndex: 0 });
+			const { rerender } = render(<TurnNavigation />);
 			expect(screen.getByText("Goblin")).toBeInTheDocument();
 
-			rerender(
-				<TurnNavigation
-					encounter={{
-						combatants: [
-							{ id: combatantId("1"), name: "Goblin" },
-							{ id: combatantId("2"), name: "Conjurer" },
-						],
-						activeIndex: 1,
-						roundNumber: 1,
-					}}
-					onAdvanceTurn={vi.fn()}
-					onRetreatTurn={vi.fn()}
-					onClearEncounter={vi.fn()}
-					onRollAllInitiative={vi.fn()}
-					onOpenSourceManager={vi.fn()}
-				/>,
-			);
+			mockContext({ combatants, activeIndex: 1 });
+			rerender(<TurnNavigation />);
 			expect(screen.getByText("Conjurer")).toBeInTheDocument();
 		});
 	});
@@ -173,16 +169,6 @@ describe("TurnNavigation", () => {
 			expect(
 				screen.getByRole("button", { name: "Next turn" }),
 			).toBeInTheDocument();
-			expect(
-				screen.getByRole("button", {
-					name: "Roll all initiative",
-				}),
-			).toBeInTheDocument();
-			expect(
-				screen.getByRole("button", {
-					name: "Manage cached sources",
-				}),
-			).toBeInTheDocument();
 		});
 
 		it("renders a 40-character name without truncation class issues", () => {

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

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

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

@@ -1,36 +1,41 @@
 import { Loader2 } from "lucide-react";
-import { useState } from "react";
+import { useId, useState } from "react";
 import { getAllSourceCodes } from "../adapters/bestiary-index-adapter.js";
-import type { BulkImportState } from "../hooks/use-bulk-import.js";
+import { useBestiaryContext } from "../contexts/bestiary-context.js";
+import { useBulkImportContext } from "../contexts/bulk-import-context.js";
+import { useSidePanelContext } from "../contexts/side-panel-context.js";
 import { Button } from "./ui/button.js";
 import { Input } from "./ui/input.js";
 
 const DEFAULT_BASE_URL =
 	"https://raw.githubusercontent.com/5etools-mirror-3/5etools-src/main/data/bestiary/";
 
-interface BulkImportPromptProps {
-	importState: BulkImportState;
-	onStartImport: (baseUrl: string) => void;
-	onDone: () => void;
-}
+export function BulkImportPrompt() {
+	const { fetchAndCacheSource, isSourceCached, refreshCache } =
+		useBestiaryContext();
+	const { state: importState, startImport, reset } = useBulkImportContext();
+	const { dismissPanel } = useSidePanelContext();
 
-export function BulkImportPrompt({
-	importState,
-	onStartImport,
-	onDone,
-}: BulkImportPromptProps) {
 	const [baseUrl, setBaseUrl] = useState(DEFAULT_BASE_URL);
+	const baseUrlId = useId();
 	const totalSources = getAllSourceCodes().length;
 
+	const handleStart = (url: string) => {
+		startImport(url, fetchAndCacheSource, isSourceCached, refreshCache);
+	};
+
+	const handleDone = () => {
+		dismissPanel();
+		reset();
+	};
+
 	if (importState.status === "complete") {
 		return (
 			<div className="flex flex-col gap-4">
-				<div className="rounded-md border border-green-500/50 bg-green-500/10 px-3 py-2 text-sm text-green-400">
+				<div className="rounded-md border border-green-500/50 bg-green-500/10 px-3 py-2 text-green-400 text-sm">
 					All sources loaded
 				</div>
-				<Button size="sm" onClick={onDone}>
-					Done
-				</Button>
+				<Button onClick={handleDone}>Done</Button>
 			</div>
 		);
 	}
@@ -42,9 +47,7 @@ export function BulkImportPrompt({
 					Loaded {importState.completed}/{importState.total} sources (
 					{importState.failed} failed)
 				</div>
-				<Button size="sm" onClick={onDone}>
-					Done
-				</Button>
+				<Button onClick={handleDone}>Done</Button>
 			</div>
 		);
 	}
@@ -58,7 +61,7 @@ export function BulkImportPrompt({
 
 		return (
 			<div className="flex flex-col gap-4">
-				<div className="flex items-center gap-2 text-sm text-muted-foreground">
+				<div className="flex items-center gap-2 text-muted-foreground text-sm">
 					<Loader2 className="h-4 w-4 animate-spin" />
 					Loading sources... {processed}/{importState.total}
 				</div>
@@ -78,24 +81,20 @@ export function BulkImportPrompt({
 	return (
 		<div className="flex flex-col gap-4">
 			<div>
-				<h3 className="text-sm font-semibold text-foreground">
-					Bulk Import Sources
+				<h3 className="font-semibold text-foreground text-sm">
+					Import All Sources
 				</h3>
-				<p className="mt-1 text-xs text-muted-foreground">
-					Load stat block data for all {totalSources} sources at once. This will
-					download approximately 12.5 MB of data.
+				<p className="mt-1 text-muted-foreground text-xs">
+					Load stat block data for all {totalSources} sources at once.
 				</p>
 			</div>
 
 			<div className="flex flex-col gap-2">
-				<label
-					htmlFor="bulk-base-url"
-					className="text-xs text-muted-foreground"
-				>
+				<label htmlFor={baseUrlId} className="text-muted-foreground text-xs">
 					Base URL
 				</label>
 				<Input
-					id="bulk-base-url"
+					id={baseUrlId}
 					type="url"
 					value={baseUrl}
 					onChange={(e) => setBaseUrl(e.target.value)}
@@ -103,11 +102,7 @@ export function BulkImportPrompt({
 				/>
 			</div>
 
-			<Button
-				size="sm"
-				onClick={() => onStartImport(baseUrl)}
-				disabled={isDisabled}
-			>
+			<Button onClick={() => handleStart(baseUrl)} disabled={isDisabled}>
 				Load All
 			</Button>
 		</div>

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

@@ -0,0 +1,44 @@
+import { useBulkImportContext } from "../contexts/bulk-import-context.js";
+import { useSidePanelContext } from "../contexts/side-panel-context.js";
+import { Toast } from "./toast.js";
+
+export function BulkImportToasts() {
+	const { state, reset } = useBulkImportContext();
+	const { bulkImportMode, isRightPanelCollapsed } = useSidePanelContext();
+	const visible = !bulkImportMode || isRightPanelCollapsed;
+
+	if (!visible) return null;
+
+	if (state.status === "loading") {
+		return (
+			<Toast
+				message={`Loading sources... ${state.completed + state.failed}/${state.total}`}
+				progress={
+					state.total > 0 ? (state.completed + state.failed) / state.total : 0
+				}
+				onDismiss={() => {}}
+			/>
+		);
+	}
+
+	if (state.status === "complete") {
+		return (
+			<Toast
+				message="All sources loaded"
+				onDismiss={reset}
+				autoDismissMs={3000}
+			/>
+		);
+	}
+
+	if (state.status === "partial-failure") {
+		return (
+			<Toast
+				message={`Loaded ${state.completed}/${state.total} sources (${state.failed} failed)`}
+				onDismiss={reset}
+			/>
+		);
+	}
+
+	return null;
+}

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

@@ -9,18 +9,18 @@ interface ColorPaletteProps {
 
 const COLORS = [...VALID_PLAYER_COLORS] as string[];
 
-export function ColorPalette({ value, onChange }: ColorPaletteProps) {
+export function ColorPalette({ value, onChange }: Readonly<ColorPaletteProps>) {
 	return (
 		<div className="flex flex-wrap gap-2">
 			{COLORS.map((color) => (
 				<button
 					key={color}
 					type="button"
-					onClick={() => onChange(color)}
+					onClick={() => onChange(value === color ? "" : color)}
 					className={cn(
 						"h-8 w-8 rounded-full transition-all",
 						value === color
-							? "ring-2 ring-foreground ring-offset-2 ring-offset-background scale-110"
+							? "scale-110 ring-2 ring-foreground ring-offset-2 ring-offset-background"
 							: "hover:scale-110",
 					)}
 					style={{

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

@@ -1,20 +1,27 @@
 import {
 	type CombatantId,
 	type ConditionId,
+	type CreatureId,
 	deriveHpStatus,
 	type PlayerIcon,
+	type RollMode,
 } from "@initiative/domain";
-import { Brain, X } from "lucide-react";
+import { Brain, Pencil, X } from "lucide-react";
 import { type Ref, useCallback, useEffect, useRef, useState } from "react";
-import { cn } from "../lib/utils";
-import { AcShield } from "./ac-shield";
-import { ConditionPicker } from "./condition-picker";
-import { ConditionTags } from "./condition-tags";
-import { D20Icon } from "./d20-icon";
-import { HpAdjustPopover } from "./hp-adjust-popover";
-import { PLAYER_COLOR_HEX, PLAYER_ICON_MAP } from "./player-icon-map";
-import { ConfirmButton } from "./ui/confirm-button";
-import { Input } from "./ui/input";
+import { useEncounterContext } from "../contexts/encounter-context.js";
+import { useInitiativeRollsContext } from "../contexts/initiative-rolls-context.js";
+import { useSidePanelContext } from "../contexts/side-panel-context.js";
+import { useLongPress } from "../hooks/use-long-press.js";
+import { cn } from "../lib/utils.js";
+import { AcShield } from "./ac-shield.js";
+import { ConditionPicker } from "./condition-picker.js";
+import { ConditionTags } from "./condition-tags.js";
+import { D20Icon } from "./d20-icon.js";
+import { HpAdjustPopover } from "./hp-adjust-popover.js";
+import { PLAYER_COLOR_HEX, PLAYER_ICON_MAP } from "./player-icon-map.js";
+import { RollModeMenu } from "./roll-mode-menu.js";
+import { ConfirmButton } from "./ui/confirm-button.js";
+import { Input } from "./ui/input.js";
 
 interface Combatant {
 	readonly id: CombatantId;
@@ -22,45 +29,36 @@ interface Combatant {
 	readonly initiative?: number;
 	readonly maxHp?: number;
 	readonly currentHp?: number;
+	readonly tempHp?: number;
 	readonly ac?: number;
 	readonly conditions?: readonly ConditionId[];
 	readonly isConcentrating?: boolean;
 	readonly color?: string;
 	readonly icon?: string;
+	readonly creatureId?: CreatureId;
 }
 
 interface CombatantRowProps {
 	combatant: Combatant;
 	isActive: boolean;
-	onRename: (id: CombatantId, newName: string) => void;
-	onSetInitiative: (id: CombatantId, value: number | undefined) => void;
-	onRemove: (id: CombatantId) => void;
-	onSetHp: (id: CombatantId, maxHp: number | undefined) => void;
-	onAdjustHp: (id: CombatantId, delta: number) => void;
-	onSetAc: (id: CombatantId, value: number | undefined) => void;
-	onToggleCondition: (id: CombatantId, conditionId: ConditionId) => void;
-	onToggleConcentration: (id: CombatantId) => void;
-	onShowStatBlock?: () => void;
-	onRollInitiative?: (id: CombatantId) => void;
 }
 
 function EditableName({
 	name,
 	combatantId,
 	onRename,
-	onShowStatBlock,
-}: {
+	color,
+	onToggleStatBlock,
+}: Readonly<{
 	name: string;
 	combatantId: CombatantId;
 	onRename: (id: CombatantId, newName: string) => void;
-	onShowStatBlock?: () => void;
-}) {
+	color?: string;
+	onToggleStatBlock?: () => void;
+}>) {
 	const [editing, setEditing] = useState(false);
 	const [draft, setDraft] = useState(name);
 	const inputRef = useRef<HTMLInputElement>(null);
-	const clickTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
-	const longPressTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
-	const longPressTriggeredRef = useRef(false);
 
 	const commit = useCallback(() => {
 		const trimmed = draft.trim();
@@ -76,53 +74,13 @@ function EditableName({
 		requestAnimationFrame(() => inputRef.current?.select());
 	}, [name]);
 
-	useEffect(() => {
-		return () => {
-			clearTimeout(clickTimerRef.current);
-			clearTimeout(longPressTimerRef.current);
-		};
-	}, []);
-
-	const handleClick = useCallback(
-		(e: React.MouseEvent) => {
-			e.stopPropagation();
-			if (longPressTriggeredRef.current) {
-				longPressTriggeredRef.current = false;
-				return;
-			}
-			if (clickTimerRef.current) {
-				clearTimeout(clickTimerRef.current);
-				clickTimerRef.current = undefined;
-				startEditing();
-			} else {
-				clickTimerRef.current = setTimeout(() => {
-					clickTimerRef.current = undefined;
-					onShowStatBlock?.();
-				}, 250);
-			}
-		},
-		[startEditing, onShowStatBlock],
-	);
-
-	const handleTouchStart = useCallback(() => {
-		longPressTriggeredRef.current = false;
-		longPressTimerRef.current = setTimeout(() => {
-			longPressTriggeredRef.current = true;
-			startEditing();
-		}, 500);
-	}, [startEditing]);
-
-	const cancelLongPress = useCallback(() => {
-		clearTimeout(longPressTimerRef.current);
-	}, []);
-
 	if (editing) {
 		return (
 			<Input
 				ref={inputRef}
 				type="text"
 				value={draft}
-				className="h-7 text-sm"
+				className="h-7 max-w-48 text-sm"
 				onChange={(e) => setDraft(e.target.value)}
 				onBlur={commit}
 				onKeyDown={(e) => {
@@ -137,15 +95,27 @@ function EditableName({
 		<>
 			<button
 				type="button"
-				onClick={handleClick}
-				onTouchStart={handleTouchStart}
-				onTouchEnd={cancelLongPress}
-				onTouchCancel={cancelLongPress}
-				onTouchMove={cancelLongPress}
-				className="truncate text-left text-sm text-foreground cursor-text hover:text-hover-neutral transition-colors"
+				onClick={onToggleStatBlock}
+				disabled={!onToggleStatBlock}
+				className={cn(
+					"truncate text-left text-sm transition-colors",
+					onToggleStatBlock
+						? "cursor-pointer text-foreground hover:text-hover-neutral"
+						: "cursor-default text-foreground",
+				)}
+				style={color ? { color } : undefined}
 			>
 				{name}
 			</button>
+			<button
+				type="button"
+				onClick={startEditing}
+				title="Rename"
+				aria-label="Rename"
+				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>
 		</>
 	);
 }
@@ -153,10 +123,10 @@ function EditableName({
 function MaxHpDisplay({
 	maxHp,
 	onCommit,
-}: {
+}: Readonly<{
 	maxHp: number | undefined;
 	onCommit: (value: number | undefined) => void;
-}) {
+}>) {
 	const [editing, setEditing] = useState(false);
 	const [draft, setDraft] = useState(maxHp?.toString() ?? "");
 	const inputRef = useRef<HTMLInputElement>(null);
@@ -187,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) => {
@@ -202,7 +172,12 @@ function MaxHpDisplay({
 		<button
 			type="button"
 			onClick={startEditing}
-			className="inline-block h-7 min-w-[3ch] text-center text-sm leading-7 tabular-nums text-muted-foreground transition-colors hover:text-hover-neutral"
+			className={cn(
+				"inline-block h-7 min-w-[3ch] text-center leading-7 transition-colors hover:text-hover-neutral",
+				maxHp === undefined
+					? "text-muted-foreground text-sm"
+					: "text-muted-foreground text-xs",
+			)}
 		>
 			{maxHp ?? "Max"}
 		</button>
@@ -212,48 +187,47 @@ function MaxHpDisplay({
 function ClickableHp({
 	currentHp,
 	maxHp,
+	tempHp,
 	onAdjust,
-	dimmed,
-}: {
+	onSetTempHp,
+}: Readonly<{
 	currentHp: number | undefined;
 	maxHp: number | undefined;
+	tempHp: number | undefined;
 	onAdjust: (delta: number) => void;
-	dimmed?: boolean;
-}) {
+	onSetTempHp: (value: number) => void;
+}>) {
 	const [popoverOpen, setPopoverOpen] = useState(false);
 	const status = deriveHpStatus(currentHp, maxHp);
 
 	if (maxHp === undefined) {
-		return (
-			<span
-				className={cn(
-					"inline-block h-7 w-[4ch] text-center text-sm leading-7 tabular-nums text-muted-foreground",
-					dimmed && "opacity-50",
-				)}
-			>
-				--
-			</span>
-		);
+		return null;
 	}
 
 	return (
-		<div className="relative">
+		<div className="relative flex items-center">
 			<button
 				type="button"
 				onClick={() => setPopoverOpen(true)}
+				aria-label={`Current HP: ${currentHp}${tempHp ? ` (+${tempHp} temp)` : ""} (${status})`}
 				className={cn(
-					"inline-block h-7 min-w-[3ch] text-center text-sm font-medium leading-7 tabular-nums transition-colors hover:text-hover-neutral",
+					"inline-block h-7 min-w-[3ch] text-center font-medium text-sm leading-7 transition-colors hover:text-hover-neutral",
 					status === "bloodied" && "text-amber-400",
 					status === "unconscious" && "text-red-400",
 					status === "healthy" && "text-foreground",
-					dimmed && "opacity-50",
 				)}
 			>
 				{currentHp}
 			</button>
-			{popoverOpen && (
+			{!!tempHp && (
+				<span className="font-medium text-cyan-400 text-sm leading-7">
+					+{tempHp}
+				</span>
+			)}
+			{!!popoverOpen && (
 				<HpAdjustPopover
 					onAdjust={onAdjust}
+					onSetTempHp={onSetTempHp}
 					onClose={() => setPopoverOpen(false)}
 				/>
 			)}
@@ -264,10 +238,10 @@ function ClickableHp({
 function AcDisplay({
 	ac,
 	onCommit,
-}: {
+}: Readonly<{
 	ac: number | undefined;
 	onCommit: (value: number | undefined) => void;
-}) {
+}>) {
 	const [editing, setEditing] = useState(false);
 	const [draft, setDraft] = useState(ac?.toString() ?? "");
 	const inputRef = useRef<HTMLInputElement>(null);
@@ -298,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) => {
@@ -318,16 +292,34 @@ function InitiativeDisplay({
 	dimmed,
 	onSetInitiative,
 	onRollInitiative,
-}: {
+}: Readonly<{
 	initiative: number | undefined;
 	combatantId: CombatantId;
 	dimmed: boolean;
 	onSetInitiative: (id: CombatantId, value: number | undefined) => void;
-	onRollInitiative?: (id: CombatantId) => void;
-}) {
+	onRollInitiative?: (id: CombatantId, mode?: RollMode) => void;
+}>) {
 	const [editing, setEditing] = useState(false);
 	const [draft, setDraft] = useState(initiative?.toString() ?? "");
 	const inputRef = useRef<HTMLInputElement>(null);
+	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],
+		),
+	);
 
 	const commit = useCallback(() => {
 		if (draft === "") {
@@ -356,7 +348,7 @@ function InitiativeDisplay({
 				value={draft}
 				placeholder="--"
 				className={cn(
-					"h-7 w-[6ch] text-center text-sm tabular-nums",
+					"h-7 w-full text-center tabular-nums",
 					dimmed && "opacity-50",
 				)}
 				onChange={(e) => setDraft(e.target.value)}
@@ -369,35 +361,49 @@ function InitiativeDisplay({
 		);
 	}
 
-	// Empty + bestiary creature → d20 roll button
+	// Empty + bestiary creature -> d20 roll button
 	if (initiative === undefined && onRollInitiative) {
 		return (
-			<button
-				type="button"
-				onClick={() => onRollInitiative(combatantId)}
-				className={cn(
-					"flex h-7 w-full items-center justify-center text-muted-foreground transition-colors hover:text-hover-neutral",
-					dimmed && "opacity-50",
+			<>
+				<button
+					type="button"
+					onClick={() => onRollInitiative(combatantId)}
+					onContextMenu={(e) => {
+						e.preventDefault();
+						openMenu(e.clientX, e.clientY);
+					}}
+					{...longPress}
+					className={cn(
+						"flex h-7 w-full items-center justify-center text-muted-foreground transition-colors hover:text-hover-neutral",
+						dimmed && "opacity-50",
+					)}
+					title="Roll initiative"
+					aria-label="Roll initiative"
+				>
+					<D20Icon className="h-7 w-7" />
+				</button>
+				{!!menuPos && (
+					<RollModeMenu
+						position={menuPos}
+						onSelect={(mode) => onRollInitiative(combatantId, mode)}
+						onClose={() => setMenuPos(null)}
+					/>
 				)}
-				title="Roll initiative"
-				aria-label="Roll initiative"
-			>
-				<D20Icon className="h-7 w-7" />
-			</button>
+			</>
 		);
 	}
 
-	// Has value → bold number, click to edit
-	// Empty + manual → "--" placeholder, click to edit
+	// Has value -> bold number, click to edit
+	// Empty + manual -> "--" placeholder, click to edit
 	return (
 		<button
 			type="button"
 			onClick={startEditing}
 			className={cn(
-				"h-7 w-full text-center text-sm leading-7 tabular-nums transition-colors",
-				initiative !== undefined
-					? "font-medium text-foreground hover:text-hover-neutral"
-					: "text-muted-foreground hover:text-hover-neutral",
+				"h-7 w-full text-center text-sm tabular-nums leading-7 transition-colors",
+				initiative === undefined
+					? "text-muted-foreground hover:text-hover-neutral"
+					: "font-medium text-foreground hover:text-hover-neutral",
 				dimmed && "opacity-50",
 			)}
 		>
@@ -410,9 +416,13 @@ function rowBorderClass(
 	isActive: boolean,
 	isConcentrating: boolean | undefined,
 ): string {
-	if (isActive) return "border-l-2 border-l-accent bg-accent/10";
-	if (isConcentrating) return "border-l-2 border-l-purple-400";
-	return "border-l-2 border-l-transparent";
+	if (isActive && isConcentrating)
+		return "border border-l-2 border-active-row-border border-l-purple-400 bg-active-row-bg card-glow";
+	if (isActive)
+		return "border border-l-2 border-active-row-border bg-active-row-bg card-glow";
+	if (isConcentrating)
+		return "border border-l-2 border-transparent border-l-purple-400";
+	return "border border-l-2 border-transparent";
 }
 
 function concentrationIconClass(
@@ -424,56 +434,71 @@ function concentrationIconClass(
 	return dimmed ? "opacity-50 text-purple-400" : "opacity-100 text-purple-400";
 }
 
-function activateOnKeyDown(
-	handler: () => void,
-): (e: { key: string; preventDefault: () => void }) => void {
-	return (e) => {
-		if (e.key === "Enter" || e.key === " ") {
-			e.preventDefault();
-			handler();
-		}
-	};
-}
-
 export function CombatantRow({
 	ref,
 	combatant,
 	isActive,
-	onRename,
-	onSetInitiative,
-	onRemove,
-	onSetHp,
-	onAdjustHp,
-	onSetAc,
-	onToggleCondition,
-	onToggleConcentration,
-	onShowStatBlock,
-	onRollInitiative,
 }: CombatantRowProps & { ref?: Ref<HTMLDivElement> }) {
+	const {
+		editCombatant,
+		setInitiative,
+		removeCombatant,
+		setHp,
+		adjustHp,
+		setTempHp,
+		setAc,
+		toggleCondition,
+		toggleConcentration,
+	} = useEncounterContext();
+	const { selectedCreatureId, showCreature, toggleCollapse } =
+		useSidePanelContext();
+	const { handleRollInitiative } = useInitiativeRollsContext();
+
+	// Derive what was previously conditional props
+	const isStatBlockOpen = combatant.creatureId === selectedCreatureId;
+	const { creatureId } = combatant;
+	const hasStatBlock = !!creatureId;
+	const onToggleStatBlock = hasStatBlock
+		? () => {
+				if (isStatBlockOpen) {
+					toggleCollapse();
+				} else {
+					showCreature(creatureId);
+				}
+			}
+		: undefined;
+	const onRollInitiative = combatant.creatureId
+		? handleRollInitiative
+		: undefined;
+
 	const { id, name, initiative, maxHp, currentHp } = combatant;
 	const status = deriveHpStatus(currentHp, maxHp);
 	const dimmed = status === "unconscious";
 	const [pickerOpen, setPickerOpen] = useState(false);
+	const conditionAnchorRef = useRef<HTMLDivElement>(null);
 
 	const prevHpRef = useRef(currentHp);
+	const prevTempHpRef = useRef(combatant.tempHp);
 	const [isPulsing, setIsPulsing] = useState(false);
 	const pulseTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
 
 	useEffect(() => {
 		const prevHp = prevHpRef.current;
+		const prevTempHp = prevTempHpRef.current;
 		prevHpRef.current = currentHp;
+		prevTempHpRef.current = combatant.tempHp;
 
-		if (
-			prevHp !== undefined &&
-			currentHp !== undefined &&
-			currentHp < prevHp &&
-			combatant.isConcentrating
-		) {
+		const realHpDropped =
+			prevHp !== undefined && currentHp !== undefined && currentHp < prevHp;
+		const tempHpDropped =
+			prevTempHp !== undefined && (combatant.tempHp ?? 0) < prevTempHp;
+
+		if ((realHpDropped || tempHpDropped) && combatant.isConcentrating) {
 			setIsPulsing(true);
 			clearTimeout(pulseTimerRef.current);
 			pulseTimerRef.current = setTimeout(() => setIsPulsing(false), 1200);
 		}
-	}, [currentHp, combatant.isConcentrating]);
+	}, [currentHp, combatant.tempHp, combatant.isConcentrating]);
 
 	useEffect(() => {
 		if (!combatant.isConcentrating) {
@@ -482,41 +507,28 @@ export function CombatantRow({
 		}
 	}, [combatant.isConcentrating]);
 
-	const pcColor =
-		combatant.color && !isActive && !combatant.isConcentrating
-			? PLAYER_COLOR_HEX[combatant.color as keyof typeof PLAYER_COLOR_HEX]
-			: undefined;
+	const pcColor = combatant.color
+		? PLAYER_COLOR_HEX[combatant.color as keyof typeof PLAYER_COLOR_HEX]
+		: undefined;
 
 	return (
-		/* biome-ignore lint/a11y/noStaticElementInteractions: role="button" is set conditionally when onShowStatBlock exists */
 		<div
 			ref={ref}
-			role={onShowStatBlock ? "button" : undefined}
-			tabIndex={onShowStatBlock ? 0 : undefined}
 			className={cn(
-				"group rounded-md pr-3 transition-colors",
+				"group rounded-lg pr-3 transition-colors",
 				rowBorderClass(isActive, combatant.isConcentrating),
 				isPulsing && "animate-concentration-pulse",
-				onShowStatBlock && "cursor-pointer",
 			)}
-			style={pcColor ? { borderLeftColor: pcColor } : undefined}
-			onClick={onShowStatBlock}
-			onKeyDown={
-				onShowStatBlock ? activateOnKeyDown(onShowStatBlock) : undefined
-			}
 		>
-			<div className="grid grid-cols-[2rem_3rem_1fr_auto_auto_2rem] items-center gap-3 py-2">
+			<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"
-					onClick={(e) => {
-						e.stopPropagation();
-						onToggleConcentration(id);
-					}}
+					onClick={() => toggleConcentration(id)}
 					title="Concentrating"
 					aria-label="Toggle concentration"
 					className={cn(
-						"flex w-full items-center justify-center self-stretch -my-2 -ml-[2px] pl-[14px] transition-opacity hover:text-hover-neutral hover:opacity-100",
+						"-my-2 -ml-[2px] flex w-full items-center justify-center self-stretch pl-[14px] transition-opacity hover:text-hover-neutral hover:opacity-100",
 						concentrationIconClass(combatant.isConcentrating, dimmed),
 					)}
 				>
@@ -524,39 +536,40 @@ export function CombatantRow({
 				</button>
 
 				{/* Initiative */}
-				{/* biome-ignore lint/a11y/noStaticElementInteractions: stopPropagation wrapper for interactive children */}
-				<div
-					onClick={(e) => e.stopPropagation()}
-					onKeyDown={(e) => e.stopPropagation()}
-				>
+				<div className="rounded-md bg-muted/30 px-1">
 					<InitiativeDisplay
 						initiative={initiative}
 						combatantId={id}
 						dimmed={dimmed}
-						onSetInitiative={onSetInitiative}
+						onSetInitiative={setInitiative}
 						onRollInitiative={onRollInitiative}
 					/>
 				</div>
 
+				{/* AC */}
+				<div className={cn(dimmed && "opacity-50")}>
+					<AcDisplay ac={combatant.ac} onCommit={(v) => setAc(id, v)} />
+				</div>
+
 				{/* Name + Conditions */}
 				<div
 					className={cn(
-						"relative flex flex-wrap items-center gap-1 min-w-0",
+						"relative flex min-w-0 flex-wrap items-center gap-1",
 						dimmed && "opacity-50",
 					)}
 				>
-					{combatant.icon &&
-						combatant.color &&
+					{!!combatant.icon &&
+						!!combatant.color &&
 						(() => {
 							const PcIcon = PLAYER_ICON_MAP[combatant.icon as PlayerIcon];
-							const pcColor =
+							const iconColor =
 								PLAYER_COLOR_HEX[
 									combatant.color as keyof typeof PLAYER_COLOR_HEX
 								];
 							return PcIcon ? (
 								<PcIcon
-									size={14}
-									style={{ color: pcColor }}
+									size={16}
+									style={{ color: iconColor }}
 									className="shrink-0"
 								/>
 							) : null;
@@ -564,67 +577,56 @@ export function CombatantRow({
 					<EditableName
 						name={name}
 						combatantId={id}
-						onRename={onRename}
-						onShowStatBlock={onShowStatBlock}
+						onRename={editCombatant}
+						color={pcColor}
+						onToggleStatBlock={onToggleStatBlock}
 					/>
-					<ConditionTags
-						conditions={combatant.conditions}
-						onRemove={(conditionId) => onToggleCondition(id, conditionId)}
-						onOpenPicker={() => setPickerOpen((prev) => !prev)}
-					/>
-					{pickerOpen && (
+					<div ref={conditionAnchorRef}>
+						<ConditionTags
+							conditions={combatant.conditions}
+							onRemove={(conditionId) => toggleCondition(id, conditionId)}
+							onOpenPicker={() => setPickerOpen((prev) => !prev)}
+						/>
+					</div>
+					{!!pickerOpen && (
 						<ConditionPicker
+							anchorRef={conditionAnchorRef}
 							activeConditions={combatant.conditions}
-							onToggle={(conditionId) => onToggleCondition(id, conditionId)}
+							onToggle={(conditionId) => toggleCondition(id, conditionId)}
 							onClose={() => setPickerOpen(false)}
 						/>
 					)}
 				</div>
 
-				{/* AC */}
-				{/* biome-ignore lint/a11y/noStaticElementInteractions: stopPropagation wrapper for interactive children */}
-				<div
-					className={cn(dimmed && "opacity-50")}
-					onClick={(e) => e.stopPropagation()}
-					onKeyDown={(e) => e.stopPropagation()}
-				>
-					<AcDisplay ac={combatant.ac} onCommit={(v) => onSetAc(id, v)} />
-				</div>
-
 				{/* HP */}
-				{/* biome-ignore lint/a11y/noStaticElementInteractions: stopPropagation wrapper for interactive children */}
 				<div
-					className="flex items-center gap-1"
-					onClick={(e) => e.stopPropagation()}
-					onKeyDown={(e) => e.stopPropagation()}
+					className={cn(
+						"flex items-center rounded-md tabular-nums",
+						maxHp === undefined
+							? ""
+							: "gap-0.5 border border-border/50 bg-muted/30 px-1.5",
+						dimmed && "opacity-50",
+					)}
 				>
 					<ClickableHp
 						currentHp={currentHp}
 						maxHp={maxHp}
-						onAdjust={(delta) => onAdjustHp(id, delta)}
-						dimmed={dimmed}
+						tempHp={combatant.tempHp}
+						onAdjust={(delta) => adjustHp(id, delta)}
+						onSetTempHp={(value) => setTempHp(id, value)}
 					/>
 					{maxHp !== undefined && (
-						<span
-							className={cn(
-								"text-sm tabular-nums text-muted-foreground",
-								dimmed && "opacity-50",
-							)}
-						>
-							/
-						</span>
+						<span className="text-muted-foreground/50 text-xs">/</span>
 					)}
-					<div className={cn(dimmed && "opacity-50")}>
-						<MaxHpDisplay maxHp={maxHp} onCommit={(v) => onSetHp(id, v)} />
-					</div>
+					<MaxHpDisplay maxHp={maxHp} onCommit={(v) => setHp(id, v)} />
 				</div>
 
 				{/* Actions */}
 				<ConfirmButton
 					icon={<X size={16} />}
 					label="Remove combatant"
-					onConfirm={() => onRemove(id)}
-					className="h-7 w-7 text-muted-foreground opacity-0 pointer-events-none group-hover:opacity-100 group-hover:pointer-events-auto focus:opacity-100 focus:pointer-events-auto pointer-coarse:opacity-100 pointer-coarse:pointer-events-auto transition-opacity"
+					onConfirm={() => removeCombatant(id)}
+					className="pointer-events-none pointer-coarse:pointer-events-auto h-7 w-7 text-muted-foreground opacity-0 pointer-coarse:opacity-100 transition-opacity focus:pointer-events-auto focus:opacity-100 group-hover:pointer-events-auto group-hover:opacity-100"
 				/>
 			</div>
 		</div>

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

@@ -1,4 +1,8 @@
-import { CONDITION_DEFINITIONS, type ConditionId } from "@initiative/domain";
+import {
+	type ConditionId,
+	getConditionDescription,
+	getConditionsForEdition,
+} from "@initiative/domain";
 import type { LucideIcon } from "lucide-react";
 import {
 	ArrowDown,
@@ -13,12 +17,17 @@ import {
 	Heart,
 	Link,
 	Moon,
+	ShieldMinus,
 	Siren,
+	Snail,
 	Sparkles,
 	ZapOff,
 } from "lucide-react";
 import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { useRulesEditionContext } from "../contexts/rules-edition-context.js";
 import { cn } from "../lib/utils";
+import { Tooltip } from "./ui/tooltip.js";
 
 const ICON_MAP: Record<string, LucideIcon> = {
 	EyeOff,
@@ -34,6 +43,8 @@ const ICON_MAP: Record<string, LucideIcon> = {
 	Droplet,
 	ArrowDown,
 	Link,
+	ShieldMinus,
+	Snail,
 	Sparkles,
 	Moon,
 };
@@ -49,37 +60,49 @@ const COLOR_CLASSES: Record<string, string> = {
 	slate: "text-slate-400",
 	green: "text-green-400",
 	indigo: "text-indigo-400",
+	sky: "text-sky-400",
 };
 
 interface ConditionPickerProps {
+	anchorRef: React.RefObject<HTMLElement | null>;
 	activeConditions: readonly ConditionId[] | undefined;
 	onToggle: (conditionId: ConditionId) => void;
 	onClose: () => void;
 }
 
 export function ConditionPicker({
+	anchorRef,
 	activeConditions,
 	onToggle,
 	onClose,
-}: ConditionPickerProps) {
+}: Readonly<ConditionPickerProps>) {
 	const ref = useRef<HTMLDivElement>(null);
-	const [flipped, setFlipped] = useState(false);
-	const [maxHeight, setMaxHeight] = useState<number | undefined>(undefined);
+	const [pos, setPos] = useState<{
+		top: number;
+		left: number;
+		maxHeight: number;
+	} | null>(null);
 
 	useLayoutEffect(() => {
+		const anchor = anchorRef.current;
 		const el = ref.current;
-		if (!el) return;
-		const rect = el.getBoundingClientRect();
-		const spaceBelow = window.innerHeight - rect.top;
-		const spaceAbove = rect.bottom;
-		const shouldFlip =
-			rect.bottom > window.innerHeight && spaceAbove > spaceBelow;
-		setFlipped(shouldFlip);
-		const available = shouldFlip ? spaceAbove : spaceBelow;
-		if (rect.height > available) {
-			setMaxHeight(available - 16);
-		}
-	}, []);
+		if (!anchor || !el) return;
+
+		const anchorRect = anchor.getBoundingClientRect();
+		const menuHeight = el.scrollHeight;
+		const pad = 8;
+
+		const spaceBelow = window.innerHeight - anchorRect.bottom - pad;
+		const spaceAbove = anchorRect.top - pad;
+		const openBelow = spaceBelow >= menuHeight || spaceBelow >= spaceAbove;
+
+		const top = openBelow
+			? anchorRect.bottom + 4
+			: Math.max(pad, anchorRect.top - Math.min(menuHeight, spaceAbove) - 4);
+		const maxHeight = openBelow ? spaceBelow : Math.min(menuHeight, spaceAbove);
+
+		setPos({ top, left: anchorRect.left, maxHeight });
+	}, [anchorRef]);
 
 	useEffect(() => {
 		function handleClickOutside(e: MouseEvent) {
@@ -91,44 +114,55 @@ export function ConditionPicker({
 		return () => document.removeEventListener("mousedown", handleClickOutside);
 	}, [onClose]);
 
+	const { edition } = useRulesEditionContext();
+	const conditions = getConditionsForEdition(edition);
 	const active = new Set(activeConditions ?? []);
 
-	return (
+	return createPortal(
 		<div
 			ref={ref}
-			className={cn(
-				"absolute left-0 z-10 w-fit overflow-y-auto rounded-md border border-border bg-background p-1 shadow-lg",
-				flipped ? "bottom-full mb-1" : "top-full mt-1",
-			)}
-			style={maxHeight ? { maxHeight } : undefined}
+			className="card-glow fixed z-50 w-fit overflow-y-auto rounded-lg border border-border bg-background p-1"
+			style={
+				pos
+					? { top: pos.top, left: pos.left, maxHeight: pos.maxHeight }
+					: { visibility: "hidden" as const }
+			}
 		>
-			{CONDITION_DEFINITIONS.map((def) => {
+			{conditions.map((def) => {
 				const Icon = ICON_MAP[def.iconName];
 				if (!Icon) return null;
 				const isActive = active.has(def.id);
 				const colorClass = COLOR_CLASSES[def.color] ?? "text-muted-foreground";
 				return (
-					<button
+					<Tooltip
 						key={def.id}
-						type="button"
-						className={cn(
-							"flex w-full items-center gap-2 rounded px-2 py-1 text-sm transition-colors hover:bg-hover-neutral-bg",
-							isActive && "bg-card/50",
-						)}
-						onClick={() => onToggle(def.id)}
+						content={getConditionDescription(def, edition)}
+						className="block"
 					>
-						<Icon
-							size={14}
-							className={isActive ? colorClass : "text-muted-foreground"}
-						/>
-						<span
-							className={isActive ? "text-foreground" : "text-muted-foreground"}
+						<button
+							type="button"
+							className={cn(
+								"flex w-full items-center gap-2 rounded px-2 py-1 text-sm transition-colors hover:bg-hover-neutral-bg",
+								isActive && "bg-card/50",
+							)}
+							onClick={() => onToggle(def.id)}
 						>
-							{def.label}
-						</span>
-					</button>
+							<Icon
+								size={14}
+								className={isActive ? colorClass : "text-muted-foreground"}
+							/>
+							<span
+								className={
+									isActive ? "text-foreground" : "text-muted-foreground"
+								}
+							>
+								{def.label}
+							</span>
+						</button>
+					</Tooltip>
 				);
 			})}
-		</div>
+		</div>,
+		document.body,
 	);
 }

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

@@ -1,4 +1,8 @@
-import { CONDITION_DEFINITIONS, type ConditionId } from "@initiative/domain";
+import {
+	CONDITION_DEFINITIONS,
+	type ConditionId,
+	getConditionDescription,
+} from "@initiative/domain";
 import type { LucideIcon } from "lucide-react";
 import {
 	ArrowDown,
@@ -14,10 +18,15 @@ import {
 	Link,
 	Moon,
 	Plus,
+	ShieldMinus,
 	Siren,
+	Snail,
 	Sparkles,
 	ZapOff,
 } from "lucide-react";
+import { useRulesEditionContext } from "../contexts/rules-edition-context.js";
+import { cn } from "../lib/utils.js";
+import { Tooltip } from "./ui/tooltip.js";
 
 const ICON_MAP: Record<string, LucideIcon> = {
 	EyeOff,
@@ -33,6 +42,8 @@ const ICON_MAP: Record<string, LucideIcon> = {
 	Droplet,
 	ArrowDown,
 	Link,
+	ShieldMinus,
+	Snail,
 	Sparkles,
 	Moon,
 };
@@ -48,6 +59,7 @@ const COLOR_CLASSES: Record<string, string> = {
 	slate: "text-slate-400",
 	green: "text-green-400",
 	indigo: "text-indigo-400",
+	sky: "text-sky-400",
 };
 
 interface ConditionTagsProps {
@@ -60,7 +72,8 @@ export function ConditionTags({
 	conditions,
 	onRemove,
 	onOpenPicker,
-}: ConditionTagsProps) {
+}: Readonly<ConditionTagsProps>) {
+	const { edition } = useRulesEditionContext();
 	return (
 		<div className="flex flex-wrap items-center gap-0.5">
 			{conditions?.map((condId) => {
@@ -70,26 +83,32 @@ export function ConditionTags({
 				if (!Icon) return null;
 				const colorClass = COLOR_CLASSES[def.color] ?? "text-muted-foreground";
 				return (
-					<button
+					<Tooltip
 						key={condId}
-						type="button"
-						title={def.label}
-						aria-label={`Remove ${def.label}`}
-						className={`inline-flex items-center rounded p-0.5 hover:bg-hover-neutral-bg transition-colors ${colorClass}`}
-						onClick={(e) => {
-							e.stopPropagation();
-							onRemove(condId);
-						}}
+						content={`${def.label}:\n${getConditionDescription(def, edition)}`}
 					>
-						<Icon size={14} />
-					</button>
+						<button
+							type="button"
+							aria-label={`Remove ${def.label}`}
+							className={cn(
+								"inline-flex items-center rounded p-0.5 transition-colors hover:bg-hover-neutral-bg",
+								colorClass,
+							)}
+							onClick={(e) => {
+								e.stopPropagation();
+								onRemove(condId);
+							}}
+						>
+							<Icon size={14} />
+						</button>
+					</Tooltip>
 				);
 			})}
 			<button
 				type="button"
 				title="Add condition"
 				aria-label="Add condition"
-				className="inline-flex items-center rounded p-0.5 text-muted-foreground hover:text-hover-neutral hover:bg-hover-neutral-bg transition-colors opacity-0 group-hover:opacity-100 focus:opacity-100 pointer-coarse:opacity-100 transition-opacity"
+				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,9 +1,10 @@
 import type { PlayerCharacter } from "@initiative/domain";
 import { X } from "lucide-react";
-import { type FormEvent, useEffect, 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";
 
 interface CreatePlayerModalProps {
@@ -13,8 +14,8 @@ interface CreatePlayerModalProps {
 		name: string,
 		ac: number,
 		maxHp: number,
-		color: string,
-		icon: string,
+		color: string | undefined,
+		icon: string | undefined,
 	) => void;
 	playerCharacter?: PlayerCharacter;
 }
@@ -24,7 +25,7 @@ export function CreatePlayerModal({
 	onClose,
 	onSave,
 	playerCharacter,
-}: CreatePlayerModalProps) {
+}: Readonly<CreatePlayerModalProps>) {
 	const [name, setName] = useState("");
 	const [ac, setAc] = useState("10");
 	const [maxHp, setMaxHp] = useState("10");
@@ -40,22 +41,20 @@ export function CreatePlayerModal({
 				setName(playerCharacter.name);
 				setAc(String(playerCharacter.ac));
 				setMaxHp(String(playerCharacter.maxHp));
-				setColor(playerCharacter.color);
-				setIcon(playerCharacter.icon);
+				setColor(playerCharacter.color ?? "");
+				setIcon(playerCharacter.icon ?? "");
 			} else {
 				setName("");
 				setAc("10");
 				setMaxHp("10");
-				setColor("blue");
-				setIcon("sword");
+				setColor("");
+				setIcon("");
 			}
 			setError("");
 		}
 	}, [open, playerCharacter]);
 
-	if (!open) return null;
-
-	const handleSubmit = (e: FormEvent) => {
+	const handleSubmit = (e: React.SubmitEvent<HTMLFormElement>) => {
 		e.preventDefault();
 		const trimmed = name.trim();
 		if (trimmed === "") {
@@ -72,106 +71,91 @@ export function CreatePlayerModal({
 			setError("Max HP must be at least 1");
 			return;
 		}
-		onSave(trimmed, acNum, hpNum, color, icon);
+		onSave(trimmed, acNum, hpNum, color || undefined, icon || undefined);
 		onClose();
 	};
 
 	return (
-		// biome-ignore lint/a11y/noStaticElementInteractions: backdrop click to close
-		<div
-			className="fixed inset-0 z-50 flex items-center justify-center bg-black/50"
-			onMouseDown={onClose}
-		>
-			{/* biome-ignore lint/a11y/noStaticElementInteractions: prevent close when clicking modal content */}
-			<div
-				className="w-full max-w-md rounded-lg border border-border bg-card p-6 shadow-xl"
-				onMouseDown={(e) => e.stopPropagation()}
-			>
-				<div className="mb-4 flex items-center justify-between">
-					<h2 className="text-lg font-semibold text-foreground">
-						{isEdit ? "Edit Player" : "Create Player"}
-					</h2>
-					<button
-						type="button"
-						onClick={onClose}
-						className="text-muted-foreground hover:text-foreground transition-colors"
-					>
-						<X size={20} />
-					</button>
+		<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"}
+				</h2>
+				<Button
+					variant="ghost"
+					size="icon"
+					onClick={onClose}
+					className="text-muted-foreground"
+				>
+					<X size={20} />
+				</Button>
+			</div>
+
+			<form onSubmit={handleSubmit} className="flex flex-col gap-4">
+				<div>
+					<span className="mb-1 block text-muted-foreground text-sm">Name</span>
+					<Input
+						type="text"
+						value={name}
+						onChange={(e) => {
+							setName(e.target.value);
+							setError("");
+						}}
+						placeholder="Character name"
+						aria-label="Name"
+						autoFocus
+					/>
+					{!!error && <p className="mt-1 text-destructive text-sm">{error}</p>}
 				</div>
 
-				<form onSubmit={handleSubmit} className="flex flex-col gap-4">
-					<div>
-						<span className="mb-1 block text-sm text-muted-foreground">
-							Name
+				<div className="flex gap-3">
+					<div className="flex-1">
+						<span className="mb-1 block text-muted-foreground text-sm">AC</span>
+						<Input
+							type="text"
+							inputMode="numeric"
+							value={ac}
+							onChange={(e) => setAc(e.target.value)}
+							placeholder="AC"
+							aria-label="AC"
+							className="text-center"
+						/>
+					</div>
+					<div className="flex-1">
+						<span className="mb-1 block text-muted-foreground text-sm">
+							Max HP
 						</span>
 						<Input
 							type="text"
-							value={name}
-							onChange={(e) => {
-								setName(e.target.value);
-								setError("");
-							}}
-							placeholder="Character name"
-							aria-label="Name"
-							autoFocus
+							inputMode="numeric"
+							value={maxHp}
+							onChange={(e) => setMaxHp(e.target.value)}
+							placeholder="Max HP"
+							aria-label="Max HP"
+							className="text-center"
 						/>
-						{error && <p className="mt-1 text-sm text-destructive">{error}</p>}
 					</div>
+				</div>
 
-					<div className="flex gap-3">
-						<div className="flex-1">
-							<span className="mb-1 block text-sm text-muted-foreground">
-								AC
-							</span>
-							<Input
-								type="text"
-								inputMode="numeric"
-								value={ac}
-								onChange={(e) => setAc(e.target.value)}
-								placeholder="AC"
-								aria-label="AC"
-								className="text-center"
-							/>
-						</div>
-						<div className="flex-1">
-							<span className="mb-1 block text-sm text-muted-foreground">
-								Max HP
-							</span>
-							<Input
-								type="text"
-								inputMode="numeric"
-								value={maxHp}
-								onChange={(e) => setMaxHp(e.target.value)}
-								placeholder="Max HP"
-								aria-label="Max HP"
-								className="text-center"
-							/>
-						</div>
-					</div>
+				<div>
+					<span className="mb-2 block text-muted-foreground text-sm">
+						Color
+					</span>
+					<ColorPalette value={color} onChange={setColor} />
+				</div>
 
-					<div>
-						<span className="mb-2 block text-sm text-muted-foreground">
-							Color
-						</span>
-						<ColorPalette value={color} onChange={setColor} />
-					</div>
+				<div>
+					<span className="mb-2 block text-muted-foreground text-sm">Icon</span>
+					<IconGrid value={icon} onChange={setIcon} />
+				</div>
 
-					<div>
-						<span className="mb-2 block text-sm text-muted-foreground">
-							Icon
-						</span>
-						<IconGrid value={icon} onChange={setIcon} />
-					</div>
-
-					<div className="flex justify-end gap-2 pt-2">
-						<Button type="button" variant="ghost" onClick={onClose}>
-							Cancel
-						</Button>
-						<Button type="submit">{isEdit ? "Save" : "Create"}</Button>
-					</div>
-				</form>
-			</div>
-		</div>
+				<div className="flex justify-end gap-2 pt-2">
+					<Button type="button" variant="ghost" onClick={onClose}>
+						Cancel
+					</Button>
+					<Button type="submit">{isEdit ? "Save" : "Create"}</Button>
+				</div>
+			</form>
+		</Dialog>
 	);
 }

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

@@ -0,0 +1,105 @@
+import { Check, ClipboardCopy, Download, X } from "lucide-react";
+import { useCallback, useState } from "react";
+import { Button } from "./ui/button.js";
+import { Dialog } 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">
+			<div className="mb-4 flex items-center justify-between">
+				<h2 className="font-semibold text-lg">Export Encounter</h2>
+				<Button
+					type="button"
+					variant="ghost"
+					size="icon-sm"
+					onClick={handleClose}
+					className="text-muted-foreground"
+				>
+					<X className="h-4 w-4" />
+				</Button>
+			</div>
+			<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

@@ -1,4 +1,4 @@
-import { Heart, Sword } from "lucide-react";
+import { Heart, ShieldPlus, Sword } from "lucide-react";
 import {
 	useCallback,
 	useEffect,
@@ -6,15 +6,21 @@ import {
 	useRef,
 	useState,
 } from "react";
-import { Button } from "./ui/button";
 import { Input } from "./ui/input";
 
+const DIGITS_ONLY_REGEX = /^\d+$/;
+
 interface HpAdjustPopoverProps {
 	readonly onAdjust: (delta: number) => void;
+	readonly onSetTempHp: (value: number) => void;
 	readonly onClose: () => void;
 }
 
-export function HpAdjustPopover({ onAdjust, onClose }: HpAdjustPopoverProps) {
+export function HpAdjustPopover({
+	onAdjust,
+	onSetTempHp,
+	onClose,
+}: HpAdjustPopoverProps) {
 	const [inputValue, setInputValue] = useState("");
 	const [pos, setPos] = useState<{ top: number; left: number } | null>(null);
 	const ref = useRef<HTMLDivElement>(null);
@@ -86,7 +92,7 @@ export function HpAdjustPopover({ onAdjust, onClose }: HpAdjustPopoverProps) {
 	return (
 		<div
 			ref={ref}
-			className="fixed z-10 rounded-md border border-border bg-background p-2 shadow-lg"
+			className="card-glow fixed z-10 rounded-lg border border-border bg-background p-2"
 			style={
 				pos
 					? { top: pos.top, left: pos.left }
@@ -100,39 +106,50 @@ export function HpAdjustPopover({ onAdjust, onClose }: HpAdjustPopoverProps) {
 					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 === "" || /^\d+$/.test(v)) {
+						if (v === "" || DIGITS_ONLY_REGEX.test(v)) {
 							setInputValue(v);
 						}
 					}}
 					onKeyDown={handleKeyDown}
 				/>
-				<Button
+				<button
 					type="button"
-					variant="ghost"
-					size="icon"
 					disabled={!isValid}
-					className="h-7 w-7 shrink-0 text-red-400 hover:bg-red-950 hover:text-red-300"
+					className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-red-400 transition-colors hover:bg-hp-damage-hover-bg hover:text-red-300 disabled:pointer-events-none disabled:opacity-50"
 					onClick={() => applyDelta(-1)}
 					title="Apply damage"
 					aria-label="Apply damage"
 				>
 					<Sword size={14} />
-				</Button>
-				<Button
+				</button>
+				<button
 					type="button"
-					variant="ghost"
-					size="icon"
 					disabled={!isValid}
-					className="h-7 w-7 shrink-0 text-emerald-400 hover:bg-emerald-950 hover:text-emerald-300"
+					className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-emerald-400 transition-colors hover:bg-hp-heal-hover-bg hover:text-emerald-300 disabled:pointer-events-none disabled:opacity-50"
 					onClick={() => applyDelta(1)}
 					title="Apply healing"
 					aria-label="Apply healing"
 				>
 					<Heart size={14} />
-				</Button>
+				</button>
+				<button
+					type="button"
+					disabled={!isValid}
+					className="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-cyan-400 transition-colors hover:bg-cyan-400/10 hover:text-cyan-300 disabled:pointer-events-none disabled:opacity-50"
+					onClick={() => {
+						if (isValid && parsedValue) {
+							onSetTempHp(parsedValue);
+							onClose();
+						}
+					}}
+					title="Set temp HP"
+					aria-label="Set temp HP"
+				>
+					<ShieldPlus size={14} />
+				</button>
 			</div>
 		</div>
 	);

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

@@ -10,7 +10,7 @@ interface IconGridProps {
 
 const ICONS = [...VALID_PLAYER_ICONS] as PlayerIcon[];
 
-export function IconGrid({ value, onChange }: IconGridProps) {
+export function IconGrid({ value, onChange }: Readonly<IconGridProps>) {
 	return (
 		<div className="flex flex-wrap gap-2">
 			{ICONS.map((iconId) => {
@@ -19,11 +19,11 @@ export function IconGrid({ value, onChange }: IconGridProps) {
 					<button
 						key={iconId}
 						type="button"
-						onClick={() => onChange(iconId)}
+						onClick={() => onChange(value === iconId ? "" : iconId)}
 						className={cn(
 							"flex h-9 w-9 items-center justify-center rounded-md transition-all",
 							value === iconId
-								? "bg-primary/20 ring-2 ring-primary text-foreground"
+								? "bg-primary/20 text-foreground ring-2 ring-primary"
 								: "text-muted-foreground hover:bg-card hover:text-foreground",
 						)}
 						aria-label={iconId}

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,125 @@
+import { ClipboardPaste, FileUp, X } from "lucide-react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Button } from "./ui/button.js";
+import { Dialog } 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">
+			<div className="mb-4 flex items-center justify-between">
+				<h2 className="font-semibold text-lg">Import Encounter</h2>
+				<Button
+					type="button"
+					variant="ghost"
+					size="icon-sm"
+					onClick={handleClose}
+					className="text-muted-foreground"
+				>
+					<X className="h-4 w-4" />
+				</Button>
+			</div>
+			{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

@@ -0,0 +1,71 @@
+import type { PlayerCharacter } from "@initiative/domain";
+import { type RefObject, useImperativeHandle, useState } from "react";
+import { usePlayerCharactersContext } from "../contexts/player-characters-context.js";
+import { CreatePlayerModal } from "./create-player-modal.js";
+import { PlayerManagement } from "./player-management.js";
+
+export interface PlayerCharacterSectionHandle {
+	openManagement: () => void;
+}
+
+export const PlayerCharacterSection = function PlayerCharacterSectionInner({
+	ref,
+}: {
+	ref?: RefObject<PlayerCharacterSectionHandle | null>;
+}) {
+	const { characters, createCharacter, editCharacter, deleteCharacter } =
+		usePlayerCharactersContext();
+
+	const [managementOpen, setManagementOpen] = useState(false);
+	const [createOpen, setCreateOpen] = useState(false);
+	const [editingPlayer, setEditingPlayer] = useState<
+		PlayerCharacter | undefined
+	>();
+
+	useImperativeHandle(ref, () => ({
+		openManagement: () => setManagementOpen(true),
+	}));
+
+	return (
+		<>
+			<CreatePlayerModal
+				open={createOpen}
+				onClose={() => {
+					setCreateOpen(false);
+					setEditingPlayer(undefined);
+					setManagementOpen(true);
+				}}
+				onSave={(name, ac, maxHp, color, icon) => {
+					if (editingPlayer) {
+						editCharacter(editingPlayer.id, {
+							name,
+							ac,
+							maxHp,
+							color: color ?? null,
+							icon: icon ?? null,
+						});
+					} else {
+						createCharacter(name, ac, maxHp, color, icon);
+					}
+				}}
+				playerCharacter={editingPlayer}
+			/>
+			<PlayerManagement
+				open={managementOpen}
+				onClose={() => setManagementOpen(false)}
+				characters={characters}
+				onEdit={(pc) => {
+					setEditingPlayer(pc);
+					setCreateOpen(true);
+					setManagementOpen(false);
+				}}
+				onDelete={(id) => deleteCharacter(id)}
+				onCreate={() => {
+					setEditingPlayer(undefined);
+					setCreateOpen(true);
+					setManagementOpen(false);
+				}}
+			/>
+		</>
+	);
+};

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

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

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

@@ -0,0 +1,88 @@
+import type { RollMode } from "@initiative/domain";
+import { ChevronsDown, ChevronsUp } from "lucide-react";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+
+interface RollModeMenuProps {
+	readonly position: { x: number; y: number };
+	readonly onSelect: (mode: RollMode) => void;
+	readonly onClose: () => void;
+}
+
+export function RollModeMenu({
+	position,
+	onSelect,
+	onClose,
+}: RollModeMenuProps) {
+	const ref = useRef<HTMLDivElement>(null);
+	const [pos, setPos] = useState<{ top: number; left: number } | null>(null);
+
+	useLayoutEffect(() => {
+		const el = ref.current;
+		if (!el) return;
+		const rect = el.getBoundingClientRect();
+		const vw = document.documentElement.clientWidth;
+		const vh = document.documentElement.clientHeight;
+
+		let left = position.x;
+		let top = position.y;
+
+		if (left + rect.width > vw) left = vw - rect.width - 8;
+		if (left < 8) left = 8;
+		if (top + rect.height > vh) top = position.y - rect.height;
+		if (top < 8) top = 8;
+
+		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]);
+
+	return (
+		<div
+			ref={ref}
+			className="card-glow fixed z-50 min-w-40 rounded-lg border border-border bg-card py-1"
+			style={
+				pos
+					? { top: pos.top, left: pos.left }
+					: { visibility: "hidden" as const }
+			}
+		>
+			<button
+				type="button"
+				className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-emerald-400 text-sm hover:bg-hover-neutral-bg"
+				onClick={() => {
+					onSelect("advantage");
+					onClose();
+				}}
+			>
+				<ChevronsUp className="h-4 w-4" />
+				Advantage
+			</button>
+			<button
+				type="button"
+				className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-red-400 text-sm hover:bg-hover-neutral-bg"
+				onClick={() => {
+					onSelect("disadvantage");
+					onClose();
+				}}
+			>
+				<ChevronsDown className="h-4 w-4" />
+				Disadvantage
+			</button>
+		</div>
+	);
+}

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

@@ -0,0 +1,100 @@
+import type { RulesEdition } from "@initiative/domain";
+import { Monitor, Moon, Sun, X } 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 } from "./ui/dialog.js";
+
+interface SettingsModalProps {
+	open: boolean;
+	onClose: () => void;
+}
+
+const EDITION_OPTIONS: { value: RulesEdition; label: string }[] = [
+	{ value: "5e", label: "5e (2014)" },
+	{ value: "5.5e", label: "5.5e (2024)" },
+];
+
+const THEME_OPTIONS: {
+	value: "system" | "light" | "dark";
+	label: string;
+	icon: typeof Sun;
+}[] = [
+	{ value: "system", label: "System", icon: Monitor },
+	{ value: "light", label: "Light", icon: Sun },
+	{ value: "dark", label: "Dark", icon: Moon },
+];
+
+export function SettingsModal({ open, onClose }: Readonly<SettingsModalProps>) {
+	const { edition, setEdition } = useRulesEditionContext();
+	const { preference, setPreference } = useThemeContext();
+
+	return (
+		<Dialog open={open} onClose={onClose} className="card-glow w-full max-w-sm">
+			<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>
+
+			<div className="flex flex-col gap-5">
+				<div>
+					<span className="mb-2 block font-medium text-muted-foreground text-sm">
+						Conditions
+					</span>
+					<div className="flex gap-1">
+						{EDITION_OPTIONS.map((opt) => (
+							<button
+								key={opt.value}
+								type="button"
+								className={cn(
+									"flex-1 rounded-md px-3 py-1.5 text-sm transition-colors",
+									edition === opt.value
+										? "bg-accent text-primary-foreground"
+										: "bg-card text-muted-foreground hover:bg-hover-neutral-bg hover:text-foreground",
+								)}
+								onClick={() => setEdition(opt.value)}
+							>
+								{opt.label}
+							</button>
+						))}
+					</div>
+				</div>
+
+				<div>
+					<span className="mb-2 block font-medium text-muted-foreground text-sm">
+						Theme
+					</span>
+					<div className="flex gap-1">
+						{THEME_OPTIONS.map((opt) => {
+							const Icon = opt.icon;
+							return (
+								<button
+									key={opt.value}
+									type="button"
+									className={cn(
+										"flex flex-1 items-center justify-center gap-1.5 rounded-md px-3 py-1.5 text-sm transition-colors",
+										preference === opt.value
+											? "bg-accent text-primary-foreground"
+											: "bg-card text-muted-foreground hover:bg-hover-neutral-bg hover:text-foreground",
+									)}
+									onClick={() => setPreference(opt.value)}
+								>
+									<Icon size={14} />
+									{opt.label}
+								</button>
+							);
+						})}
+					</div>
+				</div>
+			</div>
+		</Dialog>
+	);
+}

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

@@ -1,28 +1,29 @@
 import { Download, Loader2, Upload } from "lucide-react";
-import { useRef, useState } from "react";
-import { getDefaultFetchUrl } from "../adapters/bestiary-index-adapter.js";
+import { useId, useRef, useState } from "react";
+import {
+	getDefaultFetchUrl,
+	getSourceDisplayName,
+} from "../adapters/bestiary-index-adapter.js";
+import { useBestiaryContext } from "../contexts/bestiary-context.js";
 import { Button } from "./ui/button.js";
 import { Input } from "./ui/input.js";
 
 interface SourceFetchPromptProps {
 	sourceCode: string;
-	sourceDisplayName: string;
-	fetchAndCacheSource: (sourceCode: string, url: string) => Promise<void>;
 	onSourceLoaded: () => void;
-	onUploadSource: (sourceCode: string, jsonData: unknown) => Promise<void>;
 }
 
 export function SourceFetchPrompt({
 	sourceCode,
-	sourceDisplayName,
-	fetchAndCacheSource,
 	onSourceLoaded,
-	onUploadSource,
-}: SourceFetchPromptProps) {
+}: Readonly<SourceFetchPromptProps>) {
+	const { fetchAndCacheSource, uploadAndCacheSource } = useBestiaryContext();
+	const sourceDisplayName = getSourceDisplayName(sourceCode);
 	const [url, setUrl] = useState(() => getDefaultFetchUrl(sourceCode));
 	const [status, setStatus] = useState<"idle" | "fetching" | "error">("idle");
 	const [error, setError] = useState<string>("");
 	const fileInputRef = useRef<HTMLInputElement>(null);
+	const sourceUrlId = useId();
 
 	const handleFetch = async () => {
 		setStatus("fetching");
@@ -46,7 +47,7 @@ export function SourceFetchPrompt({
 		try {
 			const text = await file.text();
 			const json = JSON.parse(text);
-			await onUploadSource(sourceCode, json);
+			await uploadAndCacheSource(sourceCode, json);
 			onSourceLoaded();
 		} catch (err) {
 			setStatus("error");
@@ -64,21 +65,21 @@ export function SourceFetchPrompt({
 	return (
 		<div className="flex flex-col gap-4">
 			<div>
-				<h3 className="text-sm font-semibold text-foreground">
+				<h3 className="font-semibold text-foreground text-sm">
 					Load {sourceDisplayName}
 				</h3>
-				<p className="mt-1 text-xs text-muted-foreground">
+				<p className="mt-1 text-muted-foreground text-xs">
 					Stat block data for this source needs to be loaded. Enter a URL or
 					upload a JSON file.
 				</p>
 			</div>
 
 			<div className="flex flex-col gap-2">
-				<label htmlFor="source-url" className="text-xs text-muted-foreground">
+				<label htmlFor={sourceUrlId} className="text-muted-foreground text-xs">
 					Source URL
 				</label>
 				<Input
-					id="source-url"
+					id={sourceUrlId}
 					type="url"
 					value={url}
 					onChange={(e) => setUrl(e.target.value)}
@@ -88,11 +89,7 @@ export function SourceFetchPrompt({
 			</div>
 
 			<div className="flex items-center gap-2">
-				<Button
-					size="sm"
-					onClick={handleFetch}
-					disabled={status === "fetching" || !url}
-				>
+				<Button onClick={handleFetch} disabled={status === "fetching" || !url}>
 					{status === "fetching" ? (
 						<Loader2 className="mr-1 h-3 w-3 animate-spin" />
 					) : (
@@ -101,10 +98,9 @@ export function SourceFetchPrompt({
 					{status === "fetching" ? "Loading..." : "Load"}
 				</Button>
 
-				<span className="text-xs text-muted-foreground">or</span>
+				<span className="text-muted-foreground text-xs">or</span>
 
 				<Button
-					size="sm"
 					variant="outline"
 					onClick={() => fileInputRef.current?.click()}
 					disabled={status === "fetching"}
@@ -122,7 +118,7 @@ export function SourceFetchPrompt({
 			</div>
 
 			{status === "error" && (
-				<div className="rounded-md border border-destructive/50 bg-destructive/10 px-3 py-2 text-xs text-destructive">
+				<div className="rounded-md border border-destructive/50 bg-destructive/10 px-3 py-2 text-destructive text-xs">
 					{error}
 				</div>
 			)}

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

@@ -1,15 +1,31 @@
-import { Database, Trash2 } from "lucide-react";
-import { useCallback, useEffect, useState } from "react";
+import { Database, Search, Trash2 } from "lucide-react";
+import {
+	useCallback,
+	useEffect,
+	useMemo,
+	useOptimistic,
+	useState,
+} from "react";
 import type { CachedSourceInfo } from "../adapters/bestiary-cache.js";
 import * as bestiaryCache from "../adapters/bestiary-cache.js";
+import { useBestiaryContext } from "../contexts/bestiary-context.js";
 import { Button } from "./ui/button.js";
+import { Input } from "./ui/input.js";
 
-interface SourceManagerProps {
-	onCacheCleared: () => void;
-}
-
-export function SourceManager({ onCacheCleared }: SourceManagerProps) {
+export function SourceManager() {
+	const { refreshCache } = useBestiaryContext();
 	const [sources, setSources] = useState<CachedSourceInfo[]>([]);
+	const [filter, setFilter] = useState("");
+	const [optimisticSources, applyOptimistic] = useOptimistic(
+		sources,
+		(
+			state,
+			action: { type: "remove"; sourceCode: string } | { type: "clear" },
+		) =>
+			action.type === "clear"
+				? []
+				: state.filter((s) => s.sourceCode !== action.sourceCode),
+	);
 
 	const loadSources = useCallback(async () => {
 		const cached = await bestiaryCache.getCachedSources();
@@ -17,26 +33,37 @@ export function SourceManager({ onCacheCleared }: SourceManagerProps) {
 	}, []);
 
 	useEffect(() => {
-		loadSources();
+		void loadSources();
 	}, [loadSources]);
 
 	const handleClearSource = async (sourceCode: string) => {
+		applyOptimistic({ type: "remove", sourceCode });
 		await bestiaryCache.clearSource(sourceCode);
 		await loadSources();
-		onCacheCleared();
+		void refreshCache();
 	};
 
 	const handleClearAll = async () => {
+		applyOptimistic({ type: "clear" });
 		await bestiaryCache.clearAll();
 		await loadSources();
-		onCacheCleared();
+		void refreshCache();
 	};
 
-	if (sources.length === 0) {
+	const filteredSources = useMemo(() => {
+		const term = filter.toLowerCase();
+		return term
+			? optimisticSources.filter((s) =>
+					s.displayName.toLowerCase().includes(term),
+				)
+			: optimisticSources;
+	}, [optimisticSources, filter]);
+
+	if (optimisticSources.length === 0) {
 		return (
 			<div className="flex flex-col items-center gap-2 py-8 text-center">
 				<Database className="h-8 w-8 text-muted-foreground" />
-				<p className="text-sm text-muted-foreground">No cached sources</p>
+				<p className="text-muted-foreground text-sm">No cached sources</p>
 			</div>
 		);
 	}
@@ -44,32 +71,46 @@ export function SourceManager({ onCacheCleared }: SourceManagerProps) {
 	return (
 		<div className="flex flex-col gap-3">
 			<div className="flex items-center justify-between">
-				<span className="text-sm font-semibold text-foreground">
+				<span className="font-semibold text-foreground text-sm">
 					Cached Sources
 				</span>
-				<Button size="sm" variant="outline" onClick={handleClearAll}>
+				<Button
+					variant="outline"
+					className="hover:border-hover-destructive hover:text-hover-destructive"
+					onClick={handleClearAll}
+				>
 					<Trash2 className="mr-1 h-3 w-3" />
 					Clear All
 				</Button>
 			</div>
+			<div className="relative">
+				<Search className="pointer-events-none absolute top-1/2 left-3 h-3.5 w-3.5 -translate-y-1/2 text-muted-foreground" />
+				<Input
+					placeholder="Filter sources…"
+					value={filter}
+					onChange={(e) => setFilter(e.target.value)}
+					className="pl-8"
+				/>
+			</div>
 			<ul className="flex flex-col gap-1">
-				{sources.map((source) => (
+				{filteredSources.map((source) => (
 					<li
 						key={source.sourceCode}
 						className="flex items-center justify-between rounded-md border border-border px-3 py-2"
 					>
 						<div>
-							<span className="text-sm text-foreground">
+							<span className="text-foreground text-sm">
 								{source.displayName}
 							</span>
-							<span className="ml-2 text-xs text-muted-foreground">
+							<span className="ml-2 text-muted-foreground text-xs">
 								{source.creatureCount} creatures
 							</span>
 						</div>
 						<button
 							type="button"
 							onClick={() => handleClearSource(source.sourceCode)}
-							className="text-muted-foreground hover:text-hover-danger"
+							className="rounded-md p-1 text-muted-foreground transition-colors hover:bg-hover-destructive-bg hover:text-hover-destructive"
+							aria-label={`Remove ${source.displayName}`}
 						>
 							<Trash2 className="h-3.5 w-3.5" />
 						</button>

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

@@ -1,36 +1,20 @@
-import type { Creature, CreatureId } from "@initiative/domain";
+import type { CreatureId } from "@initiative/domain";
 import { PanelRightClose, Pin, PinOff } from "lucide-react";
 import type { ReactNode } from "react";
 import { useEffect, useState } from "react";
-import { getSourceDisplayName } from "../adapters/bestiary-index-adapter.js";
-import type { BulkImportState } from "../hooks/use-bulk-import.js";
+import { useBestiaryContext } from "../contexts/bestiary-context.js";
+import { useSidePanelContext } from "../contexts/side-panel-context.js";
 import { useSwipeToDismiss } from "../hooks/use-swipe-to-dismiss.js";
+import { cn } from "../lib/utils.js";
 import { BulkImportPrompt } from "./bulk-import-prompt.js";
 import { SourceFetchPrompt } from "./source-fetch-prompt.js";
+import { SourceManager } from "./source-manager.js";
 import { StatBlock } from "./stat-block.js";
+import { Button } from "./ui/button.js";
 
 interface StatBlockPanelProps {
-	creatureId: CreatureId | null;
-	creature: Creature | null;
-	isSourceCached: (sourceCode: string) => Promise<boolean>;
-	fetchAndCacheSource: (sourceCode: string, url: string) => Promise<void>;
-	uploadAndCacheSource: (
-		sourceCode: string,
-		jsonData: unknown,
-	) => Promise<void>;
-	refreshCache: () => Promise<void>;
 	panelRole: "browse" | "pinned";
-	isFolded: boolean;
-	onToggleFold: () => void;
-	onPin: () => void;
-	onUnpin: () => void;
-	showPinButton: boolean;
 	side: "left" | "right";
-	onDismiss: () => void;
-	bulkImportMode?: boolean;
-	bulkImportState?: BulkImportState;
-	onStartBulkImport?: (baseUrl: string) => void;
-	onBulkImportDone?: () => void;
 }
 
 function extractSourceCode(cId: CreatureId): string {
@@ -39,25 +23,26 @@ function extractSourceCode(cId: CreatureId): string {
 	return cId.slice(0, colonIndex).toUpperCase();
 }
 
-function FoldedTab({
+function CollapsedTab({
 	creatureName,
 	side,
-	onToggleFold,
-}: {
+	onToggleCollapse,
+}: Readonly<{
 	creatureName: string;
 	side: "left" | "right";
-	onToggleFold: () => void;
-}) {
+	onToggleCollapse: () => void;
+}>) {
 	return (
 		<button
 			type="button"
-			onClick={onToggleFold}
-			className={`flex h-full w-[40px] cursor-pointer items-center justify-center text-muted-foreground hover:text-hover-neutral ${
-				side === "right" ? "self-start" : "self-end"
-			}`}
-			aria-label="Unfold stat block panel"
+			onClick={onToggleCollapse}
+			className={cn(
+				"flex h-full w-[40px] cursor-pointer items-center justify-center text-muted-foreground hover:text-hover-neutral",
+				side === "right" ? "self-start" : "self-end",
+			)}
+			aria-label="Expand stat block panel"
 		>
-			<span className="writing-vertical-rl text-sm font-medium">
+			<span className="writing-vertical-rl font-medium text-sm">
 				{creatureName}
 			</span>
 		</button>
@@ -67,50 +52,53 @@ function FoldedTab({
 function PanelHeader({
 	panelRole,
 	showPinButton,
-	onToggleFold,
+	onToggleCollapse,
 	onPin,
 	onUnpin,
-}: {
+}: Readonly<{
 	panelRole: "browse" | "pinned";
 	showPinButton: boolean;
-	onToggleFold: () => void;
+	onToggleCollapse: () => void;
 	onPin: () => void;
 	onUnpin: () => void;
-}) {
+}>) {
 	return (
-		<div className="flex items-center justify-between border-b border-border px-4 py-2">
+		<div className="flex items-center justify-between border-border border-b px-4 py-2">
 			<div className="flex items-center gap-1">
 				{panelRole === "browse" && (
-					<button
-						type="button"
-						onClick={onToggleFold}
-						className="text-muted-foreground hover:text-hover-neutral"
-						aria-label="Fold stat block panel"
+					<Button
+						variant="ghost"
+						size="icon-sm"
+						onClick={onToggleCollapse}
+						className="text-muted-foreground"
+						aria-label="Collapse stat block panel"
 					>
 						<PanelRightClose className="h-4 w-4" />
-					</button>
+					</Button>
 				)}
 			</div>
 			<div className="flex items-center gap-1">
 				{panelRole === "browse" && showPinButton && (
-					<button
-						type="button"
+					<Button
+						variant="ghost"
+						size="icon-sm"
 						onClick={onPin}
-						className="text-muted-foreground hover:text-hover-neutral"
+						className="text-muted-foreground"
 						aria-label="Pin creature"
 					>
 						<Pin className="h-4 w-4" />
-					</button>
+					</Button>
 				)}
 				{panelRole === "pinned" && (
-					<button
-						type="button"
+					<Button
+						variant="ghost"
+						size="icon-sm"
 						onClick={onUnpin}
-						className="text-muted-foreground hover:text-hover-neutral"
+						className="text-muted-foreground"
 						aria-label="Unpin creature"
 					>
 						<PinOff className="h-4 w-4" />
-					</button>
+					</Button>
 				)}
 			</div>
 		</div>
@@ -118,48 +106,52 @@ function PanelHeader({
 }
 
 function DesktopPanel({
-	isFolded,
+	isCollapsed,
 	side,
 	creatureName,
 	panelRole,
 	showPinButton,
-	onToggleFold,
+	onToggleCollapse,
 	onPin,
 	onUnpin,
 	children,
-}: {
-	isFolded: boolean;
+}: Readonly<{
+	isCollapsed: boolean;
 	side: "left" | "right";
 	creatureName: string;
 	panelRole: "browse" | "pinned";
 	showPinButton: boolean;
-	onToggleFold: () => void;
+	onToggleCollapse: () => void;
 	onPin: () => void;
 	onUnpin: () => void;
 	children: ReactNode;
-}) {
+}>) {
 	const sideClasses = side === "left" ? "left-0 border-r" : "right-0 border-l";
-	const foldedTranslate =
+	const collapsedTranslate =
 		side === "right"
 			? "translate-x-[calc(100%-40px)]"
 			: "translate-x-[calc(-100%+40px)]";
 
 	return (
 		<div
-			className={`fixed top-0 bottom-0 flex w-[400px] flex-col border-border bg-card transition-slide-panel ${sideClasses} ${isFolded ? foldedTranslate : "translate-x-0"}`}
+			className={cn(
+				"panel-glow fixed top-0 bottom-0 flex w-[400px] flex-col border-border bg-card transition-slide-panel",
+				sideClasses,
+				isCollapsed ? collapsedTranslate : "translate-x-0",
+			)}
 		>
-			{isFolded ? (
-				<FoldedTab
+			{isCollapsed ? (
+				<CollapsedTab
 					creatureName={creatureName}
 					side={side}
-					onToggleFold={onToggleFold}
+					onToggleCollapse={onToggleCollapse}
 				/>
 			) : (
 				<>
 					<PanelHeader
 						panelRole={panelRole}
 						showPinButton={showPinButton}
-						onToggleFold={onToggleFold}
+						onToggleCollapse={onToggleCollapse}
 						onPin={onPin}
 						onUnpin={onUnpin}
 					/>
@@ -173,36 +165,40 @@ function DesktopPanel({
 function MobileDrawer({
 	onDismiss,
 	children,
-}: {
+}: Readonly<{
 	onDismiss: () => void;
 	children: ReactNode;
-}) {
+}>) {
 	const { offsetX, isSwiping, handlers } = useSwipeToDismiss(onDismiss);
 
 	return (
 		<div className="fixed inset-0 z-50">
 			<button
 				type="button"
-				className="absolute inset-0 bg-black/50 animate-in fade-in"
+				className="fade-in absolute inset-0 animate-in bg-black/50"
 				onClick={onDismiss}
 				aria-label="Close stat block"
 			/>
 			<div
-				className={`absolute top-0 right-0 bottom-0 w-[85%] max-w-md border-l border-border bg-card shadow-xl ${isSwiping ? "" : "animate-slide-in-right"}`}
+				className={cn(
+					"panel-glow absolute top-0 right-0 bottom-0 w-[85%] max-w-md border-border border-l bg-card",
+					!isSwiping && "animate-slide-in-right",
+				)}
 				style={
 					isSwiping ? { transform: `translateX(${offsetX}px)` } : undefined
 				}
 				{...handlers}
 			>
-				<div className="flex items-center justify-between border-b border-border px-4 py-2">
-					<button
-						type="button"
+				<div className="flex items-center justify-between border-border border-b px-4 py-2">
+					<Button
+						variant="ghost"
+						size="icon-sm"
 						onClick={onDismiss}
-						className="text-muted-foreground hover:text-hover-neutral"
-						aria-label="Fold stat block panel"
+						className="text-muted-foreground"
+						aria-label="Collapse stat block panel"
 					>
 						<PanelRightClose className="h-4 w-4" />
-					</button>
+					</Button>
 				</div>
 				<div className="h-[calc(100%-41px)] overflow-y-auto p-4">
 					{children}
@@ -212,34 +208,57 @@ function MobileDrawer({
 	);
 }
 
+function usePanelRole(panelRole: "browse" | "pinned") {
+	const sidePanel = useSidePanelContext();
+	const { getCreature } = useBestiaryContext();
+
+	const creatureId =
+		panelRole === "browse"
+			? sidePanel.selectedCreatureId
+			: sidePanel.pinnedCreatureId;
+	const creature = creatureId ? (getCreature(creatureId) ?? null) : null;
+
+	const isBrowse = panelRole === "browse";
+	return {
+		creatureId,
+		creature,
+		isCollapsed: isBrowse ? sidePanel.isRightPanelCollapsed : false,
+		onToggleCollapse: isBrowse ? sidePanel.toggleCollapse : () => {},
+		onDismiss: isBrowse ? sidePanel.dismissPanel : () => {},
+		onPin: isBrowse ? sidePanel.togglePin : () => {},
+		onUnpin: panelRole === "pinned" ? sidePanel.unpin : () => {},
+		showPinButton: isBrowse && sidePanel.isWideDesktop && !!creature,
+		bulkImportMode: isBrowse && sidePanel.bulkImportMode,
+		sourceManagerMode: isBrowse && sidePanel.sourceManagerMode,
+	};
+}
+
 export function StatBlockPanel({
-	creatureId,
-	creature,
-	isSourceCached,
-	fetchAndCacheSource,
-	uploadAndCacheSource,
-	refreshCache,
 	panelRole,
-	isFolded,
-	onToggleFold,
-	onPin,
-	onUnpin,
-	showPinButton,
 	side,
-	onDismiss,
-	bulkImportMode,
-	bulkImportState,
-	onStartBulkImport,
-	onBulkImportDone,
-}: StatBlockPanelProps) {
+}: Readonly<StatBlockPanelProps>) {
+	const { isSourceCached } = useBestiaryContext();
+	const {
+		creatureId,
+		creature,
+		isCollapsed,
+		onToggleCollapse,
+		onDismiss,
+		onPin,
+		onUnpin,
+		showPinButton,
+		bulkImportMode,
+		sourceManagerMode,
+	} = usePanelRole(panelRole);
+
 	const [isDesktop, setIsDesktop] = useState(
-		() => window.matchMedia("(min-width: 1024px)").matches,
+		() => globalThis.matchMedia("(min-width: 1024px)").matches,
 	);
 	const [needsFetch, setNeedsFetch] = useState(false);
 	const [checkingCache, setCheckingCache] = useState(false);
 
 	useEffect(() => {
-		const mq = window.matchMedia("(min-width: 1024px)");
+		const mq = globalThis.matchMedia("(min-width: 1024px)");
 		const handler = (e: MediaQueryListEvent) => setIsDesktop(e.matches);
 		mq.addEventListener("change", handler);
 		return () => mq.removeEventListener("change", handler);
@@ -258,40 +277,32 @@ export function StatBlockPanel({
 		}
 
 		setCheckingCache(true);
-		isSourceCached(sourceCode).then((cached) => {
+		void isSourceCached(sourceCode).then((cached) => {
 			setNeedsFetch(!cached);
 			setCheckingCache(false);
 		});
 	}, [creatureId, creature, isSourceCached]);
 
-	if (!creatureId && !bulkImportMode) return null;
+	if (!creatureId && !bulkImportMode && !sourceManagerMode) return null;
 
 	const sourceCode = creatureId ? extractSourceCode(creatureId) : "";
 
-	const handleSourceLoaded = async () => {
-		await refreshCache();
+	const handleSourceLoaded = () => {
 		setNeedsFetch(false);
 	};
 
 	const renderContent = () => {
-		if (
-			bulkImportMode &&
-			bulkImportState &&
-			onStartBulkImport &&
-			onBulkImportDone
-		) {
-			return (
-				<BulkImportPrompt
-					importState={bulkImportState}
-					onStartImport={onStartBulkImport}
-					onDone={onBulkImportDone}
-				/>
-			);
+		if (sourceManagerMode) {
+			return <SourceManager />;
+		}
+
+		if (bulkImportMode) {
+			return <BulkImportPrompt />;
 		}
 
 		if (checkingCache) {
 			return (
-				<div className="p-4 text-sm text-muted-foreground">Loading...</div>
+				<div className="p-4 text-muted-foreground text-sm">Loading...</div>
 			);
 		}
 
@@ -303,33 +314,32 @@ export function StatBlockPanel({
 			return (
 				<SourceFetchPrompt
 					sourceCode={sourceCode}
-					sourceDisplayName={getSourceDisplayName(sourceCode)}
-					fetchAndCacheSource={fetchAndCacheSource}
 					onSourceLoaded={handleSourceLoaded}
-					onUploadSource={uploadAndCacheSource}
 				/>
 			);
 		}
 
 		return (
-			<div className="p-4 text-sm text-muted-foreground">
+			<div className="p-4 text-muted-foreground text-sm">
 				No stat block available
 			</div>
 		);
 	};
 
-	const creatureName =
-		creature?.name ?? (bulkImportMode ? "Bulk Import" : "Creature");
+	let fallbackName = "Creature";
+	if (sourceManagerMode) fallbackName = "Sources";
+	else if (bulkImportMode) fallbackName = "Import All Sources";
+	const creatureName = creature?.name ?? fallbackName;
 
 	if (isDesktop) {
 		return (
 			<DesktopPanel
-				isFolded={isFolded}
+				isCollapsed={isCollapsed}
 				side={side}
 				creatureName={creatureName}
 				panelRole={panelRole}
 				showPinButton={showPinButton}
-				onToggleFold={onToggleFold}
+				onToggleCollapse={onToggleCollapse}
 				onPin={onPin}
 				onUnpin={onUnpin}
 			>
@@ -338,7 +348,7 @@ export function StatBlockPanel({
 		);
 	}
 
-	if (panelRole === "pinned") return null;
+	if (panelRole === "pinned" || isCollapsed) return null;
 
 	return <MobileDrawer onDismiss={onDismiss}>{renderContent()}</MobileDrawer>;
 }

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

@@ -16,10 +16,10 @@ function abilityMod(score: number): string {
 function PropertyLine({
 	label,
 	value,
-}: {
+}: Readonly<{
 	label: string;
 	value: string | undefined;
-}) {
+}>) {
 	if (!value) return null;
 	return (
 		<div className="text-sm">
@@ -30,11 +30,11 @@ function PropertyLine({
 
 function SectionDivider() {
 	return (
-		<div className="my-2 h-px bg-gradient-to-r from-amber-800/60 via-amber-700/40 to-transparent" />
+		<div className="my-2 h-px bg-gradient-to-r from-stat-divider-from via-stat-divider-via to-transparent" />
 	);
 }
 
-export function StatBlock({ creature }: StatBlockProps) {
+export function StatBlock({ creature }: Readonly<StatBlockProps>) {
 	const abilities = [
 		{ label: "STR", score: creature.abilities.str },
 		{ label: "DEX", score: creature.abilities.dex },
@@ -54,11 +54,11 @@ export function StatBlock({ creature }: StatBlockProps) {
 		<div className="space-y-1 text-foreground">
 			{/* Header */}
 			<div>
-				<h2 className="text-xl font-bold text-amber-400">{creature.name}</h2>
-				<p className="text-sm italic text-muted-foreground">
+				<h2 className="font-bold text-stat-heading text-xl">{creature.name}</h2>
+				<p className="text-muted-foreground text-sm italic">
 					{creature.size} {creature.type}, {creature.alignment}
 				</p>
-				<p className="text-xs text-muted-foreground">
+				<p className="text-muted-foreground text-xs">
 					{creature.sourceDisplayName}
 				</p>
 			</div>
@@ -69,7 +69,7 @@ export function StatBlock({ creature }: StatBlockProps) {
 			<div className="space-y-0.5 text-sm">
 				<div>
 					<span className="font-semibold">Armor Class</span> {creature.ac}
-					{creature.acSource && (
+					{!!creature.acSource && (
 						<span className="text-muted-foreground">
 							{" "}
 							({creature.acSource})
@@ -194,7 +194,7 @@ export function StatBlock({ creature }: StatBlockProps) {
 			{creature.actions && creature.actions.length > 0 && (
 				<>
 					<SectionDivider />
-					<h3 className="text-base font-bold text-amber-400">Actions</h3>
+					<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">
@@ -209,7 +209,9 @@ export function StatBlock({ creature }: StatBlockProps) {
 			{creature.bonusActions && creature.bonusActions.length > 0 && (
 				<>
 					<SectionDivider />
-					<h3 className="text-base font-bold text-amber-400">Bonus Actions</h3>
+					<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">
@@ -224,7 +226,7 @@ export function StatBlock({ creature }: StatBlockProps) {
 			{creature.reactions && creature.reactions.length > 0 && (
 				<>
 					<SectionDivider />
-					<h3 className="text-base font-bold text-amber-400">Reactions</h3>
+					<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">
@@ -236,13 +238,13 @@ export function StatBlock({ creature }: StatBlockProps) {
 			)}
 
 			{/* Legendary Actions */}
-			{creature.legendaryActions && (
+			{!!creature.legendaryActions && (
 				<>
 					<SectionDivider />
-					<h3 className="text-base font-bold text-amber-400">
+					<h3 className="font-bold text-base text-stat-heading">
 						Legendary Actions
 					</h3>
-					<p className="text-sm italic text-muted-foreground">
+					<p className="text-muted-foreground text-sm italic">
 						{creature.legendaryActions.preamble}
 					</p>
 					<div className="space-y-2">

apps/web/src/components/toast.tsx

@@ -1,6 +1,7 @@
 import { X } from "lucide-react";
 import { useEffect } from "react";
 import { createPortal } from "react-dom";
+import { Button } from "./ui/button.js";
 
 interface ToastProps {
 	message: string;
@@ -22,9 +23,9 @@ export function Toast({
 	}, [autoDismissMs, onDismiss]);
 
 	return createPortal(
-		<div className="fixed bottom-4 left-1/2 z-50 -translate-x-1/2">
-			<div className="flex items-center gap-3 rounded-lg border border-border bg-card px-4 py-3 shadow-lg">
-				<span className="text-sm text-foreground">{message}</span>
+		<div className="fixed bottom-4 left-4 z-50">
+			<div className="card-glow flex items-center gap-3 rounded-lg border border-border bg-card px-4 py-3">
+				<span className="text-foreground text-sm">{message}</span>
 				{progress !== undefined && (
 					<div className="h-2 w-24 overflow-hidden rounded-full bg-muted">
 						<div
@@ -33,13 +34,14 @@ export function Toast({
 						/>
 					</div>
 				)}
-				<button
-					type="button"
+				<Button
+					variant="ghost"
+					size="icon-sm"
 					onClick={onDismiss}
-					className="text-muted-foreground hover:text-hover-neutral"
+					className="text-muted-foreground"
 				>
 					<X className="h-3 w-3" />
-				</button>
+				</Button>
 			</div>
 		</div>,
 		document.body,

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

@@ -1,35 +1,30 @@
-import type { Encounter } from "@initiative/domain";
-import { Library, StepBack, StepForward, Trash2 } from "lucide-react";
-import { D20Icon } from "./d20-icon";
-import { Button } from "./ui/button";
-import { ConfirmButton } from "./ui/confirm-button";
+import { Redo2, StepBack, StepForward, Trash2, Undo2 } from "lucide-react";
+import { useEncounterContext } from "../contexts/encounter-context.js";
+import { Button } from "./ui/button.js";
+import { ConfirmButton } from "./ui/confirm-button.js";
 
-interface TurnNavigationProps {
-	encounter: Encounter;
-	onAdvanceTurn: () => void;
-	onRetreatTurn: () => void;
-	onClearEncounter: () => void;
-	onRollAllInitiative: () => void;
-	onOpenSourceManager: () => void;
-}
+export function TurnNavigation() {
+	const {
+		encounter,
+		advanceTurn,
+		retreatTurn,
+		clearEncounter,
+		undo,
+		redo,
+		canUndo,
+		canRedo,
+	} = useEncounterContext();
 
-export function TurnNavigation({
-	encounter,
-	onAdvanceTurn,
-	onRetreatTurn,
-	onClearEncounter,
-	onRollAllInitiative,
-	onOpenSourceManager,
-}: TurnNavigationProps) {
 	const hasCombatants = encounter.combatants.length > 0;
 	const isAtStart = encounter.roundNumber === 1 && encounter.activeIndex === 0;
 	const activeCombatant = encounter.combatants[encounter.activeIndex];
 
 	return (
-		<div className="flex items-center gap-3 rounded-md border border-border bg-card px-4 py-3">
+		<div className="card-glow flex items-center gap-3 border-border border-b bg-card px-4 py-3 sm:rounded-lg sm:border">
 			<Button
+				variant="ghost"
 				size="icon"
-				onClick={onRetreatTurn}
+				onClick={retreatTurn}
 				disabled={!hasCombatants || isAtStart}
 				title="Previous turn"
 				aria-label="Previous turn"
@@ -37,9 +32,34 @@ export function TurnNavigation({
 				<StepBack className="h-5 w-5" />
 			</Button>
 
-			<div className="min-w-0 flex-1 flex items-center justify-center gap-2 text-sm">
-				<span className="rounded-full bg-muted text-foreground text-sm px-2 py-0.5 font-semibold shrink-0">
-					R{encounter.roundNumber}
+			<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">
+						R{encounter.roundNumber}
+					</span>
 				</span>
 				{activeCombatant ? (
 					<span className="truncate font-medium">{activeCombatant.name}</span>
@@ -49,38 +69,17 @@ export function TurnNavigation({
 			</div>
 
 			<div className="flex flex-shrink-0 items-center gap-3">
-				<div className="flex items-center gap-0">
-					<Button
-						variant="ghost"
-						size="icon"
-						className="text-muted-foreground hover:text-hover-action"
-						onClick={onRollAllInitiative}
-						title="Roll all initiative"
-						aria-label="Roll all initiative"
-					>
-						<D20Icon className="h-6 w-6" />
-					</Button>
-					<Button
-						variant="ghost"
-						size="icon"
-						className="text-muted-foreground hover:text-hover-neutral"
-						onClick={onOpenSourceManager}
-						title="Manage cached sources"
-						aria-label="Manage cached sources"
-					>
-						<Library className="h-5 w-5" />
-					</Button>
-					<ConfirmButton
-						icon={<Trash2 className="h-5 w-5" />}
-						label="Clear encounter"
-						onConfirm={onClearEncounter}
-						disabled={!hasCombatants}
-						className="text-muted-foreground"
-					/>
-				</div>
+				<ConfirmButton
+					icon={<Trash2 className="h-5 w-5" />}
+					label="Clear encounter"
+					onConfirm={clearEncounter}
+					disabled={!hasCombatants}
+					className="text-muted-foreground"
+				/>
 				<Button
+					variant="ghost"
 					size="icon"
-					onClick={onAdvanceTurn}
+					onClick={advanceTurn}
 					disabled={!hasCombatants}
 					title="Next turn"
 					aria-label="Next turn"

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

@@ -9,13 +9,14 @@ const buttonVariants = cva(
 			variant: {
 				default: "bg-primary text-primary-foreground hover:bg-primary/90",
 				outline:
-					"border border-border bg-transparent hover:bg-hover-neutral-bg hover:text-hover-neutral",
-				ghost: "hover:bg-hover-neutral-bg hover:text-hover-neutral",
+					"border border-border bg-background/50 text-foreground hover:bg-hover-neutral-bg hover:text-hover-neutral",
+				ghost:
+					"text-foreground hover:bg-hover-neutral-bg hover:text-hover-neutral",
 			},
 			size: {
-				default: "h-9 px-4 py-2",
-				sm: "h-8 px-3 text-xs",
+				default: "h-8 px-3 text-xs",
 				icon: "h-8 w-8",
+				"icon-sm": "h-6 w-6",
 			},
 		},
 		defaultVariants: {

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

@@ -13,6 +13,7 @@ interface ConfirmButtonProps {
 	readonly onConfirm: () => void;
 	readonly icon: ReactElement;
 	readonly label: string;
+	readonly size?: "icon" | "icon-sm";
 	readonly className?: string;
 	readonly disabled?: boolean;
 }
@@ -23,6 +24,7 @@ export function ConfirmButton({
 	onConfirm,
 	icon,
 	label,
+	size = "icon",
 	className,
 	disabled,
 }: ConfirmButtonProps) {
@@ -53,17 +55,17 @@ export function ConfirmButton({
 			}
 		}
 
-		function handleKeyDown(e: KeyboardEvent) {
+		function handleEscapeKey(e: KeyboardEvent) {
 			if (e.key === "Escape") {
 				revert();
 			}
 		}
 
 		document.addEventListener("mousedown", handleMouseDown);
-		document.addEventListener("keydown", handleKeyDown);
+		document.addEventListener("keydown", handleEscapeKey);
 		return () => {
 			document.removeEventListener("mousedown", handleMouseDown);
-			document.removeEventListener("keydown", handleKeyDown);
+			document.removeEventListener("keydown", handleEscapeKey);
 		};
 	}, [isConfirming, revert]);
 
@@ -94,11 +96,12 @@ export function ConfirmButton({
 		<div ref={wrapperRef} className="inline-flex">
 			<Button
 				variant="ghost"
-				size="icon"
+				size={size}
 				className={cn(
 					className,
-					isConfirming &&
-						"bg-destructive text-primary-foreground rounded-md animate-confirm-pulse hover:bg-destructive hover:text-primary-foreground",
+					isConfirming
+						? "animate-confirm-pulse rounded-md bg-destructive text-primary-foreground hover:bg-destructive hover:text-primary-foreground"
+						: "hover:text-hover-destructive",
 				)}
 				onClick={handleClick}
 				onKeyDown={handleKeyDown}
@@ -107,7 +110,8 @@ export function ConfirmButton({
 				aria-label={isConfirming ? `Confirm ${label.toLowerCase()}` : label}
 				title={isConfirming ? `Confirm ${label.toLowerCase()}` : label}
 			>
-				{isConfirming ? <Check size={16} /> : icon}
+				{isConfirming ? <Check size={16} /> : null}
+				{!isConfirming && icon}
 			</Button>
 		</div>
 	);

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

@@ -0,0 +1,50 @@
+import { type ReactNode, useEffect, useRef } from "react";
+import { cn } from "../../lib/utils.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>
+	);
+}

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

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

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

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

@@ -0,0 +1,55 @@
+import { type ReactNode, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+
+interface TooltipProps {
+	content: string;
+	children: ReactNode;
+	className?: string;
+}
+
+export function Tooltip({
+	content,
+	children,
+	className,
+}: Readonly<TooltipProps>) {
+	const ref = useRef<HTMLSpanElement>(null);
+	const [pos, setPos] = useState<{ top: number; left: number } | null>(null);
+
+	function show() {
+		const el = ref.current;
+		if (!el) return;
+		const rect = el.getBoundingClientRect();
+		setPos({
+			top: rect.top - 4,
+			left: rect.left + rect.width / 2,
+		});
+	}
+
+	function hide() {
+		setPos(null);
+	}
+
+	return (
+		<>
+			<span
+				ref={ref}
+				onPointerEnter={show}
+				onPointerLeave={hide}
+				className={className ?? "inline-flex"}
+			>
+				{children}
+			</span>
+			{pos !== null &&
+				createPortal(
+					<div
+						role="tooltip"
+						className="pointer-events-none fixed z-[60] max-w-64 -translate-x-1/2 -translate-y-full whitespace-pre-line rounded-md border border-border bg-background px-2.5 py-1.5 text-foreground text-xs leading-snug shadow-lg"
+						style={{ top: pos.top, left: pos.left }}
+					>
+						{content}
+					</div>,
+					document.body,
+				)}
+		</>
+	);
+}

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

@@ -0,0 +1,23 @@
+import { createContext, type ReactNode, useContext } from "react";
+import { useBestiary } from "../hooks/use-bestiary.js";
+
+export type { SearchResult } from "../hooks/use-bestiary.js";
+
+type BestiaryContextValue = ReturnType<typeof useBestiary>;
+
+const BestiaryContext = createContext<BestiaryContextValue | null>(null);
+
+export function BestiaryProvider({ children }: { children: ReactNode }) {
+	const value = useBestiary();
+	return (
+		<BestiaryContext.Provider value={value}>
+			{children}
+		</BestiaryContext.Provider>
+	);
+}
+
+export function useBestiaryContext(): BestiaryContextValue {
+	const ctx = useContext(BestiaryContext);
+	if (!ctx) throw new Error("useBestiaryContext requires BestiaryProvider");
+	return ctx;
+}

apps/web/src/contexts/bulk-import-context.tsx

@@ -0,0 +1,21 @@
+import { createContext, type ReactNode, useContext } from "react";
+import { useBulkImport } from "../hooks/use-bulk-import.js";
+
+type BulkImportContextValue = ReturnType<typeof useBulkImport>;
+
+const BulkImportContext = createContext<BulkImportContextValue | null>(null);
+
+export function BulkImportProvider({ children }: { children: ReactNode }) {
+	const value = useBulkImport();
+	return (
+		<BulkImportContext.Provider value={value}>
+			{children}
+		</BulkImportContext.Provider>
+	);
+}
+
+export function useBulkImportContext(): BulkImportContextValue {
+	const ctx = useContext(BulkImportContext);
+	if (!ctx) throw new Error("useBulkImportContext requires BulkImportProvider");
+	return ctx;
+}

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

@@ -0,0 +1,23 @@
+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>;
+
+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}
+		</EncounterContext.Provider>
+	);
+}
+
+export function useEncounterContext(): EncounterContextValue {
+	const ctx = useContext(EncounterContext);
+	if (!ctx) throw new Error("useEncounterContext requires EncounterProvider");
+	return ctx;
+}

apps/web/src/contexts/index.ts

@@ -0,0 +1,8 @@
+export { BestiaryProvider } from "./bestiary-context.js";
+export { BulkImportProvider } from "./bulk-import-context.js";
+export { EncounterProvider } from "./encounter-context.js";
+export { InitiativeRollsProvider } from "./initiative-rolls-context.js";
+export { PlayerCharactersProvider } from "./player-characters-context.js";
+export { RulesEditionProvider } from "./rules-edition-context.js";
+export { SidePanelProvider } from "./side-panel-context.js";
+export { ThemeProvider } from "./theme-context.js";

apps/web/src/contexts/initiative-rolls-context.tsx

@@ -0,0 +1,25 @@
+import { createContext, type ReactNode, useContext } from "react";
+import { useInitiativeRolls } from "../hooks/use-initiative-rolls.js";
+
+type InitiativeRollsContextValue = ReturnType<typeof useInitiativeRolls>;
+
+const InitiativeRollsContext =
+	createContext<InitiativeRollsContextValue | null>(null);
+
+export function InitiativeRollsProvider({ children }: { children: ReactNode }) {
+	const value = useInitiativeRolls();
+	return (
+		<InitiativeRollsContext.Provider value={value}>
+			{children}
+		</InitiativeRollsContext.Provider>
+	);
+}
+
+export function useInitiativeRollsContext(): InitiativeRollsContextValue {
+	const ctx = useContext(InitiativeRollsContext);
+	if (!ctx)
+		throw new Error(
+			"useInitiativeRollsContext requires InitiativeRollsProvider",
+		);
+	return ctx;
+}

apps/web/src/contexts/player-characters-context.tsx

@@ -0,0 +1,29 @@
+import { createContext, type ReactNode, useContext } from "react";
+import { usePlayerCharacters } from "../hooks/use-player-characters.js";
+
+type PlayerCharactersContextValue = ReturnType<typeof usePlayerCharacters>;
+
+const PlayerCharactersContext =
+	createContext<PlayerCharactersContextValue | null>(null);
+
+export function PlayerCharactersProvider({
+	children,
+}: {
+	children: ReactNode;
+}) {
+	const value = usePlayerCharacters();
+	return (
+		<PlayerCharactersContext.Provider value={value}>
+			{children}
+		</PlayerCharactersContext.Provider>
+	);
+}
+
+export function usePlayerCharactersContext(): PlayerCharactersContextValue {
+	const ctx = useContext(PlayerCharactersContext);
+	if (!ctx)
+		throw new Error(
+			"usePlayerCharactersContext requires PlayerCharactersProvider",
+		);
+	return ctx;
+}

apps/web/src/contexts/rules-edition-context.tsx

@@ -0,0 +1,24 @@
+import { createContext, type ReactNode, useContext } from "react";
+import { useRulesEdition } from "../hooks/use-rules-edition.js";
+
+type RulesEditionContextValue = ReturnType<typeof useRulesEdition>;
+
+const RulesEditionContext = createContext<RulesEditionContextValue | null>(
+	null,
+);
+
+export function RulesEditionProvider({ children }: { children: ReactNode }) {
+	const value = useRulesEdition();
+	return (
+		<RulesEditionContext.Provider value={value}>
+			{children}
+		</RulesEditionContext.Provider>
+	);
+}
+
+export function useRulesEditionContext(): RulesEditionContextValue {
+	const ctx = useContext(RulesEditionContext);
+	if (!ctx)
+		throw new Error("useRulesEditionContext requires RulesEditionProvider");
+	return ctx;
+}

apps/web/src/contexts/side-panel-context.tsx

@@ -0,0 +1,21 @@
+import { createContext, type ReactNode, useContext } from "react";
+import { useSidePanelState } from "../hooks/use-side-panel-state.js";
+
+type SidePanelContextValue = ReturnType<typeof useSidePanelState>;
+
+const SidePanelContext = createContext<SidePanelContextValue | null>(null);
+
+export function SidePanelProvider({ children }: { children: ReactNode }) {
+	const value = useSidePanelState();
+	return (
+		<SidePanelContext.Provider value={value}>
+			{children}
+		</SidePanelContext.Provider>
+	);
+}
+
+export function useSidePanelContext(): SidePanelContextValue {
+	const ctx = useContext(SidePanelContext);
+	if (!ctx) throw new Error("useSidePanelContext requires SidePanelProvider");
+	return ctx;
+}

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

@@ -0,0 +1,19 @@
+import { createContext, type ReactNode, useContext } from "react";
+import { useTheme } from "../hooks/use-theme.js";
+
+type ThemeContextValue = ReturnType<typeof useTheme>;
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+	const value = useTheme();
+	return (
+		<ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
+	);
+}
+
+export function useThemeContext(): ThemeContextValue {
+	const ctx = useContext(ThemeContext);
+	if (!ctx) throw new Error("useThemeContext requires ThemeProvider");
+	return ctx;
+}

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

@@ -0,0 +1,225 @@
+// @vitest-environment jsdom
+import type { BestiaryIndexEntry, PlayerCharacter } from "@initiative/domain";
+import { combatantId, creatureId, playerCharacterId } from "@initiative/domain";
+import { act, renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { useEncounter } from "../use-encounter.js";
+
+vi.mock("../../persistence/encounter-storage.js", () => ({
+	loadEncounter: vi.fn().mockReturnValue(null),
+	saveEncounter: vi.fn(),
+}));
+
+const { loadEncounter: mockLoad, saveEncounter: mockSave } =
+	await vi.importMock<typeof import("../../persistence/encounter-storage.js")>(
+		"../../persistence/encounter-storage.js",
+	);
+
+describe("useEncounter", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockLoad.mockReturnValue(null);
+	});
+
+	it("initializes with empty encounter when persistence returns null", () => {
+		const { result } = renderHook(() => useEncounter());
+
+		expect(result.current.encounter.combatants).toEqual([]);
+		expect(result.current.encounter.activeIndex).toBe(0);
+		expect(result.current.encounter.roundNumber).toBe(1);
+		expect(result.current.isEmpty).toBe(true);
+	});
+
+	it("initializes from stored encounter", () => {
+		const stored = {
+			combatants: [{ id: combatantId("c-1"), name: "Goblin" }],
+			activeIndex: 0,
+			roundNumber: 2,
+		};
+		mockLoad.mockReturnValue(stored);
+
+		const { result } = renderHook(() => useEncounter());
+
+		expect(result.current.encounter.combatants).toHaveLength(1);
+		expect(result.current.encounter.roundNumber).toBe(2);
+		expect(result.current.isEmpty).toBe(false);
+	});
+
+	it("addCombatant adds a combatant with incremental IDs and persists", () => {
+		const { result } = renderHook(() => useEncounter());
+
+		act(() => result.current.addCombatant("Goblin"));
+		act(() => result.current.addCombatant("Orc"));
+
+		expect(result.current.encounter.combatants).toHaveLength(2);
+		expect(result.current.encounter.combatants[0].name).toBe("Goblin");
+		expect(result.current.encounter.combatants[1].name).toBe("Orc");
+		expect(result.current.isEmpty).toBe(false);
+		expect(mockSave).toHaveBeenCalled();
+	});
+
+	it("removeCombatant removes a combatant and persists", () => {
+		const { result } = renderHook(() => useEncounter());
+
+		act(() => result.current.addCombatant("Goblin"));
+		const id = result.current.encounter.combatants[0].id;
+
+		act(() => result.current.removeCombatant(id));
+
+		expect(result.current.encounter.combatants).toHaveLength(0);
+		expect(result.current.isEmpty).toBe(true);
+	});
+
+	it("advanceTurn and retreatTurn update encounter state", () => {
+		const { result } = renderHook(() => useEncounter());
+
+		act(() => result.current.addCombatant("Goblin"));
+		act(() => result.current.addCombatant("Orc"));
+
+		const initialActive = result.current.encounter.activeIndex;
+
+		act(() => result.current.advanceTurn());
+		expect(result.current.encounter.activeIndex).not.toBe(initialActive);
+
+		act(() => result.current.retreatTurn());
+		expect(result.current.encounter.activeIndex).toBe(initialActive);
+	});
+
+	it("clearEncounter resets to empty and resets ID counter", () => {
+		const { result } = renderHook(() => useEncounter());
+
+		act(() => result.current.addCombatant("Goblin"));
+		act(() => result.current.clearEncounter());
+
+		expect(result.current.encounter.combatants).toHaveLength(0);
+		expect(result.current.isEmpty).toBe(true);
+
+		// After clear, IDs restart from c-1
+		act(() => result.current.addCombatant("Orc"));
+		expect(result.current.encounter.combatants[0].id).toBe("c-1");
+	});
+
+	it("addCombatant with opts applies initiative, ac, maxHp", () => {
+		const { result } = renderHook(() => useEncounter());
+
+		act(() =>
+			result.current.addCombatant("Goblin", {
+				initiative: 15,
+				ac: 13,
+				maxHp: 7,
+			}),
+		);
+
+		const goblin = result.current.encounter.combatants[0];
+		expect(goblin.initiative).toBe(15);
+		expect(goblin.ac).toBe(13);
+		expect(goblin.maxHp).toBe(7);
+		expect(goblin.currentHp).toBe(7);
+	});
+
+	it("derived flags: hasCreatureCombatants and canRollAllInitiative", () => {
+		const { result } = renderHook(() => useEncounter());
+
+		// No creatures yet
+		expect(result.current.hasCreatureCombatants).toBe(false);
+		expect(result.current.canRollAllInitiative).toBe(false);
+
+		// Add from bestiary to get a creature combatant
+		const entry: BestiaryIndexEntry = {
+			name: "Goblin",
+			source: "MM",
+			ac: 15,
+			hp: 7,
+			dex: 14,
+			cr: "1/4",
+			initiativeProficiency: 0,
+			size: "Small",
+			type: "humanoid",
+		};
+
+		act(() => {
+			result.current.addFromBestiary(entry);
+		});
+
+		expect(result.current.hasCreatureCombatants).toBe(true);
+		expect(result.current.canRollAllInitiative).toBe(true);
+	});
+
+	it("addFromBestiary adds combatant with HP, AC, creatureId", () => {
+		const { result } = renderHook(() => useEncounter());
+
+		const entry: BestiaryIndexEntry = {
+			name: "Goblin",
+			source: "MM",
+			ac: 15,
+			hp: 7,
+			dex: 14,
+			cr: "1/4",
+			initiativeProficiency: 0,
+			size: "Small",
+			type: "humanoid",
+		};
+
+		act(() => {
+			result.current.addFromBestiary(entry);
+		});
+
+		const combatant = result.current.encounter.combatants[0];
+		expect(combatant.name).toBe("Goblin");
+		expect(combatant.maxHp).toBe(7);
+		expect(combatant.currentHp).toBe(7);
+		expect(combatant.ac).toBe(15);
+		expect(combatant.creatureId).toBe(creatureId("mm:goblin"));
+	});
+
+	it("addFromBestiary auto-numbers duplicate names", () => {
+		const { result } = renderHook(() => useEncounter());
+
+		const entry: BestiaryIndexEntry = {
+			name: "Goblin",
+			source: "MM",
+			ac: 15,
+			hp: 7,
+			dex: 14,
+			cr: "1/4",
+			initiativeProficiency: 0,
+			size: "Small",
+			type: "humanoid",
+		};
+
+		act(() => {
+			result.current.addFromBestiary(entry);
+		});
+		act(() => {
+			result.current.addFromBestiary(entry);
+		});
+
+		const names = result.current.encounter.combatants.map((c) => c.name);
+		expect(names).toContain("Goblin 1");
+		expect(names).toContain("Goblin 2");
+	});
+
+	it("addFromPlayerCharacter adds combatant with HP, AC, color, icon", () => {
+		const { result } = renderHook(() => useEncounter());
+
+		const pc: PlayerCharacter = {
+			id: playerCharacterId("pc-1"),
+			name: "Aria",
+			ac: 16,
+			maxHp: 30,
+			color: "blue",
+			icon: "sword",
+		};
+
+		act(() => result.current.addFromPlayerCharacter(pc));
+
+		const combatant = result.current.encounter.combatants[0];
+		expect(combatant.name).toBe("Aria");
+		expect(combatant.maxHp).toBe(30);
+		expect(combatant.currentHp).toBe(30);
+		expect(combatant.ac).toBe(16);
+		expect(combatant.color).toBe("blue");
+		expect(combatant.icon).toBe("sword");
+		expect(combatant.playerCharacterId).toBe(playerCharacterId("pc-1"));
+	});
+});

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

@@ -0,0 +1,100 @@
+// @vitest-environment jsdom
+import { playerCharacterId } from "@initiative/domain";
+import { act, renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { usePlayerCharacters } from "../use-player-characters.js";
+
+vi.mock("../../persistence/player-character-storage.js", () => ({
+	loadPlayerCharacters: vi.fn().mockReturnValue([]),
+	savePlayerCharacters: vi.fn(),
+}));
+
+const { loadPlayerCharacters: mockLoad, savePlayerCharacters: mockSave } =
+	await vi.importMock<
+		typeof import("../../persistence/player-character-storage.js")
+	>("../../persistence/player-character-storage.js");
+
+describe("usePlayerCharacters", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockLoad.mockReturnValue([]);
+	});
+
+	it("initializes with characters from persistence", () => {
+		const stored = [
+			{
+				id: playerCharacterId("pc-1"),
+				name: "Aria",
+				ac: 16,
+				maxHp: 30,
+				color: undefined,
+				icon: undefined,
+			},
+		];
+		mockLoad.mockReturnValue(stored);
+
+		const { result } = renderHook(() => usePlayerCharacters());
+
+		expect(result.current.characters).toEqual(stored);
+	});
+
+	it("createCharacter adds a character and persists", () => {
+		const { result } = renderHook(() => usePlayerCharacters());
+
+		act(() => {
+			result.current.createCharacter("Vex", 15, 28, undefined, undefined);
+		});
+
+		expect(result.current.characters).toHaveLength(1);
+		expect(result.current.characters[0].name).toBe("Vex");
+		expect(result.current.characters[0].ac).toBe(15);
+		expect(result.current.characters[0].maxHp).toBe(28);
+		expect(mockSave).toHaveBeenCalled();
+	});
+
+	it("createCharacter returns domain error for empty name", () => {
+		const { result } = renderHook(() => usePlayerCharacters());
+
+		let error: unknown;
+		act(() => {
+			error = result.current.createCharacter("", 15, 28, undefined, undefined);
+		});
+
+		expect(error).toMatchObject({ kind: "domain-error" });
+		expect(result.current.characters).toHaveLength(0);
+	});
+
+	it("editCharacter updates character and persists", () => {
+		const { result } = renderHook(() => usePlayerCharacters());
+
+		act(() => {
+			result.current.createCharacter("Vex", 15, 28, undefined, undefined);
+		});
+
+		const id = result.current.characters[0].id;
+
+		act(() => {
+			result.current.editCharacter(id, { name: "Vex'ahlia" });
+		});
+
+		expect(result.current.characters[0].name).toBe("Vex'ahlia");
+		expect(mockSave).toHaveBeenCalled();
+	});
+
+	it("deleteCharacter removes character and persists", () => {
+		const { result } = renderHook(() => usePlayerCharacters());
+
+		act(() => {
+			result.current.createCharacter("Vex", 15, 28, undefined, undefined);
+		});
+
+		const id = result.current.characters[0].id;
+
+		act(() => {
+			result.current.deleteCharacter(id);
+		});
+
+		expect(result.current.characters).toHaveLength(0);
+		expect(mockSave).toHaveBeenCalled();
+	});
+});

apps/web/src/hooks/__tests__/use-side-panel-state.test.ts

@@ -0,0 +1,159 @@
+// @vitest-environment jsdom
+import { creatureId } from "@initiative/domain";
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useSidePanelState } from "../use-side-panel-state.js";
+
+function mockMatchMedia(matches: boolean) {
+	const listeners: Array<(e: MediaQueryListEvent) => void> = [];
+	const mql = {
+		matches,
+		addEventListener: vi.fn(
+			(_event: string, handler: (e: MediaQueryListEvent) => void) => {
+				listeners.push(handler);
+			},
+		),
+		removeEventListener: vi.fn(),
+	};
+	globalThis.matchMedia = vi.fn().mockReturnValue(mql) as typeof matchMedia;
+	return { mql, listeners };
+}
+
+const CREATURE_A = creatureId("creature-a");
+
+describe("useSidePanelState", () => {
+	it("starts with closed panel, no selection, not collapsed", () => {
+		mockMatchMedia(false);
+		const { result } = renderHook(() => useSidePanelState());
+
+		expect(result.current.panelView).toEqual({ mode: "closed" });
+		expect(result.current.selectedCreatureId).toBeNull();
+		expect(result.current.isRightPanelCollapsed).toBe(false);
+		expect(result.current.bulkImportMode).toBe(false);
+		expect(result.current.sourceManagerMode).toBe(false);
+		expect(result.current.pinnedCreatureId).toBeNull();
+	});
+
+	it("showCreature sets creature mode and selectedCreatureId", () => {
+		mockMatchMedia(false);
+		const { result } = renderHook(() => useSidePanelState());
+
+		act(() => result.current.showCreature(CREATURE_A));
+
+		expect(result.current.panelView).toEqual({
+			mode: "creature",
+			creatureId: CREATURE_A,
+		});
+		expect(result.current.selectedCreatureId).toBe(CREATURE_A);
+	});
+
+	it("showBulkImport sets bulk-import mode, selectedCreatureId null", () => {
+		mockMatchMedia(false);
+		const { result } = renderHook(() => useSidePanelState());
+
+		act(() => result.current.showBulkImport());
+
+		expect(result.current.panelView).toEqual({ mode: "bulk-import" });
+		expect(result.current.selectedCreatureId).toBeNull();
+		expect(result.current.bulkImportMode).toBe(true);
+	});
+
+	it("showSourceManager sets source-manager mode", () => {
+		mockMatchMedia(false);
+		const { result } = renderHook(() => useSidePanelState());
+
+		act(() => result.current.showSourceManager());
+
+		expect(result.current.panelView).toEqual({ mode: "source-manager" });
+		expect(result.current.sourceManagerMode).toBe(true);
+	});
+
+	it("dismissPanel sets mode to closed", () => {
+		mockMatchMedia(false);
+		const { result } = renderHook(() => useSidePanelState());
+
+		act(() => result.current.showCreature(CREATURE_A));
+		act(() => result.current.dismissPanel());
+
+		expect(result.current.panelView).toEqual({ mode: "closed" });
+	});
+
+	it("toggleCollapse flips isRightPanelCollapsed", () => {
+		mockMatchMedia(false);
+		const { result } = renderHook(() => useSidePanelState());
+
+		expect(result.current.isRightPanelCollapsed).toBe(false);
+
+		act(() => result.current.toggleCollapse());
+		expect(result.current.isRightPanelCollapsed).toBe(true);
+
+		act(() => result.current.toggleCollapse());
+		expect(result.current.isRightPanelCollapsed).toBe(false);
+	});
+
+	it("showCreature resets collapse state", () => {
+		mockMatchMedia(false);
+		const { result } = renderHook(() => useSidePanelState());
+
+		act(() => result.current.toggleCollapse());
+		expect(result.current.isRightPanelCollapsed).toBe(true);
+
+		act(() => result.current.showCreature(CREATURE_A));
+		expect(result.current.isRightPanelCollapsed).toBe(false);
+	});
+
+	it("togglePin pins the selected creature", () => {
+		mockMatchMedia(false);
+		const { result } = renderHook(() => useSidePanelState());
+
+		act(() => result.current.showCreature(CREATURE_A));
+		act(() => result.current.togglePin());
+
+		expect(result.current.pinnedCreatureId).toBe(CREATURE_A);
+	});
+
+	it("togglePin unpins when already pinned to same creature", () => {
+		mockMatchMedia(false);
+		const { result } = renderHook(() => useSidePanelState());
+
+		act(() => result.current.showCreature(CREATURE_A));
+		act(() => result.current.togglePin());
+		act(() => result.current.togglePin());
+
+		expect(result.current.pinnedCreatureId).toBeNull();
+	});
+
+	it("togglePin does nothing when no creature is selected", () => {
+		mockMatchMedia(false);
+		const { result } = renderHook(() => useSidePanelState());
+
+		act(() => result.current.togglePin());
+
+		expect(result.current.pinnedCreatureId).toBeNull();
+	});
+
+	it("unpin clears pinned creature", () => {
+		mockMatchMedia(false);
+		const { result } = renderHook(() => useSidePanelState());
+
+		act(() => result.current.showCreature(CREATURE_A));
+		act(() => result.current.togglePin());
+		act(() => result.current.unpin());
+
+		expect(result.current.pinnedCreatureId).toBeNull();
+	});
+
+	it("isWideDesktop reflects matchMedia result", () => {
+		mockMatchMedia(true);
+		const { result } = renderHook(() => useSidePanelState());
+
+		expect(result.current.isWideDesktop).toBe(true);
+	});
+
+	it("isWideDesktop is false on narrow viewport", () => {
+		mockMatchMedia(false);
+		const { result } = renderHook(() => useSidePanelState());
+
+		expect(result.current.isWideDesktop).toBe(false);
+	});
+});

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

@@ -0,0 +1,38 @@
+import { useLayoutEffect, useRef, useState } from "react";
+
+export function useActionBarAnimation(combatantCount: number) {
+	const wasEmptyRef = useRef(combatantCount === 0);
+	const [settling, setSettling] = useState(false);
+	const [rising, setRising] = useState(false);
+	const [topBarExiting, setTopBarExiting] = useState(false);
+
+	useLayoutEffect(() => {
+		const nowEmpty = combatantCount === 0;
+		if (wasEmptyRef.current && !nowEmpty) {
+			setSettling(true);
+		} else if (!wasEmptyRef.current && nowEmpty) {
+			setRising(true);
+			setTopBarExiting(true);
+		}
+		wasEmptyRef.current = nowEmpty;
+	}, [combatantCount]);
+
+	const empty = combatantCount === 0;
+	const risingClass = rising ? "animate-rise-to-center" : "";
+	const settlingClass = settling ? "animate-settle-to-bottom" : "";
+	const exitingClass = topBarExiting
+		? "absolute inset-x-0 top-0 z-10 px-4 animate-slide-up-out"
+		: "";
+	const topBarClass = settling ? "animate-slide-down-in" : exitingClass;
+	const showTopBar = !empty || topBarExiting;
+
+	return {
+		risingClass,
+		settlingClass,
+		topBarClass,
+		showTopBar,
+		onSettleEnd: () => setSettling(false),
+		onRiseEnd: () => setRising(false),
+		onTopBarExitEnd: () => setTopBarExiting(false),
+	};
+}

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

@@ -0,0 +1,316 @@
+import type { CreatureId, PlayerCharacter } from "@initiative/domain";
+import { useCallback, useDeferredValue, useMemo, 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,
+	} = useEncounterContext();
+	const { search: bestiarySearch, isLoaded: bestiaryLoaded } =
+		useBestiaryContext();
+	const { characters: playerCharacters } = usePlayerCharactersContext();
+	const { showBulkImport, showSourceManager, showCreature, panelView } =
+		useSidePanelContext();
+
+	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) => {
+			const creatureId = addFromBestiary(result);
+			const isDesktop = globalThis.matchMedia("(min-width: 1024px)").matches;
+			if (creatureId && panelView.mode === "closed" && isDesktop) {
+				showCreature(creatureId);
+			}
+		},
+		[addFromBestiary, panelView.mode, showCreature],
+	);
+
+	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 {
+			const creatureId = addMultipleFromBestiary(queued.result, queued.count);
+			const isDesktop = globalThis.matchMedia("(min-width: 1024px)").matches;
+			if (creatureId && panelView.mode === "closed" && isDesktop) {
+				showCreature(creatureId);
+			}
+		}
+		clearInput();
+	}, [
+		queued,
+		handleAddFromBestiary,
+		addMultipleFromBestiary,
+		panelView.mode,
+		showCreature,
+		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

@@ -0,0 +1,27 @@
+import { useEffect, useRef } from "react";
+import { useEncounterContext } from "../contexts/encounter-context.js";
+import { useSidePanelContext } from "../contexts/side-panel-context.js";
+
+export function useAutoStatBlock(): void {
+	const { encounter } = useEncounterContext();
+	const { panelView, updateCreature } = useSidePanelContext();
+
+	const activeCreatureId =
+		encounter.combatants[encounter.activeIndex]?.creatureId;
+	const prevActiveIndexRef = useRef(encounter.activeIndex);
+
+	useEffect(() => {
+		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);
+		}
+	}, [encounter.activeIndex, activeCreatureId, panelView.mode, updateCreature]);
+}

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

@@ -3,7 +3,7 @@ import type {
 	Creature,
 	CreatureId,
 } from "@initiative/domain";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import {
 	normalizeBestiary,
 	setSourceDisplayNames,
@@ -33,8 +33,9 @@ interface BestiaryHook {
 
 export function useBestiary(): BestiaryHook {
 	const [isLoaded, setIsLoaded] = useState(false);
-	const creatureMapRef = useRef<Map<CreatureId, Creature>>(new Map());
-	const [, setTick] = useState(0);
+	const [creatureMap, setCreatureMap] = useState(
+		() => new Map<CreatureId, Creature>(),
+	);
 
 	useEffect(() => {
 		const index = loadBestiaryIndex();
@@ -43,9 +44,8 @@ export function useBestiary(): BestiaryHook {
 			setIsLoaded(true);
 		}
 
-		bestiaryCache.loadAllCachedCreatures().then((map) => {
-			creatureMapRef.current = map;
-			setTick((t) => t + 1);
+		void bestiaryCache.loadAllCachedCreatures().then((map) => {
+			setCreatureMap(map);
 		});
 	}, []);
 
@@ -63,9 +63,12 @@ export function useBestiary(): BestiaryHook {
 			}));
 	}, []);
 
-	const getCreature = useCallback((id: CreatureId): Creature | undefined => {
-		return creatureMapRef.current.get(id);
-	}, []);
+	const getCreature = useCallback(
+		(id: CreatureId): Creature | undefined => {
+			return creatureMap.get(id);
+		},
+		[creatureMap],
+	);
 
 	const isSourceCachedFn = useCallback(
 		(sourceCode: string): Promise<boolean> => {
@@ -86,10 +89,13 @@ export function useBestiary(): BestiaryHook {
 			const creatures = normalizeBestiary(json);
 			const displayName = getSourceDisplayName(sourceCode);
 			await bestiaryCache.cacheSource(sourceCode, displayName, creatures);
-			for (const c of creatures) {
-				creatureMapRef.current.set(c.id, c);
-			}
-			setTick((t) => t + 1);
+			setCreatureMap((prev) => {
+				const next = new Map(prev);
+				for (const c of creatures) {
+					next.set(c.id, c);
+				}
+				return next;
+			});
 		},
 		[],
 	);
@@ -100,18 +106,20 @@ export function useBestiary(): BestiaryHook {
 			const creatures = normalizeBestiary(jsonData as any);
 			const displayName = getSourceDisplayName(sourceCode);
 			await bestiaryCache.cacheSource(sourceCode, displayName, creatures);
-			for (const c of creatures) {
-				creatureMapRef.current.set(c.id, c);
-			}
-			setTick((t) => t + 1);
+			setCreatureMap((prev) => {
+				const next = new Map(prev);
+				for (const c of creatures) {
+					next.set(c.id, c);
+				}
+				return next;
+			});
 		},
 		[],
 	);
 
 	const refreshCache = useCallback(async (): Promise<void> => {
 		const map = await bestiaryCache.loadAllCachedCreatures();
-		creatureMapRef.current = map;
-		setTick((t) => t + 1);
+		setCreatureMap(map);
 	}, []);
 
 	return {

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

@@ -6,7 +6,7 @@ import {
 
 const BATCH_SIZE = 6;
 
-export interface BulkImportState {
+interface BulkImportState {
 	readonly status: "idle" | "loading" | "complete" | "partial-failure";
 	readonly total: number;
 	readonly completed: number;
@@ -48,7 +48,7 @@ export function useBulkImport(): BulkImportHook {
 			countersRef.current = { completed: 0, failed: 0 };
 			setState({ status: "loading", total, completed: 0, failed: 0 });
 
-			(async () => {
+			void (async () => {
 				const cacheChecks = await Promise.all(
 					allCodes.map(async (code) => ({
 						code,
@@ -73,31 +73,39 @@ export function useBulkImport(): BulkImportHook {
 
 				setState((s) => ({ ...s, completed: alreadyCached }));
 
+				const batches: { code: string }[][] = [];
 				for (let i = 0; i < uncached.length; i += BATCH_SIZE) {
-					const batch = uncached.slice(i, i + BATCH_SIZE);
-					await Promise.allSettled(
-						batch.map(async ({ code }) => {
-							const url = getDefaultFetchUrl(code, baseUrl);
-							try {
-								await fetchAndCacheSource(code, url);
-								countersRef.current.completed++;
-							} catch (err) {
-								countersRef.current.failed++;
-								console.warn(
-									`[bulk-import] FAILED ${code} (${url}):`,
-									err instanceof Error ? err.message : err,
-								);
-							}
-							setState({
-								status: "loading",
-								total,
-								completed: countersRef.current.completed,
-								failed: countersRef.current.failed,
-							});
-						}),
-					);
+					batches.push(uncached.slice(i, i + BATCH_SIZE));
 				}
 
+				await batches.reduce(
+					(chain, batch) =>
+						chain.then(() =>
+							Promise.allSettled(
+								batch.map(async ({ code }) => {
+									const url = getDefaultFetchUrl(code, baseUrl);
+									try {
+										await fetchAndCacheSource(code, url);
+										countersRef.current.completed++;
+									} catch (err) {
+										countersRef.current.failed++;
+										console.warn(
+											`[bulk-import] FAILED ${code} (${url}):`,
+											err instanceof Error ? err.message : err,
+										);
+									}
+									setState({
+										status: "loading",
+										total,
+										completed: countersRef.current.completed,
+										failed: countersRef.current.failed,
+									});
+								}),
+							),
+						),
+					Promise.resolve() as Promise<unknown>,
+				);
+
 				await refreshCache();
 
 				const { completed, failed } = countersRef.current;

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

@@ -1,30 +1,38 @@
-import type { EncounterStore } from "@initiative/application";
+import type { EncounterStore, UndoRedoStore } from "@initiative/application";
 import {
 	addCombatantUseCase,
 	adjustHpUseCase,
 	advanceTurnUseCase,
 	clearEncounterUseCase,
 	editCombatantUseCase,
+	redoUseCase,
 	removeCombatantUseCase,
 	retreatTurnUseCase,
 	setAcUseCase,
 	setHpUseCase,
 	setInitiativeUseCase,
+	setTempHpUseCase,
 	toggleConcentrationUseCase,
 	toggleConditionUseCase,
+	undoUseCase,
 } from "@initiative/application";
 import type {
 	BestiaryIndexEntry,
 	CombatantId,
+	CombatantInit,
 	ConditionId,
+	CreatureId,
 	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";
@@ -32,6 +40,12 @@ import {
 	loadEncounter,
 	saveEncounter,
 } from "../persistence/encounter-storage.js";
+import {
+	loadUndoRedoStacks,
+	saveUndoRedoStacks,
+} from "../persistence/undo-redo-storage.js";
+
+const COMBATANT_ID_REGEX = /^c-(\d+)$/;
 
 const EMPTY_ENCOUNTER: Encounter = {
 	combatants: [],
@@ -48,7 +62,7 @@ function initializeEncounter(): Encounter {
 function deriveNextId(encounter: Encounter): number {
 	let max = 0;
 	for (const c of encounter.combatants) {
-		const match = /^c-(\d+)$/.exec(c.id);
+		const match = COMBATANT_ID_REGEX.exec(c.id);
 		if (match) {
 			const n = Number.parseInt(match[1], 10);
 			if (n > max) max = n;
@@ -57,43 +71,24 @@ 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 [undoRedoState, setUndoRedoState] =
+		useState<UndoRedoState>(loadUndoRedoStacks);
 	const encounterRef = useRef(encounter);
 	encounterRef.current = encounter;
+	const undoRedoRef = useRef(undoRedoState);
+	undoRedoRef.current = undoRedoState;
 
 	useEffect(() => {
 		saveEncounter(encounter);
 	}, [encounter]);
 
+	useEffect(() => {
+		saveUndoRedoStacks(undoRedoState);
+	}, [undoRedoState]);
+
 	const makeStore = useCallback((): EncounterStore => {
 		return {
 			get: () => encounterRef.current,
@@ -104,52 +99,68 @@ export function useEncounter() {
 		};
 	}, []);
 
+	const makeUndoRedoStore = useCallback((): UndoRedoStore => {
+		return {
+			get: () => undoRedoRef.current,
+			save: (s) => {
+				undoRedoRef.current = s;
+				setUndoRedoState(s);
+			},
+		};
+	}, []);
+
+	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;
+			setUndoRedoState(newState);
+		}
+		return result;
+	}, []);
+
 	const advanceTurn = useCallback(() => {
-		const result = advanceTurnUseCase(makeStore());
+		const result = withUndo(() => advanceTurnUseCase(makeStore()));
 
 		if (isDomainError(result)) {
 			return;
 		}
 
 		setEvents((prev) => [...prev, ...result]);
-	}, [makeStore]);
+	}, [makeStore, withUndo]);
 
 	const retreatTurn = useCallback(() => {
-		const result = retreatTurnUseCase(makeStore());
+		const result = withUndo(() => retreatTurnUseCase(makeStore()));
 
 		if (isDomainError(result)) {
 			return;
 		}
 
 		setEvents((prev) => [...prev, ...result]);
-	}, [makeStore]);
+	}, [makeStore, withUndo]);
 
 	const nextId = useRef(deriveNextId(encounter));
 
 	const addCombatant = useCallback(
-		(name: string, opts?: CombatantOpts) => {
+		(name: string, init?: CombatantInit) => {
 			const id = combatantId(`c-${++nextId.current}`);
-			const result = addCombatantUseCase(makeStore(), id, name);
+			const result = withUndo(() =>
+				addCombatantUseCase(makeStore(), id, name, init),
+			);
 
 			if (isDomainError(result)) {
 				return;
 			}
 
-			if (opts) {
-				const optEvents = applyCombatantOpts(makeStore, id, opts);
-				if (optEvents.length > 0) {
-					setEvents((prev) => [...prev, ...optEvents]);
-				}
-			}
-
 			setEvents((prev) => [...prev, ...result]);
 		},
-		[makeStore],
+		[makeStore, withUndo],
 	);
 
 	const removeCombatant = useCallback(
 		(id: CombatantId) => {
-			const result = removeCombatantUseCase(makeStore(), id);
+			const result = withUndo(() => removeCombatantUseCase(makeStore(), id));
 
 			if (isDomainError(result)) {
 				return;
@@ -157,12 +168,14 @@ export function useEncounter() {
 
 			setEvents((prev) => [...prev, ...result]);
 		},
-		[makeStore],
+		[makeStore, withUndo],
 	);
 
 	const editCombatant = useCallback(
 		(id: CombatantId, newName: string) => {
-			const result = editCombatantUseCase(makeStore(), id, newName);
+			const result = withUndo(() =>
+				editCombatantUseCase(makeStore(), id, newName),
+			);
 
 			if (isDomainError(result)) {
 				return;
@@ -170,12 +183,14 @@ export function useEncounter() {
 
 			setEvents((prev) => [...prev, ...result]);
 		},
-		[makeStore],
+		[makeStore, withUndo],
 	);
 
 	const setInitiative = useCallback(
 		(id: CombatantId, value: number | undefined) => {
-			const result = setInitiativeUseCase(makeStore(), id, value);
+			const result = withUndo(() =>
+				setInitiativeUseCase(makeStore(), id, value),
+			);
 
 			if (isDomainError(result)) {
 				return;
@@ -183,12 +198,12 @@ export function useEncounter() {
 
 			setEvents((prev) => [...prev, ...result]);
 		},
-		[makeStore],
+		[makeStore, withUndo],
 	);
 
 	const setHp = useCallback(
 		(id: CombatantId, maxHp: number | undefined) => {
-			const result = setHpUseCase(makeStore(), id, maxHp);
+			const result = withUndo(() => setHpUseCase(makeStore(), id, maxHp));
 
 			if (isDomainError(result)) {
 				return;
@@ -196,12 +211,12 @@ export function useEncounter() {
 
 			setEvents((prev) => [...prev, ...result]);
 		},
-		[makeStore],
+		[makeStore, withUndo],
 	);
 
 	const adjustHp = useCallback(
 		(id: CombatantId, delta: number) => {
-			const result = adjustHpUseCase(makeStore(), id, delta);
+			const result = withUndo(() => adjustHpUseCase(makeStore(), id, delta));
 
 			if (isDomainError(result)) {
 				return;
@@ -209,12 +224,25 @@ export function useEncounter() {
 
 			setEvents((prev) => [...prev, ...result]);
 		},
-		[makeStore],
+		[makeStore, withUndo],
+	);
+
+	const setTempHp = useCallback(
+		(id: CombatantId, tempHp: number | undefined) => {
+			const result = withUndo(() => setTempHpUseCase(makeStore(), id, tempHp));
+
+			if (isDomainError(result)) {
+				return;
+			}
+
+			setEvents((prev) => [...prev, ...result]);
+		},
+		[makeStore, withUndo],
 	);
 
 	const setAc = useCallback(
 		(id: CombatantId, value: number | undefined) => {
-			const result = setAcUseCase(makeStore(), id, value);
+			const result = withUndo(() => setAcUseCase(makeStore(), id, value));
 
 			if (isDomainError(result)) {
 				return;
@@ -222,12 +250,14 @@ export function useEncounter() {
 
 			setEvents((prev) => [...prev, ...result]);
 		},
-		[makeStore],
+		[makeStore, withUndo],
 	);
 
 	const toggleCondition = useCallback(
 		(id: CombatantId, conditionId: ConditionId) => {
-			const result = toggleConditionUseCase(makeStore(), id, conditionId);
+			const result = withUndo(() =>
+				toggleConditionUseCase(makeStore(), id, conditionId),
+			);
 
 			if (isDomainError(result)) {
 				return;
@@ -235,12 +265,14 @@ export function useEncounter() {
 
 			setEvents((prev) => [...prev, ...result]);
 		},
-		[makeStore],
+		[makeStore, withUndo],
 	);
 
 	const toggleConcentration = useCallback(
 		(id: CombatantId) => {
-			const result = toggleConcentrationUseCase(makeStore(), id);
+			const result = withUndo(() =>
+				toggleConcentrationUseCase(makeStore(), id),
+			);
 
 			if (isDomainError(result)) {
 				return;
@@ -248,7 +280,7 @@ export function useEncounter() {
 
 			setEvents((prev) => [...prev, ...result]);
 		},
-		[makeStore],
+		[makeStore, withUndo],
 	);
 
 	const clearEncounter = useCallback(() => {
@@ -258,12 +290,18 @@ export function useEncounter() {
 			return;
 		}
 
+		const cleared = clearHistory();
+		undoRedoRef.current = cleared;
+		setUndoRedoState(cleared);
+
 		nextId.current = 0;
 		setEvents((prev) => [...prev, ...result]);
 	}, [makeStore]);
 
-	const addFromBestiary = useCallback(
-		(entry: BestiaryIndexEntry) => {
+	const addOneFromBestiary = useCallback(
+		(
+			entry: BestiaryIndexEntry,
+		): { cId: CreatureId; events: DomainEvent[] } | null => {
 			const store = makeStore();
 			const existingNames = store.get().combatants.map((c) => c.name);
 			const { newName, renames } = resolveCreatureName(
@@ -271,7 +309,6 @@ export function useEncounter() {
 				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) {
@@ -279,48 +316,75 @@ export function useEncounter() {
 				}
 			}
 
-			// Add combatant with resolved name
-			const id = combatantId(`c-${++nextId.current}`);
-			const addResult = addCombatantUseCase(makeStore(), id, newName);
-			if (isDomainError(addResult)) return;
-
-			// Set HP
-			const hpResult = setHpUseCase(makeStore(), id, entry.hp);
-			if (!isDomainError(hpResult)) {
-				setEvents((prev) => [...prev, ...hpResult]);
-			}
-
-			// Set AC
-			if (entry.ac > 0) {
-				const acResult = setAcUseCase(makeStore(), id, entry.ac);
-				if (!isDomainError(acResult)) {
-					setEvents((prev) => [...prev, ...acResult]);
-				}
-			}
-
-			// Derive creatureId from source + name
 			const slug = entry.name
 				.toLowerCase()
-				.replace(/[^a-z0-9]+/g, "-")
-				.replace(/(^-|-$)/g, "");
+				.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.current}`);
+			const result = addCombatantUseCase(makeStore(), id, newName, {
+				maxHp: entry.hp,
+				ac: entry.ac > 0 ? entry.ac : undefined,
+				creatureId: cId,
 			});
 
-			setEvents((prev) => [...prev, ...addResult]);
+			if (isDomainError(result)) return null;
+
+			return { cId, events: result };
 		},
-		[makeStore, editCombatant],
+		[makeStore],
+	);
+
+	const addFromBestiary = useCallback(
+		(entry: BestiaryIndexEntry): CreatureId | null => {
+			const snapshot = encounterRef.current;
+			const added = addOneFromBestiary(entry);
+
+			if (!added) {
+				makeStore().save(snapshot);
+				return null;
+			}
+
+			const newState = pushUndo(undoRedoRef.current, snapshot);
+			undoRedoRef.current = newState;
+			setUndoRedoState(newState);
+
+			setEvents((prev) => [...prev, ...added.events]);
+			return added.cId;
+		},
+		[makeStore, addOneFromBestiary],
+	);
+
+	const addMultipleFromBestiary = useCallback(
+		(entry: BestiaryIndexEntry, count: number): CreatureId | null => {
+			const snapshot = encounterRef.current;
+			const allEvents: DomainEvent[] = [];
+			let lastCId: CreatureId | null = null;
+
+			for (let i = 0; i < count; i++) {
+				const added = addOneFromBestiary(entry);
+				if (!added) {
+					makeStore().save(snapshot);
+					return null;
+				}
+				allEvents.push(...added.events);
+				lastCId = added.cId;
+			}
+
+			const newState = pushUndo(undoRedoRef.current, snapshot);
+			undoRedoRef.current = newState;
+			setUndoRedoState(newState);
+
+			setEvents((prev) => [...prev, ...allEvents]);
+			return lastCId;
+		},
+		[makeStore, addOneFromBestiary],
 	);
 
 	const addFromPlayerCharacter = useCallback(
 		(pc: PlayerCharacter) => {
+			const snapshot = encounterRef.current;
 			const store = makeStore();
 			const existingNames = store.get().combatants.map((c) => c.name);
 			const { newName, renames } = resolveCreatureName(pc.name, existingNames);
@@ -333,47 +397,61 @@ export function useEncounter() {
 			}
 
 			const id = combatantId(`c-${++nextId.current}`);
-			const addResult = addCombatantUseCase(makeStore(), id, newName);
-			if (isDomainError(addResult)) return;
-
-			// Set HP
-			const hpResult = setHpUseCase(makeStore(), id, pc.maxHp);
-			if (!isDomainError(hpResult)) {
-				setEvents((prev) => [...prev, ...hpResult]);
-			}
-
-			// Set AC
-			if (pc.ac > 0) {
-				const acResult = setAcUseCase(makeStore(), id, pc.ac);
-				if (!isDomainError(acResult)) {
-					setEvents((prev) => [...prev, ...acResult]);
-				}
-			}
-
-			// Set color, icon, and playerCharacterId on the combatant
-			const currentEncounter = store.get();
-			store.save({
-				...currentEncounter,
-				combatants: currentEncounter.combatants.map((c) =>
-					c.id === id
-						? {
-								...c,
-								color: pc.color,
-								icon: pc.icon,
-								playerCharacterId: pc.id,
-							}
-						: c,
-				),
+			const result = addCombatantUseCase(makeStore(), id, newName, {
+				maxHp: pc.maxHp,
+				ac: pc.ac > 0 ? pc.ac : undefined,
+				color: pc.color,
+				icon: pc.icon,
+				playerCharacterId: pc.id,
 			});
 
-			setEvents((prev) => [...prev, ...addResult]);
+			if (isDomainError(result)) {
+				store.save(snapshot);
+				return;
+			}
+
+			const newState = pushUndo(undoRedoRef.current, snapshot);
+			undoRedoRef.current = newState;
+			setUndoRedoState(newState);
+
+			setEvents((prev) => [...prev, ...result]);
 		},
-		[makeStore, editCombatant],
+		[makeStore],
+	);
+
+	const undoAction = useCallback(() => {
+		undoUseCase(makeStore(), makeUndoRedoStore());
+	}, [makeStore, makeUndoRedoStore]);
+
+	const redoAction = useCallback(() => {
+		redoUseCase(makeStore(), makeUndoRedoStore());
+	}, [makeStore, makeUndoRedoStore]);
+
+	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,
+	);
+	const canRollAllInitiative = encounter.combatants.some(
+		(c) => c.creatureId != null && c.initiative == null,
 	);
 
 	return {
 		encounter,
+		undoRedoState,
 		events,
+		isEmpty,
+		hasTempHp,
+		hasCreatureCombatants,
+		canRollAllInitiative,
+		canUndo,
+		canRedo,
 		advanceTurn,
 		retreatTurn,
 		addCombatant,
@@ -383,11 +461,18 @@ export function useEncounter() {
 		setInitiative,
 		setHp,
 		adjustHp,
+		setTempHp,
 		setAc,
 		toggleCondition,
 		toggleConcentration,
 		addFromBestiary,
+		addMultipleFromBestiary,
 		addFromPlayerCharacter,
+		undo: undoAction,
+		redo: redoAction,
+		setEncounter,
+		setUndoRedoState,
 		makeStore,
+		withUndo,
 	} as const;
 }

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

@@ -0,0 +1,68 @@
+import {
+	rollAllInitiativeUseCase,
+	rollInitiativeUseCase,
+} from "@initiative/application";
+import {
+	type CombatantId,
+	isDomainError,
+	type RollMode,
+} from "@initiative/domain";
+import { useCallback, useState } from "react";
+import { useBestiaryContext } from "../contexts/bestiary-context.js";
+import { useEncounterContext } from "../contexts/encounter-context.js";
+import { useSidePanelContext } from "../contexts/side-panel-context.js";
+
+function rollDice(): number {
+	return Math.floor(Math.random() * 20) + 1;
+}
+
+export function useInitiativeRolls() {
+	const { encounter, makeStore, withUndo } = useEncounterContext();
+	const { getCreature } = useBestiaryContext();
+	const { showCreature } = useSidePanelContext();
+
+	const [rollSkippedCount, setRollSkippedCount] = useState(0);
+	const [rollSingleSkipped, setRollSingleSkipped] = useState(false);
+
+	const handleRollInitiative = useCallback(
+		(id: CombatantId, mode: RollMode = "normal") => {
+			const diceRolls: [number, ...number[]] =
+				mode === "normal" ? [rollDice()] : [rollDice(), rollDice()];
+			const result = withUndo(() =>
+				rollInitiativeUseCase(makeStore(), id, diceRolls, getCreature, mode),
+			);
+			if (isDomainError(result)) {
+				setRollSingleSkipped(true);
+				const combatant = encounter.combatants.find((c) => c.id === id);
+				if (combatant?.creatureId) {
+					showCreature(combatant.creatureId);
+				}
+			}
+		},
+		[makeStore, getCreature, withUndo, encounter.combatants, showCreature],
+	);
+
+	const handleRollAllInitiative = useCallback(
+		(mode: RollMode = "normal") => {
+			const result = withUndo(() =>
+				rollAllInitiativeUseCase(makeStore(), rollDice, getCreature, mode),
+			);
+			if (!isDomainError(result) && result.skippedNoSource > 0) {
+				setRollSkippedCount(result.skippedNoSource);
+			}
+		},
+		[makeStore, getCreature, withUndo],
+	);
+
+	return {
+		rollSkippedCount,
+		rollSingleSkipped,
+		dismissRollSkipped: useCallback(() => setRollSkippedCount(0), []),
+		dismissRollSingleSkipped: useCallback(
+			() => setRollSingleSkipped(false),
+			[],
+		),
+		handleRollInitiative,
+		handleRollAllInitiative,
+	} as const;
+}

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

@@ -0,0 +1,32 @@
+import { useCallback, useRef } from "react";
+
+const LONG_PRESS_MS = 500;
+
+export function useLongPress(onLongPress: (e: React.TouchEvent) => void) {
+	const timerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+	const firedRef = useRef(false);
+
+	const onTouchStart = useCallback(
+		(e: React.TouchEvent) => {
+			firedRef.current = false;
+			timerRef.current = setTimeout(() => {
+				firedRef.current = true;
+				onLongPress(e);
+			}, LONG_PRESS_MS);
+		},
+		[onLongPress],
+	);
+
+	const onTouchEnd = useCallback((e: React.TouchEvent) => {
+		clearTimeout(timerRef.current);
+		if (firedRef.current) {
+			e.preventDefault();
+		}
+	}, []);
+
+	const onTouchMove = useCallback(() => {
+		clearTimeout(timerRef.current);
+	}, []);
+
+	return { onTouchStart, onTouchEnd, onTouchMove };
+}

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

@@ -26,8 +26,8 @@ interface EditFields {
 	readonly name?: string;
 	readonly ac?: number;
 	readonly maxHp?: number;
-	readonly color?: string;
-	readonly icon?: string;
+	readonly color?: string | null;
+	readonly icon?: string | null;
 }
 
 export function usePlayerCharacters() {
@@ -51,7 +51,13 @@ export function usePlayerCharacters() {
 	}, []);
 
 	const createCharacter = useCallback(
-		(name: string, ac: number, maxHp: number, color: string, icon: string) => {
+		(
+			name: string,
+			ac: number,
+			maxHp: number,
+			color: string | undefined,
+			icon: string | undefined,
+		) => {
 			const id = generatePcId();
 			const result = createPlayerCharacterUseCase(
 				makeStore(),
@@ -97,6 +103,7 @@ export function usePlayerCharacters() {
 		createCharacter,
 		editCharacter,
 		deleteCharacter,
+		replacePlayerCharacters: setCharacters,
 		makeStore,
 	} as const;
 }

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

@@ -0,0 +1,52 @@
+import type { RulesEdition } from "@initiative/domain";
+import { useCallback, useSyncExternalStore } from "react";
+
+const STORAGE_KEY = "initiative:rules-edition";
+
+const listeners = new Set<() => void>();
+let currentEdition: RulesEdition = loadEdition();
+
+function loadEdition(): RulesEdition {
+	try {
+		const raw = localStorage.getItem(STORAGE_KEY);
+		if (raw === "5e" || raw === "5.5e") return raw;
+	} catch {
+		// storage unavailable
+	}
+	return "5.5e";
+}
+
+function saveEdition(edition: RulesEdition): void {
+	try {
+		localStorage.setItem(STORAGE_KEY, edition);
+	} catch {
+		// quota exceeded or storage unavailable
+	}
+}
+
+function notifyAll(): void {
+	for (const listener of listeners) {
+		listener();
+	}
+}
+
+function subscribe(callback: () => void): () => void {
+	listeners.add(callback);
+	return () => listeners.delete(callback);
+}
+
+function getSnapshot(): RulesEdition {
+	return currentEdition;
+}
+
+export function useRulesEdition() {
+	const edition = useSyncExternalStore(subscribe, getSnapshot);
+
+	const setEdition = useCallback((next: RulesEdition) => {
+		currentEdition = next;
+		saveEdition(next);
+		notifyAll();
+	}, []);
+
+	return { edition, setEdition } as const;
+}

apps/web/src/hooks/use-side-panel-state.ts

@@ -0,0 +1,107 @@
+import type { CreatureId } from "@initiative/domain";
+import { useCallback, useEffect, useState } from "react";
+
+type PanelView =
+	| { mode: "closed" }
+	| { mode: "creature"; creatureId: CreatureId }
+	| { mode: "bulk-import" }
+	| { mode: "source-manager" };
+
+interface SidePanelState {
+	panelView: PanelView;
+	selectedCreatureId: CreatureId | null;
+	bulkImportMode: boolean;
+	sourceManagerMode: boolean;
+	isRightPanelCollapsed: boolean;
+	pinnedCreatureId: CreatureId | null;
+	isWideDesktop: boolean;
+}
+
+interface SidePanelActions {
+	showCreature: (creatureId: CreatureId) => void;
+	updateCreature: (creatureId: CreatureId) => void;
+	showBulkImport: () => void;
+	showSourceManager: () => void;
+	dismissPanel: () => void;
+	toggleCollapse: () => void;
+	togglePin: () => void;
+	unpin: () => void;
+}
+
+export function useSidePanelState(): SidePanelState & SidePanelActions {
+	const [panelView, setPanelView] = useState<PanelView>({ mode: "closed" });
+	const [isRightPanelCollapsed, setIsRightPanelCollapsed] = useState(false);
+	const [pinnedCreatureId, setPinnedCreatureId] = useState<CreatureId | null>(
+		null,
+	);
+	const [isWideDesktop, setIsWideDesktop] = useState(
+		() => globalThis.matchMedia("(min-width: 1280px)").matches,
+	);
+
+	useEffect(() => {
+		const mq = globalThis.matchMedia("(min-width: 1280px)");
+		const handler = (e: MediaQueryListEvent) => setIsWideDesktop(e.matches);
+		mq.addEventListener("change", handler);
+		return () => mq.removeEventListener("change", handler);
+	}, []);
+
+	const selectedCreatureId =
+		panelView.mode === "creature" ? panelView.creatureId : null;
+
+	const showCreature = useCallback((creatureId: CreatureId) => {
+		setPanelView({ mode: "creature", creatureId });
+		setIsRightPanelCollapsed(false);
+	}, []);
+
+	const updateCreature = useCallback((creatureId: CreatureId) => {
+		setPanelView({ mode: "creature", creatureId });
+	}, []);
+
+	const showBulkImport = useCallback(() => {
+		setPanelView({ mode: "bulk-import" });
+		setIsRightPanelCollapsed(false);
+	}, []);
+
+	const showSourceManager = useCallback(() => {
+		setPanelView({ mode: "source-manager" });
+		setIsRightPanelCollapsed(false);
+	}, []);
+
+	const dismissPanel = useCallback(() => {
+		setPanelView({ mode: "closed" });
+	}, []);
+
+	const toggleCollapse = useCallback(() => {
+		setIsRightPanelCollapsed((f) => !f);
+	}, []);
+
+	const togglePin = useCallback(() => {
+		if (selectedCreatureId) {
+			setPinnedCreatureId((prev) =>
+				prev === selectedCreatureId ? null : selectedCreatureId,
+			);
+		}
+	}, [selectedCreatureId]);
+
+	const unpin = useCallback(() => {
+		setPinnedCreatureId(null);
+	}, []);
+
+	return {
+		panelView,
+		selectedCreatureId,
+		bulkImportMode: panelView.mode === "bulk-import",
+		sourceManagerMode: panelView.mode === "source-manager",
+		isRightPanelCollapsed,
+		pinnedCreatureId,
+		isWideDesktop,
+		showCreature,
+		updateCreature,
+		showBulkImport,
+		showSourceManager,
+		dismissPanel,
+		toggleCollapse,
+		togglePin,
+		unpin,
+	};
+}

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

@@ -0,0 +1,93 @@
+import { useCallback, useEffect, useSyncExternalStore } from "react";
+
+type ThemePreference = "system" | "light" | "dark";
+type ResolvedTheme = "light" | "dark";
+
+const STORAGE_KEY = "initiative:theme";
+
+const listeners = new Set<() => void>();
+let currentPreference: ThemePreference = loadPreference();
+
+function loadPreference(): ThemePreference {
+	try {
+		const raw = localStorage.getItem(STORAGE_KEY);
+		if (raw === "light" || raw === "dark" || raw === "system") return raw;
+	} catch {
+		// storage unavailable
+	}
+	return "system";
+}
+
+function savePreference(pref: ThemePreference): void {
+	try {
+		localStorage.setItem(STORAGE_KEY, pref);
+	} catch {
+		// quota exceeded or storage unavailable
+	}
+}
+
+function getSystemTheme(): ResolvedTheme {
+	if (typeof globalThis.matchMedia !== "function") return "dark";
+	return globalThis.matchMedia("(prefers-color-scheme: light)").matches
+		? "light"
+		: "dark";
+}
+
+function resolve(pref: ThemePreference): ResolvedTheme {
+	return pref === "system" ? getSystemTheme() : pref;
+}
+
+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 {
+	for (const listener of listeners) {
+		listener();
+	}
+}
+
+// Apply on load
+applyTheme(resolve(currentPreference));
+
+// Listen for OS preference changes
+if (typeof globalThis.matchMedia === "function") {
+	globalThis
+		.matchMedia("(prefers-color-scheme: light)")
+		.addEventListener("change", () => {
+			if (currentPreference === "system") {
+				applyTheme(resolve("system"));
+				notifyAll();
+			}
+		});
+}
+
+function subscribe(callback: () => void): () => void {
+	listeners.add(callback);
+	return () => listeners.delete(callback);
+}
+
+function getSnapshot(): ThemePreference {
+	return currentPreference;
+}
+
+export function useTheme() {
+	const preference = useSyncExternalStore(subscribe, getSnapshot);
+	const resolved = resolve(preference);
+
+	useEffect(() => {
+		applyTheme(resolved);
+	}, [resolved]);
+
+	const setPreference = useCallback((pref: ThemePreference) => {
+		currentPreference = pref;
+		savePreference(pref);
+		applyTheme(resolve(pref));
+		notifyAll();
+	}, []);
+
+	return { preference, resolved, setPreference } as const;
+}

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/index.css

@@ -1,14 +1,14 @@
 @import "tailwindcss";
 
 @theme {
-	--color-background: #0f172a;
+	--color-background: #0e1a2e;
 	--color-foreground: #e2e8f0;
-	--color-muted: #64748b;
+	--color-muted: #7a8ba4;
 	--color-muted-foreground: #94a3b8;
-	--color-card: #1e293b;
+	--color-card: #1a2e4a;
 	--color-card-foreground: #e2e8f0;
-	--color-border: #334155;
-	--color-input: #334155;
+	--color-border: #2a5088;
+	--color-input: #2a5088;
 	--color-primary: #3b82f6;
 	--color-primary-foreground: #ffffff;
 	--color-accent: #3b82f6;
@@ -16,15 +16,50 @@
 	--color-hover-neutral: var(--color-primary);
 	--color-hover-action: var(--color-primary);
 	--color-hover-destructive: var(--color-destructive);
-	--color-hover-neutral-bg: var(--color-card);
+	--color-hover-neutral-bg: oklch(0.623 0.214 259 / 0.15);
 	--color-hover-action-bg: var(--color-muted);
 	--color-hover-destructive-bg: transparent;
+	--color-stat-heading: #fbbf24;
+	--color-stat-divider-from: oklch(0.5 0.1 65 / 0.6);
+	--color-stat-divider-via: oklch(0.5 0.1 65 / 0.4);
+	--color-hp-damage-hover-bg: oklch(0.25 0.05 25);
+	--color-hp-heal-hover-bg: oklch(0.25 0.05 155);
+	--color-active-row-bg: oklch(0.623 0.214 259 / 0.1);
+	--color-active-row-border: oklch(0.623 0.214 259 / 0.4);
 	--radius-sm: 0.25rem;
-	--radius-md: 0.375rem;
-	--radius-lg: 0.5rem;
+	--radius-md: 0.5rem;
+	--radius-lg: 0.75rem;
 	--font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
 }
 
+[data-theme="light"] {
+	--color-background: #eeecea;
+	--color-foreground: #374151;
+	--color-muted: #e0ddd9;
+	--color-muted-foreground: #6b7280;
+	--color-card: #f7f6f4;
+	--color-card-foreground: #374151;
+	--color-border: #ddd9d5;
+	--color-input: #cdc8c3;
+	--color-primary: #2563eb;
+	--color-primary-foreground: #ffffff;
+	--color-accent: #2563eb;
+	--color-destructive: #dc2626;
+	--color-hover-neutral: var(--color-primary);
+	--color-hover-action: var(--color-primary);
+	--color-hover-destructive: var(--color-destructive);
+	--color-hover-neutral-bg: oklch(0.623 0.214 259 / 0.08);
+	--color-hover-action-bg: var(--color-muted);
+	--color-hover-destructive-bg: transparent;
+	--color-stat-heading: #92400e;
+	--color-stat-divider-from: oklch(0.55 0.1 65 / 0.5);
+	--color-stat-divider-via: oklch(0.55 0.1 65 / 0.25);
+	--color-hp-damage-hover-bg: #fef2f2;
+	--color-hp-heal-hover-bg: #ecfdf5;
+	--color-active-row-bg: oklch(0.623 0.214 259 / 0.08);
+	--color-active-row-border: oklch(0.623 0.214 259 / 0.25);
+}
+
 @keyframes concentration-shake {
 	0% {
 		translate: 0;
@@ -80,20 +115,73 @@
 	}
 }
 
-@keyframes breathe {
-	0%,
-	100% {
-		opacity: 0.4;
-		scale: 0.9;
+@keyframes settle-to-bottom {
+	from {
+		transform: translateY(-40vh);
+		opacity: 0;
 	}
-	50% {
+	40% {
+		opacity: 1;
+	}
+	to {
+		transform: translateY(0);
 		opacity: 1;
-		scale: 1.1;
 	}
 }
 
-@utility animate-breathe {
-	animation: breathe 3s ease-in-out infinite;
+@utility animate-settle-to-bottom {
+	animation: settle-to-bottom 700ms cubic-bezier(0.22, 1, 0.36, 1) backwards;
+}
+
+@keyframes rise-to-center {
+	from {
+		transform: translateY(40vh);
+		opacity: 0;
+	}
+	40% {
+		opacity: 1;
+	}
+	to {
+		transform: translateY(0);
+		opacity: 1;
+	}
+}
+
+@utility animate-rise-to-center {
+	animation: rise-to-center 700ms cubic-bezier(0.22, 1, 0.36, 1) backwards;
+}
+
+@keyframes slide-down-in {
+	from {
+		transform: translateY(-100%);
+		opacity: 0;
+	}
+	to {
+		transform: translateY(0);
+		opacity: 1;
+	}
+}
+
+@utility animate-slide-down-in {
+	animation: slide-down-in 700ms cubic-bezier(0.22, 1, 0.36, 1) backwards;
+}
+
+@keyframes slide-up-out {
+	from {
+		transform: translateY(0);
+		opacity: 1;
+	}
+	60% {
+		opacity: 0;
+	}
+	to {
+		transform: translateY(-100%);
+		opacity: 0;
+	}
+}
+
+@utility animate-slide-up-out {
+	animation: slide-up-out 700ms cubic-bezier(0.22, 1, 0.36, 1) forwards;
 }
 
 @custom-variant pointer-coarse (@media (pointer: coarse));
@@ -116,6 +204,38 @@
 		concentration-glow 1200ms ease-out;
 }
 
+@utility card-glow {
+	background-image: radial-gradient(
+		ellipse at 50% 50%,
+		oklch(0.35 0.05 250 / 0.5) 0%,
+		transparent 70%
+	);
+	box-shadow:
+		0 0 15px -2px oklch(0.623 0.214 259 / 0.2),
+		inset 0 1px 0 0 oklch(0.7 0.15 259 / 0.1);
+
+	[data-theme="light"] & {
+		background-image: none;
+		box-shadow: 0 1px 3px 0 oklch(0 0 0 / 0.08);
+	}
+}
+
+@utility panel-glow {
+	background-image: linear-gradient(
+		to bottom,
+		oklch(0.35 0.05 250 / 0.4) 0%,
+		transparent 40%
+	);
+	box-shadow:
+		0 0 20px -2px oklch(0.623 0.214 259 / 0.15),
+		inset 0 1px 0 0 oklch(0.7 0.15 259 / 0.1);
+
+	[data-theme="light"] & {
+		background-image: none;
+		box-shadow: -1px 0 6px 0 oklch(0 0 0 / 0.1);
+	}
+}
+
 * {
 	scrollbar-color: var(--color-border) transparent;
 	scrollbar-width: thin;
@@ -123,6 +243,16 @@
 
 body {
 	background-color: var(--color-background);
+	background-image: radial-gradient(
+		ellipse at 50% 40%,
+		oklch(0.26 0.055 250) 0%,
+		var(--color-background) 70%
+	);
+	background-attachment: fixed;
 	color: var(--color-foreground);
 	font-family: var(--font-sans);
 }
+
+[data-theme="light"] body {
+	background-image: none;
+}

apps/web/src/main.tsx

@@ -1,13 +1,39 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
-import { App } from "./App";
+import { App } from "./App.js";
+import {
+	BestiaryProvider,
+	BulkImportProvider,
+	EncounterProvider,
+	InitiativeRollsProvider,
+	PlayerCharactersProvider,
+	RulesEditionProvider,
+	SidePanelProvider,
+	ThemeProvider,
+} from "./contexts/index.js";
 import "./index.css";
 
 const root = document.getElementById("root");
 if (root) {
 	createRoot(root).render(
 		<StrictMode>
-			<App />
+			<ThemeProvider>
+				<RulesEditionProvider>
+					<EncounterProvider>
+						<BestiaryProvider>
+							<PlayerCharactersProvider>
+								<BulkImportProvider>
+									<SidePanelProvider>
+										<InitiativeRollsProvider>
+											<App />
+										</InitiativeRollsProvider>
+									</SidePanelProvider>
+								</BulkImportProvider>
+							</PlayerCharactersProvider>
+						</BestiaryProvider>
+					</EncounterProvider>
+				</RulesEditionProvider>
+			</ThemeProvider>
 		</StrictMode>,
 	);
 }

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

@@ -108,45 +108,44 @@ function isValidCombatantEntry(c: unknown): boolean {
 	return typeof entry.id === "string" && typeof entry.name === "string";
 }
 
+export function rehydrateEncounter(parsed: unknown): Encounter | null {
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+		return null;
+
+	const obj = parsed as Record<string, unknown>;
+
+	if (!Array.isArray(obj.combatants)) return null;
+	if (typeof obj.activeIndex !== "number") return null;
+	if (typeof obj.roundNumber !== "number") return null;
+
+	const combatants = obj.combatants as unknown[];
+
+	// Handle empty encounter (cleared state) directly — createEncounter rejects empty arrays
+	if (combatants.length === 0) {
+		return {
+			combatants: [],
+			activeIndex: 0,
+			roundNumber: 1,
+		};
+	}
+
+	if (!combatants.every(isValidCombatantEntry)) return null;
+
+	const rehydrated = combatants.map(rehydrateCombatant);
+
+	const result = createEncounter(rehydrated, obj.activeIndex, obj.roundNumber);
+	if (isDomainError(result)) return null;
+
+	return result;
+}
+
 export function loadEncounter(): Encounter | null {
 	try {
 		const raw = localStorage.getItem(STORAGE_KEY);
 		if (raw === null) return null;
 
 		const parsed: unknown = JSON.parse(raw);
-
-		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
-			return null;
-
-		const obj = parsed as Record<string, unknown>;
-
-		if (!Array.isArray(obj.combatants)) return null;
-		if (typeof obj.activeIndex !== "number") return null;
-		if (typeof obj.roundNumber !== "number") return null;
-
-		const combatants = obj.combatants as unknown[];
-
-		// Handle empty encounter (cleared state) directly — createEncounter rejects empty arrays
-		if (combatants.length === 0) {
-			return {
-				combatants: [],
-				activeIndex: 0,
-				roundNumber: 1,
-			};
-		}
-
-		if (!combatants.every(isValidCombatantEntry)) return null;
-
-		const rehydrated = combatants.map(rehydrateCombatant);
-
-		const result = createEncounter(
-			rehydrated,
-			obj.activeIndex,
-			obj.roundNumber,
-		);
-		if (isDomainError(result)) return null;
-
-		return result;
+		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 { rehydrateEncounter } from "./encounter-storage.js";
+import { rehydrateCharacter } from "./player-character-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 = rehydrateCharacter(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

@@ -15,7 +15,14 @@ export function savePlayerCharacters(characters: PlayerCharacter[]): void {
 	}
 }
 
-function rehydrateCharacter(raw: unknown): PlayerCharacter | null {
+function isValidOptionalMember(
+	value: unknown,
+	valid: ReadonlySet<string>,
+): boolean {
+	return value === undefined || (typeof value === "string" && valid.has(value));
+}
+
+export function rehydrateCharacter(raw: unknown): PlayerCharacter | null {
 	if (typeof raw !== "object" || raw === null || Array.isArray(raw))
 		return null;
 	const entry = raw as Record<string, unknown>;
@@ -35,10 +42,8 @@ function rehydrateCharacter(raw: unknown): PlayerCharacter | null {
 		entry.maxHp < 1
 	)
 		return null;
-	if (typeof entry.color !== "string" || !VALID_PLAYER_COLORS.has(entry.color))
-		return null;
-	if (typeof entry.icon !== "string" || !VALID_PLAYER_ICONS.has(entry.icon))
-		return null;
+	if (!isValidOptionalMember(entry.color, VALID_PLAYER_COLORS)) return null;
+	if (!isValidOptionalMember(entry.icon, VALID_PLAYER_ICONS)) return null;
 
 	return {
 		id: playerCharacterId(entry.id),

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

@@ -1,14 +1,16 @@
 {
-	"$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
+	"$schema": "https://biomejs.dev/schemas/2.4.8/schema.json",
 	"files": {
 		"includes": [
 			"**",
-			"!**/dist/**",
-			"!.claude/**",
-			"!.specify/**",
-			"!specs/**",
-			"!coverage/**",
-			"!.pnpm-store/**"
+			"!**/dist",
+			"!.claude",
+			"!.specify",
+			"!specs",
+			"!coverage",
+			"!.pnpm-store",
+			"!.rodney",
+			"!.agent-tests"
 		]
 	},
 	"assist": {
@@ -21,6 +23,12 @@
 			}
 		}
 	},
+	"css": {
+		"parser": {
+			"cssModules": false,
+			"tailwindDirectives": true
+		}
+	},
 	"formatter": {
 		"enabled": true,
 		"indentStyle": "tab",
@@ -30,13 +38,93 @@
 		"enabled": true,
 		"rules": {
 			"recommended": true,
+			"a11y": {
+				"noNoninteractiveElementInteractions": "error"
+			},
 			"complexity": {
 				"noExcessiveCognitiveComplexity": {
 					"level": "error",
 					"options": {
 						"maxAllowedComplexity": 15
 					}
-				}
+				},
+				"noUselessStringConcat": "error"
+			},
+			"correctness": {
+				"noNestedComponentDefinitions": "error",
+				"noReactPropAssignments": "error"
+			},
+			"nursery": {
+				"noConditionalExpect": "error",
+				"noDuplicatedSpreadProps": "error",
+				"noFloatingPromises": "error",
+				"noLeakedRender": "error",
+				"noMisusedPromises": "error",
+				"noNestedPromises": "error",
+				"noReturnAssign": "error",
+				"noScriptUrl": "error",
+				"noShadow": "error",
+				"noUnnecessaryConditions": "error",
+				"noUselessReturn": "error",
+				"useArraySome": "error",
+				"useArraySortCompare": "error",
+				"useAwaitThenable": "error",
+				"useErrorCause": "error",
+				"useExhaustiveSwitchCases": "error",
+				"useFind": "error",
+				"useGlobalThis": "error",
+				"useNullishCoalescing": "error",
+				"useRegexpExec": "error",
+				"useSortedClasses": "error",
+				"useSpread": "error"
+			},
+			"performance": {
+				"noAwaitInLoops": "error",
+				"useTopLevelRegex": "error"
+			},
+			"style": {
+				"noCommonJs": "error",
+				"noDoneCallback": "error",
+				"noExportedImports": "error",
+				"noInferrableTypes": "error",
+				"noNamespace": "error",
+				"noNegationElse": "error",
+				"noNestedTernary": "error",
+				"noParameterAssign": "error",
+				"noSubstr": "error",
+				"noUnusedTemplateLiteral": "error",
+				"noUselessElse": "error",
+				"noYodaExpression": "error",
+				"useAsConstAssertion": "error",
+				"useAtIndex": "error",
+				"useCollapsedElseIf": "error",
+				"useCollapsedIf": "error",
+				"useConsistentBuiltinInstantiation": "error",
+				"useDefaultParameterLast": "error",
+				"useExplicitLengthCheck": "error",
+				"useForOf": "error",
+				"useFragmentSyntax": "error",
+				"useNumberNamespace": "error",
+				"useSelfClosingElements": "error",
+				"useShorthandAssign": "error",
+				"useThrowNewError": "error",
+				"useThrowOnlyError": "error",
+				"useTrimStartEnd": "error"
+			},
+			"suspicious": {
+				"noAlert": "error",
+				"noConstantBinaryExpressions": "error",
+				"noDeprecatedImports": "error",
+				"noEvolvingTypes": "error",
+				"noImportCycles": "error",
+				"noReactForwardRef": "error",
+				"noSkippedTests": "error",
+				"noTemplateCurlyInString": "error",
+				"noTsIgnore": "error",
+				"noUnusedExpressions": "error",
+				"noVar": "error",
+				"useAwait": "error",
+				"useErrorMessage": "error"
 			}
 		}
 	}

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.