612 lines
30 KiB
Markdown
612 lines
30 KiB
Markdown
# Ravenous Roll20 feature catalogue
|
||
|
||
## How to use this document
|
||
|
||
This is the portable product specification for the repository. Use it when an
|
||
equivalent feature must be implemented in another project, even if that project
|
||
uses a different language, framework, or directory layout. Each feature states
|
||
observable behavior, invariants, source-of-truth inputs, the implementation in
|
||
this repository, and acceptance criteria.
|
||
|
||
This document deliberately does not duplicate every attribute or function.
|
||
Those integration details live in [ARCHITECTURE.md](ARCHITECTURE.md). The pinned
|
||
`ravenous_typst` submodule is authoritative for game rules and source data. If
|
||
this document and the book disagree, verify the pinned book and update this
|
||
document rather than preserving an accidental implementation detail.
|
||
|
||
Feature status terms:
|
||
|
||
- **Implemented** means the code and local automated checks exist.
|
||
- **Roll20-verified** means the interaction has also been exercised in Roll20.
|
||
- **Manual by design** means the sheet presents or calculates information but
|
||
intentionally does not mutate the corresponding resource.
|
||
- **Pending smoke test** means local mocks cover the logic but the remaining
|
||
real-platform scenarios are tracked in [TASKS.md](TASKS.md).
|
||
|
||
## Product boundary
|
||
|
||
The product is a French Ravenous character-management suite with four parts:
|
||
|
||
1. a generated Roll20 Custom Sheet Enhancement (CSE) character sheet;
|
||
2. optional Roll20 Mod scripts for validated JSON exchange and cross-character
|
||
actions;
|
||
3. deterministic converters and example-payload generators;
|
||
4. two dependency-free static companion sites for crafting and reusable
|
||
effects.
|
||
|
||
The suite assists play; it is not an autonomous rules engine. HP, armor
|
||
integrity, technique costs, consumable quantities, and mechanical consequences
|
||
of effects remain manual unless a future feature explicitly changes that
|
||
decision.
|
||
|
||
## F01 — Book-driven deterministic sheet build
|
||
|
||
**Status:** Implemented.
|
||
|
||
**Outcome.** Generate a deployable Roll20 bundle from hand-maintained templates
|
||
and the pinned Ravenous rulebook data. A rebuild with identical inputs produces
|
||
byte-identical output, and a check mode detects stale artifacts.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- Read skills, nested specializations, school techniques, origins, powers,
|
||
glossary labels, build limits, trigrams, and themes from the pinned book.
|
||
- Import only school tiers strictly below `build.max_tier_exclusive`.
|
||
- Exclude resistance definitions from the generated skill list because the
|
||
sheet models them as dedicated resistance fields.
|
||
- Translate only the supported Typst subset. Resolve known references and
|
||
macros; do not silently invent semantics for unsupported game markup.
|
||
- Escape generated HTML and JavaScript safely, prevent literal `</script>`
|
||
termination, and keep generated JavaScript data split over bounded lines for
|
||
the Roll20 editor.
|
||
- Fail if an uppercase template marker remains unresolved.
|
||
- Emit the HTML, CSS, translations, manifest, and a build manifest containing
|
||
source counts, selected limits/theme, a theme list, and a content hash.
|
||
- `--check` compares expected generated content without rewriting it.
|
||
|
||
**This repository:** `tools/build.py`, `src/ravenous.html`, `src/ravenous.css`,
|
||
`src/translation.json`, `src/sheet.json`, and `scripts/build.sh`. Generated
|
||
artifacts belong in `build/` and are never edited directly.
|
||
|
||
**Acceptance:** build twice and compare bytes; run `./scripts/build.sh --check`;
|
||
verify the expected source counts and absence of unresolved markers/raw known
|
||
Typst constructs with `tests/test_build.py`.
|
||
|
||
## F02 — Responsive, persistent, themed character sheet shell
|
||
|
||
**Status:** Implemented; themes are Roll20-verified.
|
||
|
||
**Outcome.** Present the character through eight compact pages: Chasseur,
|
||
Compétences, Combat, Santé & résistances, Cuisine & alchimie, Écoles, Pouvoirs,
|
||
and Effets & tours. Navigation and user choices persist as Roll20 attributes.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- Use Roll20 CSE mode with Legacy Sanitization disabled.
|
||
- Keep tabs in one sheet document and switch them through a persisted hidden
|
||
`tab` attribute and action buttons; do not rely on page reloads.
|
||
- Adapt grids for narrower screens without dropping fields.
|
||
- Generate all palettes from the book theme file. Persist the per-character
|
||
theme and apply it to both the sheet and chat cards.
|
||
- Permit a build-time initial/fallback UI theme without removing other themes.
|
||
- Retain readable system font fallbacks when the optional Google font cannot
|
||
load.
|
||
- Include public/GM-only roll selection and compact JSON exchange shortcuts in
|
||
the header.
|
||
|
||
**This repository:** page markup and sheet workers are in `src/ravenous.html`;
|
||
responsive styles and CSS custom properties are in `src/ravenous.css`; palette
|
||
parsing and generated selectors/rules are in `tools/build.py`.
|
||
|
||
**Acceptance:** switch every page, reopen the sheet, select at least two themes,
|
||
and inspect both sheet and chat output at desktop and narrow widths. Confirm all
|
||
book palettes occur in the generated selector and CSS.
|
||
|
||
## F03 — Character characteristics, resources, and derived values
|
||
|
||
**Status:** Implemented; core calculations are Roll20-verified.
|
||
|
||
**Outcome.** Track eight characteristics, temporary modifiers, resources, and
|
||
derived movement/health statistics with immediate worker recalculation.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- Track Force, Agilité, Perception, Intelligence, Volonté, Psy, Chance, and
|
||
Charisme as permanent values plus temporary modifiers and displayed totals.
|
||
- Calculate derived statistics from permanent characteristics and explicit
|
||
derived-value modifiers. Temporary characteristic modifiers affect final
|
||
characteristics and skill totals, but not derived base formulas.
|
||
- Track current and maximum Jauge, Fatigue, Toxicité, Satiété, Sang, and Actions
|
||
as appropriate; maximum formulas can have explicit modifiers.
|
||
- Recalculate on sheet open and every governing input change using silent
|
||
writes where cascading events would otherwise loop.
|
||
- Preserve stable attribute names because existing Roll20 characters store
|
||
state under those names.
|
||
|
||
**This repository:** fixed fields and the `recalculate` worker in
|
||
`src/ravenous.html`; formula assertions in `tests/test_build.py` and behavior
|
||
checks in `tests/test_worker.mjs`.
|
||
|
||
**Acceptance:** test base and temporary changes independently, all max-value
|
||
modifiers, stage boundaries, and sheet reopen. Compare formulas with the pinned
|
||
rulebook before porting them.
|
||
|
||
## F04 — Generated and custom skills with roll outcomes
|
||
|
||
**Status:** Implemented; critical-failure boundary awaits Roll20 retest.
|
||
|
||
**Outcome.** Expose every sheet-visible book skill in category subtabs, support
|
||
nested specializations and custom skills, and resolve single-die threshold
|
||
checks into an outcome and margin.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- Generate stable skill IDs and distinct stored attributes. Nested entries
|
||
inherit their parent characteristic, include ancestry in their ID/full name,
|
||
and appear indented under the parent.
|
||
- Allow the characteristic association, rank, and temporary modifier to
|
||
contribute to a skill total. The generated internal `effect` slot is
|
||
currently reserved and remains zero; do not claim active-effect automation.
|
||
- Custom repeating skills choose a characteristic and use the same total and
|
||
roll semantics.
|
||
- Let users select the die size. A roll is a critical success on natural 1, a
|
||
critical failure on the maximum face, a normal success below the threshold,
|
||
and otherwise a failure. Margin is `threshold - rolled`.
|
||
- Respect the character's public/secret-roll choice.
|
||
|
||
**This repository:** skill normalization and HTML generation in
|
||
`tools/build.py`; totals and `performSkillRoll` in `src/ravenous.html`.
|
||
|
||
**Acceptance:** verify unique IDs, category membership, nested indentation,
|
||
custom-row persistence, and rolls at natural 1, just below threshold, exactly
|
||
at threshold, and the maximum die face for both public and secret settings.
|
||
|
||
## F05 — Attack, defense, damage, and mitigation workflow
|
||
|
||
**Status:** Implemented locally; targeted-token edge cases remain a pending
|
||
Roll20 smoke test.
|
||
|
||
**Outcome.** Model arbitrary attacks as repeating rows, roll successes, offer
|
||
chat follow-ups for defense and damage, and show damage/armor-break results
|
||
after a targeted defender's selected mitigations.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- An attack stores name, default pool, threshold, temporary threshold modifier,
|
||
optional automatic successes, whether dice are rolled, base damage, damage
|
||
per extra success, armor break, maximum counted successes, three defense
|
||
thresholds, and notes.
|
||
- Attack dice count successes against the attack threshold and add automatic
|
||
successes. Follow-up context is cached by the original roll ID when available.
|
||
- Defense prompts for a defender token and a defense type. Dodge and parry add
|
||
only the targeted defender's corresponding skill and temporary skill value
|
||
to the attack's defense threshold; reposition uses its fixed threshold.
|
||
- After defense, remaining successes are clamped to zero and capped by RMax.
|
||
Zero final successes deal zero damage. Otherwise:
|
||
`damage = base + (final successes - 1) * damage per success`.
|
||
- Manual **Dégâts** accepts remaining successes when cached context is absent.
|
||
- **Subir** prompts for remaining successes and a defender token, reads that
|
||
defender's selected resistance and protection/location query, and displays
|
||
the breakdown. Each selected resistance point removes 2 DMG and 1 AB.
|
||
Protection mitigation and the first protection used for AB follow the rules
|
||
described in F06.
|
||
- Results never subtract HP or armor integrity; that remains manual by design.
|
||
- Cache loss after worker restart must degrade to prompted/manual input rather
|
||
than corrupting a character.
|
||
|
||
**This repository:** attack repeating rows, `attackRolls`, `attackDamage`, and
|
||
four attack action handlers in `src/ravenous.html`; roll-template branches in
|
||
the same file.
|
||
|
||
**Acceptance:** test zero/one/many successes, automatic-only attacks, RMax,
|
||
defense greater than attack, all three defense types, public/secret defender
|
||
rolls, absent cached context, and hand-calculated DMG/AB with a targeted second
|
||
character.
|
||
|
||
## F06 — Health locations, resistances, and protection selection
|
||
|
||
**Status:** Implemented locally; complete combat matrix remains a pending
|
||
Roll20 smoke test.
|
||
|
||
**Outcome.** Track health and armor per body location, accumulate selected
|
||
damage resistances, and make active armor or a chosen location available to the
|
||
damage workflow.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- Provide fixed head, torso, left/right arm, and left/right leg rows plus custom
|
||
repeating locations. Each row keeps HP, HP maximum, protection, current armor
|
||
integrity, and maximum integrity.
|
||
- Track the full sheet resistance set, while only damage-applicable physical and
|
||
elemental types participate in the current attack reduction selector.
|
||
- Multiple checked resistances accumulate. A clear action resets all checks.
|
||
- An active repeating protection contributes only while current integrity is
|
||
greater than zero. Sum protection for DMG, count active valid rows, and retain
|
||
the first valid protection in repeating-row order for AB.
|
||
- Current-selection DMG mitigation is total active protection plus final Force
|
||
if at least one valid protection exists. For a fixed/custom location, use its
|
||
protection plus Force only when its armor integrity is above zero.
|
||
- AB reduction uses selected resistance points and the first protection value,
|
||
never Force. Clamp displayed final values at zero.
|
||
- Encode both DMG mitigation and AB protection into one Roll20 query value so a
|
||
single location prompt can transport both integers through the dice parser.
|
||
|
||
**This repository:** health fields, `DAMAGE_RESISTANCES`, `FIXED_LOCATIONS`,
|
||
`PACK_FACTOR`, and recalculation workers in `src/ravenous.html`.
|
||
|
||
**Acceptance:** cover no armor, depleted armor, one and multiple active
|
||
protections, row reorder, each fixed location, a custom location with macro
|
||
punctuation in its name, multiple resistance checks, and zero clamping.
|
||
|
||
## F07 — Consumables and structured turn-effect tracker
|
||
|
||
**Status:** Implemented.
|
||
|
||
**Outcome.** Store free-form consumables and temporary effects, publish them to
|
||
chat, copy consumable/technique/power effects into a tracker, and guide manual
|
||
turn processing with reminders and expiration.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- Consumables store kind, name, quantity, display duration, description, and
|
||
optional structured timing/reminders. Publishing does not consume quantity.
|
||
- Active effects store an active flag, name, display duration, description,
|
||
duration type, remaining count, countdown phase, and start/end/application/
|
||
removal reminders.
|
||
- Supported duration types are manual, N turns, until next start, until next
|
||
end, combat, and a reserved actions mode. Unknown or legacy timing defaults to
|
||
manual behavior.
|
||
- Start/end actions publish reminders for that phase, decrement only matching
|
||
turn counters, mark expired effects inactive, and announce removals. They do
|
||
not apply prose mechanics or change HP/resources.
|
||
- Cleanup removes only inactive effect rows and reports how many were removed.
|
||
- Copying from a consumable preserves configured timing. Copying from a
|
||
technique or power copies text and any inferred timing, without interpreting
|
||
arbitrary prose at runtime.
|
||
- Build-time reminder inference is conservative: recognize explicit French
|
||
start/end phrases, next-start/next-end, finite turn counts, and combat end;
|
||
leave uncertain duration manual.
|
||
|
||
**This repository:** effect markup and worker handlers in `src/ravenous.html`;
|
||
`effect_reminder_metadata` in `tools/build.py`.
|
||
|
||
**Acceptance:** test every duration type at both phases, inactive rows, a
|
||
multi-turn countdown to zero, no-reminder phases, cleanup, and each copy source.
|
||
Confirm no resource is automatically changed.
|
||
|
||
## F08 — School technique catalogue and acquisition
|
||
|
||
**Status:** Implemented; Roll20-verified.
|
||
|
||
**Outcome.** Import eligible school techniques from book TSVs, let users add
|
||
them individually to an editable repeating list, prevent duplicates, and show
|
||
their cards/effects in chat.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- Group selector choices by school and label them with configured trigrams,
|
||
tier, name, and level.
|
||
- Carry school, tier, type, costs, other requirements, translated effect text,
|
||
and inferred reminder metadata into the acquired row.
|
||
- Use a stable source key to prevent adding the same generated technique twice;
|
||
do not block user-created rows without that key.
|
||
- On sheet open, backfill updated generated content/reminder metadata into rows
|
||
with recognized source keys while preserving ownership and user linkage data.
|
||
- Activation creates a themed chat card and optionally offers linked reusable
|
||
effects. Tracking copies the technique into the temporary-effect tracker.
|
||
- Do not automatically spend Sang/Jauge or execute the mechanical effect.
|
||
|
||
**This repository:** school ingestion and selector generation in
|
||
`tools/build.py`; repeating rows and worker handlers in `src/ravenous.html`.
|
||
|
||
**Acceptance:** add one technique, reject its duplicate, add a custom row,
|
||
reopen, activate, track as effect, and inspect text for unresolved Typst syntax.
|
||
|
||
## F09 — Origin selection and staged powers
|
||
|
||
**Status:** Implemented; Roll20-verified.
|
||
|
||
**Outcome.** Select an origin, import its powers in stage batches, preserve
|
||
existing/custom powers across origin changes, and activate or track powers.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- Generate origins and powers from YAML, translating supported book markup.
|
||
- Persist both the origin key and human-readable origin name.
|
||
- Selecting an origin alone adds nothing. The user chooses a stage and requests
|
||
the batch for the currently selected origin.
|
||
- Stable keys include origin, stage, and source position. Skip existing keys to
|
||
prevent duplicates while leaving unrelated/custom rows untouched.
|
||
- On sheet open, refresh recognized imported rows from current generated data.
|
||
- Activation produces a themed chat card with optional linked reusable effects;
|
||
tracking creates a temporary effect. No prose mechanics are automated.
|
||
|
||
**This repository:** origin parsing in `tools/build.py`; UI and workers in
|
||
`src/ravenous.html`.
|
||
|
||
**Acceptance:** import the same stage twice, add another stage and a custom
|
||
power, switch origin, reopen, activate, and track. Existing rows must survive
|
||
and generated duplicates must not appear.
|
||
|
||
## F10 — Reusable effect library and cross-character offers
|
||
|
||
**Status:** Implemented.
|
||
|
||
**Outcome.** Maintain reusable effect definitions separately from active
|
||
effects, attach their IDs to technique/power chat cards, and let an authorized
|
||
player copy an offered effect to a controlled target character.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- Library rows have a stable effect ID, enabled flag, constrained type, name,
|
||
duration, description, structured timing, and four reminders.
|
||
- Techniques/powers link by comma/space/semicolon-separated IDs. Only enabled,
|
||
exactly matching IDs appear on a chat card.
|
||
- Offer buttons carry a URI-encoded JSON payload and explicitly target a
|
||
character through Roll20's target prompt.
|
||
- The separate Mod action validates payload fields and bounds, verifies the
|
||
clicking player controls the target, and creates an active temporary-effect
|
||
row. It must not trust chat payloads or allow writes to another player's
|
||
character.
|
||
- Library JSON import/export targets reusable rows, not active effect rows.
|
||
|
||
**This repository:** library/link handling in `src/ravenous.html`;
|
||
cross-character application in `roll20_mod/ravenous_shared_effects.js`;
|
||
versioned exchange in `roll20_mod/ravenous_effects_import.js` and
|
||
`effects_web/schemas/ravenous-effects-v1.schema.json`.
|
||
|
||
**Acceptance:** offer zero, one, and multiple effects; ignore disabled or
|
||
unknown IDs; apply to a controlled target; reject an uncontrolled target and
|
||
malformed/oversized payloads; round-trip a library through a handout.
|
||
|
||
## F11 — Versioned character backup, restore, and creation
|
||
|
||
**Status:** Implemented; core workflow is Roll20-verified.
|
||
|
||
**Outcome.** Serialize a Roll20 character into a versioned JSON document and
|
||
either create a new character or replace the sheet data of an existing one.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- Format identifier is `ravenous-roll20-character`, version 1.
|
||
- Preserve name, sheet attributes, abilities, bio, GM notes, journal access,
|
||
and control lists in exports, subject to caller visibility.
|
||
- GM creation makes a new character. Replacement retains the destination
|
||
object/ID, linked tokens, avatar, ownership, and GM-only notes while replacing
|
||
name, bio, attributes, and abilities.
|
||
- Validate the complete incoming document before deleting any destination
|
||
attributes or abilities. Reject unknown fields, invalid types, unsafe sizes,
|
||
duplicates where prohibited, and inaccessible inputs.
|
||
- Players may export/replace only characters they control and read only shared
|
||
handouts. GM handouts use GM Notes; player exports use visible Notes and grant
|
||
that player access.
|
||
- Support direct JSON for small payloads and decoded HTML handout content for
|
||
larger payloads. Sheet header commands target the current character ID.
|
||
- Reopening the sheet after import allows workers to recompute derived values.
|
||
|
||
**This repository:** `roll20_mod/ravenous_character_io.js`, header actions in
|
||
`src/ravenous.html`, and `tests/test_character_io.mjs`.
|
||
|
||
**Acceptance:** round-trip all scalar/repeating attributes, abilities, Unicode,
|
||
HTML-sensitive text, bio/notes, and permissions; test GM creation, GM replace,
|
||
player replace, inaccessible handout, uncontrolled target, malformed JSON, and
|
||
validation failure without partial deletion.
|
||
|
||
## F12 — Monster database conversion
|
||
|
||
**Status:** Implemented.
|
||
|
||
**Outcome.** Convert a monster from the book's pinned SQLite database into the
|
||
character JSON contract while retaining information that has no faithful sheet
|
||
equivalent.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- Read the nested `monsters.db` submodule and select one/all master-visible
|
||
creatures deterministically.
|
||
- Map compatible characteristics, locations, attacks, and powers to stable
|
||
character/repeating attributes.
|
||
- Treat capabilities with damage as attacks and others as powers. Preserve
|
||
source descriptions and damage notation in row notes.
|
||
- Leave unknown dice pools/thresholds/mechanical values neutral for GM review;
|
||
never fabricate a rule conversion.
|
||
- Embed all raw database rows, including phases and unmapped fields, in GM notes
|
||
as JSON so conversion is loss-aware.
|
||
|
||
**This repository:** `tools/export_monsters.py` and
|
||
`tests/test_monster_export.py`.
|
||
|
||
**Acceptance:** convert every master-visible database entry, validate each
|
||
against the character importer, verify representative locations/attacks/powers,
|
||
and ensure raw source rows remain recoverable.
|
||
|
||
## F13 — Craft JSON exchange
|
||
|
||
**Status:** Implemented locally; real Roll20 import smoke test remains pending.
|
||
|
||
**Outcome.** Exchange finalized crafted attacks, protections, consumables, and
|
||
temporary effects through a strict versioned JSON envelope without coupling a
|
||
crafting calculator to Roll20 internals.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- Format identifier is `ravenous-roll20-craft`, version 1. The normative schema
|
||
is `docs/ravenous-craft-v1.schema.json`; semantics are documented in
|
||
`docs/craft-json-v1.md`.
|
||
- Accept 1–100 typed items with only the fields allowed for their destination.
|
||
Reject unknown fields, invalid kinds, non-finite numbers, and oversized text.
|
||
- Import creates new repeating rows; it never overwrites existing rows, equips
|
||
protection, consumes ingredients, changes resources, or recalculates recipes.
|
||
- Imported protection is inactive by omission and must be selected manually.
|
||
- Export reads compatible repeating rows into a private/shared handout according
|
||
to caller permissions.
|
||
- Players can operate only on controlled characters and readable handouts; GMs
|
||
can use explicit IDs or token selection.
|
||
|
||
**This repository:** `roll20_mod/ravenous_craft_import.js`, schema/docs under
|
||
`docs/`, and deterministic examples from `tools/generate_crafts.py`.
|
||
|
||
**Acceptance:** import/export every item type, mixed item collections, inline
|
||
and handout payloads, player/GM paths, every validation failure class, and
|
||
reopen the destination sheet to confirm persistence.
|
||
|
||
## F14 — Deterministic interoperability fixtures
|
||
|
||
**Status:** Implemented.
|
||
|
||
**Outcome.** Produce stable, adversarial example documents that exercise import
|
||
contracts in local tests and CI.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- A seeded character generator covers fixed and repeating sheet sections,
|
||
attributes, abilities, permissions, Unicode, and markup-sensitive strings.
|
||
- Identical seeds produce byte-identical UTF-8 JSON; different seeds vary.
|
||
- Craft generators deterministically cover forge (attack/protection) and
|
||
alchemy (consumable/modifier) destinations.
|
||
- Fixture generation is part of the normal build wrapper and check mode compares
|
||
regenerated fixtures with output.
|
||
- Fixtures are examples and test vectors, never authoritative game data.
|
||
|
||
**This repository:** `tools/generate_character.py`,
|
||
`tools/generate_crafts.py`, `scripts/build.sh`, and their Python tests.
|
||
|
||
**Acceptance:** reproducibility tests, contract validation, coverage assertions,
|
||
and successful import through the Mod API mock.
|
||
|
||
## F15 — Static craft workshop companion
|
||
|
||
**Status:** Functional prototype; full five-discipline rule parity, finalized
|
||
Roll20 mapping, QR sharing, and complete browser accessibility checks are not
|
||
implemented. The exact roadmap is in `craft_web/TASKS.md`.
|
||
|
||
**Outcome.** Provide an account-free static application for browsing
|
||
authoritative craft components, assembling single-discipline recipes, warning
|
||
about basic limits, keeping personal data locally, and exchanging provisional
|
||
recipe/output files.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- Production output is static HTML/CSS/JavaScript/catalog data with no backend,
|
||
tracking, runtime CDN, or mandatory Node build.
|
||
- Normalize all current craft TSV and Forge equipment entries with stable IDs,
|
||
typed searchable/filterable values, source provenance, and a catalogue
|
||
fingerprint.
|
||
- Provide accent-insensitive search, discipline/stage and numeric filters,
|
||
stable sorting, one-discipline composition, basic live totals/warnings,
|
||
personal ingredients, undo/redo, local recipe/backup storage, editable recipe
|
||
exchange, print output, and provisional Roll20 download/clipboard output.
|
||
- Keep editable workshop recipes distinct from finalized Roll20 craft exports.
|
||
Recalculate rather than trusting stored totals.
|
||
- Treat imports and URL/local-storage state as untrusted. Use text DOM APIs,
|
||
validate bounds, and keep recipes private unless the user explicitly exports.
|
||
- Clearly label Forge compatibility/statistics, trap adjudication,
|
||
repeated-effect cases, and any unported discipline calculation as manual/GM
|
||
review. A provisional export must not be presented as rules-validated.
|
||
- Preserve accessibility, responsive, print, offline-static, and theme goals,
|
||
but consult `craft_web/TASKS.md` before claiming a goal is complete.
|
||
- Rule/calculation scope and current limitations are authoritative in
|
||
`craft_web/AGENTS.md`; do not claim roadmap items as implemented.
|
||
|
||
**This repository:** `craft_web/` with its own sources, generator, schema,
|
||
tests, README, task list, and nested agent guide.
|
||
|
||
**Acceptance:** deterministic static build/check, no external runtime
|
||
dependencies, complete normalized-source catalogue, persistence/import/export
|
||
round trips for implemented functions, and visible manual-review warnings.
|
||
Discipline parity and browser-quality checks become required as their backlog
|
||
items are implemented.
|
||
|
||
## F16 — Static reusable-effects companion
|
||
|
||
**Status:** Implemented static catalogue/export foundation.
|
||
|
||
**Outcome.** Browse book alterations, assemble private reusable-effect sets,
|
||
add custom entries, and export F10-compatible JSON without an account or server.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- Source book alterations from the pinned glossary and reuse sheet translation,
|
||
theme, and conservative timing inference.
|
||
- Generate a dependency-free static application and versioned catalogue.
|
||
- Persist private sets/custom effects only in browser local storage and render
|
||
untrusted text without HTML injection.
|
||
- Export `ravenous-roll20-effects` v1 targeting the reusable library, not the
|
||
active tracker. Unknown durations remain manual.
|
||
|
||
**This repository:** `effects_web/`, especially `tools/build.py`, static sources,
|
||
the JSON schema, tests, and nested `AGENTS.md`.
|
||
|
||
**Acceptance:** deterministic build/check, catalogue translation and schema
|
||
tests, local set round trips, hostile-text rendering checks, and import into
|
||
`repeating_sharedeffects` through the Mod simulator.
|
||
|
||
## F17 — CI build, archive, and guarded publication
|
||
|
||
**Status:** Implemented.
|
||
|
||
**Outcome.** Rebuild and validate all three static deliverables and fixtures,
|
||
archive them with fingerprints, and publish only named branches to allow-listed
|
||
directories.
|
||
|
||
**Required behavior and invariants:**
|
||
|
||
- Initialize recursive submodules, use Python 3.11+ through pinned `uv`
|
||
dependencies, and ensure SQLite support for monster tests.
|
||
- Build/test/check the sheet, craft site, and effects site independently.
|
||
- Run Mod simulator tests when Node is available; lack of Node is currently an
|
||
explicitly reported optional skip in CI.
|
||
- Archive all generated bundles and examples.
|
||
- Measure Python generator line coverage with the pinned coverage tool and
|
||
reject results below 85%. Generate version, test, and coverage SVGs for every
|
||
build, archive exactly those badges, and publish them only from `main` below
|
||
`/mnt/assets/coverage/Ravenous/ravenous_roll20/main`.
|
||
- Finalize badges during Jenkins cleanup so failed `main` builds replace stale
|
||
passing status and incomplete measurements with a neutral coverage badge.
|
||
- Deploy production, development, and review branches to distinct allow-listed
|
||
paths below `/mnt/assets/ravenous_roll20`. Create the resolved product
|
||
directory when absent. Use deletion only inside that product subdirectory;
|
||
never at the shared project asset root.
|
||
- Other branches build and archive without deployment.
|
||
|
||
**This repository:** `Jenkinsfile`, `.coveragerc`, the badge/coverage scripts,
|
||
and the three build entry points.
|
||
|
||
**Acceptance:** test an ordinary branch (no deployment), each mapped publication
|
||
branch, a stale artifact, a test or coverage-floor failure, badge renderer and
|
||
publisher rejection cases, and rejection of an unexpected product target path.
|
||
|
||
## Cross-feature non-goals and compatibility rules
|
||
|
||
- Generated files are outputs, not editable sources.
|
||
- The sheet is French-first; stable machine identifiers remain ASCII where the
|
||
current contracts require it.
|
||
- Existing Roll20 attribute names, repeating section names, generated source
|
||
keys, and versioned format fields are compatibility APIs. Rename them only
|
||
with an explicit migration.
|
||
- Browser/sheet workers cannot call privileged Roll20 APIs. Cross-character
|
||
writes, handouts, permissions, and character creation belong in Mod scripts.
|
||
- Chat cards communicate and calculate; they do not grant authority to mutate a
|
||
target. Every Mod command independently validates payload and permissions.
|
||
- String-presence tests prove generation shape, not Roll20 parser/rendering
|
||
behavior. Interactive changes require a real Roll20 smoke test record.
|
||
- Counts from the current pinned book are diagnostics, not permanent product
|
||
requirements. Derive expectations from source inputs where possible.
|
||
|
||
## Adding or porting a feature
|
||
|
||
For a new feature in this repository, update this catalogue in the same change:
|
||
|
||
1. add or amend the feature's observable outcome, invariants, manual boundaries,
|
||
implementation map, and acceptance criteria;
|
||
2. update [ARCHITECTURE.md](ARCHITECTURE.md) if a boundary, data flow, persistent
|
||
name, contract, build artifact, or deployment component changes;
|
||
3. add focused automated checks and record real Roll20/browser validation or
|
||
the precise untested scenario in [TASKS.md](TASKS.md);
|
||
4. update the relevant public README and nested component guide when user
|
||
instructions or component-local constraints change.
|
||
|
||
For a port to another repository, implement the **Outcome**, **Required behavior
|
||
and invariants**, and **Acceptance** sections. The **This repository** paragraph
|
||
is a navigation aid, not a mandated target architecture.
|