@mantaq/core 0.0.2 → 0.1.0

package/README.md

@@ -10,18 +10,19 @@ npm install @mantaq/core
 
 ## Quick Reference
 
-| Pattern         | Correct                            | Anti-pattern                           |
-| --------------- | ---------------------------------- | -------------------------------------- |
-| Type context    | `context: {} as MyContext`         | casting in every handler               |
-| Type events     | `event("ID")<Payload>()`           | `event("ID")()` without generic        |
-| Send events     | `actor.send(event.create(data))`   | raw `{ id: "ID", ... }` objects        |
-| Effect data     | Use state payload                  | Depend on `event` in effect            |
-| Error handling  | Emit internal event                | Throw in effect or transition          |
-| Internal events | Declare in `internal: [...]`       | Put user events in internal            |
-| Signal check    | `if (signal.aborted) return`       | Skip abort check in async work         |
-| Regions         | Child outputs in parent `internal` | Forget to declare child outputs        |
-| Snapshot        | Save path + context manually       | Expect `snapshot()` to include context |
-| Any handler     | Universal events only (CANCEL)     | State-specific logic in `onAny`        |
+| Pattern         | Correct                                | Anti-pattern                          |
+| --------------- | -------------------------------------- | ------------------------------------- |
+| Type context    | `context: {} as MyContext`             | casting in every handler              |
+| Write context   | `context.set({ ...context.get() })`    | mutate without `set()`                |
+| Type events     | `event("ID")<Payload>()`               | `event("ID")()` without generic       |
+| Send events     | `actor.send(signInEvent.create(data))` | raw `{ type: "ID", payload }` objects |
+| Effect data     | Use state payload                      | Depend on `event` in effect           |
+| Error handling  | Emit internal event                    | Throw in effect or transition         |
+| Internal events | Declare in `internal: [...]`           | Put user events in internal           |
+| Signal check    | `if (signal.aborted) return`           | Skip abort check in async work        |
+| Regions         | Child outputs in parent `internal`     | Forget to declare child outputs       |
+| Snapshot        | `snapshot()` carries path + context    | Re-serialize context by hand          |
+| Any handler     | Universal events only (CANCEL)         | State-specific logic in `onAny`       |
 
 ## Contents
 
@@ -94,20 +95,34 @@ const actor = new Actor({
   context: {} as AuthContext,
   setup: (m) => {
     m.on(idleState, signInEvent, (event, opts) => {
-      opts!.context.phoneNumber = event.phoneNumber; // ✅ typed
+      // ✅ typed — context.get()/set() flow the constructor type
+      opts!.context.set({ ...opts!.context.get(), phoneNumber: event.payload.phoneNumber });
       return { state: signingInState };
     });
   },
 });
 ```
 
+`set()` is the write signal — always call it to write, even when the new value is the same reference. Any `set()` triggers `change`. Spread the current value:
+
+```ts
+opts.context.set({ ...opts.context.get(), phoneNumber: event.payload.phoneNumber });
+```
+
+**Never mutate in place:**
+
+```ts
+// ❌ mutation without set() — never signals; subscribers and persistence stay silent
+opts!.context.phoneNumber = event.payload.phoneNumber;
+```
+
 **Anti-pattern — casting in every handler:**
 
 ```ts
 setup: (m) => {
   m.on(idleState, signInEvent, (event, opts) => {
     const c = opts!.context as AuthContext; // ❌ unnecessary — already typed
-    c.phoneNumber = event.phoneNumber;
+    c.set({ ...c.get(), phoneNumber: event.payload.phoneNumber });
     return { state: signingInState };
   });
 },
@@ -132,7 +147,7 @@ Handlers receive the correct payload type:
 ```ts
 setup: (m) => {
   m.on(idleState, signInEvent, (event) => {
-    event.phoneNumber; // ✅ string
+    event.payload.phoneNumber; // ✅ string
     return { state: signingInState };
   });
 },
@@ -155,12 +170,12 @@ const goodEvent = event("SIGN_IN")<{ phoneNumber: string }>();
 actor.send(signInEvent.create({ phoneNumber: "+1234567890" }));
 
 // ❌ bypasses type checking
-actor.send({ id: "SIGN_IN", phoneNumber: "+1234567890" });
+actor.send({ type: "SIGN_IN", payload: { phoneNumber: "+1234567890" } });
 ```
 
 ### Effects and Event Typing
 
-Effects run when entering a state. The `event` parameter in effects is typed as the union of all possible events (`Inputs[number] | Internal[number]`) — not the specific event that triggered the transition. This is by design: effects live on states, not transitions. Multiple transitions can lead to the same state, so the effect cannot know which event caused entry.
+Effects run when entering a state. The `event` parameter in effects is typed `InternalEvent` — `{ type, payload? }` with `payload: unknown` — not the specific event that triggered the transition. This is by design: effects live on states, not transitions. Multiple transitions can lead to the same state, so the effect cannot know which event caused entry.
 
 **Pass data to effects via state payload.** Set the payload in the transition return, read it from `state.payload` in the effect.
 
@@ -184,7 +199,7 @@ const actor = new Actor({
       });
     });
     m.on(idleState, fetchEvent, (event) => {
-      return { state: loadingState.create({ url: event.url }) };
+      return { state: loadingState.create({ url: event.payload.url }) };
     });
     m.on(loadingState, doneEvent, () => ({ state: loadedState }));
   },
