aifsmjs 0.5.0 → 0.5.2

package/README.md

@@ -207,7 +207,7 @@ function step<C, E, S>(
 ): { snapshot: Snapshot<C, S>; effects: readonly Effect[] };
 ```
 
-**Pure function**. The invariant keeper for the whole library. It never dispatches effects, never mutates the snapshot, and never throws — a failing guard or unmapped event simply returns the original snapshot.
+**Pure function**. The invariant keeper for the whole library. It never dispatches effects and never mutates the snapshot. A failing guard or unmapped event simply returns the original snapshot unchanged. It does throw on misuse (`UnknownGuardError`, `UnknownActionError`, `AsyncGuardError`) so guard/action wiring errors surface at development time rather than silently passing.
 
 ### `assign(updater)`
 
@@ -266,7 +266,7 @@ const runtime = createRuntime(def, impl, {
 });
 ```
 
-Koa-style `(ctx, next) => void` pipeline. `ctx` is `{ prev, next, event, effects }`, all `structuredClone`d and frozen. **Cannot cancel a transition** — `next()` must be called; the return value carries no meaning.
+Koa-style `(ctx, next) => void` pipeline. `ctx` is `{ prev, next, event, effects, changed }`, all deep-frozen. **Cannot cancel a transition** — `next()` must be called; the return value carries no meaning.
 
 ### `aifsmjs/replay` — Pure event log replay
 
@@ -285,14 +285,25 @@ Never dispatches effects. For PBT, time-travel debugging, and incident reproduct
 
 ```typescript
 import fc from "fast-check";
-import { commandsFromMachine, properties } from "aifsmjs/pbt";
+import { createRuntime } from "aifsmjs";
+import { commandsFromMachine, initialModel, properties } from "aifsmjs/pbt";
+
+// Use one of the six built-in generic properties, or assertAll for all at once:
+properties.replayEqualsFold(def, impl, {
+  NEXT: fc.constant({ type: "NEXT" as const }),
+});
 
+// Or build a custom property using commandsFromMachine:
 fc.assert(
   fc.property(
     commandsFromMachine(def, impl, {
       NEXT: fc.constant({ type: "NEXT" as const }),
     }),
-    (cmds) => properties.runDeterministic(def, impl, cmds),
+    (cmds) => {
+      const real = createRuntime(def, impl, { dispatchEffects: false });
+      fc.modelRun(() => ({ model: initialModel(def), real }), cmds);
+      return true;
+    },
   ),
 );
 ```

package/README_ZHTW.md

@@ -206,7 +206,7 @@ function step<C, E, S>(
 ): { snapshot: Snapshot<C, S>; effects: readonly Effect[] };
 ```
 
-**Pure function**。整個 library 的 invariant 守護者。不會 dispatch effects、不會 mutate snapshot、不會丟錯——guard 沒過或 event 沒對應 transition 就回原 snapshot。
+**Pure function**。整個 library 的 invariant 守護者。不會 dispatch effects、不會 mutate snapshot。Guard 沒過或 event 沒對應 transition 就回原 snapshot（不改變）。誤用（`UnknownGuardError`、`UnknownActionError`、`AsyncGuardError`）才會丟錯，讓配接錯誤在開發期間立即浮現、不被靜默略過。
 
 ### `assign(updater)`
 
@@ -265,7 +265,7 @@ const runtime = createRuntime(def, impl, {
 });
 ```
 
-Koa-style `(ctx, next) => void` pipeline。`ctx` 是 `{ prev, next, event, effects }`，全部 `structuredClone + freeze`。**不能中止 transition**——`next()` 必呼叫，回傳值無語意。
+Koa-style `(ctx, next) => void` pipeline。`ctx` 是 `{ prev, next, event, effects, changed }`，全部 deep-frozen。**不能中止 transition**——`next()` 必呼叫，回傳值無語意。
 
 ### `aifsmjs/replay` — Pure event log replay
 
@@ -284,14 +284,25 @@ const finalSnap = replay(initialSnapshot, eventLog, def, impl);
 
 ```typescript
 import fc from "fast-check";
-import { commandsFromMachine, properties } from "aifsmjs/pbt";
+import { createRuntime } from "aifsmjs";
+import { commandsFromMachine, initialModel, properties } from "aifsmjs/pbt";
+
+// 用任一內建 generic property，或 assertAll 一次跑全部：
+properties.replayEqualsFold(def, impl, {
+  NEXT: fc.constant({ type: "NEXT" as const }),
+});
 
+// 或用 commandsFromMachine 自訂 property：
 fc.assert(
   fc.property(
     commandsFromMachine(def, impl, {
       NEXT: fc.constant({ type: "NEXT" as const }),
     }),
-    (cmds) => properties.runDeterministic(def, impl, cmds),
+    (cmds) => {
+      const real = createRuntime(def, impl, { dispatchEffects: false });
+      fc.modelRun(() => ({ model: initialModel(def), real }), cmds);
+      return true;
+    },
   ),
 );
 ```
