ravenous_roll20/craft_web/AGENTS.md

11 KiB

Agent guide: Ravenous Craft Workshop

Mission

Build a polished static web application that helps players construct Ravenous crafts from authoritative book data, understand their totals and constraints, save editable recipes locally, and export finalized results to Roll20 or paper. The application must be usable without accounts, tracking, an application server, or a network connection after its files have loaded.

This is a folder in the main repository, not a submodule. Changes here may update shared generators, schemas, tests, documentation, and Jenkins when the website needs them, but must not fork the game rules away from ravenous_typst.

Non-negotiable constraints

  • The pinned ravenous_typst submodule is the source of truth. Never infer a rule solely from a table heading, generated HTML, sample fixture, or Roll20 field name. Check the relevant chapter and setup/craft_recipes.typ.
  • Production and CI must not require Node.js. The Jenkins agent is FreeBSD 13; use Python 3.11+, the standard library, and existing pinned Python dependencies for generation and tests.
  • The deployed result must be static HTML/CSS/JavaScript/data. Do not require a backend, build daemon, service worker toolchain, CDN, or third-party API.
  • Do not edit generated web assets by hand. Edit sources and regenerate them.
  • Preserve the existing ravenous-roll20-craft version 1 contract unless a separately planned, backward-compatible schema version is required.
  • User recipes are private by default. Do not transmit them. Saving uses local browser storage; sharing requires an explicit user action.
  • Treat imported recipe text and URL state as untrusted. Render with DOM text APIs, validate structure and bounds, and never inject it with innerHTML.
  • Accessibility is a feature, not cleanup: keyboard operation, visible focus, semantic controls, screen-reader labels, reduced motion, contrast, and a print layout belong in acceptance criteria.

Authoritative source map