@@ -195,10 +210,10 @@ const actor = new Actor({
 
 ```ts
 // ✅ state payload — scoped to this state entry
-return { state: loadingState.create({ url: event.url }) };
+return { state: loadingState.create({ url: event.payload.url }) };
 
 // ⚠️ context — works but shared across all states
-opts!.context.url = event.url;
+opts!.context.set({ ...opts!.context.get(), url: event.payload.url });
 return { state: loadingState };
 ```
 
@@ -206,9 +221,8 @@ return { state: loadingState };
 
 ```ts
 m.effect(loadingState, ({ event, emit }) => {
-  // ❌ event is the union type, not the specific triggering event
-  // event.url doesn't exist on the union
-  emit(doneEvent.create()); // fine — but event.url would be a type error
+  // ❌ event is InternalEvent — payload is unknown, not the triggering event's payload
+  emit(doneEvent.create()); // fine — but event.payload.url would be a type error
 });
 ```
 
@@ -289,7 +303,10 @@ function createActor() {
       m.on(idleState, startEvent, () => ({ state: workingState }));
       m.on(workingState, doneEvent, () => ({ state: doneState }));
       m.on(workingState, failedEvent, (_event, opts) => {
-        opts!.context.retryCount++;
+        opts!.context.set({
+          ...opts!.context.get(),
+          retryCount: opts!.context.get().retryCount + 1,
+        });
         return { state: errorState };
       });
     },
@@ -320,45 +337,29 @@ m.effect(workingState, ({ signal, emit, clock }) => {
 
 ### Snapshot & Restore
 
-`actor.snapshot()` returns a serializable `Snapshot` — `{ path, regions, done? }`. It does **not** include context. Use it to save/restore actor state across sessions.
+`actor.snapshot()` returns a `Snapshot` — `{ path, context, regions, done?, error? }`. Context is included. Use it to save/restore actor state across sessions.
 
 ```ts
-interface SerializedActor {
-  path: string[];
-  regions: Record<string, unknown>;
-  context: Record<string, unknown>;
-}
-
-function saveActor(actor: { snapshot(): Snapshot; context: unknown }): SerializedActor {
-  return {
-    ...actor.snapshot(),
-    context: { ...(actor.context as Record<string, unknown>) },
-  };
-}
-
-// Usage
-const saved = saveActor(actor);
+// Snapshot carries path, context, and regions — serialize it directly
+const saved = actor.snapshot();
 localStorage.setItem("actor", JSON.stringify(saved));
 
 const raw = localStorage.getItem("actor");
 if (raw) {
-  const data = JSON.parse(raw) as SerializedActor;
-  // restore from data.path and data.context
+  const data = JSON.parse(raw) as Snapshot;
+  // rebuild the actor from data.path (re-seed context from data.context if needed)
 }
 ```
 
-**Anti-pattern — trying to snapshot context via `snapshot()`:**
+**Anti-pattern — re-serializing context by hand:**
 
 ```ts
-// ❌ snapshot() only returns path + regions, not context
+// ❌ snapshot() already includes context — no manual step needed
 const snap = actor.snapshot();
-snap.context; // doesn't exist
+snap.context; // exists
 
-// ✅ serialize context yourself
-const stateData = {
-  path: actor.snapshot().path,
-  context: { ...actor.context },
-};
+// ✅ save the snapshot as-is
+const stateData = actor.snapshot();
 ```
 
 ### Dynamic Children (Regions)
@@ -374,10 +375,10 @@ const healthMonitor = new Actor({
   initial: unknownState,
   setup: (m) => {
     m.on(unknownState, healthCheckResult, (event) => ({
-      state: event.healthy ? healthyState : degradedState,
+      state: event.payload.healthy ? healthyState : degradedState,
     }));
     m.on(healthyState, healthCheckResult, (event) => ({
-      state: event.healthy ? healthyState : degradedState,
+      state: event.payload.healthy ? healthyState : degradedState,
     }));
   },
 });
@@ -391,7 +392,7 @@ const manager = new Actor({
   setup: (m) => {
     m.on(connectedState, healthCheckResult, (event, opts) => {
       // access child via actor.regions
-      manager.regions.health.send(healthCheckResult.create({ healthy: event.healthy }));
+      manager.regions.health.send(healthCheckResult.create({ healthy: event.payload.healthy }));
       return {};
     });
   },
@@ -424,7 +425,16 @@ const parent = new Actor({
 
 ### Error Handling
 
-Never throw from effects or transitions. Emit an error as an internal event and let a transition handle it. Errors thrown inside a handler or effect have no subscriber — the machine just stops applying it.
+Never throw from effects or transitions. Emit an error as an internal event and let a transition handle it. If user code throws anyway, the machine does **not** misbehave silently: it dies into a built-in terminal `__error` state, records `snapshot().error` (the thrown value, the last known good state/context, the bad event), drops remaining events, and ignores later `send`s. Errors never escape `send()` and the machine stays deterministic — same inputs, same trace.
+
+```ts
+const snap = actor.snapshot();
+if (snap.error) {
+  snap.error.reason; // "transition" | "effect" | "budget" | "output" | "internal" | "async"
+  snap.error.state.name; // last known good state
+  snap.error.event.type; // the bad event
+}
+```
 
 Catch errors inside effects and emit recovery events:
 
@@ -448,7 +458,7 @@ setup: (m) => {
   m.on(workingState, doneEvent, () => ({ state: doneState }));
   m.on(workingState, failedEvent, (event) => {
     // handle error in transition, not in effect
-    return { state: errorState.create({ error: event.error }) };
+    return { state: errorState.create({ error: event.payload.error }) };
   });
 },
 ```
@@ -460,7 +470,7 @@ try {
   const result = riskyOperation();
   emit(doneEvent.create());
 } catch (err) {
-  throw err; // ❌ throw in effect — no handler, machine misbehaves
+  throw err; // ❌ throw in effect — the machine dies into __error
 }
 ```
 
@@ -468,7 +478,7 @@ try {
 
 ```ts
 m.on(idleState, submitEvent, (event) => {
-  if (!event.data) throw new Error("missing data"); // ❌ breaks the machine
+  if (!event.payload.data) throw new Error("missing data"); // ❌ kills the machine
   return { state: doneState };
 });
 ```
@@ -477,8 +487,8 @@ Prefer storing the error in context and transitioning to an error state:
 
 ```ts
 m.on(idleState, submitEvent, (event, opts) => {
-  if (!event.data) {
-    opts!.context.error = "missing data";
+  if (!event.payload.data) {
+    opts!.context.set({ ...opts!.context.get(), error: "missing data" });
     return { state: errorState };
   }
   return { state: doneState };
@@ -493,7 +503,7 @@ Use `onAny` to intercept events across all states — useful for universal error
 setup: (m) => {
   // CANCEL works from any state
   m.onAny(cancelEvent, (_event, opts) => {
-    opts!.context.cancelled = true;
+    opts!.context.set({ ...opts!.context.get(), cancelled: true });
     return { state: cancelledState };
   });
   // State-specific handlers still run for their state
@@ -507,13 +517,13 @@ setup: (m) => {
 setup: (m) => {
   // ❌ state-specific logic in onAny defeats the purpose
   m.onAny(submitBasicInfoEvent, (event, opts) => {
-    opts!.context.basicInfo = event; // wrong — only makes sense in basicInfo state
+    opts!.context.set({ ...opts!.context.get(), basicInfo: event }); // wrong — only makes sense in basicInfo state
     return { state: shippingAddressState };
   });
 
   // ✅ keep state-specific logic in state handlers
   m.on(basicInfoState, submitBasicInfoEvent, (event, opts) => {
-    opts!.context.basicInfo = event;
+    opts!.context.set({ ...opts!.context.get(), basicInfo: event });
     return { state: shippingAddressState };
   });
 },

package/dist/{actor-internal-CBU_EDPZ.d.mts → actor-internal-DYAL1iYK.d.mts}

@@ -20,27 +20,30 @@ declare class StateRef<T extends string, Payload = unknown, IsFinal extends bool
 }
 //#endregion
 //#region src/event.d.ts
-declare function event<const T extends string>(id: T): <Payload extends object | void = void>() => EventRef<T, Payload>;
+declare function event<const T extends string>(type: T): <Payload extends object | void = void>() => EventRef<T, Payload>;
 type AnyEventRef = EventRef<string, object | void>;
 type InternalEvent = {
-  id: string;
-} & Record<string, unknown>;
-type CreatedOfEvent<Id extends string, P> = P extends void ? {
-  id: Id;
-} : P & {
-  id: Id;
+  type: string;
+  payload?: unknown;
+};
+type CreatedOfEvent<T extends string, P> = P extends void ? {
+  type: T;
+} : {
+  type: T;
+  payload: P;
 };
 declare class EventRef<const T extends string, Payload extends object | void = void> {
-  readonly id: T;
-  constructor(id: T);
+  readonly type: T;
+  constructor(type: T);
   is(anyEvent: unknown): anyEvent is CreatedOfEvent<T, Payload>;
   create(): Payload extends void ? {
-    id: T;
+    type: T;
   } : void;
   create(payload: Payload): Payload extends void ? {
-    id: T;
-  } : Payload & {
-    id: T;
+    type: T;
+  } : {
+    type: T;
+    payload: Payload;
   };
 }
 //#endregion
@@ -60,12 +63,58 @@ interface Clock {
   setDrain?(fn: () => void): void;
 }
 //#endregion
+//#region src/context.d.ts
+declare class Context<T> {
+  #private;
+  constructor(get: () => T, set: (value: T) => void);
+  get(): T;
+  set(value: T): void;
+}
+//#endregion
+//#region src/actor-types.d.ts
+type CreatedOf<E extends AnyEventRef> = E extends EventRef<infer Type, infer P> ? CreatedOfEvent<Type, P> : never;
+type NonFinalStateRef<States extends AnyStateRef[]> = Extract<States[number], {
+  isFinal: false;
+}>;
+interface EffectInput<ActorContext, Payload = unknown> {
+  signal: AbortSignal;
+  state: {
+    name: string;
+    payload: Payload;
+  };
+  event: InternalEvent;
+  context: Context<ActorContext>;
+  emit: (event: InternalEvent) => void;
+  clock: Clock;
+}
+type EffectFn<ActorContext, Payload = unknown> = (input: EffectInput<ActorContext, Payload>) => void | Promise<void>;
+type ErrorReason = "transition" | "effect" | "budget" | "output" | "internal" | "async";
+interface ErrorInfo {
+  error: unknown;
+  state: AnyStateRef;
+  context: unknown;
+  event: InternalEvent;
+  reason: ErrorReason;
+}
+type ErrorState = StateRef<"__error", unknown, false>;
+type TransitionResult<AllowedState extends AnyStateRef = AnyStateRef, AllowedEmit extends string = string> = {
+  state?: AllowedState | {
+    state: AllowedState;
+    payload?: unknown;
+  };
+  payload?: unknown;
+  emit?: Array<{
+    type: AllowedEmit;
+  }>;
+};
+//#endregion
 //#region src/actor-internal.d.ts
 interface Snapshot<C = unknown> {
   path: string[];
   context: C;
   regions: Record<string, Snapshot<unknown>>;
   done?: boolean;
+  error?: ErrorInfo;
 }
 interface AnyActor<C = Record<string, unknown>> {
   state: AnyStateRef;
@@ -87,4 +136,4 @@ interface AnyActor<C = Record<string, unknown>> {
   };
 }
 //#endregion
-export { CreatedOfEvent as a, event as c, state as d, AnyEventRef as i, AnyStateRef as l, Snapshot as n, EventRef as o, Clock as r, InternalEvent as s, AnyActor as t, StateRef as u };
+export { AnyStateRef as _, EffectInput as a, NonFinalStateRef as c, Clock as d, AnyEventRef as f, event as g, InternalEvent as h, EffectFn as i, TransitionResult as l, EventRef as m, Snapshot as n, ErrorInfo as o, CreatedOfEvent as p, CreatedOf as r, ErrorState as s, AnyActor as t, Context as u, StateRef as v, state as y };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as CreatedOfEvent, c as event, d as state, i as AnyEventRef, l as AnyStateRef, n as Snapshot, o as EventRef, r as Clock, s as InternalEvent, t as AnyActor, u as StateRef } from "./actor-internal-CBU_EDPZ.mjs";
+import { _ as AnyStateRef, a as EffectInput, c as NonFinalStateRef, d as Clock, f as AnyEventRef, g as event, h as InternalEvent, i as EffectFn, l as TransitionResult, m as EventRef, n as Snapshot, o as ErrorInfo, p as CreatedOfEvent, r as CreatedOf, s as ErrorState, t as AnyActor, u as Context, v as StateRef, y as state } from "./actor-internal-DYAL1iYK.mjs";
 //#region src/real-clock.d.ts
 declare class RealClock implements Clock {
   #private;
@@ -38,44 +38,8 @@ declare class VirtualClock implements Clock {
   setDrain(fn: () => void): void;
 }
 //#endregion
-//#region src/context.d.ts
-declare class Context<T> {
-  #private;
-  constructor(get: () => T, set: (value: T) => void);
-  get(): T;
-  set(value: T): void;
-}
-//#endregion
-//#region src/actor-types.d.ts
-type CreatedOf<E extends AnyEventRef> = E extends EventRef<infer Id, infer P> ? CreatedOfEvent<Id, P> : never;
-type NonFinalStateRef<States extends AnyStateRef[]> = Extract<States[number], {
-  isFinal: false;
-}>;
-interface EffectInput<ActorContext, Payload = unknown> {
-  signal: AbortSignal;
-  state: {
-    name: string;
-    payload: Payload;
-  };
-  event: InternalEvent;
-  context: Context<ActorContext>;
-  emit: (event: InternalEvent) => void;
-  clock: Clock;
-}
-type EffectFn<ActorContext, Payload = unknown> = (input: EffectInput<ActorContext, Payload>) => void;
-type TransitionResult<AllowedState extends AnyStateRef = AnyStateRef, AllowedEmit extends string = string> = {
-  state?: AllowedState | {
-    state: AllowedState;
-    payload?: unknown;
-  };
-  payload?: unknown;
-  emit?: Array<{
-    id: AllowedEmit;
-  }>;
-};
-//#endregion
 //#region src/builder.d.ts
-type EventIdOf<E extends AnyEventRef> = E extends EventRef<infer Id, object | void> ? Id : never;
+type EventTypeOf<E extends AnyEventRef> = E extends EventRef<infer Type, object | void> ? Type : never;
 type PayloadOf<S extends AnyStateRef> = S extends StateRef<infer _Name, infer Payload, infer _IsFinal> ? Payload : never;
 type TransitionHandler<States extends readonly AnyStateRef[], ActorContext> = (event: InternalEvent, opts: {
   context: Context<ActorContext>;
@@ -87,25 +51,21 @@ interface BuiltMaps<States extends readonly AnyStateRef[], ActorContext> {
 }
 declare class ActorBuilder<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext> {
   #private;
-  on<S extends States[number], E extends Inputs[number] | Internal[number]>(stateRef: S, eventRef: E, fn: (event: E extends EventRef<infer Id, infer P> ? CreatedOfEvent<Id, P> : never, opts: {
+  on<S extends States[number], E extends Inputs[number] | Internal[number]>(stateRef: S, eventRef: E, fn: (event: E extends EventRef<infer Type, infer P> ? CreatedOfEvent<Type, P> : never, opts: {
     context: Context<ActorContext>;
     actor: AnyActor;
-  }) => TransitionResult<States[number], EventIdOf<Outputs[number]>>): this;
-  onAny<E extends Inputs[number] | Internal[number]>(eventRef: E, fn: (event: E extends EventRef<infer Id, infer P> ? CreatedOfEvent<Id, P> : never, opts: {
+  }) => TransitionResult<States[number], EventTypeOf<Outputs[number]>>): this;
+  onAny<E extends Inputs[number] | Internal[number]>(eventRef: E, fn: (event: E extends EventRef<infer Type, infer P> ? CreatedOfEvent<Type, P> : never, opts: {
     context: Context<ActorContext>;
     actor: AnyActor;
-  }) => TransitionResult<States[number], EventIdOf<Outputs[number]>>): this;
+  }) => TransitionResult<States[number], EventTypeOf<Outputs[number]>>): this;
   effect<S extends States[number]>(stateRef: S, fn: EffectFn<ActorContext, PayloadOf<S>>): this;
   /** @internal */ build(): BuiltMaps<States, ActorContext>;
 }
 type SetupFn<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext> = (m: ActorBuilder<States, Inputs, Internal, Outputs, ActorContext>) => void;
 //#endregion
 //#region src/actor.d.ts
-type CreatedOf$1<E extends AnyEventRef> = E extends EventRef<infer Id, infer P> ? (P extends void ? {
-  id: Id;
-} : P & {
-  id: Id;
-}) : never;
+type CreatedOf$1<E extends AnyEventRef> = E extends EventRef<infer Type, infer P> ? CreatedOfEvent<Type, P> : never;
 type InitialState<S extends AnyStateRef> = S extends StateRef<infer _N extends string, infer P> ? [unknown] extends [P] ? S | {
   state: S;
   payload?: P;
@@ -125,18 +85,9 @@ interface ActorOptions<States extends readonly AnyStateRef[], Inputs extends rea
   setup: SetupFn<States, Inputs, Internal, Outputs, ActorContext>;
   regions?: Record<string, AnyActor>;
 }
-interface InternalActorOptions<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext = Record<string, unknown>> {
-  inputs: Inputs;
-  outputs?: Outputs;
-  internal?: Internal;
-  states: States;
-  context?: ActorContext;
-  initial: InitialState<States[number]>;
-  clock?: Clock;
-  internalBudget?: number;
+interface InternalActorOptions<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext = Record<string, unknown>> extends Omit<ActorOptions<States, Inputs, Internal, Outputs, ActorContext>, "setup"> {
   transitions: TransitionDispatch<States, ActorContext>;
   effects: Record<string, Array<EffectFn<ActorContext>>>;
-  regions?: Record<string, AnyActor>;
 }
 type TransitionDispatch<States extends readonly AnyStateRef[], ActorContext> = Record<string, Record<string, ((event: InternalEvent, options: {
   context: Context<ActorContext>;
@@ -144,17 +95,16 @@ type TransitionDispatch<States extends readonly AnyStateRef[], ActorContext> = R
 }) => TransitionResult<States[number], string>) | undefined>>;
 declare class Actor<const States extends readonly AnyStateRef[], const Inputs extends readonly AnyEventRef[], const Internal extends readonly AnyEventRef[] = readonly [], const Outputs extends readonly AnyEventRef[] = readonly [], ActorContext = Record<string, unknown>> {
   #private;
-  state: States[number];
+  state: States[number] | ErrorState;
   readonly clock: Clock;
   get context(): ActorContext;
   get regions(): Record<string, AnyActor>;
   get options(): InternalActorOptions<States, Inputs, Internal, Outputs, ActorContext>;
   constructor(options: ActorOptions<States, Inputs, Internal, Outputs, ActorContext>);
-  on(event: "change", fn: (snapshot: Snapshot<ActorContext>, prev: Snapshot<ActorContext>) => void): () => void;
-  on(event: "done", fn: () => void): () => void;
+  on(event: "change" | "done", fn: ((snapshot: Snapshot<ActorContext>, prev: Snapshot<ActorContext>) => void) | (() => void)): () => void;
   settled(): Promise<void>;
   send(event: CreatedOf$1<Inputs[number]>): void;
   snapshot(): Snapshot<ActorContext>;
 }
 //#endregion
-export { Actor, type ActorBuilder, type AnyActor, type AnyEventRef, type AnyStateRef, type Clock, Context, type CreatedOf, type CreatedOfEvent, type EffectFn, type EffectInput, EventRef, type InternalEvent, type NonFinalStateRef, RealClock, type SetupFn, type Snapshot, StateRef, VirtualClock, event, state };
+export { Actor, type ActorBuilder, type AnyActor, type AnyEventRef, type AnyStateRef, type Clock, Context, type CreatedOf, type CreatedOfEvent, type EffectFn, type EffectInput, type ErrorInfo, type ErrorState, EventRef, type InternalEvent, type NonFinalStateRef, RealClock, type SetupFn, type Snapshot, StateRef, VirtualClock, event, state };

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import { registerActor, setOutputHandler } from "./internal.mjs";
+import { Either } from "@mantaq/utils";
 //#region src/state.ts
 function state(id) {
 	return () => new StateRef(id, false);
@@ -203,9 +204,6 @@ var InternalQueue = class {
 	get length() {
 		return this.#queue.length - this.#index;
 	}
-	get isProcessing() {
-		return this.#processing;
-	}
 	push(...events) {
 		if (this.#stopped) return;
 		this.#queue.push(...events);
@@ -216,12 +214,6 @@ var InternalQueue = class {
 			this.#settledResolvers.push(resolve);
 		});
 	}
-	process(processEvent) {
-		this.#process((event) => {
-			processEvent(event);
-			return true;
-		});
-	}
 	processCancellable(processEvent) {
 		this.#process(processEvent);
 	}
@@ -260,7 +252,8 @@ var Subscribers = class {
 	}
 	addChange(fn) {
 		this.change.add(fn);
-		if (this.#last) fn(this.#last, this.#last);
+		const last = this.#last;
+		if (last) this.#safe(() => fn(last, last));
 		return () => this.change.delete(fn);
 	}
 	addDone(fn) {
@@ -270,19 +263,23 @@ var Subscribers = class {
 	emitChange(snapshot) {
 		const prev = this.#last ?? snapshot;
 		this.#last = snapshot;
-		for (const fn of this.change) fn(snapshot, prev);
+		for (const fn of this.change) this.#safe(() => fn(snapshot, prev));
 	}
 	emitDone() {
-		for (const fn of this.done) fn();
+		for (const fn of this.done) this.#safe(fn);
 	}
 	clear() {
 		this.change.clear();
 		this.done.clear();
 	}
+	#safe(fn) {
+		const err = Either.from(fn);
+		if (err[0] !== void 0) console.warn(`[Actor] subscriber threw: ${err[0] instanceof Error ? err[0].message : "unknown error"}`);
+	}
 };
 //#endregion
 //#region src/snapshot.ts
-function buildSnapshot(s, regions, context) {
+function buildSnapshot(s, regions, context, error) {
 	const path = [s.name];
 	const regionSnapshots = {};
 	for (const [regionName, child] of Object.entries(regions)) regionSnapshots[regionName] = child.snapshot();
@@ -292,27 +289,40 @@ function buildSnapshot(s, regions, context) {
 		regions: regionSnapshots
 	};
 	if (s.isFinal) snap.done = true;
+	if (error !== void 0) snap.error = error;
 	return snap;
 }
 //#endregion
 //#region src/effects.ts
 function runEffects(options) {
-	if (options.state.isFinal) return null;
+	const pending = [];
+	if (options.state.isFinal) return { pending };
 	const list = options.effects[options.state.name];
-	if (!list || list.length === 0) return null;
-	const abort = new AbortController();
-	for (const effectFn of list) effectFn({
-		signal: abort.signal,
-		state: {
-			name: options.state.name,
-			payload: options.statePayload
-		},
-		event: options.event,
-		context: options.context,
-		emit: options.emit,
-		clock: options.clock
-	});
-	return abort;
+	if (!list) return { pending };
+	for (const effectFn of list) {
+		if (options.abort.signal.aborted) break;
+		const attempt = Either.from(() => effectFn({
+			signal: options.abort.signal,
+			state: {
+				name: options.state.name,
+				payload: options.statePayload
+			},
+			event: options.event,
+			context: options.context,
+			emit: options.emit,
+			clock: options.clock
+		}));
+		if (attempt[0] !== void 0) {
+			options.onError(attempt[0], options.lastGood);
+			break;
+		}
+		const out = attempt[1];
+		if (out instanceof Promise) pending.push(out.catch((error) => {
+			if (options.abort.signal.aborted) return;
+			options.onError(error, options.lastGood);
+		}));
+	}
+	return { pending };
 }
 //#endregion
 //#region src/dispatch.ts
@@ -350,13 +360,13 @@ var ActorBuilder = class {
 	#effects = {};
 	on(stateRef, eventRef, fn) {
 		const sName = stateRef.name;
-		const eId = eventRef.id;
-		(this.#transitions[sName] ??= {})[eId] = fn;
+		const eType = eventRef.type;
+		(this.#transitions[sName] ??= {})[eType] = fn;
 		return this;
 	}
 	onAny(eventRef, fn) {
-		const eId = eventRef.id;
-		(this.#transitions["Any"] ??= {})[eId] = fn;
+		const eType = eventRef.type;
+		(this.#transitions["Any"] ??= {})[eType] = fn;
 		return this;
 	}
 	effect(stateRef, fn) {
@@ -372,19 +382,16 @@ var ActorBuilder = class {
 };
 //#endregion
 //#region src/actor.ts
-function pickState(initial) {
-	return initial instanceof StateRef ? initial : initial.state;
-}
 function resolveInitial(initial) {
-	return pickState(initial);
+	return initial instanceof StateRef ? initial : initial.state;
 }
 var Actor = class {
 	state;
 	clock;
 	#context;
 	#contextHandle;
+	#contextWritten = false;
 	#lastState;
-	#lastContext;
 	#options;
 	#regions = {};
 	#children = /* @__PURE__ */ new Map();
@@ -412,7 +419,7 @@ var Actor = class {
 			setOutputHandler: (fn) => {
 				this.#outputHandler = fn;
 			},
-			pushInternal: (event) => this.#pushEvent(event),
+			pushInternal: (event) => this.#queue.push(event),
 			drainInternal: () => this.#drainInternal(),
 			abortEffects: () => this.#abortEffects()
 		});
@@ -424,8 +431,8 @@ var Actor = class {
 			transitions: built.transitions,
 			effects: built.effects
 		};
-		this.#internalIds = new Set((options.internal ?? []).map((e) => e.id));
-		this.#inputIds = new Set(options.inputs.map((e) => e.id));
+		this.#internalIds = new Set((options.internal ?? []).map((e) => e.type));
+		this.#inputIds = new Set(options.inputs.map((e) => e.type));
 		this.#internalBudget = options.internalBudget ?? 1e4;
 		this.clock = options.clock ?? new RealClock();
 		this.clock.setDrain?.(() => this.#drainInternal());
@@ -435,9 +442,9 @@ var Actor = class {
 		this.state = initState;
 		this.#context = options.context ?? {};
 		this.#lastState = initState;
-		this.#lastContext = this.#context;
 		this.#contextHandle = new Context(() => this.#context, (value) => {
 			this.#context = value;
+			this.#contextWritten = true;
 		});
 		this.#subs.seed(this.snapshot());
 		if (options.regions) for (const [key, child] of Object.entries(options.regions)) {
@@ -459,134 +466,191 @@ var Actor = class {
 		return this.#subs.addDone(cb);
 	}
 	settled() {
-		return this.#queue.settled();
+		return Promise.all([this.#queue.settled(), ...this.#pendingEffects]).then(() => void 0);
 	}
 	send(event) {
 		this.#dispatch(event);
 		this.#emitChangeIfDirty();
 	}
 	#emitChangeIfDirty() {
-		if (this.state === this.#lastState && this.#context === this.#lastContext) return;
+		if (this.state === this.#lastState && !this.#contextWritten) return;
 		this.#lastState = this.state;
-		this.#lastContext = this.#context;
+		this.#contextWritten = false;
 		this.#subs.emitChange(this.snapshot());
 	}
 	#dispatch(event) {
-		if (this.state.isFinal) return;
-		const transitions = this.#options.transitions;
-		const stateTransition = transitions[this.state.name]?.[event.id];
-		const anyTransition = transitions["Any"]?.[event.id];
-		const transitionApplied = stateTransition ? this.#applyStateStep(event, stateTransition) : false;
-		if ((anyTransition ? this.#applyAnyStep(event, anyTransition, !transitionApplied) : false) || this.#queue.length > 0) this.#drainInternal();
-		else if (!stateTransition && !anyTransition) console.warn(`[Actor] no transition for event "${event.id}" in state "${this.state.name}". Event dropped.`);
+		if (this.#error !== null || this.state.isFinal) return;
+		const prev = this.#entry;
+		this.#entry = {
+			state: this.state,
+			context: this.#context
+		};
+		try {
+			const transitions = this.#options.transitions;
+			const stateTransition = transitions[this.state.name]?.[event.type];
+			const anyTransition = transitions["Any"]?.[event.type];
+			const transitionApplied = stateTransition ? this.#applyStateStep(event, stateTransition) : false;
+			if ((this.#error === null ? this.#applyAnyStep(event, anyTransition, !transitionApplied) : false) || this.#queue.length > 0) this.#drainInternal();
+			else if (!stateTransition && !anyTransition) console.warn(`[Actor] no transition for event "${event.type}" in state "${this.state.name}". Event dropped.`);
+		} finally {
+			this.#entry = prev;
+		}
 	}
 	#applyStateStep(event, transition) {
-		const step = transition(event, {
-			context: this.#contextHandle,
-			actor: this
+		let applied = false;
+		this.#safe("transition", event, () => {
+			const step = transition(event, {
+				context: this.#contextHandle,
+				actor: this
+			});
+			if (step.emit) this.#queue.push(...step.emit);
+			if (step.state) {
+				this.#applyTransition(event, step);
+				applied = true;
+			}
 		});
-		if (step.emit) this.#queue.push(...step.emit);
-		if (step.state) {
-			this.#applyTransition(event, step);
-			return true;
-		}
-		return false;
+		return applied;
 	}
 	#applyAnyStep(event, transition, allowTransition) {
-		const step = transition(event, {
-			context: this.#contextHandle,
-			actor: this
+		if (transition === void 0) return false;
+		let emitted = false;
+		this.#safe("transition", event, () => {
+			const step = transition(event, {
+				context: this.#contextHandle,
+				actor: this
+			});
+			if (step.state && allowTransition) this.#applyTransition(event, step);
+			if (step.emit) {
+				this.#queue.push(...step.emit);
+				emitted = true;
+			}
 		});
-		if (step.state && allowTransition) this.#applyTransition(event, step);
-		if (step.emit) {
-			this.#queue.push(...step.emit);
-			return true;
-		}
-		return false;
+		return emitted;
 	}
 	snapshot() {
-		return buildSnapshot(this.state, this.#regions, this.#context);
-	}
-	#pushEvent(event) {
-		this.#queue.push(event);
+		return buildSnapshot(this.state, this.#regions, this.#context, this.#error ?? void 0);
 	}
 	#abortEffects() {
 		this.#effectAbort?.abort();
 		this.#subs.clear();
 	}
 	#applyTransition(event, step) {
-		if (!step.state) return;
-		this.#effectAbort?.abort();
+		if (this.#error !== null || !step.state) return;
 		const resolved = parseTarget(step);
 		if (!resolved) return;
+		if (!(resolved.state instanceof StateRef)) {
+			this.#enterError("transition", event, /* @__PURE__ */ new Error("invalid transition target"));
+			return;
+		}
+		this.#effectAbort?.abort();
 		this.state = resolved.state;
 		this.#runEffects(event, resolved.payload);
 		if (this.state.isFinal) this.#subs.emitDone();
 	}
 	#runEffects(event, statePayload) {
 		const list = this.#options.effects[this.state.name];
-		if (!list || list.length === 0) {
+		if (!list) {
 			this.#effectAbort = null;
 			return;
 		}
-		const abort = runEffects({
+		const abort = new AbortController();
+		this.#effectAbort = abort;
+		const lastGood = this.#entry ?? {
+			state: this.state,
+			context: this.#context
+		};
+		const result = runEffects({
 			effects: { [this.state.name]: list },
 			state: this.state,
 			statePayload,
 			event,
 			context: this.#contextHandle,
 			emit: (e) => {
+				if (this.#error !== null) return;
 				this.#queue.push(e);
 				this.#drainInternal();
 			},
-			clock: this.clock
+			clock: this.clock,
+			abort,
+			lastGood,
+			onError: (error) => this.#enterError("effect", event, error, lastGood)
 		});
-		this.#effectAbort = abort;
+		this.#pendingEffects.push(...result.pending);
 	}
 	#drainInternal() {
 		if (this.#draining) return;
 		this.#draining = true;
-		let budgetExceeded = false;
 		try {
 			const budget = this.#internalBudget;
 			let count = 0;
 			this.#queue.processCancellable((event) => {
+				if (this.#error !== null) return false;
 				if (count >= budget) {
-					budgetExceeded = true;
-					this.#abortEffects();
+					this.#enterError("budget", event, /* @__PURE__ */ new Error("internal event budget exceeded"));
 					return false;
 				}
 				count++;
-				if (this.#internalIds.has(event.id)) this.#dispatch(event);
-				else if (this.#inputIds.has(event.id)) this.#dispatch(event);
-				else if (this.#outputHandler) this.#outputHandler(event);
+				if (this.#internalIds.has(event.type) || this.#inputIds.has(event.type)) this.#dispatch(event);
+				else {
+					const outputHandler = this.#outputHandler;
+					if (outputHandler) {
+						if (!this.#safe("output", event, () => outputHandler(event))) return false;
+					}
+				}
 				return true;
 			});
 		} finally {
 			this.#draining = false;
 			this.#emitChangeIfDirty();
 		}
-		if (budgetExceeded) console.warn(`[Actor] internal event budget (${this.#internalBudget}) exceeded — possible emit loop. Actor halting.`);
+	}
+	#errorState = new StateRef("__error", false);
+	#error = null;
+	#entry = null;
+	#pendingEffects = [];
+	#safe(reason, event, fn) {
+		const attempt = Either.from(fn);
+		if (attempt[0] === void 0) return true;
+		this.#enterError(reason, event, attempt[0]);
+		return false;
+	}
+	#enterError(reason, event, error, lastGood) {
+		if (this.#error !== null) return;
+		const entry = lastGood ?? this.#entry ?? {
+			state: this.state,
+			context: this.#context
+		};
+		this.#error = {
+			error,
+			state: entry.state,
+			context: entry.context,
+			event,
+			reason
+		};
+		this.#effectAbort?.abort();
+		this.state = this.#errorState;
+		this.#lastState = this.#errorState;
+		this.#contextWritten = false;
+		this.#subs.emitChange(this.snapshot());
 	}
 };
 //#endregion
 //#region src/event.ts
-function event(id) {
-	return () => new EventRef(id);
+function event(type) {
+	return () => new EventRef(type);
 }
 var EventRef = class {
-	id;
-	constructor(id) {
-		this.id = id;
+	type;
+	constructor(type) {
+		this.type = type;
 	}
 	is(anyEvent) {
-		return !!anyEvent && typeof anyEvent === "object" && "id" in anyEvent && anyEvent.id === this.id;
+		return !!anyEvent && typeof anyEvent === "object" && "type" in anyEvent && anyEvent.type === this.type;
 	}
 	create(payload) {
-		if (payload === void 0) return { id: this.id };
-		return {
-			...payload,
-			id: this.id
+		return payload === void 0 ? { type: this.type } : {
+			type: this.type,
+			payload
 		};
 	}
 };

package/dist/internal.d.mts

@@ -1,4 +1,4 @@
-import { s as InternalEvent, t as AnyActor } from "./actor-internal-CBU_EDPZ.mjs";
+import { h as InternalEvent, t as AnyActor } from "./actor-internal-DYAL1iYK.mjs";
 import { Either } from "@mantaq/utils";
 //#region src/internal-registry.d.ts
 interface ActorInternal {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantaq/core",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "State machine runtime with actor model, event system, state hierarchy, effects, and virtual clock.",
   "license": "MIT",
   "repository": {
@@ -21,7 +21,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@mantaq/utils": "0.0.1"
+    "@mantaq/utils": "0.0.2"
   },
   "devDependencies": {
     "@stryker-mutator/core": "^9",