initiative/specs/008-encounter-difficulty/quickstart.md

Quickstart: Encounter Difficulty Indicator

Date: 2026-03-27 | Feature: 008-encounter-difficulty

Implementation Order

Phase 1: Domain — Level field + validation

1. Add level?: number to PlayerCharacter in player-character-types.ts
2. Add level validation to createPlayerCharacter() — validate if provided: integer, 1-20
3. Add level validation to editPlayerCharacter() — same rules in validateFields(), apply in applyFields()
4. Add tests for level validation in existing test files
5. Export updated types from index.ts

Phase 2: Domain — Difficulty calculation

1. Create encounter-difficulty.ts with:
   • CR_TO_XP lookup (Record<string, number>)
   • XP_BUDGET_PER_CHARACTER lookup (Record<number, { low, moderate, high }>)
   • crToXp(cr: string): number — returns 0 for unknown CRs
   • calculateEncounterDifficulty(partyLevels: number[], monsterCrs: string[]): DifficultyResult
   • DifficultyTier type and DifficultyResult type
2. Add comprehensive unit tests covering:
   • All CR string formats (0, 1/8, 1/4, 1/2, integers)
   • All difficulty tiers including trivial
   • DMG example encounters (from issue comments)
   • Edge cases: empty arrays, unknown CRs, mixed levels
3. Export from index.ts

Phase 3: Application — Pass level through use cases

1. Update CreatePlayerCharacterUseCase to accept and pass level
2. Update EditPlayerCharacterUseCase to accept and pass level

Phase 4: Web — Level field in PC forms

1. Update player characters context to pass level in create/edit calls
2. Add level input field to create player modal (optional number, 1-20)
3. Add level display + edit in player character manager
4. Test: create PC with level, edit level, verify persistence

Phase 5: Web — Difficulty indicator

1. Create useDifficulty() hook:
   • Consume encounter context, player characters context, bestiary hook
   • Map combatants → party levels + monster CRs
   • Call domain calculateEncounterDifficulty()
   • Return DifficultyResult | null (null when insufficient data)
2. Create DifficultyIndicator component:
   • Render 3 bars with conditional fill colors
   • Add title attribute for tooltip
   • Hidden when hook returns null
3. Add indicator to TurnNavigation component, right of active combatant name
4. Test: manual verification with various encounter compositions

Key Patterns to Follow

• Domain purity: calculateEncounterDifficulty takes number[] and string[], not domain types
• Validation pattern: Follow color/icon optional field pattern in create/edit
• Hook composition: useDifficulty composes multiple contexts like useInitiativeRolls
• Component size: DifficultyIndicator should be <8 props (likely 0-1, just the result)

Testing Strategy

• Domain tests (unit): Exhaustive coverage of calculateEncounterDifficulty and crToXp with table-driven tests. Cover all 34 CR values, all 20 levels, and the DMG example encounters.
• Domain tests (level validation): Test create/edit with valid levels, invalid levels, and undefined level.
• Integration: Verify indicator appears/hides correctly through component rendering (if existing test patterns support this).