@@ -398,7 +409,7 @@ aifsmjs 在幾個常見議題上做了刻意取捨，跟主流 FSM library 寫
 
 - **`send()` 是同步、回傳 `Snapshot` 而非 `Promise<Snapshot>`**。Pure `step()` 設計上就是 sync，`replay(initial, log)` 與 PBT shrinking 才能單純。Effect handler 仍可 async；runtime 觸發後忽略結果，async rejection 走 `'error'` event channel。要 await effect 完成的人可自己包一層 `Promise.all`。
 - **Guards / reducers 只能 sync**。非確定性 guard 會破壞 PBT determinism property (#1)。把 async 改寫成 event：先送 `FETCH_REQUEST`，handler 完成後送 `FETCH_DONE`，payload 帶結果。
-- **Effects 是描述子，不是 inline callback**。Action 透過 `enqueue.effect({ type, payload })` 排隊；runtime 收集後 dispatcher 才執行 user handler。好處：machine definition 可序列化（沒 inline fn 時 JSON round-trip）、`replay()` 可把 event log 摺成同樣 snapshot、`inspect/persist` middleware 抓得到 effects 做 audit log。
+- **Effects 是描述子，不是 inline callback**。Action 透過 `enqueue.effect(type, payload?)` 排隊；runtime 收集後 dispatcher 才執行 user handler。好處：machine definition 可序列化（沒 inline fn 時 JSON round-trip）、`replay()` 可把 event log 摺成同樣 snapshot、`inspect/persist` middleware 抓得到 effects 做 audit log。
 - **兩種 factory 並存**。`setup<Ctx, Evt>().defineMachine(...)` 是型別友善版（States 從 `keyof states` 推導）。`createMachine(def, impl, opts?)` 是來自 ai*js 生態 spec 的 single-factory 捷徑。顯式 `defineMachine<Ctx, Evt, States>(def)` 仍保留作完全顯式控制。看 call site 哪個讀起來順手就用哪個。
 - **`subscribe(listener)` 與 `on(type, fn, { signal, once })` 並存**。Typed `on()` 對齊平台 `EventTarget` 語意（signal + once），emit `'transition'`、`'error'`、`'dispose'`。原本的 `subscribe()` 保留 React `useSyncExternalStore` shape，可直接傳。兩者不互斥。
 

package/dist/timer/index.cjs

@@ -14,17 +14,20 @@ function after(ms, fn, opts) {
   const { st, ct } = resolveTimers(opts);
   let fired = false;
   let cancelled = false;
-  const handle = st(() => {
-    fired = true;
-    if (cancelled) return;
-    fn();
-  }, ms);
+  const timer = {};
   const cancel = () => {
     if (fired || cancelled) return;
     cancelled = true;
-    ct(handle);
+    if (timer.handle !== void 0) ct(timer.handle);
+    if (opts?.signal) opts.signal.removeEventListener("abort", cancel);
   };
-  if (opts?.signal) {
+  timer.handle = st(() => {
+    fired = true;
+    if (cancelled) return;
+    if (opts?.signal) opts.signal.removeEventListener("abort", cancel);
+    fn();
+  }, ms);
+  if (opts?.signal && !fired) {
     opts.signal.addEventListener("abort", cancel, { once: true });
   }
   return Object.freeze({ cancel });

package/dist/timer/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/timer/scheduler.ts"],"names":[],"mappings":";;;AAuBA,IAAM,IAAA,GAAoB,MAAA,CAAO,MAAA,CAAO,EAAE,QAAQ,MAAM;AAAC,CAAA,EAAG,CAAA;AAE5D,SAAS,cAAc,IAAA,EAGrB;AACA,EAAA,OAAO;AAAA,IACL,EAAA,EAAI,MAAM,UAAA,KAAe,CAAC,IAAI,EAAA,KAAO,UAAA,CAAW,UAAA,CAAW,EAAA,EAAI,EAAE,CAAA,CAAA;AAAA,IACjE,IAAI,IAAA,EAAM,YAAA,KAAiB,CAAC,CAAA,KAAM,UAAA,CAAW,aAAa,CAAW,CAAA;AAAA,GACvE;AACF;AAUO,SAAS,KAAA,CAAM,EAAA,EAAY,EAAA,EAAgB,IAAA,EAAkC;AAClF,EAAA,IAAI,IAAA,EAAM,MAAA,EAAQ,OAAA,EAAS,OAAO,IAAA;AAElC,EAAA,MAAM,EAAE,EAAA,EAAI,EAAA,EAAG,GAAI,cAAc,IAAI,CAAA;AACrC,EAAA,IAAI,KAAA,GAAQ,KAAA;AACZ,EAAA,IAAI,SAAA,GAAY,KAAA;AAEhB,EAAA,MAAM,MAAA,GAAS,GAAG,MAAM;AACtB,IAAA,KAAA,GAAQ,IAAA;AAER,IAAA,IAAI,SAAA,EAAW;AACf,IAAA,EAAA,EAAG;AAAA,EACL,GAAG,EAAE,CAAA;AAEL,EAAA,MAAM,SAAS,MAAM;AACnB,IAAA,IAAI,SAAS,SAAA,EAAW;AACxB,IAAA,SAAA,GAAY,IAAA;AACZ,IAAA,EAAA,CAAG,MAAM,CAAA;AAAA,EACX,CAAA;AAEA,EAAA,IAAI,MAAM,MAAA,EAAQ;AAChB,IAAA,IAAA,CAAK,OAAO,gBAAA,CAAiB,OAAA,EAAS,QAAQ,EAAE,IAAA,EAAM,MAAM,CAAA;AAAA,EAC9D;AAEA,EAAA,OAAO,MAAA,CAAO,MAAA,CAAO,EAAE,MAAA,EAAQ,CAAA;AACjC;AAgBO,SAAS,gBAAgB,QAAA,EAAoC;AAClE,EAAA,MAAM,OAAA,uBAAc,GAAA,EAAiB;AAErC,EAAA,MAAM,KAAA,GAAmB;AAAA,IACvB,KAAA,CAAM,EAAA,EAAI,EAAA,EAAI,IAAA,EAAM;AAClB,MAAA,MAAM,MAAA,GAAuB,EAAE,GAAG,QAAA,EAAU,GAAG,IAAA,EAAK;AAGpD,MAAA,MAAM,OAA8B,EAAC;AACrC,MAAA,MAAM,UAAU,MAAM;AACpB,QAAA,IAAI,IAAA,CAAK,GAAA,EAAK,OAAA,CAAQ,MAAA,CAAO,KAAK,GAAG,CAAA;AACrC,QAAA,EAAA,EAAG;AAAA,MACL,CAAA;AACA,MAAA,MAAM,KAAA,GAAQ,KAAA,CAAM,EAAA,EAAI,OAAA,EAAS,MAAM,CAAA;AACvC,MAAA,MAAM,MAAA,GAAsB,OAAO,MAAA,CAAO;AAAA,QACxC,MAAA,GAAS;AACP,UAAA,KAAA,CAAM,MAAA,EAAO;AACb,UAAA,IAAI,IAAA,CAAK,GAAA,EAAK,OAAA,CAAQ,MAAA,CAAO,KAAK,GAAG,CAAA;AAAA,QACvC;AAAA,OACD,CAAA;AACD,MAAA,IAAA,CAAK,GAAA,GAAM,MAAA;AACX,MAAA,OAAA,CAAQ,IAAI,MAAM,CAAA;AAClB,MAAA,OAAO,MAAA;AAAA,IACT,CAAA;AAAA,IACA,SAAA,GAAY;AACV,MAAA,KAAA,MAAW,CAAA,IAAK,OAAA,EAAS,CAAA,CAAE,MAAA,EAAO;AAClC,MAAA,OAAA,CAAQ,KAAA,EAAM;AAAA,IAChB,CAAA;AAAA,IACA,IAAI,IAAA,GAAO;AACT,MAAA,OAAO,OAAA,CAAQ,IAAA;AAAA,IACjB;AAAA,GACF;AACA,EAAA,OAAO,KAAA;AACT","file":"index.cjs","sourcesContent":["export type AfterHandle = Readonly<{\n  cancel(): void;\n}>;\n\nexport type SetTimeoutFn = (fn: () => void, ms: number) => unknown;\nexport type ClearTimeoutFn = (handle: unknown) => void;\n\nexport type AfterOptions = Readonly<{\n  /**\n   * If supplied and aborted, the callback never runs and any pending timer is\n   * cleared. Aborting after fire is a no-op.\n   */\n  signal?: AbortSignal;\n  /**\n   * Override `setTimeout` (testing, SSR, custom loops). Defaults to globalThis.\n   */\n  setTimeout?: SetTimeoutFn;\n  /**\n   * Override `clearTimeout`. Must match the `setTimeout` you injected.\n   */\n  clearTimeout?: ClearTimeoutFn;\n}>;\n\nconst NOOP: AfterHandle = Object.freeze({ cancel: () => {} });\n\nfunction resolveTimers(opts: AfterOptions | undefined): {\n  st: SetTimeoutFn;\n  ct: ClearTimeoutFn;\n} {\n  return {\n    st: opts?.setTimeout ?? ((fn, ms) => globalThis.setTimeout(fn, ms)),\n    ct: opts?.clearTimeout ?? ((h) => globalThis.clearTimeout(h as number)),\n  };\n}\n\n/**\n * Schedule `fn` to run after `ms` milliseconds. Returns a handle whose\n * `cancel()` clears the pending timer. Optional `signal` aborts the timer when\n * triggered. Aborting after the callback fires is a no-op.\n *\n * Per Node guidance, the abort listener is registered with `{ once: true }` to\n * avoid leaking listeners when the same signal is reused across many timers.\n */\nexport function after(ms: number, fn: () => void, opts?: AfterOptions): AfterHandle {\n  if (opts?.signal?.aborted) return NOOP;\n\n  const { st, ct } = resolveTimers(opts);\n  let fired = false;\n  let cancelled = false;\n\n  const handle = st(() => {\n    fired = true;\n    /* v8 ignore next — defensive race guard: cancel() sets cancelled=true and clears the timer, but if a custom setTimeout fires after clear, this short-circuits fn(). */\n    if (cancelled) return;\n    fn();\n  }, ms);\n\n  const cancel = () => {\n    if (fired || cancelled) return;\n    cancelled = true;\n    ct(handle);\n  };\n\n  if (opts?.signal) {\n    opts.signal.addEventListener(\"abort\", cancel, { once: true });\n  }\n\n  return Object.freeze({ cancel });\n}\n\nexport type Scheduler = Readonly<{\n  after(ms: number, fn: () => void, opts?: AfterOptions): AfterHandle;\n  cancelAll(): void;\n  readonly size: number;\n}>;\n\n/**\n * Build a scheduler that tracks every pending `after()` so they can be\n * cancelled together (e.g. on machine destroy). Each `after` returns a handle\n * whose `cancel()` also removes it from the tracking set.\n *\n * `defaults` are merged into every call — typically you inject `setTimeout` /\n * `clearTimeout` once at construction.\n */\nexport function createScheduler(defaults?: AfterOptions): Scheduler {\n  const pending = new Set<AfterHandle>();\n\n  const sched: Scheduler = {\n    after(ms, fn, opts) {\n      const merged: AfterOptions = { ...defaults, ...opts };\n      // Forward-reference slot so `wrapped` can find the tracked handle\n      // before it is constructed below.\n      const slot: { ref?: AfterHandle } = {};\n      const wrapped = () => {\n        if (slot.ref) pending.delete(slot.ref);\n        fn();\n      };\n      const inner = after(ms, wrapped, merged);\n      const handle: AfterHandle = Object.freeze({\n        cancel() {\n          inner.cancel();\n          if (slot.ref) pending.delete(slot.ref);\n        },\n      });\n      slot.ref = handle;\n      pending.add(handle);\n      return handle;\n    },\n    cancelAll() {\n      for (const h of pending) h.cancel();\n      pending.clear();\n    },\n    get size() {\n      return pending.size;\n    },\n  };\n  return sched;\n}\n"]}
+{"version":3,"sources":["../../src/timer/scheduler.ts"],"names":[],"mappings":";;;AAuBA,IAAM,IAAA,GAAoB,MAAA,CAAO,MAAA,CAAO,EAAE,QAAQ,MAAM;AAAC,CAAA,EAAG,CAAA;AAE5D,SAAS,cAAc,IAAA,EAGrB;AACA,EAAA,OAAO;AAAA,IACL,EAAA,EAAI,MAAM,UAAA,KAAe,CAAC,IAAI,EAAA,KAAO,UAAA,CAAW,UAAA,CAAW,EAAA,EAAI,EAAE,CAAA,CAAA;AAAA,IACjE,IAAI,IAAA,EAAM,YAAA,KAAiB,CAAC,CAAA,KAAM,UAAA,CAAW,aAAa,CAAW,CAAA;AAAA,GACvE;AACF;AAeO,SAAS,KAAA,CAAM,EAAA,EAAY,EAAA,EAAgB,IAAA,EAAkC;AAClF,EAAA,IAAI,IAAA,EAAM,MAAA,EAAQ,OAAA,EAAS,OAAO,IAAA;AAElC,EAAA,MAAM,EAAE,EAAA,EAAI,EAAA,EAAG,GAAI,cAAc,IAAI,CAAA;AACrC,EAAA,IAAI,KAAA,GAAQ,KAAA;AACZ,EAAA,IAAI,SAAA,GAAY,KAAA;AAOhB,EAAA,MAAM,QAA4C,EAAC;AAEnD,EAAA,MAAM,SAAS,MAAM;AACnB,IAAA,IAAI,SAAS,SAAA,EAAW;AACxB,IAAA,SAAA,GAAY,IAAA;AACZ,IAAA,IAAI,KAAA,CAAM,MAAA,KAAW,MAAA,EAAW,EAAA,CAAG,MAAM,MAAM,CAAA;AAG/C,IAAA,IAAI,MAAM,MAAA,EAAQ,IAAA,CAAK,MAAA,CAAO,mBAAA,CAAoB,SAAS,MAAM,CAAA;AAAA,EACnE,CAAA;AAEA,EAAA,KAAA,CAAM,MAAA,GAAS,GAAG,MAAM;AACtB,IAAA,KAAA,GAAQ,IAAA;AAER,IAAA,IAAI,SAAA,EAAW;AAGf,IAAA,IAAI,MAAM,MAAA,EAAQ,IAAA,CAAK,MAAA,CAAO,mBAAA,CAAoB,SAAS,MAAM,CAAA;AACjE,IAAA,EAAA,EAAG;AAAA,EACL,GAAG,EAAE,CAAA;AAKL,EAAA,IAAI,IAAA,EAAM,MAAA,IAAU,CAAC,KAAA,EAAO;AAC1B,IAAA,IAAA,CAAK,OAAO,gBAAA,CAAiB,OAAA,EAAS,QAAQ,EAAE,IAAA,EAAM,MAAM,CAAA;AAAA,EAC9D;AAEA,EAAA,OAAO,MAAA,CAAO,MAAA,CAAO,EAAE,MAAA,EAAQ,CAAA;AACjC;AAgBO,SAAS,gBAAgB,QAAA,EAAoC;AAClE,EAAA,MAAM,OAAA,uBAAc,GAAA,EAAiB;AAErC,EAAA,MAAM,KAAA,GAAmB;AAAA,IACvB,KAAA,CAAM,EAAA,EAAI,EAAA,EAAI,IAAA,EAAM;AAClB,MAAA,MAAM,MAAA,GAAuB,EAAE,GAAG,QAAA,EAAU,GAAG,IAAA,EAAK;AAGpD,MAAA,MAAM,OAA8B,EAAC;AACrC,MAAA,MAAM,UAAU,MAAM;AACpB,QAAA,IAAI,IAAA,CAAK,GAAA,EAAK,OAAA,CAAQ,MAAA,CAAO,KAAK,GAAG,CAAA;AACrC,QAAA,EAAA,EAAG;AAAA,MACL,CAAA;AACA,MAAA,MAAM,KAAA,GAAQ,KAAA,CAAM,EAAA,EAAI,OAAA,EAAS,MAAM,CAAA;AACvC,MAAA,MAAM,MAAA,GAAsB,OAAO,MAAA,CAAO;AAAA,QACxC,MAAA,GAAS;AACP,UAAA,KAAA,CAAM,MAAA,EAAO;AACb,UAAA,IAAI,IAAA,CAAK,GAAA,EAAK,OAAA,CAAQ,MAAA,CAAO,KAAK,GAAG,CAAA;AAAA,QACvC;AAAA,OACD,CAAA;AACD,MAAA,IAAA,CAAK,GAAA,GAAM,MAAA;AACX,MAAA,OAAA,CAAQ,IAAI,MAAM,CAAA;AAClB,MAAA,OAAO,MAAA;AAAA,IACT,CAAA;AAAA,IACA,SAAA,GAAY;AACV,MAAA,KAAA,MAAW,CAAA,IAAK,OAAA,EAAS,CAAA,CAAE,MAAA,EAAO;AAClC,MAAA,OAAA,CAAQ,KAAA,EAAM;AAAA,IAChB,CAAA;AAAA,IACA,IAAI,IAAA,GAAO;AACT,MAAA,OAAO,OAAA,CAAQ,IAAA;AAAA,IACjB;AAAA,GACF;AACA,EAAA,OAAO,KAAA;AACT","file":"index.cjs","sourcesContent":["export type AfterHandle = Readonly<{\n  cancel(): void;\n}>;\n\nexport type SetTimeoutFn = (fn: () => void, ms: number) => unknown;\nexport type ClearTimeoutFn = (handle: unknown) => void;\n\nexport type AfterOptions = Readonly<{\n  /**\n   * If supplied and aborted, the callback never runs and any pending timer is\n   * cleared. Aborting after fire is a no-op.\n   */\n  signal?: AbortSignal;\n  /**\n   * Override `setTimeout` (testing, SSR, custom loops). Defaults to globalThis.\n   */\n  setTimeout?: SetTimeoutFn;\n  /**\n   * Override `clearTimeout`. Must match the `setTimeout` you injected.\n   */\n  clearTimeout?: ClearTimeoutFn;\n}>;\n\nconst NOOP: AfterHandle = Object.freeze({ cancel: () => {} });\n\nfunction resolveTimers(opts: AfterOptions | undefined): {\n  st: SetTimeoutFn;\n  ct: ClearTimeoutFn;\n} {\n  return {\n    st: opts?.setTimeout ?? ((fn, ms) => globalThis.setTimeout(fn, ms)),\n    ct: opts?.clearTimeout ?? ((h) => globalThis.clearTimeout(h as number)),\n  };\n}\n\n/**\n * Schedule `fn` to run after `ms` milliseconds. Returns a handle whose\n * `cancel()` clears the pending timer. Optional `signal` aborts the timer when\n * triggered. Aborting after the callback fires is a no-op.\n *\n * The abort listener is registered with `{ once: true }` as a baseline, but\n * `{ once: true }` alone does NOT prevent listener accumulation when the same\n * signal is reused across many timers: it only removes the listener when the\n * signal aborts, not when the timer fires normally or `cancel()` is called.\n * We therefore explicitly call `signal.removeEventListener(\"abort\", cancel)`\n * inside the fire callback and at the end of `cancel()` so that a shared,\n * long-lived signal never accumulates dead listeners across timer reuse.\n */\nexport function after(ms: number, fn: () => void, opts?: AfterOptions): AfterHandle {\n  if (opts?.signal?.aborted) return NOOP;\n\n  const { st, ct } = resolveTimers(opts);\n  let fired = false;\n  let cancelled = false;\n  // `cancel` and the timer handle reference each other. A const cell holds the\n  // handle so `cancel` can be defined BEFORE `st(...)` runs (letting a custom\n  // `st` that fires its callback synchronously reference `cancel` without\n  // hitting the temporal-dead-zone) while still being able to clear the handle\n  // assigned afterwards. A synchronous fire sets `fired=true`, so cancel() never\n  // reads the still-unset handle in that path.\n  const timer: { handle?: ReturnType<typeof st> } = {};\n\n  const cancel = () => {\n    if (fired || cancelled) return;\n    cancelled = true;\n    if (timer.handle !== undefined) ct(timer.handle);\n    // Detach the abort listener so a reused signal does not accumulate dead\n    // closures after this timer is cancelled.\n    if (opts?.signal) opts.signal.removeEventListener(\"abort\", cancel);\n  };\n\n  timer.handle = st(() => {\n    fired = true;\n    /* v8 ignore next — defensive race guard: cancel() sets cancelled=true and clears the timer, but if a custom setTimeout fires after clear, this short-circuits fn(). */\n    if (cancelled) return;\n    // Detach the abort listener now that the timer has fired — the listener\n    // will never be invoked and must not accumulate on a reused signal.\n    if (opts?.signal) opts.signal.removeEventListener(\"abort\", cancel);\n    fn();\n  }, ms);\n\n  // Attach only if the timer has not already fired synchronously (a custom `st`\n  // may fire inline); otherwise the listener would be registered AFTER the fire\n  // path's removal ran and would then leak until the signal aborts.\n  if (opts?.signal && !fired) {\n    opts.signal.addEventListener(\"abort\", cancel, { once: true });\n  }\n\n  return Object.freeze({ cancel });\n}\n\nexport type Scheduler = Readonly<{\n  after(ms: number, fn: () => void, opts?: AfterOptions): AfterHandle;\n  cancelAll(): void;\n  readonly size: number;\n}>;\n\n/**\n * Build a scheduler that tracks every pending `after()` so they can be\n * cancelled together (e.g. on machine destroy). Each `after` returns a handle\n * whose `cancel()` also removes it from the tracking set.\n *\n * `defaults` are merged into every call — typically you inject `setTimeout` /\n * `clearTimeout` once at construction.\n */\nexport function createScheduler(defaults?: AfterOptions): Scheduler {\n  const pending = new Set<AfterHandle>();\n\n  const sched: Scheduler = {\n    after(ms, fn, opts) {\n      const merged: AfterOptions = { ...defaults, ...opts };\n      // Forward-reference slot so `wrapped` can find the tracked handle\n      // before it is constructed below.\n      const slot: { ref?: AfterHandle } = {};\n      const wrapped = () => {\n        if (slot.ref) pending.delete(slot.ref);\n        fn();\n      };\n      const inner = after(ms, wrapped, merged);\n      const handle: AfterHandle = Object.freeze({\n        cancel() {\n          inner.cancel();\n          if (slot.ref) pending.delete(slot.ref);\n        },\n      });\n      slot.ref = handle;\n      pending.add(handle);\n      return handle;\n    },\n    cancelAll() {\n      for (const h of pending) h.cancel();\n      pending.clear();\n    },\n    get size() {\n      return pending.size;\n    },\n  };\n  return sched;\n}\n"]}

package/dist/timer/index.d.cts

@@ -23,8 +23,13 @@ type AfterOptions = Readonly<{
  * `cancel()` clears the pending timer. Optional `signal` aborts the timer when
  * triggered. Aborting after the callback fires is a no-op.
  *
- * Per Node guidance, the abort listener is registered with `{ once: true }` to
- * avoid leaking listeners when the same signal is reused across many timers.
+ * The abort listener is registered with `{ once: true }` as a baseline, but
+ * `{ once: true }` alone does NOT prevent listener accumulation when the same
+ * signal is reused across many timers: it only removes the listener when the
+ * signal aborts, not when the timer fires normally or `cancel()` is called.
+ * We therefore explicitly call `signal.removeEventListener("abort", cancel)`
+ * inside the fire callback and at the end of `cancel()` so that a shared,
+ * long-lived signal never accumulates dead listeners across timer reuse.
  */
 declare function after(ms: number, fn: () => void, opts?: AfterOptions): AfterHandle;
 type Scheduler = Readonly<{

package/dist/timer/index.d.ts

@@ -23,8 +23,13 @@ type AfterOptions = Readonly<{
  * `cancel()` clears the pending timer. Optional `signal` aborts the timer when
  * triggered. Aborting after the callback fires is a no-op.
  *
- * Per Node guidance, the abort listener is registered with `{ once: true }` to
- * avoid leaking listeners when the same signal is reused across many timers.
+ * The abort listener is registered with `{ once: true }` as a baseline, but
+ * `{ once: true }` alone does NOT prevent listener accumulation when the same
+ * signal is reused across many timers: it only removes the listener when the
+ * signal aborts, not when the timer fires normally or `cancel()` is called.
+ * We therefore explicitly call `signal.removeEventListener("abort", cancel)`
+ * inside the fire callback and at the end of `cancel()` so that a shared,
+ * long-lived signal never accumulates dead listeners across timer reuse.
  */
 declare function after(ms: number, fn: () => void, opts?: AfterOptions): AfterHandle;
 type Scheduler = Readonly<{

package/dist/timer/index.js

@@ -12,17 +12,20 @@ function after(ms, fn, opts) {
   const { st, ct } = resolveTimers(opts);
   let fired = false;
   let cancelled = false;
-  const handle = st(() => {
-    fired = true;
-    if (cancelled) return;
-    fn();
-  }, ms);
+  const timer = {};
   const cancel = () => {
     if (fired || cancelled) return;
     cancelled = true;
-    ct(handle);
+    if (timer.handle !== void 0) ct(timer.handle);
+    if (opts?.signal) opts.signal.removeEventListener("abort", cancel);
   };
-  if (opts?.signal) {
+  timer.handle = st(() => {
+    fired = true;
+    if (cancelled) return;
+    if (opts?.signal) opts.signal.removeEventListener("abort", cancel);
+    fn();
+  }, ms);
+  if (opts?.signal && !fired) {
     opts.signal.addEventListener("abort", cancel, { once: true });
   }
   return Object.freeze({ cancel });

package/dist/timer/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/timer/scheduler.ts"],"names":[],"mappings":";AAuBA,IAAM,IAAA,GAAoB,MAAA,CAAO,MAAA,CAAO,EAAE,QAAQ,MAAM;AAAC,CAAA,EAAG,CAAA;AAE5D,SAAS,cAAc,IAAA,EAGrB;AACA,EAAA,OAAO;AAAA,IACL,EAAA,EAAI,MAAM,UAAA,KAAe,CAAC,IAAI,EAAA,KAAO,UAAA,CAAW,UAAA,CAAW,EAAA,EAAI,EAAE,CAAA,CAAA;AAAA,IACjE,IAAI,IAAA,EAAM,YAAA,KAAiB,CAAC,CAAA,KAAM,UAAA,CAAW,aAAa,CAAW,CAAA;AAAA,GACvE;AACF;AAUO,SAAS,KAAA,CAAM,EAAA,EAAY,EAAA,EAAgB,IAAA,EAAkC;AAClF,EAAA,IAAI,IAAA,EAAM,MAAA,EAAQ,OAAA,EAAS,OAAO,IAAA;AAElC,EAAA,MAAM,EAAE,EAAA,EAAI,EAAA,EAAG,GAAI,cAAc,IAAI,CAAA;AACrC,EAAA,IAAI,KAAA,GAAQ,KAAA;AACZ,EAAA,IAAI,SAAA,GAAY,KAAA;AAEhB,EAAA,MAAM,MAAA,GAAS,GAAG,MAAM;AACtB,IAAA,KAAA,GAAQ,IAAA;AAER,IAAA,IAAI,SAAA,EAAW;AACf,IAAA,EAAA,EAAG;AAAA,EACL,GAAG,EAAE,CAAA;AAEL,EAAA,MAAM,SAAS,MAAM;AACnB,IAAA,IAAI,SAAS,SAAA,EAAW;AACxB,IAAA,SAAA,GAAY,IAAA;AACZ,IAAA,EAAA,CAAG,MAAM,CAAA;AAAA,EACX,CAAA;AAEA,EAAA,IAAI,MAAM,MAAA,EAAQ;AAChB,IAAA,IAAA,CAAK,OAAO,gBAAA,CAAiB,OAAA,EAAS,QAAQ,EAAE,IAAA,EAAM,MAAM,CAAA;AAAA,EAC9D;AAEA,EAAA,OAAO,MAAA,CAAO,MAAA,CAAO,EAAE,MAAA,EAAQ,CAAA;AACjC;AAgBO,SAAS,gBAAgB,QAAA,EAAoC;AAClE,EAAA,MAAM,OAAA,uBAAc,GAAA,EAAiB;AAErC,EAAA,MAAM,KAAA,GAAmB;AAAA,IACvB,KAAA,CAAM,EAAA,EAAI,EAAA,EAAI,IAAA,EAAM;AAClB,MAAA,MAAM,MAAA,GAAuB,EAAE,GAAG,QAAA,EAAU,GAAG,IAAA,EAAK;AAGpD,MAAA,MAAM,OAA8B,EAAC;AACrC,MAAA,MAAM,UAAU,MAAM;AACpB,QAAA,IAAI,IAAA,CAAK,GAAA,EAAK,OAAA,CAAQ,MAAA,CAAO,KAAK,GAAG,CAAA;AACrC,QAAA,EAAA,EAAG;AAAA,MACL,CAAA;AACA,MAAA,MAAM,KAAA,GAAQ,KAAA,CAAM,EAAA,EAAI,OAAA,EAAS,MAAM,CAAA;AACvC,MAAA,MAAM,MAAA,GAAsB,OAAO,MAAA,CAAO;AAAA,QACxC,MAAA,GAAS;AACP,UAAA,KAAA,CAAM,MAAA,EAAO;AACb,UAAA,IAAI,IAAA,CAAK,GAAA,EAAK,OAAA,CAAQ,MAAA,CAAO,KAAK,GAAG,CAAA;AAAA,QACvC;AAAA,OACD,CAAA;AACD,MAAA,IAAA,CAAK,GAAA,GAAM,MAAA;AACX,MAAA,OAAA,CAAQ,IAAI,MAAM,CAAA;AAClB,MAAA,OAAO,MAAA;AAAA,IACT,CAAA;AAAA,IACA,SAAA,GAAY;AACV,MAAA,KAAA,MAAW,CAAA,IAAK,OAAA,EAAS,CAAA,CAAE,MAAA,EAAO;AAClC,MAAA,OAAA,CAAQ,KAAA,EAAM;AAAA,IAChB,CAAA;AAAA,IACA,IAAI,IAAA,GAAO;AACT,MAAA,OAAO,OAAA,CAAQ,IAAA;AAAA,IACjB;AAAA,GACF;AACA,EAAA,OAAO,KAAA;AACT","file":"index.js","sourcesContent":["export type AfterHandle = Readonly<{\n  cancel(): void;\n}>;\n\nexport type SetTimeoutFn = (fn: () => void, ms: number) => unknown;\nexport type ClearTimeoutFn = (handle: unknown) => void;\n\nexport type AfterOptions = Readonly<{\n  /**\n   * If supplied and aborted, the callback never runs and any pending timer is\n   * cleared. Aborting after fire is a no-op.\n   */\n  signal?: AbortSignal;\n  /**\n   * Override `setTimeout` (testing, SSR, custom loops). Defaults to globalThis.\n   */\n  setTimeout?: SetTimeoutFn;\n  /**\n   * Override `clearTimeout`. Must match the `setTimeout` you injected.\n   */\n  clearTimeout?: ClearTimeoutFn;\n}>;\n\nconst NOOP: AfterHandle = Object.freeze({ cancel: () => {} });\n\nfunction resolveTimers(opts: AfterOptions | undefined): {\n  st: SetTimeoutFn;\n  ct: ClearTimeoutFn;\n} {\n  return {\n    st: opts?.setTimeout ?? ((fn, ms) => globalThis.setTimeout(fn, ms)),\n    ct: opts?.clearTimeout ?? ((h) => globalThis.clearTimeout(h as number)),\n  };\n}\n\n/**\n * Schedule `fn` to run after `ms` milliseconds. Returns a handle whose\n * `cancel()` clears the pending timer. Optional `signal` aborts the timer when\n * triggered. Aborting after the callback fires is a no-op.\n *\n * Per Node guidance, the abort listener is registered with `{ once: true }` to\n * avoid leaking listeners when the same signal is reused across many timers.\n */\nexport function after(ms: number, fn: () => void, opts?: AfterOptions): AfterHandle {\n  if (opts?.signal?.aborted) return NOOP;\n\n  const { st, ct } = resolveTimers(opts);\n  let fired = false;\n  let cancelled = false;\n\n  const handle = st(() => {\n    fired = true;\n    /* v8 ignore next — defensive race guard: cancel() sets cancelled=true and clears the timer, but if a custom setTimeout fires after clear, this short-circuits fn(). */\n    if (cancelled) return;\n    fn();\n  }, ms);\n\n  const cancel = () => {\n    if (fired || cancelled) return;\n    cancelled = true;\n    ct(handle);\n  };\n\n  if (opts?.signal) {\n    opts.signal.addEventListener(\"abort\", cancel, { once: true });\n  }\n\n  return Object.freeze({ cancel });\n}\n\nexport type Scheduler = Readonly<{\n  after(ms: number, fn: () => void, opts?: AfterOptions): AfterHandle;\n  cancelAll(): void;\n  readonly size: number;\n}>;\n\n/**\n * Build a scheduler that tracks every pending `after()` so they can be\n * cancelled together (e.g. on machine destroy). Each `after` returns a handle\n * whose `cancel()` also removes it from the tracking set.\n *\n * `defaults` are merged into every call — typically you inject `setTimeout` /\n * `clearTimeout` once at construction.\n */\nexport function createScheduler(defaults?: AfterOptions): Scheduler {\n  const pending = new Set<AfterHandle>();\n\n  const sched: Scheduler = {\n    after(ms, fn, opts) {\n      const merged: AfterOptions = { ...defaults, ...opts };\n      // Forward-reference slot so `wrapped` can find the tracked handle\n      // before it is constructed below.\n      const slot: { ref?: AfterHandle } = {};\n      const wrapped = () => {\n        if (slot.ref) pending.delete(slot.ref);\n        fn();\n      };\n      const inner = after(ms, wrapped, merged);\n      const handle: AfterHandle = Object.freeze({\n        cancel() {\n          inner.cancel();\n          if (slot.ref) pending.delete(slot.ref);\n        },\n      });\n      slot.ref = handle;\n      pending.add(handle);\n      return handle;\n    },\n    cancelAll() {\n      for (const h of pending) h.cancel();\n      pending.clear();\n    },\n    get size() {\n      return pending.size;\n    },\n  };\n  return sched;\n}\n"]}
+{"version":3,"sources":["../../src/timer/scheduler.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["export type AfterHandle = Readonly<{\n  cancel(): void;\n}>;\n\nexport type SetTimeoutFn = (fn: () => void, ms: number) => unknown;\nexport type ClearTimeoutFn = (handle: unknown) => void;\n\nexport type AfterOptions = Readonly<{\n  /**\n   * If supplied and aborted, the callback never runs and any pending timer is\n   * cleared. Aborting after fire is a no-op.\n   */\n  signal?: AbortSignal;\n  /**\n   * Override `setTimeout` (testing, SSR, custom loops). Defaults to globalThis.\n   */\n  setTimeout?: SetTimeoutFn;\n  /**\n   * Override `clearTimeout`. Must match the `setTimeout` you injected.\n   */\n  clearTimeout?: ClearTimeoutFn;\n}>;\n\nconst NOOP: AfterHandle = Object.freeze({ cancel: () => {} });\n\nfunction resolveTimers(opts: AfterOptions | undefined): {\n  st: SetTimeoutFn;\n  ct: ClearTimeoutFn;\n} {\n  return {\n    st: opts?.setTimeout ?? ((fn, ms) => globalThis.setTimeout(fn, ms)),\n    ct: opts?.clearTimeout ?? ((h) => globalThis.clearTimeout(h as number)),\n  };\n}\n\n/**\n * Schedule `fn` to run after `ms` milliseconds. Returns a handle whose\n * `cancel()` clears the pending timer. Optional `signal` aborts the timer when\n * triggered. Aborting after the callback fires is a no-op.\n *\n * The abort listener is registered with `{ once: true }` as a baseline, but\n * `{ once: true }` alone does NOT prevent listener accumulation when the same\n * signal is reused across many timers: it only removes the listener when the\n * signal aborts, not when the timer fires normally or `cancel()` is called.\n * We therefore explicitly call `signal.removeEventListener(\"abort\", cancel)`\n * inside the fire callback and at the end of `cancel()` so that a shared,\n * long-lived signal never accumulates dead listeners across timer reuse.\n */\nexport function after(ms: number, fn: () => void, opts?: AfterOptions): AfterHandle {\n  if (opts?.signal?.aborted) return NOOP;\n\n  const { st, ct } = resolveTimers(opts);\n  let fired = false;\n  let cancelled = false;\n  // `cancel` and the timer handle reference each other. A const cell holds the\n  // handle so `cancel` can be defined BEFORE `st(...)` runs (letting a custom\n  // `st` that fires its callback synchronously reference `cancel` without\n  // hitting the temporal-dead-zone) while still being able to clear the handle\n  // assigned afterwards. A synchronous fire sets `fired=true`, so cancel() never\n  // reads the still-unset handle in that path.\n  const timer: { handle?: ReturnType<typeof st> } = {};\n\n  const cancel = () => {\n    if (fired || cancelled) return;\n    cancelled = true;\n    if (timer.handle !== undefined) ct(timer.handle);\n    // Detach the abort listener so a reused signal does not accumulate dead\n    // closures after this timer is cancelled.\n    if (opts?.signal) opts.signal.removeEventListener(\"abort\", cancel);\n  };\n\n  timer.handle = st(() => {\n    fired = true;\n    /* v8 ignore next — defensive race guard: cancel() sets cancelled=true and clears the timer, but if a custom setTimeout fires after clear, this short-circuits fn(). */\n    if (cancelled) return;\n    // Detach the abort listener now that the timer has fired — the listener\n    // will never be invoked and must not accumulate on a reused signal.\n    if (opts?.signal) opts.signal.removeEventListener(\"abort\", cancel);\n    fn();\n  }, ms);\n\n  // Attach only if the timer has not already fired synchronously (a custom `st`\n  // may fire inline); otherwise the listener would be registered AFTER the fire\n  // path's removal ran and would then leak until the signal aborts.\n  if (opts?.signal && !fired) {\n    opts.signal.addEventListener(\"abort\", cancel, { once: true });\n  }\n\n  return Object.freeze({ cancel });\n}\n\nexport type Scheduler = Readonly<{\n  after(ms: number, fn: () => void, opts?: AfterOptions): AfterHandle;\n  cancelAll(): void;\n  readonly size: number;\n}>;\n\n/**\n * Build a scheduler that tracks every pending `after()` so they can be\n * cancelled together (e.g. on machine destroy). Each `after` returns a handle\n * whose `cancel()` also removes it from the tracking set.\n *\n * `defaults` are merged into every call — typically you inject `setTimeout` /\n * `clearTimeout` once at construction.\n */\nexport function createScheduler(defaults?: AfterOptions): Scheduler {\n  const pending = new Set<AfterHandle>();\n\n  const sched: Scheduler = {\n    after(ms, fn, opts) {\n      const merged: AfterOptions = { ...defaults, ...opts };\n      // Forward-reference slot so `wrapped` can find the tracked handle\n      // before it is constructed below.\n      const slot: { ref?: AfterHandle } = {};\n      const wrapped = () => {\n        if (slot.ref) pending.delete(slot.ref);\n        fn();\n      };\n      const inner = after(ms, wrapped, merged);\n      const handle: AfterHandle = Object.freeze({\n        cancel() {\n          inner.cancel();\n          if (slot.ref) pending.delete(slot.ref);\n        },\n      });\n      slot.ref = handle;\n      pending.add(handle);\n      return handle;\n    },\n    cancelAll() {\n      for (const h of pending) h.cancel();\n      pending.clear();\n    },\n    get size() {\n      return pending.size;\n    },\n  };\n  return sched;\n}\n"]}

package/llms-full.txt

@@ -220,7 +220,7 @@ function step<C, E, S>(
 ): { snapshot: Snapshot<C, S>; effects: readonly Effect[] };
 ```
 
-**Pure function**. The invariant keeper for the whole library. It never dispatches effects, never mutates the snapshot, and never throws — a failing guard or unmapped event simply returns the original snapshot.
+**Pure function**. The invariant keeper for the whole library. It never dispatches effects and never mutates the snapshot. A failing guard or unmapped event simply returns the original snapshot unchanged. It does throw on misuse (`UnknownGuardError`, `UnknownActionError`, `AsyncGuardError`) so guard/action wiring errors surface at development time rather than silently passing.
 
 ### `assign(updater)`
 
@@ -279,7 +279,7 @@ const runtime = createRuntime(def, impl, {
 });
 ```
 
-Koa-style `(ctx, next) => void` pipeline. `ctx` is `{ prev, next, event, effects }`, all `structuredClone`d and frozen. **Cannot cancel a transition** — `next()` must be called; the return value carries no meaning.
+Koa-style `(ctx, next) => void` pipeline. `ctx` is `{ prev, next, event, effects, changed }`, all deep-frozen. **Cannot cancel a transition** — `next()` must be called; the return value carries no meaning.
 
 ### `aifsmjs/replay` — Pure event log replay
 
@@ -298,14 +298,25 @@ Never dispatches effects. For PBT, time-travel debugging, and incident reproduct
 
 ```typescript
 import fc from "fast-check";
-import { commandsFromMachine, properties } from "aifsmjs/pbt";
+import { createRuntime } from "aifsmjs";
+import { commandsFromMachine, initialModel, properties } from "aifsmjs/pbt";
+
+// Use one of the six built-in generic properties, or assertAll for all at once:
+properties.replayEqualsFold(def, impl, {
+  NEXT: fc.constant({ type: "NEXT" as const }),
+});
 
+// Or build a custom property using commandsFromMachine:
 fc.assert(
   fc.property(
     commandsFromMachine(def, impl, {
       NEXT: fc.constant({ type: "NEXT" as const }),
     }),
-    (cmds) => properties.runDeterministic(def, impl, cmds),
+    (cmds) => {
+      const real = createRuntime(def, impl, { dispatchEffects: false });
+      fc.modelRun(() => ({ model: initialModel(def), real }), cmds);
+      return true;
+    },
   ),
 );
 ```
@@ -543,6 +554,41 @@ 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).
 
+## [Unreleased]
+
+## [0.5.2] - 2026-06-05
+
+### Docs
+
+- Review-driven documentation fixes (`README.md`, `README_ZHTW.md`, `llms-full.txt`): clarity and accuracy from a cross-package code review. No runtime or API change; `dist` byte-identical to 0.5.1.
+
+## [0.5.1] - 2026-06-02
+
+### Fixed
+
+- **Memory: `after()` and `createScheduler().after()` accumulated dead abort
+  listeners on a reused `AbortSignal`.** `{ once: true }` only removes the
+  listener when the signal fires — not when the timer fires normally or
+  `cancel()` is called. Scheduling many timers on one long-lived signal
+  therefore accumulated dead `"abort"` closures. The fix explicitly calls
+  `signal.removeEventListener("abort", cancel)` inside the fire callback (so
+  a fired timer detaches immediately) and at the end of `cancel()` (so a
+  cancelled timer also detaches). Same class of leak as the [0.1.2] and
+  [0.3.1] abort-listener fixes; the timer subpath was the remaining gap.
+  Four regression tests added to `test/timer/scheduler.test.ts` covering
+  both `after()` and `createScheduler().after()`, fire and cancel paths.
+  (`src/timer/scheduler.ts`)
+
+### Changed
+
+- **`fast-check` peer dependency range extended to `^3.20.0 || ^4.0.0`.**
+  The ai\*js family standard is fast-check v4.8; consumers who have already
+  upgraded to v4 no longer need to suppress a peer warning. The devDependency
+  is pinned to `^4.8.0` so CI runs against v4. Consumers who remain on v3
+  are fully unaffected — the `||` range keeps v3 satisfied. The `aifsmjs/pbt`
+  subpath is the only entry point that imports fast-check; the core and all
+  other subpaths are tree-shake-free of it.
+
 ## [0.4.1] — 2026-05-29
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aifsmjs",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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",
@@ -97,7 +97,7 @@
     "prepublishOnly": "pnpm typecheck && pnpm lint && pnpm coverage && pnpm build && pnpm verify:exports && pnpm verify:llms && pnpm check:size"
   },
   "peerDependencies": {
-    "fast-check": "^3.20.0"
+    "fast-check": "^3.20.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
     "fast-check": {
@@ -108,7 +108,7 @@
     "@biomejs/biome": "^1.9.0",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^4.1.7",
-    "fast-check": "^3.20.0",
+    "fast-check": "^4.8.0",
     "tsup": "^8.3.0",
     "tsx": "^4.22.3",
     "typescript": "^5.6.0",