Concern Authoritative source
General crafting level, mastery, finishing, toxicity, satiety ravenous_typst/chapters/craft/skills_rules.typ, ravenous_typst/chapters/artisanat.typ
Alchemy selection and combination rules ravenous_typst/chapters/craft/alchemy.typ
Brewery titrage, time, effects, and arrangement ravenous_typst/chapters/craft/brasserie.typ
Forge bases, materials, finishing, combined weapons ravenous_typst/chapters/craft/armurerie.typ
Restoration stages and effect combination ravenous_typst/chapters/craft/restauration.typ
Traps, prerequisites, preparation, placement ravenous_typst/chapters/craft/traps.typ
Executable aggregation and forge-stat semantics ravenous_typst/setup/craft_recipes.typ
Curated parity recipes ravenous_typst/data/config/recipes.yaml
Ingredient catalogs ravenous_typst/data/src/craft/*.tsv
Forge equipment bases ravenous_typst/data/src/db/weapons.db, table Equipements
Display labels and references ravenous_typst/data/src/glossaries/*.yaml
Available themes ravenous_typst/setup/theme/themes.typ
Roll20 export format docs/ravenous-craft-v1.schema.json, docs/craft-json-v1.md
Roll20 accepted fields roll20_mod/ravenous_craft_import.js

At the current pinned revision the catalogs contain alchemy solvents, reagents, and transmutations; brewery ferments, methods, primary/secondary effects, and finishings; forge equipment, 50 materials, and 65 finishings; restoration mains, sides, and seasonings; and 46 traps. Counts are diagnostic, not constants: tests should derive expected counts from source files.

Proposed folder layout

craft_web/
  AGENTS.md              this guide
  TASKS.md               product decisions and phased backlog
  README.md              user-facing scope and architecture
  src/
    index.html            semantic application shell
    styles.css            layout, themes, responsive and print styles
    app.js                application boot and view coordination
    model/                pure recipe calculation and validation modules
    ui/                   small DOM modules, no framework runtime
    vendor/               reviewed vendored QR implementation, if approved
  tools/
    build.py              deterministic static-site and catalog generator
  tests/
    test_catalog.py       Python source parsing and parity tests
    test_site.py          static structure, asset, schema, and safety tests
  schemas/
    workshop-recipe-v1.schema.json
  build/                  generated, ignored locally, archived by CI

Keep modules small and dependency-free. Browser modules should expose pure functions where possible so core calculations can also be checked with Python fixtures without requiring Node in CI. If browser execution tests are added, they are optional locally unless a FreeBSD-compatible browser test runtime is explicitly approved and installed.

Data normalization and calculations

Generate a versioned catalog rather than shipping raw TSV strings. Each entry needs a stable ID derived from discipline, stage, and source identity; retain the original source name and source path for diagnostics. Normalize numeric Typst wrappers such as #ddlvl, #toxlvl, #winelvl, and #timelvl into typed numbers while retaining display-ready French text.

Use the shared glossary/Typst translation code where possible. References such as @al_concussif must become their French labels, and difficulty values use the same Unicode-star rendering as other exports. Unsupported markup must be reported during generation, not silently stripped into misleading prose.

The Python model and browser model must agree on these core semantics from setup/craft_recipes.typ:

  • total tier is the maximum component tier;
  • cost, difficulty, toxicity, satiety, and finishing values are summed;
  • mastery gates components; crafting level gates total difficulty; each discipline's finishing specialty gates its finishing total;
  • brewery separately totals available and spent titrage plus preparation and fermentation time, and rejects overspending;
  • forge starts from the SQLite equipment record, applies compatible material and finishing changes, reductions that stop at zero, and alloy amplification;
  • repeated-effect behavior described in each discipline must be represented explicitly or flagged for manual adjudication—never guessed from prose;
  • traps retain prerequisites and the transportable/preparable/on-site split;
  • manual or GM-dependent effects remain visible warnings, not fake automation.

Use curated recipes in data/config/recipes.yaml as golden parity fixtures. For every discipline, compare component selection, totals, and final forge statistics against independently expected data. A catalog build must fail on unknown macros that affect calculations.

Recipe and export formats

Define a versioned ravenous-workshop-recipe schema for editable recipes. It should store the discipline, stable selected-component IDs, user-entered name and notes, artisan limits, output choices, schema version, and a source catalog fingerprint. Do not store calculated totals as authority; recalculate them and show a migration warning when the source fingerprint changes.

Export to Roll20 only after validation. Produce exactly one of the four item types currently accepted by the importer—attack, protection, consumable, or modifier—or a documented collection of them. Unknown or non-representable properties belong in the item's human-readable notes/effects/description. The site must validate its output against docs/ravenous-craft-v1.schema.json and offer both a downloaded .json file and copy-to-clipboard.

QR sharing encodes the editable Workshop recipe, not the entire catalog. Use a compact canonical representation with an explicit version and checksum. Set a tested byte limit and fall back to file download when a recipe would make an unreliable QR code. QR decoding must use only explicit paste/file/camera action; camera support is optional and must gracefully handle denial or unavailable secure contexts. Any QR library must be vendored with its license and pinned source provenance—no runtime CDN.

UX requirements

  • Desktop and mobile layouts must both support composing without horizontal page scrolling. Large result tables may use contained scrolling.
  • Search is accent-insensitive and supports names plus rendered effect text.
  • Filters can be combined, cleared, and reflected in an accessible result count. At minimum: tier/mastery, cost, difficulty, toxicity, stage, and discipline-specific attributes.
  • Sorting must include name and relevant numeric columns, with stable ordering.
  • The workspace clearly distinguishes hard errors, exceeded player limits, compatibility exclusions, and advisory/GM-review warnings.
  • Theme choices are generated from the same Typst theme source as the sheet, persist locally, respect system preference for the initial choice, and work in print without consuming ink unnecessarily.
  • Saving is resilient to unavailable or full local storage. Users can rename, duplicate, delete with undo/confirmation, import, and export their library.
  • Do not claim cloud sync, collaboration, camera scanning, installability, or browser support until it has an implemented and tested fallback.

Build, test, and CI expectations

The target commands should eventually be:

uv run python craft_web/tools/build.py --output craft_web/build
uv run python -m unittest discover -s craft_web/tests -v
uv run python craft_web/tools/build.py --output craft_web/build --check

The build must be deterministic, independent of locale and timezone, and use UTF-8 explicitly. --check regenerates into a temporary directory and compares all tracked/expected artifacts. Tests should cover parsing, stable IDs, macro handling, every discipline, recipe validation, filter metadata, export schema, unsafe strings, theme generation, share-size limits, and golden recipes.

Jenkins should build and archive the website separately from the Roll20 sheet, then deploy it to a sibling below /mnt/assets/ravenous_roll20/ only on the existing publication branches. Deployment keeps the same allow-list and guarded-delete discipline used by the sheet. Do not introduce npm, npx, or network-loaded assets into CI.

Change workflow

  1. Identify the relevant Typst chapter, table, and executable recipe function.
  2. Add or update normalized-data fixtures and tests before calculation logic.
  3. Implement the Python generator/model, then mirror the proven behavior in small browser modules.
  4. Build and test all five disciplines, including invalid and boundary cases.
  5. Test keyboard, mobile, print, offline reload, import/export round trips, and at least two themes manually in real browsers.
  6. Record any rule that remains manual and any browser behavior not exercised.
  7. Commit generated deployment output only if the repository-wide policy is changed to track it; otherwise leave craft_web/build/ ignored.

When book data changes, prefer a failing parser or parity test over silently accepting a new macro or column with incorrect semantics.