From 2d2c7cf501a54b20f022ef916f2ff1b616a049f8 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sat, 19 Sep 2026 21:37:39 +0200 Subject: [PATCH] docs: plan craft workshop subproject --- craft_web/AGENT.md | 5 ++ craft_web/AGENTS.md | 204 ++++++++++++++++++++++++++++++++++++++++++++ craft_web/README.md | 58 +++++++++++++ craft_web/TASKS.md | 153 +++++++++++++++++++++++++++++++++ 4 files changed, 420 insertions(+) create mode 100644 craft_web/AGENT.md create mode 100644 craft_web/AGENTS.md create mode 100644 craft_web/README.md create mode 100644 craft_web/TASKS.md diff --git a/craft_web/AGENT.md b/craft_web/AGENT.md new file mode 100644 index 0000000..bdd836e --- /dev/null +++ b/craft_web/AGENT.md @@ -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. diff --git a/craft_web/AGENTS.md b/craft_web/AGENTS.md new file mode 100644 index 0000000..577eb23 --- /dev/null +++ b/craft_web/AGENTS.md @@ -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. diff --git a/craft_web/README.md b/craft_web/README.md new file mode 100644 index 0000000..cb1425b --- /dev/null +++ b/craft_web/README.md @@ -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. diff --git a/craft_web/TASKS.md b/craft_web/TASKS.md new file mode 100644 index 0000000..44bd064 --- /dev/null +++ b/craft_web/TASKS.md @@ -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.