# Feature Specification: Edit Combatant

**Feature Branch**: `004-edit-combatant`
**Created**: 2026-03-03
**Status**: Draft
**Input**: User description: "EditCombatant: allow updating a combatant's name by id in Encounter (emit CombatantUpdated, error if id not found) and wire through application + minimal UI."

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Rename a Combatant (Priority: P1)

A user running an encounter realizes a combatant's name is misspelled or wants to change it. They select the combatant by its identity, provide a new name, and the system updates the combatant in-place while preserving turn order and round state.

**Why this priority**: Core feature — without the ability to rename, the entire edit-combatant feature has no value.

**Independent Test**: Can be fully tested by creating an encounter with combatants, editing one combatant's name, and verifying the name is updated while all other encounter state remains unchanged.

**Acceptance Scenarios**:

1. **Given** an encounter with combatants [Alice, Bob], **When** the user updates Bob's name to "Robert", **Then** the encounter contains [Alice, Robert] and a `CombatantUpdated` event is emitted with the combatant's id, old name, and new name.
2. **Given** an encounter with combatants [Alice, Bob] where Bob is the active combatant, **When** the user updates Bob's name to "Robert", **Then** Bob remains the active combatant (active index unchanged) and the round number is preserved.

---

### User Story 2 - Error Feedback on Invalid Edit (Priority: P2)

A user attempts to edit a combatant that no longer exists (e.g., removed in another action) or provides an invalid name. The system returns a clear error without modifying the encounter.

**Why this priority**: Error handling ensures data integrity and provides a usable experience when things go wrong.

**Independent Test**: Can be tested by attempting to edit a non-existent combatant id and verifying an error is returned with no state change.

**Acceptance Scenarios**:

1. **Given** an encounter with combatants [Alice, Bob], **When** the user attempts to update a combatant with a non-existent id, **Then** the system returns a "combatant not found" error and the encounter is unchanged.
2. **Given** an encounter with combatants [Alice, Bob], **When** the user attempts to update Alice's name to an empty string, **Then** the system returns an "invalid name" error and the encounter is unchanged.
3. **Given** an encounter with combatants [Alice, Bob], **When** the user attempts to update Alice's name to a whitespace-only string, **Then** the system returns an "invalid name" error and the encounter is unchanged.

---

### Edge Cases

- What happens when the user sets a combatant's name to the same value it already has? The system treats it as a valid update — the encounter state is unchanged but a `CombatantUpdated` event is still emitted.
- What happens when the encounter has no combatants? Editing any id returns a "combatant not found" error.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: System MUST allow updating a combatant's name by providing the combatant's id and a new name.
- **FR-002**: System MUST emit a `CombatantUpdated` event containing the combatant id, old name, and new name upon successful update.
- **FR-003**: System MUST return a "combatant not found" error when the provided id does not match any combatant in the encounter.
- **FR-004**: System MUST return an "invalid name" error when the new name is empty or whitespace-only.
- **FR-005**: System MUST preserve turn order (active index) and round number when a combatant is renamed.
- **FR-006**: System MUST preserve the combatant's position in the combatant list (no reordering).
- **FR-007**: The user interface MUST provide a way to trigger a name edit for each combatant in the encounter.

### Key Entities

- **Combatant**: Identified by a unique id; has a mutable name. Editing updates only the name, preserving identity and list position.
- **CombatantUpdated (event)**: Records that a combatant's name changed. Contains combatant id, old name, and new name.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: Users can rename any combatant in the encounter in a single action.
- **SC-002**: Renaming a combatant never disrupts turn order, active combatant, or round number.
- **SC-003**: Invalid edit attempts (missing combatant, empty name) produce a clear, actionable error message with no side effects.
- **SC-004**: The combatant's updated name is immediately visible in the encounter UI after editing.

## Assumptions

- Name validation follows the same rules as adding a combatant (reject empty and whitespace-only names).
- No uniqueness constraint on combatant names — multiple combatants may share the same name.
- MVP baseline does not include editing other combatant attributes (e.g., initiative score, HP). Only name editing is in scope.
- MVP baseline uses inline editing (click-to-edit input field) as the name editing mechanism. More complex UX (e.g., modal dialogs, undo/redo) is not in the MVP baseline.