Documentation

This page lists every document in docs/. Each document is one of four kinds, and the kind tells you what the document does for you.

Kind	What it does	When you read it
Tutorial	Takes you through one complete piece of work, step by step	You are new and want to learn by doing
How-to guide	Gives the steps for one task you already want to do	You know the goal and want the steps
Reference	Describes what exists: controls, fields, rules, and modules	You need a fact while you work
Explanation	Says why the app or the code works the way it does	You want the background

A document stays inside its kind. A tutorial does not list every option, a reference does not teach, and an explanation gives no steps.

If you run a campaign, start with First session as GM. If you change the code, start with First code change and then read Architecture.

The deploy also publishes these documents as a website at https://cartographer.tbmh.org/docs/. Its home page is index.md, which covers what the README covers. Contributing describes how the site is built.

Tutorials

Document	What you do
First session as GM	Load the example campaign, move the party, and run one fight
First code change	Start the app, change one module, test the change, and see it in the browser

How-to guides

Document	Tasks it covers
GM guide	Build a world, run a session, track characters, curate the library
Contributing	Set up the tools, run the checks, build, and send a change
Testing a change	Run the unit tests, the typecheck, the linter, and the browser checks
Adding a tile	Draw a tile, register it, and check that it joins its neighbors

Reference

Document	What it describes
GM reference	Modes, roles, panels, keyboard control, and the rules the app applies
Tile assets	The tile catalog and the art conventions for each tile family
UI components	The shared widget builders, the panel contract, and the CSS vocabulary
The app wiring layer	The `AppContext` object and what each `src/app/` module owns
Conventions	The performance, UI, and testing rules that code here follows
Benchmarks	The performance harnesses, their options, and how to read their output
Bundled fonts	The three typefaces, their licenses, and where the styles use them

Explanation

Document	What it explains
Architecture	How the codebase is organized, and the split between pure logic and DOM glue
The map	Tiles, the node hierarchy, rendering, fog of war, and party movement
Entities	Creatures, resources, and the character model
Combat	The fight screen, the one module that writes the fight, and the view derived from it
Persistence	How a campaign becomes a string, the packing layers, and undo history
Testing strategy	Why the coverage total is low, and what the suite cannot reach
Curated spells	Why the app ships 111 spells and not the full SRD

Browser pages

The two HTML pages in docs/ and the tile preview in tests/ sit outside the four kinds. pnpm run guide generates dev-guide.html, so do not edit it by hand. gallery.html and the scripts in docs/gallery/ are written by hand. The docs site also publishes all three, under https://cartographer.tbmh.org/docs/, with the tile preview at tile-gallery.html.

Page	What it shows	How to open it
`dev-guide.html`	A tour of the codebase: the import map, the mount order, the packing layers of a save, and a checklist for a pull request	Open the file in a browser. Rebuild it with `pnpm run guide` (see Contributing)
`gallery.html`	Every shared builder in `src/ui/`, drawn from the real modules, with the call that built it and the classes that the call adds	Start `pnpm run dev`, and open `http://127.0.0.1:8080/docs/gallery.html`. The page loads ES modules, so it does not work from a `file://` address
`tests/tile-preview.html`	The tile art of each family, side by side, so every join is visible	Start `pnpm run dev`, and open `http://127.0.0.1:8080/tests/tile-preview.html`. Testing a change lists the other preview pages