Add PF2e encounter difficulty calculation with 5-tier budget system

Implements PF2e encounter difficulty alongside the existing D&D system.
PF2e uses creature level vs party level to derive XP, compares against
5-tier budgets (Trivial/Low/Moderate/Severe/Extreme), and adjusts
thresholds for party size. The indicator shows 4 bars in PF2e mode.

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

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

@@ -1,5 +1,9 @@
 // @vitest-environment jsdom
-import type { Creature, CreatureId, PlayerCharacter } from "@initiative/domain";
+import type {
+	AnyCreature,
+	CreatureId,
+	PlayerCharacter,
+} from "@initiative/domain";
 import { combatantId, creatureId, playerCharacterId } from "@initiative/domain";
 import { renderHook, waitFor } from "@testing-library/react";
 import type { ReactNode } from "react";
@@ -9,6 +13,7 @@ import {
 	buildCombatant,
 	buildCreature,
 	buildEncounter,
+	buildPf2eCreature,
 } from "../../__tests__/factories/index.js";
 import { AllProviders } from "../../__tests__/test-providers.js";
 import { useDifficultyBreakdown } from "../use-difficulty-breakdown.js";
@@ -42,7 +47,7 @@ const goblinCreature = buildCreature({
 function makeWrapper(options: {
 	encounter: ReturnType<typeof buildEncounter>;
 	playerCharacters?: PlayerCharacter[];
-	creatures?: Map<CreatureId, Creature>;
+	creatures?: Map<CreatureId, AnyCreature>;
 }) {
 	const adapters = createTestAdapters({
 		encounter: options.encounter,
@@ -345,4 +350,115 @@ describe("useDifficultyBreakdown", () => {
 			editionResult.current.setEdition("5.5e");
 		}
 	});
+
+	describe("PF2e edition", () => {
+		const orcWarrior = buildPf2eCreature({
+			id: creatureId("pf2e:orc-warrior"),
+			name: "Orc Warrior",
+			level: 3,
+			source: "crb",
+			sourceDisplayName: "Core Rulebook",
+		});
+
+		it("returns breakdown with creatureLevel, levelDifference, and XP for PF2e creatures", async () => {
+			const wrapper = makeWrapper({
+				encounter: buildEncounter({
+					combatants: [
+						buildCombatant({
+							id: combatantId("c-1"),
+							name: "Hero",
+							playerCharacterId: pcId1,
+						}),
+						buildCombatant({
+							id: combatantId("c-2"),
+							name: "Orc Warrior",
+							creatureId: orcWarrior.id,
+						}),
+					],
+				}),
+				playerCharacters: [
+					{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 },
+				],
+				creatures: new Map([[orcWarrior.id, orcWarrior]]),
+			});
+
+			const { result: editionResult } = renderHook(() => useRulesEdition(), {
+				wrapper,
+			});
+			editionResult.current.setEdition("pf2e");
+
+			try {
+				const { result } = renderHook(() => useDifficultyBreakdown(), {
+					wrapper,
+				});
+
+				await waitFor(() => {
+					const breakdown = result.current;
+					expect(breakdown).not.toBeNull();
+
+					// Party level should be 5
+					expect(breakdown?.partyLevel).toBe(5);
+
+					// Orc Warrior: level 3, party level 5 → diff −2 → 20 XP
+					const orc = breakdown?.enemyCombatants[0];
+					expect(orc?.creatureLevel).toBe(3);
+					expect(orc?.levelDifference).toBe(-2);
+					expect(orc?.xp).toBe(20);
+					expect(orc?.cr).toBeNull();
+					expect(orc?.source).toBe("Core Rulebook");
+
+					// PC should have no creature level
+					const pc = breakdown?.partyCombatants[0];
+					expect(pc?.creatureLevel).toBeUndefined();
+					expect(pc?.levelDifference).toBeUndefined();
+				});
+			} finally {
+				editionResult.current.setEdition("5.5e");
+			}
+		});
+
+		it("returns partyLevel in result", async () => {
+			const wrapper = makeWrapper({
+				encounter: buildEncounter({
+					combatants: [
+						buildCombatant({
+							id: combatantId("c-1"),
+							name: "Hero",
+							playerCharacterId: pcId1,
+						}),
+						buildCombatant({
+							id: combatantId("c-2"),
+							name: "Orc Warrior",
+							creatureId: orcWarrior.id,
+						}),
+					],
+				}),
+				playerCharacters: [
+					{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 },
+				],
+				creatures: new Map([[orcWarrior.id, orcWarrior]]),
+			});
+
+			const { result: editionResult } = renderHook(() => useRulesEdition(), {
+				wrapper,
+			});
+			editionResult.current.setEdition("pf2e");
+
+			try {
+				const { result } = renderHook(() => useDifficultyBreakdown(), {
+					wrapper,
+				});
+
+				await waitFor(() => {
+					expect(result.current).not.toBeNull();
+					expect(result.current?.partyLevel).toBe(5);
+					// 5 thresholds for PF2e
+					expect(result.current?.thresholds).toHaveLength(5);
+					expect(result.current?.thresholds[0].label).toBe("Trivial");
+				});
+			} finally {
+				editionResult.current.setEdition("5.5e");
+			}
+		});
+	});
 });

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

@@ -1,5 +1,9 @@
 // @vitest-environment jsdom
-import type { Creature, CreatureId, PlayerCharacter } from "@initiative/domain";
+import type {
+	AnyCreature,
+	CreatureId,
+	PlayerCharacter,
+} from "@initiative/domain";
 import { combatantId, creatureId, playerCharacterId } from "@initiative/domain";
 import { renderHook, waitFor } from "@testing-library/react";
 import type { ReactNode } from "react";
@@ -9,6 +13,7 @@ import {
 	buildCombatant,
 	buildCreature,
 	buildEncounter,
+	buildPf2eCreature,
 } from "../../__tests__/factories/index.js";
 import { AllProviders } from "../../__tests__/test-providers.js";
 import { useDifficulty } from "../use-difficulty.js";
@@ -43,7 +48,7 @@ const goblinCreature = buildCreature({
 function makeWrapper(options: {
 	encounter: ReturnType<typeof buildEncounter>;
 	playerCharacters?: PlayerCharacter[];
-	creatures?: Map<CreatureId, Creature>;
+	creatures?: Map<CreatureId, AnyCreature>;
 }) {
 	const adapters = createTestAdapters({
 		encounter: options.encounter,
@@ -424,4 +429,134 @@ describe("useDifficulty", () => {
 			expect(result.current?.totalMonsterXp).toBe(0);
 		});
 	});
+
+	describe("PF2e edition", () => {
+		const pf2eCreature = buildPf2eCreature({
+			id: creatureId("pf2e:orc-warrior"),
+			name: "Orc Warrior",
+			level: 5,
+		});
+
+		function makePf2eWrapper(options: {
+			encounter: ReturnType<typeof buildEncounter>;
+			playerCharacters?: PlayerCharacter[];
+			creatures?: Map<CreatureId, AnyCreature>;
+		}) {
+			const adapters = createTestAdapters({
+				encounter: options.encounter,
+				playerCharacters: options.playerCharacters ?? [],
+				creatures: options.creatures,
+			});
+			return ({ children }: { children: ReactNode }) => (
+				<AllProviders adapters={adapters}>{children}</AllProviders>
+			);
+		}
+
+		it("returns result for PF2e with leveled PCs and PF2e creatures", async () => {
+			const wrapper = makePf2eWrapper({
+				encounter: buildEncounter({
+					combatants: [
+						buildCombatant({
+							id: combatantId("c1"),
+							name: "Hero",
+							playerCharacterId: pcId1,
+						}),
+						buildCombatant({
+							id: combatantId("c2"),
+							name: "Orc Warrior",
+							creatureId: pf2eCreature.id,
+						}),
+					],
+				}),
+				playerCharacters: [
+					{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 },
+				],
+				creatures: new Map([[pf2eCreature.id, pf2eCreature]]),
+			});
+
+			const { result: editionResult } = renderHook(() => useRulesEdition(), {
+				wrapper,
+			});
+			editionResult.current.setEdition("pf2e");
+
+			try {
+				const { result } = renderHook(() => useDifficulty(), { wrapper });
+
+				await waitFor(() => {
+					expect(result.current).not.toBeNull();
+					// Creature level 5, party level 5 → diff 0 → 40 XP
+					expect(result.current?.totalMonsterXp).toBe(40);
+					expect(result.current?.partyLevel).toBe(5);
+				});
+			} finally {
+				editionResult.current.setEdition("5.5e");
+			}
+		});
+
+		it("returns null for PF2e when no PF2e creatures with level", () => {
+			const wrapper = makePf2eWrapper({
+				encounter: buildEncounter({
+					combatants: [
+						buildCombatant({
+							id: combatantId("c1"),
+							name: "Hero",
+							playerCharacterId: pcId1,
+						}),
+						buildCombatant({
+							id: combatantId("c2"),
+							name: "Custom Monster",
+						}),
+					],
+				}),
+				playerCharacters: [
+					{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 },
+				],
+			});
+
+			const { result: editionResult } = renderHook(() => useRulesEdition(), {
+				wrapper,
+			});
+			editionResult.current.setEdition("pf2e");
+
+			try {
+				const { result } = renderHook(() => useDifficulty(), { wrapper });
+				expect(result.current).toBeNull();
+			} finally {
+				editionResult.current.setEdition("5.5e");
+			}
+		});
+
+		it("returns null for PF2e when no PCs with level", () => {
+			const wrapper = makePf2eWrapper({
+				encounter: buildEncounter({
+					combatants: [
+						buildCombatant({
+							id: combatantId("c1"),
+							name: "Hero",
+							playerCharacterId: pcId1,
+						}),
+						buildCombatant({
+							id: combatantId("c2"),
+							name: "Orc Warrior",
+							creatureId: pf2eCreature.id,
+						}),
+					],
+				}),
+				playerCharacters: [{ id: pcId1, name: "Hero", ac: 15, maxHp: 30 }],
+				creatures: new Map([[pf2eCreature.id, pf2eCreature]]),
+			});
+
+			const { result: editionResult } = renderHook(() => useRulesEdition(), {
+				wrapper,
+			});
+			editionResult.current.setEdition("pf2e");
+
+			try {
+				const { result } = renderHook(() => useDifficulty(), { wrapper });
+				expect(result.current).toBeNull();
+			} finally {
+				editionResult.current.setEdition("5.5e");
+			}
+		});
+	});
 });

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

@@ -1,11 +1,17 @@
 import type {
+	AnyCreature,
 	Combatant,
 	CreatureId,
 	DifficultyThreshold,
 	DifficultyTier,
 	PlayerCharacter,
 } from "@initiative/domain";
-import { calculateEncounterDifficulty, crToXp } from "@initiative/domain";
+import {
+	calculateEncounterDifficulty,
+	crToXp,
+	derivePartyLevel,
+	pf2eCreatureXp,
+} from "@initiative/domain";
 import { useMemo } from "react";
 import { useBestiaryContext } from "../contexts/bestiary-context.js";
 import { useEncounterContext } from "../contexts/encounter-context.js";
@@ -21,6 +27,10 @@ export interface BreakdownCombatant {
 	readonly editable: boolean;
 	readonly side: "party" | "enemy";
 	readonly level: number | undefined;
+	/** PF2e only: the creature's level from bestiary data. */
+	readonly creatureLevel: number | undefined;
+	/** PF2e only: creature level minus party level. */
+	readonly levelDifference: number | undefined;
 }
 
 interface DifficultyBreakdown {
@@ -30,6 +40,7 @@ interface DifficultyBreakdown {
 	readonly encounterMultiplier: number | undefined;
 	readonly adjustedXp: number | undefined;
 	readonly partySizeAdjusted: boolean | undefined;
+	readonly partyLevel: number | undefined;
 	readonly pcCount: number;
 	readonly partyCombatants: readonly BreakdownCombatant[];
 	readonly enemyCombatants: readonly BreakdownCombatant[];
@@ -48,9 +59,16 @@ export function useDifficultyBreakdown(): DifficultyBreakdown | null {
 		const hasPartyLevel = descriptors.some(
 			(d) => d.side === "party" && d.level !== undefined,
 		);
-		const hasCr = descriptors.some((d) => d.cr !== undefined);
 
-		if (!hasPartyLevel || !hasCr) return null;
+		if (edition === "pf2e") {
+			const hasCreatureLevel = descriptors.some(
+				(d) => d.creatureLevel !== undefined,
+			);
+			if (!hasPartyLevel || !hasCreatureLevel) return null;
+		} else {
+			const hasCr = descriptors.some((d) => d.cr !== undefined);
+			if (!hasPartyLevel || !hasCr) return null;
+		}
 
 		const result = calculateEncounterDifficulty(descriptors, edition);
 
@@ -65,6 +83,7 @@ export function useDifficultyBreakdown(): DifficultyBreakdown | null {
 
 type CreatureInfo = {
 	cr?: string;
+	creatureLevel?: number;
 	source: string;
 	sourceDisplayName: string;
 };
@@ -74,6 +93,7 @@ function buildBreakdownEntry(
 	side: "party" | "enemy",
 	level: number | undefined,
 	creature: CreatureInfo | undefined,
+	partyLevel: number | undefined,
 ): BreakdownCombatant {
 	if (c.playerCharacterId) {
 		return {
@@ -84,6 +104,29 @@ function buildBreakdownEntry(
 			editable: false,
 			side,
 			level,
+			creatureLevel: undefined,
+			levelDifference: undefined,
+		};
+	}
+	if (creature && creature.creatureLevel !== undefined) {
+		const levelDiff =
+			partyLevel === undefined
+				? undefined
+				: creature.creatureLevel - partyLevel;
+		const xp =
+			partyLevel === undefined
+				? null
+				: pf2eCreatureXp(creature.creatureLevel, partyLevel);
+		return {
+			combatant: c,
+			cr: null,
+			xp,
+			source: creature.sourceDisplayName ?? creature.source,
+			editable: false,
+			side,
+			level: undefined,
+			creatureLevel: creature.creatureLevel,
+			levelDifference: levelDiff,
 		};
 	}
 	if (creature) {
@@ -96,6 +139,8 @@ function buildBreakdownEntry(
 			editable: false,
 			side,
 			level: undefined,
+			creatureLevel: undefined,
+			levelDifference: undefined,
 		};
 	}
 	if (c.cr) {
@@ -107,6 +152,8 @@ function buildBreakdownEntry(
 			editable: true,
 			side,
 			level: undefined,
+			creatureLevel: undefined,
+			levelDifference: undefined,
 		};
 	}
 	return {
@@ -117,6 +164,8 @@ function buildBreakdownEntry(
 		editable: !c.creatureId,
 		side,
 		level: undefined,
+		creatureLevel: undefined,
+		levelDifference: undefined,
 	};
 }
 
@@ -128,41 +177,91 @@ function resolveLevel(
 	return characters.find((p) => p.id === c.playerCharacterId)?.level;
 }
 
-function resolveCr(
+function resolveCreatureInfo(
 	c: Combatant,
-	getCreature: (id: CreatureId) => CreatureInfo | undefined,
-): { cr: string | null; creature: CreatureInfo | undefined } {
-	const creature = c.creatureId ? getCreature(c.creatureId) : undefined;
-	const cr = creature?.cr ?? c.cr ?? null;
-	return { cr, creature };
+	getCreature: (id: CreatureId) => AnyCreature | undefined,
+): {
+	cr: string | null;
+	creatureLevel: number | undefined;
+	creature: CreatureInfo | undefined;
+} {
+	const rawCreature = c.creatureId ? getCreature(c.creatureId) : undefined;
+	if (!rawCreature) {
+		return {
+			cr: c.cr ?? null,
+			creatureLevel: undefined,
+			creature: undefined,
+		};
+	}
+	if ("system" in rawCreature && rawCreature.system === "pf2e") {
+		return {
+			cr: null,
+			creatureLevel: rawCreature.level,
+			creature: {
+				creatureLevel: rawCreature.level,
+				source: rawCreature.source,
+				sourceDisplayName: rawCreature.sourceDisplayName,
+			},
+		};
+	}
+	const cr = "cr" in rawCreature ? rawCreature.cr : undefined;
+	return {
+		cr: cr ?? c.cr ?? null,
+		creatureLevel: undefined,
+		creature: {
+			cr,
+			source: rawCreature.source,
+			sourceDisplayName: rawCreature.sourceDisplayName,
+		},
+	};
+}
+
+function collectPartyLevel(
+	combatants: readonly Combatant[],
+	characters: readonly PlayerCharacter[],
+): number | undefined {
+	const partyLevels: number[] = [];
+	for (const c of combatants) {
+		if (resolveSide(c) !== "party") continue;
+		const level = resolveLevel(c, characters);
+		if (level !== undefined) partyLevels.push(level);
+	}
+	return partyLevels.length > 0 ? derivePartyLevel(partyLevels) : undefined;
 }
 
 function classifyCombatants(
 	combatants: readonly Combatant[],
 	characters: readonly PlayerCharacter[],
-	getCreature: (id: CreatureId) => CreatureInfo | undefined,
+	getCreature: (id: CreatureId) => AnyCreature | undefined,
 ) {
 	const partyCombatants: BreakdownCombatant[] = [];
 	const enemyCombatants: BreakdownCombatant[] = [];
 	const descriptors: {
 		level?: number;
 		cr?: string;
+		creatureLevel?: number;
 		side: "party" | "enemy";
 	}[] = [];
 	let pcCount = 0;
+	const partyLevel = collectPartyLevel(combatants, characters);
 
 	for (const c of combatants) {
 		const side = resolveSide(c);
 		const level = resolveLevel(c, characters);
 		if (level !== undefined) pcCount++;
 
-		const { cr, creature } = resolveCr(c, getCreature);
+		const { cr, creatureLevel, creature } = resolveCreatureInfo(c, getCreature);
 
-		if (level !== undefined || cr != null) {
-			descriptors.push({ level, cr: cr ?? undefined, side });
+		if (level !== undefined || cr != null || creatureLevel !== undefined) {
+			descriptors.push({
+				level,
+				cr: cr ?? undefined,
+				creatureLevel,
+				side,
+			});
 		}
 
-		const entry = buildBreakdownEntry(c, side, level, creature);
+		const entry = buildBreakdownEntry(c, side, level, creature, partyLevel);
 		const target = side === "party" ? partyCombatants : enemyCombatants;
 		target.push(entry);
 	}

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

@@ -33,9 +33,17 @@ function buildDescriptors(
 		const creatureCr =
 			creature && !("system" in creature) ? creature.cr : undefined;
 		const cr = creatureCr ?? c.cr ?? undefined;
+		const creatureLevel =
+			creature && "system" in creature && creature.system === "pf2e"
+				? creature.level
+				: undefined;
 
-		if (level !== undefined || cr !== undefined) {
-			descriptors.push({ level, cr, side });
+		if (
+			level !== undefined ||
+			cr !== undefined ||
+			creatureLevel !== undefined
+		) {
+			descriptors.push({ level, cr, creatureLevel, side });
 		}
 	}
 	return descriptors;
@@ -48,8 +56,6 @@ export function useDifficulty(): DifficultyResult | null {
 	const { edition } = useRulesEditionContext();
 
 	return useMemo(() => {
-		if (edition === "pf2e") return null;
-
 		const descriptors = buildDescriptors(
 			encounter.combatants,
 			characters,
@@ -59,9 +65,16 @@ export function useDifficulty(): DifficultyResult | null {
 		const hasPartyLevel = descriptors.some(
 			(d) => d.side === "party" && d.level !== undefined,
 		);
-		const hasCr = descriptors.some((d) => d.cr !== undefined);
 
-		if (!hasPartyLevel || !hasCr) return null;
+		if (edition === "pf2e") {
+			const hasCreatureLevel = descriptors.some(
+				(d) => d.creatureLevel !== undefined,
+			);
+			if (!hasPartyLevel || !hasCreatureLevel) return null;
+		} else {
+			const hasCr = descriptors.some((d) => d.cr !== undefined);
+			if (!hasPartyLevel || !hasCr) return null;
+		}
 
 		return calculateEncounterDifficulty(descriptors, edition);
 	}, [encounter.combatants, characters, getCreature, edition]);