Move entity rehydration to domain layer, fix tempHp gap

Rehydration functions (reconstructing typed domain objects from untyped
JSON) lived in persistence adapters, duplicating domain validation.
Adding a field required updating both the domain type and a separate
adapter function — the adapter was missed for `level`, silently dropping
it on reload. Now adding a field only requires updating the domain type
and its co-located rehydration function.

- Add `rehydratePlayerCharacter` and `rehydrateCombatant` to domain
- Persistence adapters delegate to domain instead of reimplementing
- Add `tempHp` validation (was silently dropped during rehydration)
- Tighten initiative validation to integer-only
- Exhaustive domain tests (53 cases); adapter tests slimmed to round-trip
- Remove stale `jsinspect-plus` Knip ignoreDependencies entry

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

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

.jsinspectrc

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

CLAUDE.md

@@ -73,6 +73,7 @@ docs/agents/               RPI skill artifacts (research reports, plans)
 - **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
@@ -97,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 |
@@ -114,6 +117,9 @@ 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)
+- `specs/008-encounter-difficulty/` — Live encounter difficulty indicator (5.5e XP budget system), optional PC level field
 
 ## Constitution (key principles)
 
@@ -124,10 +130,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

@@ -7,7 +7,10 @@ A local-first initiative tracker and encounter manager for tabletop RPGs (D&D 5e
 - **Initiative tracking** — add combatants (batch-add from bestiary, custom creatures with optional stats), roll initiative (manual or d20), cycle turns and rounds
 - **Encounter state** — HP, AC, conditions, concentration tracking with visual status indicators
 - **Bestiary integration** — import bestiary JSON sources, search creatures, and view full stat blocks
-- **Player characters** — create reusable player character templates with name, AC, HP, color, and icon; search and add them to encounters with pre-filled stats; manage (edit/delete) from a dedicated panel
+- **Player characters** — create reusable player character templates with name, AC, HP, level, color, and icon; search and add them to encounters with pre-filled stats; manage (edit/delete) from a dedicated panel
+- **Encounter difficulty** — live 3-bar indicator in the top bar showing encounter difficulty (Trivial/Low/Moderate/High) based on the 2024 5.5e XP budget system; automatically derived from PC levels and bestiary creature CRs
+- **Undo/redo** — reverse any encounter action with Undo/Redo buttons or keyboard shortcuts (Ctrl+Z / Ctrl+Shift+Z, Cmd on Mac); history persists across page reloads
+- **Import/export** — export the full encounter state (combatants, undo/redo history, player characters) as a JSON file or copy to clipboard; import from file upload or pasted JSON with validation and confirmation
 - **Persistent** — encounters survive page reloads via localStorage; bestiary data cached in IndexedDB; player characters stored independently
 
 ## Prerequisites

apps/web/index.html

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

apps/web/src/App.tsx

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

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

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

apps/web/src/__tests__/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/components/__tests__/turn-navigation.test.tsx

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -6,6 +6,7 @@ import {
 	useRef,
 	useState,
 } from "react";
+import { useClickOutside } from "../../hooks/use-click-outside.js";
 import { cn } from "../../lib/utils";
 import { Button } from "./button";
 
@@ -42,32 +43,7 @@ export function ConfirmButton({
 		return () => clearTimeout(timerRef.current);
 	}, []);
 
-	// Click-outside listener when confirming
-	useEffect(() => {
-		if (!isConfirming) return;
-
-		function handleMouseDown(e: MouseEvent) {
-			if (
-				wrapperRef.current &&
-				!wrapperRef.current.contains(e.target as Node)
-			) {
-				revert();
-			}
-		}
-
-		function handleEscapeKey(e: KeyboardEvent) {
-			if (e.key === "Escape") {
-				revert();
-			}
-		}
-
-		document.addEventListener("mousedown", handleMouseDown);
-		document.addEventListener("keydown", handleEscapeKey);
-		return () => {
-			document.removeEventListener("mousedown", handleMouseDown);
-			document.removeEventListener("keydown", handleEscapeKey);
-		};
-	}, [isConfirming, revert]);
+	useClickOutside(wrapperRef, revert, isConfirming);
 
 	const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
 		if (e.key === "Enter" || e.key === " ") {

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

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

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

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

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

@@ -1,5 +1,6 @@
 import { EllipsisVertical } from "lucide-react";
-import { type ReactNode, useEffect, useRef, useState } from "react";
+import { type ReactNode, useRef, useState } from "react";
+import { useClickOutside } from "../../hooks/use-click-outside.js";
 import { Button } from "./button";
 
 export interface OverflowMenuItem {
@@ -18,23 +19,7 @@ export function OverflowMenu({ items }: OverflowMenuProps) {
 	const [open, setOpen] = useState(false);
 	const ref = useRef<HTMLDivElement>(null);
 
-	useEffect(() => {
-		if (!open) return;
-		function handleMouseDown(e: MouseEvent) {
-			if (ref.current && !ref.current.contains(e.target as Node)) {
-				setOpen(false);
-			}
-		}
-		function handleKeyDown(e: KeyboardEvent) {
-			if (e.key === "Escape") setOpen(false);
-		}
-		document.addEventListener("mousedown", handleMouseDown);
-		document.addEventListener("keydown", handleKeyDown);
-		return () => {
-			document.removeEventListener("mousedown", handleMouseDown);
-			document.removeEventListener("keydown", handleKeyDown);
-		};
-	}, [open]);
+	useClickOutside(ref, () => setOpen(false), open);
 
 	return (
 		<div ref={ref} className="relative">

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

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

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

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

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

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

apps/web/src/hooks/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

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

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

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

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

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

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

@@ -1,10 +1,11 @@
-import type { EncounterStore } from "@initiative/application";
+import type { EncounterStore, UndoRedoStore } from "@initiative/application";
 import {
 	addCombatantUseCase,
 	adjustHpUseCase,
 	advanceTurnUseCase,
 	clearEncounterUseCase,
 	editCombatantUseCase,
+	redoUseCase,
 	removeCombatantUseCase,
 	retreatTurnUseCase,
 	setAcUseCase,
@@ -13,20 +14,26 @@ import {
 	setTempHpUseCase,
 	toggleConcentrationUseCase,
 	toggleConditionUseCase,
+	undoUseCase,
 } from "@initiative/application";
 import type {
 	BestiaryIndexEntry,
 	CombatantId,
+	CombatantInit,
 	ConditionId,
 	CreatureId,
+	DomainError,
 	DomainEvent,
 	Encounter,
 	PlayerCharacter,
+	UndoRedoState,
 } from "@initiative/domain";
 import {
+	clearHistory,
 	combatantId,
 	isDomainError,
 	creatureId as makeCreatureId,
+	pushUndo,
 	resolveCreatureName,
 } from "@initiative/domain";
 import { useCallback, useEffect, useRef, useState } from "react";
@@ -34,6 +41,10 @@ import {
 	loadEncounter,
 	saveEncounter,
 } from "../persistence/encounter-storage.js";
+import {
+	loadUndoRedoStacks,
+	saveUndoRedoStacks,
+} from "../persistence/undo-redo-storage.js";
 
 const COMBATANT_ID_REGEX = /^c-(\d+)$/;
 
@@ -61,43 +72,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,
@@ -108,164 +100,111 @@ export function useEncounter() {
 		};
 	}, []);
 
-	const advanceTurn = useCallback(() => {
-		const result = advanceTurnUseCase(makeStore());
+	const makeUndoRedoStore = useCallback((): UndoRedoStore => {
+		return {
+			get: () => undoRedoRef.current,
+			save: (s) => {
+				undoRedoRef.current = s;
+				setUndoRedoState(s);
+			},
+		};
+	}, []);
 
-		if (isDomainError(result)) {
-			return;
+	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;
+	}, []);
 
-		setEvents((prev) => [...prev, ...result]);
-	}, [makeStore]);
-
-	const retreatTurn = useCallback(() => {
-		const result = retreatTurnUseCase(makeStore());
-
-		if (isDomainError(result)) {
-			return;
-		}
-
-		setEvents((prev) => [...prev, ...result]);
-	}, [makeStore]);
+	const dispatchAction = useCallback(
+		(action: () => DomainEvent[] | DomainError) => {
+			const result = withUndo(action);
+			if (!isDomainError(result)) {
+				setEvents((prev) => [...prev, ...result]);
+			}
+		},
+		[withUndo],
+	);
 
 	const nextId = useRef(deriveNextId(encounter));
 
+	const advanceTurn = useCallback(
+		() => dispatchAction(() => advanceTurnUseCase(makeStore())),
+		[makeStore, dispatchAction],
+	);
+
+	const retreatTurn = useCallback(
+		() => dispatchAction(() => retreatTurnUseCase(makeStore())),
+		[makeStore, dispatchAction],
+	);
+
 	const addCombatant = useCallback(
-		(name: string, opts?: CombatantOpts) => {
+		(name: string, init?: CombatantInit) => {
 			const id = combatantId(`c-${++nextId.current}`);
-			const result = addCombatantUseCase(makeStore(), id, name);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			if (opts) {
-				const optEvents = applyCombatantOpts(makeStore, id, opts);
-				if (optEvents.length > 0) {
-					setEvents((prev) => [...prev, ...optEvents]);
-				}
-			}
-
-			setEvents((prev) => [...prev, ...result]);
+			dispatchAction(() => addCombatantUseCase(makeStore(), id, name, init));
 		},
-		[makeStore],
+		[makeStore, dispatchAction],
 	);
 
 	const removeCombatant = useCallback(
-		(id: CombatantId) => {
-			const result = removeCombatantUseCase(makeStore(), id);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
+		(id: CombatantId) =>
+			dispatchAction(() => removeCombatantUseCase(makeStore(), id)),
+		[makeStore, dispatchAction],
 	);
 
 	const editCombatant = useCallback(
-		(id: CombatantId, newName: string) => {
-			const result = editCombatantUseCase(makeStore(), id, newName);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
+		(id: CombatantId, newName: string) =>
+			dispatchAction(() => editCombatantUseCase(makeStore(), id, newName)),
+		[makeStore, dispatchAction],
 	);
 
 	const setInitiative = useCallback(
-		(id: CombatantId, value: number | undefined) => {
-			const result = setInitiativeUseCase(makeStore(), id, value);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
+		(id: CombatantId, value: number | undefined) =>
+			dispatchAction(() => setInitiativeUseCase(makeStore(), id, value)),
+		[makeStore, dispatchAction],
 	);
 
 	const setHp = useCallback(
-		(id: CombatantId, maxHp: number | undefined) => {
-			const result = setHpUseCase(makeStore(), id, maxHp);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
+		(id: CombatantId, maxHp: number | undefined) =>
+			dispatchAction(() => setHpUseCase(makeStore(), id, maxHp)),
+		[makeStore, dispatchAction],
 	);
 
 	const adjustHp = useCallback(
-		(id: CombatantId, delta: number) => {
-			const result = adjustHpUseCase(makeStore(), id, delta);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
+		(id: CombatantId, delta: number) =>
+			dispatchAction(() => adjustHpUseCase(makeStore(), id, delta)),
+		[makeStore, dispatchAction],
 	);
 
 	const setTempHp = useCallback(
-		(id: CombatantId, tempHp: number | undefined) => {
-			const result = setTempHpUseCase(makeStore(), id, tempHp);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
+		(id: CombatantId, tempHp: number | undefined) =>
+			dispatchAction(() => setTempHpUseCase(makeStore(), id, tempHp)),
+		[makeStore, dispatchAction],
 	);
 
 	const setAc = useCallback(
-		(id: CombatantId, value: number | undefined) => {
-			const result = setAcUseCase(makeStore(), id, value);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
+		(id: CombatantId, value: number | undefined) =>
+			dispatchAction(() => setAcUseCase(makeStore(), id, value)),
+		[makeStore, dispatchAction],
 	);
 
 	const toggleCondition = useCallback(
-		(id: CombatantId, conditionId: ConditionId) => {
-			const result = toggleConditionUseCase(makeStore(), id, conditionId);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
+		(id: CombatantId, conditionId: ConditionId) =>
+			dispatchAction(() =>
+				toggleConditionUseCase(makeStore(), id, conditionId),
+			),
+		[makeStore, dispatchAction],
 	);
 
 	const toggleConcentration = useCallback(
-		(id: CombatantId) => {
-			const result = toggleConcentrationUseCase(makeStore(), id);
-
-			if (isDomainError(result)) {
-				return;
-			}
-
-			setEvents((prev) => [...prev, ...result]);
-		},
-		[makeStore],
+		(id: CombatantId) =>
+			dispatchAction(() => toggleConcentrationUseCase(makeStore(), id)),
+		[makeStore, dispatchAction],
 	);
 
 	const clearEncounter = useCallback(() => {
@@ -275,20 +214,20 @@ 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): CreatureId | null => {
+	const resolveAndRename = useCallback(
+		(name: string): string => {
 			const store = makeStore();
 			const existingNames = store.get().combatants.map((c) => c.name);
-			const { newName, renames } = resolveCreatureName(
-				entry.name,
-				existingNames,
-			);
+			const { newName, renames } = resolveCreatureName(name, existingNames);
 
-			// Apply renames (e.g., "Goblin" → "Goblin 1")
 			for (const { from, to } of renames) {
 				const target = store.get().combatants.find((c) => c.name === from);
 				if (target) {
@@ -296,100 +235,122 @@ export function useEncounter() {
 				}
 			}
 
-			// Add combatant with resolved name
-			const id = combatantId(`c-${++nextId.current}`);
-			const addResult = addCombatantUseCase(makeStore(), id, newName);
-			if (isDomainError(addResult)) return null;
+			return newName;
+		},
+		[makeStore],
+	);
 
-			// Set HP
-			const hpResult = setHpUseCase(makeStore(), id, entry.hp);
-			if (!isDomainError(hpResult)) {
-				setEvents((prev) => [...prev, ...hpResult]);
-			}
+	const addOneFromBestiary = useCallback(
+		(
+			entry: BestiaryIndexEntry,
+		): { cId: CreatureId; events: DomainEvent[] } | null => {
+			const newName = resolveAndRename(entry.name);
 
-			// Set AC
-			if (entry.ac > 0) {
-				const acResult = setAcUseCase(makeStore(), id, entry.ac);
-				if (!isDomainError(acResult)) {
-					setEvents((prev) => [...prev, ...acResult]);
-				}
-			}
-
-			// Derive creatureId from source + name
 			const slug = entry.name
 				.toLowerCase()
 				.replaceAll(/[^a-z0-9]+/g, "-")
 				.replaceAll(/(^-|-$)/g, "");
 			const cId = makeCreatureId(`${entry.source.toLowerCase()}:${slug}`);
 
-			// Set creatureId on the combatant (use store.save to keep ref in sync for batch calls)
-			const currentEncounter = store.get();
-			store.save({
-				...currentEncounter,
-				combatants: currentEncounter.combatants.map((c) =>
-					c.id === id ? { ...c, creatureId: cId } : c,
-				),
+			const id = combatantId(`c-${++nextId.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;
+			return { cId, events: result };
 		},
-		[makeStore],
+		[makeStore, resolveAndRename],
+	);
+
+	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 store = makeStore();
-			const existingNames = store.get().combatants.map((c) => c.name);
-			const { newName, renames } = resolveCreatureName(pc.name, existingNames);
-
-			for (const { from, to } of renames) {
-				const target = store.get().combatants.find((c) => c.name === from);
-				if (target) {
-					editCombatantUseCase(makeStore(), target.id, to);
-				}
-			}
+			const snapshot = encounterRef.current;
+			const newName = resolveAndRename(pc.name);
 
 			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)) {
+				makeStore().save(snapshot);
+				return;
+			}
+
+			const newState = pushUndo(undoRedoRef.current, snapshot);
+			undoRedoRef.current = newState;
+			setUndoRedoState(newState);
+
+			setEvents((prev) => [...prev, ...result]);
 		},
-		[makeStore],
+		[makeStore, resolveAndRename],
 	);
 
+	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,
 	);
@@ -404,11 +365,14 @@ export function useEncounter() {
 
 	return {
 		encounter,
+		undoRedoState,
 		events,
 		isEmpty,
 		hasTempHp,
 		hasCreatureCombatants,
 		canRollAllInitiative,
+		canUndo,
+		canRedo,
 		advanceTurn,
 		retreatTurn,
 		addCombatant,
@@ -423,7 +387,13 @@ export function useEncounter() {
 		toggleCondition,
 		toggleConcentration,
 		addFromBestiary,
+		addMultipleFromBestiary,
 		addFromPlayerCharacter,
+		undo: undoAction,
+		redo: redoAction,
+		setEncounter,
+		setUndoRedoState,
 		makeStore,
+		withUndo,
 	} as const;
 }

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

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

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

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

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

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

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

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

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

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

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

@@ -90,102 +90,7 @@ describe("player-character-storage", () => {
 		});
 	});
 
-	describe("per-character validation", () => {
-		it("discards character with missing name", () => {
-			mockStorage.setItem(
-				STORAGE_KEY,
-				JSON.stringify([
-					{ id: "pc-1", ac: 10, maxHp: 50, color: "blue", icon: "sword" },
-				]),
-			);
-			expect(loadPlayerCharacters()).toEqual([]);
-		});
-
-		it("discards character with empty name", () => {
-			mockStorage.setItem(
-				STORAGE_KEY,
-				JSON.stringify([
-					{
-						id: "pc-1",
-						name: "",
-						ac: 10,
-						maxHp: 50,
-						color: "blue",
-						icon: "sword",
-					},
-				]),
-			);
-			expect(loadPlayerCharacters()).toEqual([]);
-		});
-
-		it("discards character with invalid color", () => {
-			mockStorage.setItem(
-				STORAGE_KEY,
-				JSON.stringify([
-					{
-						id: "pc-1",
-						name: "Test",
-						ac: 10,
-						maxHp: 50,
-						color: "neon",
-						icon: "sword",
-					},
-				]),
-			);
-			expect(loadPlayerCharacters()).toEqual([]);
-		});
-
-		it("discards character with invalid icon", () => {
-			mockStorage.setItem(
-				STORAGE_KEY,
-				JSON.stringify([
-					{
-						id: "pc-1",
-						name: "Test",
-						ac: 10,
-						maxHp: 50,
-						color: "blue",
-						icon: "banana",
-					},
-				]),
-			);
-			expect(loadPlayerCharacters()).toEqual([]);
-		});
-
-		it("discards character with negative AC", () => {
-			mockStorage.setItem(
-				STORAGE_KEY,
-				JSON.stringify([
-					{
-						id: "pc-1",
-						name: "Test",
-						ac: -1,
-						maxHp: 50,
-						color: "blue",
-						icon: "sword",
-					},
-				]),
-			);
-			expect(loadPlayerCharacters()).toEqual([]);
-		});
-
-		it("discards character with maxHp of 0", () => {
-			mockStorage.setItem(
-				STORAGE_KEY,
-				JSON.stringify([
-					{
-						id: "pc-1",
-						name: "Test",
-						ac: 10,
-						maxHp: 0,
-						color: "blue",
-						icon: "sword",
-					},
-				]),
-			);
-			expect(loadPlayerCharacters()).toEqual([]);
-		});
-
+	describe("delegation to domain rehydration", () => {
 		it("keeps valid characters and discards invalid ones", () => {
 			mockStorage.setItem(
 				STORAGE_KEY,

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

@@ -1,14 +1,9 @@
 import {
-	type ConditionId,
-	combatantId,
+	type Combatant,
 	createEncounter,
-	creatureId,
 	type Encounter,
 	isDomainError,
-	playerCharacterId,
-	VALID_CONDITION_IDS,
-	VALID_PLAYER_COLORS,
-	VALID_PLAYER_ICONS,
+	rehydrateCombatant,
 } from "@initiative/domain";
 
 const STORAGE_KEY = "initiative:encounter";
@@ -21,91 +16,42 @@ export function saveEncounter(encounter: Encounter): void {
 	}
 }
 
-function validateAc(value: unknown): number | undefined {
-	return typeof value === "number" && Number.isInteger(value) && value >= 0
-		? value
-		: undefined;
-}
+export function rehydrateEncounter(parsed: unknown): Encounter | null {
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+		return null;
 
-function validateConditions(value: unknown): ConditionId[] | undefined {
-	if (!Array.isArray(value)) return undefined;
-	const valid = value.filter(
-		(v): v is ConditionId =>
-			typeof v === "string" && VALID_CONDITION_IDS.has(v),
-	);
-	return valid.length > 0 ? valid : undefined;
-}
+	const obj = parsed as Record<string, unknown>;
 
-function validateCreatureId(value: unknown) {
-	return typeof value === "string" && value.length > 0
-		? creatureId(value)
-		: undefined;
-}
+	if (!Array.isArray(obj.combatants)) return null;
+	if (typeof obj.activeIndex !== "number") return null;
+	if (typeof obj.roundNumber !== "number") return null;
 
-function validateHp(
-	rawMaxHp: unknown,
-	rawCurrentHp: unknown,
-): { maxHp: number; currentHp: number } | undefined {
-	if (
-		typeof rawMaxHp !== "number" ||
-		!Number.isInteger(rawMaxHp) ||
-		rawMaxHp < 1
-	) {
-		return undefined;
+	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,
+		};
 	}
-	const validCurrentHp =
-		typeof rawCurrentHp === "number" &&
-		Number.isInteger(rawCurrentHp) &&
-		rawCurrentHp >= 0 &&
-		rawCurrentHp <= rawMaxHp;
-	return {
-		maxHp: rawMaxHp,
-		currentHp: validCurrentHp ? rawCurrentHp : rawMaxHp,
-	};
-}
 
-function rehydrateCombatant(c: unknown) {
-	const entry = c as Record<string, unknown>;
-	const base = {
-		id: combatantId(entry.id as string),
-		name: entry.name as string,
-		initiative:
-			typeof entry.initiative === "number" ? entry.initiative : undefined,
-	};
+	const rehydrated: Combatant[] = [];
+	for (const c of combatants) {
+		const result = rehydrateCombatant(c);
+		if (result === null) return null;
+		rehydrated.push(result);
+	}
 
-	const color =
-		typeof entry.color === "string" && VALID_PLAYER_COLORS.has(entry.color)
-			? entry.color
-			: undefined;
-	const icon =
-		typeof entry.icon === "string" && VALID_PLAYER_ICONS.has(entry.icon)
-			? entry.icon
-			: undefined;
-	const pcId =
-		typeof entry.playerCharacterId === "string" &&
-		entry.playerCharacterId.length > 0
-			? playerCharacterId(entry.playerCharacterId)
-			: undefined;
+	const encounter = createEncounter(
+		rehydrated,
+		obj.activeIndex,
+		obj.roundNumber,
+	);
+	if (isDomainError(encounter)) return null;
 
-	const shared = {
-		...base,
-		ac: validateAc(entry.ac),
-		conditions: validateConditions(entry.conditions),
-		isConcentrating: entry.isConcentrating === true ? true : undefined,
-		creatureId: validateCreatureId(entry.creatureId),
-		color,
-		icon,
-		playerCharacterId: pcId,
-	};
-
-	const hp = validateHp(entry.maxHp, entry.currentHp);
-	return hp ? { ...shared, ...hp } : shared;
-}
-
-function isValidCombatantEntry(c: unknown): boolean {
-	if (typeof c !== "object" || c === null || Array.isArray(c)) return false;
-	const entry = c as Record<string, unknown>;
-	return typeof entry.id === "string" && typeof entry.name === "string";
+	return encounter;
 }
 
 export function loadEncounter(): Encounter | null {
@@ -114,39 +60,7 @@ export function loadEncounter(): Encounter | null {
 		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 { rehydratePlayerCharacter } from "@initiative/domain";
+import { rehydrateEncounter } from "./encounter-storage.js";
+
+function rehydrateStack(raw: unknown[]): Encounter[] {
+	const result: Encounter[] = [];
+	for (const entry of raw) {
+		const rehydrated = rehydrateEncounter(entry);
+		if (rehydrated !== null) {
+			result.push(rehydrated);
+		}
+	}
+	return result;
+}
+
+function rehydrateCharacters(raw: unknown[]): PlayerCharacter[] {
+	const result: PlayerCharacter[] = [];
+	for (const entry of raw) {
+		const rehydrated = rehydratePlayerCharacter(entry);
+		if (rehydrated !== null) {
+			result.push(rehydrated);
+		}
+	}
+	return result;
+}
+
+export function validateImportBundle(data: unknown): ExportBundle | string {
+	if (typeof data !== "object" || data === null || Array.isArray(data)) {
+		return "Invalid file format";
+	}
+
+	const obj = data as Record<string, unknown>;
+
+	if (typeof obj.version !== "number" || obj.version !== 1) {
+		return "Invalid file format";
+	}
+	if (typeof obj.exportedAt !== "string") {
+		return "Invalid file format";
+	}
+	if (!Array.isArray(obj.undoStack) || !Array.isArray(obj.redoStack)) {
+		return "Invalid file format";
+	}
+	if (!Array.isArray(obj.playerCharacters)) {
+		return "Invalid file format";
+	}
+
+	const encounter = rehydrateEncounter(obj.encounter);
+	if (encounter === null) {
+		return "Invalid encounter data";
+	}
+
+	return {
+		version: 1,
+		exportedAt: obj.exportedAt,
+		encounter,
+		undoStack: rehydrateStack(obj.undoStack),
+		redoStack: rehydrateStack(obj.redoStack),
+		playerCharacters: rehydrateCharacters(obj.playerCharacters),
+	};
+}
+
+export function assembleExportBundle(
+	encounter: Encounter,
+	undoRedoState: UndoRedoState,
+	playerCharacters: readonly PlayerCharacter[],
+	includeHistory = true,
+): ExportBundle {
+	return {
+		version: 1,
+		exportedAt: new Date().toISOString(),
+		encounter,
+		undoStack: includeHistory ? undoRedoState.undoStack : [],
+		redoStack: includeHistory ? undoRedoState.redoStack : [],
+		playerCharacters: [...playerCharacters],
+	};
+}
+
+export function bundleToJson(bundle: ExportBundle): string {
+	return JSON.stringify(bundle, null, 2);
+}
+
+export function resolveFilename(name?: string): string {
+	const base =
+		name?.trim() ||
+		`initiative-export-${new Date().toISOString().slice(0, 10)}`;
+	return base.endsWith(".json") ? base : `${base}.json`;
+}
+
+export function triggerDownload(bundle: ExportBundle, name?: string): void {
+	const blob = new Blob([bundleToJson(bundle)], { type: "application/json" });
+	const url = URL.createObjectURL(blob);
+
+	const filename = resolveFilename(name);
+
+	const anchor = document.createElement("a");
+	anchor.href = url;
+	anchor.download = filename;
+	anchor.click();
+
+	URL.revokeObjectURL(url);
+}
+
+export async function readImportFile(
+	file: File,
+): Promise<ExportBundle | string> {
+	try {
+		const text = await file.text();
+		const parsed: unknown = JSON.parse(text);
+		return validateImportBundle(parsed);
+	} catch {
+		return "Invalid file format";
+	}
+}

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

@@ -1,9 +1,5 @@
 import type { PlayerCharacter } from "@initiative/domain";
-import {
-	playerCharacterId,
-	VALID_PLAYER_COLORS,
-	VALID_PLAYER_ICONS,
-} from "@initiative/domain";
+import { rehydratePlayerCharacter } from "@initiative/domain";
 
 const STORAGE_KEY = "initiative:player-characters";
 
@@ -15,46 +11,6 @@ export function savePlayerCharacters(characters: PlayerCharacter[]): void {
 	}
 }
 
-function isValidOptionalMember(
-	value: unknown,
-	valid: ReadonlySet<string>,
-): boolean {
-	return value === undefined || (typeof value === "string" && valid.has(value));
-}
-
-function rehydrateCharacter(raw: unknown): PlayerCharacter | null {
-	if (typeof raw !== "object" || raw === null || Array.isArray(raw))
-		return null;
-	const entry = raw as Record<string, unknown>;
-
-	if (typeof entry.id !== "string" || entry.id.length === 0) return null;
-	if (typeof entry.name !== "string" || entry.name.trim().length === 0)
-		return null;
-	if (
-		typeof entry.ac !== "number" ||
-		!Number.isInteger(entry.ac) ||
-		entry.ac < 0
-	)
-		return null;
-	if (
-		typeof entry.maxHp !== "number" ||
-		!Number.isInteger(entry.maxHp) ||
-		entry.maxHp < 1
-	)
-		return null;
-	if (!isValidOptionalMember(entry.color, VALID_PLAYER_COLORS)) return null;
-	if (!isValidOptionalMember(entry.icon, VALID_PLAYER_ICONS)) return null;
-
-	return {
-		id: playerCharacterId(entry.id),
-		name: entry.name,
-		ac: entry.ac,
-		maxHp: entry.maxHp,
-		color: entry.color as PlayerCharacter["color"],
-		icon: entry.icon as PlayerCharacter["icon"],
-	};
-}
-
 export function loadPlayerCharacters(): PlayerCharacter[] {
 	try {
 		const raw = localStorage.getItem(STORAGE_KEY);
@@ -65,7 +21,7 @@ export function loadPlayerCharacters(): PlayerCharacter[] {
 
 		const characters: PlayerCharacter[] = [];
 		for (const item of parsed) {
-			const pc = rehydrateCharacter(item);
+			const pc = rehydratePlayerCharacter(item);
 			if (pc !== null) {
 				characters.push(pc);
 			}

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

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

biome.json

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

docs/adr/000-template.md

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

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

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

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

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

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

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

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

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

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

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

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

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

package.json

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -13,6 +13,7 @@ interface EditFields {
 	readonly maxHp?: number;
 	readonly color?: string | null;
 	readonly icon?: string | null;
+	readonly level?: number | null;
 }
 
 export function editPlayerCharacterUseCase(

packages/application/src/index.ts

@@ -10,7 +10,9 @@ export type {
 	BestiarySourceCache,
 	EncounterStore,
 	PlayerCharacterStore,
+	UndoRedoStore,
 } from "./ports.js";
+export { redoUseCase } from "./redo-use-case.js";
 export { removeCombatantUseCase } from "./remove-combatant-use-case.js";
 export { retreatTurnUseCase } from "./retreat-turn-use-case.js";
 export {
@@ -24,3 +26,4 @@ export { setInitiativeUseCase } from "./set-initiative-use-case.js";
 export { setTempHpUseCase } from "./set-temp-hp-use-case.js";
 export { toggleConcentrationUseCase } from "./toggle-concentration-use-case.js";
 export { toggleConditionUseCase } from "./toggle-condition-use-case.js";
+export { undoUseCase } from "./undo-use-case.js";

packages/application/src/ports.ts

@@ -3,6 +3,7 @@ import type {
 	CreatureId,
 	Encounter,
 	PlayerCharacter,
+	UndoRedoState,
 } from "@initiative/domain";
 
 export interface EncounterStore {
@@ -19,3 +20,8 @@ export interface PlayerCharacterStore {
 	getAll(): PlayerCharacter[];
 	save(characters: PlayerCharacter[]): void;
 }
+
+export interface UndoRedoStore {
+	get(): UndoRedoState;
+	save(state: UndoRedoState): void;
+}

packages/application/src/redo-use-case.ts

@@ -0,0 +1,24 @@
+import {
+	type DomainError,
+	type Encounter,
+	isDomainError,
+	redo,
+} from "@initiative/domain";
+import type { EncounterStore, UndoRedoStore } from "./ports.js";
+
+export function redoUseCase(
+	encounterStore: EncounterStore,
+	undoRedoStore: UndoRedoStore,
+): Encounter | DomainError {
+	const current = encounterStore.get();
+	const state = undoRedoStore.get();
+	const result = redo(state, current);
+
+	if (isDomainError(result)) {
+		return result;
+	}
+
+	encounterStore.save(result.encounter);
+	undoRedoStore.save(result.state);
+	return result.encounter;
+}

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

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

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

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

packages/application/src/run-encounter-action.ts

@@ -0,0 +1,27 @@
+import {
+	type DomainError,
+	type DomainEvent,
+	type Encounter,
+	isDomainError,
+} from "@initiative/domain";
+import type { EncounterStore } from "./ports.js";
+
+interface EncounterActionResult {
+	readonly encounter: Encounter;
+	readonly events: DomainEvent[];
+}
+
+export function runEncounterAction(
+	store: EncounterStore,
+	action: (encounter: Encounter) => EncounterActionResult | DomainError,
+): DomainEvent[] | DomainError {
+	const encounter = store.get();
+	const result = action(encounter);
+
+	if (isDomainError(result)) {
+		return result;
+	}
+
+	store.save(result.encounter);
+	return result.events;
+}

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

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

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

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

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

@@ -2,23 +2,17 @@ import {
 	type CombatantId,
 	type DomainError,
 	type DomainEvent,
-	isDomainError,
 	setInitiative,
 } from "@initiative/domain";
 import type { EncounterStore } from "./ports.js";
+import { runEncounterAction } from "./run-encounter-action.js";
 
 export function setInitiativeUseCase(
 	store: EncounterStore,
 	combatantId: CombatantId,
 	value: number | undefined,
 ): DomainEvent[] | DomainError {
-	const encounter = store.get();
-	const result = setInitiative(encounter, combatantId, value);
-
-	if (isDomainError(result)) {
-		return result;
-	}
-
-	store.save(result.encounter);
-	return result.events;
+	return runEncounterAction(store, (encounter) =>
+		setInitiative(encounter, combatantId, value),
+	);
 }

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

@@ -2,23 +2,17 @@ import {
 	type CombatantId,
 	type DomainError,
 	type DomainEvent,
-	isDomainError,
 	setTempHp,
 } from "@initiative/domain";
 import type { EncounterStore } from "./ports.js";
+import { runEncounterAction } from "./run-encounter-action.js";
 
 export function setTempHpUseCase(
 	store: EncounterStore,
 	combatantId: CombatantId,
 	tempHp: number | undefined,
 ): DomainEvent[] | DomainError {
-	const encounter = store.get();
-	const result = setTempHp(encounter, combatantId, tempHp);
-
-	if (isDomainError(result)) {
-		return result;
-	}
-
-	store.save(result.encounter);
-	return result.events;
+	return runEncounterAction(store, (encounter) =>
+		setTempHp(encounter, combatantId, tempHp),
+	);
 }

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

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

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

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

packages/application/src/undo-use-case.ts

@@ -0,0 +1,24 @@
+import {
+	type DomainError,
+	type Encounter,
+	isDomainError,
+	undo,
+} from "@initiative/domain";
+import type { EncounterStore, UndoRedoStore } from "./ports.js";
+
+export function undoUseCase(
+	encounterStore: EncounterStore,
+	undoRedoStore: UndoRedoStore,
+): Encounter | DomainError {
+	const current = encounterStore.get();
+	const state = undoRedoStore.get();
+	const result = undo(state, current);
+
+	if (isDomainError(result)) {
+		return result;
+	}
+
+	encounterStore.save(result.encounter);
+	undoRedoStore.save(result.state);
+	return result.encounter;
+}

packages/domain/src/__tests__/add-combatant.test.ts

@@ -1,13 +1,18 @@
 import { describe, expect, it } from "vitest";
-import { addCombatant } from "../add-combatant.js";
+import { addCombatant, type CombatantInit } from "../add-combatant.js";
+import { creatureId } from "../creature-types.js";
+import { playerCharacterId } from "../player-character-types.js";
 import type { Combatant, Encounter } from "../types.js";
 import { combatantId, isDomainError } from "../types.js";
 import { expectDomainError } from "./test-helpers.js";
 
 // --- Helpers ---
 
-function makeCombatant(name: string): Combatant {
-	return { id: combatantId(name), name };
+function makeCombatant(
+	name: string,
+	overrides?: Partial<Combatant>,
+): Combatant {
+	return { id: combatantId(name), name, ...overrides };
 }
 
 const A = makeCombatant("A");
@@ -22,8 +27,13 @@ function enc(
 	return { combatants, activeIndex, roundNumber };
 }
 
-function successResult(encounter: Encounter, id: string, name: string) {
-	const result = addCombatant(encounter, combatantId(id), name);
+function successResult(
+	encounter: Encounter,
+	id: string,
+	name: string,
+	init?: CombatantInit,
+) {
+	const result = addCombatant(encounter, combatantId(id), name, init);
 	if (isDomainError(result)) {
 		throw new Error(`Expected success, got error: ${result.message}`);
 	}
@@ -190,4 +200,152 @@ describe("addCombatant", () => {
 			expect(encounter.combatants[1]).toEqual(B);
 		});
 	});
+
+	describe("with CombatantInit", () => {
+		it("creates combatant with maxHp and currentHp set to maxHp", () => {
+			const e = enc([]);
+			const { encounter } = successResult(e, "orc", "Orc", {
+				maxHp: 15,
+			});
+			const c = encounter.combatants[0];
+			expect(c.maxHp).toBe(15);
+			expect(c.currentHp).toBe(15);
+		});
+
+		it("creates combatant with ac", () => {
+			const e = enc([]);
+			const { encounter } = successResult(e, "orc", "Orc", {
+				ac: 13,
+			});
+			expect(encounter.combatants[0].ac).toBe(13);
+		});
+
+		it("creates combatant with initiative and sorts into position", () => {
+			const hi = makeCombatant("Hi", { initiative: 20 });
+			const lo = makeCombatant("Lo", { initiative: 10 });
+			const e = enc([hi, lo]);
+
+			const { encounter } = successResult(e, "mid", "Mid", {
+				initiative: 15,
+			});
+
+			expect(encounter.combatants.map((c) => c.name)).toEqual([
+				"Hi",
+				"Mid",
+				"Lo",
+			]);
+		});
+
+		it("rejects invalid maxHp (non-integer)", () => {
+			const e = enc([]);
+			const result = addCombatant(e, combatantId("x"), "X", {
+				maxHp: 1.5,
+			});
+			expectDomainError(result, "invalid-max-hp");
+		});
+
+		it("rejects invalid maxHp (zero)", () => {
+			const e = enc([]);
+			const result = addCombatant(e, combatantId("x"), "X", {
+				maxHp: 0,
+			});
+			expectDomainError(result, "invalid-max-hp");
+		});
+
+		it("rejects invalid ac (negative)", () => {
+			const e = enc([]);
+			const result = addCombatant(e, combatantId("x"), "X", {
+				ac: -1,
+			});
+			expectDomainError(result, "invalid-ac");
+		});
+
+		it("rejects invalid initiative (non-integer)", () => {
+			const e = enc([]);
+			const result = addCombatant(e, combatantId("x"), "X", {
+				initiative: 3.5,
+			});
+			expectDomainError(result, "invalid-initiative");
+		});
+
+		it("creates combatant with creatureId", () => {
+			const e = enc([]);
+			const cId = creatureId("srd:goblin");
+			const { encounter } = successResult(e, "gob", "Goblin", {
+				creatureId: cId,
+			});
+			expect(encounter.combatants[0].creatureId).toBe(cId);
+		});
+
+		it("creates combatant with color and icon", () => {
+			const e = enc([]);
+			const { encounter } = successResult(e, "pc", "Aria", {
+				color: "blue",
+				icon: "sword",
+			});
+			const c = encounter.combatants[0];
+			expect(c.color).toBe("blue");
+			expect(c.icon).toBe("sword");
+		});
+
+		it("creates combatant with playerCharacterId", () => {
+			const e = enc([]);
+			const pcId = playerCharacterId("pc-1");
+			const { encounter } = successResult(e, "pc", "Aria", {
+				playerCharacterId: pcId,
+			});
+			expect(encounter.combatants[0].playerCharacterId).toBe(pcId);
+		});
+
+		it("creates combatant with all init fields", () => {
+			const e = enc([]);
+			const cId = creatureId("srd:orc");
+			const pcId = playerCharacterId("pc-1");
+			const { encounter } = successResult(e, "orc", "Orc", {
+				maxHp: 15,
+				ac: 13,
+				initiative: 12,
+				creatureId: cId,
+				color: "red",
+				icon: "axe",
+				playerCharacterId: pcId,
+			});
+			const c = encounter.combatants[0];
+			expect(c.maxHp).toBe(15);
+			expect(c.currentHp).toBe(15);
+			expect(c.ac).toBe(13);
+			expect(c.initiative).toBe(12);
+			expect(c.creatureId).toBe(cId);
+			expect(c.color).toBe("red");
+			expect(c.icon).toBe("axe");
+			expect(c.playerCharacterId).toBe(pcId);
+		});
+
+		it("CombatantAdded event includes init", () => {
+			const e = enc([]);
+			const { events } = successResult(e, "orc", "Orc", {
+				maxHp: 15,
+				ac: 13,
+			});
+			expect(events[0]).toMatchObject({
+				type: "CombatantAdded",
+				init: { maxHp: 15, ac: 13 },
+			});
+		});
+
+		it("preserves activeIndex through initiative sort", () => {
+			const hi = makeCombatant("Hi", { initiative: 20 });
+			const lo = makeCombatant("Lo", { initiative: 10 });
+			// Lo is active (index 1)
+			const e = enc([hi, lo], 1);
+
+			const { encounter } = successResult(e, "mid", "Mid", {
+				initiative: 15,
+			});
+
+			// Lo should still be active after sort
+			const loIdx = encounter.combatants.findIndex((c) => c.name === "Lo");
+			expect(encounter.activeIndex).toBe(loIdx);
+		});
+	});
 });

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

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 import {
 	CONDITION_DEFINITIONS,
 	getConditionDescription,
+	getConditionsForEdition,
 } from "../conditions.js";
 
 function findCondition(id: string) {
@@ -25,13 +26,27 @@ describe("getConditionDescription", () => {
 		);
 	});
 
-	it("every condition has both descriptions", () => {
-		for (const def of CONDITION_DEFINITIONS) {
+	it("universal conditions have both descriptions", () => {
+		const universal = CONDITION_DEFINITIONS.filter(
+			(d) => d.edition === undefined,
+		);
+		expect(universal.length).toBeGreaterThan(0);
+		for (const def of universal) {
 			expect(def.description).toBeTruthy();
 			expect(def.description5e).toBeTruthy();
 		}
 	});
 
+	it("edition-specific conditions have their edition description", () => {
+		const sapped = findCondition("sapped");
+		expect(sapped.description).toBeTruthy();
+		expect(sapped.edition).toBe("5.5e");
+
+		const slowed = findCondition("slowed");
+		expect(slowed.description).toBeTruthy();
+		expect(slowed.edition).toBe("5.5e");
+	});
+
 	it("conditions with identical rules share the same text", () => {
 		const blinded = findCondition("blinded");
 		expect(blinded.description).toBe(blinded.description5e);
@@ -42,3 +57,26 @@ describe("getConditionDescription", () => {
 		expect(exhaustion.description).not.toBe(exhaustion.description5e);
 	});
 });
+
+describe("getConditionsForEdition", () => {
+	it("includes sapped and slowed for 5.5e", () => {
+		const conditions = getConditionsForEdition("5.5e");
+		const ids = conditions.map((d) => d.id);
+		expect(ids).toContain("sapped");
+		expect(ids).toContain("slowed");
+	});
+
+	it("excludes sapped and slowed for 5e", () => {
+		const conditions = getConditionsForEdition("5e");
+		const ids = conditions.map((d) => d.id);
+		expect(ids).not.toContain("sapped");
+		expect(ids).not.toContain("slowed");
+	});
+
+	it("includes universal conditions for both editions", () => {
+		const ids5e = getConditionsForEdition("5e").map((d) => d.id);
+		const ids55e = getConditionsForEdition("5.5e").map((d) => d.id);
+		expect(ids5e).toContain("blinded");
+		expect(ids55e).toContain("blinded");
+	});
+});

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

@@ -23,6 +23,7 @@ function success(
 		maxHp,
 		color,
 		icon,
+		undefined,
 	);
 	if (isDomainError(result)) {
 		throw new Error(`Expected success, got error: ${result.message}`);
@@ -241,4 +242,76 @@ describe("createPlayerCharacter", () => {
 		expect(events).toHaveLength(1);
 		expect(events[0].type).toBe("PlayerCharacterCreated");
 	});
+
+	it("creates a player character with a valid level", () => {
+		const result = createPlayerCharacter(
+			[],
+			id,
+			"Test",
+			10,
+			50,
+			"blue",
+			"sword",
+			5,
+		);
+		if (isDomainError(result)) throw new Error(result.message);
+		expect(result.characters[0].level).toBe(5);
+	});
+
+	it("creates a player character without a level", () => {
+		const result = createPlayerCharacter(
+			[],
+			id,
+			"Test",
+			10,
+			50,
+			"blue",
+			"sword",
+			undefined,
+		);
+		if (isDomainError(result)) throw new Error(result.message);
+		expect(result.characters[0].level).toBeUndefined();
+	});
+
+	it("rejects level below 1", () => {
+		const result = createPlayerCharacter(
+			[],
+			id,
+			"Test",
+			10,
+			50,
+			"blue",
+			"sword",
+			0,
+		);
+		expectDomainError(result, "invalid-level");
+	});
+
+	it("rejects level above 20", () => {
+		const result = createPlayerCharacter(
+			[],
+			id,
+			"Test",
+			10,
+			50,
+			"blue",
+			"sword",
+			21,
+		);
+		expectDomainError(result, "invalid-level");
+	});
+
+	it("rejects non-integer level", () => {
+		const result = createPlayerCharacter(
+			[],
+			id,
+			"Test",
+			10,
+			50,
+			"blue",
+			"sword",
+			3.5,
+		);
+		expectDomainError(result, "invalid-level");
+	});
 });

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

@@ -110,4 +110,33 @@ describe("editPlayerCharacter", () => {
 		expect(event.oldName).toBe("Aragorn");
 		expect(event.newName).toBe("Strider");
 	});
+
+	it("sets level on a player character", () => {
+		const result = editPlayerCharacter([makePC()], id, { level: 5 });
+		if (isDomainError(result)) throw new Error(result.message);
+		expect(result.characters[0].level).toBe(5);
+	});
+
+	it("clears level when set to null", () => {
+		const result = editPlayerCharacter([makePC({ level: 5 })], id, {
+			level: null,
+		});
+		if (isDomainError(result)) throw new Error(result.message);
+		expect(result.characters[0].level).toBeUndefined();
+	});
+
+	it("rejects invalid level", () => {
+		const result = editPlayerCharacter([makePC()], id, { level: 0 });
+		expectDomainError(result, "invalid-level");
+	});
+
+	it("rejects level above 20", () => {
+		const result = editPlayerCharacter([makePC()], id, { level: 21 });
+		expectDomainError(result, "invalid-level");
+	});
+
+	it("rejects non-integer level", () => {
+		const result = editPlayerCharacter([makePC()], id, { level: 3.5 });
+		expectDomainError(result, "invalid-level");
+	});
 });

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

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "vitest";
+import {
+	calculateEncounterDifficulty,
+	crToXp,
+} from "../encounter-difficulty.js";
+
+describe("crToXp", () => {
+	it("returns 0 for CR 0", () => {
+		expect(crToXp("0")).toBe(0);
+	});
+
+	it("returns 25 for CR 1/8", () => {
+		expect(crToXp("1/8")).toBe(25);
+	});
+
+	it("returns 50 for CR 1/4", () => {
+		expect(crToXp("1/4")).toBe(50);
+	});
+
+	it("returns 100 for CR 1/2", () => {
+		expect(crToXp("1/2")).toBe(100);
+	});
+
+	it("returns 200 for CR 1", () => {
+		expect(crToXp("1")).toBe(200);
+	});
+
+	it("returns 155000 for CR 30", () => {
+		expect(crToXp("30")).toBe(155000);
+	});
+
+	it("returns 0 for unknown CR", () => {
+		expect(crToXp("99")).toBe(0);
+		expect(crToXp("")).toBe(0);
+		expect(crToXp("abc")).toBe(0);
+	});
+});
+
+describe("calculateEncounterDifficulty", () => {
+	it("returns trivial when monster XP is below Low threshold", () => {
+		// 4x level 1: Low = 200, Moderate = 300, High = 400
+		// 1x CR 0 = 0 XP → trivial
+		const result = calculateEncounterDifficulty([1, 1, 1, 1], ["0"]);
+		expect(result.tier).toBe("trivial");
+		expect(result.totalMonsterXp).toBe(0);
+		expect(result.partyBudget).toEqual({
+			low: 200,
+			moderate: 300,
+			high: 400,
+		});
+	});
+
+	it("returns low for 4x level 1 vs Bugbear (CR 1)", () => {
+		// DMG example: 4x level 1 PCs vs 1 Bugbear (CR 1, 200 XP)
+		// Low = 200, Moderate = 300 → 200 >= 200 but < 300 → Low
+		const result = calculateEncounterDifficulty([1, 1, 1, 1], ["1"]);
+		expect(result.tier).toBe("low");
+		expect(result.totalMonsterXp).toBe(200);
+	});
+
+	it("returns moderate for 5x level 3 vs 1125 XP", () => {
+		// 5x level 3: Low = 750, Moderate = 1125, High = 2000
+		// 1125 XP >= 1125 Moderate but < 2000 High → Moderate
+		// Using CR 3 (700) + CR 2 (450) = 1150 XP ≈ 1125 threshold
+		// Let's use exact: 5 * 225 = 1125 moderate budget
+		// Need monsters that sum exactly to 1125: CR 3 (700) + CR 2 (450) = 1150
+		const result = calculateEncounterDifficulty([3, 3, 3, 3, 3], ["3", "2"]);
+		expect(result.tier).toBe("moderate");
+		expect(result.totalMonsterXp).toBe(1150);
+		expect(result.partyBudget.moderate).toBe(1125);
+	});
+
+	it("returns high when XP meets High threshold", () => {
+		// 4x level 1: High = 400
+		// 2x CR 1 = 400 XP → High
+		const result = calculateEncounterDifficulty([1, 1, 1, 1], ["1", "1"]);
+		expect(result.tier).toBe("high");
+		expect(result.totalMonsterXp).toBe(400);
+	});
+
+	it("caps at high when XP far exceeds threshold", () => {
+		// 4x level 1: High = 400
+		// CR 30 = 155000 XP → still High (no tier above)
+		const result = calculateEncounterDifficulty([1, 1, 1, 1], ["30"]);
+		expect(result.tier).toBe("high");
+		expect(result.totalMonsterXp).toBe(155000);
+	});
+
+	it("handles mixed party levels", () => {
+		// 3x level 3 + 1x level 2
+		// level 3: low=150, mod=225, high=400 (x3 = 450, 675, 1200)
+		// level 2: low=100, mod=150, high=200 (x1 = 100, 150, 200)
+		// Total: low=550, mod=825, high=1400
+		const result = calculateEncounterDifficulty([3, 3, 3, 2], ["3"]);
+		expect(result.partyBudget).toEqual({
+			low: 550,
+			moderate: 825,
+			high: 1400,
+		});
+		expect(result.totalMonsterXp).toBe(700);
+		expect(result.tier).toBe("low");
+	});
+
+	it("returns trivial with empty monster array", () => {
+		const result = calculateEncounterDifficulty([5, 5], []);
+		expect(result.tier).toBe("trivial");
+		expect(result.totalMonsterXp).toBe(0);
+	});
+
+	it("returns high with empty party array (zero budget thresholds)", () => {
+		// Domain function treats empty party as zero budgets — any XP exceeds all thresholds.
+		// The useDifficulty hook guards this path by returning null when no leveled PCs exist.
+		const result = calculateEncounterDifficulty([], ["1"]);
+		expect(result.tier).toBe("high");
+		expect(result.totalMonsterXp).toBe(200);
+		expect(result.partyBudget).toEqual({ low: 0, moderate: 0, high: 0 });
+	});
+
+	it("handles fractional CRs", () => {
+		const result = calculateEncounterDifficulty(
+			[1, 1, 1, 1],
+			["1/8", "1/4", "1/2"],
+		);
+		expect(result.totalMonsterXp).toBe(175); // 25 + 50 + 100
+		expect(result.tier).toBe("trivial"); // 175 < 200 Low
+	});
+
+	it("ignores unknown CRs (0 XP)", () => {
+		const result = calculateEncounterDifficulty([1, 1, 1, 1], ["unknown"]);
+		expect(result.totalMonsterXp).toBe(0);
+		expect(result.tier).toBe("trivial");
+	});
+});

packages/domain/src/__tests__/rehydrate-combatant.test.ts

@@ -0,0 +1,241 @@
+import { describe, expect, it } from "vitest";
+import { rehydrateCombatant } from "../rehydrate-combatant.js";
+
+function validCombatant(overrides: Record<string, unknown> = {}) {
+	return {
+		id: "c-1",
+		name: "Goblin",
+		initiative: 12,
+		ac: 15,
+		maxHp: 7,
+		currentHp: 5,
+		tempHp: 3,
+		conditions: ["poisoned"],
+		isConcentrating: true,
+		creatureId: "creature-goblin",
+		color: "red",
+		icon: "skull",
+		playerCharacterId: "pc-1",
+		...overrides,
+	};
+}
+
+function minimalCombatant() {
+	return { id: "c-1", name: "Goblin" };
+}
+
+describe("rehydrateCombatant", () => {
+	describe("valid input", () => {
+		it("accepts a combatant with all fields", () => {
+			const result = rehydrateCombatant(validCombatant());
+			expect(result).not.toBeNull();
+			expect(result?.name).toBe("Goblin");
+			expect(result?.initiative).toBe(12);
+			expect(result?.ac).toBe(15);
+			expect(result?.maxHp).toBe(7);
+			expect(result?.currentHp).toBe(5);
+			expect(result?.tempHp).toBe(3);
+			expect(result?.conditions).toEqual(["poisoned"]);
+			expect(result?.isConcentrating).toBe(true);
+			expect(result?.creatureId).toBe("creature-goblin");
+			expect(result?.color).toBe("red");
+			expect(result?.icon).toBe("skull");
+			expect(result?.playerCharacterId).toBe("pc-1");
+		});
+
+		it("accepts a minimal combatant (id + name only)", () => {
+			const result = rehydrateCombatant(minimalCombatant());
+			expect(result).not.toBeNull();
+			expect(result?.id).toBe("c-1");
+			expect(result?.name).toBe("Goblin");
+			expect(result?.initiative).toBeUndefined();
+			expect(result?.ac).toBeUndefined();
+			expect(result?.maxHp).toBeUndefined();
+		});
+
+		it("preserves branded CombatantId", () => {
+			const result = rehydrateCombatant(minimalCombatant());
+			expect(result?.id).toBe("c-1");
+		});
+	});
+
+	describe("required field rejection", () => {
+		it.each([
+			null,
+			42,
+			"string",
+			[1, 2],
+			undefined,
+		])("rejects non-object input: %j", (input) => {
+			expect(rehydrateCombatant(input)).toBeNull();
+		});
+
+		it("rejects missing id", () => {
+			const { id: _, ...rest } = minimalCombatant();
+			expect(rehydrateCombatant(rest)).toBeNull();
+		});
+
+		it("rejects empty id", () => {
+			expect(rehydrateCombatant({ ...minimalCombatant(), id: "" })).toBeNull();
+		});
+
+		it("rejects missing name", () => {
+			const { name: _, ...rest } = minimalCombatant();
+			expect(rehydrateCombatant(rest)).toBeNull();
+		});
+
+		it("rejects non-string name", () => {
+			expect(
+				rehydrateCombatant({ ...minimalCombatant(), name: 42 }),
+			).toBeNull();
+			expect(
+				rehydrateCombatant({ ...minimalCombatant(), name: null }),
+			).toBeNull();
+		});
+	});
+
+	describe("optional field leniency", () => {
+		it("drops invalid ac — keeps combatant", () => {
+			for (const ac of [-1, 1.5, "15"]) {
+				const result = rehydrateCombatant({ ...minimalCombatant(), ac });
+				expect(result).not.toBeNull();
+				expect(result?.ac).toBeUndefined();
+			}
+		});
+
+		it("drops invalid maxHp — keeps combatant", () => {
+			for (const maxHp of [0, 1.5, "7"]) {
+				const result = rehydrateCombatant({ ...minimalCombatant(), maxHp });
+				expect(result).not.toBeNull();
+				expect(result?.maxHp).toBeUndefined();
+			}
+		});
+
+		it("falls back currentHp to maxHp when currentHp invalid", () => {
+			const result = rehydrateCombatant({
+				...minimalCombatant(),
+				maxHp: 10,
+				currentHp: "bad",
+			});
+			expect(result?.maxHp).toBe(10);
+			expect(result?.currentHp).toBe(10);
+		});
+
+		it("falls back currentHp to maxHp when currentHp > maxHp", () => {
+			const result = rehydrateCombatant({
+				...minimalCombatant(),
+				maxHp: 10,
+				currentHp: 15,
+			});
+			expect(result?.maxHp).toBe(10);
+			expect(result?.currentHp).toBe(10);
+		});
+
+		it("drops invalid initiative — keeps combatant", () => {
+			for (const initiative of [1.5, "12"]) {
+				const result = rehydrateCombatant({
+					...minimalCombatant(),
+					initiative,
+				});
+				expect(result).not.toBeNull();
+				expect(result?.initiative).toBeUndefined();
+			}
+		});
+
+		it("drops invalid conditions — keeps combatant", () => {
+			const result = rehydrateCombatant({
+				...minimalCombatant(),
+				conditions: "poisoned",
+			});
+			expect(result).not.toBeNull();
+			expect(result?.conditions).toBeUndefined();
+		});
+
+		it("drops unknown condition IDs", () => {
+			const result = rehydrateCombatant({
+				...minimalCombatant(),
+				conditions: ["fake-condition"],
+			});
+			expect(result).not.toBeNull();
+			expect(result?.conditions).toBeUndefined();
+		});
+
+		it("filters valid conditions from mixed array", () => {
+			const result = rehydrateCombatant({
+				...minimalCombatant(),
+				conditions: ["poisoned", "fake", "blinded"],
+			});
+			expect(result?.conditions).toEqual(["poisoned", "blinded"]);
+		});
+
+		it("drops invalid color — keeps combatant", () => {
+			const result = rehydrateCombatant({
+				...minimalCombatant(),
+				color: "neon",
+			});
+			expect(result).not.toBeNull();
+			expect(result?.color).toBeUndefined();
+		});
+
+		it("drops invalid icon — keeps combatant", () => {
+			const result = rehydrateCombatant({
+				...minimalCombatant(),
+				icon: "rocket",
+			});
+			expect(result).not.toBeNull();
+			expect(result?.icon).toBeUndefined();
+		});
+
+		it("drops isConcentrating when not strictly true", () => {
+			for (const isConcentrating of [false, "true", 1]) {
+				const result = rehydrateCombatant({
+					...minimalCombatant(),
+					isConcentrating,
+				});
+				expect(result).not.toBeNull();
+				expect(result?.isConcentrating).toBeUndefined();
+			}
+		});
+
+		it("drops invalid creatureId", () => {
+			for (const creatureId of ["", 42]) {
+				const result = rehydrateCombatant({
+					...minimalCombatant(),
+					creatureId,
+				});
+				expect(result).not.toBeNull();
+				expect(result?.creatureId).toBeUndefined();
+			}
+		});
+
+		it("drops invalid playerCharacterId", () => {
+			for (const playerCharacterId of ["", 42]) {
+				const result = rehydrateCombatant({
+					...minimalCombatant(),
+					playerCharacterId,
+				});
+				expect(result).not.toBeNull();
+				expect(result?.playerCharacterId).toBeUndefined();
+			}
+		});
+
+		it("drops invalid tempHp — keeps combatant", () => {
+			for (const tempHp of [-1, 1.5, "3"]) {
+				const result = rehydrateCombatant({
+					...minimalCombatant(),
+					tempHp,
+				});
+				expect(result).not.toBeNull();
+				expect(result?.tempHp).toBeUndefined();
+			}
+		});
+
+		it("preserves valid tempHp of 0", () => {
+			const result = rehydrateCombatant({
+				...minimalCombatant(),
+				tempHp: 0,
+			});
+			expect(result?.tempHp).toBe(0);
+		});
+	});
+});

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

@@ -0,0 +1,136 @@
+import { describe, expect, it } from "vitest";
+import { rehydratePlayerCharacter } from "../rehydrate-player-character.js";
+
+function validPc(overrides: Record<string, unknown> = {}) {
+	return {
+		id: "pc-1",
+		name: "Aria",
+		ac: 16,
+		maxHp: 45,
+		color: "blue",
+		icon: "sword",
+		level: 5,
+		...overrides,
+	};
+}
+
+describe("rehydratePlayerCharacter", () => {
+	describe("valid input", () => {
+		it("accepts a valid PC with all fields", () => {
+			const result = rehydratePlayerCharacter(validPc());
+			expect(result).not.toBeNull();
+			expect(result?.name).toBe("Aria");
+			expect(result?.ac).toBe(16);
+			expect(result?.maxHp).toBe(45);
+			expect(result?.color).toBe("blue");
+			expect(result?.icon).toBe("sword");
+			expect(result?.level).toBe(5);
+		});
+
+		it("accepts a valid PC without optional color/icon/level", () => {
+			const result = rehydratePlayerCharacter(
+				validPc({ color: undefined, icon: undefined, level: undefined }),
+			);
+			expect(result).not.toBeNull();
+			expect(result?.color).toBeUndefined();
+			expect(result?.icon).toBeUndefined();
+			expect(result?.level).toBeUndefined();
+		});
+
+		it("preserves branded PlayerCharacterId", () => {
+			const result = rehydratePlayerCharacter(validPc());
+			expect(result?.id).toBe("pc-1");
+		});
+	});
+
+	describe("required field rejection", () => {
+		it.each([
+			null,
+			42,
+			"string",
+			[1, 2],
+			undefined,
+		])("rejects non-object input: %j", (input) => {
+			expect(rehydratePlayerCharacter(input)).toBeNull();
+		});
+
+		it("rejects missing id", () => {
+			const { id: _, ...rest } = validPc();
+			expect(rehydratePlayerCharacter(rest)).toBeNull();
+		});
+
+		it("rejects empty id", () => {
+			expect(rehydratePlayerCharacter(validPc({ id: "" }))).toBeNull();
+		});
+
+		it("rejects missing name", () => {
+			const { name: _, ...rest } = validPc();
+			expect(rehydratePlayerCharacter(rest)).toBeNull();
+		});
+
+		it("rejects empty/whitespace name", () => {
+			expect(rehydratePlayerCharacter(validPc({ name: "" }))).toBeNull();
+			expect(rehydratePlayerCharacter(validPc({ name: "   " }))).toBeNull();
+		});
+
+		it("rejects missing ac", () => {
+			const { ac: _, ...rest } = validPc();
+			expect(rehydratePlayerCharacter(rest)).toBeNull();
+		});
+
+		it("rejects negative ac", () => {
+			expect(rehydratePlayerCharacter(validPc({ ac: -1 }))).toBeNull();
+		});
+
+		it("rejects float ac", () => {
+			expect(rehydratePlayerCharacter(validPc({ ac: 1.5 }))).toBeNull();
+		});
+
+		it("rejects string ac", () => {
+			expect(rehydratePlayerCharacter(validPc({ ac: "16" }))).toBeNull();
+		});
+
+		it("rejects missing maxHp", () => {
+			const { maxHp: _, ...rest } = validPc();
+			expect(rehydratePlayerCharacter(rest)).toBeNull();
+		});
+
+		it("rejects maxHp of 0", () => {
+			expect(rehydratePlayerCharacter(validPc({ maxHp: 0 }))).toBeNull();
+		});
+
+		it("rejects float maxHp", () => {
+			expect(rehydratePlayerCharacter(validPc({ maxHp: 1.5 }))).toBeNull();
+		});
+
+		it("rejects string maxHp", () => {
+			expect(rehydratePlayerCharacter(validPc({ maxHp: "45" }))).toBeNull();
+		});
+	});
+
+	describe("optional field rejection (strict)", () => {
+		it("rejects invalid color", () => {
+			expect(rehydratePlayerCharacter(validPc({ color: "neon" }))).toBeNull();
+		});
+
+		it("rejects invalid icon", () => {
+			expect(rehydratePlayerCharacter(validPc({ icon: "rocket" }))).toBeNull();
+		});
+
+		it("rejects level 0", () => {
+			expect(rehydratePlayerCharacter(validPc({ level: 0 }))).toBeNull();
+		});
+
+		it("rejects level 21", () => {
+			expect(rehydratePlayerCharacter(validPc({ level: 21 }))).toBeNull();
+		});
+
+		it("rejects float level", () => {
+			expect(rehydratePlayerCharacter(validPc({ level: 3.5 }))).toBeNull();
+		});
+
+		it("rejects string level", () => {
+			expect(rehydratePlayerCharacter(validPc({ level: "5" }))).toBeNull();
+		});
+	});
+});

packages/domain/src/__tests__/undo-redo.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import type { Encounter } from "../types.js";
+import { isDomainError } from "../types.js";
+import {
+	clearHistory,
+	EMPTY_UNDO_REDO_STATE,
+	pushUndo,
+	redo,
+	undo,
+} from "../undo-redo.js";
+
+function enc(roundNumber = 1, activeIndex = 0): Encounter {
+	return { combatants: [], activeIndex, roundNumber };
+}
+
+describe("pushUndo", () => {
+	it("adds a snapshot to the undo stack", () => {
+		const result = pushUndo(EMPTY_UNDO_REDO_STATE, enc(1));
+		expect(result.undoStack).toHaveLength(1);
+		expect(result.undoStack[0]).toEqual(enc(1));
+	});
+
+	it("clears the redo stack", () => {
+		const state = {
+			undoStack: [enc(1)],
+			redoStack: [enc(2)],
+		};
+		const result = pushUndo(state, enc(3));
+		expect(result.redoStack).toHaveLength(0);
+	});
+
+	it("caps the undo stack at 50, dropping the oldest", () => {
+		const undoStack = Array.from({ length: 50 }, (_, i) => enc(i + 1));
+		const state = { undoStack, redoStack: [] };
+		const result = pushUndo(state, enc(51));
+		expect(result.undoStack).toHaveLength(50);
+		expect(result.undoStack[0]).toEqual(enc(2));
+		expect(result.undoStack[49]).toEqual(enc(51));
+	});
+});
+
+describe("undo", () => {
+	it("pops from undo stack and pushes current to redo stack", () => {
+		const state = { undoStack: [enc(1)], redoStack: [] };
+		const result = undo(state, enc(2));
+		expect(isDomainError(result)).toBe(false);
+		if (isDomainError(result)) return;
+		expect(result.encounter).toEqual(enc(1));
+		expect(result.state.undoStack).toHaveLength(0);
+		expect(result.state.redoStack).toEqual([enc(2)]);
+	});
+
+	it("returns domain error when undo stack is empty", () => {
+		const result = undo(EMPTY_UNDO_REDO_STATE, enc(1));
+		expect(isDomainError(result)).toBe(true);
+		if (!isDomainError(result)) return;
+		expect(result.code).toBe("nothing-to-undo");
+	});
+
+	it("pops the most recent entry (last in stack)", () => {
+		const state = { undoStack: [enc(1), enc(2), enc(3)], redoStack: [] };
+		const result = undo(state, enc(4));
+		expect(isDomainError(result)).toBe(false);
+		if (isDomainError(result)) return;
+		expect(result.encounter).toEqual(enc(3));
+		expect(result.state.undoStack).toEqual([enc(1), enc(2)]);
+	});
+});
+
+describe("redo", () => {
+	it("pops from redo stack and pushes current to undo stack", () => {
+		const state = { undoStack: [], redoStack: [enc(1)] };
+		const result = redo(state, enc(2));
+		expect(isDomainError(result)).toBe(false);
+		if (isDomainError(result)) return;
+		expect(result.encounter).toEqual(enc(1));
+		expect(result.state.redoStack).toHaveLength(0);
+		expect(result.state.undoStack).toEqual([enc(2)]);
+	});
+
+	it("returns domain error when redo stack is empty", () => {
+		const result = redo(EMPTY_UNDO_REDO_STATE, enc(1));
+		expect(isDomainError(result)).toBe(true);
+		if (!isDomainError(result)) return;
+		expect(result.code).toBe("nothing-to-redo");
+	});
+
+	it("pops the most recent entry (last in stack)", () => {
+		const state = { undoStack: [], redoStack: [enc(1), enc(2), enc(3)] };
+		const result = redo(state, enc(4));
+		expect(isDomainError(result)).toBe(false);
+		if (isDomainError(result)) return;
+		expect(result.encounter).toEqual(enc(3));
+		expect(result.state.redoStack).toEqual([enc(1), enc(2)]);
+	});
+});
+
+describe("undo-then-redo roundtrip", () => {
+	it("returns the exact same encounter after undo then redo", () => {
+		const original = enc(5);
+		const current = enc(6);
+		const afterPush = pushUndo(EMPTY_UNDO_REDO_STATE, original);
+
+		const undoResult = undo(afterPush, current);
+		expect(isDomainError(undoResult)).toBe(false);
+		if (isDomainError(undoResult)) return;
+
+		expect(undoResult.encounter).toEqual(original);
+
+		const redoResult = redo(undoResult.state, undoResult.encounter);
+		expect(isDomainError(redoResult)).toBe(false);
+		if (isDomainError(redoResult)) return;
+
+		expect(redoResult.encounter).toEqual(current);
+	});
+});
+
+describe("clearHistory", () => {
+	it("empties both stacks", () => {
+		const result = clearHistory();
+		expect(result.undoStack).toHaveLength(0);
+		expect(result.redoStack).toHaveLength(0);
+	});
+});

packages/domain/src/add-combatant.ts

@@ -1,24 +1,94 @@
+import type { CreatureId } from "./creature-types.js";
 import type { DomainEvent } from "./events.js";
-import type { CombatantId, DomainError, Encounter } from "./types.js";
+import { sortByInitiative } from "./initiative-sort.js";
+import type { PlayerCharacterId } from "./player-character-types.js";
+import type {
+	Combatant,
+	CombatantId,
+	DomainError,
+	Encounter,
+} from "./types.js";
+
+export interface CombatantInit {
+	readonly maxHp?: number;
+	readonly ac?: number;
+	readonly initiative?: number;
+	readonly creatureId?: CreatureId;
+	readonly color?: string;
+	readonly icon?: string;
+	readonly playerCharacterId?: PlayerCharacterId;
+}
 
 export interface AddCombatantSuccess {
 	readonly encounter: Encounter;
 	readonly events: DomainEvent[];
 }
 
+function validateInit(init: CombatantInit): DomainError | undefined {
+	if (
+		init.maxHp !== undefined &&
+		(!Number.isInteger(init.maxHp) || init.maxHp < 1)
+	) {
+		return {
+			kind: "domain-error",
+			code: "invalid-max-hp",
+			message: `Max HP must be a positive integer, got ${init.maxHp}`,
+		};
+	}
+	if (init.ac !== undefined && (!Number.isInteger(init.ac) || init.ac < 0)) {
+		return {
+			kind: "domain-error",
+			code: "invalid-ac",
+			message: `AC must be a non-negative integer, got ${init.ac}`,
+		};
+	}
+	if (init.initiative !== undefined && !Number.isInteger(init.initiative)) {
+		return {
+			kind: "domain-error",
+			code: "invalid-initiative",
+			message: `Initiative must be an integer, got ${init.initiative}`,
+		};
+	}
+	return undefined;
+}
+
+function buildCombatant(
+	id: CombatantId,
+	name: string,
+	init?: CombatantInit,
+): Combatant {
+	return {
+		id,
+		name,
+		...(init?.maxHp !== undefined && {
+			maxHp: init.maxHp,
+			currentHp: init.maxHp,
+		}),
+		...(init?.ac !== undefined && { ac: init.ac }),
+		...(init?.initiative !== undefined && { initiative: init.initiative }),
+		...(init?.creatureId !== undefined && { creatureId: init.creatureId }),
+		...(init?.color !== undefined && { color: init.color }),
+		...(init?.icon !== undefined && { icon: init.icon }),
+		...(init?.playerCharacterId !== undefined && {
+			playerCharacterId: init.playerCharacterId,
+		}),
+	};
+}
+
 /**
  * Pure function that adds a combatant to the end of an encounter's list.
  *
  * FR-001: Accepts an Encounter, CombatantId, and name; returns next state + events.
  * FR-002: Appends new combatant to end of combatants list.
  * FR-004: Rejects empty/whitespace-only names with DomainError.
- * FR-005: Does not alter activeIndex or roundNumber.
+ * FR-005: Does not alter activeIndex or roundNumber (unless initiative triggers sort).
  * FR-006: Events returned as values, not dispatched via side effects.
  */
 export function addCombatant(
 	encounter: Encounter,
 	id: CombatantId,
 	name: string,
+	init?: CombatantInit,
 ): AddCombatantSuccess | DomainError {
 	const trimmed = name.trim();
 
@@ -30,12 +100,35 @@ export function addCombatant(
 		};
 	}
 
-	const position = encounter.combatants.length;
+	if (init) {
+		const error = validateInit(init);
+		if (error) return error;
+	}
+
+	const newCombatant = buildCombatant(id, trimmed, init);
+	let combatants: readonly Combatant[] = [
+		...encounter.combatants,
+		newCombatant,
+	];
+	let activeIndex = encounter.activeIndex;
+
+	if (init?.initiative !== undefined) {
+		const activeCombatantId =
+			encounter.combatants.length > 0
+				? encounter.combatants[encounter.activeIndex].id
+				: id;
+
+		const result = sortByInitiative(combatants, activeCombatantId);
+		combatants = result.sorted;
+		activeIndex = result.activeIndex;
+	}
+
+	const position = combatants.findIndex((c) => c.id === id);
 
 	return {
 		encounter: {
-			combatants: [...encounter.combatants, { id, name: trimmed }],
-			activeIndex: encounter.activeIndex,
+			combatants,
+			activeIndex,
 			roundNumber: encounter.roundNumber,
 		},
 		events: [
@@ -44,6 +137,7 @@ export function addCombatant(
 				combatantId: id,
 				name: trimmed,
 				position,
+				init,
 			},
 		],
 	};

packages/domain/src/adjust-hp.ts

@@ -1,5 +1,11 @@
 import type { DomainEvent } from "./events.js";
-import type { CombatantId, DomainError, Encounter } from "./types.js";
+import {
+	type CombatantId,
+	type DomainError,
+	type Encounter,
+	findCombatant,
+	isDomainError,
+} from "./types.js";
 
 export interface AdjustHpSuccess {
 	readonly encounter: Encounter;
@@ -17,17 +23,9 @@ export function adjustHp(
 	combatantId: CombatantId,
 	delta: number,
 ): AdjustHpSuccess | DomainError {
-	const targetIdx = encounter.combatants.findIndex((c) => c.id === combatantId);
-
-	if (targetIdx === -1) {
-		return {
-			kind: "domain-error",
-			code: "combatant-not-found",
-			message: `No combatant found with ID "${combatantId}"`,
-		};
-	}
-
-	const target = encounter.combatants[targetIdx];
+	const found = findCombatant(encounter, combatantId);
+	if (isDomainError(found)) return found;
+	const { combatant: target } = found;
 
 	if (target.maxHp === undefined || target.currentHp === undefined) {
 		return {

packages/domain/src/conditions.ts

@@ -12,6 +12,8 @@ export type ConditionId =
 	| "poisoned"
 	| "prone"
 	| "restrained"
+	| "sapped"
+	| "slowed"
 	| "stunned"
 	| "unconscious";
 
@@ -24,6 +26,8 @@ export interface ConditionDefinition {
 	readonly description5e: string;
 	readonly iconName: string;
 	readonly color: string;
+	/** When set, the condition only appears in this edition's picker. */
+	readonly edition?: RulesEdition;
 }
 
 export function getConditionDescription(
@@ -159,6 +163,26 @@ export const CONDITION_DEFINITIONS: readonly ConditionDefinition[] = [
 		iconName: "Link",
 		color: "neutral",
 	},
+	{
+		id: "sapped",
+		label: "Sapped",
+		description:
+			"Disadvantage on next attack roll before the start of your next turn. (Weapon Mastery: Sap)",
+		description5e: "",
+		iconName: "ShieldMinus",
+		color: "amber",
+		edition: "5.5e",
+	},
+	{
+		id: "slowed",
+		label: "Slowed",
+		description:
+			"Speed reduced by 10 ft. until the start of your next turn. (Weapon Mastery: Slow)",
+		description5e: "",
+		iconName: "Snail",
+		color: "sky",
+		edition: "5.5e",
+	},
 	{
 		id: "stunned",
 		label: "Stunned",
@@ -184,3 +208,11 @@ export const CONDITION_DEFINITIONS: readonly ConditionDefinition[] = [
 export const VALID_CONDITION_IDS: ReadonlySet<string> = new Set(
 	CONDITION_DEFINITIONS.map((d) => d.id),
 );
+
+export function getConditionsForEdition(
+	edition: RulesEdition,
+): readonly ConditionDefinition[] {
+	return CONDITION_DEFINITIONS.filter(
+		(d) => d.edition === undefined || d.edition === edition,
+	);
+}

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

@@ -22,6 +22,7 @@ export function createPlayerCharacter(
 	maxHp: number,
 	color: string | undefined,
 	icon: string | undefined,
+	level?: number,
 ): CreatePlayerCharacterSuccess | DomainError {
 	const trimmed = name.trim();
 
@@ -65,6 +66,17 @@ export function createPlayerCharacter(
 		};
 	}
 
+	if (
+		level !== undefined &&
+		(!Number.isInteger(level) || level < 1 || level > 20)
+	) {
+		return {
+			kind: "domain-error",
+			code: "invalid-level",
+			message: "Level must be an integer between 1 and 20",
+		};
+	}
+
 	const newCharacter: PlayerCharacter = {
 		id,
 		name: trimmed,
@@ -72,6 +84,7 @@ export function createPlayerCharacter(
 		maxHp,
 		color: color as PlayerCharacter["color"],
 		icon: icon as PlayerCharacter["icon"],
+		level,
 	};
 
 	return {

packages/domain/src/edit-combatant.ts

@@ -1,5 +1,11 @@
 import type { DomainEvent } from "./events.js";
-import type { CombatantId, DomainError, Encounter } from "./types.js";
+import {
+	type CombatantId,
+	type DomainError,
+	type Encounter,
+	findCombatant,
+	isDomainError,
+} from "./types.js";
 
 export interface EditCombatantSuccess {
 	readonly encounter: Encounter;
@@ -30,17 +36,9 @@ export function editCombatant(
 		};
 	}
 
-	const index = encounter.combatants.findIndex((c) => c.id === id);
-
-	if (index === -1) {
-		return {
-			kind: "domain-error",
-			code: "combatant-not-found",
-			message: `No combatant found with ID "${id}"`,
-		};
-	}
-
-	const oldName = encounter.combatants[index].name;
+	const found = findCombatant(encounter, id);
+	if (isDomainError(found)) return found;
+	const oldName = found.combatant.name;
 
 	return {
 		encounter: {

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

@@ -20,6 +20,7 @@ interface EditFields {
 	readonly maxHp?: number;
 	readonly color?: string | null;
 	readonly icon?: string | null;
+	readonly level?: number | null;
 }
 
 function validateFields(fields: EditFields): DomainError | null {
@@ -72,6 +73,17 @@ function validateFields(fields: EditFields): DomainError | null {
 			message: `Invalid icon: ${fields.icon}`,
 		};
 	}
+	if (
+		fields.level !== undefined &&
+		fields.level !== null &&
+		(!Number.isInteger(fields.level) || fields.level < 1 || fields.level > 20)
+	) {
+		return {
+			kind: "domain-error",
+			code: "invalid-level",
+			message: "Level must be an integer between 1 and 20",
+		};
+	}
 	return null;
 }
 
@@ -92,6 +104,8 @@ function applyFields(
 			fields.icon === undefined
 				? existing.icon
 				: ((fields.icon as PlayerCharacter["icon"]) ?? undefined),
+		level:
+			fields.level === undefined ? existing.level : (fields.level ?? undefined),
 	};
 }
 
@@ -120,7 +134,8 @@ export function editPlayerCharacter(
 		updated.ac === existing.ac &&
 		updated.maxHp === existing.maxHp &&
 		updated.color === existing.color &&
-		updated.icon === existing.icon
+		updated.icon === existing.icon &&
+		updated.level === existing.level
 	) {
 		return {
 			kind: "domain-error",

packages/domain/src/encounter-difficulty.ts

@@ -0,0 +1,126 @@
+export type DifficultyTier = "trivial" | "low" | "moderate" | "high";
+
+export interface DifficultyResult {
+	readonly tier: DifficultyTier;
+	readonly totalMonsterXp: number;
+	readonly partyBudget: {
+		readonly low: number;
+		readonly moderate: number;
+		readonly high: number;
+	};
+}
+
+/** Maps challenge rating strings to XP values (standard 5e). */
+const CR_TO_XP: Readonly<Record<string, number>> = {
+	"0": 0,
+	"1/8": 25,
+	"1/4": 50,
+	"1/2": 100,
+	"1": 200,
+	"2": 450,
+	"3": 700,
+	"4": 1100,
+	"5": 1800,
+	"6": 2300,
+	"7": 2900,
+	"8": 3900,
+	"9": 5000,
+	"10": 5900,
+	"11": 7200,
+	"12": 8400,
+	"13": 10000,
+	"14": 11500,
+	"15": 13000,
+	"16": 15000,
+	"17": 18000,
+	"18": 20000,
+	"19": 22000,
+	"20": 25000,
+	"21": 33000,
+	"22": 41000,
+	"23": 50000,
+	"24": 62000,
+	"25": 75000,
+	"26": 90000,
+	"27": 105000,
+	"28": 120000,
+	"29": 135000,
+	"30": 155000,
+};
+
+/** Maps character level (1-20) to XP budget thresholds (2024 5.5e DMG). */
+const XP_BUDGET_PER_CHARACTER: Readonly<
+	Record<number, { low: number; moderate: number; high: number }>
+> = {
+	1: { low: 50, moderate: 75, high: 100 },
+	2: { low: 100, moderate: 150, high: 200 },
+	3: { low: 150, moderate: 225, high: 400 },
+	4: { low: 250, moderate: 375, high: 500 },
+	5: { low: 500, moderate: 750, high: 1100 },
+	6: { low: 600, moderate: 1000, high: 1400 },
+	7: { low: 750, moderate: 1300, high: 1700 },
+	8: { low: 1000, moderate: 1700, high: 2100 },
+	9: { low: 1300, moderate: 2000, high: 2600 },
+	10: { low: 1600, moderate: 2300, high: 3100 },
+	11: { low: 1900, moderate: 2900, high: 4100 },
+	12: { low: 2200, moderate: 3700, high: 4700 },
+	13: { low: 2600, moderate: 4200, high: 5400 },
+	14: { low: 2900, moderate: 4900, high: 6200 },
+	15: { low: 3300, moderate: 5400, high: 7800 },
+	16: { low: 3800, moderate: 6100, high: 9800 },
+	17: { low: 4500, moderate: 7200, high: 11700 },
+	18: { low: 5000, moderate: 8700, high: 14200 },
+	19: { low: 5500, moderate: 10700, high: 17200 },
+	20: { low: 6400, moderate: 13200, high: 22000 },
+};
+
+/** Returns the XP value for a given CR string. Returns 0 for unknown CRs. */
+export function crToXp(cr: string): number {
+	return CR_TO_XP[cr] ?? 0;
+}
+
+/**
+ * Calculates encounter difficulty from party levels and monster CRs.
+ * Both arrays should be pre-filtered (only PCs with levels, only bestiary-linked monsters).
+ */
+export function calculateEncounterDifficulty(
+	partyLevels: readonly number[],
+	monsterCrs: readonly string[],
+): DifficultyResult {
+	let budgetLow = 0;
+	let budgetModerate = 0;
+	let budgetHigh = 0;
+
+	for (const level of partyLevels) {
+		const budget = XP_BUDGET_PER_CHARACTER[level];
+		if (budget) {
+			budgetLow += budget.low;
+			budgetModerate += budget.moderate;
+			budgetHigh += budget.high;
+		}
+	}
+
+	let totalMonsterXp = 0;
+	for (const cr of monsterCrs) {
+		totalMonsterXp += crToXp(cr);
+	}
+
+	let tier: DifficultyTier = "trivial";
+	if (totalMonsterXp >= budgetHigh) {
+		tier = "high";
+	} else if (totalMonsterXp >= budgetModerate) {
+		tier = "moderate";
+	} else if (totalMonsterXp >= budgetLow) {
+		tier = "low";
+	}
+
+	return {
+		tier,
+		totalMonsterXp,
+		partyBudget: {
+			low: budgetLow,
+			moderate: budgetModerate,
+			high: budgetHigh,
+		},
+	};
+}

packages/domain/src/events.ts

@@ -1,4 +1,5 @@
 import type { ConditionId } from "./conditions.js";
+import type { CreatureId } from "./creature-types.js";
 import type { PlayerCharacterId } from "./player-character-types.js";
 import type { CombatantId } from "./types.js";
 
@@ -19,6 +20,15 @@ export interface CombatantAdded {
 	readonly combatantId: CombatantId;
 	readonly name: string;
 	readonly position: number;
+	readonly init?: {
+		readonly maxHp?: number;
+		readonly ac?: number;
+		readonly initiative?: number;
+		readonly creatureId?: CreatureId;
+		readonly color?: string;
+		readonly icon?: string;
+		readonly playerCharacterId?: PlayerCharacterId;
+	};
 }
 
 export interface CombatantRemoved {

packages/domain/src/export-bundle.ts

@@ -0,0 +1,11 @@
+import type { PlayerCharacter } from "./player-character-types.js";
+import type { Encounter } from "./types.js";
+
+export interface ExportBundle {
+	readonly version: number;
+	readonly exportedAt: string;
+	readonly encounter: Encounter;
+	readonly undoStack: readonly Encounter[];
+	readonly redoStack: readonly Encounter[];
+	readonly playerCharacters: readonly PlayerCharacter[];
+}

packages/domain/src/index.ts

@@ -1,4 +1,8 @@
-export { type AddCombatantSuccess, addCombatant } from "./add-combatant.js";
+export {
+	type AddCombatantSuccess,
+	addCombatant,
+	type CombatantInit,
+} from "./add-combatant.js";
 export { type AdjustHpSuccess, adjustHp } from "./adjust-hp.js";
 export { advanceTurn } from "./advance-turn.js";
 export { resolveCreatureName } from "./auto-number.js";
@@ -11,6 +15,7 @@ export {
 	type ConditionDefinition,
 	type ConditionId,
 	getConditionDescription,
+	getConditionsForEdition,
 	type RulesEdition,
 	VALID_CONDITION_IDS,
 } from "./conditions.js";
@@ -43,6 +48,12 @@ export {
 	type EditPlayerCharacterSuccess,
 	editPlayerCharacter,
 } from "./edit-player-character.js";
+export {
+	calculateEncounterDifficulty,
+	crToXp,
+	type DifficultyResult,
+	type DifficultyTier,
+} from "./encounter-difficulty.js";
 export type {
 	AcSet,
 	CombatantAdded,
@@ -66,6 +77,7 @@ export type {
 	TurnAdvanced,
 	TurnRetreated,
 } from "./events.js";
+export type { ExportBundle } from "./export-bundle.js";
 export { deriveHpStatus, type HpStatus } from "./hp-status.js";
 export {
 	calculateInitiative,
@@ -82,6 +94,8 @@ export {
 	VALID_PLAYER_COLORS,
 	VALID_PLAYER_ICONS,
 } from "./player-character-types.js";
+export { rehydrateCombatant } from "./rehydrate-combatant.js";
+export { rehydratePlayerCharacter } from "./rehydrate-player-character.js";
 export {
 	type RemoveCombatantSuccess,
 	removeCombatant,
@@ -114,5 +128,14 @@ export {
 	createEncounter,
 	type DomainError,
 	type Encounter,
+	findCombatant,
 	isDomainError,
 } from "./types.js";
+export {
+	clearHistory,
+	EMPTY_UNDO_REDO_STATE,
+	pushUndo,
+	redo,
+	type UndoRedoState,
+	undo,
+} from "./undo-redo.js";

packages/domain/src/initiative-sort.ts

@@ -0,0 +1,35 @@
+import type { Combatant, CombatantId } from "./types.js";
+
+interface Indexed {
+	readonly c: Combatant;
+	readonly i: number;
+}
+
+function compareByInitiative(a: Indexed, b: Indexed): number {
+	const aHas = a.c.initiative !== undefined;
+	const bHas = b.c.initiative !== undefined;
+	if (aHas && bHas) {
+		const diff = b.c.initiative - a.c.initiative;
+		return diff === 0 ? a.i - b.i : diff;
+	}
+	if (aHas && !bHas) return -1;
+	if (!aHas && bHas) return 1;
+	return a.i - b.i;
+}
+
+/**
+ * Stable-sorts combatants by initiative (descending), preserving relative
+ * order for ties and for combatants without initiative. Returns the sorted
+ * list and the new activeIndex that tracks the given active combatant
+ * through the reorder.
+ */
+export function sortByInitiative(
+	combatants: readonly Combatant[],
+	activeCombatantId: CombatantId,
+): { sorted: readonly Combatant[]; activeIndex: number } {
+	const indexed = combatants.map((c, i) => ({ c, i }));
+	indexed.sort(compareByInitiative);
+	const sorted = indexed.map(({ c }) => c);
+	const idx = sorted.findIndex((c) => c.id === activeCombatantId);
+	return { sorted, activeIndex: idx === -1 ? 0 : idx };
+}

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

@@ -74,6 +74,7 @@ export interface PlayerCharacter {
 	readonly maxHp: number;
 	readonly color?: PlayerColor;
 	readonly icon?: PlayerIcon;
+	readonly level?: number;
 }
 
 export interface PlayerCharacterList {

packages/domain/src/rehydrate-combatant.ts

@@ -0,0 +1,106 @@
+import type { ConditionId } from "./conditions.js";
+import { VALID_CONDITION_IDS } from "./conditions.js";
+import { creatureId } from "./creature-types.js";
+import {
+	playerCharacterId,
+	VALID_PLAYER_COLORS,
+	VALID_PLAYER_ICONS,
+} from "./player-character-types.js";
+import type { Combatant } from "./types.js";
+import { combatantId } from "./types.js";
+
+function validateAc(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0
+		? value
+		: undefined;
+}
+
+function validateConditions(value: unknown): ConditionId[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	const valid = value.filter(
+		(v): v is ConditionId =>
+			typeof v === "string" && VALID_CONDITION_IDS.has(v),
+	);
+	return valid.length > 0 ? valid : undefined;
+}
+
+function validateHp(
+	rawMaxHp: unknown,
+	rawCurrentHp: unknown,
+): { maxHp: number; currentHp: number } | undefined {
+	if (
+		typeof rawMaxHp !== "number" ||
+		!Number.isInteger(rawMaxHp) ||
+		rawMaxHp < 1
+	) {
+		return undefined;
+	}
+	const validCurrentHp =
+		typeof rawCurrentHp === "number" &&
+		Number.isInteger(rawCurrentHp) &&
+		rawCurrentHp >= 0 &&
+		rawCurrentHp <= rawMaxHp;
+	return {
+		maxHp: rawMaxHp,
+		currentHp: validCurrentHp ? rawCurrentHp : rawMaxHp,
+	};
+}
+
+function validateTempHp(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0
+		? value
+		: undefined;
+}
+
+function validateInteger(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value)
+		? value
+		: undefined;
+}
+
+function validateSetMember(
+	value: unknown,
+	valid: ReadonlySet<string>,
+): string | undefined {
+	return typeof value === "string" && valid.has(value) ? value : undefined;
+}
+
+function validateNonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function parseOptionalFields(entry: Record<string, unknown>) {
+	return {
+		initiative: validateInteger(entry.initiative),
+		ac: validateAc(entry.ac),
+		conditions: validateConditions(entry.conditions),
+		isConcentrating: entry.isConcentrating === true ? true : undefined,
+		creatureId: validateNonEmptyString(entry.creatureId)
+			? creatureId(entry.creatureId as string)
+			: undefined,
+		color: validateSetMember(entry.color, VALID_PLAYER_COLORS),
+		icon: validateSetMember(entry.icon, VALID_PLAYER_ICONS),
+		playerCharacterId: validateNonEmptyString(entry.playerCharacterId)
+			? playerCharacterId(entry.playerCharacterId as string)
+			: undefined,
+		tempHp: validateTempHp(entry.tempHp),
+	};
+}
+
+export function rehydrateCombatant(raw: unknown): Combatant | null {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+		return null;
+	const entry = raw as Record<string, unknown>;
+
+	if (typeof entry.id !== "string" || entry.id.length === 0) return null;
+	if (typeof entry.name !== "string") return null;
+
+	const shared: Combatant = {
+		id: combatantId(entry.id),
+		name: entry.name,
+		...parseOptionalFields(entry),
+	};
+
+	const hp = validateHp(entry.maxHp, entry.currentHp);
+	return hp ? { ...shared, ...hp } : shared;
+}