T012–T016: Phase 3 application + web shell (use case, ports, React hook, UI, README)

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

README.md

@@ -0,0 +1,28 @@
+# Initiative Tracker
+
+A turn-based initiative tracker for tabletop RPG encounters. Click "Next Turn" to cycle through combatants and advance rounds.
+
+## Prerequisites
+
+- Node.js 22
+- pnpm 10.6+
+
+## Getting Started
+
+```sh
+pnpm install
+pnpm --filter web dev
+```
+
+Open the URL printed in your terminal (typically `http://localhost:5173`).
+
+The app starts with a 3-combatant demo encounter (Aria, Brak, Cael). Click **Next Turn** to advance through the initiative order. When the last combatant finishes their turn, the round number increments and the cycle restarts.
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `pnpm --filter web dev` | Start the dev server |
+| `pnpm --filter web build` | Production build |
+| `pnpm test` | Run all tests |
+| `pnpm check` | Full merge gate (format, lint, typecheck, test) |

apps/web/src/App.tsx

@@ -1,3 +1,43 @@
+import { useEncounter } from "./hooks/use-encounter";
+
 export function App() {
-	return <div>Initiative Tracker</div>;
+	const { encounter, events, advanceTurn } = useEncounter();
+	const activeCombatant = encounter.combatants[encounter.activeIndex];
+
+	return (
+		<div>
+			<h1>Initiative Tracker</h1>
+
+			<p>
+				Round {encounter.roundNumber} — Current: {activeCombatant.name}
+			</p>
+
+			<ul>
+				{encounter.combatants.map((c, i) => (
+					<li key={c.id}>
+						{i === encounter.activeIndex ? `▶ ${c.name}` : c.name}
+					</li>
+				))}
+			</ul>
+
+			<button type="button" onClick={advanceTurn}>
+				Next Turn
+			</button>
+
+			{events.length > 0 && (
+				<div>
+					<h2>Events</h2>
+					<ul>
+						{events.map((e, i) => (
+							<li key={`${e.type}-${i}`}>
+								{e.type === "TurnAdvanced"
+									? `Turn: ${e.previousCombatantId} → ${e.newCombatantId} (round ${e.roundNumber})`
+									: `Round advanced to ${e.newRoundNumber}`}
+							</li>
+						))}
+					</ul>
+				</div>
+			)}
+		</div>
+	);
 }

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

@@ -0,0 +1,47 @@
+import type { EncounterStore } from "@initiative/application";
+import { advanceTurnUseCase } from "@initiative/application";
+import type { DomainEvent, Encounter } from "@initiative/domain";
+import {
+	combatantId,
+	createEncounter,
+	isDomainError,
+} from "@initiative/domain";
+import { useCallback, useRef, useState } from "react";
+
+function createDemoEncounter(): Encounter {
+	const result = createEncounter([
+		{ id: combatantId("1"), name: "Aria" },
+		{ id: combatantId("2"), name: "Brak" },
+		{ id: combatantId("3"), name: "Cael" },
+	]);
+
+	if (isDomainError(result)) {
+		throw new Error(`Failed to create demo encounter: ${result.message}`);
+	}
+
+	return result;
+}
+
+export function useEncounter() {
+	const [encounter, setEncounter] = useState<Encounter>(createDemoEncounter);
+	const [events, setEvents] = useState<DomainEvent[]>([]);
+	const encounterRef = useRef(encounter);
+	encounterRef.current = encounter;
+
+	const advanceTurn = useCallback(() => {
+		const store: EncounterStore = {
+			get: () => encounterRef.current,
+			save: (e) => setEncounter(e),
+		};
+
+		const result = advanceTurnUseCase(store);
+
+		if (isDomainError(result)) {
+			return;
+		}
+
+		setEvents((prev) => [...prev, ...result]);
+	}, []);
+
+	return { encounter, events, advanceTurn } as const;
+}

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

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

packages/application/src/index.ts

@@ -1 +1,2 @@
-export {};
+export { advanceTurnUseCase } from "./advance-turn-use-case.js";
+export type { EncounterStore } from "./ports.js";

packages/application/src/ports.ts

@@ -0,0 +1,6 @@
+import type { Encounter } from "@initiative/domain";
+
+export interface EncounterStore {
+	get(): Encounter;
+	save(encounter: Encounter): void;
+}

specs/001-advance-turn/tasks.md

@@ -48,11 +48,11 @@
 
 **Goal**: Wire up the application use case and minimal React UI with a "Next Turn" button.
 
-- [ ] T012 Define port interface in `packages/application/src/ports.ts` — `EncounterStore` port: `get(): Encounter`, `save(e: Encounter)`
+- [X] T012 Define port interface in `packages/application/src/ports.ts` — `EncounterStore` port: `get(): Encounter`, `save(e: Encounter)`
-- [ ] T013 Implement `AdvanceTurnUseCase` in `packages/application/src/advance-turn-use-case.ts` — accepts `EncounterStore`, calls `advanceTurn`, saves result, returns events
+- [X] T013 Implement `AdvanceTurnUseCase` in `packages/application/src/advance-turn-use-case.ts` — accepts `EncounterStore`, calls `advanceTurn`, saves result, returns events
-- [ ] T014 Export public API from `packages/application/src/index.ts` — re-export use case and port types
+- [X] T014 Export public API from `packages/application/src/index.ts` — re-export use case and port types
-- [ ] T015 Implement `useEncounter` hook in `apps/web/src/hooks/use-encounter.ts` — in-memory `EncounterStore` via React state, exposes encounter state + `advanceTurn` action, hardcoded 3-combatant demo
+- [X] T015 Implement `useEncounter` hook in `apps/web/src/hooks/use-encounter.ts` — in-memory `EncounterStore` via React state, exposes encounter state + `advanceTurn` action, hardcoded 3-combatant demo
-- [ ] T016 Wire up `apps/web/src/App.tsx` — display current combatant, round number, combatant list with active indicator, "Next Turn" button, emitted events
+- [X] T016 Wire up `apps/web/src/App.tsx` — display current combatant, round number, combatant list with active indicator, "Next Turn" button, emitted events
 
 **Checkpoint (Milestone 2)**: `pnpm check` passes. `vite build` succeeds. Clicking "Next Turn" cycles combatants and increments rounds correctly.