# Research: HP Status Indicators

**Feature**: 013-hp-status-indicators
**Date**: 2026-03-05

## R1: HP Status Derivation Approach

**Decision**: Implement as a pure domain function `deriveHpStatus(currentHp, maxHp)` returning a discriminated union type `HpStatus = "healthy" | "bloodied" | "unconscious"`.

**Rationale**:
- The status is a derived value, not stored state. Computing it on demand avoids synchronization issues and keeps the data model unchanged.
- A standalone pure function in the domain layer is consistent with the project's architecture (e.g., `adjustHp`, `setHp` are each in their own module).
- Returning a simple string union (not an object or class) is the lightest representation and easy to pattern-match in the UI.

**Alternatives considered**:
- Storing status as a field on `Combatant`: Rejected -- introduces redundant state that must stay in sync with HP changes. Violates principle of derived data.
- Computing in the UI layer only: Rejected -- violates constitution principle I (domain logic must be pure domain functions) and makes the logic untestable without a UI.

## R2: Bloodied Threshold

**Decision**: Bloodied when `0 < currentHp < maxHp / 2` (strict less-than for both bounds, floating-point division).

**Rationale**:
- Follows D&D 4e/5e convention where "bloodied" means below half HP.
- Using strict less-than means at exactly half HP the combatant is still "healthy" -- this is the most common TTRPG interpretation.
- Floating-point division handles odd maxHp values correctly (e.g., maxHp=21: bloodied at 10 since 10 < 10.5).

**Alternatives considered**:
- `currentHp <= maxHp / 2`: Would make combatants at exactly half HP appear bloodied. Less standard.
- `Math.floor(maxHp / 2)`: Would make maxHp=21 bloodied at 10 (same result) but maxHp=20 bloodied at 10 (also same). No practical difference but adds unnecessary complexity.

## R3: Visual Treatment Approach

**Decision**: Color the HP text and optionally mute the entire row for unconscious combatants:
- **Healthy**: Default foreground color (no change)
- **Bloodied**: Amber/orange HP text (`text-amber-400`) -- warm danger signal
- **Unconscious**: Red HP text (`text-red-400`) + reduced row opacity (`opacity-50`) -- clearly out of action

**Rationale**:
- Coloring the HP number is the most targeted indicator -- it draws the eye to the relevant data point.
- Row opacity reduction for unconscious combatants provides a strong "out of action" signal without removing the row (GM may still need to reference it).
- Amber and red are universally understood warning/danger colors and already used in the project (red for damage mode in quick-hp-input, `--color-destructive: #ef4444`).
- No new icons needed -- color alone is sufficient for two states and avoids visual clutter.

**Alternatives considered**:
- Full row background color: Too visually heavy, would conflict with the active-turn indicator (blue left border + bg-accent/10).
- Strikethrough on name for unconscious: Considered but opacity reduction is more modern and less ambiguous (strikethrough could imply "removed").
- Badge/pill indicator: Adds UI elements and visual weight. Color on existing text is simpler.

## R4: Function Signature & Return for Undefined HP

**Decision**: Return `undefined` when maxHp is not set (status is not applicable). Function signature: `deriveHpStatus(currentHp: number | undefined, maxHp: number | undefined): HpStatus | undefined`.

**Rationale**:
- When maxHp is undefined, HP tracking is disabled for that combatant. No status can be derived.
- Returning `undefined` (not a fourth status value) keeps the type clean and matches the "no HP tracking" semantic.
- The UI simply skips styling when the result is `undefined`.

**Alternatives considered**:
- Separate `"none"` status: Adds a value that is semantically different from the three health states. `undefined` is more idiomatic TypeScript for "not applicable".