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

Research: Encounter Difficulty Indicator

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

Research Questions & Findings

1. Where does the CR-to-XP mapping come from?

Decision: Create a static lookup table in the domain layer as a Record<string, number>.

Rationale: No CR-to-XP mapping exists in the codebase. The bestiary index stores CR as a string but does not include XP. The standard 5e CR-to-XP table is fixed (published rules), so a static lookup is the simplest approach. The existing proficiencyBonus(cr) function in creature-types.ts demonstrates the pattern: a pure function that maps a CR string to a derived value.

Alternatives considered:

• Adding XP to the bestiary index: Would require rebuilding the index generation script and inflating the index size. Unnecessary since XP is deterministically derived from CR.
• Computing XP from CR via formula: No clean formula exists for the 5e table — it's an irregular curve. A lookup table is more reliable and readable.

2. How does the difficulty component access creature CR at runtime?

Decision: The difficulty hook (useDifficulty) will consume useBestiary() to access the creature map, then look up CR for each combatant with a creatureId.

Rationale: The useBestiary() hook already provides getCreature(id): Creature | undefined, which returns the full Creature including cr. This is the established pattern — CombatantRow and StatBlockPanel already use it. No new adapter or port is needed.

Data flow:

useDifficulty hook
├── useEncounterContext() → encounter.combatants[]
├── usePlayerCharactersContext() → characters[] (for level lookup)
└── useBestiary() → getCreature(creatureId) → creature.cr
    └── domain: crToXp(cr) → xp
    └── domain: calculateDifficulty({ partyLevels, monsterXp }) → DifficultyResult

Alternatives considered:

• Passing CR through the application layer port: Would add a BestiarySourceCache dependency to the difficulty calculation, breaking domain purity. Better to resolve CRs to XP values in the hook (adapter layer) and pass pure data to the domain function.

3. How should the domain difficulty function be structured?

Decision: A single pure function that takes resolved inputs (party levels as number[], monster XP values as number[]) and returns a DifficultyResult.

Rationale: Keeping the domain function agnostic to how levels and XP are obtained preserves purity and testability. The function doesn't need to know about PlayerCharacter, Combatant, or Creature types — just numbers. This follows the pattern of advanceTurn(encounter) and proficiencyBonus(cr): pure inputs → pure outputs.

Function signature (domain):

calculateEncounterDifficulty(partyLevels: number[], monsterCrs: string[]): DifficultyResult

Takes party levels (already filtered to only PCs with levels) and monster CR strings (already filtered to only bestiary-linked combatants). Returns the tier, total XP, and budget thresholds.

Alternatives considered:

• Taking full Combatant[] + PlayerCharacter[]: Would couple the difficulty module to combatant/PC types unnecessarily.
• Separate functions for budget and XP: The calculation is simple enough for one function. Internal helpers can split the logic without exposing multiple public functions.

4. How does level integrate with the PlayerCharacter CRUD flow?

Decision: Add level?: number to PlayerCharacter interface. Validation in createPlayerCharacter and editPlayerCharacter domain functions. Passed through use cases and context like existing fields.

Rationale: The existing pattern for optional fields (e.g., color, icon) is well-established:

• Domain type: optional field on interface
• Create function: validate if provided, skip if undefined
• Edit function: validate in validateFields(), apply in applyFields()
• Use case: pass through from adapter
• Context: expose in create/edit methods
• UI: optional input field in modal

Following this exact pattern for level minimizes risk and code churn.

5. Does adding level to PlayerCharacter affect export compatibility?

Decision: No version bump needed. The field is optional, so existing exports (version 1) import correctly — level will be undefined for old data.

Rationale: The ExportBundle includes playerCharacters: readonly PlayerCharacter[]. Adding an optional field to PlayerCharacter is backward-compatible: old exports simply lack the field, which TypeScript treats as undefined. The validateImportBundle() function doesn't validate individual PlayerCharacter fields beyond basic structure checks.

6. Should the difficulty calculation live in a new domain module or extend an existing one?

Decision: New module encounter-difficulty.ts in packages/domain/src/.

Rationale: The difficulty calculation is a self-contained concern with its own lookup tables and types. It doesn't naturally belong in creature-types.ts (which is about creature data structures) or types.ts (which is about encounter/combatant structure). A dedicated module keeps concerns separated and makes the feature easy to find, test, and potentially remove.

7. How should the 3-bar indicator be rendered?

Decision: Simple div elements with Tailwind CSS classes for color and fill state. No external icon or SVG needed.

Rationale: The bars are simple rectangles with conditional fill colors (green/yellow/red). Tailwind's bg-* utilities handle this trivially. The existing codebase uses Tailwind for all styling with no CSS-in-JS or external style libraries. A native HTML tooltip (title attribute) handles the hover tooltip requirement.

Alternatives considered:

• Lucide icons: No suitable "signal bars" icon exists. Custom SVG would be overkill for 3 rectangles.
• CSS custom properties for colors: Unnecessary abstraction for 3 fixed states.