@typeonce/effect-machine 0.31.2 → 0.33.0

package/docs/agent-guide.md

@@ -22,12 +22,12 @@ const CounterState = Schema.TaggedUnion({
   Running: { count: Schema.Number }
 })
 
-export const CounterStates = Machine.states({
+export const CounterStates = Machine.state({ initial: "Idle", states: {
   Idle: {},
   Running: CounterState.cases.Running
-})
+} })
 
-export const CounterEvents = Machine.events(
+export const CounterEvents = Machine.eventsFromSchemas(
   Schema.TaggedUnion({
     Start: {},
     Increment: {},
@@ -37,27 +37,27 @@ export const CounterEvents = Machine.events(
 
 export const CounterMachine = Machine.make({
   id: "Counter",
-  states: CounterStates.states,
+  root: CounterStates,
   events: CounterEvents,
-  initial: (to) => to.Idle()
-}).handle({
+  initialConfiguration: root => root.resolve(({ target }) => target.from(to => to.Idle.from()))
+}).handle({ states: {
   Idle: {
     on: {
-      Start: (to) => to.full.Running().resolve(({ target }) => target.from({ count: 0 }))
+      Start: (to) => to.branch.Running().resolve(({ target }) => target.from({ count: 0 }))
     }
   },
   Running: {
     on: {
-      Increment: (to) => to.full.Running().resolve(({ state, target }) => target.from({ count: state.count + 1 })),
-      Stop: (to) => to.full.Idle()
+      Increment: (to) => to.branch.Running().resolve(({ state, target }) => target.from({ count: state.count + 1 })),
+      Stop: (to) => to.branch.Idle()
     }
   }
-})
+} })
 ```
 
 Each step has one job:
 
-- `Machine.states` declares the state tree and the data owned by each state.
+- `Machine.state` declares the root, its child topology, and state-owned data.
 - `Machine.events` declares the public messages the machine accepts and returns
   typed event constructors.
 - `Machine.make` joins the state tree, event protocol, input, and initial state.
@@ -106,12 +106,12 @@ const RequestState = Schema.TaggedUnion({
   Failed: { message: Schema.String }
 })
 
-const RequestStates = Machine.states({
+const RequestStates = Machine.state({ initial: "Idle", states: {
   Idle: {},
   Loading: {},
   Ready: RequestState.cases.Ready,
   Failed: RequestState.cases.Failed
-})
+} })
 ```
 
 The machine can now be `Loading`, `Ready`, or `Failed`. It cannot construct a
@@ -139,7 +139,7 @@ const DocumentState = Schema.TaggedUnion({
   }
 })
 
-const DocumentStates = Machine.states({
+const DocumentStates = Machine.state({ initial: "Closed", states: {
   Closed: {},
   Open: {
     // Editing, Saving, and SaveFailed all need the document and draft.
@@ -152,7 +152,7 @@ const DocumentStates = Machine.states({
       SaveFailed: DocumentState.cases.SaveFailed
     }
   }
-})
+} })
 ```
 
 Do not copy `documentId` and `draft` into every child. Copies can disagree after
@@ -165,22 +165,22 @@ Hierarchy owns behavior as well as data. Define a transition on the lowest
 compound state whose children share it.
 
 ```ts
-const DocumentEvents = Machine.events(
+const DocumentEvents = Machine.eventsFromSchemas(
   Schema.TaggedUnion({
     Close: {}
   })
 )
 
 const DocumentMachine = Machine.make({
-  states: DocumentStates.states,
+  root: DocumentStates,
   events: DocumentEvents,
   initial: (to) => to.Closed()
-}).handle({
+}).handle({ states: {
   Closed: {},
   Open: {
     on: {
       // All Open children close the document in the same way.
-      Close: (to) => to.full.Closed()
+      Close: (to) => to.branch.Closed()
     },
     states: {
       Editing: {},
@@ -188,7 +188,7 @@ const DocumentMachine = Machine.make({
       SaveFailed: {}
     }
   }
-})
+} })
 ```
 
 The machine checks the deepest active state first, then its ancestors. Put a
@@ -202,7 +202,7 @@ after domain actions and outcomes. Do not expose state setters such as
 `SetLoading` or `SetError`.
 
 ```ts
-export const CheckoutEvents = Machine.events(
+export const CheckoutEvents = Machine.eventsFromSchemas(
   Schema.TaggedUnion({
     Submit: {},
     Cancel: {}
@@ -210,23 +210,23 @@ export const CheckoutEvents = Machine.events(
 )
 
 const CheckoutMachine = Machine.make({
-  states: CheckoutStates.states,
+  root: CheckoutStates,
   events: CheckoutEvents,
   initial: (to) => to.Editing()
-}).handle({
+}).handle({ states: {
   Editing: {
     on: {
-      Submit: (to) => to.full.Submitting()
+      Submit: (to) => to.branch.Submitting()
     }
   },
   Submitting: {
     on: {
       // Cancel has meaning while work is in progress.
-      Cancel: (to) => to.full.Editing()
+      Cancel: (to) => to.branch.Editing()
     }
   },
   Complete: {}
-})
+} })
 ```
 
 The sender requests `Submit`. The machine decides whether `Submit` has a
@@ -243,7 +243,7 @@ child in every region. A parallel model therefore accepts the full product of
 those regions.
 
 ```ts
-const ScreenStates = Machine.states({
+const ScreenStates = Machine.state({ initial: "Screen", states: {
   Screen: {
     type: "parallel",
     states: {
@@ -263,7 +263,7 @@ const ScreenStates = Machine.states({
       }
     }
   }
-})
+} })
 ```
 
 This model permits all four combinations: online with a closed panel, online
@@ -286,29 +286,29 @@ const LoadState = Schema.TaggedUnion({
   Failed: { message: Schema.String }
 })
 
-const LoadStates = Machine.states({
+const LoadStates = Machine.state({ initial: "Idle", states: {
   Idle: {},
   Loading: LoadState.cases.Loading,
   Ready: LoadState.cases.Ready,
   Failed: LoadState.cases.Failed
-})
+} })
 
 const LoadMachine = Machine.make({
-  states: LoadStates.states,
-  events: Machine.events(),
-  initial: (to) => to.Idle()
-}).handle({
+  root: LoadStates,
+  events: Machine.eventsFromSchemas(),
+  initialConfiguration: root => root.resolve(({ target }) => target.from(to => to.Idle.from()))
+}).handle({ states: {
   Idle: {},
   Loading: {
     invoke: (from) =>
       from
         .effect("load-document", ({ state }) => loadDocument(state.documentId))
-        .onDone((to) => to.full.Ready().resolve(({ output, target }) => target.from({ content: output })))
-        .onFailure((to) => to.full.Failed().resolve(({ error, target }) => target.from({ message: String(error) })))
+        .onDone((to) => to.branch.Ready().resolve(({ output, target }) => target.from({ content: output })))
+        .onFailure((to) => to.branch.Failed().resolve(({ error, target }) => target.from({ message: String(error) })))
   },
   Ready: {},
   Failed: {}
-})
+} })
 ```
 
 `loadDocument` may require Effect services. Those requirements remain on the
@@ -356,8 +356,8 @@ Commissioning: {
         { discard: true }
       )
     )
-    .onDone((to) => to.full.Running())
-    .onFailure((to) => to.full.Failed())
+    .onDone((to) => to.branch.Running())
+    .onFailure((to) => to.branch.Failed())
 }
 ```
 
@@ -374,24 +374,24 @@ A transition should choose the next state from the current snapshot and event.
 Use ordinary TypeScript conditions when one event has several valid outcomes.
 
 ```ts
-const ReviewEvents = Machine.events(
+const ReviewEvents = Machine.eventsFromSchemas(
   Schema.TaggedUnion({
     Evaluate: { score: Schema.Number }
   })
 )
 
 const ReviewMachine = Machine.make({
-  states: ReviewStates.states,
+  root: ReviewStates,
   events: ReviewEvents,
   initial: (to) => to.Pending()
-}).handle({
+}).handle({ states: {
   Pending: {
     on: {
       Evaluate: (to) =>
         to
           .branches({
-            accepted: { target: to.full.Accepted() },
-            rejected: { target: to.full.Rejected() }
+            accepted: { target: to.branch.Accepted() },
+            rejected: { target: to.branch.Rejected() }
           })
           .resolve(({ event, select }) =>
             event.score >= 80
@@ -402,7 +402,7 @@ const ReviewMachine = Machine.make({
   },
   Accepted: {},
   Rejected: {}
-})
+} })
 ```
 
 Given the same snapshot and event, the handler should choose the same result.

package/docs/effect-atom-react.md

@@ -39,85 +39,61 @@ Service-free machines can use `AtomMachine.make` directly.
 
 ## Own a machine in one React subtree
 
-Use `useMachineAtom` when a provider, route, dialog, or other React subtree
-owns one machine instance:
+Create a context from a factory. Each Provider owns a fresh bridge in its current
+Atom registry; it does not subscribe to state changes.
 
 ```tsx
-import { useMachineAtom } from "@typeonce/effect-machine-react"
-import { createContext, type ReactNode, useContext } from "react"
-import { AuthMachine, type AuthMachineInput } from "../machines/auth-machine"
+import { createMachineContext } from "@typeonce/effect-machine-react"
+import { AuthMachine } from "../machines/auth-machine"
 import { MachineAtoms } from "../lib/atom-runtime"
 
-const makeAuthMachine = MachineAtoms.factory(AuthMachine)
-type AuthMachineAtom = ReturnType<typeof makeAuthMachine>
-
-const AuthMachineContext = createContext<AuthMachineAtom | null>(null)
-
-export function AuthMachineProvider({
-  children,
-  input
-}: {
-  readonly children: ReactNode
-  readonly input: AuthMachineInput
-}) {
-  const machine = useMachineAtom(() => makeAuthMachine(input))
+export const Auth = createMachineContext(MachineAtoms.factory(AuthMachine))
+export const useAuthMachine = Auth.useMachine
 
+function AuthRoute({ input, attemptId }: Props) {
   return (
-    <AuthMachineContext.Provider value={machine}>
-      {children}
-    </AuthMachineContext.Provider>
+    <Auth.Provider key={attemptId} input={input}>
+      <Suspense fallback={<Loading />}>
+        <AuthCard />
+      </Suspense>
+    </Auth.Provider>
   )
 }
-
-export function useAuthMachine(): AuthMachineAtom {
-  const machine = useContext(AuthMachineContext)
-  if (machine === null) {
-    throw new Error("useAuthMachine must be used inside AuthMachineProvider")
-  }
-  return machine
-}
 ```
 
-The provider strongly owns the complete `MachineAtom`. The hook mounts
-`machine.ref` after React commits the owner, but it does not read `state`,
-`snapshot`, or `result`. Machine updates therefore do not rerender the
-provider.
+Input is startup-only. Send events to update the existing workflow; change the
+Provider's React key to create a new one. Keep the Provider above Suspense so
+suspension does not discard the owner. Supply an Atom RegistryProvider at the
+application boundary. The same factory used by two Providers creates isolated
+machines, even when their inputs are equal.
 
-The factory captures startup input once. A later `input` prop change does not
-replace the running workflow. Send an event when the change belongs to that
-workflow. Change the provider's React key when React should own a new machine:
-
-```tsx
-<AuthMachineProvider key={attemptId} input={input}>
-  <AuthCard />
-</AuthMachineProvider>
-```
-
-Put the owner above a Suspense boundary. React can then retain the same machine
-while a state-reading descendant suspends.
+`useMachineAtom(() => makeMachine(input))` remains available for custom owners.
+It mounts the reference after commit without reading `result` or `snapshot`.
 
 ## Render state-owned data
 
-Subscribe in the smallest component that renders a state path:
+Render a typed path in the smallest component that needs it:
 
 ```tsx
-import { useAtomSuspense } from "@effect/atom-react"
-import { AtomMachine } from "@typeonce/effect-machine/reactivity"
-import { Option } from "effect"
+import { MachineState } from "@typeonce/effect-machine-react"
 
 function EditingFields() {
   const machine = useAuthMachine()
-  const editing = useAtomSuspense(
-    AtomMachine.selectSnapshot(machine, "Editing")
-  ).value
-
-  return Option.match(editing, {
-    onNone: () => null,
-    onSome: ({ value }) => <EmailField email={value.email} />
-  })
+  return (
+    <MachineState machine={machine} path="Editing" inactive={null}>
+      {({ value }) => <EmailField email={value.email} />}
+    </MachineState>
+  )
 }
 ```
 
+`MachineState` subscribes only its renderer. The path determines the callback's
+snapshot type. Startup suspends, failures reach the nearest error boundary,
+and an inactive path renders `inactive` (null by default).
+
+For custom hooks, `useAtomSuspense(AtomMachine.selectSnapshot(machine, path)).value`
+returns an Option of the selected snapshot.
+
 `AtomMachine.select` returns the selected state value.
 `AtomMachine.selectSnapshot` also retains the selected state's child topology.
 Both return `Option.none()` while the path is inactive. Do not replace that
@@ -240,11 +216,7 @@ function AuthScreen() {
   const machine = useAuthMachine()
   const state = useAtomSuspense(machine.result).value
 
-  return AuthStates.match(state, {
-    Editing: (editing) => <EditingScreen state={editing} />,
-    Verification: (verification) => <VerificationScreen state={verification} />,
-    Failed: (failed) => <FailureScreen state={failed} />
-  })
+  return <MachineSummary snapshot={state} />
 }
 ```
 
@@ -320,7 +292,7 @@ export const plantAtoms = AtomMachine.familyChild(CentralMachineAtom, {
   child: (plantId: string) => Plant(plantId),
   atoms: {
     broken: AtomMachine.matchesChild("Broken"),
-    state: (plant) => plant.state,
+    state: (plant) => plant.result,
     send: (plant) => plant.send
   }
 })

package/docs/machine-review.md

@@ -39,12 +39,12 @@ job is returning `target.from()`.
 // Redundant
 const handlers = {
   Start: (to) =>
-    to.full.Running().resolve(({ target }) => target.from())
+    to.branch.Running().resolve(({ target }) => target.from())
 }
 
 // Preferred
 const handlers = {
-  Start: (to) => to.full.Running()
+  Start: (to) => to.branch.Running()
 }
 ```
 
@@ -176,11 +176,11 @@ Model `Submit` as the component-facing event. Let a machine state own the work
 and its lifetime:
 
 ```ts
-machine.handle({
+machine.handle({ states: {
   Editing: {
     on: {
       Submit: (to) =>
-        to.full.Submitting().resolve(({ event, target }) =>
+        to.branch.Submitting().resolve(({ event, target }) =>
           target.from({ order: event.order })
         )
     }
@@ -190,17 +190,17 @@ machine.handle({
       from
         .effect("submit-order", ({ state }) => submitOrder(state.order))
         .onDone((to) =>
-          to.full.Complete().resolve(({ output, target }) =>
+          to.branch.Complete().resolve(({ output, target }) =>
             target.from({ order: output })
           )
         )
         .onFailure((to) =>
-          to.full.Failed().resolve(({ error, target }) =>
+          to.branch.Failed().resolve(({ error, target }) =>
             target.from({ message: String(error) })
           )
         )
   }
-})
+} })
 ```
 
 `submitOrder` can use Effect services for the API request and analytics. The