initiative/specs/005-player-characters/research.md

Research: Player Character Management

Branch: 005-player-characters | Date: 2026-03-12

Key Decisions

1. PlayerCharacter as a separate domain entity

• Decision: PlayerCharacter is a new type in the domain layer, distinct from Combatant. When added to an encounter, a snapshot is copied into a Combatant.
• Rationale: Player characters are persistent templates reused across encounters; combatants are ephemeral per-encounter instances. Mixing them would violate the single-responsibility of the Encounter aggregate.
• Alternatives considered: Extending Combatant with a isPlayerCharacter flag — rejected because combatants belong to encounters and are cleared with them, while player characters must survive encounter clears.

2. Combatant type extension for color and icon

• Decision: Add optional color?: string and icon?: string fields to the existing Combatant interface, plus playerCharacterId?: PlayerCharacterId to track origin.
• Rationale: The combatant row needs to render color/icon. Storing these on the combatant (copied from the player character at add-time) keeps the combatant self-contained and avoids runtime lookups against the player character store.
• Alternatives considered: Looking up color/icon from the player character store at render time — rejected because the player character might be deleted or edited after the combatant was added, and the spec says combatants are independent copies.

3. Storage: separate localStorage key

• Decision: Use localStorage with key "initiative:player-characters", separate from encounter storage ("initiative:encounter").
• Rationale: Follows existing pattern (encounter uses its own key). Player characters must survive encounter clears. IndexedDB is overkill for a small list of player characters.
• Alternatives considered: IndexedDB (like bestiary cache) — rejected as overly complex for simple JSON list. Shared key with encounter — rejected because clearing encounter would wipe player characters.

4. Search integration approach

• Decision: The useBestiary search hook or a new usePlayerCharacters hook provides player character search results. The ActionBar dropdown renders a "Players" group above bestiary results.
• Rationale: Player character search is a simple substring match on a small in-memory list — no index needed. Keeping it separate from bestiary search maintains separation of concerns.
• Alternatives considered: Merging into the bestiary index — rejected because player characters are user-created, not part of the pre-built index.

5. Color palette and icon set

• Decision: Use a fixed set of 10 distinguishable colors and ~15 Lucide icons already available in the project.
• Rationale: Lucide React is already a dependency. A fixed palette ensures visual consistency and simplifies the domain model (color is a string enum, not arbitrary hex).
• Alternatives considered: Arbitrary hex color picker — rejected for MVP as it complicates UX and validation.

6. Domain operations pattern

• Decision: Player character CRUD follows the same pattern as encounter operations: pure functions returning {result, events} | DomainError. New domain events: PlayerCharacterCreated, PlayerCharacterUpdated, PlayerCharacterDeleted.
• Rationale: Consistency with existing domain patterns. Events enable future features (undo, audit).
• Alternatives considered: Simpler CRUD without events — rejected for consistency with the project's event-driven domain.

7. Management view location

• Decision: A new icon button in the bottom bar (alongside the existing search) opens a player character management panel/modal.
• Rationale: The bottom bar already serves as the primary action area. A modal keeps the management view accessible without adding routing complexity.
• Alternatives considered: A separate route/page — rejected because the app is currently a single-page encounter tracker with no routing.

Cross-feature impacts

Spec 001 (Combatant Management)

• Combatant type gains three optional fields: color, icon, playerCharacterId
• encounter-storage.ts rehydration needs to handle new optional fields
• Combatant row component needs to render color/icon when present

Spec 003 (Combatant State)

• No changes needed. AC and HP management already works on optional fields that player characters pre-fill.

Spec 004 (Bestiary)

• ActionBar dropdown gains a "Players" section above bestiary results
• addFromBestiary pattern informs the new addFromPlayerCharacter flow
• No changes to bestiary search itself

Unresolved items

None. All technical decisions are resolved.