initiative/specs/021-bestiary-statblock/spec.md

Feature Specification: Bestiary Search & Stat Block Display

Feature Branch: 021-bestiary-statblock Created: 2026-03-06 Status: Draft Input: User description: "Bestiary creature library with search, stat block display, and combatant prefill from bundled D&D 5e monster data."

User Scenarios & Testing (mandatory)

User Story 1 - Search and Add a Creature from the Bestiary (Priority: P1)

As a DM running an encounter, I want to search for a creature by name in the bestiary so that I can quickly add it as a combatant with its stats pre-filled (name, HP, AC), saving me from manually entering data.

The action bar gains a search icon (magnifying glass). Clicking it opens a search input with autocomplete suggestions filtered from the bundled bestiary. Selecting a creature adds it as a combatant with name, max HP, current HP, and AC pre-filled from the creature's stat block data.

Why this priority: This is the core value proposition — reducing manual data entry when setting up encounters. Without this, the bestiary data has no way to reach the encounter tracker.

Independent Test: Can be fully tested by searching for "Goblin", selecting it, and verifying a combatant appears with the correct name, HP, and AC values from the 2024 Monster Manual.

Acceptance Scenarios:

1. Given the action bar is visible, When the user clicks the search icon, Then a search input appears with focus.
2. Given the search input is open, When the user types "gob", Then a dropdown shows matching creatures (e.g., "Goblin", "Goblin Boss", "Goblin Shaman") filtered from the bestiary.
3. Given search results are showing, When the user selects "Goblin", Then a new combatant is added with name "Goblin", max HP, current HP, and AC matching the Goblin's bestiary entry.
4. Given a combatant named "Goblin" already exists, When the user adds another Goblin from the bestiary, Then the existing combatant is renamed to "Goblin 1" and the new combatant is named "Goblin 2" (auto-numbered).
5. Given an auto-numbered combatant "Goblin 2" exists, When the user edits its name, Then the name updates as usual (renaming is not blocked by auto-numbering).
6. Given the search input is open, When the user types a query with no matches (e.g., "zzzzz"), Then the dropdown shows a "No creatures found" message.
7. Given the search input is open, When the user presses Escape or clicks outside, Then the search closes without adding a combatant.

---

User Story 2 - View Creature Stat Block (Priority: P2)

As a DM, I want to see the full stat block of a creature displayed in a side panel so that I can reference its abilities, actions, and traits during combat without switching to another tool.

When a creature is selected from the bestiary search or when clicking a bestiary-linked combatant in the tracker, a stat block panel appears beside the encounter tracker showing the creature's full information in the classic D&D stat block layout.

Why this priority: The stat block display is the primary reference tool during combat. It transforms the app from just an initiative tracker into a combat management tool.

Independent Test: Can be tested by selecting any creature and verifying all stat block sections render correctly with accurate data from the bestiary.

Acceptance Scenarios:

1. Given a creature is selected from the bestiary search, When the stat block panel opens, Then it displays: name, size, type, alignment, AC, HP (average and formula), speed, ability scores with modifiers, saving throws, skills, damage resistances/immunities, condition immunities, senses, languages, challenge rating, traits, actions, and legendary actions (if applicable).
2. Given the stat block panel is open on desktop (wide viewport), Then the layout is side-by-side: encounter tracker on the left, stat block panel on the right.
3. Given the stat block panel is open on mobile (narrow viewport), Then the stat block appears as a slide-over drawer that can be dismissed.
4. Given a stat block is displayed, When the user clicks a different bestiary-linked combatant in the tracker, Then the stat block panel updates to show that creature's data.
5. Given a stat block is displayed, When the user closes the panel (via close button or gesture), Then the layout returns to the single-column tracker view.
6. Given a creature entry contains markup tags (e.g., spell references, dice notation), Then they render as plain text (e.g., "{@spell fireball|XPHB}" renders as "fireball", "{@dice 3d6}" renders as "3d6").

---

User Story 3 - Quick-Add by Name with Bestiary Suggestions (Priority: P3)

As a DM, I want to see bestiary suggestions while typing a combatant name in the regular add flow, so that I can seamlessly switch between adding a custom-named combatant and pulling stats from the bestiary.

When typing in the existing combatant name input, matching bestiary creatures appear as suggestions. The user can either ignore them and add a plain-named combatant (current behavior) or select a suggestion to get the stat pre-fill.

Why this priority: This enhances the existing add flow without disrupting it. It's a convenience layer on top of P1 and P2.

Independent Test: Can be tested by typing "Dragon" in the name input and verifying suggestions appear, then either selecting one (stats pre-filled) or pressing Enter to add a plain "Dragon" combatant.

Acceptance Scenarios:

1. Given the user is typing in the combatant name input, When the text matches one or more bestiary creature names, Then matching suggestions appear below the input.
2. Given suggestions are visible, When the user selects a suggestion, Then the combatant is added with name, HP, and AC pre-filled from the bestiary.
3. Given suggestions are visible, When the user presses Enter without selecting a suggestion, Then a plain combatant is added with just the typed name (current behavior preserved).
4. Given the user types fewer than 2 characters, Then no suggestions are shown (to avoid overwhelming results).

