Small objectives, dependable progress. @cranberry-forge/trailmark is a framework-independent quest journal for JavaScript games and interactive worlds. Define a few commissions, activate them deliberately, and feed typed events into inspectable counters. The runtime has zero dependencies, no storage, no renderer, and no Cranberry Forge imports.
Version 0.1.0 · ESM · JavaScript + TypeScript declarations · MIT
The harbor laboratory
Run the repository locally and open /trailmark.html to restore a tiny procedural archipelago: gather timber and stone, repair three open stone arches, rebuild a village's terracotta roofs, and light the lighthouse. Each action goes through the public package API. Inspect the event trace, replay the most recent event to demonstrate deduplication, claim receipts, and export or load a versioned save.
The standalone runtime does not depend on the demonstration or on Three.js. The scene is application code that derives its appearance from journal.list().
Where it fits
Quest journals, narrative engines, and state machines are established categories. Trailmark's contribution is a compact objective-specific integration utility: explicit gated activation, integer objective aggregation, deterministic views, bounded event dedupe, and validated local receipts/saves in one small API.
| Tool | Documented focus | Choose it when |
|---|---|---|
| XState persistence | Persisting/restoring actor state; deep persistence and event-sourcing patterns | Your gameplay needs hierarchical or parallel state machines and actor orchestration. |
| inkjs | JavaScript runtime and compiler for ink interactive narrative, including story continuation and choices | Your project needs authored branching narrative, ink scripts, and story execution. |
| Trailmark | Objective counters, prerequisite gates, completion receipts, and bounded local saves | You already have events and need a small inspectable quest journal beside your world or narrative engine. |
This comparison describes documented focus, not feature exclusivity or a performance benchmark. Primary sources reviewed on September 7, 2026. Trailmark can sit alongside either alternative; it does not implement their general state-machine or story-language capabilities.
Documentation and verification
The source repository includes tests/trailmark.test.mjs. Its meaningful checks cover explicit activation, prerequisite gates, matching/clamping, deterministic fan-out, FIFO deduplication, one-time claims, save round trips, detached data, malformed inputs, atomic failed restore, reused evicted IDs, and sequence exhaustion. Run from the Cranberry Forge repository with node --test tests/trailmark.test.mjs.