Implement the 023-clear-encounter feature that adds a clear encounter button with confirmation dialog to remove all combatants and reset round/turn counters, with the cleared state persisting across page refreshes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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

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

packages/application/src/index.ts

@@ -1,6 +1,7 @@
 export { addCombatantUseCase } from "./add-combatant-use-case.js";
 export { adjustHpUseCase } from "./adjust-hp-use-case.js";
 export { advanceTurnUseCase } from "./advance-turn-use-case.js";
+export { clearEncounterUseCase } from "./clear-encounter-use-case.js";
 export { editCombatantUseCase } from "./edit-combatant-use-case.js";
 export type { EncounterStore } from "./ports.js";
 export { removeCombatantUseCase } from "./remove-combatant-use-case.js";

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

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "vitest";
+import { clearEncounter } from "../clear-encounter.js";
+import type { DomainError, Encounter } from "../types.js";
+import { combatantId, createEncounter, isDomainError } from "../types.js";
+
+function makeEncounter(
+	count: number,
+	overrides?: Partial<Encounter>,
+): Encounter {
+	const combatants = Array.from({ length: count }, (_, i) => ({
+		id: combatantId(`c-${i + 1}`),
+		name: `Combatant ${i + 1}`,
+	}));
+
+	const result = createEncounter(combatants);
+	if (isDomainError(result)) {
+		throw new Error("Failed to create encounter in test helper");
+	}
+
+	return { ...result, ...overrides };
+}
+
+describe("clearEncounter", () => {
+	it("clears encounter with multiple combatants at round 3 — returns empty encounter with roundNumber 1 and activeIndex 0", () => {
+		const encounter = makeEncounter(4, { roundNumber: 3, activeIndex: 2 });
+
+		const result = clearEncounter(encounter);
+
+		expect(isDomainError(result)).toBe(false);
+		const success = result as Exclude<typeof result, DomainError>;
+		expect(success.encounter.combatants).toEqual([]);
+		expect(success.encounter.roundNumber).toBe(1);
+		expect(success.encounter.activeIndex).toBe(0);
+	});
+
+	it("clears encounter with a single combatant", () => {
+		const encounter = makeEncounter(1);
+
+		const result = clearEncounter(encounter);
+
+		expect(isDomainError(result)).toBe(false);
+		const success = result as Exclude<typeof result, DomainError>;
+		expect(success.encounter.combatants).toEqual([]);
+		expect(success.encounter.activeIndex).toBe(0);
+		expect(success.encounter.roundNumber).toBe(1);
+	});
+
+	it("clears encounter with combatants that have HP/AC/conditions/concentration", () => {
+		const encounter: Encounter = {
+			combatants: [
+				{
+					id: combatantId("c-1"),
+					name: "Fighter",
+					maxHp: 50,
+					currentHp: 30,
+					ac: 18,
+					conditions: ["blinded", "poisoned"],
+					isConcentrating: true,
+				},
+				{
+					id: combatantId("c-2"),
+					name: "Wizard",
+					maxHp: 25,
+					currentHp: 0,
+					ac: 12,
+					conditions: ["unconscious"],
+				},
+			],
+			activeIndex: 0,
+			roundNumber: 5,
+		};
+
+		const result = clearEncounter(encounter);
+
+		expect(isDomainError(result)).toBe(false);
+		const success = result as Exclude<typeof result, DomainError>;
+		expect(success.encounter.combatants).toEqual([]);
+	});
+
+	it("returns DomainError with code 'encounter-already-empty' when encounter has no combatants", () => {
+		const encounter: Encounter = {
+			combatants: [],
+			activeIndex: 0,
+			roundNumber: 1,
+		};
+
+		const result = clearEncounter(encounter);
+
+		expect(isDomainError(result)).toBe(true);
+		const error = result as DomainError;
+		expect(error.code).toBe("encounter-already-empty");
+	});
+
+	it("emits EncounterCleared event with correct combatantCount", () => {
+		const encounter = makeEncounter(3);
+
+		const result = clearEncounter(encounter);
+
+		expect(isDomainError(result)).toBe(false);
+		const success = result as Exclude<typeof result, DomainError>;
+		expect(success.events).toEqual([
+			{ type: "EncounterCleared", combatantCount: 3 },
+		]);
+	});
+
+	it("is deterministic — same input always produces same output", () => {
+		const encounter = makeEncounter(2, { roundNumber: 4, activeIndex: 1 });
+
+		const result1 = clearEncounter(encounter);
+		const result2 = clearEncounter(encounter);
+
+		expect(result1).toEqual(result2);
+	});
+});

packages/domain/src/clear-encounter.ts

@@ -0,0 +1,33 @@
+import type { DomainEvent } from "./events.js";
+import type { DomainError, Encounter } from "./types.js";
+
+export interface ClearEncounterSuccess {
+	readonly encounter: Encounter;
+	readonly events: DomainEvent[];
+}
+
+export function clearEncounter(
+	encounter: Encounter,
+): ClearEncounterSuccess | DomainError {
+	if (encounter.combatants.length === 0) {
+		return {
+			kind: "domain-error",
+			code: "encounter-already-empty",
+			message: "Cannot clear an encounter that has no combatants",
+		};
+	}
+
+	return {
+		encounter: {
+			combatants: [],
+			activeIndex: 0,
+			roundNumber: 1,
+		},
+		events: [
+			{
+				type: "EncounterCleared",
+				combatantCount: encounter.combatants.length,
+			},
+		],
+	};
+}

packages/domain/src/events.ts

@@ -98,6 +98,11 @@ export interface ConcentrationEnded {
 	readonly combatantId: CombatantId;
 }
 
+export interface EncounterCleared {
+	readonly type: "EncounterCleared";
+	readonly combatantCount: number;
+}
+
 export type DomainEvent =
 	| TurnAdvanced
 	| RoundAdvanced
@@ -113,4 +118,5 @@ export type DomainEvent =
 	| ConditionAdded
 	| ConditionRemoved
 	| ConcentrationStarted
-	| ConcentrationEnded;
+	| ConcentrationEnded
+	| EncounterCleared;

packages/domain/src/index.ts

@@ -2,6 +2,10 @@ export { type AddCombatantSuccess, addCombatant } from "./add-combatant.js";
 export { type AdjustHpSuccess, adjustHp } from "./adjust-hp.js";
 export { advanceTurn } from "./advance-turn.js";
 export { resolveCreatureName } from "./auto-number.js";
+export {
+	type ClearEncounterSuccess,
+	clearEncounter,
+} from "./clear-encounter.js";
 export {
 	CONDITION_DEFINITIONS,
 	type ConditionDefinition,
@@ -34,6 +38,7 @@ export type {
 	ConditionRemoved,
 	CurrentHpAdjusted,
 	DomainEvent,
+	EncounterCleared,
 	InitiativeSet,
 	MaxHpSet,
 	RoundAdvanced,