aifsmjs 0.5.1 → 0.5.3

package/dist/replay/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/effects/enqueuer.ts","../../src/fsm/evaluator.ts","../../src/fsm/snapshot.ts","../../src/fsm/updater.ts","../../src/fsm/lifecycle.ts","../../src/replay/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { Enqueuer } from \"../fsm/types.js\";\n\n/**\n * Build a closure-based Enqueuer that pushes effects into the supplied sink.\n * Each `step()` invocation creates one such enqueuer and discards it\n * afterwards; the sink is the effects array later returned to the caller.\n *\n * Lives in `effects/` because the Enqueuer concept is the effects-domain API\n * — `step()` imports it from here.\n */\nexport function createEnqueuer(sink: { type: string; payload?: unknown }[]): Enqueuer {\n  return Object.freeze({\n    effect(type: string, payload?: unknown) {\n      if (payload === undefined) {\n        sink.push(Object.freeze({ type }));\n      } else {\n        sink.push(Object.freeze({ type, payload }));\n      }\n    },\n  });\n}\n","import type { Guard, GuardRef, Implementations } from \"./types.js\";\n\nexport class UnknownGuardError extends Error {\n  readonly guardName: string;\n  constructor(guardName: string) {\n    super(`aifsmjs: guard \"${guardName}\" not found in implementations.guards`);\n    this.name = \"UnknownGuardError\";\n    this.guardName = guardName;\n  }\n}\n\nexport class AsyncGuardError extends Error {\n  readonly guardName: string;\n  constructor(guardName: string) {\n    super(\n      `aifsmjs: guard \"${guardName}\" must be sync; received a Promise. Async guards break determinism and replay. Move I/O into an effect.`,\n    );\n    this.name = \"AsyncGuardError\";\n    this.guardName = guardName;\n  }\n}\n\n/**\n * Detect declared-async guards at definition time. Catches the common case of\n * `async (args) => ...` inline guards. Combinator builders or arrow returns of\n * a Promise still slip past — those are caught at `evalGuard` runtime via\n * the `isThenable` check.\n *\n * Caveat: this relies on `Function.prototype.constructor.name === \"AsyncFunction\"`,\n * which is reliable in ES2017+ runtimes. If your bundler transpiles `async`\n * to generator-based code (e.g. ES5 / very old TypeScript targets), this\n * check returns `false` for those forms — the runtime `evalGuard` thenable\n * check still catches them.\n */\nexport function isAsyncGuardFn(fn: unknown): boolean {\n  if (typeof fn !== \"function\") return false;\n  return fn.constructor?.name === \"AsyncFunction\";\n}\n\n/**\n * Detect a thenable (PromiseLike) — anything with a callable `then`. Used in\n * place of `instanceof Promise` so cross-realm Promises (iframe / worker /\n * vm context) and user-defined thenables are also rejected.\n */\nfunction isThenable(x: unknown): x is PromiseLike<unknown> {\n  return (\n    x !== null &&\n    (typeof x === \"object\" || typeof x === \"function\") &&\n    typeof (x as { then?: unknown }).then === \"function\"\n  );\n}\n\n/**\n * Resolve a guard ref to a Guard function. String refs are looked up in the\n * implementations map; inline functions are returned as-is.\n */\nexport function resolveGuard<Ctx, Evt>(\n  ref: GuardRef<Ctx, Evt>,\n  impl: Implementations<Ctx, Evt>,\n): Guard<Ctx, Evt> {\n  if (typeof ref === \"function\") return ref;\n  const fn = impl.guards?.[ref];\n  if (!fn) throw new UnknownGuardError(ref);\n  return fn;\n}\n\n/**\n * Evaluate a guard ref against (context, event). Guards must be sync and pure;\n * TypeScript blocks declared-async signatures at compile time, but JS callers\n * or casts can still slip through. This function checks two ways:\n *   1. Inline AsyncFunction (declared `async`) → throw AsyncGuardError.\n *   2. Return value is a Promise → throw AsyncGuardError.\n * Both throws are user errors; they would otherwise silently pass the guard\n * (Promise is truthy) and break determinism.\n *\n * The optional `value` argument is the current state value, threaded so the\n * `stateIn` combinator and similar predicates can introspect it.\n */\nexport function evalGuard<Ctx, Evt>(\n  ref: GuardRef<Ctx, Evt>,\n  context: Ctx,\n  event: Evt,\n  impl: Implementations<Ctx, Evt>,\n  value?: string,\n): boolean {\n  const fn = resolveGuard(ref, impl);\n  // Function.prototype.name is \"\" for anonymous arrows — use `||` not `??`\n  // so the empty string falls back to \"<inline>\" for readable error messages.\n  const guardName = typeof ref === \"string\" ? ref : fn.name || \"<inline>\";\n  if (isAsyncGuardFn(fn)) {\n    throw new AsyncGuardError(guardName);\n  }\n  // Build args while honouring exactOptionalPropertyTypes: omit fields that\n  // would otherwise be assigned `undefined`.\n  type Args = {\n    context: Ctx;\n    event: Evt;\n    guards?: Readonly<Record<string, Guard<Ctx, Evt>>>;\n    value?: string;\n  };\n  const args: Args = { context, event };\n  const guardsMap = impl.guards;\n  if (guardsMap) args.guards = guardsMap;\n  if (value !== undefined) args.value = value;\n  const result = fn(args);\n  // TS narrows `result` to boolean from Guard's return type, but a JS caller\n  // or a cast can slip a Promise / PromiseLike through. We accept anything\n  // thenable (native Promise, cross-realm Promise, user-defined thenable),\n  // not just same-realm `instanceof Promise`.\n  if (isThenable(result)) {\n    throw new AsyncGuardError(guardName);\n  }\n  return result;\n}\n","import type { Snapshot } from \"./types.js\";\n\nconst IS_DEV =\n  typeof process !== \"undefined\" &&\n  typeof process.env !== \"undefined\" &&\n  process.env.NODE_ENV !== \"production\";\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (value === null || typeof value !== \"object\") return false;\n  const proto = Object.getPrototypeOf(value);\n  return proto === Object.prototype || proto === null;\n}\n\nexport function deepFreeze<T>(value: T): T {\n  if (value === null || typeof value !== \"object\") return value;\n  if (Object.isFrozen(value)) return value;\n  Object.freeze(value);\n  if (Array.isArray(value)) {\n    for (const item of value) deepFreeze(item);\n  } else if (isPlainObject(value)) {\n    for (const key of Object.keys(value)) {\n      deepFreeze((value as Record<string, unknown>)[key]);\n    }\n  }\n  return value;\n}\n\n/**\n * Wrap a freshly built snapshot. In dev mode the whole tree is deep-frozen so\n * accidental mutation throws immediately. In production only the top object is\n * frozen, keeping the cost negligible.\n */\nexport function freezeSnapshot<C, S extends string>(snap: Snapshot<C, S>): Snapshot<C, S> {\n  // IS_DEV is always true in vitest; the production branch (`Object.freeze`)\n  // is exercised only when NODE_ENV === \"production\" and is intentionally\n  // left out of the coverage threshold.\n  return IS_DEV ? deepFreeze(snap) : Object.freeze(snap);\n}\n\nexport function createSnapshot<C, S extends string>(args: {\n  value: S;\n  context: C;\n  status?: \"active\" | \"final\";\n}): Snapshot<C, S> {\n  return freezeSnapshot({\n    value: args.value,\n    context: args.context,\n    status: args.status ?? \"active\",\n  });\n}\n","import type { Action } from \"./types.js\";\n\nfunction isPlainRecord(value: unknown): value is Record<string, unknown> {\n  if (value === null || typeof value !== \"object\") return false;\n  const proto = Object.getPrototypeOf(value);\n  return proto === Object.prototype || proto === null;\n}\n\n/**\n * Build an Action that returns a Partial<Ctx> from a pure updater.\n * The partial is merged into the current context by `step()`.\n */\nexport function assign<Ctx, Evt>(\n  updater: (args: { context: Ctx; event: Evt }) => Partial<Ctx>,\n): Action<Ctx, Evt> {\n  return ({ context, event }) => updater({ context, event });\n}\n\n/**\n * Merge a partial context update into the current context. Plain-object\n * contexts get a shallow merge; non-object contexts get replaced wholesale.\n *\n * The function never mutates either argument.\n */\nexport function mergeContext<Ctx>(current: Ctx, patch: Partial<Ctx> | void): Ctx {\n  if (patch === undefined || patch === null) return current;\n  if (isPlainRecord(current) && isPlainRecord(patch)) {\n    return { ...current, ...patch } as Ctx;\n  }\n  return patch as Ctx;\n}\n","import { createEnqueuer } from \"../effects/enqueuer.js\";\nimport { evalGuard } from \"./evaluator.js\";\nimport { freezeSnapshot } from \"./snapshot.js\";\nimport type {\n  Action,\n  ActionRef,\n  Effect,\n  Implementations,\n  MachineDef,\n  Snapshot,\n  StepResult,\n  TransitionDef,\n} from \"./types.js\";\nimport { mergeContext } from \"./updater.js\";\n\nexport class UnknownActionError extends Error {\n  readonly actionName: string;\n  constructor(actionName: string) {\n    super(`aifsmjs: action \"${actionName}\" not found in implementations.actions`);\n    this.name = \"UnknownActionError\";\n    this.actionName = actionName;\n  }\n}\n\nfunction resolveAction<Ctx, Evt>(\n  ref: ActionRef<Ctx, Evt>,\n  impl: Implementations<Ctx, Evt>,\n): Action<Ctx, Evt> {\n  if (typeof ref === \"function\") return ref;\n  const fn = impl.actions?.[ref];\n  if (!fn) throw new UnknownActionError(ref);\n  return fn;\n}\n\nfunction runActions<Ctx, Evt>(\n  refs: readonly ActionRef<Ctx, Evt>[] | undefined,\n  ctx: Ctx,\n  event: Evt,\n  impl: Implementations<Ctx, Evt>,\n  effectSink: Effect[],\n): Ctx {\n  if (!refs || refs.length === 0) return ctx;\n  const enqueue = createEnqueuer(effectSink as { type: string; payload?: unknown }[]);\n  let current = ctx;\n  for (const ref of refs) {\n    const fn = resolveAction(ref, impl);\n    const patch = fn({ context: current, event, enqueue });\n    current = mergeContext(current, patch);\n  }\n  return current;\n}\n\nfunction pickTransition<Ctx, Evt, States extends string>(\n  candidates: readonly TransitionDef<Ctx, Evt, States>[],\n  ctx: Ctx,\n  event: Evt,\n  impl: Implementations<Ctx, Evt>,\n  value: States,\n): TransitionDef<Ctx, Evt, States> | undefined {\n  for (const t of candidates) {\n    if (!t.guard) return t;\n    if (evalGuard(t.guard, ctx, event, impl, value)) return t;\n  }\n  return undefined;\n}\n\n/**\n * Compute the next snapshot and collected effects from a single event.\n *\n * Order is fixed and uninterruptible:\n *   1. resolve candidate transitions for (state, event.type)\n *   2. evaluate guards in declaration order; pick the first passing one\n *   3. if external (target defined), run exit actions of the old state\n *   4. run transition.actions in declaration order\n *   5. if external, run entry actions of the new state\n *   6. return { snapshot, effects, changed }\n *\n * The function is pure: it never dispatches effects and never mutates inputs.\n */\nexport function step<Ctx, Evt extends { type: string }, States extends string>(\n  def: MachineDef<Ctx, Evt, States>,\n  snapshot: Snapshot<Ctx, States>,\n  event: Evt,\n  impl: Implementations<Ctx, Evt>,\n): StepResult<Ctx, States> {\n  // Final state is inert: it never reacts to events.\n  if (snapshot.status === \"final\") {\n    return Object.freeze({ snapshot, effects: [] as readonly Effect[], changed: false });\n  }\n\n  const state = def.states[snapshot.value];\n  /* v8 ignore next 3 — defensive: snapshot.value is always validated against def.states by defineMachine + initialSnapshot. */\n  if (!state) {\n    return Object.freeze({ snapshot, effects: [] as readonly Effect[], changed: false });\n  }\n\n  const candidates = state.on?.[event.type];\n  const candidateList: readonly TransitionDef<Ctx, Evt, States>[] = candidates\n    ? Array.isArray(candidates)\n      ? candidates\n      : [candidates as TransitionDef<Ctx, Evt, States>]\n    : [];\n\n  const chosen = pickTransition(candidateList, snapshot.context, event, impl, snapshot.value);\n  if (!chosen) {\n    return Object.freeze({ snapshot, effects: [] as readonly Effect[], changed: false });\n  }\n\n  const isExternal = chosen.target !== undefined;\n  const nextStateValue = (chosen.target ?? snapshot.value) as States;\n  const nextState = def.states[nextStateValue];\n\n  const effectSink: Effect[] = [];\n  let ctx = snapshot.context;\n\n  if (isExternal) {\n    ctx = runActions(state.exit, ctx, event, impl, effectSink);\n  }\n  ctx = runActions(chosen.actions, ctx, event, impl, effectSink);\n  if (isExternal && nextState) {\n    ctx = runActions(nextState.entry, ctx, event, impl, effectSink);\n  }\n\n  const status: \"active\" | \"final\" = nextState?.final === true ? \"final\" : \"active\";\n  const nextSnapshot = freezeSnapshot({\n    value: nextStateValue,\n    context: ctx,\n    status,\n  });\n\n  return Object.freeze({\n    snapshot: nextSnapshot,\n    effects: Object.freeze(effectSink.slice()) as readonly Effect[],\n    changed: true,\n  });\n}\n","import { step } from \"../fsm/lifecycle.js\";\nimport type { Effect, Implementations, MachineDef, Snapshot } from \"../fsm/types.js\";\n\nexport type ReplayResult<Ctx, States extends string> = Readonly<{\n  snapshot: Snapshot<Ctx, States>;\n  effects: readonly Effect[];\n}>;\n\n/**\n * Fold an event log into a final snapshot via `step()`. Effects are collected\n * but never dispatched — this is a pure function, suitable for PBT, time\n * travel, and incident reproduction.\n *\n * Equivalent to:\n *   events.reduce((s, e) => step(def, s, e, impl).snapshot, initial)\n * but also accumulates the effects across all events.\n */\nexport function replay<Ctx, Evt extends { type: string }, States extends string>(\n  initial: Snapshot<Ctx, States>,\n  events: readonly Evt[],\n  def: MachineDef<Ctx, Evt, States>,\n  impl: Implementations<Ctx, Evt>,\n): ReplayResult<Ctx, States> {\n  let snapshot = initial;\n  const effects: Effect[] = [];\n  for (const event of events) {\n    const r = step(def, snapshot, event, impl);\n    snapshot = r.snapshot;\n    if (r.effects.length > 0) {\n      for (const eff of r.effects) effects.push(eff);\n    }\n  }\n  return Object.freeze({ snapshot, effects: Object.freeze(effects.slice()) });\n}\n"]}
+{"version":3,"sources":["../../src/effects/enqueuer.ts","../../src/fsm/evaluator.ts","../../src/fsm/resolver.ts","../../src/fsm/snapshot.ts","../../src/fsm/updater.ts","../../src/fsm/lifecycle.ts","../../src/replay/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { Enqueuer } from \"../fsm/types.js\";\n\n/**\n * Build a closure-based Enqueuer that pushes effects into the supplied sink.\n * Each `step()` invocation creates one such enqueuer and discards it\n * afterwards; the sink is the effects array later returned to the caller.\n *\n * Lives in `effects/` because the Enqueuer concept is the effects-domain API\n * — `step()` imports it from here.\n */\nexport function createEnqueuer(sink: { type: string; payload?: unknown }[]): Enqueuer {\n  return Object.freeze({\n    effect(type: string, payload?: unknown) {\n      if (payload === undefined) {\n        sink.push(Object.freeze({ type }));\n      } else {\n        sink.push(Object.freeze({ type, payload }));\n      }\n    },\n  });\n}\n","import type { Guard, GuardRef, Implementations } from \"./types.js\";\n\nexport class UnknownGuardError extends Error {\n  readonly guardName: string;\n  constructor(guardName: string) {\n    super(`aifsmjs: guard \"${guardName}\" not found in implementations.guards`);\n    this.name = \"UnknownGuardError\";\n    this.guardName = guardName;\n  }\n}\n\nexport class AsyncGuardError extends Error {\n  readonly guardName: string;\n  constructor(guardName: string) {\n    super(\n      `aifsmjs: guard \"${guardName}\" must be sync; received a Promise. Async guards break determinism and replay. Move I/O into an effect.`,\n    );\n    this.name = \"AsyncGuardError\";\n    this.guardName = guardName;\n  }\n}\n\n/**\n * Detect declared-async guards at definition time. Catches the common case of\n * `async (args) => ...` inline guards. Combinator builders or arrow returns of\n * a Promise still slip past — those are caught at `evalGuard` runtime via\n * the `isThenable` check.\n *\n * Caveat: this relies on `Function.prototype.constructor.name === \"AsyncFunction\"`,\n * which is reliable in ES2017+ runtimes. If your bundler transpiles `async`\n * to generator-based code (e.g. ES5 / very old TypeScript targets), this\n * check returns `false` for those forms — the runtime `evalGuard` thenable\n * check still catches them.\n */\nexport function isAsyncGuardFn(fn: unknown): boolean {\n  if (typeof fn !== \"function\") return false;\n  return fn.constructor?.name === \"AsyncFunction\";\n}\n\n/**\n * Detect a thenable (PromiseLike) — anything with a callable `then`. Used in\n * place of `instanceof Promise` so cross-realm Promises (iframe / worker /\n * vm context) and user-defined thenables are also rejected.\n */\nfunction isThenable(x: unknown): x is PromiseLike<unknown> {\n  return (\n    x !== null &&\n    (typeof x === \"object\" || typeof x === \"function\") &&\n    typeof (x as { then?: unknown }).then === \"function\"\n  );\n}\n\n/**\n * Resolve a guard ref to a Guard function. String refs are looked up in the\n * implementations map; inline functions are returned as-is.\n */\nexport function resolveGuard<Ctx, Evt>(\n  ref: GuardRef<Ctx, Evt>,\n  impl: Implementations<Ctx, Evt>,\n): Guard<Ctx, Evt> {\n  if (typeof ref === \"function\") return ref;\n  const fn = impl.guards?.[ref];\n  if (!fn) throw new UnknownGuardError(ref);\n  return fn;\n}\n\n/**\n * Evaluate a guard ref against (context, event). Guards must be sync and pure;\n * TypeScript blocks declared-async signatures at compile time, but JS callers\n * or casts can still slip through. This function checks two ways:\n *   1. Inline AsyncFunction (declared `async`) → throw AsyncGuardError.\n *   2. Return value is a Promise → throw AsyncGuardError.\n * Both throws are user errors; they would otherwise silently pass the guard\n * (Promise is truthy) and break determinism.\n *\n * The optional `value` argument is the current state value, threaded so the\n * `stateIn` combinator and similar predicates can introspect it.\n */\nexport function evalGuard<Ctx, Evt>(\n  ref: GuardRef<Ctx, Evt>,\n  context: Ctx,\n  event: Evt,\n  impl: Implementations<Ctx, Evt>,\n  value?: string,\n): boolean {\n  const fn = resolveGuard(ref, impl);\n  // Function.prototype.name is \"\" for anonymous arrows — use `||` not `??`\n  // so the empty string falls back to \"<inline>\" for readable error messages.\n  const guardName = typeof ref === \"string\" ? ref : fn.name || \"<inline>\";\n  if (isAsyncGuardFn(fn)) {\n    throw new AsyncGuardError(guardName);\n  }\n  // Build args while honouring exactOptionalPropertyTypes: omit fields that\n  // would otherwise be assigned `undefined`.\n  type Args = {\n    context: Ctx;\n    event: Evt;\n    guards?: Readonly<Record<string, Guard<Ctx, Evt>>>;\n    value?: string;\n  };\n  const args: Args = { context, event };\n  const guardsMap = impl.guards;\n  if (guardsMap) args.guards = guardsMap;\n  if (value !== undefined) args.value = value;\n  const result = fn(args);\n  // TS narrows `result` to boolean from Guard's return type, but a JS caller\n  // or a cast can slip a Promise / PromiseLike through. We accept anything\n  // thenable (native Promise, cross-realm Promise, user-defined thenable),\n  // not just same-realm `instanceof Promise`.\n  if (isThenable(result)) {\n    throw new AsyncGuardError(guardName);\n  }\n  return result;\n}\n","import type { MachineDef, TransitionConfig, TransitionDef } from \"./types.js\";\n\n/**\n * Normalize a single transition config into its object form. The string\n * shorthand `\"targetState\"` (à la XState) becomes `{ target: \"targetState\" }`;\n * the object form is returned unchanged. Centralised here so every consumer\n * (`step`, `resolveTransitions`, `can`, validation) sees the same shape.\n *\n * @since 0.5.3\n */\nexport function normalizeTransition<Ctx, Evt, States extends string>(\n  entry: TransitionConfig<Ctx, Evt, States>,\n): TransitionDef<Ctx, Evt, States> {\n  return typeof entry === \"string\" ? ({ target: entry } as TransitionDef<Ctx, Evt, States>) : entry;\n}\n\n/**\n * Normalize the raw `state.on[eventType]` value (object, string shorthand, or\n * an array mixing both) into an ordered list of {@link TransitionDef} objects.\n * Declaration order is preserved.\n *\n * @since 0.5.3\n */\nexport function normalizeTransitions<Ctx, Evt, States extends string>(\n  entry:\n    | TransitionConfig<Ctx, Evt, States>\n    | readonly TransitionConfig<Ctx, Evt, States>[]\n    | undefined,\n): readonly TransitionDef<Ctx, Evt, States>[] {\n  if (entry === undefined) return [];\n  if (Array.isArray(entry)) {\n    // Hot path (send/step/can run this per event): when no string shorthand is\n    // present, return the original array instead of allocating a normalized copy.\n    return entry.some((t) => typeof t === \"string\")\n      ? entry.map((t) => normalizeTransition(t))\n      : (entry as readonly TransitionDef<Ctx, Evt, States>[]);\n  }\n  return [normalizeTransition(entry as TransitionConfig<Ctx, Evt, States>)];\n}\n\n/**\n * Return all transition candidates for (state, eventType). Order is preserved\n * from the declaration so that guard fallthrough behaves predictably. String\n * shorthands are normalized to `{ target }` objects.\n *\n * If the event has no entry under the given state, an empty array is returned.\n */\nexport function resolveTransitions<Ctx, Evt extends { type: string }, States extends string>(\n  def: MachineDef<Ctx, Evt, States>,\n  stateValue: States,\n  eventType: string,\n): readonly TransitionDef<Ctx, Evt, States>[] {\n  const state = def.states[stateValue];\n  if (!state || !state.on) return [];\n  return normalizeTransitions(state.on[eventType]);\n}\n","import type { Snapshot } from \"./types.js\";\n\nconst IS_DEV =\n  typeof process !== \"undefined\" &&\n  typeof process.env !== \"undefined\" &&\n  process.env.NODE_ENV !== \"production\";\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (value === null || typeof value !== \"object\") return false;\n  const proto = Object.getPrototypeOf(value);\n  return proto === Object.prototype || proto === null;\n}\n\nexport function deepFreeze<T>(value: T): T {\n  if (value === null || typeof value !== \"object\") return value;\n  if (Object.isFrozen(value)) return value;\n  Object.freeze(value);\n  if (Array.isArray(value)) {\n    for (const item of value) deepFreeze(item);\n  } else if (isPlainObject(value)) {\n    for (const key of Object.keys(value)) {\n      deepFreeze((value as Record<string, unknown>)[key]);\n    }\n  }\n  return value;\n}\n\n/**\n * Wrap a freshly built snapshot. In dev mode the whole tree is deep-frozen so\n * accidental mutation throws immediately. In production only the top object is\n * frozen, keeping the cost negligible.\n */\nexport function freezeSnapshot<C, S extends string>(snap: Snapshot<C, S>): Snapshot<C, S> {\n  // IS_DEV is always true in vitest; the production branch (`Object.freeze`)\n  // is exercised only when NODE_ENV === \"production\" and is intentionally\n  // left out of the coverage threshold.\n  return IS_DEV ? deepFreeze(snap) : Object.freeze(snap);\n}\n\nexport function createSnapshot<C, S extends string>(args: {\n  value: S;\n  context: C;\n  status?: \"active\" | \"final\";\n}): Snapshot<C, S> {\n  return freezeSnapshot({\n    value: args.value,\n    context: args.context,\n    status: args.status ?? \"active\",\n  });\n}\n","import type { Action } from \"./types.js\";\n\nfunction isPlainRecord(value: unknown): value is Record<string, unknown> {\n  if (value === null || typeof value !== \"object\") return false;\n  const proto = Object.getPrototypeOf(value);\n  return proto === Object.prototype || proto === null;\n}\n\n/**\n * Build an Action that returns a Partial<Ctx> from a pure updater.\n * The partial is merged into the current context by `step()`.\n */\nexport function assign<Ctx, Evt>(\n  updater: (args: { context: Ctx; event: Evt }) => Partial<Ctx>,\n): Action<Ctx, Evt> {\n  return ({ context, event }) => updater({ context, event });\n}\n\n/**\n * Merge a partial context update into the current context. Plain-object\n * contexts get a shallow merge; non-object contexts get replaced wholesale.\n *\n * The function never mutates either argument.\n */\nexport function mergeContext<Ctx>(current: Ctx, patch: Partial<Ctx> | void): Ctx {\n  if (patch === undefined || patch === null) return current;\n  if (isPlainRecord(current) && isPlainRecord(patch)) {\n    return { ...current, ...patch } as Ctx;\n  }\n  return patch as Ctx;\n}\n","import { createEnqueuer } from \"../effects/enqueuer.js\";\nimport { evalGuard } from \"./evaluator.js\";\nimport { normalizeTransitions } from \"./resolver.js\";\nimport { freezeSnapshot } from \"./snapshot.js\";\nimport type {\n  Action,\n  ActionRef,\n  Effect,\n  Implementations,\n  MachineDef,\n  Snapshot,\n  StepResult,\n  TransitionDef,\n} from \"./types.js\";\nimport { mergeContext } from \"./updater.js\";\n\nexport class UnknownActionError extends Error {\n  readonly actionName: string;\n  constructor(actionName: string) {\n    super(`aifsmjs: action \"${actionName}\" not found in implementations.actions`);\n    this.name = \"UnknownActionError\";\n    this.actionName = actionName;\n  }\n}\n\nfunction resolveAction<Ctx, Evt>(\n  ref: ActionRef<Ctx, Evt>,\n  impl: Implementations<Ctx, Evt>,\n): Action<Ctx, Evt> {\n  if (typeof ref === \"function\") return ref;\n  const fn = impl.actions?.[ref];\n  if (!fn) throw new UnknownActionError(ref);\n  return fn;\n}\n\nfunction runActions<Ctx, Evt>(\n  refs: readonly ActionRef<Ctx, Evt>[] | undefined,\n  ctx: Ctx,\n  event: Evt,\n  impl: Implementations<Ctx, Evt>,\n  effectSink: Effect[],\n): Ctx {\n  if (!refs || refs.length === 0) return ctx;\n  const enqueue = createEnqueuer(effectSink as { type: string; payload?: unknown }[]);\n  let current = ctx;\n  for (const ref of refs) {\n    const fn = resolveAction(ref, impl);\n    const patch = fn({ context: current, event, enqueue });\n    current = mergeContext(current, patch);\n  }\n  return current;\n}\n\nfunction pickTransition<Ctx, Evt, States extends string>(\n  candidates: readonly TransitionDef<Ctx, Evt, States>[],\n  ctx: Ctx,\n  event: Evt,\n  impl: Implementations<Ctx, Evt>,\n  value: States,\n): TransitionDef<Ctx, Evt, States> | undefined {\n  for (const t of candidates) {\n    if (!t.guard) return t;\n    if (evalGuard(t.guard, ctx, event, impl, value)) return t;\n  }\n  return undefined;\n}\n\n/**\n * Compute the next snapshot and collected effects from a single event.\n *\n * Order is fixed and uninterruptible:\n *   1. resolve candidate transitions for (state, event.type)\n *   2. evaluate guards in declaration order; pick the first passing one\n *   3. if external (target defined), run exit actions of the old state\n *   4. run transition.actions in declaration order\n *   5. if external, run entry actions of the new state\n *   6. return { snapshot, effects, changed }\n *\n * The function is pure: it never dispatches effects and never mutates inputs.\n */\nexport function step<Ctx, Evt extends { type: string }, States extends string>(\n  def: MachineDef<Ctx, Evt, States>,\n  snapshot: Snapshot<Ctx, States>,\n  event: Evt,\n  impl: Implementations<Ctx, Evt>,\n): StepResult<Ctx, States> {\n  // Final state is inert: it never reacts to events.\n  if (snapshot.status === \"final\") {\n    return Object.freeze({ snapshot, effects: [] as readonly Effect[], changed: false });\n  }\n\n  const state = def.states[snapshot.value];\n  /* v8 ignore next 3 — defensive: snapshot.value is always validated against def.states by defineMachine + initialSnapshot. */\n  if (!state) {\n    return Object.freeze({ snapshot, effects: [] as readonly Effect[], changed: false });\n  }\n\n  const candidateList = normalizeTransitions(state.on?.[event.type]);\n\n  const chosen = pickTransition(candidateList, snapshot.context, event, impl, snapshot.value);\n  if (!chosen) {\n    return Object.freeze({ snapshot, effects: [] as readonly Effect[], changed: false });\n  }\n\n  const isExternal = chosen.target !== undefined;\n  const nextStateValue = (chosen.target ?? snapshot.value) as States;\n  const nextState = def.states[nextStateValue];\n\n  const effectSink: Effect[] = [];\n  let ctx = snapshot.context;\n\n  if (isExternal) {\n    ctx = runActions(state.exit, ctx, event, impl, effectSink);\n  }\n  ctx = runActions(chosen.actions, ctx, event, impl, effectSink);\n  if (isExternal && nextState) {\n    ctx = runActions(nextState.entry, ctx, event, impl, effectSink);\n  }\n\n  const status: \"active\" | \"final\" = nextState?.final === true ? \"final\" : \"active\";\n  const nextSnapshot = freezeSnapshot({\n    value: nextStateValue,\n    context: ctx,\n    status,\n  });\n\n  return Object.freeze({\n    snapshot: nextSnapshot,\n    effects: Object.freeze(effectSink.slice()) as readonly Effect[],\n    changed: true,\n  });\n}\n","import { step } from \"../fsm/lifecycle.js\";\nimport type { Effect, Implementations, MachineDef, Snapshot } from \"../fsm/types.js\";\n\nexport type ReplayResult<Ctx, States extends string> = Readonly<{\n  snapshot: Snapshot<Ctx, States>;\n  effects: readonly Effect[];\n}>;\n\n/**\n * Fold an event log into a final snapshot via `step()`. Effects are collected\n * but never dispatched — this is a pure function, suitable for PBT, time\n * travel, and incident reproduction.\n *\n * Equivalent to:\n *   events.reduce((s, e) => step(def, s, e, impl).snapshot, initial)\n * but also accumulates the effects across all events.\n */\nexport function replay<Ctx, Evt extends { type: string }, States extends string>(\n  initial: Snapshot<Ctx, States>,\n  events: readonly Evt[],\n  def: MachineDef<Ctx, Evt, States>,\n  impl: Implementations<Ctx, Evt>,\n): ReplayResult<Ctx, States> {\n  let snapshot = initial;\n  const effects: Effect[] = [];\n  for (const event of events) {\n    const r = step(def, snapshot, event, impl);\n    snapshot = r.snapshot;\n    if (r.effects.length > 0) {\n      for (const eff of r.effects) effects.push(eff);\n    }\n  }\n  return Object.freeze({ snapshot, effects: Object.freeze(effects.slice()) });\n}\n"]}

