Mantaq

A TypeScript state machine library built around actors, events, and hierarchical states.

Docs: anderscan.github.io/mantaq

Packages

• core. State machine runtime with actor model, event system, state hierarchy, effects, and virtual clock for testing.
• sugar. Convenience helpers: batch state/event creation, matching, effect utilities, dynamic children.
• traversal. Graph build, coverage instrumentation, and history for testing state machines.
• test. Test harness and coverage assertions for actor behavior.
• pbt. Seeded property-based testing helpers (generators, runProperty).
• utils. Shared internal utilities.
• examples. Real working examples (checkout, auth, saga, event sourcing, undo/redo, and more).

Getting Started

npm install @mantaq/core

From the repo (development):

vp install
vp run ready

Usage

The docs tell one story: a multi-step checkout form. Same machine here.

import { Actor, state, event } from "@mantaq/core";

const basicInfo = state("basicInfo")();
const payment = state("payment")();
const success = state("success")().final();

const submitBasicInfo = event("submitBasicInfo")();
const submitPayment = event("submitPayment")();

const checkout = new Actor({
  inputs: [submitBasicInfo, submitPayment],
  states: [basicInfo, payment, success],
  initial: basicInfo,
  setup: (m) => {
    m.on(basicInfo, submitBasicInfo, () => ({ state: payment }));
    m.on(payment, submitPayment, () => ({ state: success }));
  },
});

checkout.send(submitBasicInfo.create());
checkout.snapshot().path[0]; // "payment"

Docs

The documentation site (apps/docs) builds one running example from start to finish: the checkout form. Each page expands the machine from the previous page. Entity IDs are fixed: the same states and events everywhere.

• Canonical example: packages/examples/checkout.test.ts
• vp run docs:check. Verifies docs use only canonical IDs, imports match real package exports, and the canonical example typechecks.
• .opencode/skills/docs-write/. Agent skill for writing docs: single-example rules and a five-persona review loop (from ux-research/personas-and-journeys.md).

Skills

Agent skills for end users building with @mantaq/core. Writing, testing, and reviewing actor-model code. These are not for developing the library itself.

npx skills add AndersCan/mantaq

The mantaq skill covers philosophy, building blocks, and transition rules, with sibling files for patterns, testing, sugar helpers, and review conventions.

Development

vp run dev        # start dev server
vp run -r test    # run all tests
vp run -r build   # build all packages

Releasing

Versioning is manual; publishing runs in CI via npm trusted publishing (OIDC) with SLSA provenance (.github/workflows/release.yml).

1. Accumulate bump files in .bumpy/ as changes land.
2. When ready: bumpy version. Bumps versions, writes changelogs, consumes bump files.
3. Commit the version changes, push, open a PR, merge to main. A version PR consumes every pending bump file, so the CI bumpy ci check step fails with "No bump files found in this PR". Expected. Add an empty bump to satisfy it: vp exec bumpy add --empty --name "version-packages-v0-3-0" (use the new version number). Same applies to docs-only PRs with no releases.
4. The publish job builds every package and publishes the versioned ones. Publishing uses npm trusted publishing (OIDC). No token secrets.

Project Structure

mantaq/
├── packages/
│   ├── core/        # State machine runtime
│   ├── sugar/       # Convenience helpers
│   ├── traversal/   # Graph + coverage testing tools
│   ├── test/        # Test harness
│   ├── pbt/         # Seeded property-based testing helpers
│   ├── utils/       # Shared utilities
│   └── examples/    # Usage examples
├── apps/
│   └── docs/        # Documentation site
└── vite.config.ts   # Monorepo config