aifsmjs 0.2.0 → 0.3.0

package/README.md

@@ -8,9 +8,9 @@
 
 > A small, strict FSM library for any TypeScript/JS app that needs deterministic, replayable state transitions. Lifecycle is a pure `step()` function. Chain-of-Responsibility intuition is reserved for cross-cutting concerns (observe / persist / replay), never for the transition core.
 
-**Primary audience**: developers building stateful flows — multi-step forms, checkout funnels, auth flows, tutorial sequences, document-status workflows, scene flow in interactive apps, and the same patterns in browser-based games (PixiJS / Svelte 5 / plain Canvas / WebGL). The core is **environment-neutral** (pure function + adapter boundary): browser, Node, Bun, Deno, Flutter WebView, and Web Workers all work. The Roadmap section keeps gaming-specific niceties (tick hook, ECS bridge) as opt-in subpaths, not core surface.
+Part of the [ai\*js micro-runtime ecosystem](https://github.com/yshengliao) — see also [aibridgejs](https://github.com/yshengliao/aibridgejs) (cross-context RPC) and [aiecsjs](https://github.com/yshengliao/aiecsjs) (ECS).
 
-> Traditional Chinese version: [README_ZHTW.md](README_ZHTW.md).
+**Primary audience**: developers building stateful flows — multi-step forms, checkout funnels, auth flows, tutorial sequences, document-status workflows, scene flow in interactive apps, and the same patterns in browser-based games (PixiJS / Svelte 5 / plain Canvas / WebGL). The core is **environment-neutral** (pure function + adapter boundary): browser, Node, Bun, Deno, Flutter WebView, and Web Workers all work. The Roadmap section keeps gaming-specific niceties (tick hook, ECS bridge) as opt-in subpaths, not core surface.
 
 ---
 
@@ -106,15 +106,16 @@ The three layers are fully decoupled: take `step()` alone for replay, take `Mach
 
 | Will do (v1)                                        | Won't do                                          |
 | --------------------------------------------------- | ------------------------------------------------- |
-| Flat states + transitions                           | Hierarchical / compound states                    |
+| Flat states + transitions                           | Parallel state regions                            |
+| Hierarchical sugar via `state.sub` (experimental, since 0.3.0) | Closures embedded in definition (breaks serialize) |
 | Guards (sync only; inline async throws `InvalidDefinitionError` at `defineMachine`; runtime throws `AsyncGuardError` on thenable return) | Async guards                                      |
 | Actions (assign + enqueue effects)                  | Async API inside an action (use an effect)        |
 | Fire-and-forget effects                             | Actor invocation / spawn                          |
 | Read-only inspect middleware                        | Cancellable transition middleware                 |
 | `replay(initial, log, def, impl)` pure function     | Time-travel debugger (v2 candidate)               |
 | `fast-check` `fc.commands` adapter                   | Custom PBT framework                               |
-| String ref + runtime injection                      | Closures embedded in definition (breaks serialize) |
-| Tree-shake friendly subpath exports                  | Single root import for everything                 |
+| String ref + runtime injection                      | Single root import for everything                 |
+| Tree-shake friendly subpath exports                  | ECS / Pixi bridges (opt-in subpath, not core)     |
 
 ---
 
@@ -356,6 +357,27 @@ Non-goals:
 - No async lifecycle hook
 - Inspect middleware cannot alter the transition outcome
 
+### Sub-machine lifecycle (since 0.3.0, experimental)
+
+When a state declares `sub`, the per-transition ordering is:
+
+1. Parent `step()` runs: `exit actions → transition.actions → entry actions`.
+2. Old child (if any) `dispose()` — synchronous; exceptions become
+   `SubMachineError(phase: "dispose")`.
+3. New child (if next state has `sub`) instantiation — exceptions become
+   `SubMachineError(phase: "init")`.
+4. Parent snapshot commits.
+5. Middleware pipeline runs.
+6. Effects dispatch.
+7. `'transition'` event emits to `on()` / `onTransition()` subscribers.
+
+If step 2 or 3 throws, the parent snapshot is **not** committed (rollback
+to `prev`); no middleware / effects / `'transition'` runs.
+
+`runtime.dispose()` cascades to the child via `controller.signal`'s abort
+listener and an explicit `child.dispose()` call. Cascade swallows child
+exceptions to honour the never-throws dispose contract.
+
 ---
 
 ## Lifecycle Protocol
@@ -438,7 +460,7 @@ Example-first, PBT-augmented. Lesson from jssm: "3000+ tests / 100% coverage" tu
 - **Example tests** (vitest): for every src module, write happy path + edge + error-message triplets.
 - **PBT smoke**: each generic property runs 50 iterations as an invariant guard, not as a coverage source.
 - **CI-enforced thresholds**: `@vitest/coverage-v8` is wired to **100% statements / 100% lines / 100% functions / ≥90% branches**. The few defensive invariant-guard branches (e.g. runtime determinism mismatch) carry `/* v8 ignore */` annotations with rationale.
-- **Size budget**: `scripts/check-size.mjs` enforces per-subpath gzip caps in CI — core ≤3 KB, replay ≤1.6 KB, pbt ≤4.5 KB, others ≤1 KB. Exceeding any cap fails the build.
+- **Size budget**: `scripts/check-size.mjs` enforces per-subpath gzip caps in CI — core ≤4.7 KB (raised in 0.3.0 for sub-machine sugar), replay ≤1.8 KB, pbt ≤5.5 KB (raised in 0.3.0 because `pbt` transitively imports `createRuntime`), others ≤1 KB. Exceeding any cap fails the build.
 
 ### The 6 built-in generic properties
 
@@ -458,7 +480,7 @@ Example-first, PBT-augmented. Lesson from jssm: "3000+ tests / 100% coverage" tu
 |                            | aifsmjs        | XState v5         | Robot3            | @xstate/store     | Zag.js            |
 | -------------------------- | -------------- | ----------------- | ----------------- | ----------------- | ----------------- |
 | Core size (gzip)           | ~2.8KB         | ~15KB             | ~1KB              | < 1KB             | per-component     |
-| Hierarchical states         | No (v1)        | Yes               | No                | N/A               | Yes               |
+| Hierarchical states         | Sugar (0.3.0)  | Yes               | No                | N/A               | Yes               |
 | Async invoke / actor        | No             | Yes               | No                | N/A               | No                |
 | Guard combinators           | and/or/not     | and/or/not        | No                | N/A               | No                |
 | Effects dual-track          | enqueue        | enqueueActions    | reduce/action     | enq.effect()      | array of names    |
@@ -474,12 +496,23 @@ Example-first, PBT-augmented. Lesson from jssm: "3000+ tests / 100% coverage" tu
 | Version | Scope                                                              |
 | ------- | ------------------------------------------------------------------ |
 | v0.1    | core + guards + effects + inspect + replay + pbt (this release)    |
-| v0.2    | Hierarchical / compound states, including entry/exit ordering       |
-| v0.3    | Parallel state regions                                              |
-| v0.4    | Actor invocation (async) and spawn                                  |
+| v0.2    | Async-guard detection, coverage tuning, llms-full.txt verify gate  |
+| v0.3    | Hierarchical sugar via `state.sub` (experimental, this release)    |
+| v0.4    | `historyState` — remember last active sub-state on re-entry        |
 | v0.5    | `aifsmjs-bridge-bitecs` / `aifsmjs-bridge-pixi` (separate sub-packages) |
 | v1.0    | API freeze and stability guarantee                                  |
 
+**Out of scope (v1)**:
+
+- **Parallel state regions** (out of scope for v1)
+- **Actor invocation / spawn** (out of scope for v1)
+- **Tick / game-loop hook** (out of scope for v1)
+- **ECS / Pixi bridges** (out of scope for v1)
+
+**v0.4 candidate**: `historyState` — remember last active sub-state on
+re-entry. Workaround today: snapshot via `onTransition` and restore
+manually.
+
 ---
 
 ## License

package/README_ZHTW.md

@@ -8,6 +8,8 @@
 
 > 一個小而嚴格的 FSM library，為任何需要可重現、可重播狀態流轉的 TypeScript/JS app 而生：把 lifecycle 寫成 pure `step()`，把 Chain-of-Responsibility 直覺收斂到 cross-cutting concerns（observe / persist / replay）── 而非 transition 主流程。
 
+隸屬 [ai\*js micro-runtime 生態系](https://github.com/yshengliao) ─ 另見 [aibridgejs](https://github.com/yshengliao/aibridgejs)（cross-context RPC）與 [aiecsjs](https://github.com/yshengliao/aiecsjs)（ECS）。
+
 **主要受眾**：所有處理 stateful flow 的工程師 ── 多步驟表單、checkout 流程、auth flow、教學引導步驟、文件審批狀態機、互動 app 的 scene flow，以及瀏覽器遊戲的相同模式（PixiJS / Svelte 5 / 純 Canvas / WebGL）。Library 本身**環境中立**（pure core + adapter 邊界）：browser、Node、Bun、Deno、Flutter WebView、Web Worker 全部都跑。Roadmap 段把遊戲特有的便利功能（tick hook、ECS bridge）保留為 opt-in subpath，不進 core surface。
 
 ---
@@ -103,15 +105,16 @@ console.log(runtime.getSnapshot().context); // { ticks: 1 }
 
 | 會做（v1）                                          | 不會做                                            |
 | --------------------------------------------------- | ------------------------------------------------- |
-| Flat states + transitions                           | Hierarchical / compound states                    |
+| Flat states + transitions                           | Parallel state regions                            |
+| 透過 `state.sub` 的階層式 sugar（experimental，since 0.3.0） | Definition 內直接綁 closure（會無法序列化）    |
 | Guards（sync only；inline async 在 `defineMachine` 時丟 `InvalidDefinitionError`；runtime 偵測到 thenable 回傳則丟 `AsyncGuardError`） | Async guards                                      |
 | Actions（assign + enqueue effects）                 | 在 action 內呼叫 async API（請放到 effect）        |
 | Fire-and-forget effects                             | Actor invocation / spawn                          |
 | Read-only inspect middleware                        | 可中止 transition 的 middleware                   |
 | `replay(initial, log, def, impl)` 純函式             | Time travel debugger（v2 再評估）                  |
 | `fast-check` `fc.commands` adapter                   | 自家 PBT framework                                 |
-| String ref + runtime injection                      | Definition 內直接綁 closure（會無法序列化）        |
-| Tree-shake friendly subpath exports                  | 從 root 一次 import 全部                           |
+| String ref + runtime injection                      | 從 root 一次 import 全部                           |
+| Tree-shake friendly subpath exports                  | ECS / Pixi bridges（opt-in subpath，不進 core）   |
 
 ---
 
@@ -353,6 +356,22 @@ sched.cancelAll();
 - async lifecycle hook
 - Inspect middleware 影響 transition 結果
 
+### Sub-machine lifecycle（since 0.3.0，experimental）
+
+當一個 state 宣告 `sub` 時，每次 transition 的執行順序為：
+
+1. Parent `step()` 執行：`exit actions → transition.actions → entry actions`。
+2. 舊 child（若有）`dispose()` — 同步執行；例外會包成 `SubMachineError(phase: "dispose")`。
+3. 新 child（若 next state 有 `sub`）實例化 — 例外會包成 `SubMachineError(phase: "init")`。
+4. Parent snapshot 確認提交。
+5. Middleware pipeline 執行。
+6. Effects 派發。
+7. `'transition'` 事件發給 `on()` / `onTransition()` 的訂閱者。
+
+若步驟 2 或 3 丟例外，parent snapshot **不會**提交（回滾至 `prev`）；middleware、effects、`'transition'` 都不會執行。
+
+`runtime.dispose()` 透過 `controller.signal` 的 abort listener 以及顯式的 `child.dispose()` 呼叫，將 dispose 行為串聯到 child。Cascade 會吞掉 child 的例外，以遵守永不丟錯的 dispose 契約。
+
 ---
 
 ## Lifecycle Protocol
@@ -435,7 +454,7 @@ aifsmjs 在幾個常見議題上做了刻意取捨，跟主流 FSM library 寫
 - **Example tests**（vitest）：對每個 src module 寫 happy path + 邊界 + error message 三類。
 - **PBT smoke**：每條 generic property 跑 50 runs，作為 invariant guard，不追求 coverage。
 - **CI 強制門檻**：`@vitest/coverage-v8` 設 **100% statements / 100% lines / 100% functions / ≥90% branches**。少數 defensive invariant-guard 分支（例如 runtime determinism mismatch）標 `/* v8 ignore */` 並寫明原因。
-- **Size budget**：`scripts/check-size.mjs` 在 CI 檢查每個 subpath gzip 大小，超過預算（core ≤3 KB、replay ≤1.6 KB、pbt ≤4.5 KB、其他 ≤1 KB）即 fail。
+- **Size budget**：`scripts/check-size.mjs` 在 CI 檢查每個 subpath gzip 大小，超過預算（core ≤4.7 KB、replay ≤1.8 KB、pbt ≤5.5 KB、其他 ≤1 KB；0.3.0 為了 sub-machine sugar 提高 core / pbt 上限）即 fail。
 
 ### 內建的 6 條 generic properties
 
@@ -455,7 +474,7 @@ aifsmjs 在幾個常見議題上做了刻意取捨，跟主流 FSM library 寫
 |                            | aifsmjs        | XState v5         | Robot3            | @xstate/store     | Zag.js            |
 | -------------------------- | -------------- | ----------------- | ----------------- | ----------------- | ----------------- |
 | Core size (gzip)           | ~2.8KB         | ~15KB             | ~1KB              | < 1KB             | per-component     |
-| Hierarchical states         | No (v1)        | Yes               | No                | N/A               | Yes               |
+| Hierarchical states         | Sugar (0.3.0)  | Yes               | No                | N/A               | Yes               |
 | Async invoke / actor        | No             | Yes               | No                | N/A               | No                |
 | Guard combinators           | and/or/not     | and/or/not        | No                | N/A               | No                |
 | Effects 雙軌                | enqueue        | enqueueActions    | reduce/action     | enq.effect()      | array of names    |
@@ -471,12 +490,21 @@ aifsmjs 在幾個常見議題上做了刻意取捨，跟主流 FSM library 寫
 | 版本 | 範圍                                                              |
 | ---- | ----------------------------------------------------------------- |
 | v0.1 | core + guards + effects + inspect + replay + pbt（本次發佈）       |
-| v0.2 | Hierarchical / compound states，含 entry/exit 階層順序             |
-| v0.3 | Parallel state regions                                             |
-| v0.4 | Actor invocation（async）與 spawn                                  |
+| v0.2 | Async-guard 偵測、coverage 調整、llms-full.txt verify gate        |
+| v0.3 | 透過 `state.sub` 的階層式 sugar（experimental，本次發佈）          |
+| v0.4 | `historyState` — re-entry 時恢復上一次的 sub-state                 |
 | v0.5 | `aifsmjs-bridge-bitecs` / `aifsmjs-bridge-pixi`（獨立 sub-package） |
 | v1.0 | API freeze 與 stability guarantee                                  |
 
+**不在 v1 範圍內**：
+
+- **Parallel state regions**（v1 不做）
+- **Actor invocation / spawn**（v1 不做）
+- **Tick / game-loop hook**（v1 不做）
+- **ECS / Pixi bridges**（v1 不做）
+
+**v0.4 候選**：`historyState` — re-entry 時自動恢復上一次的 sub-state。0.3.0 的暫代方案：透過 `onTransition` snapshot sub-runtime 的 value，之後手動還原。
+
 ---
 
 ## License

package/STABILITY.md

@@ -0,0 +1,77 @@
+# 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.
+
+## Experimental (since 0.3.0)
+
+Shape and behaviour may change in any minor bump until 1.0. Production use
+is OK; expect a one-line patch on minor upgrades.
+
+- `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.
+
+### Known boundaries (0.3.0)
+
+- **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 0.3.0 dispatcher re-resolves
+  guards to identify the chosen transition before deciding external vs
+  internal, so guarded internal transitions on the same event no longer
+  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. A future major may
+  switch to a two-phase "init before dispose" commit strategy; for 0.3.x
+  this remains opt-in only when child failures are expected.
+
+## Draft (planned, not implemented in 0.3.0)
+
+API sketched, not shipped. May change before release.
+
+- `historyState` (v0.4 candidate) — 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.

package/dist/effects/index.d.cts

@@ -1,4 +1,4 @@
-import { c as Enqueuer, E as Effect, b as EffectHandler } from '../types-BLwKAHnW.cjs';
+import { c as Enqueuer, E as Effect, b as EffectHandler } from '../types-CGKk6Rur.cjs';
 
 /**
  * Build a closure-based Enqueuer that pushes effects into the supplied sink.

package/dist/effects/index.d.ts

@@ -1,4 +1,4 @@
-import { c as Enqueuer, E as Effect, b as EffectHandler } from '../types-BLwKAHnW.js';
+import { c as Enqueuer, E as Effect, b as EffectHandler } from '../types-CGKk6Rur.js';
 
 /**
  * Build a closure-based Enqueuer that pushes effects into the supplied sink.

package/dist/guards/index.d.cts

@@ -1,4 +1,4 @@
-import { e as GuardRef, G as Guard } from '../types-BLwKAHnW.cjs';
+import { e as GuardRef, G as Guard } from '../types-CGKk6Rur.cjs';
 
 /** Logical AND over guards. Short-circuits on the first `false`. */
 declare function and<Ctx, Evt>(items: readonly GuardRef<Ctx, Evt>[]): Guard<Ctx, Evt>;

package/dist/guards/index.d.ts

@@ -1,4 +1,4 @@
-import { e as GuardRef, G as Guard } from '../types-BLwKAHnW.js';
+import { e as GuardRef, G as Guard } from '../types-CGKk6Rur.js';
 
 /** Logical AND over guards. Short-circuits on the first `false`. */
 declare function and<Ctx, Evt>(items: readonly GuardRef<Ctx, Evt>[]): Guard<Ctx, Evt>;

package/dist/index.cjs

@@ -192,6 +192,18 @@ var RuntimeDisposedError = class extends Error {
     this.name = "RuntimeDisposedError";
   }
 };