---

User Story 4 - Responsive Layout Transition (Priority: P4)

As a DM using the app on different devices, I want the layout to adapt between side-by-side (desktop) and drawer (mobile) views so that the stat block is usable regardless of screen size.

Why this priority: The core functionality works on desktop with the side-by-side layout. Mobile adaptation is important for table use but is an enhancement over the desktop experience.

Independent Test: Can be tested by resizing the browser window and verifying the stat block transitions between panel and drawer modes.

Acceptance Scenarios:

1. Given a wide viewport (desktop), When a stat block is open, Then the tracker and stat block display side-by-side.
2. Given a narrow viewport (mobile/tablet), When a stat block is open, Then it appears as a dismissible drawer overlay.
3. Given the viewport is resized from wide to narrow while a stat block is open, Then the layout transitions smoothly from panel to drawer.

---

Edge Cases

• What happens when two creatures from different future bestiary sources share the same name? The source tag is shown alongside the name in search results (e.g., "Goblin (MM 2024)").
• What happens when adding multiple creatures of the same type? Auto-numbering appends an incrementing suffix: "Goblin 1", "Goblin 2", etc. The first instance is renamed to "Goblin 1" when a second is added.
• What happens if the bestiary data fails to load? The app continues to function as a plain initiative tracker; the search icon is hidden or disabled with appropriate feedback.
• How does the stat block handle creatures with no traits or legendary actions? Those sections are simply omitted from the stat block display.
• How does the stat block handle very long content (e.g., a Lich with extensive spellcasting)? The stat block panel scrolls independently of the encounter tracker.

Requirements (mandatory)

Functional Requirements

• FR-001: System MUST bundle the 2024 Monster Manual bestiary data as a static asset shipped with the application.
• FR-002: System MUST normalize raw bestiary data into a consistent internal creature format at load time via an adapter.
• FR-003: System MUST provide a search interface (magnifying glass icon) in the action bar that filters creatures by name substring matching.
• FR-004: Search results MUST appear as the user types, with results updating on each keystroke (or with minimal debounce for performance).
• FR-005: Selecting a creature from search results MUST add a combatant with name, max HP, current HP, and AC pre-filled from the creature's data.
• FR-006: System MUST auto-number duplicate creature names (e.g., "Goblin 1", "Goblin 2") when multiple combatants share the same bestiary creature name.
• FR-007: Auto-numbered names MUST remain editable via the existing rename functionality.
• FR-008: System MUST display a stat block panel showing the full creature information when a creature is selected.
• FR-009: The stat block MUST include: name, size, type, alignment, AC (with armor source if applicable), HP (average + formula), speed, ability scores with modifiers, saving throws, skills, damage vulnerabilities, damage resistances, damage immunities, condition immunities, senses, languages, challenge rating, proficiency bonus, traits, actions, bonus actions, reactions, and legendary actions.
• FR-010: System MUST strip bestiary markup tags (spell references, dice notation, attack tags) and render them as plain readable text.
• FR-011: On wide viewports, the layout MUST be side-by-side with the encounter tracker on the left and stat block on the right.
• FR-012: On narrow viewports, the stat block MUST appear as a dismissible drawer or slide-over.
• FR-013: The existing action bar name input SHOULD show bestiary suggestions as the user types, allowing selection for stat pre-fill or plain entry on Enter.
• FR-014: System MUST support adding more bestiary source files in the future without structural changes, each identified by a source tag.
• FR-015: Combatants added from the bestiary MUST retain a link to their creature data so the stat block can be re-opened from the tracker.

Key Entities

• Creature: A bestiary entry representing a monster or NPC. Key attributes: name, source, size, type, alignment, armor class, hit points (average and formula), speed, ability scores (STR/DEX/CON/INT/WIS/CHA), saving throw bonuses, skill bonuses, damage resistances/immunities, condition immunities, senses, languages, challenge rating, proficiency bonus, traits, actions, legendary actions.
• Bestiary Source: A collection of creatures from a specific publication (e.g., "MM 2024"). Key attributes: source identifier, display name, tag label (e.g., "legacy" for 2014 books).
• Combatant (extended): Existing combatant entity gains an optional reference to a Creature, enabling stat block lookup and stat pre-fill on creation.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Users can search for and add a creature from the bestiary as a combatant in under 5 seconds (type query, select result, combatant appears with stats).
• SC-002: Search results appear within 200ms of typing for the full 2024 Monster Manual dataset (400+ creatures).
• SC-003: All stat block sections render correctly for 100% of creatures in the bundled bestiary (no missing data, no raw markup tags visible).
• SC-004: The stat block panel is readable and fully functional on viewports from 375px (mobile) to 2560px (ultrawide) without horizontal scrolling or content clipping.
• SC-005: Adding a creature from the bestiary pre-fills name, HP, and AC with 100% accuracy relative to the source data.
• SC-006: The existing "quick add by name" flow continues to work identically for users who do not interact with bestiary features (zero regression).