Add Pathfinder 2e game system mode
All checks were successful
CI / check (push) Successful in 2m21s
CI / build-image (push) Successful in 24s

Implements PF2e as an alternative game system alongside D&D 5e/5.5e.
Settings modal "Game System" selector switches conditions, bestiary,
stat block layout, and initiative calculation between systems.

- Valued conditions with increment/decrement UX (Clumsy 2, Frightened 3)
- 2,502 PF2e creatures from bundled search index (77 sources)
- PF2e stat block: level, traits, Perception, Fort/Ref/Will, ability mods
- Perception-based initiative rolling
- System-scoped source cache (D&D and PF2e sources don't collide)
- Backwards-compatible condition rehydration (ConditionId[] → ConditionEntry[])
- Difficulty indicator hidden in PF2e mode (excluded from MVP)

Closes dostulata/initiative#19

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Lukas
2026-04-07 01:26:22 +02:00
parent 8f6eebc43b
commit e62c49434c
67 changed files with 27758 additions and 527 deletions

View File

@@ -23,10 +23,15 @@ interface Combatant {
readonly currentHp?: number; // 0..maxHp
readonly tempHp?: number; // positive integer, damage buffer
readonly ac?: number; // non-negative integer
readonly conditions?: readonly ConditionId[];
readonly conditions?: readonly ConditionEntry[];
readonly isConcentrating?: boolean;
readonly creatureId?: CreatureId; // link to bestiary entry
}
interface ConditionEntry {
readonly id: ConditionId;
readonly value?: number; // PF2e valued conditions (e.g., Clumsy 2); undefined for D&D
}
```
---
@@ -273,21 +278,41 @@ Acceptance scenarios:
3. **Given** a combatant is NOT concentrating, **When** damage is taken, **Then** no pulse/flash occurs.
4. **Given** a concentrating combatant takes damage, **When** the animation completes, **Then** the row returns to its normal concentration-active appearance.
**Story CC-8 — Rules Edition Setting (P2)**
As a DM who plays in both 5e (2014) and 5.5e (2024) groups, I want to choose which edition's condition descriptions appear in tooltips so I reference the correct rules for the game I am running.
**Story CC-8 — Game System Setting (P2)**
As a DM who runs games across D&D 5e, 5.5e, and Pathfinder 2e, I want to choose which game system the tracker uses so that conditions, bestiary search, stat block layout, and initiative calculation all match the game I am running.
Acceptance scenarios:
1. **Given** the user opens the kebab menu, **When** they click "Settings", **Then** a settings modal opens.
2. **Given** the settings modal is open, **When** viewing the Conditions section, **Then** a rules edition selector shows 5e (2014) and 5.5e (2024) with 5.5e selected by default.
3. **Given** the user selects 5e (2014), **When** hovering a condition icon (e.g., Exhaustion), **Then** the tooltip shows the 2014 description.
4. **Given** the user selects 5.5e (2024), **When** hovering the same condition, **Then** the tooltip shows the 2024 description.
5. **Given** the user changes the edition and reloads the page, **Then** the selected edition is preserved.
6. **Given** a condition with identical rules across editions (e.g., Deafened), **Then** the tooltip text is the same regardless of setting.
7. **Given** the settings modal is open, **When** viewing the Theme section, **Then** a System / Light / Dark selector is available, replacing the inline cycle button in the kebab menu.
2. **Given** the settings modal is open, **When** viewing the Game System section, **Then** a selector shows three options: D&D 5e (2014), D&D 5.5e (2024), and Pathfinder 2e, with D&D 5.5e selected by default.
3. **Given** the user selects Pathfinder 2e, **When** viewing condition icons/tooltips, **Then** the PF2e condition set is used (Clumsy, Drained, Enfeebled, etc.) instead of D&D conditions.
4. **Given** the user selects Pathfinder 2e, **When** searching creatures in the bestiary, **Then** results come from the PF2e index (~2,700+ creatures) instead of the D&D index.
5. **Given** the user selects Pathfinder 2e, **When** viewing a creature stat block, **Then** the PF2e layout is shown (level, Fort/Ref/Will, ability modifiers, top/mid/bot ability sections).
6. **Given** the user selects Pathfinder 2e, **When** rolling initiative for a bestiary creature, **Then** Perception is used as the initiative modifier instead of DEX + proficiency.
7. **Given** the user selects D&D 5e (2014), **When** hovering a condition icon (e.g., Exhaustion), **Then** the tooltip shows the 2014 description. **When** 5.5e (2024) is selected, **Then** the tooltip shows the 2024 description.
8. **Given** the user changes the game system and reloads the page, **Then** the selected game system is preserved.
9. **Given** a condition with identical rules across D&D editions (e.g., Deafened), **Then** the tooltip text is the same regardless of D&D edition.
10. **Given** the settings modal is open, **When** viewing the Theme section, **Then** a System / Light / Dark selector is available, replacing the inline cycle button in the kebab menu.
**Story CC-9 — Value-Based Conditions (P2)**
As a DM running a PF2e encounter, I want conditions like Clumsy, Frightened, and Drained to carry an integer value so I can track escalating severity levels as defined by the PF2e rules.
The condition picker uses the same counter pattern as the bestiary batch-add (see `specs/004-bestiary/spec.md`, US-S2): clicking a valued condition shows `[-] N [+] [✓]` controls inline; the user adjusts the value and confirms. Clicking a condition tag on the combatant row decrements the value by 1.
Acceptance scenarios:
1. **Given** the game system is Pathfinder 2e and the condition picker is open, **When** the user clicks an inactive valued condition (e.g., Frightened), **Then** the row shows a counter at value 1 with `[-]`, `[+]`, and `[✓]` (confirm) buttons — the condition is not yet applied.
2. **Given** the counter is showing value 1, **When** the user clicks `[+]` twice, **Then** the counter shows value 3.
3. **Given** the counter is showing a value, **When** the user clicks `[✓]` (confirm), **Then** the condition is applied at that value and its icon appears inline with the value as a badge.
4. **Given** a combatant already has Frightened 2 and the picker is open, **When** the user clicks Frightened in the picker, **Then** the counter shows pre-filled at value 2 for adjustment.
5. **Given** a combatant has Frightened 2, **When** the user clicks the Frightened icon tag on the row, **Then** the value decrements to 1.
6. **Given** a combatant has Frightened 1, **When** the user clicks the Frightened icon tag on the row, **Then** the condition is removed entirely.
7. **Given** a PF2e condition that is not valued (e.g., Prone, Off-Guard), **When** the user clicks it in the picker, **Then** it toggles on/off with no counter or value badge — identical to D&D condition behavior.
8. **Given** the game system is D&D (5e or 5.5e), **When** interacting with conditions, **Then** no value counters or badges are shown and conditions toggle on/off as before.
9. **Given** a combatant has Clumsy 3, **When** the user hovers over the condition icon, **Then** the tooltip shows the condition name, the current value, and the PF2e rules description.
10. **Given** a valued condition counter is showing, **When** the user clicks a different valued condition, **Then** the previous counter is replaced (only one counter at a time).
### Requirements
- **FR-032**: The MVP MUST support the following 15 standard D&D 5e/5.5e conditions: blinded, charmed, deafened, exhaustion, frightened, grappled, incapacitated, invisible, paralyzed, petrified, poisoned, prone, restrained, stunned, unconscious.
- **FR-032**: When a D&D game system is active, the system MUST support the following 15 standard D&D 5e/5.5e conditions: blinded, charmed, deafened, exhaustion, frightened, grappled, incapacitated, invisible, paralyzed, petrified, poisoned, prone, restrained, stunned, unconscious. When Pathfinder 2e is active, the system MUST support the PF2e condition set (see FR-103).
- **FR-033**: Each condition MUST have a fixed icon and color mapping (Lucide icons; no emoji):
| Condition | Icon | Color |
@@ -312,9 +337,9 @@ Acceptance scenarios:
- **FR-035**: Conditions MUST be displayed in the fixed definition order (blinded -> unconscious), regardless of application order.
- **FR-036**: The "+" condition button MUST be hidden by default and appear only on row hover (or touch/focus on touch devices).
- **FR-037**: Clicking "+" MUST open the compact condition picker showing all conditions as icon + label pairs.
- **FR-038**: Clicking a condition in the picker MUST toggle it on or off.
- **FR-039**: Clicking an active condition icon tag in the row MUST remove that condition.
- **FR-040**: Hovering an active condition icon MUST show a tooltip with the condition name and its rules description for the selected edition.
- **FR-038**: Clicking a condition in the picker MUST toggle it on or off. For PF2e valued conditions, clicking MUST open an inline counter (same pattern as the bestiary batch-add count badge: `[-] N [+] [✓]`) instead of toggling immediately. The user adjusts the value and confirms with the `[✓]` button. Only one valued condition counter may be open at a time.
- **FR-039**: For D&D conditions, clicking an active condition icon tag in the row MUST remove that condition. For PF2e valued conditions, clicking MUST decrement the value by 1; the condition is removed when the value reaches 0. For PF2e non-valued conditions, clicking removes the condition.
- **FR-040**: Hovering an active condition icon MUST show a tooltip with the condition name and its rules description for the active game system. For PF2e valued conditions, the tooltip MUST also display the current value (e.g., "Frightened 2").
- **FR-041**: Condition icons MUST NOT increase the row's width; row height MAY increase to accommodate wrapping.
- **FR-042**: The condition picker MUST close when the user clicks outside of it.
- **FR-043**: Conditions MUST persist as part of combatant state (surviving page reload).
@@ -330,6 +355,11 @@ Acceptance scenarios:
- **FR-053**: When a concentrating combatant takes damage, the Brain icon and row accent MUST briefly pulse/flash for 700 ms.
- **FR-054**: The pulse animation MUST NOT trigger on healing or when concentration is inactive.
- **FR-055**: Concentration MUST persist across page reloads via existing storage.
- **FR-103**: When Pathfinder 2e is active, the system MUST support the following PF2e conditions: blinded, clumsy (valued), concealed, confused, controlled, dazzled, deafened, doomed (valued), drained (valued), dying (valued), enfeebled (valued), fascinated, fatigued, fleeing, frightened (valued), grabbed, hidden, immobilized, off-guard, paralyzed, petrified, prone, quickened, restrained, sickened (valued), slowed (valued), stunned (valued), stupefied (valued), unconscious, undetected, wounded (valued).
- **FR-104**: Each PF2e condition MUST have a fixed icon and color mapping (Lucide icons; no emoji). The icon/color table for PF2e conditions is defined separately from the D&D table (FR-033).
- **FR-105**: For PF2e valued conditions, the condition icon tag MUST display the current value as a small numeric badge (e.g., "2" next to the Frightened icon). Non-valued PF2e conditions display without a badge.
- **FR-106**: The condition data model MUST use `ConditionEntry` objects (`{ id: ConditionId, value?: number }`) instead of bare `ConditionId` values. D&D conditions MUST be stored without a `value` field (backwards-compatible).
- **FR-107**: Switching the game system MUST NOT clear existing combatant conditions. Conditions from the previous game system that are not valid in the new system remain stored but are hidden from display until the user switches back.
### Edge Cases
@@ -340,9 +370,13 @@ Acceptance scenarios:
- When concentration is toggled during an active pulse animation, the animation cancels and the new state applies immediately.
- Multiple combatants may concentrate simultaneously; concentration is independent per combatant.
- Conditions have no mechanical effects in the MVP baseline (no auto-disadvantage, no automation).
- When the rules edition preference is missing from localStorage, the system defaults to 5.5e (2024).
- Changing the edition while a condition tooltip is visible updates the tooltip on next hover (no live update required).
- When the game system preference is missing from localStorage, the system defaults to D&D 5.5e (2024).
- Changing the game system while a condition tooltip is visible updates the tooltip on next hover (no live update required).
- The settings modal is app-level UI; it does not interact with encounter state.
- When the game system is switched from D&D to PF2e, existing D&D conditions on combatants are hidden (not deleted). Switching back to D&D restores them.
- PF2e valued condition at value 0 is treated as removed — it MUST NOT appear on the row.
- Dying 4 in PF2e has special mechanical significance (death), but the system does not enforce this automatically — it displays the value only.
- Persistent damage is excluded from the PF2e MVP condition set. It can be added as a follow-up feature.
---
@@ -410,12 +444,12 @@ Acceptance scenarios:
- **FR-066**: System MUST display a d20 icon button in the initiative slot for every combatant that has a linked bestiary creature and does not yet have an initiative value.
- **FR-067**: System MUST NOT display the d20 button for combatants without a linked bestiary creature; they see a "--" placeholder that is clickable to type a value.
- **FR-068**: When the d20 button is clicked, the system MUST generate a uniform random integer in [1, 20], add the creature's initiative modifier, and set the result as the initiative value.
- **FR-069**: The initiative modifier MUST be calculated as: DEX modifier + (proficiency multiplier x proficiency bonus), where DEX modifier = floor((DEX - 10) / 2) and proficiency bonus is derived from challenge rating.
- **FR-069**: For D&D creatures, the initiative modifier MUST be calculated as: DEX modifier + (proficiency multiplier x proficiency bonus), where DEX modifier = floor((DEX - 10) / 2) and proficiency bonus is derived from challenge rating. For PF2e creatures, the initiative modifier MUST be the creature's Perception value from the index.
- **FR-070**: The initiative proficiency multiplier MUST be read from `initiative.proficiency` in bestiary data (0 if absent, 1 for proficiency, 2 for expertise).
- **FR-071**: System MUST provide a "Roll All Initiative" button in the top bar. Clicking it MUST roll for every bestiary-linked combatant that does not already have an initiative value; all others MUST be left unchanged.
- **FR-072**: After any initiative roll (single or batch), the encounter list MUST re-sort descending per existing behavior.
- **FR-073**: Once a combatant has an initiative value, the d20 button is replaced by the value as plain text using a click-to-edit pattern (consistent with AC and name editing).
- **FR-074**: The stat block header MUST display initiative in the format "Initiative +X (Y)" where X is the modifier (with + or - sign) and Y = 10 + X.
- **FR-074**: For D&D creatures, the stat block header MUST display initiative in the format "Initiative +X (Y)" where X is the modifier (with + or - sign) and Y = 10 + X. For PF2e creatures, the stat block MUST display "Perception +X" where X is the Perception modifier.
- **FR-075**: The initiative display in the stat block MUST be positioned adjacent to the AC value, matching Monster Manual 2024 layout.
- **FR-076**: No initiative line MUST be shown in the stat block for combatants without bestiary data.
- **FR-077**: The initiative display in the stat block is display-only. It MUST NOT modify encounter turn order or trigger rolling automatically.
@@ -489,11 +523,11 @@ Acceptance scenarios:
- **FR-093**: All interactive elements in the row MUST remain keyboard-accessible (focusable and operable via keyboard).
- **FR-094**: On touch devices, hover-only controls ("+" button, "x" button) MUST remain accessible via tap or focus.
- **FR-095**: The system MUST provide a settings modal accessible via a "Settings" item in the kebab overflow menu.
- **FR-096**: The settings modal MUST include a Conditions section with a rules edition selector offering two options: 5e (2014) and 5.5e (2024).
- **FR-097**: The default rules edition MUST be 5.5e (2024).
- **FR-098**: Each condition definition MUST carry a description for both editions. Conditions with identical rules across editions MAY share a single description value.
- **FR-099**: Condition tooltips MUST display the description corresponding to the active rules edition preference.
- **FR-100**: The rules edition preference MUST persist across sessions via localStorage (key `"initiative:rules-edition"`).
- **FR-096**: The settings modal MUST include a Game System section with a selector offering three options: D&D 5e (2014), D&D 5.5e (2024), and Pathfinder 2e. The label MUST read "Game System" (not "Conditions" or "Rules Edition").
- **FR-097**: The default game system MUST be D&D 5.5e (2024).
- **FR-098**: Each D&D condition definition MUST carry a description for both D&D editions. Each PF2e condition definition MUST carry a PF2e rules description. Conditions with identical rules across D&D editions MAY share a single description value.
- **FR-099**: Condition tooltips MUST display the description corresponding to the active game system. For D&D game systems, the tooltip uses the edition-specific description. For PF2e, the tooltip uses the PF2e description.
- **FR-100**: The game system preference MUST persist across sessions via localStorage (key `"initiative:game-system"`).
- **FR-101**: The settings modal MUST include a Theme section with System / Light / Dark options, replacing the inline theme cycle button in the kebab menu.
- **FR-102**: The settings modal MUST close on Escape, click-outside, or the close button.
@@ -539,6 +573,10 @@ Acceptance scenarios:
- **SC-028**: The AC number is visually identifiable as armor class through the shield shape alone.
- **SC-029**: No layout shift occurs when hovering/unhovering rows.
- **SC-030**: All HP, AC, initiative, condition, and concentration interactions remain fully operable using only a keyboard.
- **SC-031**: The user can switch rules edition in 2 interactions (open settings → select edition).
- **SC-032**: Condition tooltips accurately reflect the selected edition's rules text for all conditions that differ between editions.
- **SC-033**: The rules edition preference survives a full page reload.
- **SC-031**: The user can switch game system in 2 interactions (open settings → select system).
- **SC-032**: Condition tooltips accurately reflect the active game system's rules text for all conditions.
- **SC-033**: The game system preference survives a full page reload.
- **SC-034**: All PF2e conditions are available and visually distinguishable by icon and color when PF2e is the active game system.
- **SC-035**: PF2e valued conditions display their current value and can be incremented/decremented within 1 click each.
- **SC-036**: Switching game system immediately changes the available conditions, bestiary search results, stat block layout, and initiative calculation — no page reload required.
- **SC-037**: The game system preference survives a full page reload.

View File

@@ -8,9 +8,11 @@
## Overview
The Bestiary feature provides creature search across a pre-indexed library of 3,312+ creatures from 102+ D&D sources, stat block display for full creature reference during combat, source data management via on-demand fetch or file upload, and a dual-panel UX with collapse/expand and pin capabilities. Creatures can be added individually or in batch from a search dropdown, with stats pre-filled from the index.
The Bestiary feature provides creature search across pre-indexed creature libraries: 3,312+ D&D creatures from 102+ sources and ~2,700+ Pathfinder 2e creatures from 79 Pf2eTools sources. The active game system setting (see `specs/003-combatant-state/spec.md`, FR-096) determines which index the search operates against. Stat block display, source management, and creature pre-fill all adapt to the active game system.
The architecture uses a two-tier design: a lightweight search index (`data/bestiary/index.json`) shipped with the app containing mechanical facts for all creatures, and full stat block data loaded on-demand at the source level, normalized, and cached in IndexedDB.
The feature also includes full creature reference via stat block display during combat, source data management via on-demand fetch or file upload, and a dual-panel UX with collapse/expand and pin capabilities. Creatures can be added individually or in batch from a search dropdown, with stats pre-filled from the index.
The architecture uses a two-tier design: lightweight search indexes shipped with the app (one per game system) containing mechanical facts for all creatures, and full stat block data loaded on-demand at the source level, normalized, and cached in IndexedDB.
**Structure**: This spec is organized by topic area. Each topic section contains its own user scenarios, requirements, and edge cases.
@@ -37,11 +39,11 @@ When the search input has no bestiary matches (or fewer than 2 characters typed)
### Requirements
- **FR-001**: The app MUST ship a pre-generated search index (`data/bestiary/index.json`) containing creature name, source code, AC, HP average, DEX score, CR, initiative proficiency multiplier, size code, and creature type for all indexed creatures.
- **FR-001**: The app MUST ship pre-generated search indexes for each supported game system. The D&D index (`data/bestiary/index.json`) MUST contain creature name, source code, AC, HP average, DEX score, CR, initiative proficiency multiplier, size code, and creature type. The PF2e index (`data/bestiary/pf2e-index.json`) MUST contain creature name, source code, AC, HP, level, Perception modifier, size, and creature type.
- **FR-002**: The app MUST include a source display name map translating source codes to human-readable names (e.g., "XMM" -> "Monster Manual (2025)").
- **FR-003**: Search MUST operate against the full shipped index — case-insensitive substring match on creature name, minimum 2 characters, maximum 10 results, sorted alphabetically.
- **FR-003**: Search MUST operate against the shipped index corresponding to the active game system — case-insensitive substring match on creature name, minimum 2 characters, maximum 10 results, sorted alphabetically.
- **FR-004**: Search results MUST display the source display name alongside the creature name.
- **FR-005**: Adding a creature from search MUST populate name, HP, AC, and initiative data directly from the index without any network fetch.
- **FR-005**: Adding a creature from search MUST populate name, HP, AC, and initiative data directly from the index without any network fetch. For D&D creatures, initiative data is the DEX-based modifier. For PF2e creatures, initiative data is the Perception modifier.
- **FR-006**: The system MUST auto-number duplicate creature names (e.g., "Goblin 1", "Goblin 2") when multiple combatants share the same bestiary creature name. When a second copy is added, the existing combatant is renamed to include the suffix.
- **FR-007**: Auto-numbered names MUST remain editable via the existing rename functionality.
- **FR-008**: Combatants added from the bestiary MUST retain a link (`creatureId`) to their creature data so the stat block can be re-opened from the tracker.
@@ -67,6 +69,8 @@ When the search input has no bestiary matches (or fewer than 2 characters typed)
10. **Given** the user types a name with no bestiary match, **When** the dropdown shows no results, **Then** optional input fields for initiative, AC, and max HP appear with visible labels.
11. **Given** the optional fields are visible, **When** the user leaves all optional fields empty and submits, **Then** the creature is added with only the name (no stats pre-filled).
12. **Given** the search input is open, **When** the user presses Escape, **Then** the search closes without adding a combatant.
13. **Given** the game system is Pathfinder 2e, **When** the DM types "abo" in the search field, **Then** results show PF2e creatures (e.g., "Aboleth (Bestiary 1)") from the PF2e index, not D&D creatures.
14. **Given** the game system is Pathfinder 2e, **When** the DM selects a PF2e creature, **Then** a combatant is added with name, HP, AC, and Perception as the initiative modifier.
### Edge Cases
@@ -97,7 +101,7 @@ As a DM using the app on different devices, I want the layout to adapt between s
### Requirements
- **FR-016**: The system MUST display a stat block panel with full creature information when a creature is selected.
- **FR-017**: 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, passive perception, traits, actions, bonus actions, reactions, spellcasting, and legendary actions.
- **FR-017**: For D&D creatures, 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, passive perception, traits, actions, bonus actions, reactions, spellcasting, and legendary actions. For PF2e creatures, the stat block MUST include: name, level, traits (as tags), Perception and senses, languages, skills, ability modifiers (Str/Dex/Con/Int/Wis/Cha as modifiers, not scores), items, AC, saving throws (Fort/Ref/Will), HP (with optional immunities/resistances/weaknesses), speed, attacks, top abilities, mid abilities (reactions/auras), bot abilities (active), and spellcasting.
- **FR-018**: Optional stat block sections (traits, legendary actions, bonus actions, reactions, etc.) MUST be omitted entirely when the creature has none.
- **FR-019**: The system MUST strip bestiary markup tags (spell references, dice notation, attack tags) and render them as plain readable text (e.g., `{@spell fireball|XPHB}` -> "fireball", `{@dice 3d6}` -> "3d6").
- **FR-020**: On wide viewports (desktop), the layout MUST be side-by-side with the encounter tracker on the left and stat block on the right.
@@ -105,6 +109,12 @@ As a DM using the app on different devices, I want the layout to adapt between s
- **FR-022**: The stat block panel MUST scroll independently of the encounter tracker.
- **FR-023**: When the user clicks the book icon on a different bestiary-linked combatant row, the stat block panel MUST update to show that creature's data.
- **FR-024**: The existing search/view button MUST be repurposed to open the stat block for the currently focused/selected creature in the dropdown.
- **FR-063**: The stat block renderer MUST select the appropriate layout (D&D or PF2e) based on the creature's game system. The creature's game system is determined by the index it was added from.
- **FR-064**: PF2e stat blocks MUST display level in place of challenge rating. Level MUST appear in the stat block header.
- **FR-065**: PF2e stat blocks MUST display three saving throws (Fortitude, Reflex, Will) instead of D&D's six ability-based saves.
- **FR-066**: PF2e stat blocks MUST display ability modifiers directly (e.g., "Str +4") rather than ability scores with derived modifiers.
- **FR-067**: PF2e stat blocks MUST organize abilities into three sections: top (above defenses), mid (reactions and auras), and bot (active abilities), matching the Pf2eTools source structure.
- **FR-068**: PF2e stat blocks MUST strip Pf2eTools markup tags (e.g., `{@damage 1d8+7}`, `{@condition frightened}`) and render them as plain readable text, using the same tag-stripping approach as D&D (FR-019).
- **FR-062**: Bestiary-linked combatant rows MUST display a small book icon (Lucide `BookOpen`) as the dedicated stat block trigger. The icon MUST have a tooltip ("View stat block") and an `aria-label="View stat block"` for accessibility. The book icon is the only way to manually open a stat block from the tracker — clicking the combatant name always enters inline rename mode. Non-bestiary combatant rows MUST NOT display the book icon.
### Acceptance Scenarios
@@ -119,6 +129,8 @@ As a DM using the app on different devices, I want the layout to adapt between s
8. **Given** a bestiary-linked combatant row is visible, **When** the user looks at the row, **Then** a small book icon is visible as the stat block trigger with a tooltip "View stat block".
9. **Given** a custom (non-bestiary) combatant row is visible, **When** the user looks at the row, **Then** no book icon is displayed.
10. **Given** a bestiary-linked combatant row is visible, **When** the user clicks the combatant's name, **Then** inline rename mode is entered — the stat block does NOT open.
11. **Given** a PF2e creature is selected, **When** the stat block opens, **Then** it displays: name, level, traits as tags, Perception, senses, languages, skills, ability modifiers, AC, Fort/Ref/Will saves, HP, speed, attacks, abilities (top/mid/bot sections), and spellcasting (if applicable). No CR, no ability scores, no legendary actions.
12. **Given** a PF2e creature with conditional AC (e.g., "with shield raised"), **When** viewing the stat block, **Then** both the standard AC and conditional AC are shown.
### Edge Cases
@@ -164,7 +176,7 @@ A DM wants to see which sources are cached, find a specific source, clear a spec
- **FR-034**: An import button (Lucide Import icon) in the top bar MUST open the stat block side panel with the bulk import prompt.
- **FR-035**: The bulk import prompt MUST show a descriptive text explaining the operation, including approximate data volume (~12.5 MB) and the dynamic number of sources derived from the bestiary index at runtime.
- **FR-036**: The system MUST pre-fill a base URL that the user can edit.
- **FR-037**: The system MUST construct individual fetch URLs by appending `bestiary-{sourceCode}.json` to the base URL for each source.
- **FR-037**: The system MUST construct individual fetch URLs by appending the appropriate filename pattern to the base URL: `bestiary-{sourceCode}.json` for D&D sources, `creatures-{sourceCode}.json` for PF2e sources (matching the Pf2eTools naming convention).
- **FR-038**: All fetch requests during bulk import MUST fire concurrently (browser handles connection pooling).
- **FR-039**: Already-cached sources MUST be skipped during bulk import.
- **FR-040**: The system MUST show a text counter ("Loading sources... N/T") and progress bar during bulk import.
@@ -177,6 +189,10 @@ A DM wants to see which sources are cached, find a specific source, clear a spec
- **FR-047**: The app MUST provide a management UI showing cached sources with a filter input for searching by display name and options to clear individual sources or all cached data.
- **FR-048**: The normalization adapter and tag-stripping utility MUST remain the canonical pipeline for all fetched and uploaded data.
- **FR-049**: The distributed app bundle MUST contain zero copyrighted prose content — only mechanical facts and creature names in the search index.
- **FR-069**: The system MUST use a separate normalization pipeline for PF2e source data, mapping the Pf2eTools JSON structure to the PF2e creature type. Both pipelines (D&D and PF2e) MUST use the canonical tag-stripping utility.
- **FR-070**: The source cache MUST be scoped by game system. D&D and PF2e sources MUST NOT collide in IndexedDB (e.g., both may have a source code "B1" but they are different sources).
- **FR-071**: The bulk import prompt MUST adapt to the active game system: showing the correct source count, base URL (Pf2eTools for PF2e, 5etools for D&D), and approximate data volume for the active system.
- **FR-072**: The source management UI MUST show only sources for the active game system.
### Acceptance Scenarios
@@ -199,6 +215,8 @@ A DM wants to see which sources are cached, find a specific source, clear a spec
17. **Given** the source management UI is open, **When** the DM clears a single source, **Then** that source's data is removed; stat blocks for its creatures require re-fetching, while other cached sources remain.
18. **Given** the source management UI is open, **When** the DM clears all cached data, **Then** all source data is removed and all stat blocks require re-fetching.
19. **Given** many sources are cached, **When** the DM types a partial name in the filter input, **Then** only sources whose display name matches (case-insensitive) are shown.
20. **Given** the game system is Pathfinder 2e, **When** the user clicks the import button, **Then** the bulk import prompt shows the PF2e source count (~79), a Pf2eTools-based URL, and a PF2e-appropriate data volume estimate.
21. **Given** the game system is Pathfinder 2e and a PF2e source is cached, **When** the user opens a PF2e creature's stat block from that source, **Then** the PF2e stat block renders correctly from cached data.
### Edge Cases
@@ -273,8 +291,9 @@ As a DM with a creature pinned, I want to collapse the right (browse) panel inde
## Key Entities
- **Search Index** (`BestiaryIndex`): Pre-shipped lightweight dataset keyed by name + source, containing mechanical facts (name, source code, AC, HP average, DEX score, CR, initiative proficiency multiplier, size, type) for all creatures. Sufficient for adding combatants; insufficient for rendering a full stat block.
- **Source** (`BestiarySource`): A D&D publication identified by a code (e.g., "XMM") with a display name (e.g., "Monster Manual (2025)"). Caching and fetching operate at the source level.
- **Search Index (D&D)** (`BestiaryIndex`): Pre-shipped lightweight dataset keyed by name + source, containing mechanical facts (name, source code, AC, HP average, DEX score, CR, initiative proficiency multiplier, size, type) for all creatures. Sufficient for adding combatants; insufficient for rendering a full stat block.
- **Search Index (PF2e)** (`Pf2eBestiaryIndex`): Pre-shipped lightweight dataset for PF2e creatures, containing name, source code, AC, HP, level, Perception modifier, size, and creature type. Parallel to the D&D search index but with PF2e-specific fields (level instead of CR, Perception instead of DEX/proficiency).
- **Source** (`BestiarySource`): A D&D or PF2e publication identified by a code (e.g., "XMM") with a display name (e.g., "Monster Manual (2025)"). Caching and fetching operate at the source level.
- **Creature (Full)** (`Creature`): A complete creature record with all stat block data (traits, actions, legendary actions, spellcasting, etc.), available only after source data is fetched/uploaded and cached. Identified by a branded `CreatureId`.
- **Cached Source Data**: The full normalized bestiary data for a single source, stored in IndexedDB. Contains complete creature stat blocks.
- **Combatant** (extended): Gains an optional `creatureId` reference to a `Creature`, enabling stat block lookup and stat pre-fill on creation.
@@ -287,7 +306,7 @@ As a DM with a creature pinned, I want to collapse the right (browse) panel inde
## Success Criteria *(mandatory)*
- **SC-001**: All 3,312+ indexed creatures are searchable immediately on app load, with search results appearing within 100ms of typing.
- **SC-001**: All indexed creatures for the active game system (3,312+ D&D or ~2,700+ PF2e) are searchable immediately on app load, with search results appearing within 100ms of typing.
- **SC-002**: Adding a creature from search to the encounter completes without any network request and within 200ms.
- **SC-003**: After a source is cached, stat blocks for any creature from that source display within 200ms with no additional prompt.
- **SC-004**: The distributed app bundle contains zero copyrighted prose content — only mechanical facts and creature names in the search index.
@@ -304,3 +323,7 @@ As a DM with a creature pinned, I want to collapse the right (browse) panel inde
- **SC-015**: Users can pin a creature and browse a different creature's stat block simultaneously, without any additional navigation steps.
- **SC-016**: The pinned panel is never visible on screens narrower than the dual-panel breakpoint, ensuring mobile usability is not degraded.
- **SC-017**: All collapse/expand and pin/unpin interactions are discoverable through visible button controls without requiring documentation or tooltips.
- **SC-018**: All ~2,700+ PF2e indexed creatures are searchable when PF2e is the active game system, with search results appearing within 100ms of typing.
- **SC-019**: PF2e stat blocks render the correct layout (level, three saves, ability modifiers, ability sections) for all PF2e creatures — no D&D-specific fields (CR, ability scores, legendary actions) are shown.
- **SC-020**: Switching game system immediately changes which creatures appear in search — no page reload required.
- **SC-021**: Both D&D and PF2e search indexes ship bundled with the app; no network fetch is required to search creatures in either system.