aifsmjs 0.4.0 → 0.5.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 ysl
+Copyright (c) 2026 yshengliao
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/llms-full.txt

@@ -543,6 +543,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] — 2026-05-29
+
+### Changed
+
+- **`STABILITY.md` is now repo-only** — removed from the npm `files`
+  allowlist, aligning with the majority of the ai*js family (5 of 7
+  packages already ship the stability contract repo-only). The file stays
+  in the repository and remains visible on GitHub and the rendered npm
+  package page; it is simply no longer bundled inside the published
+  tarball. Packaging consistency patch: **no runtime API change, no
+  signature change**; the built bundles (`dist/`) are byte-identical to
+  0.4.0 (core gzip 4,387 B).
+
 ## [0.4.0] — 2026-05-29
 
 ### Changed
@@ -956,10 +969,10 @@ pnpm example:form-wizard      # 04-form-wizard
 
 | # | Example | What it shows | Real-world pattern |
 |---|---|---|---|
-| 01 | [traffic-light](01-traffic-light/index.ts) | Minimal `setup → defineMachine → createRuntime → send` loop with `assign` and a snapshot subscriber. | Cyclic scene flow (loading → menu → playing → result → loading) — or any 3-state cycle. |
-| 02 | [approval-workflow](02-approval-workflow/index.ts) | Multi-candidate guarded transitions (`and([...])`), effects + handlers, `persist` + `recorder` middleware, and `replay()` to reproduce the final snapshot. | Document approval, ticket triage, turn-based games with branching outcomes + post-mortem replay. |
-| 03 | [checkout-funnel](03-checkout-funnel/index.ts) | E-commerce checkout: cart → shipping → payment → review → confirmed. Per-stage validation as guards, payment + analytics as effects, full replay of the funnel. | Plain web app — no canvas, no game loop. Demonstrates that aifsmjs models classic UX funnels. |
-| 04 | [form-wizard](04-form-wizard/index.ts) | Multi-step form wizard with back / next / jump-to-step navigation. Per-step validation, draft persistence via the `persist` middleware. | Account onboarding, settings editor, multi-page survey. |
+| 01 | [traffic-light](https://github.com/yshengliao/aifsmjs/blob/main/examples/01-traffic-light/index.ts) | Minimal `setup → defineMachine → createRuntime → send` loop with `assign` and a snapshot subscriber. | Cyclic scene flow (loading → menu → playing → result → loading) — or any 3-state cycle. |
+| 02 | [approval-workflow](https://github.com/yshengliao/aifsmjs/blob/main/examples/02-approval-workflow/index.ts) | Multi-candidate guarded transitions (`and([...])`), effects + handlers, `persist` + `recorder` middleware, and `replay()` to reproduce the final snapshot. | Document approval, ticket triage, turn-based games with branching outcomes + post-mortem replay. |
+| 03 | [checkout-funnel](https://github.com/yshengliao/aifsmjs/blob/main/examples/03-checkout-funnel/index.ts) | E-commerce checkout: cart → shipping → payment → review → confirmed. Per-stage validation as guards, payment + analytics as effects, full replay of the funnel. | Plain web app — no canvas, no game loop. Demonstrates that aifsmjs models classic UX funnels. |
+| 04 | [form-wizard](https://github.com/yshengliao/aifsmjs/blob/main/examples/04-form-wizard/index.ts) | Multi-step form wizard with back / next / jump-to-step navigation. Per-step validation, draft persistence via the `persist` middleware. | Account onboarding, settings editor, multi-page survey. |
 
 ## Notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aifsmjs",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Small, strict FSM library for deterministic, replayable state machines in any TypeScript/JS app — multi-step forms, checkout funnels, auth flows, tutorials, scene flow. Pure step() lifecycle, opt-in effects, inspect, replay, and a fast-check property-based testing adapter. Browser / Node / Bun / Deno / WebView / Worker friendly.",
   "keywords": [
     "fsm",
@@ -18,7 +18,7 @@
     "typescript",
     "esm"
   ],
-  "author": "ysl <ysl@sheng.page>",
+  "author": "yshengliao",
   "license": "MIT",
   "homepage": "https://github.com/yshengliao/aifsmjs#readme",
   "repository": {
@@ -74,7 +74,6 @@
     "dist",
     "README.md",
     "README_ZHTW.md",
-    "STABILITY.md",
     "LICENSE",
     "llms.txt",
     "llms-full.txt"

package/STABILITY.md

@@ -1,87 +0,0 @@
-# Stability
-
-This document defines the stability tier of every public symbol exported by
-`aifsmjs`. Tiers govern what breaks may occur in future minor / major bumps.
-
-## Stable (since 0.1.0)
-
-Fully stable. Breaking changes only at a major version bump (1.0+).
-
-- `createMachine`, `defineMachine`, `setup`, `createRuntime`, `initialSnapshot`
-- `step`, `resolveTransitions`, `evalGuard`, `resolveGuard`, `isAsyncGuardFn`
-- `assign`, `mergeContext`, `createSnapshot`, `deepFreeze`, `freezeSnapshot`
-- `Runtime.send`, `Runtime.reset`, `Runtime.can`, `Runtime.getSnapshot`,
-  `Runtime.snapshot`, `Runtime.subscribe`, `Runtime.on`, `Runtime.dispose`,
-  `Runtime.signal`, `Runtime.disposed`
-- All error classes from 0.1.0–0.2.1: `RuntimeDisposedError`,
-  `InvalidDefinitionError`, `UnknownActionError`, `UnknownGuardError`,
-  `AsyncGuardError`
-- Types: `MachineDef`, `StateDef` (fields `on`, `entry`, `exit`, `final`),
-  `TransitionDef`, `Snapshot`, `Implementations`, `Guard`, `Action`,
-  `EffectHandler`, `Effect`, `Enqueuer`, `Middleware`, `MiddlewareContext`,
-  `RuntimeOptions`, `StepResult`, `ResetEvent`, `RESET_EVENT_TYPE`,
-  `RuntimeTransitionEvent`, `RuntimeErrorEvent`, `RuntimeEventMap`
-- All subpath exports: `aifsmjs/guards`, `aifsmjs/effects`, `aifsmjs/inspect`,
-  `aifsmjs/replay`, `aifsmjs/pbt`, `aifsmjs/timer`
-- `Runtime.onTransition` (added in 0.3.0) — pure sugar over the stable
-  `on('transition', ...)` API; listed under Stable because the underlying
-  contract is unchanged.
-
-### Sub-machines (stable since 0.4.0)
-
-The hierarchical sub-machine surface shipped experimentally in 0.3.0 is
-stable as of 0.4.0. Signatures and runtime semantics — including the
-init-failure quarantine behaviour described below — are frozen for the 1.x
-line. The boundaries listed are intentional design trade-offs, not bugs or
-pending instability.
-
-- `StateDef.sub` (optional `SubMachineDef`) — when present, a child runtime
-  is lazily initialised on entry and disposed on exit. Per-transition
-  ordering is parent `step()` (exit / actions / entry) → child dispose →
-  child init → snapshot commit.
-- `StateDef.subImpl` (optional `Implementations`) — paired with `sub`;
-  passed to the child `createRuntime`. Defaults to `{}`.
-- `Runtime.subRuntime()` — returns the live child handle, or `undefined`.
-  Returned generic is `Runtime<unknown, { type: string }, string>`; caller
-  narrows via cast if necessary.
-- `SubMachineError` — thrown by `send()` / `reset()` on child init/dispose
-  failure. Fields: `parentState`, `phase ("init" | "dispose")`, `cause`.
-- `SubMachineDef` type alias.
-
-#### Design boundaries
-
-- **Replay / PBT do not see child state.** `replay()` and
-  `commandsFromMachine` only inspect parent snapshots. If your business
-  logic lives in the parent layer, replay is still deterministic.
-- **`subRuntime()` may return a disposed handle** if an external caller
-  disposed it. The handle is not reinitialised until the parent leaves and
-  re-enters the sub-bearing state. Detect with `child.disposed`.
-- **Self-targeting external (`A → A`) is treated as full exit/entry**:
-  child is disposed and reinitialised. The dispatcher re-resolves guards to
-  identify the chosen transition before deciding external vs internal, so
-  guarded internal transitions on the same event do not trigger a reinit.
-- **Init-failure mid-transition leaves the parent without a live child.**
-  If `applySubLifecycle` successfully disposes the old child and then the
-  new child's `createRuntime` throws, the parent's snapshot is rolled back
-  to `prev` but `subRuntime()` returns `undefined`. Callers catching
-  `SubMachineError(phase: "init")` should treat the runtime as quarantined
-  — call `runtime.dispose()` (idempotent) or `runtime.reset()` (which
-  attempts re-init) before sending further events. This quarantine
-  behaviour is part of the stable contract; a future **major** version may
-  switch to a two-phase "init before dispose" commit strategy (a breaking
-  change reserved for 1.0+), but the current semantics are frozen for the
-  1.x line.
-
-## Experimental
-
-No experimental APIs as of 0.4.0. The 0.3.0 sub-machine surface graduated to
-Stable in 0.4.0 — see "Sub-machines" above.
-
-## Draft (planned, not implemented)
-
-API sketched, not shipped. May change before release.
-
-- `historyState` (candidate for a future minor) — opt-in pseudo-state that
-  remembers the last active sub-state on re-entry. Workaround in 0.3.0:
-  snapshot the sub-runtime's value on exit via `onTransition`, restore
-  manually.