Add manual CR assignment and difficulty breakdown panel

Implement issue #21: custom combatants can now have a challenge rating
assigned via a new breakdown panel, opened by tapping the difficulty
indicator. Bestiary-linked combatants show read-only CR with source name;
custom combatants get a CR picker with all standard 5e values. CR persists
across reloads and round-trips through JSON export/import.

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

CLAUDE.md

@@ -70,11 +70,60 @@ docs/agents/               RPI skill artifacts (research reports, plans)
 - **TypeScript strict mode** with `verbatimModuleSyntax`. Use `.js` extensions in relative imports.
 - **Branded types** for identity values (e.g., `CombatantId`). Prefer immutability/`readonly` where practical.
 - **Domain events** are plain data objects with a `type` discriminant — no classes.
-- **Tests** live in `packages/*/src/__tests__/*.test.ts`. Test pure functions directly; map acceptance scenarios from specs to individual `it()` blocks.
+- **Tests** live in `__tests__/` directories adjacent to source. See the Testing section below for conventions on mocking, assertions, and per-layer approach.
 - **Quality gates** are enforced at pre-commit via Lefthook (parallel jobs). No gate may exist only as a CI step or manual process.
 
 For component prop rules, export format compatibility, and ADRs, see [`docs/conventions.md`](docs/conventions.md).
 
+## Testing
+
+### Philosophy
+
+Test **user-visible behavior**, not implementation details. A good test answers "does this feature work?" not "does this internal function get called?"
+
+### Adapter Injection
+
+Adapters (storage, cache, browser APIs) are provided via `AdapterContext`. Production wires real implementations; tests wire in-memory implementations. This means:
+- No `vi.mock()` for adapter or persistence modules
+- Tests control adapter behavior by configuring the in-memory implementation
+- Type changes in adapter interfaces are caught at compile time
+
+### Per-Layer Approach
+
+| Layer | How to test |
+|---|---|
+| Domain (`packages/domain`) | Pure unit tests, no mocks, test invariants and acceptance scenarios |
+| Application (`packages/application`) | Mock port interfaces only, use real domain logic |
+| Hooks (context-wrapped) | Test via `renderHook` with `AllProviders` wrapping in-memory adapters |
+| Hooks (component-specific) | Test through the component that uses them |
+| Components | Render with `AllProviders`, use in-memory adapters, use `userEvent` for interactions |
+
+### Test Data
+
+Use factory functions from `apps/web/src/__tests__/factories/` to construct domain objects. Each factory provides sensible defaults overridden via `Partial<T>`:
+
+```typescript
+import { buildEncounter } from "../../__tests__/factories/build-encounter.js";
+import { buildCombatant } from "../../__tests__/factories/build-combatant.js";
+
+const encounter = buildEncounter({
+  combatants: [buildCombatant({ name: "Goblin" })],
+  activeIndex: 0,
+  roundNumber: 1,
+});
+```
+
+Add new factory files as needed (one per domain type). Don't inline test data construction — use factories so type changes are caught at compile time.
+
+### Anti-Patterns
+
+- **`vi.mock()` for adapters**: Use in-memory adapter implementations via `AdapterContext` instead
+- **Mocking contexts**: Use `AllProviders` and drive state through real hooks instead of `vi.mock("../../contexts/...")`. Exception: context mocks are acceptable when the component under test requires specific state machine states that cannot be reached through adapter configuration alone — document the reason in a comment at the top of the test file.
+- **Stubbing child components**: Render real children; stub only if the child has heavy I/O that can't be mocked at the adapter level
+- **Asserting mock call counts**: Prefer asserting what the user sees (`screen.getByText(...)`) over `expect(mockFn).toHaveBeenCalledWith(...)`
+- **Testing internal state**: Don't assert `result.current.suggestionIndex === 0`; assert the first suggestion is highlighted
+- **Assertion-free tests**: Every `it()` block must contain at least one `expect()`. Tests that render without asserting inflate coverage without catching bugs.
+
 ## Self-Review Checklist
 
 Before finishing a change, consider:

apps/web/src/__tests__/adapters/in-memory-adapters.ts

@@ -0,0 +1,108 @@
+import {
+	type Creature,
+	type CreatureId,
+	EMPTY_UNDO_REDO_STATE,
+	type Encounter,
+	type PlayerCharacter,
+	type UndoRedoState,
+} from "@initiative/domain";
+import type { Adapters } from "../../contexts/adapter-context.js";
+
+export function createTestAdapters(options?: {
+	encounter?: Encounter | null;
+	undoRedoState?: UndoRedoState;
+	playerCharacters?: PlayerCharacter[];
+	creatures?: Map<CreatureId, Creature>;
+	sources?: Map<
+		string,
+		{ displayName: string; creatures: Creature[]; cachedAt: number }
+	>;
+}): Adapters {
+	let storedEncounter = options?.encounter ?? null;
+	let storedUndoRedo = options?.undoRedoState ?? EMPTY_UNDO_REDO_STATE;
+	let storedPCs = options?.playerCharacters ?? [];
+	const sourceStore =
+		options?.sources ??
+		new Map<
+			string,
+			{ displayName: string; creatures: Creature[]; cachedAt: number }
+		>();
+
+	// Pre-populate sourceStore from creatures map if provided
+	if (options?.creatures && !options?.sources) {
+		// No-op: creatures are accessed directly from the map
+	}
+
+	const creatureMap = options?.creatures ?? new Map<CreatureId, Creature>();
+
+	return {
+		encounterPersistence: {
+			load: () => storedEncounter,
+			save: (e) => {
+				storedEncounter = e;
+			},
+		},
+		undoRedoPersistence: {
+			load: () => storedUndoRedo,
+			save: (state) => {
+				storedUndoRedo = state;
+			},
+		},
+		playerCharacterPersistence: {
+			load: () => [...storedPCs],
+			save: (pcs) => {
+				storedPCs = pcs;
+			},
+		},
+		bestiaryCache: {
+			cacheSource(sourceCode, displayName, creatures) {
+				sourceStore.set(sourceCode, {
+					displayName,
+					creatures,
+					cachedAt: Date.now(),
+				});
+				for (const c of creatures) {
+					creatureMap.set(c.id, c);
+				}
+				return Promise.resolve();
+			},
+			isSourceCached(sourceCode) {
+				return Promise.resolve(sourceStore.has(sourceCode));
+			},
+			getCachedSources() {
+				return Promise.resolve(
+					[...sourceStore.entries()].map(([sourceCode, info]) => ({
+						sourceCode,
+						displayName: info.displayName,
+						creatureCount: info.creatures.length,
+						cachedAt: info.cachedAt,
+					})),
+				);
+			},
+			clearSource(sourceCode) {
+				sourceStore.delete(sourceCode);
+				return Promise.resolve();
+			},
+			clearAll() {
+				sourceStore.clear();
+				return Promise.resolve();
+			},
+			loadAllCachedCreatures() {
+				return Promise.resolve(new Map(creatureMap));
+			},
+		},
+		bestiaryIndex: {
+			loadIndex: () => ({ sources: {}, creatures: [] }),
+			getAllSourceCodes: () => [],
+			getDefaultFetchUrl: (sourceCode, baseUrl) => {
+				const filename = `bestiary-${sourceCode.toLowerCase()}.json`;
+				if (baseUrl !== undefined) {
+					const normalized = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+					return `${normalized}${filename}`;
+				}
+				return `https://example.com/${filename}`;
+			},
+			getSourceDisplayName: (sourceCode) => sourceCode,
+		},
+	};
+}

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

@@ -7,34 +7,6 @@ import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 import { App } from "../App.js";
 import { AllProviders } from "./test-providers.js";
 
