Encounter

Encounter serves both audiences from one app with two views: the DM’s control window and a read-only tracker on a monitor facing the players.

The windows share an origin, so they share localStorage. The tracker listens for the storage event, which the browser fires in every other window when one writes, and re-reads its keys on focus. A turn advance reaches the player monitor at once, with no server, socket or polling. Neither window hands derived state to the other: each rebuilds the turn order from the same saved data with the same pure function.

What the players see is curated in code. Hidden combatants are filtered out before rendering, and no hit-point number reaches their screen. Monsters show one of four states (healthy, bloodied, a pulsing critical, dead), while player characters get an AC shield and an HP bar, and conditions appear as labelled icons. The dock shows at most 11 portraits at three sizes, designed for a 2560×720 ultrawide and scaled down to fit a smaller screen’s long axis.

The second screen made the wrapper a liability. The player display lives at its own URL path, and a packaged build loads its files without an HTTP server, so that path had nothing to answer it short of changing how the app picks its view. The macOS build had a second problem: its embedded webview could not be relied on to deliver storage events between windows, and those events are what keep the player display live. Two windows of an ordinary browser, pointed at a local server, have neither problem.

The wrapper was shelved, not deleted: 25 lines of Rust, still version-synced, and the entry point still accepts ?tracker as a fallback for packaged builds.

The new model got its own tooling. A server manager’s stop command kills only processes listening on the app’s port, after checking that each process ID is a plain integer. A one-command game-night setup installs dependencies with lifecycle scripts disabled, starts the server and opens both views.

Creatures and turns are kept apart. A creature holds the state: hit points, armour class, buffs and conditions. A turn slot is one moment in the order the turn marker walks.

Opt-in rules modules reshape the slot list through one hook: data in, data out, and by design rule a module never touches storage or app internals. A stable sort by initiative runs afterwards, so a tie order the DM set by dragging survives. The first module, Monsters act twice, gives every non-player creature a second turn at its initiative minus 10, to keep fights with a big party moving. Each turn gets its own HP controls, and all of them drive the one shared creature.

The hook is written as a public contract that outside modules could target later without a rewrite, and the 17-entry condition registry (the 15 standard 5e conditions plus Concentration and Hunter’s Mark) follows the same shape. The combat rules get the same care: Shield’s +5 AC drops when the turn comes back to its caster, temporary HP absorbs damage first, and undo restores both pools.

During a live game, combatants vanished the moment the encounter started. Ids came from a module-level counter that restarted at 1 on every page reload, while the roster persisted in localStorage, so a new entry could take an id a saved one already held. Downstream, a Map keyed by id kept only the last entry per key, and the duplicates disappeared without an error.

The fix, released in v1.5.0 on 26 July 2026, has two layers. Ids are now minted with crypto.randomUUID() at the source, and starting an encounter regenerates any duplicate id, so even data saved under the old scheme can’t drop a combatant.

The honest coda: the same resettable counter survives in the Party and NPC builders. It drops no one, but after a reload a new NPC template can reuse an old id. It is unfixed in v1.8.0 and listed in the honest notes.