@mantaq/core 0.5.0 → 0.5.2

package/README.md

@@ -12,7 +12,7 @@ npm install @mantaq/core
 
 | Pattern         | Correct                                            | Anti-pattern                          |
 | --------------- | -------------------------------------------------- | ------------------------------------- |
-| Type context    | `context: {} as MyContext`                         | casting in every handler              |
+| Type context    | `const c: MyContext = {...}`, `context: c`         | `as` cast on the context value        |
 | Write context   | `const s = context.get(); s.x = y; context.set(s)` | mutate without `set()`                |
 | Type events     | `event("ID")<Payload>()`                           | `event("ID")()` without generic       |
 | Send events     | `actor.send(signInEvent.create(data))`             | raw `{ type: "ID", payload }` objects |
@@ -81,7 +81,7 @@ See [anderscan.github.io/mantaq](https://anderscan.github.io/mantaq) for full do
 
 ### Typed Actor Context
 
-Cast the context type once at the constructor level. Handlers receive the typed context automatically. No casting needed per-handler.
+Declare the context value with its type once, then pass it to the constructor. Handlers receive the typed context automatically. `as` on the context is an anti-pattern: it hides missing fields.
 
 ```ts
 interface AuthContext {
@@ -89,11 +89,13 @@ interface AuthContext {
   phoneNumber?: string;
 }
 
+const initialContext: AuthContext = {};
+
 const actor = new Actor({
   inputs: [signInEvent],
   states: [idleState, signingInState],
   initial: idleState,
-  context: {} as AuthContext,
+  context: initialContext,
   setup: (m) => {
     m.on(idleState, signInEvent, (event, opts) => {
       // ✅ typed — context.get()/set() flow the constructor type
@@ -299,12 +301,13 @@ const doneEvent = event("WORK_DONE")();
 const failedEvent = event("WORK_FAILED")<{ error: string }>();
 
 function createActor() {
+  const initialContext: MyContext = { retryCount: 0, maxRetries: 3 };
   return new Actor({
     inputs: [startEvent],
     internal: [doneEvent, failedEvent],
     states: [idleState, workingState, doneState, errorState],
     initial: idleState,
-    context: { retryCount: 0, maxRetries: 3 } as MyContext,
+    context: initialContext,
     setup: (m) => {
       m.effect(workingState, {
         name: "attemptWork",
@@ -533,6 +536,41 @@ m.on(idleState, submitEvent, (event, opts) => {
 });
 ```
 
+### Reading state in a UI
+
+`actor.state.name` is the typed state name: a union of your declared states plus `"__error"`. Read it, not `snapshot().path[0]`, which is an untyped `string`.
+
+```ts
+const render = () => show(actor.state.name);
+actor.on("change", { fn: render });
+render();
+```
+
+Two different failures need two different responses:
+
+- **Dead machine.** `actor.state.name === "__error"` (details in `snapshot().error`). A handler threw and the actor is terminal. Create a new actor and offer Reload.
+- **Failed state the machine models.** An `error` state reached through a failure event is an ordinary state. Render it like any other state.
+
+`recover()` is not for UIs: it breaks determinism. Recreate the actor instead.
+
+To bind any actor without naming `Actor`'s five generics, type the binder on the parts it uses:
+
+```ts
+import type { Snapshot } from "@mantaq/core";
+
+function bind<
+  A extends {
+    state: { name: string };
+    on(event: "change", options: { fn: () => void }): () => void;
+    snapshot(): Snapshot<unknown>;
+  },
+>(actor: A, render: (name: A["state"]["name"]) => void): () => void {
+  const paint = () => render(actor.state.name);
+  paint();
+  return actor.on("change", { fn: paint });
+}
+```
+
 ### Any Handler
 
 Use `onAny` to intercept events across all states. Useful for universal error handling, cleanup, or logging.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantaq/core",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "State machine runtime with actor model, event system, state hierarchy, effects, and virtual clock.",
   "license": "MIT",
   "repository": {