-// Mock persistence — no localStorage interaction
-vi.mock("../persistence/encounter-storage.js", () => ({
-	loadEncounter: () => null,
-	saveEncounter: () => {},
-}));
-
-vi.mock("../persistence/player-character-storage.js", () => ({
-	loadPlayerCharacters: () => [],
-	savePlayerCharacters: () => {},
-}));
-
-// Mock bestiary — no IndexedDB or JSON index
-vi.mock("../adapters/bestiary-cache.js", () => ({
-	loadAllCachedCreatures: () => Promise.resolve(new Map()),
-	isSourceCached: () => Promise.resolve(false),
-	cacheSource: () => Promise.resolve(),
-	getCachedSources: () => Promise.resolve([]),
-	clearSource: () => Promise.resolve(),
-	clearAll: () => Promise.resolve(),
-}));
-
-vi.mock("../adapters/bestiary-index-adapter.js", () => ({
-	loadBestiaryIndex: () => ({ sources: {}, creatures: [] }),
-	getAllSourceCodes: () => [],
-	getDefaultFetchUrl: () => "",
-	getSourceDisplayName: (code: string) => code,
-}));
-
 // DOM API stubs — jsdom doesn't implement these
 beforeAll(() => {
 	Object.defineProperty(globalThis, "matchMedia", {

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

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

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

@@ -209,6 +209,31 @@ describe("round-trip: export then import", () => {
 		expect(imported.playerCharacters).toEqual(bundle.playerCharacters);
 	});
 
+	it("round-trips a combatant with cr field", () => {
+		const encounterWithCr: Encounter = {
+			combatants: [
+				{
+					id: combatantId("c-1"),
+					name: "Custom Thug",
+					cr: "2",
+				},
+			],
+			activeIndex: 0,
+			roundNumber: 1,
+		};
+		const emptyUndoRedo: UndoRedoState = {
+			undoStack: [],
+			redoStack: [],
+		};
+		const bundle = assembleExportBundle(encounterWithCr, 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[0].cr).toBe("2");
+	});
+
 	it("round-trips an empty encounter", () => {
 		const emptyEncounter: Encounter = {
 			combatants: [],

apps/web/src/__tests__/factories/build-combatant.ts

@@ -0,0 +1,12 @@
+import type { Combatant } from "@initiative/domain";
+import { combatantId } from "@initiative/domain";
+
+let counter = 0;
+
+export function buildCombatant(overrides?: Partial<Combatant>): Combatant {
+	return {
+		id: combatantId(`c-${++counter}`),
+		name: "Combatant",
+		...overrides,
+	};
+}

apps/web/src/__tests__/factories/build-creature.ts

@@ -0,0 +1,26 @@
+import type { Creature } from "@initiative/domain";
+import { creatureId } from "@initiative/domain";
+
+let counter = 0;
+
+export function buildCreature(overrides?: Partial<Creature>): Creature {
+	const id = ++counter;
+	return {
+		id: creatureId(`creature-${id}`),
+		name: `Creature ${id}`,
+		source: "srd",
+		sourceDisplayName: "SRD",
+		size: "Medium",
+		type: "humanoid",
+		alignment: "neutral",
+		ac: 13,
+		hp: { average: 7, formula: "2d6" },
+		speed: "30 ft.",
+		abilities: { str: 10, dex: 14, con: 10, int: 10, wis: 10, cha: 10 },
+		cr: "1/4",
+		initiativeProficiency: 0,
+		proficiencyBonus: 2,
+		passive: 10,
+		...overrides,
+	};
+}

apps/web/src/__tests__/factories/build-encounter.ts

@@ -0,0 +1,10 @@
+import type { Encounter } from "@initiative/domain";
+
+export function buildEncounter(overrides?: Partial<Encounter>): Encounter {
+	return {
+		combatants: [],
+		activeIndex: 0,
+		roundNumber: 1,
+		...overrides,
+	};
+}

apps/web/src/__tests__/factories/index.ts

@@ -0,0 +1,3 @@
+export { buildCombatant } from "./build-combatant.js";
+export { buildCreature } from "./build-creature.js";
+export { buildEncounter } from "./build-encounter.js";

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

@@ -5,7 +5,9 @@ import type { Creature, CreatureId } from "@initiative/domain";
 import { cleanup, fireEvent, render, screen } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-// Mock the context modules
+// Uses context mocks because StatBlockPanel requires fine-grained control over
+// panel state (collapsed/expanded, pinned/unpinned, wide/narrow desktop) that
+// would need extensive setup to drive through real providers.
 vi.mock("../contexts/side-panel-context.js", () => ({
 	useSidePanelContext: vi.fn(),
 }));
@@ -14,14 +16,6 @@ vi.mock("../contexts/bestiary-context.js", () => ({
 	useBestiaryContext: vi.fn(),
 }));
 
-// Mock adapters to avoid IndexedDB
-vi.mock("../adapters/bestiary-index-adapter.js", () => ({
-	loadBestiaryIndex: () => ({ sources: {}, creatures: [] }),
-	getAllSourceCodes: () => [],
-	getDefaultFetchUrl: () => "",
-	getSourceDisplayName: (code: string) => code,
-}));
-
 import { StatBlockPanel } from "../components/stat-block-panel.js";
 import { useBestiaryContext } from "../contexts/bestiary-context.js";
 import { useSidePanelContext } from "../contexts/side-panel-context.js";

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

@@ -1,4 +1,6 @@
 import type { ReactNode } from "react";
+import type { Adapters } from "../contexts/adapter-context.js";
+import { AdapterProvider } from "../contexts/adapter-context.js";
 import {
 	BestiaryProvider,
 	BulkImportProvider,
@@ -9,9 +11,18 @@ import {
 	SidePanelProvider,
 	ThemeProvider,
 } from "../contexts/index.js";
+import { createTestAdapters } from "./adapters/in-memory-adapters.js";
 
-export function AllProviders({ children }: { children: ReactNode }) {
+export function AllProviders({
+	adapters,
+	children,
+}: {
+	adapters?: Adapters;
+	children: ReactNode;
+}) {
+	const resolved = adapters ?? createTestAdapters();
 	return (
+		<AdapterProvider adapters={resolved}>
 			<ThemeProvider>
 				<RulesEditionProvider>
 					<EncounterProvider>
@@ -19,7 +30,9 @@ export function AllProviders({ children }: { children: ReactNode }) {
 							<PlayerCharactersProvider>
 								<BulkImportProvider>
 									<SidePanelProvider>
-									<InitiativeRollsProvider>{children}</InitiativeRollsProvider>
+										<InitiativeRollsProvider>
+											{children}
+										</InitiativeRollsProvider>
 									</SidePanelProvider>
 								</BulkImportProvider>
 							</PlayerCharactersProvider>
@@ -27,5 +40,6 @@ export function AllProviders({ children }: { children: ReactNode }) {
 					</EncounterProvider>
 				</RulesEditionProvider>
 			</ThemeProvider>
+		</AdapterProvider>
 	);
 }

apps/web/src/adapters/__tests__/bestiary-cache-fallback.test.ts

@@ -0,0 +1,95 @@
+import type { Creature } from "@initiative/domain";
+import { creatureId } from "@initiative/domain";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock idb to reject — simulates IndexedDB unavailable.
+// This must be a separate file from bestiary-cache.test.ts because the
+// module caches the db connection in a singleton; once openDB succeeds
+// in one test, the fallback path is unreachable.
+vi.mock("idb", () => ({
+	openDB: vi.fn().mockRejectedValue(new Error("IndexedDB unavailable")),
+}));
+
+const {
+	cacheSource,
+	isSourceCached,
+	getCachedSources,
+	clearSource,
+	clearAll,
+	loadAllCachedCreatures,
+} = await import("../bestiary-cache.js");
+
+function makeCreature(id: string, name: string): Creature {
+	return {
+		id: creatureId(id),
+		name,
+		source: "MM",
+		sourceDisplayName: "Monster Manual",
+		size: "Small",
+		type: "humanoid",
+		alignment: "neutral evil",
+		ac: 15,
+		hp: { average: 7, formula: "2d6" },
+		speed: "30 ft.",
+		abilities: { str: 8, dex: 14, con: 10, int: 10, wis: 8, cha: 8 },
+		cr: "1/4",
+		initiativeProficiency: 0,
+		proficiencyBonus: 2,
+		passive: 9,
+	};
+}
+
+describe("bestiary-cache fallback (IndexedDB unavailable)", () => {
+	beforeEach(async () => {
+		await clearAll();
+	});
+
+	it("cacheSource falls back to in-memory store", async () => {
+		const creatures = [makeCreature("mm:goblin", "Goblin")];
+		await cacheSource("MM", "Monster Manual", creatures);
+
+		expect(await isSourceCached("MM")).toBe(true);
+	});
+
+	it("isSourceCached returns false for uncached source", async () => {
+		expect(await isSourceCached("XGE")).toBe(false);
+	});
+
+	it("getCachedSources returns sources from in-memory store", async () => {
+		await cacheSource("MM", "Monster Manual", [
+			makeCreature("mm:goblin", "Goblin"),
+		]);
+
+		const sources = await getCachedSources();
+		expect(sources).toHaveLength(1);
+		expect(sources[0].sourceCode).toBe("MM");
+		expect(sources[0].creatureCount).toBe(1);
+	});
+
+	it("loadAllCachedCreatures assembles creatures from in-memory store", async () => {
+		const goblin = makeCreature("mm:goblin", "Goblin");
+		await cacheSource("MM", "Monster Manual", [goblin]);
+
+		const map = await loadAllCachedCreatures();
+		expect(map.size).toBe(1);
+		expect(map.get(creatureId("mm:goblin"))?.name).toBe("Goblin");
+	});
+
+	it("clearSource removes a single source from in-memory store", async () => {
+		await cacheSource("MM", "Monster Manual", []);
+		await cacheSource("VGM", "Volo's Guide", []);
+
+		await clearSource("MM");
+
+		expect(await isSourceCached("MM")).toBe(false);
+		expect(await isSourceCached("VGM")).toBe(true);
+	});
+
+	it("clearAll removes all data from in-memory store", async () => {
+		await cacheSource("MM", "Monster Manual", []);
+		await clearAll();
+
+		const sources = await getCachedSources();
+		expect(sources).toEqual([]);
+	});
+});

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

@@ -0,0 +1,174 @@
+import type { Creature } from "@initiative/domain";
+import { creatureId } from "@initiative/domain";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock idb — the one legitimate use of vi.mock for a third-party I/O library.
+// We can't use real IndexedDB in jsdom; this tests the cache logic through
+// all public API methods with an in-memory backing store.
+const fakeStore = new Map<string, unknown>();
+
+vi.mock("idb", () => ({
+	openDB: vi.fn().mockResolvedValue({
+		put: vi.fn((_storeName: string, value: unknown) => {
+			const record = value as { sourceCode: string };
+			fakeStore.set(record.sourceCode, value);
+			return Promise.resolve();
+		}),
+		get: vi.fn((_storeName: string, key: string) =>
+			Promise.resolve(fakeStore.get(key)),
+		),
+		getAll: vi.fn((_storeName: string) =>
+			Promise.resolve([...fakeStore.values()]),
+		),
+		delete: vi.fn((_storeName: string, key: string) => {
+			fakeStore.delete(key);
+			return Promise.resolve();
+		}),
+		clear: vi.fn((_storeName: string) => {
+			fakeStore.clear();
+			return Promise.resolve();
+		}),
+	}),
+}));
+
+// Import after mocking
+const {
+	cacheSource,
+	isSourceCached,
+	getCachedSources,
+	clearSource,
+	clearAll,
+	loadAllCachedCreatures,
+} = await import("../bestiary-cache.js");
+
+function makeCreature(id: string, name: string): Creature {
+	return {
+		id: creatureId(id),
+		name,
+		source: "MM",
+		sourceDisplayName: "Monster Manual",
+		size: "Small",
+		type: "humanoid",
+		alignment: "neutral evil",
+		ac: 15,
+		hp: { average: 7, formula: "2d6" },
+		speed: "30 ft.",
+		abilities: { str: 8, dex: 14, con: 10, int: 10, wis: 8, cha: 8 },
+		cr: "1/4",
+		initiativeProficiency: 0,
+		proficiencyBonus: 2,
+		passive: 9,
+	};
+}
+
+describe("bestiary-cache", () => {
+	beforeEach(() => {
+		fakeStore.clear();
+	});
+
+	describe("cacheSource", () => {
+		it("stores creatures and metadata", async () => {
+			const creatures = [makeCreature("mm:goblin", "Goblin")];
+			await cacheSource("MM", "Monster Manual", creatures);
+
+			expect(fakeStore.has("MM")).toBe(true);
+			const record = fakeStore.get("MM") as {
+				sourceCode: string;
+				displayName: string;
+				creatures: Creature[];
+				creatureCount: number;
+				cachedAt: number;
+			};
+			expect(record.sourceCode).toBe("MM");
+			expect(record.displayName).toBe("Monster Manual");
+			expect(record.creatures).toHaveLength(1);
+			expect(record.creatureCount).toBe(1);
+			expect(record.cachedAt).toBeGreaterThan(0);
+		});
+	});
+
+	describe("isSourceCached", () => {
+		it("returns false for uncached source", async () => {
+			expect(await isSourceCached("XGE")).toBe(false);
+		});
+
+		it("returns true after caching", async () => {
+			await cacheSource("MM", "Monster Manual", []);
+			expect(await isSourceCached("MM")).toBe(true);
+		});
+	});
+
+	describe("getCachedSources", () => {
+		it("returns empty array when no sources cached", async () => {
+			const sources = await getCachedSources();
+			expect(sources).toEqual([]);
+		});
+
+		it("returns source info with creature counts", async () => {
+			await cacheSource("MM", "Monster Manual", [
+				makeCreature("mm:goblin", "Goblin"),
+				makeCreature("mm:orc", "Orc"),
+			]);
+			await cacheSource("VGM", "Volo's Guide", [
+				makeCreature("vgm:flind", "Flind"),
+			]);
+
+			const sources = await getCachedSources();
+			expect(sources).toHaveLength(2);
+
+			const mm = sources.find((s) => s.sourceCode === "MM");
+			expect(mm).toBeDefined();
+			expect(mm?.displayName).toBe("Monster Manual");
+			expect(mm?.creatureCount).toBe(2);
+
+			const vgm = sources.find((s) => s.sourceCode === "VGM");
+			expect(vgm?.creatureCount).toBe(1);
+		});
+	});
+
+	describe("loadAllCachedCreatures", () => {
+		it("returns empty map when nothing cached", async () => {
+			const map = await loadAllCachedCreatures();
+			expect(map.size).toBe(0);
+		});
+
+		it("assembles creatures from all cached sources", async () => {
+			const goblin = makeCreature("mm:goblin", "Goblin");
+			const orc = makeCreature("mm:orc", "Orc");
+			const flind = makeCreature("vgm:flind", "Flind");
+
+			await cacheSource("MM", "Monster Manual", [goblin, orc]);
+			await cacheSource("VGM", "Volo's Guide", [flind]);
+
+			const map = await loadAllCachedCreatures();
+			expect(map.size).toBe(3);
+			expect(map.get(creatureId("mm:goblin"))?.name).toBe("Goblin");
+			expect(map.get(creatureId("mm:orc"))?.name).toBe("Orc");
+			expect(map.get(creatureId("vgm:flind"))?.name).toBe("Flind");
+		});
+	});
+
+	describe("clearSource", () => {
+		it("removes a single source", async () => {
+			await cacheSource("MM", "Monster Manual", []);
+			await cacheSource("VGM", "Volo's Guide", []);
+
+			await clearSource("MM");
+
+			expect(await isSourceCached("MM")).toBe(false);
+			expect(await isSourceCached("VGM")).toBe(true);
+		});
+	});
+
+	describe("clearAll", () => {
+		it("removes all cached data", async () => {
+			await cacheSource("MM", "Monster Manual", []);
+			await cacheSource("VGM", "Volo's Guide", []);
+
+			await clearAll();
+
+			const sources = await getCachedSources();
+			expect(sources).toEqual([]);
+		});
+	});
+});

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

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest";
+import {
+	getAllSourceCodes,
+	getDefaultFetchUrl,
+	getSourceDisplayName,
+	loadBestiaryIndex,
+} from "../bestiary-index-adapter.js";
+
+describe("loadBestiaryIndex", () => {
+	it("returns an object with sources and creatures", () => {
+		const index = loadBestiaryIndex();
+		expect(index.sources).toBeDefined();
+		expect(index.creatures).toBeDefined();
+		expect(Array.isArray(index.creatures)).toBe(true);
+	});
+
+	it("creatures have the expected shape", () => {
+		const index = loadBestiaryIndex();
+		expect(index.creatures.length).toBeGreaterThan(0);
+		const first = index.creatures[0];
+		expect(first).toHaveProperty("name");
+		expect(first).toHaveProperty("source");
+		expect(first).toHaveProperty("ac");
+		expect(first).toHaveProperty("hp");
+		expect(first).toHaveProperty("dex");
+		expect(first).toHaveProperty("cr");
+		expect(first).toHaveProperty("initiativeProficiency");
+		expect(first).toHaveProperty("size");
+		expect(first).toHaveProperty("type");
+	});
+
+	it("returns the same cached instance on subsequent calls", () => {
+		const a = loadBestiaryIndex();
+		const b = loadBestiaryIndex();
+		expect(a).toBe(b);
+	});
+
+	it("sources is a record of source code to display name", () => {
+		const index = loadBestiaryIndex();
+		const entries = Object.entries(index.sources);
+		expect(entries.length).toBeGreaterThan(0);
+		for (const [code, name] of entries) {
+			expect(typeof code).toBe("string");
+			expect(typeof name).toBe("string");
+			expect(code.length).toBeGreaterThan(0);
+			expect(name.length).toBeGreaterThan(0);
+		}
+	});
+});
+
+describe("getAllSourceCodes", () => {
+	it("returns all keys from the index sources", () => {
+		const codes = getAllSourceCodes();
+		const index = loadBestiaryIndex();
+		expect(codes).toEqual(Object.keys(index.sources));
+	});
+
+	it("returns only strings", () => {
+		for (const code of getAllSourceCodes()) {
+			expect(typeof code).toBe("string");
+		}
+	});
+});
+
+describe("getDefaultFetchUrl", () => {
+	it("returns default GitHub URL when no baseUrl provided", () => {
+		const url = getDefaultFetchUrl("MM");
+		expect(url).toBe(
+			"https://raw.githubusercontent.com/5etools-mirror-3/5etools-src/main/data/bestiary/bestiary-mm.json",
+		);
+	});
+
+	it("constructs URL from baseUrl with trailing slash", () => {
+		const url = getDefaultFetchUrl("PHB", "https://example.com/data/");
+		expect(url).toBe("https://example.com/data/bestiary-phb.json");
+	});
+
+	it("normalizes baseUrl without trailing slash", () => {
+		const url = getDefaultFetchUrl("PHB", "https://example.com/data");
+		expect(url).toBe("https://example.com/data/bestiary-phb.json");
+	});
+
+	it("lowercases the source code in the filename", () => {
+		const url = getDefaultFetchUrl("XMM");
+		expect(url).toContain("bestiary-xmm.json");
+	});
+
+	it("applies filename override for Plane Shift sources", () => {
+		expect(getDefaultFetchUrl("PSA")).toContain("bestiary-ps-a.json");
+		expect(getDefaultFetchUrl("PSD")).toContain("bestiary-ps-d.json");
+		expect(getDefaultFetchUrl("PSK")).toContain("bestiary-ps-k.json");
+	});
+});
+
+describe("getSourceDisplayName", () => {
+	it("returns display name for a known source", () => {
+		const index = loadBestiaryIndex();
+		const [code, expectedName] = Object.entries(index.sources)[0];
+		expect(getSourceDisplayName(code)).toBe(expectedName);
+	});
+
+	it("falls back to source code for unknown source", () => {
+		expect(getSourceDisplayName("UNKNOWN_SOURCE_XYZ")).toBe(
+			"UNKNOWN_SOURCE_XYZ",
+		);
+	});
+});

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

@@ -5,7 +5,7 @@ const DB_NAME = "initiative-bestiary";
 const STORE_NAME = "sources";
 const DB_VERSION = 2;
 
-export interface CachedSourceInfo {
+interface CachedSourceInfo {
 	readonly sourceCode: string;
 	readonly displayName: string;
 	readonly creatureCount: number;

apps/web/src/adapters/ports.ts

@@ -0,0 +1,50 @@
+import type {
+	BestiaryIndex,
+	Creature,
+	CreatureId,
+	Encounter,
+	PlayerCharacter,
+	UndoRedoState,
+} from "@initiative/domain";
+
+export interface EncounterPersistence {
+	load(): Encounter | null;
+	save(encounter: Encounter): void;
+}
+
+export interface UndoRedoPersistence {
+	load(): UndoRedoState;
+	save(state: UndoRedoState): void;
+}
+
+export interface PlayerCharacterPersistence {
+	load(): PlayerCharacter[];
+	save(characters: PlayerCharacter[]): void;
+}
+
+export interface CachedSourceInfo {
+	readonly sourceCode: string;
+	readonly displayName: string;
+	readonly creatureCount: number;
+	readonly cachedAt: number;
+}
+
+export interface BestiaryCachePort {
+	cacheSource(
+		sourceCode: string,
+		displayName: string,
+		creatures: Creature[],
+	): Promise<void>;
+	isSourceCached(sourceCode: string): Promise<boolean>;
+	getCachedSources(): Promise<CachedSourceInfo[]>;
+	clearSource(sourceCode: string): Promise<void>;
+	clearAll(): Promise<void>;
+	loadAllCachedCreatures(): Promise<Map<CreatureId, Creature>>;
+}
+
+export interface BestiaryIndexPort {
+	loadIndex(): BestiaryIndex;
+	getAllSourceCodes(): string[];
+	getDefaultFetchUrl(sourceCode: string, baseUrl?: string): string;
+	getSourceDisplayName(sourceCode: string): string;
+}

apps/web/src/adapters/production-adapters.ts

@@ -0,0 +1,44 @@
+import type { Adapters } from "../contexts/adapter-context.js";
+import {
+	loadEncounter,
+	saveEncounter,
+} from "../persistence/encounter-storage.js";
+import {
+	loadPlayerCharacters,
+	savePlayerCharacters,
+} from "../persistence/player-character-storage.js";
+import {
+	loadUndoRedoStacks,
+	saveUndoRedoStacks,
+} from "../persistence/undo-redo-storage.js";
+import * as bestiaryCache from "./bestiary-cache.js";
+import * as bestiaryIndex from "./bestiary-index-adapter.js";
+
+export const productionAdapters: Adapters = {
+	encounterPersistence: {
+		load: loadEncounter,
+		save: saveEncounter,
+	},
+	undoRedoPersistence: {
+		load: loadUndoRedoStacks,
+		save: saveUndoRedoStacks,
+	},
+	playerCharacterPersistence: {
+		load: loadPlayerCharacters,
+		save: savePlayerCharacters,
+	},
+	bestiaryCache: {
+		cacheSource: bestiaryCache.cacheSource,
+		isSourceCached: bestiaryCache.isSourceCached,
+		getCachedSources: bestiaryCache.getCachedSources,
+		clearSource: bestiaryCache.clearSource,
+		clearAll: bestiaryCache.clearAll,
+		loadAllCachedCreatures: bestiaryCache.loadAllCachedCreatures,
+	},
+	bestiaryIndex: {
+		loadIndex: bestiaryIndex.loadBestiaryIndex,
+		getAllSourceCodes: bestiaryIndex.getAllSourceCodes,
+		getDefaultFetchUrl: bestiaryIndex.getDefaultFetchUrl,
+		getSourceDisplayName: bestiaryIndex.getSourceDisplayName,
+	},
+};

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

@@ -1,41 +1,16 @@
 // @vitest-environment jsdom
 import "@testing-library/jest-dom/vitest";
 
-import { cleanup, render, screen } from "@testing-library/react";
+import { playerCharacterId } from "@initiative/domain";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
+import type { ReactNode } from "react";
 import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { createTestAdapters } from "../../__tests__/adapters/in-memory-adapters.js";
 import { polyfillDialog } from "../../__tests__/polyfill-dialog.js";
 import { AllProviders } from "../../__tests__/test-providers.js";
 import { ActionBar } from "../action-bar.js";
 
-// Mock persistence — no localStorage interaction
-vi.mock("../../persistence/encounter-storage.js", () => ({
-	loadEncounter: () => null,
-	saveEncounter: () => {},
-}));
-
-vi.mock("../../persistence/player-character-storage.js", () => ({
-	loadPlayerCharacters: () => [],
-	savePlayerCharacters: () => {},
-}));
-
-// Mock bestiary — no IndexedDB or JSON index
-vi.mock("../../adapters/bestiary-cache.js", () => ({
-	loadAllCachedCreatures: () => Promise.resolve(new Map()),
-	isSourceCached: () => Promise.resolve(false),
-	cacheSource: () => Promise.resolve(),
-	getCachedSources: () => Promise.resolve([]),
-	clearSource: () => Promise.resolve(),
-	clearAll: () => Promise.resolve(),
-}));
-
-vi.mock("../../adapters/bestiary-index-adapter.js", () => ({
-	loadBestiaryIndex: () => ({ sources: {}, creatures: [] }),
-	getAllSourceCodes: () => [],
-	getDefaultFetchUrl: () => "",
-	getSourceDisplayName: (code: string) => code,
-}));
-
 // DOM API stubs — jsdom doesn't implement these
 beforeAll(() => {
 	Object.defineProperty(globalThis, "matchMedia", {
@@ -60,10 +35,97 @@ function renderBar(props: Partial<Parameters<typeof ActionBar>[0]> = {}) {
 	return render(<ActionBar {...props} />, { wrapper: AllProviders });
 }
 
+function renderBarWithBestiary(
+	props: Partial<Parameters<typeof ActionBar>[0]> = {},
+) {
+	const adapters = createTestAdapters();
+	adapters.bestiaryIndex = {
+		...adapters.bestiaryIndex,
+		loadIndex: () => ({
+			sources: { MM: "Monster Manual" },
+			creatures: [
+				{
+					name: "Goblin",
+					source: "MM",
+					ac: 15,
+					hp: 7,
+					dex: 14,
+					cr: "1/4",
+					initiativeProficiency: 0,
+					size: "Small",
+					type: "humanoid",
+				},
+				{
+					name: "Golem, Iron",
+					source: "MM",
+					ac: 20,
+					hp: 210,
+					dex: 9,
+					cr: "16",
+					initiativeProficiency: 0,
+					size: "Large",
+					type: "construct",
+				},
+			],
+		}),
+		getSourceDisplayName: (code: string) =>
+			code === "MM" ? "Monster Manual" : code,
+	};
+	return render(<ActionBar {...props} />, {
+		wrapper: ({ children }: { children: ReactNode }) => (
+			<AllProviders adapters={adapters}>{children}</AllProviders>
+		),
+	});
+}
+
+function renderBarWithPCs(
+	props: Partial<Parameters<typeof ActionBar>[0]> = {},
+) {
+	const adapters = createTestAdapters({
+		playerCharacters: [
+			{
+				id: playerCharacterId("pc-1"),
+				name: "Gandalf",
+				ac: 15,
+				maxHp: 40,
+			},
+		],
+	});
+	adapters.bestiaryIndex = {
+		...adapters.bestiaryIndex,
+		loadIndex: () => ({
+			sources: { MM: "Monster Manual" },
+			creatures: [
+				{
+					name: "Goblin",
+					source: "MM",
+					ac: 15,
+					hp: 7,
+					dex: 14,
+					cr: "1/4",
+					initiativeProficiency: 0,
+					size: "Small",
+					type: "humanoid",
+				},
+			],
+		}),
+		getSourceDisplayName: (code: string) =>
+			code === "MM" ? "Monster Manual" : code,
+	};
+	return render(<ActionBar {...props} />, {
+		wrapper: ({ children }: { children: ReactNode }) => (
+			<AllProviders adapters={adapters}>{children}</AllProviders>
+		),
+	});
+}
+
 describe("ActionBar", () => {
+	describe("basic rendering and custom add", () => {
 		it("renders input with placeholder '+ Add combatants'", () => {
 			renderBar();
-		expect(screen.getByPlaceholderText("+ Add combatants")).toBeInTheDocument();
+			expect(
+				screen.getByPlaceholderText("+ Add combatants"),
+			).toBeInTheDocument();
 		});
 
 		it("submitting with a name adds a combatant", async () => {
@@ -71,20 +133,16 @@ describe("ActionBar", () => {
 			renderBar();
 			const input = screen.getByPlaceholderText("+ Add combatants");
 			await user.type(input, "Goblin");
-		// The Add button appears when name >= 2 chars and no suggestions
 			const addButton = screen.getByRole("button", { name: "Add" });
 			await user.click(addButton);
-		// Input is cleared after adding (context handles the state)
 			expect(input).toHaveValue("");
 		});
 
 		it("submitting with empty name does nothing", async () => {
 			const user = userEvent.setup();
 			renderBar();
-		// Submit the form directly (Enter on empty input)
 			const input = screen.getByPlaceholderText("+ Add combatants");
 			await user.type(input, "{Enter}");
-		// Input stays empty, no error
 			expect(input).toHaveValue("");
 		});
 
@@ -106,6 +164,160 @@ describe("ActionBar", () => {
 			expect(screen.getByRole("button", { name: "Add" })).toBeInTheDocument();
 		});
 
+		it("submits custom stats with combatant", async () => {
+			const user = userEvent.setup();
+			renderBar();
+			const input = screen.getByPlaceholderText("+ Add combatants");
+			await user.type(input, "Fighter");
+			await user.type(screen.getByPlaceholderText("Init"), "15");
+			await user.type(screen.getByPlaceholderText("AC"), "18");
+			await user.type(screen.getByPlaceholderText("MaxHP"), "45");
+			await user.click(screen.getByRole("button", { name: "Add" }));
+			expect(input).toHaveValue("");
+		});
+	});
+
+	describe("bestiary suggestions and queuing", () => {
+		it("shows bestiary suggestions when typing a matching name", async () => {
+			const user = userEvent.setup();
+			renderBarWithBestiary();
+			const input = screen.getByPlaceholderText("+ Add combatants");
+			await user.type(input, "Go");
+
+			await waitFor(() => {
+				expect(screen.getByText("Goblin")).toBeInTheDocument();
+			});
+			expect(screen.getByText("Golem, Iron")).toBeInTheDocument();
+		});
+
+		it("clicking a suggestion queues it with count badge", async () => {
+			const user = userEvent.setup();
+			renderBarWithBestiary();
+			const input = screen.getByPlaceholderText("+ Add combatants");
+			await user.type(input, "Go");
+
+			await waitFor(() => {
+				expect(screen.getByText("Goblin")).toBeInTheDocument();
+			});
+
+			// Click the Goblin suggestion
+			await user.click(screen.getByText("Goblin"));
+
+			// Should show count badge "1"
+			expect(screen.getByText("1")).toBeInTheDocument();
+		});
+
+		it("clicking same suggestion again increments count", async () => {
+			const user = userEvent.setup();
+			renderBarWithBestiary();
+			const input = screen.getByPlaceholderText("+ Add combatants");
+			await user.type(input, "Go");
+
+			await waitFor(() => {
+				expect(screen.getByText("Goblin")).toBeInTheDocument();
+			});
+
+			await user.click(screen.getByText("Goblin"));
+			await user.click(screen.getByText("Goblin"));
+
+			expect(screen.getByText("2")).toBeInTheDocument();
+		});
+
+		it("confirming queued creatures adds them to the encounter", async () => {
+			const user = userEvent.setup();
+			renderBarWithBestiary();
+			const input = screen.getByPlaceholderText("+ Add combatants");
+			await user.type(input, "Go");
+
+			await waitFor(() => {
+				expect(screen.getByText("Goblin")).toBeInTheDocument();
+			});
+
+			// Queue 1 Goblin
+			await user.click(screen.getByText("Goblin"));
+
+			// Press Enter to confirm the queued creature
+			await user.keyboard("{Enter}");
+
+			// Input should be cleared after confirming
+			expect(input).toHaveValue("");
+		});
+
+		it("clears queued when search text no longer matches", async () => {
+			const user = userEvent.setup();
+			renderBarWithBestiary();
+			const input = screen.getByPlaceholderText("+ Add combatants");
+			await user.type(input, "Go");
+
+			await waitFor(() => {
+				expect(screen.getByText("Goblin")).toBeInTheDocument();
+			});
+
+			await user.click(screen.getByText("Goblin"));
+			expect(screen.getByText("1")).toBeInTheDocument();
+
+			// Change search to something with no matches
+			await user.clear(input);
+			await user.type(input, "xyz");
+
+			// Count badge should be gone
+			expect(screen.queryByText("1")).not.toBeInTheDocument();
+		});
+	});
+
+	describe("player character matching", () => {
+		it("shows matching player characters in suggestions", async () => {
+			const user = userEvent.setup();
+			renderBarWithPCs();
+			const input = screen.getByPlaceholderText("+ Add combatants");
+			await user.type(input, "Gan");
+
+			await waitFor(() => {
+				expect(screen.getByText("Gandalf")).toBeInTheDocument();
+			});
+			expect(screen.getByText("Player")).toBeInTheDocument();
+		});
+	});
+
+	describe("browse mode", () => {
+		it("toggles browse mode via eye icon button", async () => {
+			const user = userEvent.setup();
+			renderBarWithBestiary();
+
+			const browseButton = screen.getByRole("button", {
+				name: "Browse stat blocks",
+			});
+			await user.click(browseButton);
+
+			expect(
+				screen.getByPlaceholderText("Search stat blocks..."),
+			).toBeInTheDocument();
+			expect(
+				screen.getByRole("button", { name: "Switch to add mode" }),
+			).toBeInTheDocument();
+		});
+
+		it("browse mode shows suggestions without add UI", async () => {
+			const user = userEvent.setup();
+			renderBarWithBestiary();
+
+			await user.click(
+				screen.getByRole("button", { name: "Browse stat blocks" }),
+			);
+			const input = screen.getByPlaceholderText("Search stat blocks...");
+			await user.type(input, "Go");
+
+			await waitFor(() => {
+				expect(screen.getByText("Goblin")).toBeInTheDocument();
+			});
+			// No Add button in browse mode
+			expect(
+				screen.queryByRole("button", { name: "Add" }),
+			).not.toBeInTheDocument();
+		});
+	});
+
+	describe("overflow menu", () => {
 		it("does not show roll all initiative button when no creature combatants", () => {
 			renderBar();
 			expect(
@@ -115,7 +327,6 @@ describe("ActionBar", () => {
 
 		it("shows overflow menu items", () => {
 			renderBar({ onManagePlayers: vi.fn() });
-		// The overflow menu should be present (it contains Player Characters etc.)
 			expect(
 				screen.getByRole("button", { name: "More actions" }),
 			).toBeInTheDocument();
@@ -125,10 +336,8 @@ describe("ActionBar", () => {
 			const user = userEvent.setup();
 			renderBar();
 			await user.click(screen.getByRole("button", { name: "More actions" }));
-		// Click the menu item
 			const items = screen.getAllByText("Export Encounter");
 			await user.click(items[0]);
-		// Dialog should now be open — it renders a second "Export Encounter" as heading
 			expect(
 				screen.getAllByText("Export Encounter").length,
 			).toBeGreaterThanOrEqual(1);
@@ -162,19 +371,5 @@ describe("ActionBar", () => {
 			await user.click(screen.getByText("Settings"));
 			expect(onOpenSettings).toHaveBeenCalledOnce();
 		});
-
-	it("submits custom stats with combatant", async () => {
-		const user = userEvent.setup();
-		renderBar();
-		const input = screen.getByPlaceholderText("+ Add combatants");
-		await user.type(input, "Fighter");
-		const initInput = screen.getByPlaceholderText("Init");
-		const acInput = screen.getByPlaceholderText("AC");
-		const hpInput = screen.getByPlaceholderText("MaxHP");
-		await user.type(initInput, "15");
-		await user.type(acInput, "18");
-		await user.type(hpInput, "45");
-		await user.click(screen.getByRole("button", { name: "Add" }));
-		expect(input).toHaveValue("");
 	});
 });

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

@@ -4,6 +4,8 @@ import "@testing-library/jest-dom/vitest";
 import { cleanup, render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { createTestAdapters } from "../../__tests__/adapters/in-memory-adapters.js";
+import { AdapterProvider } from "../../contexts/adapter-context.js";
 import { BulkImportPrompt } from "../bulk-import-prompt.js";
 
 const THREE_SOURCES_REGEX = /3 sources/;
@@ -28,6 +30,10 @@ let mockImportState = {
 	failed: 0,
 };
 
+// Uses context mocks because the bulk import state machine (idle → loading →
+// complete → partial-failure) is impractical to drive through user interactions
+// without real network calls. Consider migrating if adapter injection expands
+// to cover these state transitions.
 vi.mock("../../contexts/bestiary-context.js", () => ({
 	useBestiaryContext: () => ({
 		fetchAndCacheSource: mockFetchAndCacheSource,
@@ -50,12 +56,23 @@ vi.mock("../../contexts/side-panel-context.js", () => ({
 	}),
 }));
 
-vi.mock("../../adapters/bestiary-index-adapter.js", () => ({
+function createAdaptersWithSources() {
+	const adapters = createTestAdapters();
+	adapters.bestiaryIndex = {
+		...adapters.bestiaryIndex,
 		getAllSourceCodes: () => ["MM", "VGM", "XGE"],
-	getDefaultFetchUrl: () => "",
-	getSourceDisplayName: (code: string) => code,
-	loadBestiaryIndex: () => ({ sources: {}, creatures: [] }),
-}));
+	};
+	return adapters;
+}
+
+function renderWithAdapters() {
+	const adapters = createAdaptersWithSources();
+	return render(
+		<AdapterProvider adapters={adapters}>
+			<BulkImportPrompt />
+		</AdapterProvider>,
+	);
+}
 
 describe("BulkImportPrompt", () => {
 	afterEach(() => {
@@ -64,7 +81,7 @@ describe("BulkImportPrompt", () => {
 	});
 
 	it("idle: shows base URL input, source count, Load All button", () => {
-		render(<BulkImportPrompt />);
+		renderWithAdapters();
 		expect(screen.getByText(THREE_SOURCES_REGEX)).toBeInTheDocument();
 		expect(screen.getByDisplayValue(GITHUB_URL_REGEX)).toBeInTheDocument();
 		expect(
@@ -74,7 +91,7 @@ describe("BulkImportPrompt", () => {
 
 	it("idle: clearing URL disables the button", async () => {
 		const user = userEvent.setup();
-		render(<BulkImportPrompt />);
+		renderWithAdapters();
 
 		const input = screen.getByDisplayValue(GITHUB_URL_REGEX);
 		await user.clear(input);
@@ -83,7 +100,7 @@ describe("BulkImportPrompt", () => {
 
 	it("idle: clicking Load All calls startImport with URL", async () => {
 		const user = userEvent.setup();
-		render(<BulkImportPrompt />);
+		renderWithAdapters();
 
 		await user.click(screen.getByRole("button", { name: "Load All" }));
 		expect(mockStartImport).toHaveBeenCalledWith(
@@ -101,7 +118,7 @@ describe("BulkImportPrompt", () => {
 			completed: 3,
 			failed: 1,
 		};
-		render(<BulkImportPrompt />);
+		renderWithAdapters();
 		expect(screen.getByText(LOADING_PROGRESS_REGEX)).toBeInTheDocument();
 	});
 
@@ -112,7 +129,7 @@ describe("BulkImportPrompt", () => {
 			completed: 10,
 			failed: 0,
 		};
-		render(<BulkImportPrompt />);
+		renderWithAdapters();
 		expect(screen.getByText("All sources loaded")).toBeInTheDocument();
 		expect(screen.getByRole("button", { name: "Done" })).toBeInTheDocument();
 	});
@@ -125,7 +142,7 @@ describe("BulkImportPrompt", () => {
 			failed: 0,
 		};
 		const user = userEvent.setup();
-		render(<BulkImportPrompt />);
+		renderWithAdapters();
 
 		await user.click(screen.getByRole("button", { name: "Done" }));
 		expect(mockDismissPanel).toHaveBeenCalled();
@@ -139,7 +156,7 @@ describe("BulkImportPrompt", () => {
 			completed: 7,
 			failed: 3,
 		};
-		render(<BulkImportPrompt />);
+		renderWithAdapters();
 		expect(screen.getByText(SEVEN_OF_TEN_REGEX)).toBeInTheDocument();
 		expect(screen.getByText(THREE_FAILED_REGEX)).toBeInTheDocument();
 	});

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

@@ -13,34 +13,6 @@ const TEMP_HP_REGEX = /^\+\d/;
 const CURRENT_HP_7_REGEX = /Current HP: 7/;
 const CURRENT_HP_REGEX = /Current HP/;
 
-// Mock persistence — no localStorage interaction
-vi.mock("../../persistence/encounter-storage.js", () => ({
-	loadEncounter: () => null,
-	saveEncounter: () => {},
-}));
-
-vi.mock("../../persistence/player-character-storage.js", () => ({
-	loadPlayerCharacters: () => [],
-	savePlayerCharacters: () => {},
-}));
-
-// Mock bestiary — no IndexedDB or JSON index
-vi.mock("../../adapters/bestiary-cache.js", () => ({
-	loadAllCachedCreatures: () => Promise.resolve(new Map()),
-	isSourceCached: () => Promise.resolve(false),
-	cacheSource: () => Promise.resolve(),
-	getCachedSources: () => Promise.resolve([]),
-	clearSource: () => Promise.resolve(),
-	clearAll: () => Promise.resolve(),
-}));
-
-vi.mock("../../adapters/bestiary-index-adapter.js", () => ({
-	loadBestiaryIndex: () => ({ sources: {}, creatures: [] }),
-	getAllSourceCodes: () => [],
-	getDefaultFetchUrl: () => "",
-	getSourceDisplayName: (code: string) => code,
-}));
-
 // DOM API stubs
 beforeAll(() => {
 	Object.defineProperty(globalThis, "matchMedia", {

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

@@ -3,36 +3,33 @@ import type { ConditionId } from "@initiative/domain";
 import { cleanup, render, screen } from "@testing-library/react";
 import { userEvent } from "@testing-library/user-event";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { RulesEditionProvider } from "../../contexts/rules-edition-context.js";
 import { ConditionTags } from "../condition-tags.js";
 
-vi.mock("../../contexts/rules-edition-context.js", () => ({
-	useRulesEditionContext: () => ({ edition: "5.5e" }),
-}));
-
 afterEach(cleanup);
 
+function renderTags(props: Partial<Parameters<typeof ConditionTags>[0]> = {}) {
+	return render(
+		<RulesEditionProvider>
+			<ConditionTags
+				conditions={props.conditions}
+				onRemove={props.onRemove ?? (() => {})}
+				onOpenPicker={props.onOpenPicker ?? (() => {})}
+			/>
+		</RulesEditionProvider>,
+	);
+}
+
 describe("ConditionTags", () => {
 	it("renders nothing when conditions is undefined", () => {
-		const { container } = render(
-			<ConditionTags
-				conditions={undefined}
-				onRemove={() => {}}
-				onOpenPicker={() => {}}
-			/>,
-		);
+		const { container } = renderTags();
 		// Only the add button should be present
 		expect(container.querySelectorAll("button")).toHaveLength(1);
 	});
 
 	it("renders a button per condition", () => {
 		const conditions: ConditionId[] = ["blinded", "prone"];
-		render(
-			<ConditionTags
-				conditions={conditions}
-				onRemove={() => {}}
-				onOpenPicker={() => {}}
-			/>,
-		);
+		renderTags({ conditions });
 		expect(
 			screen.getByRole("button", { name: "Remove Blinded" }),
 		).toBeDefined();
@@ -41,13 +38,10 @@ describe("ConditionTags", () => {
 
 	it("calls onRemove with condition id when clicked", async () => {
 		const onRemove = vi.fn();
-		render(
-			<ConditionTags
-				conditions={["blinded"] as ConditionId[]}
-				onRemove={onRemove}
-				onOpenPicker={() => {}}
-			/>,
-		);
+		renderTags({
+			conditions: ["blinded"] as ConditionId[],
+			onRemove,
+		});
 
 		await userEvent.click(
 			screen.getByRole("button", { name: "Remove Blinded" }),
@@ -58,13 +52,7 @@ describe("ConditionTags", () => {
 
 	it("calls onOpenPicker when add button is clicked", async () => {
 		const onOpenPicker = vi.fn();
-		render(
-			<ConditionTags
-				conditions={[]}
-				onRemove={() => {}}
-				onOpenPicker={onOpenPicker}
-			/>,
-		);
+		renderTags({ conditions: [], onOpenPicker });
 
 		await userEvent.click(
 			screen.getByRole("button", { name: "Add condition" }),
@@ -74,13 +62,7 @@ describe("ConditionTags", () => {
 	});
 
 	it("renders empty conditions array without errors", () => {
-		render(
-			<ConditionTags
-				conditions={[]}
-				onRemove={() => {}}
-				onOpenPicker={() => {}}
-			/>,
-		);
+		renderTags({ conditions: [] });
 		// Only add button
 		expect(screen.getByRole("button", { name: "Add condition" })).toBeDefined();
 	});

apps/web/src/components/__tests__/difficulty-breakdown-panel.test.tsx

@@ -0,0 +1,232 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import type { Creature, CreatureId, PlayerCharacter } from "@initiative/domain";
+import { combatantId, creatureId, playerCharacterId } from "@initiative/domain";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { createTestAdapters } from "../../__tests__/adapters/in-memory-adapters.js";
+import {
+	buildCombatant,
+	buildCreature,
+	buildEncounter,
+} from "../../__tests__/factories/index.js";
+import { AllProviders } from "../../__tests__/test-providers.js";
+import { DifficultyBreakdownPanel } from "../difficulty-breakdown-panel.js";
+
+beforeAll(() => {
+	Object.defineProperty(globalThis, "matchMedia", {
+		writable: true,
+		value: vi.fn().mockImplementation((query: string) => ({
+			matches: false,
+			media: query,
+			onchange: null,
+			addListener: vi.fn(),
+			removeListener: vi.fn(),
+			addEventListener: vi.fn(),
+			removeEventListener: vi.fn(),
+			dispatchEvent: vi.fn(),
+		})),
+	});
+});
+
+afterEach(cleanup);
+
+const pcId1 = playerCharacterId("pc-1");
+const goblinCreature = buildCreature({
+	id: creatureId("srd:goblin"),
+	name: "Goblin",
+	cr: "1/4",
+	source: "srd",
+	sourceDisplayName: "SRD",
+});
+
+function renderPanel(options: {
+	encounter: ReturnType<typeof buildEncounter>;
+	playerCharacters?: PlayerCharacter[];
+	creatures?: Map<CreatureId, Creature>;
+	onClose?: () => void;
+}) {
+	const adapters = createTestAdapters({
+		encounter: options.encounter,
+		playerCharacters: options.playerCharacters ?? [],
+		creatures: options.creatures,
+	});
+	return render(
+		<AllProviders adapters={adapters}>
+			<DifficultyBreakdownPanel onClose={options.onClose ?? (() => {})} />
+		</AllProviders>,
+	);
+}
+
+function defaultEncounter() {
+	return buildEncounter({
+		combatants: [
+			buildCombatant({
+				id: combatantId("c-1"),
+				name: "Hero",
+				playerCharacterId: pcId1,
+			}),
+			buildCombatant({
+				id: combatantId("c-2"),
+				name: "Goblin",
+				creatureId: goblinCreature.id,
+			}),
+			buildCombatant({
+				id: combatantId("c-3"),
+				name: "Custom Thug",
+				cr: "2",
+			}),
+			buildCombatant({
+				id: combatantId("c-4"),
+				name: "Bandit",
+			}),
+		],
+	});
+}
+
+const defaultPCs: PlayerCharacter[] = [
+	{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 },
+];
+
+describe("DifficultyBreakdownPanel", () => {
+	it("renders party budget section", async () => {
+		renderPanel({
+			encounter: defaultEncounter(),
+			playerCharacters: defaultPCs,
+			creatures: new Map([[goblinCreature.id, goblinCreature]]),
+		});
+
+		await waitFor(() => {
+			expect(
+				screen.getByText("Party Budget", { exact: false }),
+			).toBeInTheDocument();
+			expect(screen.getByText("1 PC", { exact: false })).toBeInTheDocument();
+			expect(screen.getByText("Low:", { exact: false })).toBeInTheDocument();
+		});
+	});
+
+	it("renders tier label", async () => {
+		renderPanel({
+			encounter: defaultEncounter(),
+			playerCharacters: defaultPCs,
+			creatures: new Map([[goblinCreature.id, goblinCreature]]),
+		});
+
+		await waitFor(() => {
+			expect(
+				screen.getByText("Encounter Difficulty:", { exact: false }),
+			).toBeInTheDocument();
+		});
+	});
+
+	it("renders bestiary combatant as read-only with source name", async () => {
+		renderPanel({
+			encounter: defaultEncounter(),
+			playerCharacters: defaultPCs,
+			creatures: new Map([[goblinCreature.id, goblinCreature]]),
+		});
+
+		await waitFor(() => {
+			expect(screen.getByText("Goblin (SRD)")).toBeInTheDocument();
+			expect(screen.getAllByText("CR 1/4").length).toBeGreaterThanOrEqual(1);
+		});
+	});
+
+	it("renders custom combatant with CR picker", async () => {
+		renderPanel({
+			encounter: defaultEncounter(),
+			playerCharacters: defaultPCs,
+			creatures: new Map([[goblinCreature.id, goblinCreature]]),
+		});
+
+		await waitFor(() => {
+			const pickers = screen.getAllByLabelText("Challenge rating");
+			expect(pickers).toHaveLength(2);
+			// First picker is "Custom Thug" with CR 2
+			expect(pickers[0]).toHaveValue("2");
+		});
+	});
+
+	it("renders unassigned combatant with Assign picker and dash for XP", async () => {
+		renderPanel({
+			encounter: defaultEncounter(),
+			playerCharacters: defaultPCs,
+			creatures: new Map([[goblinCreature.id, goblinCreature]]),
+		});
+
+		await waitFor(() => {
+			const pickers = screen.getAllByLabelText("Challenge rating");
+			// Second picker is "Bandit" with no CR
+			expect(pickers[1]).toHaveValue("");
+			// "—" appears for unassigned XP
+			expect(screen.getByText("—")).toBeInTheDocument();
+		});
+	});
+
+	it("selecting a CR updates the visible XP value", async () => {
+		const user = userEvent.setup();
+		renderPanel({
+			encounter: defaultEncounter(),
+			playerCharacters: defaultPCs,
+			creatures: new Map([[goblinCreature.id, goblinCreature]]),
+		});
+
+		// Wait for the panel to render with bestiary data
+		await waitFor(() => {
+			expect(screen.getByText("—")).toBeInTheDocument();
+		});
+
+		// The Bandit (second picker) has no CR — shows "—" for XP
+		const pickers = screen.getAllByLabelText("Challenge rating");
+
+		// Select CR 5 (1,800 XP) on Bandit
+		await user.selectOptions(pickers[1], "5");
+
+		// XP should update — the "—" should be replaced with an XP value
+		await waitFor(() => {
+			expect(screen.getByText("1,800")).toBeInTheDocument();
+		});
+	});
+
+	it("renders total monster XP", async () => {
+		renderPanel({
+			encounter: defaultEncounter(),
+			playerCharacters: defaultPCs,
+			creatures: new Map([[goblinCreature.id, goblinCreature]]),
+		});
+
+		await waitFor(() => {
+			expect(screen.getByText("Total Monster XP")).toBeInTheDocument();
+		});
+	});
+
+	it("renders nothing when breakdown data is insufficient", () => {
+		// No PCs with level → breakdown returns null
+		const { container } = renderPanel({
+			encounter: buildEncounter({
+				combatants: [
+					buildCombatant({ id: combatantId("c-1"), name: "Custom" }),
+				],
+			}),
+		});
+
+		expect(container.innerHTML).toBe("");
+	});
+
+	it("calls onClose when Escape is pressed", async () => {
+		const user = userEvent.setup();
+		const onClose = vi.fn();
+		renderPanel({
+			encounter: defaultEncounter(),
+			playerCharacters: defaultPCs,
+			creatures: new Map([[goblinCreature.id, goblinCreature]]),
+			onClose,
+		});
+
+		await user.keyboard("{Escape}");
+
+		expect(onClose).toHaveBeenCalledOnce();
+	});
+});

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

@@ -1,7 +1,8 @@
 // @vitest-environment jsdom
 import type { DifficultyResult } from "@initiative/domain";
 import { cleanup, render, screen } from "@testing-library/react";
-import { afterEach, describe, expect, it } from "vitest";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { DifficultyIndicator } from "../difficulty-indicator.js";
 
 afterEach(cleanup);
@@ -56,4 +57,41 @@ describe("DifficultyIndicator", () => {
 			}),
 		).toBeDefined();
 	});
+
+	it("calls onClick when clicked", async () => {
+		const user = userEvent.setup();
+		const handleClick = vi.fn();
+		render(
+			<DifficultyIndicator
+				result={makeResult("moderate")}
+				onClick={handleClick}
+			/>,
+		);
+
+		await user.click(
+			screen.getByRole("img", {
+				name: "Moderate encounter difficulty",
+			}),
+		);
+		expect(handleClick).toHaveBeenCalledOnce();
+	});
+
+	it("renders as div when onClick not provided", () => {
+		const { container } = render(
+			<DifficultyIndicator result={makeResult("moderate")} />,
+		);
+		const element = container.querySelector("[role='img']");
+		expect(element?.tagName).toBe("DIV");
+	});
+
+	it("renders as button when onClick provided", () => {
+		const { container } = render(
+			<DifficultyIndicator
+				result={makeResult("moderate")}
+				onClick={() => {}}
+			/>,
+		);
+		const element = container.querySelector("[role='img']");
+		expect(element?.tagName).toBe("BUTTON");
+	});
 });

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

@@ -33,32 +33,6 @@ beforeAll(() => {
 
 afterEach(cleanup);
 
-vi.mock("../../persistence/encounter-storage.js", () => ({
-	loadEncounter: () => null,
-	saveEncounter: () => {},
-}));
-
-vi.mock("../../persistence/player-character-storage.js", () => ({
-	loadPlayerCharacters: () => [],
-	savePlayerCharacters: () => {},
-}));
-
-vi.mock("../../adapters/bestiary-cache.js", () => ({
-	loadAllCachedCreatures: () => Promise.resolve(new Map()),
-	isSourceCached: () => Promise.resolve(false),
-	cacheSource: () => Promise.resolve(),
-	getCachedSources: () => Promise.resolve([]),
-	clearSource: () => Promise.resolve(),
-	clearAll: () => Promise.resolve(),
-}));
-
-vi.mock("../../adapters/bestiary-index-adapter.js", () => ({
-	loadBestiaryIndex: () => ({ sources: {}, creatures: [] }),
-	getAllSourceCodes: () => [],
-	getDefaultFetchUrl: () => "",
-	getSourceDisplayName: (code: string) => code,
-}));
-
 function renderSection() {
 	const ref = createRef<PlayerCharacterSectionHandle>();
 	const result = render(<PlayerCharacterSection ref={ref} />, {

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

@@ -28,32 +28,6 @@ beforeAll(() => {
 	});
 });
 
-vi.mock("../../persistence/encounter-storage.js", () => ({
-	loadEncounter: () => null,
-	saveEncounter: () => {},
-}));
-
-vi.mock("../../persistence/player-character-storage.js", () => ({
-	loadPlayerCharacters: () => [],
-	savePlayerCharacters: () => {},
-}));
-
-vi.mock("../../adapters/bestiary-cache.js", () => ({
-	loadAllCachedCreatures: () => Promise.resolve(new Map()),
-	isSourceCached: () => Promise.resolve(false),
-	cacheSource: () => Promise.resolve(),
-	getCachedSources: () => Promise.resolve([]),
-	clearSource: () => Promise.resolve(),
-	clearAll: () => Promise.resolve(),
-}));
-
-vi.mock("../../adapters/bestiary-index-adapter.js", () => ({
-	loadBestiaryIndex: () => ({ sources: {}, creatures: [] }),
-	getAllSourceCodes: () => [],
-	getDefaultFetchUrl: () => "",
-	getSourceDisplayName: (code: string) => code,
-}));
-
 function renderModal(open = true) {
 	const onClose = vi.fn();
 	const result = render(<SettingsModal open={open} onClose={onClose} />, {

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

@@ -4,6 +4,8 @@ import "@testing-library/jest-dom/vitest";
 import { cleanup, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { createTestAdapters } from "../../__tests__/adapters/in-memory-adapters.js";
+import { AdapterProvider } from "../../contexts/adapter-context.js";
 import { SourceFetchPrompt } from "../source-fetch-prompt.js";
 
 const MONSTER_MANUAL_REGEX = /Monster Manual/;
@@ -13,6 +15,9 @@ afterEach(cleanup);
 const mockFetchAndCacheSource = vi.fn();
 const mockUploadAndCacheSource = vi.fn();
 
+// Uses context mock because fetchAndCacheSource/uploadAndCacheSource involve
+// real fetch() calls. The test controls success/failure to verify the
+// component's loading and error UI, not the fetching logic itself.
 vi.mock("../../contexts/bestiary-context.js", () => ({
 	useBestiaryContext: () => ({
 		fetchAndCacheSource: mockFetchAndCacheSource,
@@ -20,22 +25,23 @@ vi.mock("../../contexts/bestiary-context.js", () => ({
 	}),
 }));
 
-vi.mock("../../adapters/bestiary-index-adapter.js", () => ({
+function renderPrompt(sourceCode = "MM") {
+	const onSourceLoaded = vi.fn();
+	const adapters = createTestAdapters();
+	adapters.bestiaryIndex = {
+		...adapters.bestiaryIndex,
 		getDefaultFetchUrl: (code: string) =>
 			`https://example.com/bestiary/${code}.json`,
 		getSourceDisplayName: (code: string) =>
 			code === "MM" ? "Monster Manual" : code,
-	loadBestiaryIndex: () => ({ sources: {}, creatures: [] }),
-	getAllSourceCodes: () => [],
-}));
-
-function renderPrompt(sourceCode = "MM") {
-	const onSourceLoaded = vi.fn();
+	};
 	const result = render(
+		<AdapterProvider adapters={adapters}>
 			<SourceFetchPrompt
 				sourceCode={sourceCode}
 				onSourceLoaded={onSourceLoaded}
-		/>,
+			/>
+		</AdapterProvider>,
 	);
 	return { ...result, onSourceLoaded };
 }

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

@@ -3,60 +3,68 @@ import "@testing-library/jest-dom/vitest";
 
 import { cleanup, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
-import { afterEach, describe, expect, it, vi } from "vitest";
-
-vi.mock("../../adapters/bestiary-cache.js", () => ({
-	getCachedSources: vi.fn(),
-	clearSource: vi.fn(),
-	clearAll: vi.fn(),
-}));
-
-// Mock the context module
-vi.mock("../../contexts/bestiary-context.js", () => ({
-	useBestiaryContext: vi.fn(),
-}));
-
-import * as bestiaryCache from "../../adapters/bestiary-cache.js";
-import { useBestiaryContext } from "../../contexts/bestiary-context.js";
+import type { ReactNode } from "react";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { createTestAdapters } from "../../__tests__/adapters/in-memory-adapters.js";
+import { AllProviders } from "../../__tests__/test-providers.js";
+import type { CachedSourceInfo } from "../../adapters/ports.js";
 import { SourceManager } from "../source-manager.js";
 
-const mockGetCachedSources = vi.mocked(bestiaryCache.getCachedSources);
-const mockClearSource = vi.mocked(bestiaryCache.clearSource);
-const mockClearAll = vi.mocked(bestiaryCache.clearAll);
-const mockUseBestiaryContext = vi.mocked(useBestiaryContext);
-
-afterEach(() => {
-	cleanup();
-	vi.clearAllMocks();
+beforeAll(() => {
+	Object.defineProperty(globalThis, "matchMedia", {
+		writable: true,
+		value: vi.fn().mockImplementation((query: string) => ({
+			matches: false,
+			media: query,
+			onchange: null,
+			addListener: vi.fn(),
+			removeListener: vi.fn(),
+			addEventListener: vi.fn(),
+			removeEventListener: vi.fn(),
+			dispatchEvent: vi.fn(),
+		})),
+	});
 });
 
-function setupMockContext() {
-	const refreshCache = vi.fn().mockResolvedValue(undefined);
-	mockUseBestiaryContext.mockReturnValue({
-		refreshCache,
-		search: vi.fn().mockReturnValue([]),
-		getCreature: vi.fn(),
-		isLoaded: true,
-		isSourceCached: vi.fn().mockResolvedValue(false),
-		fetchAndCacheSource: vi.fn(),
-		uploadAndCacheSource: vi.fn(),
-	} as ReturnType<typeof useBestiaryContext>);
-	return { refreshCache };
+afterEach(cleanup);
+
+function renderWithSources(sources: CachedSourceInfo[] = []) {
+	const adapters = createTestAdapters();
+	// Wire getCachedSources to return the provided sources initially,
+	// then empty after clear operations
+	let currentSources = [...sources];
+	adapters.bestiaryCache = {
+		...adapters.bestiaryCache,
+		getCachedSources: () => Promise.resolve(currentSources),
+		clearSource(sourceCode) {
+			currentSources = currentSources.filter(
+				(s) => s.sourceCode !== sourceCode,
+			);
+			return Promise.resolve();
+		},
+		clearAll() {
+			currentSources = [];
+			return Promise.resolve();
+		},
+	};
+
+	render(<SourceManager />, {
+		wrapper: ({ children }: { children: ReactNode }) => (
+			<AllProviders adapters={adapters}>{children}</AllProviders>
+		),
+	});
 }
 
 describe("SourceManager", () => {
 	it("shows 'No cached sources' empty state when no sources", async () => {
-		setupMockContext();
-		mockGetCachedSources.mockResolvedValue([]);
-		render(<SourceManager />);
+		void renderWithSources([]);
 		await waitFor(() => {
 			expect(screen.getByText("No cached sources")).toBeInTheDocument();
 		});
 	});
 
 	it("lists cached sources with display name and creature count", async () => {
-		setupMockContext();
-		mockGetCachedSources.mockResolvedValue([
+		void renderWithSources([
 			{
 				sourceCode: "mm",
 				displayName: "Monster Manual",
@@ -70,7 +78,6 @@ describe("SourceManager", () => {
 				cachedAt: Date.now(),
 			},
 		]);
-		render(<SourceManager />);
 		await waitFor(() => {
 			expect(screen.getByText("Monster Manual")).toBeInTheDocument();
 		});
@@ -79,38 +86,31 @@ describe("SourceManager", () => {
 		expect(screen.getByText("100 creatures")).toBeInTheDocument();
 	});
 
-	it("Clear All button calls cache clear and refreshCache", async () => {
+	it("Clear All button removes all sources", async () => {
 		const user = userEvent.setup();
-		const { refreshCache } = setupMockContext();
-		mockGetCachedSources
-			.mockResolvedValueOnce([
+		void renderWithSources([
 			{
 				sourceCode: "mm",
 				displayName: "Monster Manual",
 				creatureCount: 300,
 				cachedAt: Date.now(),
 			},
-			])
-			.mockResolvedValue([]);
-		mockClearAll.mockResolvedValue(undefined);
-		render(<SourceManager />);
+		]);
 
 		await waitFor(() => {
 			expect(screen.getByText("Monster Manual")).toBeInTheDocument();
 		});
 
 		await user.click(screen.getByRole("button", { name: "Clear All" }));
+
 		await waitFor(() => {
-			expect(mockClearAll).toHaveBeenCalled();
+			expect(screen.getByText("No cached sources")).toBeInTheDocument();
 		});
-		expect(refreshCache).toHaveBeenCalled();
 	});
 
-	it("individual source delete button calls clear for that source", async () => {
+	it("individual source delete button removes that source", async () => {
 		const user = userEvent.setup();
-		const { refreshCache } = setupMockContext();
-		mockGetCachedSources
-			.mockResolvedValueOnce([
+		void renderWithSources([
 			{
 				sourceCode: "mm",
 				displayName: "Monster Manual",
@@ -123,18 +123,8 @@ describe("SourceManager", () => {
 				creatureCount: 100,
 				cachedAt: Date.now(),
 			},
-			])
-			.mockResolvedValue([
-				{
-					sourceCode: "vgm",
-					displayName: "Volo's Guide",
-					creatureCount: 100,
-					cachedAt: Date.now(),
-				},
 		]);
-		mockClearSource.mockResolvedValue(undefined);
 
-		render(<SourceManager />);
 		await waitFor(() => {
 			expect(screen.getByText("Monster Manual")).toBeInTheDocument();
 		});
@@ -142,9 +132,10 @@ describe("SourceManager", () => {
 		await user.click(
 			screen.getByRole("button", { name: "Remove Monster Manual" }),
 		);
+
 		await waitFor(() => {
-			expect(mockClearSource).toHaveBeenCalledWith("mm");
+			expect(screen.queryByText("Monster Manual")).not.toBeInTheDocument();
 		});
-		expect(refreshCache).toHaveBeenCalled();
+		expect(screen.getByText("Volo's Guide")).toBeInTheDocument();
 	});
 });

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

@@ -1,100 +1,68 @@
 // @vitest-environment jsdom
 import "@testing-library/jest-dom/vitest";
 
-import type { Encounter } from "@initiative/domain";
 import { combatantId } from "@initiative/domain";
 import { cleanup, render, screen } from "@testing-library/react";
-import { afterEach, describe, expect, it, vi } from "vitest";
-
-// 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 type { ReactNode } from "react";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { createTestAdapters } from "../../__tests__/adapters/in-memory-adapters.js";
+import {
+	buildCombatant,
+	buildEncounter,
+} from "../../__tests__/factories/index.js";
+import { AllProviders } from "../../__tests__/test-providers.js";
 import { TurnNavigation } from "../turn-navigation.js";
 
-const mockUseEncounterContext = vi.mocked(useEncounterContext);
-
-afterEach(() => {
-	cleanup();
-	vi.clearAllMocks();
+beforeAll(() => {
+	Object.defineProperty(globalThis, "matchMedia", {
+		writable: true,
+		value: vi.fn().mockImplementation((query: string) => ({
+			matches: false,
+			media: query,
+			onchange: null,
+			addListener: vi.fn(),
+			removeListener: vi.fn(),
+			addEventListener: vi.fn(),
+			removeEventListener: vi.fn(),
+			dispatchEvent: vi.fn(),
+		})),
+	});
 });
 
-function mockContext(overrides: Partial<Encounter> = {}) {
-	const encounter: Encounter = {
-		combatants: [
-			{ id: combatantId("1"), name: "Goblin" },
-			{ id: combatantId("2"), name: "Conjurer" },
-		],
-		activeIndex: 0,
-		roundNumber: 1,
-		...overrides,
-	};
+afterEach(cleanup);
 
-	const value = {
-		encounter,
-		advanceTurn: vi.fn(),
-		retreatTurn: vi.fn(),
-		clearEncounter: vi.fn(),
-		isEmpty: encounter.combatants.length === 0,
-		hasCreatureCombatants: false,
-		canRollAllInitiative: false,
-		addCombatant: vi.fn(),
-		removeCombatant: vi.fn(),
-		editCombatant: vi.fn(),
-		setInitiative: vi.fn(),
-		setHp: vi.fn(),
-		adjustHp: vi.fn(),
-		setTempHp: vi.fn(),
-		hasTempHp: false,
-		setAc: vi.fn(),
-		toggleCondition: vi.fn(),
-		toggleConcentration: vi.fn(),
-		addFromBestiary: vi.fn(),
-		addMultipleFromBestiary: vi.fn(),
-		addFromPlayerCharacter: vi.fn(),
-		makeStore: vi.fn(),
-		withUndo: vi.fn((action: () => unknown) => action()),
-		undo: vi.fn(),
-		redo: vi.fn(),
-		canUndo: false,
-		canRedo: false,
-		undoRedoState: { undoStack: [], redoStack: [] },
-		setEncounter: vi.fn(),
-		setUndoRedoState: vi.fn(),
-		events: [],
-		lastCreatureId: null,
-	};
-
-	mockUseEncounterContext.mockReturnValue(
-		value as ReturnType<typeof useEncounterContext>,
-	);
-	return value;
-}
-
-function renderNav(overrides: Partial<Encounter> = {}) {
-	mockContext(overrides);
-	return render(<TurnNavigation />);
+function renderNav(encounter = buildEncounter()) {
+	const adapters = createTestAdapters({ encounter });
+	return render(<TurnNavigation />, {
+		wrapper: ({ children }: { children: ReactNode }) => (
+			<AllProviders adapters={adapters}>{children}</AllProviders>
+		),
+	});
 }
 
 describe("TurnNavigation", () => {
 	describe("US1: Round badge and combatant name", () => {
 		it("renders the round badge with correct round number", () => {
-			renderNav({ roundNumber: 3 });
+			renderNav(
+				buildEncounter({
+					combatants: [buildCombatant({ name: "Goblin" })],
+					roundNumber: 3,
+				}),
+			);
 			expect(screen.getByText("R3")).toBeInTheDocument();
 		});
 
 		it("renders the combatant name separately from the round badge", () => {
-			renderNav();
+			renderNav(
+				buildEncounter({
+					combatants: [
+						buildCombatant({ id: combatantId("c-1"), name: "Goblin" }),
+						buildCombatant({ id: combatantId("c-2"), name: "Conjurer" }),
+					],
+					activeIndex: 0,
+					roundNumber: 1,
+				}),
+			);
 			const badge = screen.getByText("R1");
 			const name = screen.getByText("Goblin");
 			expect(badge).toBeInTheDocument();
@@ -104,59 +72,45 @@ describe("TurnNavigation", () => {
 		});
 
 		it("does not render an em dash between round and name", () => {
-			const { container } = renderNav();
+			const { container } = renderNav(
+				buildEncounter({
+					combatants: [buildCombatant({ name: "Goblin" })],
+				}),
+			);
 			expect(container.textContent).not.toContain("\u2014");
 		});
 
 		it("round badge and combatant name are siblings in the center area", () => {
-			renderNav();
+			renderNav(
+				buildEncounter({
+					combatants: [buildCombatant({ name: "Goblin" })],
+				}),
+			);
 			const badge = screen.getByText("R1");
 			const name = screen.getByText("Goblin");
-			// badge text is inside inner span > outer span, name is a direct child
 			expect(badge.closest(".flex")).toBe(name.parentElement);
 		});
-
-		it("updates the round badge when round changes", () => {
-			mockContext({ roundNumber: 2 });
-			const { rerender } = render(<TurnNavigation />);
-			expect(screen.getByText("R2")).toBeInTheDocument();
-
-			mockContext({ roundNumber: 3 });
-			rerender(<TurnNavigation />);
-			expect(screen.getByText("R3")).toBeInTheDocument();
-			expect(screen.queryByText("R2")).not.toBeInTheDocument();
-		});
-
-		it("renders the next combatant name when turn advances", () => {
-			const combatants = [
-				{ id: combatantId("1"), name: "Goblin" },
-				{ id: combatantId("2"), name: "Conjurer" },
-			];
-			mockContext({ combatants, activeIndex: 0 });
-			const { rerender } = render(<TurnNavigation />);
-			expect(screen.getByText("Goblin")).toBeInTheDocument();
-
-			mockContext({ combatants, activeIndex: 1 });
-			rerender(<TurnNavigation />);
-			expect(screen.getByText("Conjurer")).toBeInTheDocument();
-		});
 	});
 
 	describe("US2: Layout robustness", () => {
 		it("applies truncation styles to long combatant names", () => {
 			const longName =
 				"Ancient Red Dragon Wyrm of the Northern Wastes and Beyond";
-			renderNav({
-				combatants: [{ id: combatantId("1"), name: longName }],
-			});
+			renderNav(
+				buildEncounter({
+					combatants: [buildCombatant({ name: longName })],
+				}),
+			);
 			const nameEl = screen.getByText(longName);
 			expect(nameEl.className).toContain("truncate");
 		});
 
 		it("renders three-zone layout with a single-character name", () => {
-			renderNav({
-				combatants: [{ id: combatantId("1"), name: "O" }],
-			});
+			renderNav(
+				buildEncounter({
+					combatants: [buildCombatant({ name: "O" })],
+				}),
+			);
 			expect(screen.getByText("R1")).toBeInTheDocument();
 			expect(screen.getByText("O")).toBeInTheDocument();
 			expect(
@@ -169,9 +123,11 @@ describe("TurnNavigation", () => {
 
 		it("keeps all action buttons accessible regardless of name length", () => {
 			const longName = "A".repeat(60);
-			renderNav({
-				combatants: [{ id: combatantId("1"), name: longName }],
-			});
+			renderNav(
+				buildEncounter({
+					combatants: [buildCombatant({ name: longName })],
+				}),
+			);
 			expect(
 				screen.getByRole("button", { name: "Previous turn" }),
 			).toBeInTheDocument();
@@ -182,29 +138,30 @@ describe("TurnNavigation", () => {
 
 		it("renders a 40-character name without truncation class issues", () => {
 			const name40 = "A".repeat(40);
-			renderNav({
-				combatants: [{ id: combatantId("1"), name: name40 }],
-			});
+			renderNav(
+				buildEncounter({
+					combatants: [buildCombatant({ name: name40 })],
+				}),
+			);
 			const nameEl = screen.getByText(name40);
 			expect(nameEl).toBeInTheDocument();
-			// The truncate class is applied but CSS only visually truncates if content overflows
 			expect(nameEl.className).toContain("truncate");
 		});
 	});
 
 	describe("US3: No combatants state", () => {
 		it("shows the round badge when there are no combatants", () => {
-			renderNav({ combatants: [], roundNumber: 1 });
+			renderNav(buildEncounter({ combatants: [], roundNumber: 1 }));
 			expect(screen.getByText("R1")).toBeInTheDocument();
 		});
 
 		it("shows 'No combatants' placeholder text", () => {
-			renderNav({ combatants: [] });
+			renderNav(buildEncounter({ combatants: [] }));
 			expect(screen.getByText("No combatants")).toBeInTheDocument();
 		});
 
 		it("disables navigation buttons when there are no combatants", () => {
-			renderNav({ combatants: [] });
+			renderNav(buildEncounter({ combatants: [] }));
 			expect(
 				screen.getByRole("button", { name: "Previous turn" }),
 			).toBeDisabled();

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

@@ -12,27 +12,20 @@ import {
 	Upload,
 	Users,
 } from "lucide-react";
-import React, { type RefObject, useCallback, useRef, useState } from "react";
+import React, { type RefObject, useCallback, useState } from "react";
 import type { SearchResult } 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 {
 	creatureKey,
 	type QueuedCreature,
 	type SuggestionActions,
 	useActionBarState,
 } from "../hooks/use-action-bar-state.js";
+import { useEncounterExportImport } from "../hooks/use-encounter-export-import.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";
@@ -439,116 +432,23 @@ export function ActionBar({
 	} = useActionBarState();
 
 	const { state: bulkImportState } = useBulkImportContext();
+
 	const {
-		encounter,
-		undoRedoState,
-		isEmpty: encounterIsEmpty,
-		setEncounter,
-		setUndoRedoState,
-	} = useEncounterContext();
-	const { characters: playerCharacters, replacePlayerCharacters } =
-		usePlayerCharactersContext();
-
-	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);
-		},
-		[encounter, undoRedoState, playerCharacters],
-	);
-
-	const handleExportClipboard = useCallback(
-		(includeHistory: boolean) => {
-			const bundle = assembleExportBundle(
-				encounter,
-				undoRedoState,
-				playerCharacters,
-				includeHistory,
-			);
-			void navigator.clipboard.writeText(bundleToJson(bundle));
-		},
-		[encounter, undoRedoState, playerCharacters],
-	);
-
-	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 handleValidatedBundle = useCallback(
-		(result: import("@initiative/domain").ExportBundle | string) => {
-			if (typeof result === "string") {
-				setImportError(result);
-				return;
-			}
-			if (encounterIsEmpty) {
-				applyImport(result);
-			} else {
-				pendingBundleRef.current = result;
-				setShowImportConfirm(true);
-			}
-		},
-		[encounterIsEmpty, applyImport],
-	);
-
-	const handleImportFile = useCallback(
-		async (e: React.ChangeEvent<HTMLInputElement>) => {
-			const file = e.target.files?.[0];
-			if (!file) return;
-			if (importFileRef.current) importFileRef.current.value = "";
-
-			setImportError(null);
-			handleValidatedBundle(await readImportFile(file));
-		},
-		[handleValidatedBundle],
-	);
-
-	const handleImportClipboard = useCallback(
-		(text: string) => {
-			setImportError(null);
-			try {
-				const parsed: unknown = JSON.parse(text);
-				handleValidatedBundle(validateImportBundle(parsed));
-			} catch {
-				setImportError("Invalid file format");
-			}
-		},
-		[handleValidatedBundle],
-	);
-
-	const handleImportConfirm = useCallback(() => {
-		if (pendingBundleRef.current) {
-			applyImport(pendingBundleRef.current);
-			pendingBundleRef.current = null;
-		}
-		setShowImportConfirm(false);
-	}, [applyImport]);
-
-	const handleImportCancel = useCallback(() => {
-		pendingBundleRef.current = null;
-		setShowImportConfirm(false);
-	}, []);
+		importError,
+		showExportMethod,
+		showImportMethod,
+		showImportConfirm,
+		importFileRef,
+		setImportError,
+		setShowExportMethod,
+		setShowImportMethod,
+		handleExportDownload,
+		handleExportClipboard,
+		handleImportFile,
+		handleImportClipboard,
+		handleImportConfirm,
+		handleImportCancel,
+	} = useEncounterExportImport();
 
 	const overflowItems = buildOverflowItems({
 		onManagePlayers,

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

@@ -1,6 +1,6 @@
 import { Loader2 } from "lucide-react";
 import { useId, useState } from "react";
-import { getAllSourceCodes } from "../adapters/bestiary-index-adapter.js";
+import { useAdapters } from "../contexts/adapter-context.js";
 import { useBestiaryContext } from "../contexts/bestiary-context.js";
 import { useBulkImportContext } from "../contexts/bulk-import-context.js";
 import { useSidePanelContext } from "../contexts/side-panel-context.js";
@@ -11,6 +11,7 @@ const DEFAULT_BASE_URL =
 	"https://raw.githubusercontent.com/5etools-mirror-3/5etools-src/main/data/bestiary/";
 
 export function BulkImportPrompt() {
+	const { bestiaryIndex } = useAdapters();
 	const { fetchAndCacheSource, isSourceCached, refreshCache } =
 		useBestiaryContext();
 	const { state: importState, startImport, reset } = useBulkImportContext();
@@ -18,7 +19,7 @@ export function BulkImportPrompt() {
 
 	const [baseUrl, setBaseUrl] = useState(DEFAULT_BASE_URL);
 	const baseUrlId = useId();
-	const totalSources = getAllSourceCodes().length;
+	const totalSources = bestiaryIndex.getAllSourceCodes().length;
 
 	const handleStart = (url: string) => {
 		startImport(url, fetchAndCacheSource, isSourceCached, refreshCache);

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

@@ -0,0 +1,36 @@
+import { VALID_CR_VALUES } from "@initiative/domain";
+
+const CR_LABELS: Record<string, string> = {
+	"0": "CR 0",
+	"1/8": "CR 1/8",
+	"1/4": "CR 1/4",
+	"1/2": "CR 1/2",
+};
+
+function formatCr(cr: string): string {
+	return CR_LABELS[cr] ?? `CR ${cr}`;
+}
+
+export function CrPicker({
+	value,
+	onChange,
+}: {
+	value: string | null;
+	onChange: (cr: string | undefined) => void;
+}) {
+	return (
+		<select
+			className="rounded border border-border bg-card px-1.5 py-0.5 text-xs"
+			value={value ?? ""}
+			onChange={(e) => onChange(e.target.value || undefined)}
+			aria-label="Challenge rating"
+		>
+			<option value="">Assign</option>
+			{VALID_CR_VALUES.map((cr) => (
+				<option key={cr} value={cr}>
+					{formatCr(cr)}
+				</option>
+			))}
+		</select>
+	);
+}

apps/web/src/components/difficulty-breakdown-panel.tsx

@@ -0,0 +1,109 @@
+import type { DifficultyTier } from "@initiative/domain";
+import { useRef } from "react";
+import { useEncounterContext } from "../contexts/encounter-context.js";
+import { useClickOutside } from "../hooks/use-click-outside.js";
+import {
+	type BreakdownCombatant,
+	useDifficultyBreakdown,
+} from "../hooks/use-difficulty-breakdown.js";
+import { CrPicker } from "./cr-picker.js";
+
+const TIER_LABELS: Record<DifficultyTier, { label: string; color: string }> = {
+	trivial: { label: "Trivial", color: "text-muted-foreground" },
+	low: { label: "Low", color: "text-green-500" },
+	moderate: { label: "Moderate", color: "text-yellow-500" },
+	high: { label: "High", color: "text-red-500" },
+};
+
+function formatXp(xp: number): string {
+	return xp.toLocaleString();
+}
+
+function CombatantRow({ entry }: { entry: BreakdownCombatant }) {
+	const { setCr } = useEncounterContext();
+
+	const nameLabel = entry.source
+		? `${entry.combatant.name} (${entry.source})`
+		: entry.combatant.name;
+
+	return (
+		<div className="flex items-center justify-between gap-2 text-xs">
+			<span className="min-w-0 truncate" title={nameLabel}>
+				{nameLabel}
+			</span>
+			<div className="flex shrink-0 items-center gap-2">
+				{entry.editable ? (
+					<CrPicker
+						value={entry.cr}
+						onChange={(cr) => setCr(entry.combatant.id, cr)}
+					/>
+				) : (
+					<span className="text-muted-foreground">
+						{entry.cr ? `CR ${entry.cr}` : "—"}
+					</span>
+				)}
+				<span className="w-12 text-right tabular-nums">
+					{entry.xp == null ? "—" : formatXp(entry.xp)}
+				</span>
+			</div>
+		</div>
+	);
+}
+
+export function DifficultyBreakdownPanel({ onClose }: { onClose: () => void }) {
+	const ref = useRef<HTMLDivElement>(null);
+	useClickOutside(ref, onClose);
+
+	const breakdown = useDifficultyBreakdown();
+	if (!breakdown) return null;
+
+	const tierConfig = TIER_LABELS[breakdown.tier];
+
+	return (
+		<div
+			ref={ref}
+			className="absolute top-full right-0 z-50 mt-1 w-72 rounded-lg border border-border bg-card p-3 shadow-lg"
+		>
+			<div className="mb-2 font-medium text-sm">
+				Encounter Difficulty:{" "}
+				<span className={tierConfig.color}>{tierConfig.label}</span>
+			</div>
+
+			<div className="mb-2 border-border border-t pt-2">
+				<div className="mb-1 text-muted-foreground text-xs">
+					Party Budget ({breakdown.pcCount}{" "}
+					{breakdown.pcCount === 1 ? "PC" : "PCs"})
+				</div>
+				<div className="flex gap-3 text-xs">
+					<span>
+						Low: <strong>{formatXp(breakdown.partyBudget.low)}</strong>
+					</span>
+					<span>
+						Mod: <strong>{formatXp(breakdown.partyBudget.moderate)}</strong>
+					</span>
+					<span>
+						High: <strong>{formatXp(breakdown.partyBudget.high)}</strong>
+					</span>
+				</div>
+			</div>
+
+			<div className="border-border border-t pt-2">
+				<div className="mb-1 flex justify-between text-muted-foreground text-xs">
+					<span>Monsters</span>
+					<span>XP</span>
+				</div>
+				<div className="flex flex-col gap-1">
+					{breakdown.combatants.map((entry) => (
+						<CombatantRow key={entry.combatant.id} entry={entry} />
+					))}
+				</div>
+				<div className="mt-2 flex justify-between border-border border-t pt-2 font-medium text-xs">
+					<span>Total Monster XP</span>
+					<span className="tabular-nums">
+						{formatXp(breakdown.totalMonsterXp)}
+					</span>
+				</div>
+			</div>
+		</div>
+	);
+}

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

@@ -13,16 +13,29 @@ const TIER_CONFIG: Record<
 
 const BAR_HEIGHTS = ["h-2", "h-3", "h-4"] as const;
 
-export function DifficultyIndicator({ result }: { result: DifficultyResult }) {
+export function DifficultyIndicator({
+	result,
+	onClick,
+}: {
+	result: DifficultyResult;
+	onClick?: () => void;
+}) {
 	const config = TIER_CONFIG[result.tier];
 	const tooltip = `${config.label} encounter difficulty`;
 
+	const Element = onClick ? "button" : "div";
+
 	return (
-		<div
-			className="flex items-end gap-0.5"
+		<Element
+			className={cn(
+				"flex items-end gap-0.5",
+				onClick && "cursor-pointer rounded p-1 hover:bg-muted/50",
+			)}
 			title={tooltip}
 			role="img"
 			aria-label={tooltip}
+			onClick={onClick}
+			type={onClick ? "button" : undefined}
 		>
 			{BAR_HEIGHTS.map((height, i) => (
 				<div
@@ -34,6 +47,6 @@ export function DifficultyIndicator({ result }: { result: DifficultyResult }) {
 					)}
 				/>
 			))}
-		</div>
+		</Element>
 	);
 }

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

@@ -1,9 +1,6 @@
 import { Download, Loader2, Upload } from "lucide-react";
 import { useId, useRef, useState } from "react";
-import {
-	getDefaultFetchUrl,
-	getSourceDisplayName,
-} from "../adapters/bestiary-index-adapter.js";
+import { useAdapters } from "../contexts/adapter-context.js";
 import { useBestiaryContext } from "../contexts/bestiary-context.js";
 import { Button } from "./ui/button.js";
 import { Input } from "./ui/input.js";
@@ -17,9 +14,12 @@ export function SourceFetchPrompt({
 	sourceCode,
 	onSourceLoaded,
 }: Readonly<SourceFetchPromptProps>) {
+	const { bestiaryIndex } = useAdapters();
 	const { fetchAndCacheSource, uploadAndCacheSource } = useBestiaryContext();
-	const sourceDisplayName = getSourceDisplayName(sourceCode);
-	const [url, setUrl] = useState(() => getDefaultFetchUrl(sourceCode));
+	const sourceDisplayName = bestiaryIndex.getSourceDisplayName(sourceCode);
+	const [url, setUrl] = useState(() =>
+		bestiaryIndex.getDefaultFetchUrl(sourceCode),
+	);
 	const [status, setStatus] = useState<"idle" | "fetching" | "error">("idle");
 	const [error, setError] = useState<string>("");
 	const fileInputRef = useRef<HTMLInputElement>(null);

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

@@ -6,13 +6,14 @@ import {
 	useOptimistic,
 	useState,
 } from "react";
-import type { CachedSourceInfo } from "../adapters/bestiary-cache.js";
-import * as bestiaryCache from "../adapters/bestiary-cache.js";
+import type { CachedSourceInfo } from "../adapters/ports.js";
+import { useAdapters } from "../contexts/adapter-context.js";
 import { useBestiaryContext } from "../contexts/bestiary-context.js";
 import { Button } from "./ui/button.js";
 import { Input } from "./ui/input.js";
 
 export function SourceManager() {
+	const { bestiaryCache } = useAdapters();
 	const { refreshCache } = useBestiaryContext();
 	const [sources, setSources] = useState<CachedSourceInfo[]>([]);
 	const [filter, setFilter] = useState("");
@@ -30,7 +31,7 @@ export function SourceManager() {
 	const loadSources = useCallback(async () => {
 		const cached = await bestiaryCache.getCachedSources();
 		setSources(cached);
-	}, []);
+	}, [bestiaryCache]);
 
 	useEffect(() => {
 		void loadSources();

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

@@ -1,6 +1,8 @@
 import { Redo2, StepBack, StepForward, Trash2, Undo2 } from "lucide-react";
+import { useState } from "react";
 import { useEncounterContext } from "../contexts/encounter-context.js";
 import { useDifficulty } from "../hooks/use-difficulty.js";
+import { DifficultyBreakdownPanel } from "./difficulty-breakdown-panel.js";
 import { DifficultyIndicator } from "./difficulty-indicator.js";
 import { Button } from "./ui/button.js";
 import { ConfirmButton } from "./ui/confirm-button.js";
@@ -18,6 +20,7 @@ export function TurnNavigation() {
 	} = useEncounterContext();
 
 	const difficulty = useDifficulty();
+	const [showBreakdown, setShowBreakdown] = useState(false);
 	const hasCombatants = encounter.combatants.length > 0;
 	const isAtStart = encounter.roundNumber === 1 && encounter.activeIndex === 0;
 	const activeCombatant = encounter.combatants[encounter.activeIndex];
@@ -69,7 +72,19 @@ export function TurnNavigation() {
 				) : (
 					<span className="text-muted-foreground">No combatants</span>
 				)}
-				{difficulty && <DifficultyIndicator result={difficulty} />}
+				{difficulty && (
+					<div className="relative">
+						<DifficultyIndicator
+							result={difficulty}
+							onClick={() => setShowBreakdown((prev) => !prev)}
+						/>
+						{showBreakdown ? (
+							<DifficultyBreakdownPanel
+								onClose={() => setShowBreakdown(false)}
+							/>
+						) : null}
+					</div>
+				)}
 			</div>
 
 			<div className="flex flex-shrink-0 items-center gap-3">

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

@@ -0,0 +1,38 @@
+import { createContext, type ReactNode, useContext } from "react";
+import type {
+	BestiaryCachePort,
+	BestiaryIndexPort,
+	EncounterPersistence,
+	PlayerCharacterPersistence,
+	UndoRedoPersistence,
+} from "../adapters/ports.js";
+
+export interface Adapters {
+	encounterPersistence: EncounterPersistence;
+	undoRedoPersistence: UndoRedoPersistence;
+	playerCharacterPersistence: PlayerCharacterPersistence;
+	bestiaryCache: BestiaryCachePort;
+	bestiaryIndex: BestiaryIndexPort;
+}
+
+const AdapterContext = createContext<Adapters | null>(null);
+
+export function AdapterProvider({
+	adapters,
+	children,
+}: {
+	adapters: Adapters;
+	children: ReactNode;
+}) {
+	return (
+		<AdapterContext.Provider value={adapters}>
+			{children}
+		</AdapterContext.Provider>
+	);
+}
+
+export function useAdapters(): Adapters {
+	const ctx = useContext(AdapterContext);
+	if (!ctx) throw new Error("useAdapters requires AdapterProvider");
+	return ctx;
+}

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

@@ -10,19 +10,9 @@ import {
 	isDomainError,
 	playerCharacterId,
 } from "@initiative/domain";
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
 import { type EncounterState, encounterReducer } from "../use-encounter.js";
 
-vi.mock("../../persistence/encounter-storage.js", () => ({
-	loadEncounter: vi.fn().mockReturnValue(null),
-	saveEncounter: vi.fn(),
-}));
-
-vi.mock("../../persistence/undo-redo-storage.js", () => ({
-	loadUndoRedoStacks: vi.fn().mockReturnValue(EMPTY_UNDO_REDO_STATE),
-	saveUndoRedoStacks: vi.fn(),
-}));
-
 function emptyState(): EncounterState {
 	return {
 		encounter: {

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

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

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

@@ -1,15 +1,38 @@
 // @vitest-environment jsdom
 import { act, renderHook } from "@testing-library/react";
-import { describe, expect, it, vi } from "vitest";
+import type { ReactNode } from "react";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+import { createTestAdapters } from "../../__tests__/adapters/in-memory-adapters.js";
+import { AllProviders } from "../../__tests__/test-providers.js";
 import { useBulkImport } from "../use-bulk-import.js";
 
-vi.mock("../../adapters/bestiary-index-adapter.js", () => ({
+beforeAll(() => {
+	Object.defineProperty(globalThis, "matchMedia", {
+		writable: true,
+		value: vi.fn().mockImplementation((query: string) => ({
+			matches: false,
+			media: query,
+			onchange: null,
+			addListener: vi.fn(),
+			removeListener: vi.fn(),
+			addEventListener: vi.fn(),
+			removeEventListener: vi.fn(),
+			dispatchEvent: vi.fn(),
+		})),
+	});
+});
+
+const adapters = createTestAdapters();
+adapters.bestiaryIndex = {
+	...adapters.bestiaryIndex,
 	getAllSourceCodes: () => ["MM", "VGM", "XGE"],
-	getDefaultFetchUrl: (code: string, baseUrl: string) =>
+	getDefaultFetchUrl: (code: string, baseUrl?: string) =>
 		`${baseUrl}${code}.json`,
-	loadBestiaryIndex: () => ({ sources: {}, creatures: [] }),
-	getSourceDisplayName: (code: string) => code,
-}));
+};
+
+function wrapper({ children }: { children: ReactNode }) {
+	return <AllProviders adapters={adapters}>{children}</AllProviders>;
+}
 
 /** Flush microtasks so the internal async IIFE inside startImport settles. */
 function flushMicrotasks(): Promise<void> {
@@ -20,7 +43,7 @@ function flushMicrotasks(): Promise<void> {
 
 describe("useBulkImport", () => {
 	it("starts in idle state with all counters at 0", () => {
-		const { result } = renderHook(() => useBulkImport());
+		const { result } = renderHook(() => useBulkImport(), { wrapper });
 		expect(result.current.state).toEqual({
 			status: "idle",
 			total: 0,
@@ -30,7 +53,7 @@ describe("useBulkImport", () => {
 	});
 
 	it("reset returns to idle state", async () => {
-		const { result } = renderHook(() => useBulkImport());
+		const { result } = renderHook(() => useBulkImport(), { wrapper });
 
 		const isSourceCached = vi.fn().mockResolvedValue(true);
 		const fetchAndCacheSource = vi.fn();
@@ -51,7 +74,7 @@ describe("useBulkImport", () => {
 	});
 
 	it("goes straight to complete when all sources are cached", async () => {
-		const { result } = renderHook(() => useBulkImport());
+		const { result } = renderHook(() => useBulkImport(), { wrapper });
 
 		const isSourceCached = vi.fn().mockResolvedValue(true);
 		const fetchAndCacheSource = vi.fn();
@@ -73,7 +96,7 @@ describe("useBulkImport", () => {
 	});
 
 	it("fetches uncached sources and completes", async () => {
-		const { result } = renderHook(() => useBulkImport());
+		const { result } = renderHook(() => useBulkImport(), { wrapper });
 
 		const isSourceCached = vi.fn().mockResolvedValue(false);
 		const fetchAndCacheSource = vi.fn().mockResolvedValue(undefined);
@@ -97,7 +120,7 @@ describe("useBulkImport", () => {
 	});
 
 	it("reports partial-failure when some sources fail", async () => {
-		const { result } = renderHook(() => useBulkImport());
+		const { result } = renderHook(() => useBulkImport(), { wrapper });
 
 		const isSourceCached = vi.fn().mockResolvedValue(false);
 		const fetchAndCacheSource = vi
@@ -124,7 +147,7 @@ describe("useBulkImport", () => {
 	});
 
 	it("calls refreshCache after all batches complete", async () => {
-		const { result } = renderHook(() => useBulkImport());
+		const { result } = renderHook(() => useBulkImport(), { wrapper });
 
 		const isSourceCached = vi.fn().mockResolvedValue(false);
 		const fetchAndCacheSource = vi.fn().mockResolvedValue(undefined);

apps/web/src/hooks/__tests__/use-difficulty-breakdown.test.tsx

@@ -0,0 +1,246 @@
+// @vitest-environment jsdom
+import type { Creature, CreatureId, PlayerCharacter } from "@initiative/domain";
+import { combatantId, creatureId, playerCharacterId } from "@initiative/domain";
+import { renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+import { createTestAdapters } from "../../__tests__/adapters/in-memory-adapters.js";
+import {
+	buildCombatant,
+	buildCreature,
+	buildEncounter,
+} from "../../__tests__/factories/index.js";
+import { AllProviders } from "../../__tests__/test-providers.js";
+import { useDifficultyBreakdown } from "../use-difficulty-breakdown.js";
+
+beforeAll(() => {
+	Object.defineProperty(globalThis, "matchMedia", {
+		writable: true,
+		value: vi.fn().mockImplementation((query: string) => ({
+			matches: false,
+			media: query,
+			onchange: null,
+			addListener: vi.fn(),
+			removeListener: vi.fn(),
+			addEventListener: vi.fn(),
+			removeEventListener: vi.fn(),
+			dispatchEvent: vi.fn(),
+		})),
+	});
+});
+
+const pcId1 = playerCharacterId("pc-1");
+const goblinCreature = buildCreature({
+	id: creatureId("srd:goblin"),
+	name: "Goblin",
+	cr: "1/4",
+	source: "srd",
+	sourceDisplayName: "SRD",
+});
+
+function makeWrapper(options: {
+	encounter: ReturnType<typeof buildEncounter>;
+	playerCharacters?: PlayerCharacter[];
+	creatures?: Map<CreatureId, Creature>;
+}) {
+	const adapters = createTestAdapters({
+		encounter: options.encounter,
+		playerCharacters: options.playerCharacters ?? [],
+		creatures: options.creatures,
+	});
+	return ({ children }: { children: ReactNode }) => (
+		<AllProviders adapters={adapters}>{children}</AllProviders>
+	);
+}
+
+describe("useDifficultyBreakdown", () => {
+	it("returns null when no leveled PCs", () => {
+		const wrapper = makeWrapper({
+			encounter: buildEncounter({
+				combatants: [
+					buildCombatant({
+						id: combatantId("c-1"),
+						name: "Hero",
+						playerCharacterId: pcId1,
+					}),
+					buildCombatant({
+						id: combatantId("c-2"),
+						name: "Goblin",
+						creatureId: goblinCreature.id,
+					}),
+				],
+			}),
+			playerCharacters: [{ id: pcId1, name: "Hero", ac: 15, maxHp: 30 }],
+			creatures: new Map([[goblinCreature.id, goblinCreature]]),
+		});
+
+		const { result } = renderHook(() => useDifficultyBreakdown(), {
+			wrapper,
+		});
+		expect(result.current).toBeNull();
+	});
+
+	it("returns null when no monsters with CR", () => {
+		const wrapper = makeWrapper({
+			encounter: buildEncounter({
+				combatants: [
+					buildCombatant({
+						id: combatantId("c-1"),
+						name: "Hero",
+						playerCharacterId: pcId1,
+					}),
+					buildCombatant({
+						id: combatantId("c-2"),
+						name: "Custom",
+					}),
+				],
+			}),
+			playerCharacters: [
+				{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 },
+			],
+		});
+
+		const { result } = renderHook(() => useDifficultyBreakdown(), {
+			wrapper,
+		});
+		expect(result.current).toBeNull();
+	});
+
+	it("returns per-combatant entries with correct data", async () => {
+		const wrapper = makeWrapper({
+			encounter: buildEncounter({
+				combatants: [
+					buildCombatant({
+						id: combatantId("c-1"),
+						name: "Hero",
+						playerCharacterId: pcId1,
+					}),
+					buildCombatant({
+						id: combatantId("c-2"),
+						name: "Goblin",
+						creatureId: goblinCreature.id,
+					}),
+					buildCombatant({
+						id: combatantId("c-3"),
+						name: "Custom Thug",
+						cr: "2",
+					}),
+					buildCombatant({
+						id: combatantId("c-4"),
+						name: "Bandit",
+					}),
+				],
+			}),
+			playerCharacters: [
+				{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 },
+			],
+			creatures: new Map([[goblinCreature.id, goblinCreature]]),
+		});
+
+		const { result } = renderHook(() => useDifficultyBreakdown(), {
+			wrapper,
+		});
+
+		await waitFor(() => {
+			const breakdown = result.current;
+			expect(breakdown).not.toBeNull();
+			expect(breakdown?.pcCount).toBe(1);
+			// CR 1/4 = 50 + CR 2 = 450 → total 500
+			expect(breakdown?.totalMonsterXp).toBe(500);
+			expect(breakdown?.combatants).toHaveLength(3);
+
+			// Bestiary combatant
+			const goblin = breakdown?.combatants[0];
+			expect(goblin?.cr).toBe("1/4");
+			expect(goblin?.xp).toBe(50);
+			expect(goblin?.source).toBe("SRD");
+			expect(goblin?.editable).toBe(false);
+
+			// Custom with CR
+			const thug = breakdown?.combatants[1];
+			expect(thug?.cr).toBe("2");
+			expect(thug?.xp).toBe(450);
+			expect(thug?.source).toBeNull();
+			expect(thug?.editable).toBe(true);
+
+			// Custom without CR
+			const bandit = breakdown?.combatants[2];
+			expect(bandit?.cr).toBeNull();
+			expect(bandit?.xp).toBeNull();
+			expect(bandit?.source).toBeNull();
+			expect(bandit?.editable).toBe(true);
+		});
+	});
+
+	it("bestiary combatant with missing creature is non-editable with null CR", () => {
+		const missingCreatureId = creatureId("creature-missing");
+		const wrapper = makeWrapper({
+			encounter: buildEncounter({
+				combatants: [
+					buildCombatant({
+						id: combatantId("c-1"),
+						name: "Hero",
+						playerCharacterId: pcId1,
+					}),
+					buildCombatant({
+						id: combatantId("c-2"),
+						name: "Ghost",
+						creatureId: missingCreatureId,
+					}),
+					buildCombatant({
+						id: combatantId("c-3"),
+						name: "Thug",
+						cr: "1",
+					}),
+				],
+			}),
+			playerCharacters: [
+				{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 },
+			],
+		});
+
+		const { result } = renderHook(() => useDifficultyBreakdown(), {
+			wrapper,
+		});
+
+		// With no bestiary creatures loaded, the Ghost has null CR
+		const breakdown = result.current;
+		expect(breakdown).not.toBeNull();
+		const ghost = breakdown?.combatants[0];
+		expect(ghost?.cr).toBeNull();
+		expect(ghost?.xp).toBeNull();
+		expect(ghost?.editable).toBe(false);
+	});
+
+	it("excludes PC combatants from breakdown entries", async () => {
+		const wrapper = makeWrapper({
+			encounter: buildEncounter({
+				combatants: [
+					buildCombatant({
+						id: combatantId("c-1"),
+						name: "Hero",
+						playerCharacterId: pcId1,
+					}),
+					buildCombatant({
+						id: combatantId("c-2"),
+						name: "Goblin",
+						creatureId: goblinCreature.id,
+					}),
+				],
+			}),
+			playerCharacters: [
+				{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 1 },
+			],
+			creatures: new Map([[goblinCreature.id, goblinCreature]]),
+		});
+
+		const { result } = renderHook(() => useDifficultyBreakdown(), {
+			wrapper,
+		});
+
+		await waitFor(() => {
+			expect(result.current?.combatants).toHaveLength(1);
+			expect(result.current?.combatants[0].combatant.name).toBe("Goblin");
+		});
+	});
+});

apps/web/src/hooks/__tests__/use-difficulty-custom-cr.test.tsx

@@ -0,0 +1,173 @@
+// @vitest-environment jsdom
+import type { Creature, CreatureId, PlayerCharacter } from "@initiative/domain";
+import { combatantId, creatureId, playerCharacterId } from "@initiative/domain";
+import { renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+import { createTestAdapters } from "../../__tests__/adapters/in-memory-adapters.js";
+import {
+	buildCombatant,
+	buildCreature,
+	buildEncounter,
+} from "../../__tests__/factories/index.js";
+import { AllProviders } from "../../__tests__/test-providers.js";
+import { useDifficulty } from "../use-difficulty.js";
+
+beforeAll(() => {
+	Object.defineProperty(globalThis, "matchMedia", {
+		writable: true,
+		value: vi.fn().mockImplementation((query: string) => ({
+			matches: false,
+			media: query,
+			onchange: null,
+			addListener: vi.fn(),
+			removeListener: vi.fn(),
+			addEventListener: vi.fn(),
+			removeEventListener: vi.fn(),
+			dispatchEvent: vi.fn(),
+		})),
+	});
+});
+
+const pcId1 = playerCharacterId("pc-1");
+const goblinCreature = buildCreature({
+	id: creatureId("srd:goblin"),
+	name: "Goblin",
+	cr: "1/4",
+});
+
+function makeWrapper(options: {
+	encounter: ReturnType<typeof buildEncounter>;
+	playerCharacters?: PlayerCharacter[];
+	creatures?: Map<CreatureId, Creature>;
+}) {
+	const adapters = createTestAdapters({
+		encounter: options.encounter,
+		playerCharacters: options.playerCharacters ?? [],
+		creatures: options.creatures,
+	});
+	return ({ children }: { children: ReactNode }) => (
+		<AllProviders adapters={adapters}>{children}</AllProviders>
+	);
+}
+
+describe("useDifficulty with custom combatant CRs", () => {
+	it("includes custom combatant with cr field in monster XP", () => {
+		const wrapper = makeWrapper({
+			encounter: buildEncounter({
+				combatants: [
+					buildCombatant({
+						id: combatantId("c-1"),
+						name: "Hero",
+						playerCharacterId: pcId1,
+					}),
+					buildCombatant({
+						id: combatantId("c-2"),
+						name: "Custom Thug",
+						cr: "2",
+					}),
+				],
+			}),
+			playerCharacters: [
+				{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 1 },
+			],
+		});
+
+		const { result } = renderHook(() => useDifficulty(), { wrapper });
+
+		expect(result.current).not.toBeNull();
+		expect(result.current?.totalMonsterXp).toBe(450);
+	});
+
+	it("uses bestiary CR when combatant has both creatureId and cr", async () => {
+		const wrapper = makeWrapper({
+			encounter: buildEncounter({
+				combatants: [
+					buildCombatant({
+						id: combatantId("c-1"),
+						name: "Hero",
+						playerCharacterId: pcId1,
+					}),
+					buildCombatant({
+						id: combatantId("c-2"),
+						name: "Goblin",
+						creatureId: goblinCreature.id,
+						cr: "5",
+					}),
+				],
+			}),
+			playerCharacters: [
+				{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 1 },
+			],
+			creatures: new Map([[goblinCreature.id, goblinCreature]]),
+		});
+
+		const { result } = renderHook(() => useDifficulty(), { wrapper });
+
+		await waitFor(() => {
+			expect(result.current).not.toBeNull();
+			// Should use bestiary CR 1/4 (50 XP), not the manual cr "5" (1800 XP)
+			expect(result.current?.totalMonsterXp).toBe(50);
+		});
+	});
+
+	it("mixes bestiary and custom-with-CR combatants correctly", async () => {
+		const wrapper = makeWrapper({
+			encounter: buildEncounter({
+				combatants: [
+					buildCombatant({
+						id: combatantId("c-1"),
+						name: "Hero",
+						playerCharacterId: pcId1,
+					}),
+					buildCombatant({
+						id: combatantId("c-2"),
+						name: "Goblin",
+						creatureId: goblinCreature.id,
+					}),
+					buildCombatant({
+						id: combatantId("c-3"),
+						name: "Custom",
+						cr: "1",
+					}),
+				],
+			}),
+			playerCharacters: [
+				{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 },
+			],
+			creatures: new Map([[goblinCreature.id, goblinCreature]]),
+		});
+
+		const { result } = renderHook(() => useDifficulty(), { wrapper });
+
+		await waitFor(() => {
+			expect(result.current).not.toBeNull();
+			// CR 1/4 = 50 XP, CR 1 = 200 XP → total 250
+			expect(result.current?.totalMonsterXp).toBe(250);
+		});
+	});
+
+	it("custom combatant without CR is still excluded", () => {
+		const wrapper = makeWrapper({
+			encounter: buildEncounter({
+				combatants: [
+					buildCombatant({
+						id: combatantId("c-1"),
+						name: "Hero",
+						playerCharacterId: pcId1,
+					}),
+					buildCombatant({
+						id: combatantId("c-2"),
+						name: "Custom Monster",
+					}),
+				],
+			}),
+			playerCharacters: [
+				{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 1 },
+			],
+		});
+
+		const { result } = renderHook(() => useDifficulty(), { wrapper });
+		expect(result.current).toBeNull();
+	});
+});

apps/web/src/hooks/__tests__/use-encounter-export-import.test.tsx

@@ -0,0 +1,234 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+
+import type { ExportBundle } from "@initiative/domain";
+import { combatantId, playerCharacterId } from "@initiative/domain";
+import { act, renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+import { createTestAdapters } from "../../__tests__/adapters/in-memory-adapters.js";
+import {
+	buildCombatant,
+	buildEncounter,
+} from "../../__tests__/factories/index.js";
+import { AllProviders } from "../../__tests__/test-providers.js";
+import { useEncounterContext } from "../../contexts/encounter-context.js";
+import { useEncounterExportImport } from "../use-encounter-export-import.js";
+
+beforeAll(() => {
+	Object.defineProperty(globalThis, "matchMedia", {
+		writable: true,
+		value: vi.fn().mockImplementation((query: string) => ({
+			matches: false,
+			media: query,
+			onchange: null,
+			addListener: vi.fn(),
+			removeListener: vi.fn(),
+			addEventListener: vi.fn(),
+			removeEventListener: vi.fn(),
+			dispatchEvent: vi.fn(),
+		})),
+	});
+});
+
+function wrapper({ children }: { children: ReactNode }) {
+	return <AllProviders>{children}</AllProviders>;
+}
+
+function wrapperWithEncounter(encounter: ReturnType<typeof buildEncounter>) {
+	const adapters = createTestAdapters({ encounter });
+	return function Wrapper({ children }: { children: ReactNode }) {
+		return <AllProviders adapters={adapters}>{children}</AllProviders>;
+	};
+}
+
+const VALID_BUNDLE: ExportBundle = {
+	version: 1,
+	exportedAt: "2026-01-01T00:00:00.000Z",
+	encounter: buildEncounter({
+		combatants: [buildCombatant({ id: combatantId("c-1"), name: "Imported" })],
+	}),
+	undoStack: [],
+	redoStack: [],
+	playerCharacters: [
+		{
+			id: playerCharacterId("pc-1"),
+			name: "Hero",
+			ac: 16,
+			maxHp: 30,
+		},
+	],
+};
+
+describe("useEncounterExportImport", () => {
+	describe("import via clipboard", () => {
+		it("imports valid JSON into empty encounter without error", () => {
+			const { result } = renderHook(() => useEncounterExportImport(), {
+				wrapper,
+			});
+
+			act(() => {
+				result.current.handleImportClipboard(JSON.stringify(VALID_BUNDLE));
+			});
+
+			// Import should succeed without error and not show confirm
+			expect(result.current.importError).toBeNull();
+			expect(result.current.showImportConfirm).toBe(false);
+		});
+
+		it("sets error for invalid JSON", () => {
+			const { result } = renderHook(() => useEncounterExportImport(), {
+				wrapper,
+			});
+
+			act(() => {
+				result.current.handleImportClipboard("not json{{{");
+			});
+
+			expect(result.current.importError).toBe("Invalid file format");
+		});
+
+		it("sets error for valid JSON that fails validation", () => {
+			const { result } = renderHook(() => useEncounterExportImport(), {
+				wrapper,
+			});
+
+			act(() => {
+				result.current.handleImportClipboard(JSON.stringify({ version: 999 }));
+			});
+
+			expect(result.current.importError).toBe("Invalid file format");
+		});
+
+		it("shows confirm dialog when encounter is not empty", () => {
+			const encounter = buildEncounter({
+				combatants: [
+					buildCombatant({ id: combatantId("c-1"), name: "Existing" }),
+				],
+			});
+
+			const { result } = renderHook(() => useEncounterExportImport(), {
+				wrapper: wrapperWithEncounter(encounter),
+			});
+
+			act(() => {
+				result.current.handleImportClipboard(JSON.stringify(VALID_BUNDLE));
+			});
+
+			expect(result.current.showImportConfirm).toBe(true);
+			expect(result.current.importError).toBeNull();
+		});
+
+		it("handleImportConfirm clears confirm dialog", () => {
+			const encounter = buildEncounter({
+				combatants: [
+					buildCombatant({ id: combatantId("c-1"), name: "Existing" }),
+				],
+			});
+
+			const { result } = renderHook(() => useEncounterExportImport(), {
+				wrapper: wrapperWithEncounter(encounter),
+			});
+
+			act(() => {
+				result.current.handleImportClipboard(JSON.stringify(VALID_BUNDLE));
+			});
+
+			expect(result.current.showImportConfirm).toBe(true);
+
+			act(() => {
+				result.current.handleImportConfirm();
+			});
+
+			expect(result.current.showImportConfirm).toBe(false);
+		});
+
+		it("handleImportCancel clears pending without applying", () => {
+			const encounter = buildEncounter({
+				combatants: [
+					buildCombatant({ id: combatantId("c-1"), name: "Existing" }),
+				],
+			});
+
+			const { result } = renderHook(
+				() => ({
+					exportImport: useEncounterExportImport(),
+					encounter: useEncounterContext(),
+				}),
+				{ wrapper: wrapperWithEncounter(encounter) },
+			);
+
+			act(() => {
+				result.current.exportImport.handleImportClipboard(
+					JSON.stringify(VALID_BUNDLE),
+				);
+			});
+
+			act(() => {
+				result.current.exportImport.handleImportCancel();
+			});
+
+			expect(result.current.exportImport.showImportConfirm).toBe(false);
+			expect(result.current.encounter.encounter.combatants[0].name).toBe(
+				"Existing",
+			);
+		});
+	});
+
+	describe("export", () => {
+		it("handleExportDownload calls triggerDownload", () => {
+			const encounter = buildEncounter({
+				combatants: [
+					buildCombatant({ id: combatantId("c-1"), name: "Fighter" }),
+				],
+			});
+
+			const { result } = renderHook(() => useEncounterExportImport(), {
+				wrapper: wrapperWithEncounter(encounter),
+			});
+
+			// triggerDownload creates a blob URL and clicks an anchor — just verify it doesn't throw
+			expect(() => {
+				act(() => {
+					result.current.handleExportDownload(false, "test-export.json");
+				});
+			}).not.toThrow();
+		});
+	});
+
+	describe("dialog state", () => {
+		it("toggles export method dialog", () => {
+			const { result } = renderHook(() => useEncounterExportImport(), {
+				wrapper,
+			});
+
+			expect(result.current.showExportMethod).toBe(false);
+			act(() => result.current.setShowExportMethod(true));
+			expect(result.current.showExportMethod).toBe(true);
+		});
+
+		it("toggles import method dialog", () => {
+			const { result } = renderHook(() => useEncounterExportImport(), {
+				wrapper,
+			});
+
+			expect(result.current.showImportMethod).toBe(false);
+			act(() => result.current.setShowImportMethod(true));
+			expect(result.current.showImportMethod).toBe(true);
+		});
+
+		it("clears import error", () => {
+			const { result } = renderHook(() => useEncounterExportImport(), {
+				wrapper,
+			});
+
+			act(() => {
+				result.current.handleImportClipboard("bad json");
+			});
+			expect(result.current.importError).toBe("Invalid file format");
+
+			act(() => result.current.setImportError(null));
+			expect(result.current.importError).toBeNull();
+		});
+	});
+});

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

@@ -2,27 +2,35 @@
 import type { BestiaryIndexEntry, PlayerCharacter } from "@initiative/domain";
 import { combatantId, creatureId, playerCharacterId } from "@initiative/domain";
 import { act, renderHook } from "@testing-library/react";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ReactNode } from "react";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+import { createTestAdapters } from "../../__tests__/adapters/in-memory-adapters.js";
+import { AllProviders } from "../../__tests__/test-providers.js";
 import { useEncounter } from "../use-encounter.js";
 
-vi.mock("../../persistence/encounter-storage.js", () => ({
-	loadEncounter: vi.fn().mockReturnValue(null),
-	saveEncounter: vi.fn(),
-}));
+beforeAll(() => {
+	Object.defineProperty(globalThis, "matchMedia", {
+		writable: true,
+		value: vi.fn().mockImplementation((query: string) => ({
+			matches: false,
+			media: query,
+			onchange: null,
+			addListener: vi.fn(),
+			removeListener: vi.fn(),
+			addEventListener: vi.fn(),
+			removeEventListener: vi.fn(),
+			dispatchEvent: vi.fn(),
+		})),
+	});
+});
 
-const { loadEncounter: mockLoad, saveEncounter: mockSave } =
-	await vi.importMock<typeof import("../../persistence/encounter-storage.js")>(
-		"../../persistence/encounter-storage.js",
-	);
+function wrapper({ children }: { children: ReactNode }) {
+	return <AllProviders>{children}</AllProviders>;
+}
 
 describe("useEncounter", () => {
-	beforeEach(() => {
-		vi.clearAllMocks();
-		mockLoad.mockReturnValue(null);
-	});
-
 	it("initializes with empty encounter when persistence returns null", () => {
-		const { result } = renderHook(() => useEncounter());
+		const { result } = renderHook(() => useEncounter(), { wrapper });
 
 		expect(result.current.encounter.combatants).toEqual([]);
 		expect(result.current.encounter.activeIndex).toBe(0);
@@ -32,13 +40,33 @@ describe("useEncounter", () => {
 
 	it("initializes from stored encounter", () => {
 		const stored = {
-			combatants: [{ id: combatantId("c-1"), name: "Goblin" }],
+			combatants: [
+				{
+					id: combatantId("c-1"),
+					name: "Goblin",
+					initiative: undefined,
+					maxHp: undefined,
+					currentHp: undefined,
+					tempHp: undefined,
+					ac: undefined,
+					conditions: [],
+					concentrating: false,
+					creatureId: undefined,
+					playerCharacterId: undefined,
+					color: undefined,
+					icon: undefined,
+				},
+			],
 			activeIndex: 0,
 			roundNumber: 2,
 		};
-		mockLoad.mockReturnValue(stored);
+		const adapters = createTestAdapters({ encounter: stored });
 
-		const { result } = renderHook(() => useEncounter());
+		const { result } = renderHook(() => useEncounter(), {
+			wrapper: ({ children }: { children: ReactNode }) => (
+				<AllProviders adapters={adapters}>{children}</AllProviders>
+			),
+		});
 
 		expect(result.current.encounter.combatants).toHaveLength(1);
 		expect(result.current.encounter.roundNumber).toBe(2);
@@ -46,7 +74,7 @@ describe("useEncounter", () => {
 	});
 
 	it("addCombatant adds a combatant with incremental IDs and persists", () => {
-		const { result } = renderHook(() => useEncounter());
+		const { result } = renderHook(() => useEncounter(), { wrapper });
 
 		act(() => result.current.addCombatant("Goblin"));
 		act(() => result.current.addCombatant("Orc"));
@@ -55,11 +83,10 @@ describe("useEncounter", () => {
 		expect(result.current.encounter.combatants[0].name).toBe("Goblin");
 		expect(result.current.encounter.combatants[1].name).toBe("Orc");
 		expect(result.current.isEmpty).toBe(false);
-		expect(mockSave).toHaveBeenCalled();
 	});
 
 	it("removeCombatant removes a combatant and persists", () => {
-		const { result } = renderHook(() => useEncounter());
+		const { result } = renderHook(() => useEncounter(), { wrapper });
 
 		act(() => result.current.addCombatant("Goblin"));
 		const id = result.current.encounter.combatants[0].id;
@@ -71,7 +98,7 @@ describe("useEncounter", () => {
 	});
 
 	it("advanceTurn and retreatTurn update encounter state", () => {
-		const { result } = renderHook(() => useEncounter());
+		const { result } = renderHook(() => useEncounter(), { wrapper });
 
 		act(() => result.current.addCombatant("Goblin"));
 		act(() => result.current.addCombatant("Orc"));
@@ -86,7 +113,7 @@ describe("useEncounter", () => {
 	});
 
 	it("clearEncounter resets to empty and resets ID counter", () => {
-		const { result } = renderHook(() => useEncounter());
+		const { result } = renderHook(() => useEncounter(), { wrapper });
 
 		act(() => result.current.addCombatant("Goblin"));
 		act(() => result.current.clearEncounter());
@@ -100,7 +127,7 @@ describe("useEncounter", () => {
 	});
 
 	it("addCombatant with opts applies initiative, ac, maxHp", () => {
-		const { result } = renderHook(() => useEncounter());
+		const { result } = renderHook(() => useEncounter(), { wrapper });
 
 		act(() =>
 			result.current.addCombatant("Goblin", {
@@ -118,7 +145,7 @@ describe("useEncounter", () => {
 	});
 
 	it("derived flags: hasCreatureCombatants and canRollAllInitiative", () => {
-		const { result } = renderHook(() => useEncounter());
+		const { result } = renderHook(() => useEncounter(), { wrapper });
 
 		// No creatures yet
 		expect(result.current.hasCreatureCombatants).toBe(false);
@@ -146,7 +173,7 @@ describe("useEncounter", () => {
 	});
 
 	it("addFromBestiary adds combatant with HP, AC, creatureId", () => {
-		const { result } = renderHook(() => useEncounter());
+		const { result } = renderHook(() => useEncounter(), { wrapper });
 
 		const entry: BestiaryIndexEntry = {
 			name: "Goblin",
@@ -173,7 +200,7 @@ describe("useEncounter", () => {
 	});
 
 	it("addFromBestiary auto-numbers duplicate names", () => {
-		const { result } = renderHook(() => useEncounter());
+		const { result } = renderHook(() => useEncounter(), { wrapper });
 
 		const entry: BestiaryIndexEntry = {
 			name: "Goblin",
@@ -200,7 +227,7 @@ describe("useEncounter", () => {
 	});
 
 	it("addFromPlayerCharacter adds combatant with HP, AC, color, icon", () => {
-		const { result } = renderHook(() => useEncounter());
+		const { result } = renderHook(() => useEncounter(), { wrapper });
 
 		const pc: PlayerCharacter = {
 			id: playerCharacterId("pc-1"),

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

@@ -1,25 +1,33 @@
 // @vitest-environment jsdom
 import { playerCharacterId } from "@initiative/domain";
 import { act, renderHook } from "@testing-library/react";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ReactNode } from "react";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+import { createTestAdapters } from "../../__tests__/adapters/in-memory-adapters.js";
+import { AllProviders } from "../../__tests__/test-providers.js";
 import { usePlayerCharacters } from "../use-player-characters.js";
 
-vi.mock("../../persistence/player-character-storage.js", () => ({
-	loadPlayerCharacters: vi.fn().mockReturnValue([]),
-	savePlayerCharacters: vi.fn(),
-}));
+beforeAll(() => {
+	Object.defineProperty(globalThis, "matchMedia", {
+		writable: true,
+		value: vi.fn().mockImplementation((query: string) => ({
+			matches: false,
+			media: query,
+			onchange: null,
+			addListener: vi.fn(),
+			removeListener: vi.fn(),
+			addEventListener: vi.fn(),
+			removeEventListener: vi.fn(),
+			dispatchEvent: vi.fn(),
+		})),
+	});
+});
 
-const { loadPlayerCharacters: mockLoad, savePlayerCharacters: mockSave } =
-	await vi.importMock<
-		typeof import("../../persistence/player-character-storage.js")
-	>("../../persistence/player-character-storage.js");
+function wrapper({ children }: { children: ReactNode }) {
+	return <AllProviders>{children}</AllProviders>;
+}
 
 describe("usePlayerCharacters", () => {
-	beforeEach(() => {
-		vi.clearAllMocks();
-		mockLoad.mockReturnValue([]);
-	});
-
 	it("initializes with characters from persistence", () => {
 		const stored = [
 			{
@@ -31,15 +39,19 @@ describe("usePlayerCharacters", () => {
 				icon: undefined,
 			},
 		];
-		mockLoad.mockReturnValue(stored);
+		const adapters = createTestAdapters({ playerCharacters: stored });
 
-		const { result } = renderHook(() => usePlayerCharacters());
+		const { result } = renderHook(() => usePlayerCharacters(), {
+			wrapper: ({ children }: { children: ReactNode }) => (
+				<AllProviders adapters={adapters}>{children}</AllProviders>
+			),
+		});
 
 		expect(result.current.characters).toEqual(stored);
 	});
 
 	it("createCharacter adds a character and persists", () => {
-		const { result } = renderHook(() => usePlayerCharacters());
+		const { result } = renderHook(() => usePlayerCharacters(), { wrapper });
 
 		act(() => {
 			result.current.createCharacter(
@@ -56,11 +68,10 @@ describe("usePlayerCharacters", () => {
 		expect(result.current.characters[0].name).toBe("Vex");
 		expect(result.current.characters[0].ac).toBe(15);
 		expect(result.current.characters[0].maxHp).toBe(28);
-		expect(mockSave).toHaveBeenCalled();
 	});
 
 	it("createCharacter returns domain error for empty name", () => {
-		const { result } = renderHook(() => usePlayerCharacters());
+		const { result } = renderHook(() => usePlayerCharacters(), { wrapper });
 
 		let error: unknown;
 		act(() => {
@@ -79,7 +90,7 @@ describe("usePlayerCharacters", () => {
 	});
 
 	it("editCharacter updates character and persists", () => {
-		const { result } = renderHook(() => usePlayerCharacters());
+		const { result } = renderHook(() => usePlayerCharacters(), { wrapper });
 
 		act(() => {
 			result.current.createCharacter(
@@ -99,11 +110,10 @@ describe("usePlayerCharacters", () => {
 		});
 
 		expect(result.current.characters[0].name).toBe("Vex'ahlia");
-		expect(mockSave).toHaveBeenCalled();
 	});
 
 	it("deleteCharacter removes character and persists", () => {
-		const { result } = renderHook(() => usePlayerCharacters());
+		const { result } = renderHook(() => usePlayerCharacters(), { wrapper });
 
 		act(() => {
 			result.current.createCharacter(
@@ -123,6 +133,5 @@ describe("usePlayerCharacters", () => {
 		});
 
 		expect(result.current.characters).toHaveLength(0);
-		expect(mockSave).toHaveBeenCalled();
 	});
 });

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

@@ -8,11 +8,7 @@ import {
 	normalizeBestiary,
 	setSourceDisplayNames,
 } from "../adapters/bestiary-adapter.js";
-import * as bestiaryCache from "../adapters/bestiary-cache.js";
-import {
-	getSourceDisplayName,
-	loadBestiaryIndex,
-} from "../adapters/bestiary-index-adapter.js";
+import { useAdapters } from "../contexts/adapter-context.js";
 
 export interface SearchResult extends BestiaryIndexEntry {
 	readonly sourceDisplayName: string;
@@ -32,13 +28,14 @@ interface BestiaryHook {
 }
 
 export function useBestiary(): BestiaryHook {
+	const { bestiaryCache, bestiaryIndex } = useAdapters();
 	const [isLoaded, setIsLoaded] = useState(false);
 	const [creatureMap, setCreatureMap] = useState(
 		() => new Map<CreatureId, Creature>(),
 	);
 
 	useEffect(() => {
-		const index = loadBestiaryIndex();
+		const index = bestiaryIndex.loadIndex();
 		setSourceDisplayNames(index.sources as Record<string, string>);
 		if (index.creatures.length > 0) {
 			setIsLoaded(true);
@@ -47,21 +44,24 @@ export function useBestiary(): BestiaryHook {
 		void bestiaryCache.loadAllCachedCreatures().then((map) => {
 			setCreatureMap(map);
 		});
-	}, []);
+	}, [bestiaryCache, bestiaryIndex]);
 
-	const search = useCallback((query: string): SearchResult[] => {
+	const search = useCallback(
+		(query: string): SearchResult[] => {
 			if (query.length < 2) return [];
 			const lower = query.toLowerCase();
-		const index = loadBestiaryIndex();
+			const index = bestiaryIndex.loadIndex();
 			return index.creatures
 				.filter((c) => c.name.toLowerCase().includes(lower))
 				.sort((a, b) => a.name.localeCompare(b.name))
 				.slice(0, 10)
 				.map((c) => ({
 					...c,
-				sourceDisplayName: getSourceDisplayName(c.source),
+					sourceDisplayName: bestiaryIndex.getSourceDisplayName(c.source),
 				}));
-	}, []);
+		},
+		[bestiaryIndex],
+	);
 
 	const getCreature = useCallback(
 		(id: CreatureId): Creature | undefined => {
@@ -74,7 +74,7 @@ export function useBestiary(): BestiaryHook {
 		(sourceCode: string): Promise<boolean> => {
 			return bestiaryCache.isSourceCached(sourceCode);
 		},
-		[],
+		[bestiaryCache],
 	);
 
 	const fetchAndCacheSource = useCallback(
@@ -87,7 +87,7 @@ export function useBestiary(): BestiaryHook {
 			}
 			const json = await response.json();
 			const creatures = normalizeBestiary(json);
-			const displayName = getSourceDisplayName(sourceCode);
+			const displayName = bestiaryIndex.getSourceDisplayName(sourceCode);
 			await bestiaryCache.cacheSource(sourceCode, displayName, creatures);
 			setCreatureMap((prev) => {
 				const next = new Map(prev);
@@ -97,14 +97,14 @@ export function useBestiary(): BestiaryHook {
 				return next;
 			});
 		},
-		[],
+		[bestiaryCache, bestiaryIndex],
 	);
 
 	const uploadAndCacheSource = useCallback(
 		async (sourceCode: string, jsonData: unknown): Promise<void> => {
 			// biome-ignore lint/suspicious/noExplicitAny: raw JSON shape varies
 			const creatures = normalizeBestiary(jsonData as any);
-			const displayName = getSourceDisplayName(sourceCode);
+			const displayName = bestiaryIndex.getSourceDisplayName(sourceCode);
 			await bestiaryCache.cacheSource(sourceCode, displayName, creatures);
 			setCreatureMap((prev) => {
 				const next = new Map(prev);
@@ -114,13 +114,13 @@ export function useBestiary(): BestiaryHook {
 				return next;
 			});
 		},
-		[],
+		[bestiaryCache, bestiaryIndex],
 	);
 
 	const refreshCache = useCallback(async (): Promise<void> => {
 		const map = await bestiaryCache.loadAllCachedCreatures();
 		setCreatureMap(map);
-	}, []);
+	}, [bestiaryCache]);
 
 	return {
 		search,

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

@@ -1,8 +1,5 @@
 import { useCallback, useRef, useState } from "react";
-import {
-	getAllSourceCodes,
-	getDefaultFetchUrl,
-} from "../adapters/bestiary-index-adapter.js";
+import { useAdapters } from "../contexts/adapter-context.js";
 
 const BATCH_SIZE = 6;
 
@@ -32,6 +29,7 @@ interface BulkImportHook {
 }
 
 export function useBulkImport(): BulkImportHook {
+	const { bestiaryIndex } = useAdapters();
 	const [state, setState] = useState<BulkImportState>(IDLE_STATE);
 	const countersRef = useRef({ completed: 0, failed: 0 });
 
@@ -42,7 +40,7 @@ export function useBulkImport(): BulkImportHook {
 			isSourceCached: (sourceCode: string) => Promise<boolean>,
 			refreshCache: () => Promise<void>,
 		) => {
-			const allCodes = getAllSourceCodes();
+			const allCodes = bestiaryIndex.getAllSourceCodes();
 			const total = allCodes.length;
 
 			countersRef.current = { completed: 0, failed: 0 };
@@ -83,7 +81,7 @@ export function useBulkImport(): BulkImportHook {
 						chain.then(() =>
 							Promise.allSettled(
 								batch.map(async ({ code }) => {
-									const url = getDefaultFetchUrl(code, baseUrl);
+									const url = bestiaryIndex.getDefaultFetchUrl(code, baseUrl);
 									try {
 										await fetchAndCacheSource(code, url);
 										countersRef.current.completed++;
@@ -117,7 +115,7 @@ export function useBulkImport(): BulkImportHook {
 				});
 			})();
 		},
-		[],
+		[bestiaryIndex],
 	);
 
 	const reset = useCallback(() => {

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

@@ -0,0 +1,140 @@
+import type {
+	Combatant,
+	CreatureId,
+	DifficultyTier,
+	PlayerCharacter,
+} from "@initiative/domain";
+import { calculateEncounterDifficulty, crToXp } 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";
+
+export interface BreakdownCombatant {
+	readonly combatant: Combatant;
+	readonly cr: string | null;
+	readonly xp: number | null;
+	readonly source: string | null;
+	readonly editable: boolean;
+}
+
+interface DifficultyBreakdown {
+	readonly tier: DifficultyTier;
+	readonly totalMonsterXp: number;
+	readonly partyBudget: {
+		readonly low: number;
+		readonly moderate: number;
+		readonly high: number;
+	};
+	readonly pcCount: number;
+	readonly combatants: readonly BreakdownCombatant[];
+}
+
+export function useDifficultyBreakdown(): DifficultyBreakdown | null {
+	const { encounter } = useEncounterContext();
+	const { characters } = usePlayerCharactersContext();
+	const { getCreature } = useBestiaryContext();
+
+	return useMemo(() => {
+		const partyLevels = derivePartyLevels(encounter.combatants, characters);
+		const { entries, crs } = classifyCombatants(
+			encounter.combatants,
+			getCreature,
+		);
+
+		if (partyLevels.length === 0 || crs.length === 0) {
+			return null;
+		}
+
+		const result = calculateEncounterDifficulty(partyLevels, crs);
+
+		return {
+			...result,
+			pcCount: partyLevels.length,
+			combatants: entries,
+		};
+	}, [encounter.combatants, characters, getCreature]);
+}
+
+function classifyBestiaryCombatant(
+	c: Combatant,
+	getCreature: (
+		id: CreatureId,
+	) => { cr: string; source: string; sourceDisplayName: string } | undefined,
+): { entry: BreakdownCombatant; cr: string | null } {
+	const creature = c.creatureId ? getCreature(c.creatureId) : undefined;
+	if (creature) {
+		return {
+			entry: {
+				combatant: c,
+				cr: creature.cr,
+				xp: crToXp(creature.cr),
+				source: creature.sourceDisplayName ?? creature.source,
+				editable: false,
+			},
+			cr: creature.cr,
+		};
+	}
+	return {
+		entry: {
+			combatant: c,
+			cr: null,
+			xp: null,
+			source: null,
+			editable: false,
+		},
+		cr: null,
+	};
+}
+
+function classifyCombatants(
+	combatants: readonly Combatant[],
+	getCreature: (
+		id: CreatureId,
+	) => { cr: string; source: string; sourceDisplayName: string } | undefined,
+): { entries: BreakdownCombatant[]; crs: string[] } {
+	const entries: BreakdownCombatant[] = [];
+	const crs: string[] = [];
+
+	for (const c of combatants) {
+		if (c.playerCharacterId) continue;
+
+		if (c.creatureId) {
+			const { entry, cr } = classifyBestiaryCombatant(c, getCreature);
+			entries.push(entry);
+			if (cr) crs.push(cr);
+		} else if (c.cr) {
+			crs.push(c.cr);
+			entries.push({
+				combatant: c,
+				cr: c.cr,
+				xp: crToXp(c.cr),
+				source: null,
+				editable: true,
+			});
+		} else {
+			entries.push({
+				combatant: c,
+				cr: null,
+				xp: null,
+				source: null,
+				editable: true,
+			});
+		}
+	}
+
+	return { entries, crs };
+}
+
+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;
+}

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

@@ -29,9 +29,12 @@ function deriveMonsterCrs(
 ): string[] {
 	const crs: string[] = [];
 	for (const c of combatants) {
-		if (!c.creatureId) continue;
+		if (c.creatureId) {
 			const creature = getCreature(c.creatureId);
 			if (creature) crs.push(creature.cr);
+		} else if (c.cr) {
+			crs.push(c.cr);
+		}
 	}
 	return crs;
 }

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

@@ -0,0 +1,139 @@
+import type { ExportBundle } from "@initiative/domain";
+import { useCallback, useRef, useState } from "react";
+import { useEncounterContext } from "../contexts/encounter-context.js";
+import { usePlayerCharactersContext } from "../contexts/player-characters-context.js";
+import {
+	assembleExportBundle,
+	bundleToJson,
+	readImportFile,
+	triggerDownload,
+	validateImportBundle,
+} from "../persistence/export-import.js";
+
+export function useEncounterExportImport() {
+	const {
+		encounter,
+		undoRedoState,
+		isEmpty: encounterIsEmpty,
+		setEncounter,
+		setUndoRedoState,
+	} = useEncounterContext();
+	const { characters: playerCharacters, replacePlayerCharacters } =
+		usePlayerCharactersContext();
+
+	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<ExportBundle | null>(null);
+	const importFileRef = useRef<HTMLInputElement>(null);
+
+	const handleExportDownload = useCallback(
+		(includeHistory: boolean, filename: string) => {
+			const bundle = assembleExportBundle(
+				encounter,
+				undoRedoState,
+				playerCharacters,
+				includeHistory,
+			);
+			triggerDownload(bundle, filename);
+		},
+		[encounter, undoRedoState, playerCharacters],
+	);
+
+	const handleExportClipboard = useCallback(
+		(includeHistory: boolean) => {
+			const bundle = assembleExportBundle(
+				encounter,
+				undoRedoState,
+				playerCharacters,
+				includeHistory,
+			);
+			void navigator.clipboard.writeText(bundleToJson(bundle));
+		},
+		[encounter, undoRedoState, playerCharacters],
+	);
+
+	const applyImport = useCallback(
+		(bundle: ExportBundle) => {
+			setEncounter(bundle.encounter);
+			setUndoRedoState({
+				undoStack: bundle.undoStack,
+				redoStack: bundle.redoStack,
+			});
+			replacePlayerCharacters([...bundle.playerCharacters]);
+		},
+		[setEncounter, setUndoRedoState, replacePlayerCharacters],
+	);
+
+	const handleValidatedBundle = useCallback(
+		(result: ExportBundle | string) => {
+			if (typeof result === "string") {
+				setImportError(result);
+				return;
+			}
+			if (encounterIsEmpty) {
+				applyImport(result);
+			} else {
+				pendingBundleRef.current = result;
+				setShowImportConfirm(true);
+			}
+		},
+		[encounterIsEmpty, applyImport],
+	);
+
+	const handleImportFile = useCallback(
+		async (e: React.ChangeEvent<HTMLInputElement>) => {
+			const file = e.target.files?.[0];
+			if (!file) return;
+			if (importFileRef.current) importFileRef.current.value = "";
+
+			setImportError(null);
+			handleValidatedBundle(await readImportFile(file));
+		},
+		[handleValidatedBundle],
+	);
+
+	const handleImportClipboard = useCallback(
+		(text: string) => {
+			setImportError(null);
+			try {
+				const parsed: unknown = JSON.parse(text);
+				handleValidatedBundle(validateImportBundle(parsed));
+			} catch {
+				setImportError("Invalid file format");
+			}
+		},
+		[handleValidatedBundle],
+	);
+
+	const handleImportConfirm = useCallback(() => {
+		if (pendingBundleRef.current) {
+			applyImport(pendingBundleRef.current);
+			pendingBundleRef.current = null;
+		}
+		setShowImportConfirm(false);
+	}, [applyImport]);
+
+	const handleImportCancel = useCallback(() => {
+		pendingBundleRef.current = null;
+		setShowImportConfirm(false);
+	}, []);
+
+	return {
+		importError,
+		showExportMethod,
+		showImportMethod,
+		showImportConfirm,
+		importFileRef,
+		setImportError,
+		setShowExportMethod,
+		setShowImportMethod,
+		handleExportDownload,
+		handleExportClipboard,
+		handleImportFile,
+		handleImportClipboard,
+		handleImportConfirm,
+		handleImportCancel,
+	} as const;
+}

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

@@ -9,6 +9,7 @@ import {
 	removeCombatantUseCase,
 	retreatTurnUseCase,
 	setAcUseCase,
+	setCrUseCase,
 	setHpUseCase,
 	setInitiativeUseCase,
 	setTempHpUseCase,
@@ -37,14 +38,7 @@ import {
 	resolveCreatureName,
 } from "@initiative/domain";
 import { useCallback, useEffect, useReducer, useRef } from "react";
-import {
-	loadEncounter,
-	saveEncounter,
-} from "../persistence/encounter-storage.js";
-import {
-	loadUndoRedoStacks,
-	saveUndoRedoStacks,
-} from "../persistence/undo-redo-storage.js";
+import { useAdapters } from "../contexts/adapter-context.js";
 
 // -- Types --
 
@@ -59,6 +53,7 @@ type EncounterAction =
 	| { type: "adjust-hp"; id: CombatantId; delta: number }
 	| { type: "set-temp-hp"; id: CombatantId; tempHp: number | undefined }
 	| { type: "set-ac"; id: CombatantId; value: number | undefined }
+	| { type: "set-cr"; id: CombatantId; value: string | undefined }
 	| {
 			type: "toggle-condition";
 			id: CombatantId;
@@ -111,11 +106,14 @@ function deriveNextId(encounter: Encounter): number {
 	return max;
 }
 
-function initializeState(): EncounterState {
-	const encounter = loadEncounter() ?? EMPTY_ENCOUNTER;
+function initializeState(
+	loadEncounterFn: () => Encounter | null,
+	loadUndoRedoFn: () => UndoRedoState,
+): EncounterState {
+	const encounter = loadEncounterFn() ?? EMPTY_ENCOUNTER;
 	return {
 		encounter,
-		undoRedoState: loadUndoRedoStacks(),
+		undoRedoState: loadUndoRedoFn(),
 		events: [],
 		nextId: deriveNextId(encounter),
 		lastCreatureId: null,
@@ -322,6 +320,7 @@ function dispatchEncounterAction(
 		| { type: "adjust-hp" }
 		| { type: "set-temp-hp" }
 		| { type: "set-ac" }
+		| { type: "set-cr" }
 		| { type: "toggle-condition" }
 		| { type: "toggle-concentration" }
 	>,
@@ -362,6 +361,9 @@ function dispatchEncounterAction(
 		case "set-ac":
 			result = setAcUseCase(store, action.id, action.value);
 			break;
+		case "set-cr":
+			result = setCrUseCase(store, action.id, action.value);
+			break;
 		case "toggle-condition":
 			result = toggleConditionUseCase(store, action.id, action.conditionId);
 			break;
@@ -385,7 +387,10 @@ function dispatchEncounterAction(
 // -- Hook --
 
 export function useEncounter() {
-	const [state, dispatch] = useReducer(encounterReducer, null, initializeState);
+	const { encounterPersistence, undoRedoPersistence } = useAdapters();
+	const [state, dispatch] = useReducer(encounterReducer, null, () =>
+		initializeState(encounterPersistence.load, undoRedoPersistence.load),
+	);
 	const { encounter, undoRedoState, events } = state;
 
 	const encounterRef = useRef(encounter);
@@ -394,12 +399,12 @@ export function useEncounter() {
 	undoRedoRef.current = undoRedoState;
 
 	useEffect(() => {
-		saveEncounter(encounter);
-	}, [encounter]);
+		encounterPersistence.save(encounter);
+	}, [encounter, encounterPersistence]);
 
 	useEffect(() => {
-		saveUndoRedoStacks(undoRedoState);
-	}, [undoRedoState]);
+		undoRedoPersistence.save(undoRedoState);
+	}, [undoRedoState, undoRedoPersistence]);
 
 	// Escape hatches for useInitiativeRolls (needs raw port access)
 	const makeStore = useCallback((): EncounterStore => {
@@ -496,6 +501,11 @@ export function useEncounter() {
 				dispatch({ type: "set-ac", id, value }),
 			[],
 		),
+		setCr: useCallback(
+			(id: CombatantId, value: string | undefined) =>
+				dispatch({ type: "set-cr", id, value }),
+			[],
+		),
 		toggleCondition: useCallback(
 			(id: CombatantId, conditionId: ConditionId) =>
 				dispatch({ type: "toggle-condition", id, conditionId }),

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

@@ -7,14 +7,7 @@ import {
 import type { PlayerCharacter, PlayerCharacterId } from "@initiative/domain";
 import { isDomainError, playerCharacterId } from "@initiative/domain";
 import { useCallback, useEffect, useRef, useState } from "react";
-import {
-	loadPlayerCharacters,
-	savePlayerCharacters,
-} from "../persistence/player-character-storage.js";
-
-function initializeCharacters(): PlayerCharacter[] {
-	return loadPlayerCharacters();
-}
+import { useAdapters } from "../contexts/adapter-context.js";
 
 let nextPcId = 0;
 
@@ -32,14 +25,16 @@ interface EditFields {
 }
 
 export function usePlayerCharacters() {
-	const [characters, setCharacters] =
-		useState<PlayerCharacter[]>(initializeCharacters);
+	const { playerCharacterPersistence } = useAdapters();
+	const [characters, setCharacters] = useState<PlayerCharacter[]>(() =>
+		playerCharacterPersistence.load(),
+	);
 	const charactersRef = useRef(characters);
 	charactersRef.current = characters;
 
 	useEffect(() => {
-		savePlayerCharacters(characters);
-	}, [characters]);
+		playerCharacterPersistence.save(characters);
+	}, [characters, playerCharacterPersistence]);
 
 	const makeStore = useCallback((): PlayerCharacterStore => {
 		return {

apps/web/src/main.tsx

@@ -1,6 +1,8 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { App } from "./App.js";
+import { productionAdapters } from "./adapters/production-adapters.js";
+import { AdapterProvider } from "./contexts/adapter-context.js";
 import {
 	BestiaryProvider,
 	BulkImportProvider,
@@ -17,6 +19,7 @@ const root = document.getElementById("root");
 if (root) {
 	createRoot(root).render(
 		<StrictMode>
+			<AdapterProvider adapters={productionAdapters}>
 				<ThemeProvider>
 					<RulesEditionProvider>
 						<EncounterProvider>
@@ -34,6 +37,7 @@ if (root) {
 						</EncounterProvider>
 					</RulesEditionProvider>
 				</ThemeProvider>
+			</AdapterProvider>
 		</StrictMode>,
 	);
 }

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

@@ -134,6 +134,26 @@ describe("loadEncounter", () => {
 		expect(loadEncounter()).toBeNull();
 	});
 
+	it("round-trip preserves combatant cr field", () => {
+		const result = createEncounter(
+			[
+				{
+					id: combatantId("c-1"),
+					name: "Custom Thug",
+					cr: "2",
+				},
+			],
+			0,
+			1,
+		);
+		if (isDomainError(result)) throw new Error("unreachable");
+		saveEncounter(result);
+		const loaded = loadEncounter();
+
+		expect(loaded).not.toBeNull();
+		expect(loaded?.combatants[0].cr).toBe("2");
+	});
+
 	it("saving after modifications persists the latest state", () => {
 		const encounter = makeEncounter();
 		saveEncounter(encounter);

packages/application/src/index.ts

@@ -21,6 +21,7 @@ export {
 } from "./roll-all-initiative-use-case.js";
 export { rollInitiativeUseCase } from "./roll-initiative-use-case.js";
 export { setAcUseCase } from "./set-ac-use-case.js";
+export { setCrUseCase } from "./set-cr-use-case.js";
 export { setHpUseCase } from "./set-hp-use-case.js";
 export { setInitiativeUseCase } from "./set-initiative-use-case.js";
 export { setTempHpUseCase } from "./set-temp-hp-use-case.js";

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

@@ -0,0 +1,18 @@
+import {
+	type CombatantId,
+	type DomainError,
+	type DomainEvent,
+	setCr,
+} from "@initiative/domain";
+import type { EncounterStore } from "./ports.js";
+import { runEncounterAction } from "./run-encounter-action.js";
+
+export function setCrUseCase(
+	store: EncounterStore,
+	combatantId: CombatantId,
+	value: string | undefined,
+): DomainEvent[] | DomainError {
+	return runEncounterAction(store, (encounter) =>
+		setCr(encounter, combatantId, value),
+	);
+}

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

@@ -219,6 +219,28 @@ describe("rehydrateCombatant", () => {
 			}
 		});
 
+		it("preserves valid cr field", () => {
+			for (const cr of ["5", "1/4", "0", "30"]) {
+				const result = rehydrateCombatant({ ...minimalCombatant(), cr });
+				expect(result).not.toBeNull();
+				expect(result?.cr).toBe(cr);
+			}
+		});
+
+		it("drops invalid cr field", () => {
+			for (const cr of ["99", "", 42, null, "abc"]) {
+				const result = rehydrateCombatant({ ...minimalCombatant(), cr });
+				expect(result).not.toBeNull();
+				expect(result?.cr).toBeUndefined();
+			}
+		});
+
+		it("combatant without cr rehydrates as before", () => {
+			const result = rehydrateCombatant(minimalCombatant());
+			expect(result).not.toBeNull();
+			expect(result?.cr).toBeUndefined();
+		});
+
 		it("drops invalid tempHp — keeps combatant", () => {
 			for (const tempHp of [-1, 1.5, "3"]) {
 				const result = rehydrateCombatant({

packages/domain/src/__tests__/set-cr.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from "vitest";
+import { setCr } from "../set-cr.js";
+import type { Combatant, Encounter } from "../types.js";
+import { combatantId, isDomainError } from "../types.js";
+import { expectDomainError } from "./test-helpers.js";
+
+function makeCombatant(name: string, cr?: string): Combatant {
+	return cr === undefined
+		? { id: combatantId(name), name }
+		: { id: combatantId(name), name, cr };
+}
+
+function enc(
+	combatants: Combatant[],
+	activeIndex = 0,
+	roundNumber = 1,
+): Encounter {
+	return { combatants, activeIndex, roundNumber };
+}
+
+function successResult(
+	encounter: Encounter,
+	id: string,
+	value: string | undefined,
+) {
+	const result = setCr(encounter, combatantId(id), value);
+	if (isDomainError(result)) {
+		throw new Error(`Expected success, got error: ${result.message}`);
+	}
+	return result;
+}
+
+describe("setCr", () => {
+	it("sets CR to a valid integer value", () => {
+		const e = enc([makeCombatant("A"), makeCombatant("B")]);
+		const { encounter, events } = successResult(e, "A", "5");
+
+		expect(encounter.combatants[0].cr).toBe("5");
+		expect(events).toEqual([
+			{
+				type: "CrSet",
+				combatantId: combatantId("A"),
+				previousCr: undefined,
+				newCr: "5",
+			},
+		]);
+	});
+
+	it("sets CR to 0", () => {
+		const e = enc([makeCombatant("A")]);
+		const { encounter } = successResult(e, "A", "0");
+
+		expect(encounter.combatants[0].cr).toBe("0");
+	});
+
+	it("sets CR to fractional values", () => {
+		for (const cr of ["1/8", "1/4", "1/2"]) {
+			const e = enc([makeCombatant("A")]);
+			const { encounter } = successResult(e, "A", cr);
+			expect(encounter.combatants[0].cr).toBe(cr);
+		}
+	});
+
+	it("sets CR to 30", () => {
+		const e = enc([makeCombatant("A")]);
+		const { encounter } = successResult(e, "A", "30");
+
+		expect(encounter.combatants[0].cr).toBe("30");
+	});
+
+	it("clears CR with undefined", () => {
+		const e = enc([makeCombatant("A", "5")]);
+		const { encounter, events } = successResult(e, "A", undefined);
+
+		expect(encounter.combatants[0].cr).toBeUndefined();
+		expect(events[0]).toMatchObject({
+			previousCr: "5",
+			newCr: undefined,
+		});
+	});
+
+	it("returns error for nonexistent combatant", () => {
+		const e = enc([makeCombatant("A")]);
+		const result = setCr(e, combatantId("nonexistent"), "1");
+
+		expectDomainError(result, "combatant-not-found");
+	});
+
+	it("returns error for invalid CR string", () => {
+		const e = enc([makeCombatant("A")]);
+		const result = setCr(e, combatantId("A"), "99");
+
+		expectDomainError(result, "invalid-cr");
+	});
+
+	it("returns error for empty string CR", () => {
+		const e = enc([makeCombatant("A")]);
+		const result = setCr(e, combatantId("A"), "");
+
+		expectDomainError(result, "invalid-cr");
+	});
+
+	it("preserves other fields when setting CR", () => {
+		const combatant: Combatant = {
+			id: combatantId("A"),
+			name: "Aria",
+			initiative: 15,
+			maxHp: 20,
+			currentHp: 18,
+			ac: 14,
+		};
+		const e = enc([combatant]);
+		const { encounter } = successResult(e, "A", "2");
+
+		const updated = encounter.combatants[0];
+		expect(updated.cr).toBe("2");
+		expect(updated.name).toBe("Aria");
+		expect(updated.initiative).toBe(15);
+		expect(updated.maxHp).toBe(20);
+		expect(updated.currentHp).toBe(18);
+		expect(updated.ac).toBe(14);
+	});
+
+	it("does not reorder combatants", () => {
+		const e = enc([makeCombatant("A"), makeCombatant("B")]);
+		const { encounter } = successResult(e, "B", "1");
+
+		expect(encounter.combatants[0].id).toBe(combatantId("A"));
+		expect(encounter.combatants[1].id).toBe(combatantId("B"));
+	});
+
+	it("preserves activeIndex and roundNumber", () => {
+		const e = enc([makeCombatant("A"), makeCombatant("B")], 1, 5);
+		const { encounter } = successResult(e, "A", "1/4");
+
+		expect(encounter.activeIndex).toBe(1);
+		expect(encounter.roundNumber).toBe(5);
+	});
+
+	it("does not mutate input encounter", () => {
+		const e = enc([makeCombatant("A")]);
+		const original = JSON.parse(JSON.stringify(e));
+		setCr(e, combatantId("A"), "10");
+		expect(e).toEqual(original);
+	});
+});

packages/domain/src/encounter-difficulty.ts

@@ -74,6 +74,9 @@ const XP_BUDGET_PER_CHARACTER: Readonly<
 	20: { low: 6400, moderate: 13200, high: 22000 },
 };
 
+/** All standard 5e challenge rating strings, in ascending order. */
+export const VALID_CR_VALUES: readonly string[] = Object.keys(CR_TO_XP);
+
 /** 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;

packages/domain/src/events.ts

@@ -94,6 +94,13 @@ export interface AcSet {
 	readonly newAc: number | undefined;
 }
 
+export interface CrSet {
+	readonly type: "CrSet";
+	readonly combatantId: CombatantId;
+	readonly previousCr: string | undefined;
+	readonly newCr: string | undefined;
+}
+
 export interface ConditionAdded {
 	readonly type: "ConditionAdded";
 	readonly combatantId: CombatantId;
@@ -153,6 +160,7 @@ export type DomainEvent =
 	| TurnRetreated
 	| RoundRetreated
 	| AcSet
+	| CrSet
 	| ConditionAdded
 	| ConditionRemoved
 	| ConcentrationStarted

packages/domain/src/index.ts

@@ -53,6 +53,7 @@ export {
 	crToXp,
 	type DifficultyResult,
 	type DifficultyTier,
+	VALID_CR_VALUES,
 } from "./encounter-difficulty.js";
 export type {
 	AcSet,
@@ -63,6 +64,7 @@ export type {
 	ConcentrationStarted,
 	ConditionAdded,
 	ConditionRemoved,
+	CrSet,
 	CurrentHpAdjusted,
 	DomainEvent,
 	EncounterCleared,
@@ -107,6 +109,7 @@ export {
 	selectRoll,
 } from "./roll-initiative.js";
 export { type SetAcSuccess, setAc } from "./set-ac.js";
+export { type SetCrSuccess, setCr } from "./set-cr.js";
 export { type SetHpSuccess, setHp } from "./set-hp.js";
 export {
 	type SetInitiativeSuccess,

packages/domain/src/rehydrate-combatant.ts

@@ -1,6 +1,7 @@
 import type { ConditionId } from "./conditions.js";
 import { VALID_CONDITION_IDS } from "./conditions.js";
 import { creatureId } from "./creature-types.js";
+import { VALID_CR_VALUES } from "./encounter-difficulty.js";
 import {
 	playerCharacterId,
 	VALID_PLAYER_COLORS,
@@ -69,6 +70,12 @@ function validateNonEmptyString(value: unknown): string | undefined {
 	return typeof value === "string" && value.length > 0 ? value : undefined;
 }
 
+function validateCr(value: unknown): string | undefined {
+	return typeof value === "string" && VALID_CR_VALUES.includes(value)
+		? value
+		: undefined;
+}
+
 function parseOptionalFields(entry: Record<string, unknown>) {
 	return {
 		initiative: validateInteger(entry.initiative),
@@ -78,6 +85,7 @@ function parseOptionalFields(entry: Record<string, unknown>) {
 		creatureId: validateNonEmptyString(entry.creatureId)
 			? creatureId(entry.creatureId as string)
 			: undefined,
+		cr: validateCr(entry.cr),
 		color: validateSetMember(entry.color, VALID_PLAYER_COLORS),
 		icon: validateSetMember(entry.icon, VALID_PLAYER_ICONS),
 		playerCharacterId: validateNonEmptyString(entry.playerCharacterId)

packages/domain/src/set-cr.ts

@@ -0,0 +1,53 @@
+import { VALID_CR_VALUES } from "./encounter-difficulty.js";
+import type { DomainEvent } from "./events.js";
+import {
+	type CombatantId,
+	type DomainError,
+	type Encounter,
+	findCombatant,
+	isDomainError,
+} from "./types.js";
+
+export interface SetCrSuccess {
+	readonly encounter: Encounter;
+	readonly events: DomainEvent[];
+}
+
+export function setCr(
+	encounter: Encounter,
+	combatantId: CombatantId,
+	value: string | undefined,
+): SetCrSuccess | DomainError {
+	const found = findCombatant(encounter, combatantId);
+	if (isDomainError(found)) return found;
+
+	if (value !== undefined && !VALID_CR_VALUES.includes(value)) {
+		return {
+			kind: "domain-error",
+			code: "invalid-cr",
+			message: `CR must be a valid challenge rating, got "${value}"`,
+		};
+	}
+
+	const previousCr = found.combatant.cr;
+
+	const updatedCombatants = encounter.combatants.map((c) =>
+		c.id === combatantId ? { ...c, cr: value } : c,
+	);
+
+	return {
+		encounter: {
+			combatants: updatedCombatants,
+			activeIndex: encounter.activeIndex,
+			roundNumber: encounter.roundNumber,
+		},
+		events: [
+			{
+				type: "CrSet",
+				combatantId,
+				previousCr,
+				newCr: value,
+			},
+		],
+	};
+}

packages/domain/src/types.ts

@@ -20,6 +20,7 @@ export interface Combatant {
 	readonly conditions?: readonly ConditionId[];
 	readonly isConcentrating?: boolean;
 	readonly creatureId?: CreatureId;
+	readonly cr?: string;
 	readonly color?: string;
 	readonly icon?: string;
 	readonly playerCharacterId?: PlayerCharacterId;

specs/008-encounter-difficulty/spec.md

@@ -47,7 +47,7 @@ The difficulty indicator only appears when meaningful calculation is possible. I
 
 **Acceptance Scenarios**:
 
-1. **Given** an encounter with only custom combatants (no `creatureId`), **When** the top bar renders, **Then** no difficulty indicator is shown.
+1. **Given** an encounter with only custom combatants that have no `cr` assigned, **When** the top bar renders, **Then** no difficulty indicator is shown.
 
 2. **Given** an encounter with bestiary-linked monsters but no PC combatants, **When** the top bar renders, **Then** no difficulty indicator is shown.
 
@@ -55,7 +55,7 @@ The difficulty indicator only appears when meaningful calculation is possible. I
 
 4. **Given** an encounter with one leveled PC combatant and one bestiary-linked monster, **When** the last leveled PC is removed, **Then** the indicator disappears.
 
-5. **Given** an encounter with one leveled PC combatant and one bestiary-linked monster, **When** the last bestiary-linked monster is removed (only custom combatants remain), **Then** the indicator disappears.
+5. **Given** an encounter with one leveled PC combatant and one bestiary-linked monster, **When** the last bestiary-linked monster is removed and the remaining custom combatants have no `cr` assigned, **Then** the indicator disappears.
 
 ---
 
@@ -101,12 +101,82 @@ The difficulty calculation uses the 2024 5.5e XP Budget per Character table and
 
 3. **Given** a party with PCs at different levels (e.g., three level 3 and one level 2), **When** the budget is calculated, **Then** each PC's budget is looked up individually by level and summed (not averaged).
 
-4. **Given** an encounter with both bestiary-linked and custom combatants, **When** the XP total is calculated, **Then** only bestiary-linked combatants contribute XP (custom combatants are excluded).
+4. **Given** an encounter with bestiary-linked combatants, custom combatants with CR assigned, and custom combatants without CR, **When** the XP total is calculated, **Then** bestiary-linked combatants contribute XP from their creature CR and custom combatants with CR contribute XP from their assigned CR. Custom combatants without CR are excluded.
 
 5. **Given** a PC combatant whose player character has no level, **When** the budget is calculated, **Then** that PC is excluded from the budget (as if they are not in the party).
 
 ---
 
+### Difficulty Breakdown
+
+**Story ED-5 — View difficulty breakdown details (Priority: P2)**
+
+The game master taps the difficulty indicator to open a breakdown panel. The panel shows the party XP budget (sum of per-PC budgets with the tier thresholds), a list of all combatants that contribute XP (each showing name, CR, and XP value), and the total monster XP. This gives the GM visibility into how the difficulty tier was calculated.
+
+**Why this priority**: The indicator alone shows the tier but not the reasoning. The breakdown panel turns the indicator from a black box into a transparent tool the GM can act on.
+
+**Independent Test**: Can be tested by creating an encounter with leveled PCs and monsters, tapping the indicator, and verifying the panel displays correct budget and per-monster XP values.
+
+**Acceptance Scenarios**:
+
+1. **Given** the difficulty indicator is visible, **When** the user taps the indicator, **Then** a breakdown panel opens showing party budget, per-combatant XP contributions, and total monster XP.
+
+2. **Given** the breakdown panel is open, **When** the user taps outside the panel or taps a close control, **Then** the panel closes.
+
+3. **Given** an encounter with three leveled PCs at levels 1, 3, and 5, **When** the breakdown panel is open, **Then** the party budget section shows the summed Low, Moderate, and High thresholds for those levels.
+
+4. **Given** an encounter with two bestiary-linked monsters and one custom combatant with CR assigned, **When** the breakdown panel is open, **Then** all three appear in the combatant list with their name, CR, and XP value.
+
+5. **Given** an encounter with a custom combatant that has no CR assigned, **When** the breakdown panel is open, **Then** that combatant appears in the list as "unassigned" (no XP contribution shown).
+
+6. **Given** the breakdown panel is open, **When** a combatant is added or removed from the encounter, **Then** the panel content updates immediately.
+
+---
+
+### Manual CR Assignment
+
+**Story ED-6 — Assign CR to a custom combatant (Priority: P2)**
+
+From the difficulty breakdown panel, the game master can assign a challenge rating to any custom (non-bestiary) combatant. A CR picker offers all standard 5e CR values (0, 1/8, 1/4, 1/2, 1–30). Assigning a CR immediately updates that combatant's XP contribution, the total monster XP, and the difficulty tier.
+
+**Why this priority**: Without CR assignment, custom combatants are invisible to the difficulty calculation. This closes the gap for GMs who don't use the bestiary.
+
+**Independent Test**: Can be tested by adding a custom combatant, opening the breakdown panel, assigning a CR, and verifying the XP total and difficulty tier update.
+
+**Acceptance Scenarios**:
+
+1. **Given** the breakdown panel is open and a custom combatant has no CR, **When** the user taps the "unassigned" CR area for that combatant, **Then** a CR picker appears offering values: 0, 1/8, 1/4, 1/2, 1–30.
+
+2. **Given** the CR picker is open for a custom combatant, **When** the user selects CR 5, **Then** the combatant's XP updates to 1,800 and the difficulty tier recalculates immediately.
+
+3. **Given** a custom combatant has CR 2 assigned, **When** the user taps the CR value in the breakdown panel, **Then** the CR picker opens with CR 2 pre-selected, allowing the user to change it.
+
+4. **Given** a custom combatant has CR 3 assigned, **When** the user selects a different CR from the picker, **Then** the XP contribution updates immediately to match the new CR.
+
+5. **Given** a custom combatant has CR assigned, **When** the encounter is saved and the page is reloaded, **Then** the CR assignment is restored and the difficulty calculation reflects it.
+
+6. **Given** a custom combatant has CR assigned, **When** the encounter is exported to JSON and re-imported, **Then** the CR assignment is preserved.
+
+---
+
+**Story ED-7 — Bestiary CR takes precedence over manual CR (Priority: P2)**
+
+Bestiary-linked combatants derive their CR from the creature data. The breakdown panel shows their CR as read-only with the bestiary source name visible, making the precedence clear. The manual `cr` field on `Combatant` is ignored when `creatureId` is present.
+
+**Why this priority**: Without clear precedence rules, a combatant could show conflicting CRs from bestiary data and manual assignment, confusing the GM.
+
+**Independent Test**: Can be tested by adding a bestiary-linked combatant and verifying its CR is read-only in the breakdown panel.
+
+**Acceptance Scenarios**:
+
+1. **Given** a bestiary-linked combatant with CR 3 from creature data, **When** the breakdown panel is open, **Then** the combatant shows CR 3 as read-only with the bestiary source name visible.
+
+2. **Given** a bestiary-linked combatant, **When** the user views it in the breakdown panel, **Then** no CR picker is available — the CR cannot be manually overridden.
+
+3. **Given** a combatant that was custom but is later linked to a bestiary creature, **When** the breakdown panel is open, **Then** the CR derives from the creature data and any previously assigned manual CR is ignored.
+
+---
+
 ### Edge Cases
 
 - **All bars empty (trivial)**: When total monster XP is greater than 0 but below the Low threshold, the indicator shows three empty bars. This communicates "we can calculate, but it's trivial."
@@ -114,7 +184,9 @@ The difficulty calculation uses the 2024 5.5e XP Budget per Character table and
 - **Mixed party levels**: PCs at different levels each contribute their own budget — the system handles heterogeneous parties correctly.
 - **Duplicate PC combatants**: If the same player character is added to the encounter multiple times, each copy contributes to the party budget independently (each counts as a party member).
 - **CR fractions**: Bestiary creatures can have fractional CRs (e.g., "1/4", "1/2"). The CR-to-XP lookup must handle these string formats.
-- **Custom combatants silently excluded**: Custom combatants without `creatureId` do not appear in the XP total and are not flagged as warnings or errors.
+- **Custom combatants without CR silently excluded**: Custom combatants without `creatureId` and without a manually assigned `cr` do not appear in the XP total and are not flagged as warnings or errors. They appear in the breakdown panel as "unassigned."
+- **Bestiary CR overrides manual CR**: If a combatant has both `creatureId` and a manual `cr` value, the bestiary CR is used and the manual value is ignored. The breakdown panel makes this visible by showing the CR as read-only.
+- **CR assignment on combatant later linked to bestiary**: If a custom combatant with a manual CR is subsequently linked to a bestiary creature, the manual CR becomes irrelevant — the creature's CR takes over.
 - **PCs without level silently excluded**: PC combatants whose player character has no level do not contribute to the budget and are not flagged.
 - **Indicator with empty encounter**: When the encounter has no combatants, the indicator is hidden (the top bar may not even render per existing behavior).
 - **Level field on existing player characters**: Existing player characters created before this feature will have no level. They are treated as "no level assigned" — no migration or default is needed.
@@ -135,7 +207,7 @@ The system MUST contain a CR-to-XP lookup table mapping all standard 5e challeng
 The system MUST calculate the party's XP budget by summing the per-character budget for each PC combatant whose player character has a level assigned. PCs without a level are excluded from the sum.
 
 #### FR-004 — Monster XP total calculation
-The system MUST calculate the total monster XP by summing the XP value (derived from CR) for each combatant that has a `creatureId`. Combatants without `creatureId` are excluded.
+The system MUST calculate the total monster XP by summing the XP value (derived from CR) for each combatant that has a CR. For bestiary-linked combatants, CR is derived from the creature data via `creatureId`. For custom combatants, CR comes from the optional `cr` field. Combatants with neither `creatureId` nor `cr` are excluded.
 
 #### FR-005 — Difficulty tier determination
 The system MUST determine the encounter difficulty tier by comparing total monster XP against the party's Low, Moderate, and High thresholds. The tier is the highest threshold that the total XP meets or exceeds. If below Low, the encounter is trivial (no tier label).
@@ -153,7 +225,7 @@ The indicator MUST show a tooltip on hover displaying the difficulty label (e.g.
 The indicator MUST update immediately when combatants are added to or removed from the encounter.
 
 #### FR-010 — Hidden when data insufficient
-The indicator MUST be hidden when the encounter has no PC combatants with levels OR no bestiary-linked combatants.
+The indicator MUST be hidden when the encounter has no PC combatants with levels OR no combatants with CR (neither bestiary-linked nor custom combatants with `cr` assigned).
 
 #### FR-011 — Optional level field on PlayerCharacter
 The `PlayerCharacter` entity MUST support an optional `level` field accepting integer values 1-20.
@@ -167,6 +239,24 @@ The player character level MUST be persisted and restored across sessions, consi
 #### FR-014 — High is the cap
 When total monster XP exceeds the High threshold, the indicator MUST display the High state (three red bars). There is no tier above High.
 
+#### FR-015 — Optional CR field on Combatant
+The `Combatant` entity MUST support an optional `cr` field accepting standard 5e challenge rating strings ("0", "1/8", "1/4", "1/2", "1"–"30").
+
+#### FR-016 — Tappable difficulty indicator
+The difficulty indicator MUST be tappable, opening a difficulty breakdown panel.
+
+#### FR-017 — Breakdown panel content
+The breakdown panel MUST display: the party XP budget (with Low, Moderate, High thresholds), a list of combatants showing name, CR, and XP contribution, and the total monster XP.
+
+#### FR-018 — CR picker for custom combatants
+The breakdown panel MUST provide a CR picker for custom combatants (those without `creatureId`) offering all standard 5e CR values: 0, 1/8, 1/4, 1/2, 1–30.
+
+#### FR-019 — Bestiary CR precedence
+When a combatant has a `creatureId`, the system MUST derive CR from the linked creature data. The manual `cr` field MUST be ignored. The breakdown panel MUST display bestiary-linked CRs as read-only with the source name visible.
+
+#### FR-020 — CR persistence
+The `cr` field on `Combatant` MUST persist within the encounter across page reloads (via encounter storage) and MUST round-trip through JSON export/import.
+
 ### Key Entities
 
 - **XP Budget Table**: A lookup mapping character level (1-20) to three XP thresholds (Low, Moderate, High), sourced from the 2024 5.5e DMG.
@@ -174,6 +264,7 @@ When total monster XP exceeds the High threshold, the indicator MUST display the
 - **DifficultyTier**: An enumeration of difficulty categories: Trivial, Low, Moderate, High.
 - **DifficultyResult**: The output of the calculation containing the tier, total monster XP, and per-tier budget thresholds.
 - **PlayerCharacter.level**: An optional integer (1-20) added to the existing `PlayerCharacter` entity defined in spec 005.
+- **Combatant.cr**: An optional string field on the existing `Combatant` entity, accepting standard 5e CR values. Used for manual CR assignment on custom combatants. Ignored when the combatant has a `creatureId`.
 
 ---
 
@@ -188,6 +279,8 @@ When total monster XP exceeds the High threshold, the indicator MUST display the
 - **SC-005**: The difficulty calculation is a pure domain function with no I/O, consistent with the project's deterministic domain core.
 - **SC-006**: The domain module for difficulty calculation has zero imports from application, adapter, or UI layers.
 - **SC-007**: The optional level field integrates seamlessly into the existing player character create/edit workflow without disrupting existing functionality.
+- **SC-008**: The difficulty breakdown panel correctly displays per-combatant XP contributions and party budget that sum to the values used for tier determination.
+- **SC-009**: Custom combatants with manually assigned CR contribute correctly to the difficulty calculation, matching the same CR-to-XP mapping used for bestiary creatures.
 
 ---
 
@@ -199,7 +292,7 @@ When total monster XP exceeds the High threshold, the indicator MUST display the
 - The `level` field is added to the existing `PlayerCharacter` type from spec 005. No new entity or storage mechanism is needed.
 - Existing player characters without a level are treated as "no level assigned" with no migration.
 - The difficulty indicator occupies minimal horizontal space in the top bar and does not interfere with the combatant name truncation or other controls.
-- MVP baseline does not include CR assignment for custom (non-bestiary) combatants.
+- The breakdown panel is the sole UI surface for manual CR assignment — there is no CR field in the combatant create/edit forms.
+- MVP baseline does not include assigning combatants to party/enemy sides — all combatants with CR are counted as enemies.
 - MVP baseline does not include the 2014 DMG encounter multiplier mechanic or the four-tier (Easy/Medium/Hard/Deadly) system.
-- MVP baseline does not include showing XP totals or budget numbers in the indicator — only the visual bars and tooltip label.
 - MVP baseline does not include per-combatant level overrides — level is always derived from the player character template.

vitest.config.ts

@@ -18,8 +18,8 @@ export default defineConfig({
 					branches: 90,
 				},
 				"apps/web/src/adapters": {
-					lines: 68,
-					branches: 56,
+					lines: 80,
+					branches: 62,
 				},
 				"apps/web/src/persistence": {
 					lines: 85,