Add player character management feature

Persistent player character templates (name, AC, HP, color, icon) with
full CRUD, bestiary-style search to add PCs to encounters with pre-filled
stats, and color/icon visual distinction in combatant rows. Also stops
the stat block panel from auto-opening when adding a creature.

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

apps/web/src/App.tsx

@@ -7,6 +7,8 @@ import { Plus } from "lucide-react";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { ActionBar } from "./components/action-bar";
 import { CombatantRow } from "./components/combatant-row";
+import { CreatePlayerModal } from "./components/create-player-modal";
+import { PlayerManagement } from "./components/player-management";
 import { SourceManager } from "./components/source-manager";
 import { StatBlockPanel } from "./components/stat-block-panel";
 import { Toast } from "./components/toast";
@@ -14,6 +16,7 @@ import { TurnNavigation } from "./components/turn-navigation";
 import { type SearchResult, useBestiary } from "./hooks/use-bestiary";
 import { useBulkImport } from "./hooks/use-bulk-import";
 import { useEncounter } from "./hooks/use-encounter";
+import { usePlayerCharacters } from "./hooks/use-player-characters";
 
 function rollDice(): number {
 	return Math.floor(Math.random() * 20) + 1;
@@ -35,9 +38,23 @@ export function App() {
 		toggleCondition,
 		toggleConcentration,
 		addFromBestiary,
+		addFromPlayerCharacter,
 		makeStore,
 	} = useEncounter();
 
+	const {
+		characters: playerCharacters,
+		createCharacter: createPlayerCharacter,
+		editCharacter: editPlayerCharacter,
+		deleteCharacter: deletePlayerCharacter,
+	} = usePlayerCharacters();
+
+	const [createPlayerOpen, setCreatePlayerOpen] = useState(false);
+	const [managementOpen, setManagementOpen] = useState(false);
+	const [editingPlayer, setEditingPlayer] = useState<
+		(typeof playerCharacters)[number] | undefined
+	>(undefined);
+
 	const {
 		search,
 		getCreature,
@@ -80,14 +97,6 @@ export function App() {
 	const handleAddFromBestiary = useCallback(
 		(result: SearchResult) => {
 			addFromBestiary(result);
-			// Derive the creature ID so stat block panel can try to show it
-			const slug = result.name
-				.toLowerCase()
-				.replace(/[^a-z0-9]+/g, "-")
-				.replace(/(^-|-$)/g, "");
-			setSelectedCreatureId(
-				`${result.source.toLowerCase()}:${slug}` as CreatureId,
-			);
 		},
 		[addFromBestiary],
 	);
@@ -259,6 +268,9 @@ export function App() {
 						onBulkImport={handleBulkImport}
 						bulkImportDisabled={bulkImport.state.status === "loading"}
 						inputRef={actionBarInputRef}
+						playerCharacters={playerCharacters}
+						onAddFromPlayerCharacter={addFromPlayerCharacter}
+						onManagePlayers={() => setManagementOpen(true)}
 					/>
 				</div>
 			</div>
@@ -331,6 +343,45 @@ export function App() {
 					onDismiss={bulkImport.reset}
 				/>
 			)}
+
+			<CreatePlayerModal
+				open={createPlayerOpen}
+				onClose={() => {
+					setCreatePlayerOpen(false);
+					setEditingPlayer(undefined);
+				}}
+				onSave={(name, ac, maxHp, color, icon) => {
+					if (editingPlayer) {
+						editPlayerCharacter?.(editingPlayer.id, {
+							name,
+							ac,
+							maxHp,
+							color,
+							icon,
+						});
+					} else {
+						createPlayerCharacter(name, ac, maxHp, color, icon);
+					}
+				}}
+				playerCharacter={editingPlayer}
+			/>
+
+			<PlayerManagement
+				open={managementOpen}
+				onClose={() => setManagementOpen(false)}
+				characters={playerCharacters}
+				onEdit={(pc) => {
+					setEditingPlayer(pc);
+					setCreatePlayerOpen(true);
+					setManagementOpen(false);
+				}}
+				onDelete={(id) => deletePlayerCharacter?.(id)}
+				onCreate={() => {
+					setEditingPlayer(undefined);
+					setCreatePlayerOpen(true);
+					setManagementOpen(false);
+				}}
+			/>
 		</div>
 	);
 }

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

@@ -1,4 +1,5 @@
-import { Check, Eye, Import, Minus, Plus } from "lucide-react";
+import type { PlayerCharacter, PlayerIcon } from "@initiative/domain";
+import { Check, Eye, Import, Minus, Plus, Users } from "lucide-react";
 import {
 	type FormEvent,
 	type RefObject,
@@ -7,6 +8,7 @@ import {
 	useState,
 } from "react";
 import type { SearchResult } from "../hooks/use-bestiary.js";
+import { PLAYER_COLOR_HEX, PLAYER_ICON_MAP } from "./player-icon-map";
 import { Button } from "./ui/button.js";
 import { Input } from "./ui/input.js";
 
@@ -27,6 +29,9 @@ interface ActionBarProps {
 	onBulkImport?: () => void;
 	bulkImportDisabled?: boolean;
 	inputRef?: RefObject<HTMLInputElement | null>;
+	playerCharacters?: readonly PlayerCharacter[];
+	onAddFromPlayerCharacter?: (pc: PlayerCharacter) => void;
+	onManagePlayers?: () => void;
 }
 
 function creatureKey(r: SearchResult): string {
@@ -42,9 +47,13 @@ export function ActionBar({
 	onBulkImport,
 	bulkImportDisabled,
 	inputRef,
+	playerCharacters,
+	onAddFromPlayerCharacter,
+	onManagePlayers,
 }: ActionBarProps) {
 	const [nameInput, setNameInput] = useState("");
 	const [suggestions, setSuggestions] = useState<SearchResult[]>([]);
+	const [pcMatches, setPcMatches] = useState<PlayerCharacter[]>([]);
 	const [suggestionIndex, setSuggestionIndex] = useState(-1);
 	const [queued, setQueued] = useState<QueuedCreature | null>(null);
 	const [customInit, setCustomInit] = useState("");
@@ -73,6 +82,7 @@ export function ActionBar({
 		setQueued(null);
 		setNameInput("");
 		setSuggestions([]);
+		setPcMatches([]);
 		setSuggestionIndex(-1);
 	};
 
@@ -99,6 +109,7 @@ export function ActionBar({
 		onAddCombatant(nameInput, Object.keys(opts).length > 0 ? opts : undefined);
 		setNameInput("");
 		setSuggestions([]);
+		setPcMatches([]);
 		clearCustomFields();
 	};
 
@@ -106,13 +117,22 @@ export function ActionBar({
 		setNameInput(value);
 		setSuggestionIndex(-1);
 		let newSuggestions: SearchResult[] = [];
+		let newPcMatches: PlayerCharacter[] = [];
 		if (value.length >= 2) {
 			newSuggestions = bestiarySearch(value);
 			setSuggestions(newSuggestions);
+			if (playerCharacters && playerCharacters.length > 0) {
+				const lower = value.toLowerCase();
+				newPcMatches = playerCharacters.filter((pc) =>
+					pc.name.toLowerCase().includes(lower),
+				);
+			}
+			setPcMatches(newPcMatches);
 		} else {
 			setSuggestions([]);
+			setPcMatches([]);
 		}
-		if (newSuggestions.length > 0) {
+		if (newSuggestions.length > 0 || newPcMatches.length > 0) {
 			clearCustomFields();
 		}
 		if (queued) {
@@ -141,8 +161,10 @@ export function ActionBar({
 		}
 	};
 
+	const hasSuggestions = suggestions.length > 0 || pcMatches.length > 0;
+
 	const handleKeyDown = (e: React.KeyboardEvent) => {
-		if (suggestions.length === 0) return;
+		if (!hasSuggestions) return;
 
 		if (e.key === "ArrowDown") {
 			e.preventDefault();
@@ -157,6 +179,7 @@ export function ActionBar({
 			setQueued(null);
 			setSuggestionIndex(-1);
 			setSuggestions([]);
+			setPcMatches([]);
 		}
 	};
 
@@ -238,7 +261,7 @@ export function ActionBar({
 						placeholder="+ Add combatants"
 						className="max-w-xs"
 					/>
-					{suggestions.length > 0 && (
+					{hasSuggestions && (
 						<div className="absolute bottom-full z-50 mb-1 w-full max-w-xs rounded-md border border-border bg-card shadow-lg">
 							<button
 								type="button"
@@ -246,6 +269,7 @@ export function ActionBar({
 								onMouseDown={(e) => e.preventDefault()}
 								onClick={() => {
 									setSuggestions([]);
+									setPcMatches([]);
 									setQueued(null);
 									setSuggestionIndex(-1);
 								}}
@@ -256,90 +280,133 @@ export function ActionBar({
 									Esc
 								</kbd>
 							</button>
-							<ul className="max-h-48 overflow-y-auto py-1">
-								{suggestions.map((result, i) => {
-									const key = creatureKey(result);
-									const isQueued =
-										queued !== null && creatureKey(queued.result) === key;
-									return (
-										<li key={key}>
-											<button
-												type="button"
-												className={`flex w-full items-center justify-between px-3 py-1.5 text-left text-sm ${
-													isQueued
-														? "bg-accent/30 text-foreground"
-														: i === suggestionIndex
-															? "bg-accent/20 text-foreground"
-															: "text-foreground hover:bg-hover-neutral-bg"
-												}`}
-												onMouseDown={(e) => e.preventDefault()}
-												onClick={() => handleClickSuggestion(result)}
-												onMouseEnter={() => setSuggestionIndex(i)}
-											>
-												<span>{result.name}</span>
-												<span className="flex items-center gap-1 text-xs text-muted-foreground">
-													{isQueued ? (
-														<>
-															<button
-																type="button"
-																className="rounded p-0.5 text-foreground hover:bg-accent/40"
-																onMouseDown={(e) => e.preventDefault()}
-																onClick={(e) => {
-																	e.stopPropagation();
-																	if (queued.count <= 1) {
-																		setQueued(null);
-																	} else {
-																		setQueued({
-																			...queued,
-																			count: queued.count - 1,
-																		});
-																	}
-																}}
-															>
-																<Minus className="h-3 w-3" />
-															</button>
-															<span className="min-w-5 rounded-full bg-accent px-1.5 py-0.5 text-center font-medium text-foreground">
-																{queued.count}
+							<div className="max-h-48 overflow-y-auto py-1">
+								{pcMatches.length > 0 && (
+									<>
+										<div className="px-3 py-1 text-xs font-medium text-muted-foreground">
+											Players
+										</div>
+										<ul>
+											{pcMatches.map((pc) => {
+												const PcIcon = PLAYER_ICON_MAP[pc.icon as PlayerIcon];
+												const pcColor =
+													PLAYER_COLOR_HEX[
+														pc.color as keyof typeof PLAYER_COLOR_HEX
+													];
+												return (
+													<li key={pc.id}>
+														<button
+															type="button"
+															className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-sm text-foreground hover:bg-hover-neutral-bg"
+															onMouseDown={(e) => e.preventDefault()}
+															onClick={() => {
+																onAddFromPlayerCharacter?.(pc);
+																setNameInput("");
+																setSuggestions([]);
+																setPcMatches([]);
+															}}
+														>
+															{PcIcon && (
+																<PcIcon size={14} style={{ color: pcColor }} />
+															)}
+															<span className="flex-1 truncate">{pc.name}</span>
+															<span className="text-xs text-muted-foreground">
+																Player
 															</span>
-															<button
-																type="button"
-																className="rounded p-0.5 text-foreground hover:bg-accent/40"
-																onMouseDown={(e) => e.preventDefault()}
-																onClick={(e) => {
-																	e.stopPropagation();
-																	setQueued({
-																		...queued,
-																		count: queued.count + 1,
-																	});
-																}}
-															>
-																<Plus className="h-3 w-3" />
-															</button>
-															<button
-																type="button"
-																className="ml-0.5 rounded p-0.5 text-foreground hover:bg-accent/40"
-																onMouseDown={(e) => e.preventDefault()}
-																onClick={(e) => {
-																	e.stopPropagation();
-																	confirmQueued();
-																}}
-															>
-																<Check className="h-3.5 w-3.5" />
-															</button>
-														</>
-													) : (
-														result.sourceDisplayName
-													)}
-												</span>
-											</button>
-										</li>
-									);
-								})}
-							</ul>
+														</button>
+													</li>
+												);
+											})}
+										</ul>
+									</>
+								)}
+								{suggestions.length > 0 && (
+									<ul>
+										{suggestions.map((result, i) => {
+											const key = creatureKey(result);
+											const isQueued =
+												queued !== null && creatureKey(queued.result) === key;
+											return (
+												<li key={key}>
+													<button
+														type="button"
+														className={`flex w-full items-center justify-between px-3 py-1.5 text-left text-sm ${
+															isQueued
+																? "bg-accent/30 text-foreground"
+																: i === suggestionIndex
+																	? "bg-accent/20 text-foreground"
+																	: "text-foreground hover:bg-hover-neutral-bg"
+														}`}
+														onMouseDown={(e) => e.preventDefault()}
+														onClick={() => handleClickSuggestion(result)}
+														onMouseEnter={() => setSuggestionIndex(i)}
+													>
+														<span>{result.name}</span>
+														<span className="flex items-center gap-1 text-xs text-muted-foreground">
+															{isQueued ? (
+																<>
+																	<button
+																		type="button"
+																		className="rounded p-0.5 text-foreground hover:bg-accent/40"
+																		onMouseDown={(e) => e.preventDefault()}
+																		onClick={(e) => {
+																			e.stopPropagation();
+																			if (queued.count <= 1) {
+																				setQueued(null);
+																			} else {
+																				setQueued({
+																					...queued,
+																					count: queued.count - 1,
+																				});
+																			}
+																		}}
+																	>
+																		<Minus className="h-3 w-3" />
+																	</button>
+																	<span className="min-w-5 rounded-full bg-accent px-1.5 py-0.5 text-center font-medium text-foreground">
+																		{queued.count}
+																	</span>
+																	<button
+																		type="button"
+																		className="rounded p-0.5 text-foreground hover:bg-accent/40"
+																		onMouseDown={(e) => e.preventDefault()}
+																		onClick={(e) => {
+																			e.stopPropagation();
+																			setQueued({
+																				...queued,
+																				count: queued.count + 1,
+																			});
+																		}}
+																	>
+																		<Plus className="h-3 w-3" />
+																	</button>
+																	<button
+																		type="button"
+																		className="ml-0.5 rounded p-0.5 text-foreground hover:bg-accent/40"
+																		onMouseDown={(e) => e.preventDefault()}
+																		onClick={(e) => {
+																			e.stopPropagation();
+																			confirmQueued();
+																		}}
+																	>
+																		<Check className="h-3.5 w-3.5" />
+																	</button>
+																</>
+															) : (
+																result.sourceDisplayName
+															)}
+														</span>
+													</button>
+												</li>
+											);
+										})}
+									</ul>
+								)}
+							</div>
 						</div>
 					)}
 				</div>
-				{nameInput.length >= 2 && suggestions.length === 0 && (
+				{nameInput.length >= 2 && !hasSuggestions && (
 					<div className="flex items-center gap-2">
 						<Input
 							type="text"
@@ -370,6 +437,17 @@ export function ActionBar({
 				<Button type="submit" size="sm">
 					Add
 				</Button>
+				{onManagePlayers && (
+					<Button
+						type="button"
+						size="sm"
+						variant="ghost"
+						onClick={onManagePlayers}
+						title="Player characters"
+					>
+						<Users className="h-4 w-4" />
+					</Button>
+				)}
 				{bestiaryLoaded && onViewStatBlock && (
 					<div ref={viewerRef} className="relative">
 						<Button

apps/web/src/components/color-palette.tsx

@@ -0,0 +1,36 @@
+import { VALID_PLAYER_COLORS } from "@initiative/domain";
+import { cn } from "../lib/utils";
+import { PLAYER_COLOR_HEX } from "./player-icon-map";
+
+interface ColorPaletteProps {
+	value: string;
+	onChange: (color: string) => void;
+}
+
+const COLORS = [...VALID_PLAYER_COLORS] as string[];
+
+export function ColorPalette({ value, onChange }: ColorPaletteProps) {
+	return (
+		<div className="flex flex-wrap gap-2">
+			{COLORS.map((color) => (
+				<button
+					key={color}
+					type="button"
+					onClick={() => onChange(color)}
+					className={cn(
+						"h-8 w-8 rounded-full transition-all",
+						value === color
+							? "ring-2 ring-foreground ring-offset-2 ring-offset-background scale-110"
+							: "hover:scale-110",
+					)}
+					style={{
+						backgroundColor:
+							PLAYER_COLOR_HEX[color as keyof typeof PLAYER_COLOR_HEX],
+					}}
+					aria-label={color}
+					title={color}
+				/>
+			))}
+		</div>
+	);
+}

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

@@ -2,6 +2,7 @@ import {
 	type CombatantId,
 	type ConditionId,
 	deriveHpStatus,
+	type PlayerIcon,
 } from "@initiative/domain";
 import { Brain, X } from "lucide-react";
 import { type Ref, useCallback, useEffect, useRef, useState } from "react";
@@ -11,6 +12,7 @@ import { ConditionPicker } from "./condition-picker";
 import { ConditionTags } from "./condition-tags";
 import { D20Icon } from "./d20-icon";
 import { HpAdjustPopover } from "./hp-adjust-popover";
+import { PLAYER_COLOR_HEX, PLAYER_ICON_MAP } from "./player-icon-map";
 import { ConfirmButton } from "./ui/confirm-button";
 import { Input } from "./ui/input";
 
@@ -23,6 +25,8 @@ interface Combatant {
 	readonly ac?: number;
 	readonly conditions?: readonly ConditionId[];
 	readonly isConcentrating?: boolean;
+	readonly color?: string;
+	readonly icon?: string;
 }
 
 interface CombatantRowProps {
@@ -478,6 +482,11 @@ export function CombatantRow({
 		}
 	}, [combatant.isConcentrating]);
 
+	const pcColor =
+		combatant.color && !isActive && !combatant.isConcentrating
+			? PLAYER_COLOR_HEX[combatant.color as keyof typeof PLAYER_COLOR_HEX]
+			: undefined;
+
 	return (
 		/* biome-ignore lint/a11y/noStaticElementInteractions: role="button" is set conditionally when onShowStatBlock exists */
 		<div
@@ -490,6 +499,7 @@ export function CombatantRow({
 				isPulsing && "animate-concentration-pulse",
 				onShowStatBlock && "cursor-pointer",
 			)}
+			style={pcColor ? { borderLeftColor: pcColor } : undefined}
 			onClick={onShowStatBlock}
 			onKeyDown={
 				onShowStatBlock ? activateOnKeyDown(onShowStatBlock) : undefined
@@ -535,6 +545,22 @@ export function CombatantRow({
 						dimmed && "opacity-50",
 					)}
 				>
+					{combatant.icon &&
+						combatant.color &&
+						(() => {
+							const PcIcon = PLAYER_ICON_MAP[combatant.icon as PlayerIcon];
+							const pcColor =
+								PLAYER_COLOR_HEX[
+									combatant.color as keyof typeof PLAYER_COLOR_HEX
+								];
+							return PcIcon ? (
+								<PcIcon
+									size={14}
+									style={{ color: pcColor }}
+									className="shrink-0"
+								/>
+							) : null;
+						})()}
 					<EditableName
 						name={name}
 						combatantId={id}

apps/web/src/components/create-player-modal.tsx

@@ -0,0 +1,169 @@
+import type { PlayerCharacter } from "@initiative/domain";
+import { X } from "lucide-react";
+import { type FormEvent, useEffect, useState } from "react";
+import { ColorPalette } from "./color-palette";
+import { IconGrid } from "./icon-grid";
+import { Button } from "./ui/button";
+import { Input } from "./ui/input";
+
+interface CreatePlayerModalProps {
+	open: boolean;
+	onClose: () => void;
+	onSave: (
+		name: string,
+		ac: number,
+		maxHp: number,
+		color: string,
+		icon: string,
+	) => void;
+	playerCharacter?: PlayerCharacter;
+}
+
+export function CreatePlayerModal({
+	open,
+	onClose,
+	onSave,
+	playerCharacter,
+}: CreatePlayerModalProps) {
+	const [name, setName] = useState("");
+	const [ac, setAc] = useState("10");
+	const [maxHp, setMaxHp] = useState("10");
+	const [color, setColor] = useState("blue");
+	const [icon, setIcon] = useState("sword");
+	const [error, setError] = useState("");
+
+	const isEdit = !!playerCharacter;
+
+	useEffect(() => {
+		if (open) {
+			if (playerCharacter) {
+				setName(playerCharacter.name);
+				setAc(String(playerCharacter.ac));
+				setMaxHp(String(playerCharacter.maxHp));
+				setColor(playerCharacter.color);
+				setIcon(playerCharacter.icon);
+			} else {
+				setName("");
+				setAc("10");
+				setMaxHp("10");
+				setColor("blue");
+				setIcon("sword");
+			}
+			setError("");
+		}
+	}, [open, playerCharacter]);
+
+	if (!open) return null;
+
+	const handleSubmit = (e: FormEvent) => {
+		e.preventDefault();
+		const trimmed = name.trim();
+		if (trimmed === "") {
+			setError("Name is required");
+			return;
+		}
+		const acNum = Number.parseInt(ac, 10);
+		if (Number.isNaN(acNum) || acNum < 0) {
+			setError("AC must be a non-negative number");
+			return;
+		}
+		const hpNum = Number.parseInt(maxHp, 10);
+		if (Number.isNaN(hpNum) || hpNum < 1) {
+			setError("Max HP must be at least 1");
+			return;
+		}
+		onSave(trimmed, acNum, hpNum, color, icon);
+		onClose();
+	};
+
+	return (
+		<div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
+			<div className="w-full max-w-md rounded-lg border border-border bg-card p-6 shadow-xl">
+				<div className="mb-4 flex items-center justify-between">
+					<h2 className="text-lg font-semibold text-foreground">
+						{isEdit ? "Edit Player" : "Create Player"}
+					</h2>
+					<button
+						type="button"
+						onClick={onClose}
+						className="text-muted-foreground hover:text-foreground transition-colors"
+					>
+						<X size={20} />
+					</button>
+				</div>
+
+				<form onSubmit={handleSubmit} className="flex flex-col gap-4">
+					<div>
+						<span className="mb-1 block text-sm text-muted-foreground">
+							Name
+						</span>
+						<Input
+							type="text"
+							value={name}
+							onChange={(e) => {
+								setName(e.target.value);
+								setError("");
+							}}
+							placeholder="Character name"
+							aria-label="Name"
+							autoFocus
+						/>
+						{error && <p className="mt-1 text-sm text-destructive">{error}</p>}
+					</div>
+
+					<div className="flex gap-3">
+						<div className="flex-1">
+							<span className="mb-1 block text-sm text-muted-foreground">
+								AC
+							</span>
+							<Input
+								type="text"
+								inputMode="numeric"
+								value={ac}
+								onChange={(e) => setAc(e.target.value)}
+								placeholder="AC"
+								aria-label="AC"
+								className="text-center"
+							/>
+						</div>
+						<div className="flex-1">
+							<span className="mb-1 block text-sm text-muted-foreground">
+								Max HP
+							</span>
+							<Input
+								type="text"
+								inputMode="numeric"
+								value={maxHp}
+								onChange={(e) => setMaxHp(e.target.value)}
+								placeholder="Max HP"
+								aria-label="Max HP"
+								className="text-center"
+							/>
+						</div>
+					</div>
+
+					<div>
+						<span className="mb-2 block text-sm text-muted-foreground">
+							Color
+						</span>
+						<ColorPalette value={color} onChange={setColor} />
+					</div>
+
+					<div>
+						<span className="mb-2 block text-sm text-muted-foreground">
+							Icon
+						</span>
+						<IconGrid value={icon} onChange={setIcon} />
+					</div>
+
+					<div className="flex justify-end gap-2 pt-2">
+						<Button type="button" variant="ghost" onClick={onClose}>
+							Cancel
+						</Button>
+						<Button type="submit">{isEdit ? "Save" : "Create"}</Button>
+					</div>
+				</form>
+			</div>
+		</div>
+	);
+}

apps/web/src/components/icon-grid.tsx

@@ -0,0 +1,38 @@
+import type { PlayerIcon } from "@initiative/domain";
+import { VALID_PLAYER_ICONS } from "@initiative/domain";
+import { cn } from "../lib/utils";
+import { PLAYER_ICON_MAP } from "./player-icon-map";
+
+interface IconGridProps {
+	value: string;
+	onChange: (icon: string) => void;
+}
+
+const ICONS = [...VALID_PLAYER_ICONS] as PlayerIcon[];
+
+export function IconGrid({ value, onChange }: IconGridProps) {
+	return (
+		<div className="flex flex-wrap gap-2">
+			{ICONS.map((iconId) => {
+				const Icon = PLAYER_ICON_MAP[iconId];
+				return (
+					<button
+						key={iconId}
+						type="button"
+						onClick={() => onChange(iconId)}
+						className={cn(
+							"flex h-9 w-9 items-center justify-center rounded-md transition-all",
+							value === iconId
+								? "bg-primary/20 ring-2 ring-primary text-foreground"
+								: "text-muted-foreground hover:bg-card hover:text-foreground",
+						)}
+						aria-label={iconId}
+						title={iconId}
+					>
+						<Icon size={20} />
+					</button>
+				);
+			})}
+		</div>
+	);
+}

apps/web/src/components/player-icon-map.ts

@@ -0,0 +1,50 @@
+import type { PlayerColor, PlayerIcon } from "@initiative/domain";
+import type { LucideIcon } from "lucide-react";
+import {
+	Axe,
+	Crosshair,
+	Crown,
+	Eye,
+	Feather,
+	Flame,
+	Heart,
+	Moon,
+	Shield,
+	Skull,
+	Star,
+	Sun,
+	Sword,
+	Wand,
+	Zap,
+} from "lucide-react";
+
+export const PLAYER_ICON_MAP: Record<PlayerIcon, LucideIcon> = {
+	sword: Sword,
+	shield: Shield,
+	skull: Skull,
+	heart: Heart,
+	wand: Wand,
+	flame: Flame,
+	crown: Crown,
+	star: Star,
+	moon: Moon,
+	sun: Sun,
+	axe: Axe,
+	crosshair: Crosshair,
+	eye: Eye,
+	feather: Feather,
+	zap: Zap,
+};
+
+export const PLAYER_COLOR_HEX: Record<PlayerColor, string> = {
+	red: "#ef4444",
+	blue: "#3b82f6",
+	green: "#22c55e",
+	purple: "#a855f7",
+	orange: "#f97316",
+	pink: "#ec4899",
+	cyan: "#06b6d4",
+	yellow: "#eab308",
+	emerald: "#10b981",
+	indigo: "#6366f1",
+};

apps/web/src/components/player-management.tsx

@@ -0,0 +1,105 @@
+import type {
+	PlayerCharacter,
+	PlayerCharacterId,
+	PlayerIcon,
+} from "@initiative/domain";
+import { Pencil, Plus, X } from "lucide-react";
+import { PLAYER_COLOR_HEX, PLAYER_ICON_MAP } from "./player-icon-map";
+import { Button } from "./ui/button";
+import { ConfirmButton } from "./ui/confirm-button";
+
+interface PlayerManagementProps {
+	open: boolean;
+	onClose: () => void;
+	characters: readonly PlayerCharacter[];
+	onEdit: (pc: PlayerCharacter) => void;
+	onDelete: (id: PlayerCharacterId) => void;
+	onCreate: () => void;
+}
+
+export function PlayerManagement({
+	open,
+	onClose,
+	characters,
+	onEdit,
+	onDelete,
+	onCreate,
+}: PlayerManagementProps) {
+	if (!open) return null;
+
+	return (
+		<div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
+			<div className="w-full max-w-md rounded-lg border border-border bg-card p-6 shadow-xl">
+				<div className="mb-4 flex items-center justify-between">
+					<h2 className="text-lg font-semibold text-foreground">
+						Player Characters
+					</h2>
+					<button
+						type="button"
+						onClick={onClose}
+						className="text-muted-foreground hover:text-foreground transition-colors"
+					>
+						<X size={20} />
+					</button>
+				</div>
+
+				{characters.length === 0 ? (
+					<div className="flex flex-col items-center gap-3 py-8 text-center">
+						<p className="text-muted-foreground">No player characters yet</p>
+						<Button onClick={onCreate} size="sm">
+							<Plus size={16} />
+							Create your first player character
+						</Button>
+					</div>
+				) : (
+					<div className="flex flex-col gap-1">
+						{characters.map((pc) => {
+							const Icon = PLAYER_ICON_MAP[pc.icon as PlayerIcon];
+							const color =
+								PLAYER_COLOR_HEX[pc.color as keyof typeof PLAYER_COLOR_HEX];
+							return (
+								<div
+									key={pc.id}
+									className="group flex items-center gap-3 rounded-md px-3 py-2 hover:bg-background/50"
+								>
+									{Icon && (
+										<Icon size={18} style={{ color }} className="shrink-0" />
+									)}
+									<span className="flex-1 truncate text-sm text-foreground">
+										{pc.name}
+									</span>
+									<span className="text-xs tabular-nums text-muted-foreground">
+										AC {pc.ac}
+									</span>
+									<span className="text-xs tabular-nums text-muted-foreground">
+										HP {pc.maxHp}
+									</span>
+									<button
+										type="button"
+										onClick={() => onEdit(pc)}
+										className="text-muted-foreground hover:text-foreground transition-colors"
+										title="Edit"
+									>
+										<Pencil size={14} />
+									</button>
+									<ConfirmButton
+										icon={<X size={14} />}
+										label="Delete player character"
+										onConfirm={() => onDelete(pc.id)}
+										className="h-6 w-6 text-muted-foreground"
+									/>
+								</div>
+							);
+						})}
+						<div className="mt-2 flex justify-end">
+							<Button onClick={onCreate} size="sm" variant="ghost">
+								<Plus size={16} />
+								Add
+							</Button>
+						</div>
+					</div>
+				)}
+			</div>
+		</div>
+	);
+}

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

@@ -19,6 +19,7 @@ import type {
 	ConditionId,
 	DomainEvent,
 	Encounter,
+	PlayerCharacter,
 } from "@initiative/domain";
 import {
 	combatantId,
@@ -318,6 +319,58 @@ export function useEncounter() {
 		[makeStore, editCombatant],
 	);
 
+	const addFromPlayerCharacter = useCallback(
+		(pc: PlayerCharacter) => {
+			const store = makeStore();
+			const existingNames = store.get().combatants.map((c) => c.name);
+			const { newName, renames } = resolveCreatureName(pc.name, existingNames);
+
+			for (const { from, to } of renames) {
+				const target = store.get().combatants.find((c) => c.name === from);
+				if (target) {
+					editCombatantUseCase(makeStore(), target.id, to);
+				}
+			}
+
+			const id = combatantId(`c-${++nextId.current}`);
+			const addResult = addCombatantUseCase(makeStore(), id, newName);
+			if (isDomainError(addResult)) return;
+
+			// Set HP
+			const hpResult = setHpUseCase(makeStore(), id, pc.maxHp);
+			if (!isDomainError(hpResult)) {
+				setEvents((prev) => [...prev, ...hpResult]);
+			}
+
+			// Set AC
+			if (pc.ac > 0) {
+				const acResult = setAcUseCase(makeStore(), id, pc.ac);
+				if (!isDomainError(acResult)) {
+					setEvents((prev) => [...prev, ...acResult]);
+				}
+			}
+
+			// Set color, icon, and playerCharacterId on the combatant
+			const currentEncounter = store.get();
+			store.save({
+				...currentEncounter,
+				combatants: currentEncounter.combatants.map((c) =>
+					c.id === id
+						? {
+								...c,
+								color: pc.color,
+								icon: pc.icon,
+								playerCharacterId: pc.id,
+							}
+						: c,
+				),
+			});
+
+			setEvents((prev) => [...prev, ...addResult]);
+		},
+		[makeStore, editCombatant],
+	);
+
 	return {
 		encounter,
 		events,
@@ -334,6 +387,7 @@ export function useEncounter() {
 		toggleCondition,
 		toggleConcentration,
 		addFromBestiary,
+		addFromPlayerCharacter,
 		makeStore,
 	} as const;
 }

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

@@ -0,0 +1,102 @@
+import type { PlayerCharacterStore } from "@initiative/application";
+import {
+	createPlayerCharacterUseCase,
+	deletePlayerCharacterUseCase,
+	editPlayerCharacterUseCase,
+} from "@initiative/application";
+import type { PlayerCharacter, PlayerCharacterId } from "@initiative/domain";
+import { isDomainError, playerCharacterId } from "@initiative/domain";
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+	loadPlayerCharacters,
+	savePlayerCharacters,
+} from "../persistence/player-character-storage.js";
+
+function initializeCharacters(): PlayerCharacter[] {
+	return loadPlayerCharacters();
+}
+
+let nextPcId = 0;
+
+function generatePcId(): PlayerCharacterId {
+	return playerCharacterId(`pc-${++nextPcId}`);
+}
+
+interface EditFields {
+	readonly name?: string;
+	readonly ac?: number;
+	readonly maxHp?: number;
+	readonly color?: string;
+	readonly icon?: string;
+}
+
+export function usePlayerCharacters() {
+	const [characters, setCharacters] =
+		useState<PlayerCharacter[]>(initializeCharacters);
+	const charactersRef = useRef(characters);
+	charactersRef.current = characters;
+
+	useEffect(() => {
+		savePlayerCharacters(characters);
+	}, [characters]);
+
+	const makeStore = useCallback((): PlayerCharacterStore => {
+		return {
+			getAll: () => charactersRef.current,
+			save: (updated) => {
+				charactersRef.current = updated;
+				setCharacters(updated);
+			},
+		};
+	}, []);
+
+	const createCharacter = useCallback(
+		(name: string, ac: number, maxHp: number, color: string, icon: string) => {
+			const id = generatePcId();
+			const result = createPlayerCharacterUseCase(
+				makeStore(),
+				id,
+				name,
+				ac,
+				maxHp,
+				color,
+				icon,
+			);
+			if (isDomainError(result)) {
+				return result;
+			}
+			return undefined;
+		},
+		[makeStore],
+	);
+
+	const editCharacter = useCallback(
+		(id: PlayerCharacterId, fields: EditFields) => {
+			const result = editPlayerCharacterUseCase(makeStore(), id, fields);
+			if (isDomainError(result)) {
+				return result;
+			}
+			return undefined;
+		},
+		[makeStore],
+	);
+
+	const deleteCharacter = useCallback(
+		(id: PlayerCharacterId) => {
+			const result = deletePlayerCharacterUseCase(makeStore(), id);
+			if (isDomainError(result)) {
+				return result;
+			}
+			return undefined;
+		},
+		[makeStore],
+	);
+
+	return {
+		characters,
+		createCharacter,
+		editCharacter,
+		deleteCharacter,
+		makeStore,
+	} as const;
+}

apps/web/src/persistence/__tests__/player-character-storage.test.ts

@@ -0,0 +1,231 @@
+import type { PlayerCharacter } from "@initiative/domain";
+import { playerCharacterId } from "@initiative/domain";
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+	loadPlayerCharacters,
+	savePlayerCharacters,
+} from "../player-character-storage.js";
+
+const STORAGE_KEY = "initiative:player-characters";
+
+function createMockLocalStorage() {
+	const store = new Map<string, string>();
+	return {
+		getItem: (key: string) => store.get(key) ?? null,
+		setItem: (key: string, value: string) => store.set(key, value),
+		removeItem: (key: string) => store.delete(key),
+		clear: () => store.clear(),
+		get length() {
+			return store.size;
+		},
+		key: (_index: number) => null,
+		store,
+	};
+}
+
+function makePC(overrides?: Partial<PlayerCharacter>): PlayerCharacter {
+	return {
+		id: playerCharacterId("pc-1"),
+		name: "Aragorn",
+		ac: 16,
+		maxHp: 120,
+		color: "green",
+		icon: "sword",
+		...overrides,
+	};
+}
+
+describe("player-character-storage", () => {
+	let mockStorage: ReturnType<typeof createMockLocalStorage>;
+
+	beforeEach(() => {
+		mockStorage = createMockLocalStorage();
+		Object.defineProperty(globalThis, "localStorage", {
+			value: mockStorage,
+			writable: true,
+		});
+	});
+
+	describe("round-trip save/load", () => {
+		it("saves and loads a single character", () => {
+			const pc = makePC();
+			savePlayerCharacters([pc]);
+			const loaded = loadPlayerCharacters();
+			expect(loaded).toEqual([pc]);
+		});
+
+		it("saves and loads multiple characters", () => {
+			const pcs = [
+				makePC({ id: playerCharacterId("pc-1"), name: "Aragorn" }),
+				makePC({
+					id: playerCharacterId("pc-2"),
+					name: "Legolas",
+					ac: 14,
+					maxHp: 90,
+					color: "blue",
+					icon: "eye",
+				}),
+			];
+			savePlayerCharacters(pcs);
+			const loaded = loadPlayerCharacters();
+			expect(loaded).toEqual(pcs);
+		});
+	});
+
+	describe("empty storage", () => {
+		it("returns empty array when no data exists", () => {
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+	});
+
+	describe("corrupt JSON", () => {
+		it("returns empty array for invalid JSON", () => {
+			mockStorage.setItem(STORAGE_KEY, "not-json{{{");
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+
+		it("returns empty array for non-array JSON", () => {
+			mockStorage.setItem(STORAGE_KEY, '{"foo": "bar"}');
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+	});
+
+	describe("per-character validation", () => {
+		it("discards character with missing name", () => {
+			mockStorage.setItem(
+				STORAGE_KEY,
+				JSON.stringify([
+					{ id: "pc-1", ac: 10, maxHp: 50, color: "blue", icon: "sword" },
+				]),
+			);
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+
+		it("discards character with empty name", () => {
+			mockStorage.setItem(
+				STORAGE_KEY,
+				JSON.stringify([
+					{
+						id: "pc-1",
+						name: "",
+						ac: 10,
+						maxHp: 50,
+						color: "blue",
+						icon: "sword",
+					},
+				]),
+			);
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+
+		it("discards character with invalid color", () => {
+			mockStorage.setItem(
+				STORAGE_KEY,
+				JSON.stringify([
+					{
+						id: "pc-1",
+						name: "Test",
+						ac: 10,
+						maxHp: 50,
+						color: "neon",
+						icon: "sword",
+					},
+				]),
+			);
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+
+		it("discards character with invalid icon", () => {
+			mockStorage.setItem(
+				STORAGE_KEY,
+				JSON.stringify([
+					{
+						id: "pc-1",
+						name: "Test",
+						ac: 10,
+						maxHp: 50,
+						color: "blue",
+						icon: "banana",
+					},
+				]),
+			);
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+
+		it("discards character with negative AC", () => {
+			mockStorage.setItem(
+				STORAGE_KEY,
+				JSON.stringify([
+					{
+						id: "pc-1",
+						name: "Test",
+						ac: -1,
+						maxHp: 50,
+						color: "blue",
+						icon: "sword",
+					},
+				]),
+			);
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+
+		it("discards character with maxHp of 0", () => {
+			mockStorage.setItem(
+				STORAGE_KEY,
+				JSON.stringify([
+					{
+						id: "pc-1",
+						name: "Test",
+						ac: 10,
+						maxHp: 0,
+						color: "blue",
+						icon: "sword",
+					},
+				]),
+			);
+			expect(loadPlayerCharacters()).toEqual([]);
+		});
+
+		it("keeps valid characters and discards invalid ones", () => {
+			mockStorage.setItem(
+				STORAGE_KEY,
+				JSON.stringify([
+					{
+						id: "pc-1",
+						name: "Valid",
+						ac: 10,
+						maxHp: 50,
+						color: "blue",
+						icon: "sword",
+					},
+					{
+						id: "pc-2",
+						name: "",
+						ac: 10,
+						maxHp: 50,
+						color: "blue",
+						icon: "sword",
+					},
+				]),
+			);
+			const loaded = loadPlayerCharacters();
+			expect(loaded).toHaveLength(1);
+			expect(loaded[0].name).toBe("Valid");
+		});
+	});
+
+	describe("storage errors", () => {
+		it("save silently catches errors", () => {
+			Object.defineProperty(globalThis, "localStorage", {
+				value: {
+					setItem: () => {
+						throw new Error("QuotaExceeded");
+					},
+					getItem: () => null,
+				},
+				writable: true,
+			});
+			expect(() => savePlayerCharacters([makePC()])).not.toThrow();
+		});
+	});
+});

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

@@ -5,7 +5,10 @@ import {
 	creatureId,
 	type Encounter,
 	isDomainError,
+	playerCharacterId,
 	VALID_CONDITION_IDS,
+	VALID_PLAYER_COLORS,
+	VALID_PLAYER_ICONS,
 } from "@initiative/domain";
 
 const STORAGE_KEY = "initiative:encounter";
@@ -70,12 +73,29 @@ function rehydrateCombatant(c: unknown) {
 			typeof entry.initiative === "number" ? entry.initiative : undefined,
 	};
 
+	const color =
+		typeof entry.color === "string" && VALID_PLAYER_COLORS.has(entry.color)
+			? entry.color
+			: undefined;
+	const icon =
+		typeof entry.icon === "string" && VALID_PLAYER_ICONS.has(entry.icon)
+			? entry.icon
+			: undefined;
+	const pcId =
+		typeof entry.playerCharacterId === "string" &&
+		entry.playerCharacterId.length > 0
+			? playerCharacterId(entry.playerCharacterId)
+			: undefined;
+
 	const shared = {
 		...base,
 		ac: validateAc(entry.ac),
 		conditions: validateConditions(entry.conditions),
 		isConcentrating: entry.isConcentrating === true ? true : undefined,
 		creatureId: validateCreatureId(entry.creatureId),
+		color,
+		icon,
+		playerCharacterId: pcId,
 	};
 
 	const hp = validateHp(entry.maxHp, entry.currentHp);

apps/web/src/persistence/player-character-storage.ts

@@ -0,0 +1,72 @@
+import type { PlayerCharacter } from "@initiative/domain";
+import {
+	playerCharacterId,
+	VALID_PLAYER_COLORS,
+	VALID_PLAYER_ICONS,
+} from "@initiative/domain";
+
+const STORAGE_KEY = "initiative:player-characters";
+
+export function savePlayerCharacters(characters: PlayerCharacter[]): void {
+	try {
+		localStorage.setItem(STORAGE_KEY, JSON.stringify(characters));
+	} catch {
+		// Silently swallow errors (quota exceeded, storage unavailable)
+	}
+}
+
+function rehydrateCharacter(raw: unknown): PlayerCharacter | null {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+		return null;
+	const entry = raw as Record<string, unknown>;
+
+	if (typeof entry.id !== "string" || entry.id.length === 0) return null;
+	if (typeof entry.name !== "string" || entry.name.trim().length === 0)
+		return null;
+	if (
+		typeof entry.ac !== "number" ||
+		!Number.isInteger(entry.ac) ||
+		entry.ac < 0
+	)
+		return null;
+	if (
+		typeof entry.maxHp !== "number" ||
+		!Number.isInteger(entry.maxHp) ||
+		entry.maxHp < 1
+	)
+		return null;
+	if (typeof entry.color !== "string" || !VALID_PLAYER_COLORS.has(entry.color))
+		return null;
+	if (typeof entry.icon !== "string" || !VALID_PLAYER_ICONS.has(entry.icon))
+		return null;
+
+	return {
+		id: playerCharacterId(entry.id),
+		name: entry.name,
+		ac: entry.ac,
+		maxHp: entry.maxHp,
+		color: entry.color as PlayerCharacter["color"],
+		icon: entry.icon as PlayerCharacter["icon"],
+	};
+}
+
+export function loadPlayerCharacters(): PlayerCharacter[] {
+	try {
+		const raw = localStorage.getItem(STORAGE_KEY);
+		if (raw === null) return [];
+
+		const parsed: unknown = JSON.parse(raw);
+		if (!Array.isArray(parsed)) return [];
+
+		const characters: PlayerCharacter[] = [];
+		for (const item of parsed) {
+			const pc = rehydrateCharacter(item);
+			if (pc !== null) {
+				characters.push(pc);
+			}
+		}
+		return characters;
+	} catch {
+		return [];
+	}
+}