+var SubMachineError = class extends Error {
+  parentState;
+  phase;
+  cause;
+  constructor(parentState, phase, cause) {
+    super(`aifsmjs: sub-machine ${phase} failed at parent state "${parentState}"`, { cause });
+    this.name = "SubMachineError";
+    this.parentState = parentState;
+    this.phase = phase;
+    this.cause = cause;
+  }
+};
 var RESET_EVENT = Object.freeze({ type: RESET_EVENT_TYPE });
 function composeMiddleware(middleware) {
   return (ctx, finalNext) => {
@@ -216,6 +228,8 @@ function createRuntime(def, impl, opts = {}) {
   const shouldDispatch = opts.dispatchEffects !== false;
   const controller = new AbortController();
   let disposed = false;
+  let childRuntime;
+  let childAbortCleanup;
   const eventListeners = {
     transition: /* @__PURE__ */ new Set(),
     error: /* @__PURE__ */ new Set(),
@@ -231,14 +245,7 @@ function createRuntime(def, impl, opts = {}) {
   }
   function runMiddleware(prev, event, effects, changed) {
     if (!middlewareChain) return;
-    const mwCtx = deepFreeze({
-      prev,
-      next: snapshot,
-      event,
-      effects,
-      changed
-    });
-    middlewareChain(mwCtx, () => {
+    middlewareChain(deepFreeze({ prev, next: snapshot, event, effects, changed }), () => {
     });
   }
   function dispatchEffects(effects, context, event) {
@@ -249,52 +256,128 @@ function createRuntime(def, impl, opts = {}) {
       const r = handler(eff, { context, event, signal: controller.signal });
       if (r instanceof Promise) {
         r.catch((err) => {
-          const payload = { error: err, event };
-          emit("error", payload);
+          emit("error", { error: err, event });
         });
       }
     }
   }
+  function wireChildAbort(child) {
+    if (controller.signal.aborted) {
+      try {
+        child.dispose();
+      } catch {
+      }
+      return () => {
+      };
+    }
+    const onAbort = () => {
+      try {
+        child.dispose();
+      } catch {
+      }
+    };
+    controller.signal.addEventListener("abort", onAbort, { once: true });
+    return () => controller.signal.removeEventListener("abort", onAbort);
+  }
+  function findChosenIsExternal(value, event, context) {
+    const state = def.states[value];
+    if (!state?.on) return false;
+    const candidates = state.on[event.type];
+    if (!candidates) return false;
+    const list = Array.isArray(candidates) ? candidates : [candidates];
+    for (const t of list) {
+      if (!t.guard || evalGuard(t.guard, context, event, impl, value)) {
+        return t.target !== void 0;
+      }
+    }
+    return false;
+  }
+  function applySubLifecycle(prevValue, nextValue) {
+    const prevStateDef = def.states[prevValue];
+    const nextStateDef = def.states[nextValue];
+    if (prevStateDef?.sub !== void 0 && childRuntime !== void 0) {
+      const child = childRuntime;
+      childRuntime = void 0;
+      childAbortCleanup?.();
+      childAbortCleanup = void 0;
+      try {
+        child.dispose();
+      } catch (cause) {
+        throw new SubMachineError(prevValue, "dispose", cause);
+      }
+    }
+    if (nextStateDef?.sub !== void 0) {
+      let newChild;
+      try {
+        newChild = createRuntime(nextStateDef.sub, nextStateDef.subImpl ?? {});
+      } catch (cause) {
+        throw new SubMachineError(nextValue, "init", cause);
+      }
+      childRuntime = newChild;
+      childAbortCleanup = wireChildAbort(newChild);
+    }
+  }
   function send(event) {
     if (disposed) throw new RuntimeDisposedError();
     const prev = snapshot;
     const result = step(def, prev, event, impl);
+    const isExternal = result.changed && (prev.value !== result.snapshot.value || findChosenIsExternal(prev.value, event, prev.context));
+    if (result.changed && isExternal) applySubLifecycle(prev.value, result.snapshot.value);
     snapshot = result.snapshot;
     const committed = result.snapshot;
     runMiddleware(prev, event, result.effects, result.changed);
-    if (shouldDispatch) {
-      dispatchEffects(result.effects, committed.context, event);
-    }
+    if (shouldDispatch) dispatchEffects(result.effects, committed.context, event);
     if (result.changed) {
       notify(committed);
-      const payload = {
+      emit("transition", {
         prev,
         next: committed,
         event,
         effects: result.effects,
         changed: true
-      };
-      emit("transition", payload);
+      });
     }
     return snapshot;
   }
   function reset(event) {
     if (disposed) throw new RuntimeDisposedError();
     const prev = snapshot;
-    snapshot = initialSnapshot(def);
-    const changed = prev.value !== snapshot.value;
+    const nextSnap = initialSnapshot(def);
+    const changed = prev.value !== nextSnap.value;
+    if (childRuntime) {
+      const child = childRuntime;
+      childRuntime = void 0;
+      childAbortCleanup?.();
+      childAbortCleanup = void 0;
+      try {
+        child.dispose();
+      } catch (cause) {
+        throw new SubMachineError(prev.value, "dispose", cause);
+      }
+    }
+    const initStateDef = def.states[nextSnap.value];
+    if (initStateDef?.sub) {
+      let newChild;
+      try {
+        newChild = createRuntime(initStateDef.sub, initStateDef.subImpl ?? {});
+      } catch (cause) {
+        throw new SubMachineError(nextSnap.value, "init", cause);
+      }
+      childRuntime = newChild;
+      childAbortCleanup = wireChildAbort(newChild);
+    }
+    snapshot = nextSnap;
     const triggerEvent = event ?? RESET_EVENT;
     runMiddleware(prev, triggerEvent, [], changed);
     if (changed) {
       notify();
-      const payload = {
+      emit("transition", {
         prev,
         next: snapshot,
         event: triggerEvent,
         effects: [],
         changed: true
-      };
-      emit("transition", payload);
+      });
     }
     return snapshot;
   }
@@ -345,6 +428,15 @@ function createRuntime(def, impl, opts = {}) {
   function dispose() {
     if (disposed) return;
     disposed = true;
+    if (childRuntime) {
+      childAbortCleanup?.();
+      childAbortCleanup = void 0;
+      try {
+        childRuntime.dispose();
+      } catch {
+      }
+      childRuntime = void 0;
+    }
     controller.abort();
     listeners.clear();
     emit("dispose", void 0);
@@ -352,7 +444,7 @@ function createRuntime(def, impl, opts = {}) {
     for (const cleanup of externalAbortCleanups) cleanup();
     externalAbortCleanups.clear();
   }
-  return {
+  const runtime = {
     getSnapshot: () => snapshot,
     snapshot: () => snapshot,
     send,
@@ -371,8 +463,22 @@ function createRuntime(def, impl, opts = {}) {
       };
       listeners.add(listener);
       return () => listeners.delete(listener);
-    }
+    },
+    subRuntime: () => childRuntime,
+    onTransition: (handler, options) => on("transition", handler, options)
   };
+  const bootStateDef = def.states[snapshot.value];
+  if (bootStateDef?.sub) {
+    let newChild;
+    try {
+      newChild = createRuntime(bootStateDef.sub, bootStateDef.subImpl ?? {});
+    } catch (cause) {
+      throw new SubMachineError(snapshot.value, "init", cause);
+    }
+    childRuntime = newChild;
+    childAbortCleanup = wireChildAbort(newChild);
+  }
+  return runtime;
 }
 
 // src/fsm/definition.ts
@@ -399,6 +505,15 @@ function validateDefinition(def) {
     );
   }
   for (const [stateName, stateDef] of Object.entries(def.states)) {
+    if (stateDef.sub !== void 0) {
+      const sub = stateDef.sub;
+      const subStates = sub.states;
+      if (typeof sub !== "object" || sub === null || typeof subStates !== "object" || subStates === null || typeof sub.initial !== "string") {
+        throw new InvalidDefinitionError(
+          `state "${stateName}".sub is not a valid sub-machine definition (missing states or initial)`
+        );
+      }
+    }
     if (!stateDef.on) continue;
     for (const [evtType, entry] of Object.entries(stateDef.on)) {
       const transitions = Array.isArray(entry) ? entry : [entry];
@@ -455,6 +570,7 @@ exports.AsyncGuardError = AsyncGuardError;
 exports.InvalidDefinitionError = InvalidDefinitionError;
 exports.RESET_EVENT_TYPE = RESET_EVENT_TYPE;
 exports.RuntimeDisposedError = RuntimeDisposedError;
+exports.SubMachineError = SubMachineError;
 exports.UnknownActionError = UnknownActionError;
 exports.UnknownGuardError = UnknownGuardError;
 exports.assign = assign;