diff --git a/CLAUDE.md b/CLAUDE.md index 7bd121d..31b642d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -69,6 +69,7 @@ docs/agents/ RPI skill artifacts (research reports, plans) - **oxlint** for type-aware linting that Biome can't do. Configured in `.oxlintrc.json`. - **TypeScript strict mode** with `verbatimModuleSyntax`. Use `.js` extensions in relative imports. - **Branded types** for identity values (e.g., `CombatantId`). Prefer immutability/`readonly` where practical. +- **Reuse UI primitives** — before creating custom interactive elements (buttons, inputs, selects, dialogs), check `apps/web/src/components/ui/` for existing components with established variants and hover styles. - **Domain events** are plain data objects with a `type` discriminant — no classes. - **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. diff --git a/apps/web/src/__tests__/export-import.test.ts b/apps/web/src/__tests__/export-import.test.ts index 0f7ce13..7a2b309 100644 --- a/apps/web/src/__tests__/export-import.test.ts +++ b/apps/web/src/__tests__/export-import.test.ts @@ -234,6 +234,57 @@ describe("round-trip: export then import", () => { expect(imported.encounter.combatants[0].cr).toBe("2"); }); + it("round-trips a combatant with side field", () => { + const encounterWithSide: Encounter = { + combatants: [ + { + id: combatantId("c-1"), + name: "Allied Guard", + cr: "2", + side: "party", + }, + { + id: combatantId("c-2"), + name: "Goblin", + side: "enemy", + }, + ], + activeIndex: 0, + roundNumber: 1, + }; + const emptyUndoRedo: UndoRedoState = { + undoStack: [], + redoStack: [], + }; + const bundle = assembleExportBundle(encounterWithSide, 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].side).toBe("party"); + expect(imported.encounter.combatants[1].side).toBe("enemy"); + }); + + it("round-trips a combatant without side field as undefined", () => { + const encounterNoSide: Encounter = { + combatants: [{ id: combatantId("c-1"), name: "Custom" }], + activeIndex: 0, + roundNumber: 1, + }; + const emptyUndoRedo: UndoRedoState = { + undoStack: [], + redoStack: [], + }; + const bundle = assembleExportBundle(encounterNoSide, 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].side).toBeUndefined(); + }); + it("round-trips an empty encounter", () => { const emptyEncounter: Encounter = { combatants: [], diff --git a/apps/web/src/components/__tests__/difficulty-breakdown-panel.test.tsx b/apps/web/src/components/__tests__/difficulty-breakdown-panel.test.tsx index 0f9f2f8..2de9857 100644 --- a/apps/web/src/components/__tests__/difficulty-breakdown-panel.test.tsx +++ b/apps/web/src/components/__tests__/difficulty-breakdown-panel.test.tsx @@ -121,7 +121,7 @@ describe("DifficultyBreakdownPanel", () => { }); }); - it("renders bestiary combatant as read-only with source name", async () => { + it("shows PC in party column with level", async () => { renderPanel({ encounter: defaultEncounter(), playerCharacters: defaultPCs, @@ -129,12 +129,53 @@ describe("DifficultyBreakdownPanel", () => { }); await waitFor(() => { - expect(screen.getByText("Goblin (SRD)")).toBeInTheDocument(); + expect(screen.getByText("Hero")).toBeInTheDocument(); + expect(screen.getByText("Lv 5")).toBeInTheDocument(); + }); + }); + + it("shows monsters in enemy column", async () => { + renderPanel({ + encounter: defaultEncounter(), + playerCharacters: defaultPCs, + creatures: new Map([[goblinCreature.id, goblinCreature]]), + }); + + await waitFor(() => { + expect(screen.getByText("Goblin")).toBeInTheDocument(); expect(screen.getAllByText("CR 1/4").length).toBeGreaterThanOrEqual(1); }); }); - it("renders custom combatant with CR picker", async () => { + it("renders explanation text", async () => { + renderPanel({ + encounter: defaultEncounter(), + playerCharacters: defaultPCs, + creatures: new Map([[goblinCreature.id, goblinCreature]]), + }); + + await waitFor(() => { + expect( + screen.getByText( + "Allied NPC XP is subtracted from encounter difficulty", + ), + ).toBeInTheDocument(); + }); + }); + + it("renders Net Monster XP footer", async () => { + renderPanel({ + encounter: defaultEncounter(), + playerCharacters: defaultPCs, + creatures: new Map([[goblinCreature.id, goblinCreature]]), + }); + + await waitFor(() => { + expect(screen.getByText("Net Monster XP")).toBeInTheDocument(); + }); + }); + + it("renders custom combatant with CR picker in enemy column", async () => { renderPanel({ encounter: defaultEncounter(), playerCharacters: defaultPCs, @@ -144,27 +185,10 @@ describe("DifficultyBreakdownPanel", () => { 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({ @@ -173,24 +197,19 @@ describe("DifficultyBreakdownPanel", () => { creatures: new Map([[goblinCreature.id, goblinCreature]]), }); - // Wait for the panel to render with bestiary data await waitFor(() => { - expect(screen.getByText("—")).toBeInTheDocument(); + expect(screen.getAllByLabelText("Challenge rating")).toHaveLength(2); }); - // 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 () => { + it("non-PC combatants show toggle button", async () => { renderPanel({ encounter: defaultEncounter(), playerCharacters: defaultPCs, @@ -198,12 +217,57 @@ describe("DifficultyBreakdownPanel", () => { }); await waitFor(() => { - expect(screen.getByText("Total Monster XP")).toBeInTheDocument(); + // Each non-PC enemy combatant has a toggle button + expect( + screen.getByLabelText("Move Goblin to party side"), + ).toBeInTheDocument(); + expect( + screen.getByLabelText("Move Custom Thug to party side"), + ).toBeInTheDocument(); + }); + }); + + it("PC combatants do not show side toggle", async () => { + renderPanel({ + encounter: defaultEncounter(), + playerCharacters: defaultPCs, + creatures: new Map([[goblinCreature.id, goblinCreature]]), + }); + + await waitFor(() => { + expect(screen.getByText("Hero")).toBeInTheDocument(); + }); + + expect( + screen.queryByLabelText("Move Hero to enemy side"), + ).not.toBeInTheDocument(); + }); + + it("side toggle moves combatant between sections", async () => { + const user = userEvent.setup(); + renderPanel({ + encounter: defaultEncounter(), + playerCharacters: defaultPCs, + creatures: new Map([[goblinCreature.id, goblinCreature]]), + }); + + await waitFor(() => { + expect(screen.getByText("Goblin")).toBeInTheDocument(); + }); + + // Toggle goblin to party side + const toggleBtn = screen.getByLabelText("Move Goblin to party side"); + await user.click(toggleBtn); + + // After toggle, the aria-label should change to "Move Goblin to enemy side" + await waitFor(() => { + expect( + screen.getByLabelText("Move Goblin to enemy side"), + ).toBeInTheDocument(); }); }); it("renders nothing when breakdown data is insufficient", () => { - // No PCs with level → breakdown returns null const { container } = renderPanel({ encounter: buildEncounter({ combatants: [ diff --git a/apps/web/src/components/difficulty-breakdown-panel.tsx b/apps/web/src/components/difficulty-breakdown-panel.tsx index 72686fe..acdeec4 100644 --- a/apps/web/src/components/difficulty-breakdown-panel.tsx +++ b/apps/web/src/components/difficulty-breakdown-panel.tsx @@ -1,4 +1,5 @@ import type { DifficultyTier } from "@initiative/domain"; +import { ArrowLeftRight } from "lucide-react"; import { useRef } from "react"; import { useEncounterContext } from "../contexts/encounter-context.js"; import { useClickOutside } from "../hooks/use-click-outside.js"; @@ -7,6 +8,7 @@ import { useDifficultyBreakdown, } from "../hooks/use-difficulty-breakdown.js"; import { CrPicker } from "./cr-picker.js"; +import { Button } from "./ui/button.js"; const TIER_LABELS: Record = { trivial: { label: "Trivial", color: "text-muted-foreground" }, @@ -19,19 +21,55 @@ function formatXp(xp: number): string { return xp.toLocaleString(); } -function CombatantRow({ entry }: { entry: BreakdownCombatant }) { - const { setCr } = useEncounterContext(); +function PcRow({ entry }: { entry: BreakdownCombatant }) { + return ( +
+ + {entry.combatant.name} + + + + {entry.level === undefined ? "\u2014" : `Lv ${entry.level}`} + + {"\u2014"} +
+ ); +} - const nameLabel = entry.source - ? `${entry.combatant.name} (${entry.source})` - : entry.combatant.name; +function NpcRow({ + entry, + onToggleSide, +}: { + entry: BreakdownCombatant; + onToggleSide: () => void; +}) { + const { setCr } = useEncounterContext(); + const isParty = entry.side === "party"; + const targetSide = isParty ? "enemy" : "party"; + + let xpDisplay: string; + if (entry.xp == null) { + xpDisplay = "\u2014"; + } else if (isParty && entry.cr) { + xpDisplay = `\u2212${formatXp(entry.xp)}`; + } else { + xpDisplay = formatXp(entry.xp); + } return ( -
- - {nameLabel} +
+ + {entry.combatant.name} -
+ + {entry.editable ? ( ) : ( - {entry.cr ? `CR ${entry.cr}` : "—"} + {entry.cr ? `CR ${entry.cr}` : "\u2014"} )} - - {entry.xp == null ? "—" : formatXp(entry.xp)} - -
+ + {xpDisplay}
); } @@ -53,16 +89,25 @@ function CombatantRow({ entry }: { entry: BreakdownCombatant }) { export function DifficultyBreakdownPanel({ onClose }: { onClose: () => void }) { const ref = useRef(null); useClickOutside(ref, onClose); + const { setSide } = useEncounterContext(); const breakdown = useDifficultyBreakdown(); if (!breakdown) return null; const tierConfig = TIER_LABELS[breakdown.tier]; + const handleToggle = (entry: BreakdownCombatant) => { + const newSide = entry.side === "party" ? "enemy" : "party"; + setSide(entry.combatant.id, newSide); + }; + + const isPC = (entry: BreakdownCombatant) => + entry.combatant.playerCharacterId != null; + return (
Encounter Difficulty:{" "} @@ -87,22 +132,55 @@ export function DifficultyBreakdownPanel({ onClose }: { onClose: () => void }) {
+
+ Allied NPC XP is subtracted from encounter difficulty +
+
- Monsters + Party XP
-
- {breakdown.combatants.map((entry) => ( - - ))} +
+ {breakdown.partyCombatants.map((entry) => + isPC(entry) ? ( + + ) : ( + handleToggle(entry)} + /> + ), + )}
-
- Total Monster XP - - {formatXp(breakdown.totalMonsterXp)} - +
+ +
+
+ Enemy + XP
+
+ {breakdown.enemyCombatants.map((entry) => + isPC(entry) ? ( + + ) : ( + handleToggle(entry)} + /> + ), + )} +
+
+ +
+ Net Monster XP + + {formatXp(breakdown.totalMonsterXp)} +
); diff --git a/apps/web/src/hooks/__tests__/use-difficulty-breakdown.test.tsx b/apps/web/src/hooks/__tests__/use-difficulty-breakdown.test.tsx index 5520084..178c316 100644 --- a/apps/web/src/hooks/__tests__/use-difficulty-breakdown.test.tsx +++ b/apps/web/src/hooks/__tests__/use-difficulty-breakdown.test.tsx @@ -106,7 +106,7 @@ describe("useDifficultyBreakdown", () => { expect(result.current).toBeNull(); }); - it("returns per-combatant entries with correct data", async () => { + it("returns per-combatant entries split by side", async () => { const wrapper = makeWrapper({ encounter: buildEncounter({ combatants: [ @@ -145,29 +145,34 @@ describe("useDifficultyBreakdown", () => { const breakdown = result.current; expect(breakdown).not.toBeNull(); expect(breakdown?.pcCount).toBe(1); - // CR 1/4 = 50 + CR 2 = 450 → total 500 + // 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]; + // PC in party column + expect(breakdown?.partyCombatants).toHaveLength(1); + expect(breakdown?.partyCombatants[0].combatant.name).toBe("Hero"); + expect(breakdown?.partyCombatants[0].side).toBe("party"); + expect(breakdown?.partyCombatants[0].level).toBe(5); + + // Enemies: goblin, thug, bandit + expect(breakdown?.enemyCombatants).toHaveLength(3); + + const goblin = breakdown?.enemyCombatants[0]; expect(goblin?.cr).toBe("1/4"); expect(goblin?.xp).toBe(50); expect(goblin?.source).toBe("SRD"); expect(goblin?.editable).toBe(false); + expect(goblin?.side).toBe("enemy"); - // Custom with CR - const thug = breakdown?.combatants[1]; + const thug = breakdown?.enemyCombatants[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]; + const bandit = breakdown?.enemyCombatants[2]; expect(bandit?.cr).toBeNull(); expect(bandit?.xp).toBeNull(); - expect(bandit?.source).toBeNull(); expect(bandit?.editable).toBe(true); }); }); @@ -203,16 +208,15 @@ describe("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]; + const ghost = breakdown?.enemyCombatants[0]; expect(ghost?.cr).toBeNull(); expect(ghost?.xp).toBeNull(); expect(ghost?.editable).toBe(false); }); - it("excludes PC combatants from breakdown entries", async () => { + it("PC combatants appear in partyCombatants with level", async () => { const wrapper = makeWrapper({ encounter: buildEncounter({ combatants: [ @@ -239,8 +243,53 @@ describe("useDifficultyBreakdown", () => { }); await waitFor(() => { - expect(result.current?.combatants).toHaveLength(1); - expect(result.current?.combatants[0].combatant.name).toBe("Goblin"); + expect(result.current?.partyCombatants).toHaveLength(1); + expect(result.current?.partyCombatants[0].combatant.name).toBe("Hero"); + expect(result.current?.partyCombatants[0].level).toBe(1); + expect(result.current?.partyCombatants[0].side).toBe("party"); }); }); + + it("combatant with explicit side override is placed correctly", () => { + const wrapper = makeWrapper({ + encounter: buildEncounter({ + combatants: [ + buildCombatant({ + id: combatantId("c-1"), + name: "Hero", + playerCharacterId: pcId1, + }), + buildCombatant({ + id: combatantId("c-2"), + name: "Allied Guard", + creatureId: goblinCreature.id, + side: "party", + }), + buildCombatant({ + id: combatantId("c-3"), + name: "Thug", + cr: "1", + }), + ], + }), + playerCharacters: [ + { id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 }, + ], + creatures: new Map([[goblinCreature.id, goblinCreature]]), + }); + + const { result } = renderHook(() => useDifficultyBreakdown(), { + wrapper, + }); + + const breakdown = result.current; + expect(breakdown).not.toBeNull(); + // Allied Guard should be in party column + expect(breakdown?.partyCombatants).toHaveLength(2); + expect(breakdown?.partyCombatants[1].combatant.name).toBe("Allied Guard"); + expect(breakdown?.partyCombatants[1].side).toBe("party"); + // Thug in enemy column + expect(breakdown?.enemyCombatants).toHaveLength(1); + expect(breakdown?.enemyCombatants[0].combatant.name).toBe("Thug"); + }); }); diff --git a/apps/web/src/hooks/__tests__/use-difficulty.test.ts b/apps/web/src/hooks/__tests__/use-difficulty.test.ts deleted file mode 100644 index 1ab3fdf..0000000 --- a/apps/web/src/hooks/__tests__/use-difficulty.test.ts +++ /dev/null @@ -1,220 +0,0 @@ -// @vitest-environment jsdom -import type { - Combatant, - CreatureId, - Encounter, - PlayerCharacter, -} from "@initiative/domain"; -import { combatantId, creatureId, playerCharacterId } from "@initiative/domain"; -import { renderHook } from "@testing-library/react"; -import { beforeEach, describe, expect, it, vi } from "vitest"; - -vi.mock("../../contexts/encounter-context.js", () => ({ - useEncounterContext: vi.fn(), -})); - -vi.mock("../../contexts/player-characters-context.js", () => ({ - usePlayerCharactersContext: vi.fn(), -})); - -vi.mock("../../contexts/bestiary-context.js", () => ({ - useBestiaryContext: vi.fn(), -})); - -import { useBestiaryContext } from "../../contexts/bestiary-context.js"; -import { useEncounterContext } from "../../contexts/encounter-context.js"; -import { usePlayerCharactersContext } from "../../contexts/player-characters-context.js"; -import { useDifficulty } from "../use-difficulty.js"; - -const mockEncounterContext = vi.mocked(useEncounterContext); -const mockPlayerCharactersContext = vi.mocked(usePlayerCharactersContext); -const mockBestiaryContext = vi.mocked(useBestiaryContext); - -const pcId1 = playerCharacterId("pc-1"); -const pcId2 = playerCharacterId("pc-2"); -const crId1 = creatureId("creature-1"); -const _crId2 = creatureId("creature-2"); - -function setup(options: { - combatants: Combatant[]; - characters: PlayerCharacter[]; - creatures: Map; -}) { - const encounter = { - combatants: options.combatants, - activeIndex: 0, - roundNumber: 1, - } as Encounter; - - mockEncounterContext.mockReturnValue({ - encounter, - } as ReturnType); - - mockPlayerCharactersContext.mockReturnValue({ - characters: options.characters, - } as ReturnType); - - mockBestiaryContext.mockReturnValue({ - getCreature: (id: CreatureId) => options.creatures.get(id), - } as ReturnType); -} - -beforeEach(() => { - vi.clearAllMocks(); -}); - -describe("useDifficulty", () => { - it("returns difficulty result for leveled PCs and bestiary monsters", () => { - setup({ - combatants: [ - { id: combatantId("c1"), name: "Hero", playerCharacterId: pcId1 }, - { id: combatantId("c2"), name: "Goblin", creatureId: crId1 }, - ], - characters: [{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 1 }], - creatures: new Map([[crId1, { cr: "1/4" }]]), - }); - - const { result } = renderHook(() => useDifficulty()); - - expect(result.current).not.toBeNull(); - expect(result.current?.tier).toBe("low"); - expect(result.current?.totalMonsterXp).toBe(50); - }); - - describe("returns null when data is insufficient (ED-2)", () => { - it("returns null when encounter has no combatants", () => { - setup({ combatants: [], characters: [], creatures: new Map() }); - - const { result } = renderHook(() => useDifficulty()); - expect(result.current).toBeNull(); - }); - - it("returns null when only custom combatants (no creatureId)", () => { - setup({ - combatants: [ - { - id: combatantId("c1"), - name: "Custom", - playerCharacterId: pcId1, - }, - ], - characters: [{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 }], - creatures: new Map(), - }); - - const { result } = renderHook(() => useDifficulty()); - expect(result.current).toBeNull(); - }); - - it("returns null when bestiary monsters present but no PC combatants", () => { - setup({ - combatants: [ - { id: combatantId("c1"), name: "Goblin", creatureId: crId1 }, - ], - characters: [], - creatures: new Map([[crId1, { cr: "1" }]]), - }); - - const { result } = renderHook(() => useDifficulty()); - expect(result.current).toBeNull(); - }); - - it("returns null when PC combatants have no level", () => { - setup({ - combatants: [ - { - id: combatantId("c1"), - name: "Hero", - playerCharacterId: pcId1, - }, - { id: combatantId("c2"), name: "Goblin", creatureId: crId1 }, - ], - characters: [{ id: pcId1, name: "Hero", ac: 15, maxHp: 30 }], - creatures: new Map([[crId1, { cr: "1" }]]), - }); - - const { result } = renderHook(() => useDifficulty()); - expect(result.current).toBeNull(); - }); - - it("returns null when PC combatant references unknown player character", () => { - setup({ - combatants: [ - { - id: combatantId("c1"), - name: "Hero", - playerCharacterId: pcId2, - }, - { id: combatantId("c2"), name: "Goblin", creatureId: crId1 }, - ], - characters: [{ id: pcId1, name: "Other", ac: 15, maxHp: 30, level: 5 }], - creatures: new Map([[crId1, { cr: "1" }]]), - }); - - const { result } = renderHook(() => useDifficulty()); - expect(result.current).toBeNull(); - }); - }); - - it("handles mixed combatants: only leveled PCs and bestiary monsters contribute", () => { - // Party: one leveled PC, one without level (excluded) - // Monsters: one bestiary creature, one custom (excluded) - setup({ - combatants: [ - { - id: combatantId("c1"), - name: "Leveled", - playerCharacterId: pcId1, - }, - { - id: combatantId("c2"), - name: "No Level", - playerCharacterId: pcId2, - }, - { id: combatantId("c3"), name: "Goblin", creatureId: crId1 }, - { id: combatantId("c4"), name: "Custom Monster" }, - ], - characters: [ - { id: pcId1, name: "Leveled", ac: 15, maxHp: 30, level: 1 }, - { id: pcId2, name: "No Level", ac: 12, maxHp: 20 }, - ], - creatures: new Map([[crId1, { cr: "1" }]]), - }); - - const { result } = renderHook(() => useDifficulty()); - - expect(result.current).not.toBeNull(); - // 1 level-1 PC: budget low=50, mod=75, high=100 - // 1 CR 1 monster: 200 XP → high (200 >= 100) - expect(result.current?.tier).toBe("high"); - expect(result.current?.totalMonsterXp).toBe(200); - expect(result.current?.partyBudget.low).toBe(50); - }); - - it("includes duplicate PC combatants in budget", () => { - // Same PC added twice → counts twice - setup({ - combatants: [ - { - id: combatantId("c1"), - name: "Hero 1", - playerCharacterId: pcId1, - }, - { - id: combatantId("c2"), - name: "Hero 2", - playerCharacterId: pcId1, - }, - { id: combatantId("c3"), name: "Goblin", creatureId: crId1 }, - ], - characters: [{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 1 }], - creatures: new Map([[crId1, { cr: "1/4" }]]), - }); - - const { result } = renderHook(() => useDifficulty()); - - expect(result.current).not.toBeNull(); - // 2x level 1: budget low=100 - expect(result.current?.partyBudget.low).toBe(100); - }); -}); diff --git a/apps/web/src/hooks/__tests__/use-difficulty.test.tsx b/apps/web/src/hooks/__tests__/use-difficulty.test.tsx new file mode 100644 index 0000000..a65e201 --- /dev/null +++ b/apps/web/src/hooks/__tests__/use-difficulty.test.tsx @@ -0,0 +1,381 @@ +// @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 pcId2 = playerCharacterId("pc-2"); +const crId1 = creatureId("srd:goblin"); + +const goblinCreature = buildCreature({ + id: crId1, + name: "Goblin", + cr: "1/4", +}); + +function makeWrapper(options: { + encounter: ReturnType; + playerCharacters?: PlayerCharacter[]; + creatures?: Map; +}) { + const adapters = createTestAdapters({ + encounter: options.encounter, + playerCharacters: options.playerCharacters ?? [], + creatures: options.creatures, + }); + return ({ children }: { children: ReactNode }) => ( + {children} + ); +} + +describe("useDifficulty", () => { + it("returns difficulty result for leveled PCs and bestiary monsters", async () => { + const wrapper = makeWrapper({ + encounter: buildEncounter({ + combatants: [ + buildCombatant({ + id: combatantId("c1"), + name: "Hero", + playerCharacterId: pcId1, + }), + buildCombatant({ + id: combatantId("c2"), + name: "Goblin", + creatureId: crId1, + }), + ], + }), + playerCharacters: [ + { id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 1 }, + ], + creatures: new Map([[crId1, goblinCreature]]), + }); + + const { result } = renderHook(() => useDifficulty(), { wrapper }); + + await waitFor(() => { + expect(result.current).not.toBeNull(); + expect(result.current?.tier).toBe("low"); + expect(result.current?.totalMonsterXp).toBe(50); + }); + }); + + describe("returns null when data is insufficient (ED-2)", () => { + it("returns null when encounter has no combatants", () => { + const wrapper = makeWrapper({ + encounter: buildEncounter({ combatants: [] }), + }); + + const { result } = renderHook(() => useDifficulty(), { wrapper }); + expect(result.current).toBeNull(); + }); + + it("returns null when only custom combatants (no creatureId)", () => { + const wrapper = makeWrapper({ + encounter: buildEncounter({ + combatants: [ + buildCombatant({ + id: combatantId("c1"), + name: "Custom", + playerCharacterId: pcId1, + }), + ], + }), + playerCharacters: [ + { id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 }, + ], + }); + + const { result } = renderHook(() => useDifficulty(), { wrapper }); + expect(result.current).toBeNull(); + }); + + it("returns null when bestiary monsters present but no PC combatants", () => { + const wrapper = makeWrapper({ + encounter: buildEncounter({ + combatants: [ + buildCombatant({ + id: combatantId("c1"), + name: "Goblin", + creatureId: crId1, + }), + ], + }), + creatures: new Map([[crId1, goblinCreature]]), + }); + + const { result } = renderHook(() => useDifficulty(), { wrapper }); + expect(result.current).toBeNull(); + }); + + it("returns null when PC combatants have no level", () => { + const wrapper = makeWrapper({ + encounter: buildEncounter({ + combatants: [ + buildCombatant({ + id: combatantId("c1"), + name: "Hero", + playerCharacterId: pcId1, + }), + buildCombatant({ + id: combatantId("c2"), + name: "Goblin", + creatureId: crId1, + }), + ], + }), + playerCharacters: [{ id: pcId1, name: "Hero", ac: 15, maxHp: 30 }], + creatures: new Map([[crId1, goblinCreature]]), + }); + + const { result } = renderHook(() => useDifficulty(), { wrapper }); + expect(result.current).toBeNull(); + }); + + it("returns null when PC combatant references unknown player character", () => { + const wrapper = makeWrapper({ + encounter: buildEncounter({ + combatants: [ + buildCombatant({ + id: combatantId("c1"), + name: "Hero", + playerCharacterId: pcId2, + }), + buildCombatant({ + id: combatantId("c2"), + name: "Goblin", + creatureId: crId1, + }), + ], + }), + playerCharacters: [ + { id: pcId1, name: "Other", ac: 15, maxHp: 30, level: 5 }, + ], + creatures: new Map([[crId1, goblinCreature]]), + }); + + const { result } = renderHook(() => useDifficulty(), { wrapper }); + expect(result.current).toBeNull(); + }); + }); + + it("handles mixed combatants: only leveled PCs and CR-bearing monsters contribute", async () => { + const wrapper = makeWrapper({ + encounter: buildEncounter({ + combatants: [ + buildCombatant({ + id: combatantId("c1"), + name: "Leveled", + playerCharacterId: pcId1, + }), + buildCombatant({ + id: combatantId("c2"), + name: "No Level", + playerCharacterId: pcId2, + }), + buildCombatant({ + id: combatantId("c3"), + name: "Goblin", + creatureId: crId1, + }), + buildCombatant({ + id: combatantId("c4"), + name: "Custom Monster", + }), + ], + }), + playerCharacters: [ + { id: pcId1, name: "Leveled", ac: 15, maxHp: 30, level: 1 }, + { id: pcId2, name: "No Level", ac: 12, maxHp: 20 }, + ], + creatures: new Map([[crId1, goblinCreature]]), + }); + + const { result } = renderHook(() => useDifficulty(), { wrapper }); + + await waitFor(() => { + expect(result.current).not.toBeNull(); + // 1 level-1 PC: budget low=50, mod=75, high=100 + // CR 1/4 = 50 XP -> low (50 >= 50) + expect(result.current?.tier).toBe("low"); + expect(result.current?.totalMonsterXp).toBe(50); + expect(result.current?.partyBudget.low).toBe(50); + }); + }); + + it("includes duplicate PC combatants in budget", async () => { + const wrapper = makeWrapper({ + encounter: buildEncounter({ + combatants: [ + buildCombatant({ + id: combatantId("c1"), + name: "Hero 1", + playerCharacterId: pcId1, + }), + buildCombatant({ + id: combatantId("c2"), + name: "Hero 2", + playerCharacterId: pcId1, + }), + buildCombatant({ + id: combatantId("c3"), + name: "Goblin", + creatureId: crId1, + }), + ], + }), + playerCharacters: [ + { id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 1 }, + ], + creatures: new Map([[crId1, goblinCreature]]), + }); + + const { result } = renderHook(() => useDifficulty(), { wrapper }); + + await waitFor(() => { + expect(result.current).not.toBeNull(); + // 2x level 1: budget low=100 + expect(result.current?.partyBudget.low).toBe(100); + }); + }); + + it("combatant toggled to party side subtracts XP", async () => { + const bugbear = buildCreature({ + id: creatureId("srd:bugbear"), + name: "Bugbear", + cr: "1", + }); + const wrapper = makeWrapper({ + encounter: buildEncounter({ + combatants: [ + buildCombatant({ + id: combatantId("c1"), + name: "Hero", + playerCharacterId: pcId1, + }), + buildCombatant({ + id: combatantId("c2"), + name: "Allied Guard", + creatureId: bugbear.id, + side: "party", + }), + buildCombatant({ + id: combatantId("c3"), + name: "Thug", + cr: "1", + }), + ], + }), + playerCharacters: [ + { id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 1 }, + ], + creatures: new Map([[bugbear.id, bugbear]]), + }); + + const { result } = renderHook(() => useDifficulty(), { wrapper }); + + await waitFor(() => { + expect(result.current).not.toBeNull(); + // Thug CR 1 = 200 XP, Allied Guard CR 1 = 200 XP subtracted, net = 0 + expect(result.current?.totalMonsterXp).toBe(0); + expect(result.current?.tier).toBe("trivial"); + }); + }); + + it("default side resolution: PC -> party, non-PC -> enemy", async () => { + const wrapper = makeWrapper({ + encounter: buildEncounter({ + combatants: [ + buildCombatant({ + id: combatantId("c1"), + name: "Hero", + playerCharacterId: pcId1, + }), + buildCombatant({ + id: combatantId("c2"), + name: "Goblin", + creatureId: crId1, + }), + ], + }), + playerCharacters: [ + { id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 3 }, + ], + creatures: new Map([[crId1, goblinCreature]]), + }); + + const { result } = renderHook(() => useDifficulty(), { wrapper }); + + await waitFor(() => { + expect(result.current).not.toBeNull(); + // Level 3 budget: low=150, mod=225, high=400 + // CR 1/4 = 50 XP -> trivial + expect(result.current?.partyBudget.low).toBe(150); + expect(result.current?.totalMonsterXp).toBe(50); + expect(result.current?.tier).toBe("trivial"); + }); + }); + + it("custom combatant with CR on party side subtracts XP", async () => { + const wrapper = makeWrapper({ + encounter: buildEncounter({ + combatants: [ + buildCombatant({ + id: combatantId("c1"), + name: "Hero", + playerCharacterId: pcId1, + }), + buildCombatant({ + id: combatantId("c2"), + name: "Ally", + cr: "2", + side: "party", + }), + buildCombatant({ + id: combatantId("c3"), + name: "Goblin", + creatureId: crId1, + }), + ], + }), + playerCharacters: [ + { id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 }, + ], + creatures: new Map([[crId1, goblinCreature]]), + }); + + const { result } = renderHook(() => useDifficulty(), { wrapper }); + + await waitFor(() => { + expect(result.current).not.toBeNull(); + // CR 1/4 = 50 XP enemy, CR 2 = 450 XP ally subtracted, net = 0 (floored) + expect(result.current?.totalMonsterXp).toBe(0); + }); + }); +}); diff --git a/apps/web/src/hooks/use-difficulty-breakdown.ts b/apps/web/src/hooks/use-difficulty-breakdown.ts index 9515023..469e5e7 100644 --- a/apps/web/src/hooks/use-difficulty-breakdown.ts +++ b/apps/web/src/hooks/use-difficulty-breakdown.ts @@ -9,6 +9,7 @@ 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"; +import { resolveSide } from "./use-difficulty.js"; export interface BreakdownCombatant { readonly combatant: Combatant; @@ -16,6 +17,8 @@ export interface BreakdownCombatant { readonly xp: number | null; readonly source: string | null; readonly editable: boolean; + readonly side: "party" | "enemy"; + readonly level: number | undefined; } interface DifficultyBreakdown { @@ -27,7 +30,8 @@ interface DifficultyBreakdown { readonly high: number; }; readonly pcCount: number; - readonly combatants: readonly BreakdownCombatant[]; + readonly partyCombatants: readonly BreakdownCombatant[]; + readonly enemyCombatants: readonly BreakdownCombatant[]; } export function useDifficultyBreakdown(): DifficultyBreakdown | null { @@ -36,105 +40,129 @@ export function useDifficultyBreakdown(): DifficultyBreakdown | null { const { getCreature } = useBestiaryContext(); return useMemo(() => { - const partyLevels = derivePartyLevels(encounter.combatants, characters); - const { entries, crs } = classifyCombatants( - encounter.combatants, - getCreature, + const { partyCombatants, enemyCombatants, descriptors, pcCount } = + classifyCombatants(encounter.combatants, characters, getCreature); + + const hasPartyLevel = descriptors.some( + (d) => d.side === "party" && d.level !== undefined, ); + const hasCr = descriptors.some((d) => d.cr !== undefined); - if (partyLevels.length === 0 || crs.length === 0) { - return null; - } + if (!hasPartyLevel || !hasCr) return null; - const result = calculateEncounterDifficulty(partyLevels, crs); + const result = calculateEncounterDifficulty(descriptors); return { ...result, - pcCount: partyLevels.length, - combatants: entries, + pcCount, + partyCombatants, + enemyCombatants, }; }, [encounter.combatants, characters, getCreature]); } -function classifyBestiaryCombatant( +type CreatureInfo = { + cr: string; + source: string; + sourceDisplayName: string; +}; + +function buildBreakdownEntry( 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) { + side: "party" | "enemy", + level: number | undefined, + creature: CreatureInfo | undefined, +): BreakdownCombatant { + if (c.playerCharacterId) { 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, - }, + side, + level, + }; + } + if (creature) { + return { + combatant: c, + cr: creature.cr, + xp: crToXp(creature.cr), + source: creature.sourceDisplayName ?? creature.source, + editable: false, + side, + level: undefined, + }; + } + if (c.cr) { + return { + combatant: c, + cr: c.cr, + xp: crToXp(c.cr), + source: null, + editable: true, + side, + level: undefined, + }; + } + return { + combatant: c, cr: null, + xp: null, + source: null, + editable: !c.creatureId, + side, + level: undefined, }; } +function resolveLevel( + c: Combatant, + characters: readonly PlayerCharacter[], +): number | undefined { + if (!c.playerCharacterId) return undefined; + return characters.find((p) => p.id === c.playerCharacterId)?.level; +} + +function resolveCr( + c: Combatant, + getCreature: (id: CreatureId) => CreatureInfo | undefined, +): { cr: string | null; creature: CreatureInfo | undefined } { + const creature = c.creatureId ? getCreature(c.creatureId) : undefined; + const cr = creature ? creature.cr : (c.cr ?? null); + return { cr, creature }; +} + 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[] = []; + getCreature: (id: CreatureId) => CreatureInfo | undefined, +) { + const partyCombatants: BreakdownCombatant[] = []; + const enemyCombatants: BreakdownCombatant[] = []; + const descriptors: { + level?: number; + cr?: string; + side: "party" | "enemy"; + }[] = []; + let pcCount = 0; + 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); + const side = resolveSide(c); + const level = resolveLevel(c, characters); + if (level !== undefined) pcCount++; + + const { cr, creature } = resolveCr(c, getCreature); + + if (level !== undefined || cr != null) { + descriptors.push({ level, cr: cr ?? undefined, side }); + } + + const entry = buildBreakdownEntry(c, side, level, creature); + const target = side === "party" ? partyCombatants : enemyCombatants; + target.push(entry); } - return levels; + + return { partyCombatants, enemyCombatants, descriptors, pcCount }; } diff --git a/apps/web/src/hooks/use-difficulty.ts b/apps/web/src/hooks/use-difficulty.ts index 360f370..70522aa 100644 --- a/apps/web/src/hooks/use-difficulty.ts +++ b/apps/web/src/hooks/use-difficulty.ts @@ -1,5 +1,6 @@ import type { Combatant, + CombatantDescriptor, CreatureId, DifficultyResult, PlayerCharacter, @@ -10,33 +11,31 @@ import { useBestiaryContext } from "../contexts/bestiary-context.js"; import { useEncounterContext } from "../contexts/encounter-context.js"; import { usePlayerCharactersContext } from "../contexts/player-characters-context.js"; -function derivePartyLevels( - combatants: readonly Combatant[], - characters: readonly PlayerCharacter[], -): number[] { - const levels: number[] = []; - for (const c of combatants) { - if (!c.playerCharacterId) continue; - const pc = characters.find((p) => p.id === c.playerCharacterId); - if (pc?.level !== undefined) levels.push(pc.level); - } - return levels; +export function resolveSide(c: Combatant): "party" | "enemy" { + if (c.side) return c.side; + return c.playerCharacterId ? "party" : "enemy"; } -function deriveMonsterCrs( +function buildDescriptors( combatants: readonly Combatant[], + characters: readonly PlayerCharacter[], getCreature: (id: CreatureId) => { cr: string } | undefined, -): string[] { - const crs: string[] = []; +): CombatantDescriptor[] { + const descriptors: CombatantDescriptor[] = []; for (const c of combatants) { - if (c.creatureId) { - const creature = getCreature(c.creatureId); - if (creature) crs.push(creature.cr); - } else if (c.cr) { - crs.push(c.cr); + const side = resolveSide(c); + const level = c.playerCharacterId + ? characters.find((p) => p.id === c.playerCharacterId)?.level + : undefined; + const cr = c.creatureId + ? getCreature(c.creatureId)?.cr + : (c.cr ?? undefined); + + if (level !== undefined || cr !== undefined) { + descriptors.push({ level, cr, side }); } } - return crs; + return descriptors; } export function useDifficulty(): DifficultyResult | null { @@ -45,13 +44,19 @@ export function useDifficulty(): DifficultyResult | null { const { getCreature } = useBestiaryContext(); return useMemo(() => { - const partyLevels = derivePartyLevels(encounter.combatants, characters); - const monsterCrs = deriveMonsterCrs(encounter.combatants, getCreature); + const descriptors = buildDescriptors( + encounter.combatants, + characters, + getCreature, + ); - if (partyLevels.length === 0 || monsterCrs.length === 0) { - return null; - } + const hasPartyLevel = descriptors.some( + (d) => d.side === "party" && d.level !== undefined, + ); + const hasCr = descriptors.some((d) => d.cr !== undefined); - return calculateEncounterDifficulty(partyLevels, monsterCrs); + if (!hasPartyLevel || !hasCr) return null; + + return calculateEncounterDifficulty(descriptors); }, [encounter.combatants, characters, getCreature]); } diff --git a/apps/web/src/hooks/use-encounter.ts b/apps/web/src/hooks/use-encounter.ts index 95dfd0f..7f0a6a5 100644 --- a/apps/web/src/hooks/use-encounter.ts +++ b/apps/web/src/hooks/use-encounter.ts @@ -12,6 +12,7 @@ import { setCrUseCase, setHpUseCase, setInitiativeUseCase, + setSideUseCase, setTempHpUseCase, toggleConcentrationUseCase, toggleConditionUseCase, @@ -54,6 +55,7 @@ type EncounterAction = | { 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: "set-side"; id: CombatantId; value: "party" | "enemy" } | { type: "toggle-condition"; id: CombatantId; @@ -321,6 +323,7 @@ function dispatchEncounterAction( | { type: "set-temp-hp" } | { type: "set-ac" } | { type: "set-cr" } + | { type: "set-side" } | { type: "toggle-condition" } | { type: "toggle-concentration" } >, @@ -364,6 +367,9 @@ function dispatchEncounterAction( case "set-cr": result = setCrUseCase(store, action.id, action.value); break; + case "set-side": + result = setSideUseCase(store, action.id, action.value); + break; case "toggle-condition": result = toggleConditionUseCase(store, action.id, action.conditionId); break; @@ -506,6 +512,11 @@ export function useEncounter() { dispatch({ type: "set-cr", id, value }), [], ), + setSide: useCallback( + (id: CombatantId, value: "party" | "enemy") => + dispatch({ type: "set-side", id, value }), + [], + ), toggleCondition: useCallback( (id: CombatantId, conditionId: ConditionId) => dispatch({ type: "toggle-condition", id, conditionId }), diff --git a/apps/web/src/persistence/__tests__/encounter-storage.test.ts b/apps/web/src/persistence/__tests__/encounter-storage.test.ts index 791f165..05deb60 100644 --- a/apps/web/src/persistence/__tests__/encounter-storage.test.ts +++ b/apps/web/src/persistence/__tests__/encounter-storage.test.ts @@ -154,6 +154,47 @@ describe("loadEncounter", () => { expect(loaded?.combatants[0].cr).toBe("2"); }); + it("round-trip preserves combatant side field", () => { + const result = createEncounter( + [ + { + id: combatantId("c-1"), + name: "Allied Guard", + cr: "2", + side: "party", + }, + { + id: combatantId("c-2"), + name: "Goblin", + side: "enemy", + }, + ], + 0, + 1, + ); + if (isDomainError(result)) throw new Error("unreachable"); + saveEncounter(result); + const loaded = loadEncounter(); + + expect(loaded).not.toBeNull(); + expect(loaded?.combatants[0].side).toBe("party"); + expect(loaded?.combatants[1].side).toBe("enemy"); + }); + + it("round-trip preserves combatant without side field as undefined", () => { + const result = createEncounter( + [{ id: combatantId("c-1"), name: "Custom" }], + 0, + 1, + ); + if (isDomainError(result)) throw new Error("unreachable"); + saveEncounter(result); + const loaded = loadEncounter(); + + expect(loaded).not.toBeNull(); + expect(loaded?.combatants[0].side).toBeUndefined(); + }); + it("saving after modifications persists the latest state", () => { const encounter = makeEncounter(); saveEncounter(encounter); diff --git a/packages/application/src/index.ts b/packages/application/src/index.ts index c2daeaa..f2d83fb 100644 --- a/packages/application/src/index.ts +++ b/packages/application/src/index.ts @@ -24,6 +24,7 @@ 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 { setSideUseCase } from "./set-side-use-case.js"; export { setTempHpUseCase } from "./set-temp-hp-use-case.js"; export { toggleConcentrationUseCase } from "./toggle-concentration-use-case.js"; export { toggleConditionUseCase } from "./toggle-condition-use-case.js"; diff --git a/packages/application/src/set-side-use-case.ts b/packages/application/src/set-side-use-case.ts new file mode 100644 index 0000000..0ebadce --- /dev/null +++ b/packages/application/src/set-side-use-case.ts @@ -0,0 +1,18 @@ +import { + type CombatantId, + type DomainError, + type DomainEvent, + setSide, +} from "@initiative/domain"; +import type { EncounterStore } from "./ports.js"; +import { runEncounterAction } from "./run-encounter-action.js"; + +export function setSideUseCase( + store: EncounterStore, + combatantId: CombatantId, + value: "party" | "enemy", +): DomainEvent[] | DomainError { + return runEncounterAction(store, (encounter) => + setSide(encounter, combatantId, value), + ); +} diff --git a/packages/domain/src/__tests__/encounter-difficulty.test.ts b/packages/domain/src/__tests__/encounter-difficulty.test.ts index 35a3285..7c253a5 100644 --- a/packages/domain/src/__tests__/encounter-difficulty.test.ts +++ b/packages/domain/src/__tests__/encounter-difficulty.test.ts @@ -36,11 +36,27 @@ describe("crToXp", () => { }); }); +/** Helper to build party-side descriptors with level. */ +function party(level: number) { + return { level, side: "party" as const }; +} + +/** Helper to build enemy-side descriptors with CR. */ +function enemy(cr: string) { + return { cr, side: "enemy" as const }; +} + describe("calculateEncounterDifficulty", () => { it("returns trivial when monster XP is below Low threshold", () => { // 4x level 1: Low = 200, Moderate = 300, High = 400 - // 1x CR 0 = 0 XP → trivial - const result = calculateEncounterDifficulty([1, 1, 1, 1], ["0"]); + // 1x CR 0 = 0 XP -> trivial + const result = calculateEncounterDifficulty([ + party(1), + party(1), + party(1), + party(1), + enemy("0"), + ]); expect(result.tier).toBe("trivial"); expect(result.totalMonsterXp).toBe(0); expect(result.partyBudget).toEqual({ @@ -51,20 +67,29 @@ describe("calculateEncounterDifficulty", () => { }); it("returns low for 4x level 1 vs Bugbear (CR 1)", () => { - // DMG example: 4x level 1 PCs vs 1 Bugbear (CR 1, 200 XP) - // Low = 200, Moderate = 300 → 200 >= 200 but < 300 → Low - const result = calculateEncounterDifficulty([1, 1, 1, 1], ["1"]); + const result = calculateEncounterDifficulty([ + party(1), + party(1), + party(1), + party(1), + enemy("1"), + ]); expect(result.tier).toBe("low"); expect(result.totalMonsterXp).toBe(200); }); - it("returns moderate for 5x level 3 vs 1125 XP", () => { + it("returns moderate for 5x level 3 vs 1150 XP", () => { // 5x level 3: Low = 750, Moderate = 1125, High = 2000 - // 1125 XP >= 1125 Moderate but < 2000 High → Moderate - // Using CR 3 (700) + CR 2 (450) = 1150 XP ≈ 1125 threshold - // Let's use exact: 5 * 225 = 1125 moderate budget - // Need monsters that sum exactly to 1125: CR 3 (700) + CR 2 (450) = 1150 - const result = calculateEncounterDifficulty([3, 3, 3, 3, 3], ["3", "2"]); + // CR 3 (700) + CR 2 (450) = 1150 XP >= 1125 Moderate + const result = calculateEncounterDifficulty([ + party(3), + party(3), + party(3), + party(3), + party(3), + enemy("3"), + enemy("2"), + ]); expect(result.tier).toBe("moderate"); expect(result.totalMonsterXp).toBe(1150); expect(result.partyBudget.moderate).toBe(1125); @@ -72,26 +97,41 @@ describe("calculateEncounterDifficulty", () => { it("returns high when XP meets High threshold", () => { // 4x level 1: High = 400 - // 2x CR 1 = 400 XP → High - const result = calculateEncounterDifficulty([1, 1, 1, 1], ["1", "1"]); + // 2x CR 1 = 400 XP -> High + const result = calculateEncounterDifficulty([ + party(1), + party(1), + party(1), + party(1), + enemy("1"), + enemy("1"), + ]); expect(result.tier).toBe("high"); expect(result.totalMonsterXp).toBe(400); }); it("caps at high when XP far exceeds threshold", () => { - // 4x level 1: High = 400 - // CR 30 = 155000 XP → still High (no tier above) - const result = calculateEncounterDifficulty([1, 1, 1, 1], ["30"]); + const result = calculateEncounterDifficulty([ + party(1), + party(1), + party(1), + party(1), + enemy("30"), + ]); expect(result.tier).toBe("high"); expect(result.totalMonsterXp).toBe(155000); }); it("handles mixed party levels", () => { // 3x level 3 + 1x level 2 - // level 3: low=150, mod=225, high=400 (x3 = 450, 675, 1200) - // level 2: low=100, mod=150, high=200 (x1 = 100, 150, 200) // Total: low=550, mod=825, high=1400 - const result = calculateEncounterDifficulty([3, 3, 3, 2], ["3"]); + const result = calculateEncounterDifficulty([ + party(3), + party(3), + party(3), + party(2), + enemy("3"), + ]); expect(result.partyBudget).toEqual({ low: 550, moderate: 825, @@ -101,33 +141,110 @@ describe("calculateEncounterDifficulty", () => { expect(result.tier).toBe("low"); }); - it("returns trivial with empty monster array", () => { - const result = calculateEncounterDifficulty([5, 5], []); + it("returns trivial with no enemies", () => { + const result = calculateEncounterDifficulty([party(5), party(5)]); expect(result.tier).toBe("trivial"); expect(result.totalMonsterXp).toBe(0); }); - it("returns high with empty party array (zero budget thresholds)", () => { - // Domain function treats empty party as zero budgets — any XP exceeds all thresholds. - // The useDifficulty hook guards this path by returning null when no leveled PCs exist. - const result = calculateEncounterDifficulty([], ["1"]); + it("returns high with no party levels (zero budget thresholds)", () => { + const result = calculateEncounterDifficulty([enemy("1")]); expect(result.tier).toBe("high"); expect(result.totalMonsterXp).toBe(200); expect(result.partyBudget).toEqual({ low: 0, moderate: 0, high: 0 }); }); it("handles fractional CRs", () => { - const result = calculateEncounterDifficulty( - [1, 1, 1, 1], - ["1/8", "1/4", "1/2"], - ); + const result = calculateEncounterDifficulty([ + party(1), + party(1), + party(1), + party(1), + enemy("1/8"), + enemy("1/4"), + enemy("1/2"), + ]); expect(result.totalMonsterXp).toBe(175); // 25 + 50 + 100 expect(result.tier).toBe("trivial"); // 175 < 200 Low }); it("ignores unknown CRs (0 XP)", () => { - const result = calculateEncounterDifficulty([1, 1, 1, 1], ["unknown"]); + const result = calculateEncounterDifficulty([ + party(1), + party(1), + party(1), + party(1), + enemy("unknown"), + ]); expect(result.totalMonsterXp).toBe(0); expect(result.tier).toBe("trivial"); }); + + it("subtracts XP for party-side combatant with CR", () => { + // 4x level 1 party, 1 enemy CR 2 (450 XP), 1 party CR 1 (200 XP) + // Net = 450 - 200 = 250 + const result = calculateEncounterDifficulty([ + party(1), + party(1), + party(1), + party(1), + enemy("2"), + { cr: "1", side: "party" }, + ]); + expect(result.totalMonsterXp).toBe(250); + expect(result.tier).toBe("low"); // 250 >= 200 Low, < 300 Moderate + }); + + it("floors net monster XP at 0", () => { + // Party ally has more XP than enemy + const result = calculateEncounterDifficulty([ + party(1), + { cr: "5", side: "party" }, // 1800 XP subtracted + enemy("1"), // 200 XP added + ]); + expect(result.totalMonsterXp).toBe(0); + expect(result.tier).toBe("trivial"); + }); + + it("dual contribution: combatant with both level and CR on party side", () => { + // Party combatant with level 1 AND CR 1 on party side + // Level contributes to budget, CR subtracts from monster XP + const result = calculateEncounterDifficulty([ + { level: 1, cr: "1", side: "party" }, // budget += lv1, monsterXp -= 200 + enemy("2"), // monsterXp += 450 + ]); + expect(result.partyBudget).toEqual({ low: 50, moderate: 75, high: 100 }); + expect(result.totalMonsterXp).toBe(250); // 450 - 200 + }); + + it("enemy-side combatant with level does NOT contribute to budget", () => { + const result = calculateEncounterDifficulty([ + party(1), + { level: 5, side: "enemy" }, // should not add to budget + enemy("1"), + ]); + // Only level 1 party contributes to budget + expect(result.partyBudget).toEqual({ low: 50, moderate: 75, high: 100 }); + expect(result.totalMonsterXp).toBe(200); + }); + + it("mixed sides calculate correctly", () => { + // 2 party PCs (level 3), 1 party ally (CR 1, 200 XP), 2 enemies (CR 2, 450 each) + // Budget: 2x level 3 = low 300, mod 450, high 800 + // Monster XP: 900 - 200 = 700 + const result = calculateEncounterDifficulty([ + party(3), + party(3), + { cr: "1", side: "party" }, + enemy("2"), + enemy("2"), + ]); + expect(result.partyBudget).toEqual({ + low: 300, + moderate: 450, + high: 800, + }); + expect(result.totalMonsterXp).toBe(700); + expect(result.tier).toBe("moderate"); // 700 >= 450 Moderate, < 800 High + }); }); diff --git a/packages/domain/src/__tests__/rehydrate-combatant.test.ts b/packages/domain/src/__tests__/rehydrate-combatant.test.ts index b2bc4ff..331a904 100644 --- a/packages/domain/src/__tests__/rehydrate-combatant.test.ts +++ b/packages/domain/src/__tests__/rehydrate-combatant.test.ts @@ -241,6 +241,28 @@ describe("rehydrateCombatant", () => { expect(result?.cr).toBeUndefined(); }); + it("preserves valid side field", () => { + for (const side of ["party", "enemy"]) { + const result = rehydrateCombatant({ ...minimalCombatant(), side }); + expect(result).not.toBeNull(); + expect(result?.side).toBe(side); + } + }); + + it("drops invalid side field", () => { + for (const side of ["ally", "", 42, null, true]) { + const result = rehydrateCombatant({ ...minimalCombatant(), side }); + expect(result).not.toBeNull(); + expect(result?.side).toBeUndefined(); + } + }); + + it("combatant without side rehydrates as before", () => { + const result = rehydrateCombatant(minimalCombatant()); + expect(result).not.toBeNull(); + expect(result?.side).toBeUndefined(); + }); + it("drops invalid tempHp — keeps combatant", () => { for (const tempHp of [-1, 1.5, "3"]) { const result = rehydrateCombatant({ diff --git a/packages/domain/src/__tests__/set-side.test.ts b/packages/domain/src/__tests__/set-side.test.ts new file mode 100644 index 0000000..455fb5a --- /dev/null +++ b/packages/domain/src/__tests__/set-side.test.ts @@ -0,0 +1,115 @@ +import { describe, expect, it } from "vitest"; +import { setSide } from "../set-side.js"; +import type { Combatant, Encounter } from "../types.js"; +import { combatantId, isDomainError } from "../types.js"; +import { expectDomainError } from "./test-helpers.js"; + +function makeCombatant(name: string, side?: "party" | "enemy"): Combatant { + return side === undefined + ? { id: combatantId(name), name } + : { id: combatantId(name), name, side }; +} + +function enc( + combatants: Combatant[], + activeIndex = 0, + roundNumber = 1, +): Encounter { + return { combatants, activeIndex, roundNumber }; +} + +function successResult( + encounter: Encounter, + id: string, + value: "party" | "enemy", +) { + const result = setSide(encounter, combatantId(id), value); + if (isDomainError(result)) { + throw new Error(`Expected success, got error: ${result.message}`); + } + return result; +} + +describe("setSide", () => { + it("sets side to party", () => { + const e = enc([makeCombatant("A"), makeCombatant("B")]); + const { encounter, events } = successResult(e, "A", "party"); + + expect(encounter.combatants[0].side).toBe("party"); + expect(events).toEqual([ + { + type: "SideSet", + combatantId: combatantId("A"), + previousSide: undefined, + newSide: "party", + }, + ]); + }); + + it("sets side to enemy", () => { + const e = enc([makeCombatant("A")]); + const { encounter } = successResult(e, "A", "enemy"); + + expect(encounter.combatants[0].side).toBe("enemy"); + }); + + it("records previous side in event", () => { + const e = enc([makeCombatant("A", "party")]); + const { events } = successResult(e, "A", "enemy"); + + expect(events[0]).toMatchObject({ + previousSide: "party", + newSide: "enemy", + }); + }); + + it("returns error for nonexistent combatant", () => { + const e = enc([makeCombatant("A")]); + const result = setSide(e, combatantId("nonexistent"), "party"); + + expectDomainError(result, "combatant-not-found"); + }); + + it("preserves other fields when setting side", () => { + const combatant: Combatant = { + id: combatantId("A"), + name: "Aria", + initiative: 15, + maxHp: 20, + currentHp: 18, + ac: 14, + cr: "2", + }; + const e = enc([combatant]); + const { encounter } = successResult(e, "A", "party"); + + const updated = encounter.combatants[0]; + expect(updated.side).toBe("party"); + expect(updated.name).toBe("Aria"); + expect(updated.initiative).toBe(15); + expect(updated.cr).toBe("2"); + }); + + it("does not reorder combatants", () => { + const e = enc([makeCombatant("A"), makeCombatant("B")]); + const { encounter } = successResult(e, "B", "party"); + + 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", "party"); + + 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)); + setSide(e, combatantId("A"), "party"); + expect(e).toEqual(original); + }); +}); diff --git a/packages/domain/src/encounter-difficulty.ts b/packages/domain/src/encounter-difficulty.ts index 012c76e..ac25b4e 100644 --- a/packages/domain/src/encounter-difficulty.ts +++ b/packages/domain/src/encounter-difficulty.ts @@ -82,43 +82,61 @@ export function crToXp(cr: string): number { return CR_TO_XP[cr] ?? 0; } +export interface CombatantDescriptor { + readonly level?: number; + readonly cr?: string; + readonly side: "party" | "enemy"; +} + +function determineTier( + xp: number, + low: number, + moderate: number, + high: number, +): DifficultyTier { + if (xp >= high) return "high"; + if (xp >= moderate) return "moderate"; + if (xp >= low) return "low"; + return "trivial"; +} + /** - * Calculates encounter difficulty from party levels and monster CRs. - * Both arrays should be pre-filtered (only PCs with levels, only bestiary-linked monsters). + * Calculates encounter difficulty from combatant descriptors. + * Party-side combatants with level contribute to the budget. + * Enemy-side combatants with CR add XP; party-side with CR subtract XP (floored at 0). */ export function calculateEncounterDifficulty( - partyLevels: readonly number[], - monsterCrs: readonly string[], + combatants: readonly CombatantDescriptor[], ): DifficultyResult { let budgetLow = 0; let budgetModerate = 0; let budgetHigh = 0; + let totalMonsterXp = 0; - for (const level of partyLevels) { - const budget = XP_BUDGET_PER_CHARACTER[level]; - if (budget) { - budgetLow += budget.low; - budgetModerate += budget.moderate; - budgetHigh += budget.high; + for (const c of combatants) { + if (c.level !== undefined && c.side === "party") { + const budget = XP_BUDGET_PER_CHARACTER[c.level]; + if (budget) { + budgetLow += budget.low; + budgetModerate += budget.moderate; + budgetHigh += budget.high; + } + } + + if (c.cr !== undefined) { + const xp = crToXp(c.cr); + if (c.side === "enemy") { + totalMonsterXp += xp; + } else { + totalMonsterXp -= xp; + } } } - let totalMonsterXp = 0; - for (const cr of monsterCrs) { - totalMonsterXp += crToXp(cr); - } - - let tier: DifficultyTier = "trivial"; - if (totalMonsterXp >= budgetHigh) { - tier = "high"; - } else if (totalMonsterXp >= budgetModerate) { - tier = "moderate"; - } else if (totalMonsterXp >= budgetLow) { - tier = "low"; - } + totalMonsterXp = Math.max(0, totalMonsterXp); return { - tier, + tier: determineTier(totalMonsterXp, budgetLow, budgetModerate, budgetHigh), totalMonsterXp, partyBudget: { low: budgetLow, diff --git a/packages/domain/src/events.ts b/packages/domain/src/events.ts index 7e44562..1ec59e9 100644 --- a/packages/domain/src/events.ts +++ b/packages/domain/src/events.ts @@ -101,6 +101,13 @@ export interface CrSet { readonly newCr: string | undefined; } +export interface SideSet { + readonly type: "SideSet"; + readonly combatantId: CombatantId; + readonly previousSide: "party" | "enemy" | undefined; + readonly newSide: "party" | "enemy"; +} + export interface ConditionAdded { readonly type: "ConditionAdded"; readonly combatantId: CombatantId; @@ -161,6 +168,7 @@ export type DomainEvent = | RoundRetreated | AcSet | CrSet + | SideSet | ConditionAdded | ConditionRemoved | ConcentrationStarted diff --git a/packages/domain/src/index.ts b/packages/domain/src/index.ts index 702c16b..db2e67b 100644 --- a/packages/domain/src/index.ts +++ b/packages/domain/src/index.ts @@ -49,6 +49,7 @@ export { editPlayerCharacter, } from "./edit-player-character.js"; export { + type CombatantDescriptor, calculateEncounterDifficulty, crToXp, type DifficultyResult, @@ -75,6 +76,7 @@ export type { PlayerCharacterUpdated, RoundAdvanced, RoundRetreated, + SideSet, TempHpSet, TurnAdvanced, TurnRetreated, @@ -115,6 +117,7 @@ export { type SetInitiativeSuccess, setInitiative, } from "./set-initiative.js"; +export { type SetSideSuccess, setSide } from "./set-side.js"; export { type SetTempHpSuccess, setTempHp } from "./set-temp-hp.js"; export { type ToggleConcentrationSuccess, diff --git a/packages/domain/src/rehydrate-combatant.ts b/packages/domain/src/rehydrate-combatant.ts index f7bc534..0b044bb 100644 --- a/packages/domain/src/rehydrate-combatant.ts +++ b/packages/domain/src/rehydrate-combatant.ts @@ -76,6 +76,14 @@ function validateCr(value: unknown): string | undefined { : undefined; } +const VALID_SIDES = new Set(["party", "enemy"]); + +function validateSide(value: unknown): "party" | "enemy" | undefined { + return typeof value === "string" && VALID_SIDES.has(value) + ? (value as "party" | "enemy") + : undefined; +} + function parseOptionalFields(entry: Record) { return { initiative: validateInteger(entry.initiative), @@ -86,6 +94,7 @@ function parseOptionalFields(entry: Record) { ? creatureId(entry.creatureId as string) : undefined, cr: validateCr(entry.cr), + side: validateSide(entry.side), color: validateSetMember(entry.color, VALID_PLAYER_COLORS), icon: validateSetMember(entry.icon, VALID_PLAYER_ICONS), playerCharacterId: validateNonEmptyString(entry.playerCharacterId) diff --git a/packages/domain/src/set-side.ts b/packages/domain/src/set-side.ts new file mode 100644 index 0000000..8690315 --- /dev/null +++ b/packages/domain/src/set-side.ts @@ -0,0 +1,54 @@ +import type { DomainEvent } from "./events.js"; +import { + type CombatantId, + type DomainError, + type Encounter, + findCombatant, + isDomainError, +} from "./types.js"; + +export interface SetSideSuccess { + readonly encounter: Encounter; + readonly events: DomainEvent[]; +} + +const VALID_SIDES = new Set(["party", "enemy"]); + +export function setSide( + encounter: Encounter, + combatantId: CombatantId, + value: "party" | "enemy", +): SetSideSuccess | DomainError { + const found = findCombatant(encounter, combatantId); + if (isDomainError(found)) return found; + + if (!VALID_SIDES.has(value)) { + return { + kind: "domain-error", + code: "invalid-side", + message: `Side must be "party" or "enemy", got "${value}"`, + }; + } + + const previousSide = found.combatant.side; + + const updatedCombatants = encounter.combatants.map((c) => + c.id === combatantId ? { ...c, side: value } : c, + ); + + return { + encounter: { + combatants: updatedCombatants, + activeIndex: encounter.activeIndex, + roundNumber: encounter.roundNumber, + }, + events: [ + { + type: "SideSet", + combatantId, + previousSide, + newSide: value, + }, + ], + }; +} diff --git a/packages/domain/src/types.ts b/packages/domain/src/types.ts index 0ba9a16..960036d 100644 --- a/packages/domain/src/types.ts +++ b/packages/domain/src/types.ts @@ -21,6 +21,7 @@ export interface Combatant { readonly isConcentrating?: boolean; readonly creatureId?: CreatureId; readonly cr?: string; + readonly side?: "party" | "enemy"; readonly color?: string; readonly icon?: string; readonly playerCharacterId?: PlayerCharacterId; diff --git a/specs/008-encounter-difficulty/spec.md b/specs/008-encounter-difficulty/spec.md index 7307ea8..0574e72 100644 --- a/specs/008-encounter-difficulty/spec.md +++ b/specs/008-encounter-difficulty/spec.md @@ -3,7 +3,7 @@ **Feature Branch**: `008-encounter-difficulty` **Created**: 2026-03-27 **Status**: Draft -**Input**: Gitea issue #18 — "Encounter difficulty indicator (5.5e XP budget)" +**Input**: Gitea issue #18 — "Encounter difficulty indicator (5.5e XP budget)", Gitea issue #22 — "Combatant side assignment for encounter difficulty" ## User Scenarios & Testing *(mandatory)* @@ -101,7 +101,7 @@ 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 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. +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** enemy-side combatants with CR add XP to the monster total, party-side combatants with CR subtract XP from the monster total, and custom combatants without CR are excluded. The net monster XP is floored at 0. 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). @@ -119,7 +119,7 @@ The game master taps the difficulty indicator to open a breakdown panel. The pan **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. +1. **Given** the difficulty indicator is visible, **When** the user taps the indicator, **Then** a breakdown panel opens showing party budget, two columns (Party and Enemy) listing combatants with their XP contributions, a side toggle per combatant, and the net monster XP total. 2. **Given** the breakdown panel is open, **When** the user taps outside the panel or taps a close control, **Then** the panel closes. @@ -131,6 +131,8 @@ The game master taps the difficulty indicator to open a breakdown panel. The pan 6. **Given** the breakdown panel is open, **When** a combatant is added or removed from the encounter, **Then** the panel content updates immediately. +7. **Given** the breakdown panel is open, **When** the user toggles a combatant's side, **Then** it moves to the other column and the difficulty tier, monster XP total, and party budget update immediately. + --- ### Manual CR Assignment @@ -177,6 +179,34 @@ Bestiary-linked combatants derive their CR from the creature data. The breakdown --- +### Side Assignment + +**Story ED-8 — Assign combatants to party or enemy side (Priority: P2)** + +A game master has allied NPCs fighting alongside the party. From the difficulty breakdown panel, they toggle an NPC to the party side. The NPC's XP is subtracted from the monster total instead of added, and the difficulty tier drops accordingly. PC combatants default to the party side and non-PC combatants default to the enemy side, so users who don't care about sides never interact with this feature. + +**Why this priority**: Extends the breakdown panel (ED-5) with side assignment. Without sides, allied NPCs inflate difficulty artificially. + +**Independent Test**: Can be tested by adding a leveled PC and two monsters, toggling one monster to party side, and verifying its XP is subtracted from the total. + +**Acceptance Scenarios**: + +1. **Given** the breakdown panel is open, **When** a non-PC combatant's side is toggled to party, **Then** its CR-derived XP is subtracted from the monster total instead of added, and the difficulty tier recalculates immediately. + +2. **Given** a combatant with both a level (from its player character) and a CR on the party side, **When** the difficulty is calculated, **Then** it contributes to the party budget via its level AND subtracts its CR XP from the monster total — both effects apply independently. + +3. **Given** party-side combatants whose total CR XP exceeds the enemy-side total, **When** the difficulty is calculated, **Then** the net monster XP is floored at 0 (difficulty cannot go negative). + +4. **Given** the breakdown panel is open, **When** the user views a PC combatant, **Then** it appears in the Party column by default. **When** the user views a non-PC combatant, **Then** it appears in the Enemy column by default. Both can be toggled. + +5. **Given** a combatant's side has been toggled, **When** the encounter is saved and the page is reloaded, **Then** the side assignment is restored. + +6. **Given** a combatant's side has been toggled, **When** the encounter is exported to JSON and re-imported, **Then** the side assignment is preserved. + +7. **Given** the breakdown panel is open, **Then** above the two columns a brief rules-oriented explanation is shown: "Allied NPC XP is subtracted from encounter difficulty" (tone is mechanical/rules-focused). + +--- + ### 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." @@ -190,6 +220,9 @@ Bestiary-linked combatants derive their CR from the creature data. The breakdown - **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. +- **Net monster XP floored at 0**: If party-side combatant XP exceeds enemy-side combatant XP, the net monster XP is 0 (trivial), not negative. +- **Dual contribution (level + CR on party side)**: A combatant with both a level and a CR on the party side contributes to the party budget via level and subtracts from monster XP via CR. These are independent effects. +- **Side defaults preserve opt-in**: Because PCs default to party and others default to enemy, users who never assign sides see identical behavior to the pre-side-assignment calculation. --- @@ -206,8 +239,8 @@ The system MUST contain a CR-to-XP lookup table mapping all standard 5e challeng #### FR-003 — Party XP budget calculation 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 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-004 — Net monster XP calculation +The system MUST calculate the net monster XP by summing the XP value (derived from CR) for each enemy-side combatant that has a CR and subtracting the XP value for each party-side 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. The net monster XP MUST be floored at 0. #### 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). @@ -239,24 +272,39 @@ 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-015 — Optional CR and side fields 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") and an optional `side` field accepting `"party"` or `"enemy"`. #### 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. +The breakdown panel MUST display: the party XP budget (with Low, Moderate, High thresholds), two stacked sections (Party and Enemy) using a columnar grid layout (name, toggle button, CR, XP) for aligned readability, the net monster XP total, and a brief rules-oriented explanation (e.g., "Allied NPC XP is subtracted from encounter difficulty"). Source names are omitted from the panel to conserve horizontal space. #### 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. +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. #### 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. +#### FR-021 — Side defaults +When `side` is undefined, PC combatants MUST default to party side and all other combatants MUST default to enemy side. The `useDifficulty` hook resolves defaults before calling the domain function. + +#### FR-022 — Party-side CR subtraction +Party-side combatants with CR MUST have their XP subtracted from the monster total. Party-side combatants with level MUST contribute to the party budget. These effects are independent — a combatant with both level and CR on party side contributes to budget AND subtracts from monster XP. + +#### FR-023 — Side toggle in breakdown panel +The breakdown panel MUST provide a side toggle button per non-PC combatant to switch between party and enemy side. PC combatants are fixed to the party side and do not show a toggle. Toggling MUST immediately update the difficulty calculation. The toggle button uses an arrow icon with a hover background effect for discoverability. + +#### FR-024 — Side persistence +The `side` field on `Combatant` MUST persist within the encounter across page reloads (via encounter storage) and MUST round-trip through JSON export/import. + +#### FR-025 — Domain function signature +The `calculateEncounterDifficulty` domain function MUST accept combatant descriptors with `{ level?, cr?, side }` so it can partition combatants internally, replacing the current `partyLevels[]` / `monsterCrs[]` signature. + ### 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. @@ -265,6 +313,7 @@ The `cr` field on `Combatant` MUST persist within the encounter across page relo - **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`. +- **Combatant.side**: An optional string field (`"party"` | `"enemy"`) on the existing `Combatant` entity. When undefined, defaults are resolved by the hook layer: PC combatants default to `"party"`, all others to `"enemy"`. --- @@ -281,6 +330,7 @@ The `cr` field on `Combatant` MUST persist within the encounter across page relo - **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. +- **SC-010**: Party-side combatants with CR correctly subtract their XP from the monster total, and the net XP is never negative. --- @@ -293,6 +343,5 @@ The `cr` field on `Combatant` MUST persist within the encounter across page relo - 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. - 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 per-combatant level overrides — level is always derived from the player character template.