docs: plan craft workshop subproject
Roll20 Sheet Build Successful The Ravenous Roll20 sheet was generated and validated successfully.
Ravenous/ravenous_roll20/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-09-19 21:37:39 +02:00
parent 1acd155617
commit 2d2c7cf501
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
4 changed files with 420 additions and 0 deletions

5
craft_web/AGENT.md Normal file
View File

@ -0,0 +1,5 @@
# Craft Workshop agent instructions
The complete instructions for this subproject are in [AGENTS.md](AGENTS.md).
The plural filename is retained so repository-aware coding agents discover the
guidance automatically.

204
craft_web/AGENTS.md Normal file
View File

@ -0,0 +1,204 @@
# 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
```text
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:
```sh
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/books/RPG/` 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.

58
craft_web/README.md Normal file
View File

@ -0,0 +1,58 @@
# Ravenous Craft Workshop
This subproject will build a static, offline-capable website for composing,
checking, saving, sharing, and exporting Ravenous crafts. It is intentionally
kept inside this repository so that every published catalog is generated from
the exact `ravenous_typst` revision used by the Roll20 sheet.
The intended implementation is deliberately boring to deploy:
- Python 3.11 generates normalized JSON and the static bundle;
- the browser application uses dependency-free HTML, CSS, and JavaScript;
- no Node.js, application server, database, account, or CDN is required;
- Jenkins can build it on FreeBSD 13 and publish it below `RPG/`;
- recipes work offline and remain on the player's device unless explicitly
downloaded, copied, or encoded in a share link/QR code.
The product scope and implementation phases are in [TASKS.md](TASKS.md). The
authoritative development rules and source map are in [AGENTS.md](AGENTS.md).
## Proposed user experience
The home screen is a searchable catalog and recipe workspace. A player chooses
one of Forge, Restauration, Alchimie, Brasserie, or Pièges, enters their artisan
limits, then adds compatible components. Totals, derived output, constraints,
and warnings update immediately. Filters include mastery/tier, difficulty,
toxicity, cost, finishing budget, equipment category, and discipline-specific
values such as satiety, titrage, or preparation time.
Recipes can be named, duplicated, pinned, sorted, and stored locally. They can
be exported as:
- an editable Ravenous Workshop recipe file;
- finalized `ravenous-roll20-craft` version 1 JSON;
- a print-friendly recipe card;
- a compact link or QR code when the encoded recipe fits safely.
Import accepts Workshop recipes and Roll20 craft JSON. Roll20 imports are
treated as finalized items and may not be fully reversible into source
ingredients.
## Architecture boundary
`ravenous_typst` remains the rules and content authority. The generator will
read its TSV files, `data/src/db/weapons.db`, glossary YAML, theme definitions,
and `data/config/recipes.yaml`. Browser code consumes only generated normalized
data; it must not contain a second hand-maintained copy of ingredients or
rules.
The website's editable recipe document and the Roll20 exchange document serve
different purposes:
- `ravenous-workshop-recipe` records selected source components, user inputs,
and source-data version so the recipe can be reopened and recalculated;
- `ravenous-roll20-craft` records final sheet rows accepted by the existing Mod
importer and JSON Schema.
That separation is a proposed design decision and is called out for approval
in Phase 0 of the task list.

153
craft_web/TASKS.md Normal file
View File

@ -0,0 +1,153 @@
# Ravenous Craft Workshop backlog
This backlog is intentionally staged. Phase 0 decisions should be approved
before implementation because they affect saved data, URLs, and deployment.
## Phase 0 — Decisions to vet
- [ ] Approve the two-format model: editable `ravenous-workshop-recipe` files
for reopening and sharing, finalized `ravenous-roll20-craft` v1 files for
Roll20 import.
- [ ] Approve all five initial disciplines: Forge, Restauration, Alchimie,
Brasserie, and Pièges. Alternatively, select an MVP subset; recommended MVP
is Alchimie + Restauration, followed by Brasserie, Forge, then Pièges.
- [ ] Decide whether invalid/excess recipes may be saved and shared with clear
warnings. Recommendation: yes, but block finalized Roll20 export until hard
structural errors are fixed; artisan-limit overruns remain exportable only
after an explicit acknowledgement because a GM may authorize them.
- [ ] Confirm French-only v1. Recommendation: generate stable internal IDs now,
but defer UI localization until the French workflow is complete.
- [ ] Approve browser-local storage with explicit JSON backup/restore and no
server synchronization or analytics.
- [ ] Approve QR contents and limits: encode compact editable recipes, show the
approximate QR size, and fall back to download/share text above the tested
capacity. Camera scanning is a later enhancement, not MVP.
- [ ] Pick the public path. Recommendation:
`/mnt/books/RPG/ravenous_craft/` (`/RPG/ravenous_craft/`) as a sibling of the
Roll20 sheet, with branch suffixes matching the existing deployment policy.
- [ ] Approve a vendored, license-recorded QR encoder with no CDN/runtime
network dependency, or defer QR generation until after the core release.
## Phase 1 — Data compiler and executable model
- [ ] Scaffold the documented `craft_web/src`, `tools`, `tests`, `schemas`, and
generated `build` layout; add the build directory to `.gitignore`.
- [ ] Extract a shared Typst text translator so the sheet, monster exporter,
and craft catalog use identical glossary labels and star rendering.
- [ ] Parse every craft TSV into a normalized, versioned catalog with stable
IDs, typed values, source provenance, compatibility tags, and rendered text.
- [ ] Read Forge equipment from `data/src/db/weapons.db` and normalize nullable,
numeric, categorical, special-effect, and application-target fields.
- [ ] Generate all available palettes from `setup/theme/themes.typ` into CSS
variables plus theme metadata; define a safe default and high-contrast mode.
- [ ] Port the aggregation semantics from `setup/craft_recipes.typ` into a pure
Python reference model for all five disciplines.
- [ ] Implement explicit parsing for forge `change`, drawback reduction, bonus
reduction, alloy, and compatibility macros; fail on unknown mechanical macros.
- [ ] Define and validate `ravenous-workshop-recipe` v1, including a catalog
fingerprint and migration/error envelope.
- [ ] Turn curated `data/config/recipes.yaml` entries into golden fixtures and
add boundary tests for negative totals, repeated effects, finishing budgets,
brewery titrage, forge reductions, and trap timing.
- [ ] Emit deterministic `catalog.json`, schema files, build metadata, and a
human-readable unsupported-markup report; add `--check`.
## Phase 2 — Read-only catalog browser
- [ ] Build the semantic application shell with responsive navigation for the
five disciplines and a useful no-JavaScript explanation.
- [ ] Implement accent-insensitive full-text search over name, stage, detail,
and rendered effects.
- [ ] Implement combinable filters: tier/mastery, cost, difficulty, toxicity,
stage/category, satiety, finishing, titrage, time, equipment target, and trap
preparation tag where applicable.
- [ ] Implement stable sorting by name and every visible numeric measure;
preserve filter/sort state in the URL without including private recipes.
- [ ] Add compact/list/table views, result counts, active-filter chips, clear
actions, empty states, and mobile-contained tables.
- [ ] Add generated theme selection for every book palette, system/default
behavior, persisted preference, high contrast, reduced motion, and print CSS.
- [ ] Add source/version/about views explaining that Typst data is authoritative
and linking exported formats to their schema documentation.
- [ ] Test keyboard traversal, focus order, labels, contrast, 200% zoom, narrow
screens, print preview, unsupported storage, and offline static loading.
## Phase 3 — Recipe composers
- [ ] Create a shared workspace with artisan inputs: Intelligence, main skill,
Excellence, Mastery, discipline finishing specialty, and optional consumer
toxicity/satiety limits.
- [ ] Show live totals and separate hard validity errors, artisan-limit
overruns, incompatibilities, and advisory GM/manual-review notes.
- [ ] Implement Alchemy: solvent, permitted reagent count, reagents,
transmutations, duration/contact notes, toxicity, output quantity, and
repeated-effect presentation.
- [ ] Implement Restauration: main ingredients, sides, seasonings, satiety,
toxicity, finishing budget, and repeated-effect presentation.
- [ ] Implement Brasserie: ferments, preparation and fermentation methods,
main/secondary effects, finishings, titrage budget, toxicity, and both times.
- [ ] Implement Forge: base shape/nature, compatible materials and finishings,
final attack/protection statistics, reductions capped at zero, alloys,
equipment-specific fields, and combined-weapon/manual-rule warnings.
- [ ] Implement Pièges: effect selection, prerequisites, quantity, team inputs,
preparation/placement split, participant timing, minimum placement time, and
manual camouflage/integrity fields without inventing GM decisions.
- [ ] Add undo/redo for composition, recipe duplication, reset confirmation,
and a readable calculation breakdown showing each component's contribution.
- [ ] Add curated recipes as loadable examples and verify browser results against
the Python golden fixtures.
## Phase 4 — Save, import, export, and sharing
- [ ] Implement a local recipe library with rename, duplicate, pin, tag, sort,
search, delete recovery, timestamps, and graceful quota/private-mode errors.
- [ ] Export/import one editable Workshop recipe and a complete library backup;
validate limits, versions, unknown fields, and source fingerprints.
- [ ] Add migration hooks and a comparison screen for recipes saved against an
older catalog revision; never silently rewrite selections.
- [ ] Map finalized recipes to Roll20 attack, protection, consumable, and
modifier items, including automatic-success/dice fields and readable fallback
notes for data Roll20 cannot represent.
- [ ] Validate generated Roll20 payloads against
`docs/ravenous-craft-v1.schema.json`; test round trips through the existing
Roll20 Mod importer fixture model.
- [ ] Provide download and clipboard actions with deterministic UTF-8 filenames,
success/error feedback, and recovery when Clipboard APIs are unavailable.
- [ ] Add print-friendly single-recipe and recipe-book views with generated
theme accents, clean monochrome fallback, effects, totals, and source version.
- [ ] Define the compact URL/QR codec, canonical ordering, checksum, size limits,
malformed-input handling, and privacy warning; add deterministic vectors.
- [ ] Vendor the approved QR encoder with license/provenance, render accessible
SVG/canvas plus text fallback, and add print/download actions.
- [ ] Optionally add camera/file QR decoding only after explicit permission,
feature detection, secure-context handling, and a non-camera fallback.
## Phase 5 — Offline quality and publication
- [ ] Add a minimal web manifest and service worker only after cache versioning,
update prompts, offline fallback, and stale-catalog recovery are designed and
tested. The plain static site must remain usable if service workers fail.
- [ ] Add Python CI tests for deterministic generation, schema/export validity,
source counts, unsupported macros, unsafe strings, link integrity, asset
locality, and forbidden CDN/Node dependencies.
- [ ] Add an optional browser smoke-test strategy that works on FreeBSD 13 or
document manual browser coverage; do not make Node a hidden requirement.
- [ ] Extend Jenkins with separate build, test, archive, and guarded deployment
steps for the craft site, preserving the existing Roll20 sheet artifacts.
- [ ] Publish review/development/production branches under the approved sibling
paths below `/mnt/books/RPG/`, with an explicit deployment allow-list.
- [ ] Perform manual acceptance in current Firefox and Chromium on desktop and
mobile-sized viewports: compose each discipline, reload offline, save/restore,
share/scan QR, print, export, and import into a controlled Roll20 character.
- [ ] Document supported browsers, local-data/privacy behavior, backup advice,
source revision, known manual rules, deployment URL, and recovery procedures.
## Later candidates, deliberately outside v1
- [ ] Installable PWA polish and OS share-target integration.
- [ ] Optional encrypted recipe bundles or peer-to-peer sharing.
- [ ] Campaign inventory, ingredient quantities, shopping lists, and pricing.
- [ ] Multi-character artisan profiles and party trap planning.
- [ ] English/localized UI generated from stable IDs.
- [ ] Server-backed synchronization or collaborative editing. These require a
separate privacy, authentication, hosting, and maintenance design.