package/dist/{types-CGKk6Rur.d.cts → types-DIM7QTtf.d.cts}

@@ -40,6 +40,15 @@ type TransitionDef<Ctx, Evt, States extends string> = Readonly<{
     guard?: GuardRef<Ctx, Evt>;
     actions?: readonly ActionRef<Ctx, Evt>[];
 }>;
+/**
+ * A single transition as written in a `StateDef.on` map. Either the full
+ * {@link TransitionDef} object form, or the string shorthand `"targetState"`
+ * (à la XState) which the resolver normalizes to `{ target: "targetState" }`
+ * before processing. The shorthand carries no guard or actions.
+ *
+ * @since 0.5.3
+ */
+type TransitionConfig<Ctx, Evt, States extends string> = States | TransitionDef<Ctx, Evt, States>;
 /**
  * @experimental v0.3.0
  *
@@ -56,7 +65,7 @@ type SubMachineDef<SubCtx, SubEvt extends {
     type: string;
 }, SubStates extends string> = MachineDef<SubCtx, SubEvt, SubStates>;
 type StateDef<Ctx, Evt, States extends string> = Readonly<{
-    on?: Readonly<Record<string, TransitionDef<Ctx, Evt, States> | readonly TransitionDef<Ctx, Evt, States>[]>>;
+    on?: Readonly<Record<string, TransitionConfig<Ctx, Evt, States> | readonly TransitionConfig<Ctx, Evt, States>[]>>;
     entry?: readonly ActionRef<Ctx, Evt>[];
     exit?: readonly ActionRef<Ctx, Evt>[];
     final?: boolean;
@@ -90,6 +99,27 @@ type MachineDef<Ctx, Evt extends {
     context: Ctx;
     states: Readonly<Record<States, StateDef<Ctx, Evt, States>>>;
 }>;
+/**
+ * Input shape accepted by `defineMachine` / `setup().defineMachine`. Identical
+ * to {@link MachineDef} except `context` is **optional** — when omitted it
+ * defaults to `{}` (paired with the `Ctx = Record<string, never>` default type
+ * parameter). The returned value is always a fully-normalized
+ * {@link MachineDef} with `context` present, so downstream consumers are
+ * unaffected.
+ *
+ * @since 0.5.3
+ */
+type MachineConfig<Ctx, Evt extends {
+    type: string;
+}, States extends string> = Readonly<{
+    id: string;
+    initial: States;
+    states: Readonly<Record<States, StateDef<Ctx, Evt, States>>>;
+}> & (Record<string, never> extends Ctx ? {
+    readonly context?: Ctx;
+} : {
+    readonly context: Ctx;
+});
 type Snapshot<Ctx, States extends string> = Readonly<{
     value: States;
     context: Ctx;
@@ -244,4 +274,4 @@ type RuntimeOptions<Ctx, Evt, States extends string> = Readonly<{
     dispatchEffects?: boolean;
 }>;
 
-export { type Action as A, type Effect as E, type Guard as G, type Implementations as I, type MachineDef as M, RESET_EVENT_TYPE as R, type Snapshot as S, type TransitionDef as T, type ActionRef as a, type EffectHandler as b, type Enqueuer as c, type GuardArgs as d, type GuardRef as e, type Middleware as f, type MiddlewareContext as g, type ResetEvent as h, type Runtime as i, type RuntimeErrorEvent as j, type RuntimeEventMap as k, type RuntimeOptions as l, type RuntimeTransitionEvent as m, type StateDef as n, type StepResult as o, type SubMachineDef as p };
+export { type Action as A, type Effect as E, type Guard as G, type Implementations as I, type MachineConfig as M, RESET_EVENT_TYPE as R, type Snapshot as S, type TransitionConfig as T, type ActionRef as a, type EffectHandler as b, type Enqueuer as c, type GuardArgs as d, type GuardRef as e, type MachineDef as f, type Middleware as g, type MiddlewareContext as h, type ResetEvent as i, type Runtime as j, type RuntimeErrorEvent as k, type RuntimeEventMap as l, type RuntimeOptions as m, type RuntimeTransitionEvent as n, type StateDef as o, type StepResult as p, type SubMachineDef as q, type TransitionDef as r };

package/dist/{types-CGKk6Rur.d.ts → types-DIM7QTtf.d.ts}

@@ -40,6 +40,15 @@ type TransitionDef<Ctx, Evt, States extends string> = Readonly<{
     guard?: GuardRef<Ctx, Evt>;
     actions?: readonly ActionRef<Ctx, Evt>[];
 }>;
+/**
+ * A single transition as written in a `StateDef.on` map. Either the full
+ * {@link TransitionDef} object form, or the string shorthand `"targetState"`
+ * (à la XState) which the resolver normalizes to `{ target: "targetState" }`
+ * before processing. The shorthand carries no guard or actions.
+ *
+ * @since 0.5.3
+ */
+type TransitionConfig<Ctx, Evt, States extends string> = States | TransitionDef<Ctx, Evt, States>;
 /**
  * @experimental v0.3.0
  *
@@ -56,7 +65,7 @@ type SubMachineDef<SubCtx, SubEvt extends {
     type: string;
 }, SubStates extends string> = MachineDef<SubCtx, SubEvt, SubStates>;
 type StateDef<Ctx, Evt, States extends string> = Readonly<{
-    on?: Readonly<Record<string, TransitionDef<Ctx, Evt, States> | readonly TransitionDef<Ctx, Evt, States>[]>>;
+    on?: Readonly<Record<string, TransitionConfig<Ctx, Evt, States> | readonly TransitionConfig<Ctx, Evt, States>[]>>;
     entry?: readonly ActionRef<Ctx, Evt>[];
     exit?: readonly ActionRef<Ctx, Evt>[];
     final?: boolean;
@@ -90,6 +99,27 @@ type MachineDef<Ctx, Evt extends {
     context: Ctx;
     states: Readonly<Record<States, StateDef<Ctx, Evt, States>>>;
 }>;
+/**
+ * Input shape accepted by `defineMachine` / `setup().defineMachine`. Identical
+ * to {@link MachineDef} except `context` is **optional** — when omitted it
+ * defaults to `{}` (paired with the `Ctx = Record<string, never>` default type
+ * parameter). The returned value is always a fully-normalized
+ * {@link MachineDef} with `context` present, so downstream consumers are
+ * unaffected.
+ *
+ * @since 0.5.3
+ */
+type MachineConfig<Ctx, Evt extends {
+    type: string;
+}, States extends string> = Readonly<{
+    id: string;
+    initial: States;
+    states: Readonly<Record<States, StateDef<Ctx, Evt, States>>>;
+}> & (Record<string, never> extends Ctx ? {
+    readonly context?: Ctx;
+} : {
+    readonly context: Ctx;
+});
 type Snapshot<Ctx, States extends string> = Readonly<{
     value: States;
     context: Ctx;
@@ -244,4 +274,4 @@ type RuntimeOptions<Ctx, Evt, States extends string> = Readonly<{
     dispatchEffects?: boolean;
 }>;
 
-export { type Action as A, type Effect as E, type Guard as G, type Implementations as I, type MachineDef as M, RESET_EVENT_TYPE as R, type Snapshot as S, type TransitionDef as T, type ActionRef as a, type EffectHandler as b, type Enqueuer as c, type GuardArgs as d, type GuardRef as e, type Middleware as f, type MiddlewareContext as g, type ResetEvent as h, type Runtime as i, type RuntimeErrorEvent as j, type RuntimeEventMap as k, type RuntimeOptions as l, type RuntimeTransitionEvent as m, type StateDef as n, type StepResult as o, type SubMachineDef as p };
+export { type Action as A, type Effect as E, type Guard as G, type Implementations as I, type MachineConfig as M, RESET_EVENT_TYPE as R, type Snapshot as S, type TransitionConfig as T, type ActionRef as a, type EffectHandler as b, type Enqueuer as c, type GuardArgs as d, type GuardRef as e, type MachineDef as f, type Middleware as g, type MiddlewareContext as h, type ResetEvent as i, type Runtime as j, type RuntimeErrorEvent as k, type RuntimeEventMap as l, type RuntimeOptions as m, type RuntimeTransitionEvent as n, type StateDef as o, type StepResult as p, type SubMachineDef as q, type TransitionDef as r };

package/llms-full.txt

@@ -177,13 +177,34 @@ aifsmjs follows the XState v5 two-phase pattern (`setup().createMachine()`): the
 
 ```typescript
 function defineMachine<
-  Ctx,
-  Evt extends { type: string },
-  States extends string,
->(def: MachineDef<Ctx, Evt, States>): MachineDef<Ctx, Evt, States>;
+  Ctx = Record<string, never>,
+  Evt extends { type: string } = { type: string },
+  States extends string = string,
+>(def: MachineConfig<Ctx, Evt, States>): MachineDef<Ctx, Evt, States>;
 ```
 
-Pure data builder. Freezes the whole definition and validates that `initial` exists in the `states` map.
+Pure data builder. Validates that `initial` exists in the `states` map and returns the (normalized) definition.
+
+`context` is **optional** — omit it for stateless machines and it defaults to `{}` (the type parameter defaults to `Record<string, never>`). Existing definitions that pass `context` are unaffected.
+
+```typescript
+// No context needed — defaults to {}
+const toggle = defineMachine({
+  id: "toggle",
+  initial: "off",
+  states: {
+    off: { on: { TOGGLE: "on" } },   // string shorthand, see below
+    on:  { on: { TOGGLE: "off" } },
+  },
+});
+```
+
+**String-shorthand transitions.** A transition value may be either the full object form or a bare target-state string (à la XState). The string is normalized to `{ target }` before processing — it carries no guard or actions:
+
+```typescript
+on: { NEXT: "green" }                 // shorthand for { target: "green" }
+on: { NEXT: [{ target: "a", guard: "g" }, "b"] }  // mixes with the object form
+```
 
 ### `createRuntime(def, impl, opts?)`
 
@@ -220,7 +241,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 +300,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 +319,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;
+    },
   ),
 );
 ```
@@ -419,6 +451,8 @@ aifsmjs ships a few opinionated calls that look different from the typical FSM l
 - **Guards and reducers are sync.** A non-deterministic guard would break the PBT determinism property (#1 in the generic suite). Move async predicates into events: send `FETCH_REQUEST`, then later `FETCH_DONE` with the resolved value as payload.
 - **Effects are descriptors, not inline callbacks.** Actions enqueue `{ type, payload }` via `enqueue.effect(...)`; the runtime collects them and the dispatcher invokes user handlers. This keeps machine definitions serializable (JSON round-trippable when no inline functions are used), enables `replay()` to fold an event log into the same snapshot, and lets `inspect/persist` middleware capture effects for audit logs.
 - **Two factory paths coexist.** `setup<Ctx, Evt>().defineMachine(...)` is the type-friendly form (States inferred from `keyof states`). `createMachine(def, impl, opts?)` is the spec-style single-factory shortcut from the ai*js ecosystem review. Plain `defineMachine<Ctx, Evt, States>(def)` remains for explicit generic control. Pick whichever reads best at the call site.
+- **Transitions accept a string shorthand.** `on: { EVENT: "targetState" }` is sugar for `on: { EVENT: { target: "targetState" } }`, normalized in the resolver before any guard/action processing. The shorthand has no guard or actions; reach for the object form when you need them. It composes inside the array form too, so guard-fallthrough lists can mix `{ target, guard }` objects with bare target strings. The full object form is unchanged — this is purely additive.
+- **`context` is optional.** Omit it for stateless machines and it defaults to `{}` (`Ctx` defaults to `Record<string, never>`). Definitions that already pass `context` keep their inferred type and behave identically.
 - **`subscribe(listener)` and `on(type, fn, { signal, once })` both exist.** The typed `on()` matches the platform `EventTarget` semantics (signal + once) and emits `'transition'`, `'error'`, `'dispose'`. The older `subscribe()` keeps the React `useSyncExternalStore` shape — pass it directly. They are not exclusive.
 
 ---
@@ -545,6 +579,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.3] - 2026-06-05
+
+### Added
+
+- **String-shorthand transitions and optional `context` (both additive, non-breaking).** Transitions now accept a bare target string — `on: { EVENT: "target" }` is sugar for `{ target: "target" }`, normalized in the resolver and composable inside guard-fallthrough arrays; and `context` is now optional in `defineMachine` / `setup().defineMachine`, defaulting to `{}` (`Ctx` defaults to `Record<string, never>`). Existing object-form transitions and explicit-`context` definitions are unaffected. (`src/fsm/types.ts`, `src/fsm/resolver.ts`, `src/fsm/definition.ts`, `src/fsm/lifecycle.ts`, `src/fsm/runtime.ts`)
+
+## [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aifsmjs",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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",