ravenous_roll20/craft_web/TASKS.md

10 KiB

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.

Functional proof of concept

  • Build a deterministic static site with Python only and no runtime CDN.
  • Display 511 live entries from every craft TSV and the Forge SQLite table.
  • Provide all Typst-derived themes, responsive catalogue cards, text search, discipline/stage filters, numeric limits, and sorting.
  • Let players add/remove components and display live tier, cost, difficulty, toxicity, artisan level, and a simple difficulty warning.
  • Demonstrate local browser saving and a provisional Roll20 JSON download.
  • Enforce one craft discipline per recipe and lock it from the first component.
  • Let players create and remove persistent personal ingredients in local storage.
  • Add deterministic Python tests and a --check build mode.
  • Build, archive, and deploy the prototype through Jenkins below RPG/.

The proof of concept intentionally does not claim full rule parity yet. The remaining phases turn it into a trusted calculator and production application.

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. Current path: /mnt/assets/ravenous_roll20/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 assets, 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/assets/ravenous_roll20/, 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.