@typeonce/effect-machine 0.27.1 → 0.29.0

package/docs/effect-atom-react.md

@@ -1,230 +1,293 @@
-# Effect Atom and React patterns
+# Effect Atom and React
 
-This guide records the folder organization and three integration patterns
-validated in the process app. Use the API reference for individual AtomMachine
-operations. Read the [Effect Machine agent guide](./agent-guide.md) for
-statechart modeling, transitions, services, and testing.
+React code should own one stable machine atom, pass it through props or
+Context, and subscribe in the descendants that render machine state. Keep the
+machine definition free of React dependencies.
+
+Read the [Effect Machine agent guide](./agent-guide.md) for statechart
+modeling, transitions, services, and testing.
 
 ## Recommended folder structure
 
 ```text
 src/
-├── context/                 # Optional React Context adapters
-│   ├── dialog-context.tsx
-│   └── process-context.tsx
+├── context/
+│   └── auth-machine-context.tsx  # React ownership and distribution
 ├── lib/
-│   ├── atom-runtime.ts      # Shared bound AtomMachine runtime
-│   └── services/            # Generic Effect business services
-│       └── query-processor.ts
+│   ├── atom-runtime.ts           # Shared bound AtomMachine runtime
+│   └── services/
 └── machines/
-    ├── counter/
-    │   ├── machine.ts       # Machine implementation
-    │   └── atom.ts          # Focused atoms for React
-    ├── process/
-    │   ├── machine.ts
-    │   └── atom.ts
-    └── dialog/
-        ├── machine.ts
-        └── atom.ts
+    └── auth-machine.ts           # States, events, and behavior
 ```
 
-Keep these responsibilities separate:
+`machine.ts` owns the workflow. A Context module only creates and distributes
+the machine atom. State-slot components decide which state paths they render.
 
-- `machine.ts` defines states, events, transitions, statechart behavior, and
-  Effect service requirements. It has no React dependency.
-- `atom.ts` adapts that machine to the shared bound AtomMachine runtime and
-  exports the focused atoms React needs.
-- `lib/services/` contains reusable business services used by machines.
-- `context/` is optional. It only distributes an already-created machine scope
-  through a React subtree.
-- `lib/atom-runtime.ts` binds AtomMachine once to the application's Effect
-  service layer:
+Bind service-backed machines once at the application runtime:
 
 ```ts
 import { AtomMachine } from "@typeonce/effect-machine/reactivity"
 import { Atom } from "effect/unstable/reactivity"
-import { QueryProcessor } from "./services/query-processor"
+import { AppLayer } from "./app-layer"
 
-const atomRuntime = Atom.runtime(QueryProcessor.layer)
+const atomRuntime = Atom.runtime(AppLayer)
 
-export const machineAtoms = AtomMachine.bind(atomRuntime)
+export const MachineAtoms = AtomMachine.bind(atomRuntime)
 ```
 
-Each `machineAtoms.make` call still creates an independent machine bridge.
+Service-free machines can use `AtomMachine.make` directly.
 
-## 1. One global actor with no input
+## Own a machine in one React subtree
 
-Use a module-level bridge when a no-input machine intentionally has one
-application-wide instance:
+Use `useMachineAtom` when a provider, route, dialog, or other React subtree
+owns one machine instance:
 
-```ts
-import { machineAtoms } from "@/lib/atom-runtime"
-import { AtomMachine } from "@typeonce/effect-machine/reactivity"
-import { counterMachine } from "./machine"
+```tsx
+import { useMachineAtom } from "@typeonce/effect-machine-react"
+import { createContext, type ReactNode, useContext } from "react"
+import { AuthMachine, type AuthMachineInput } from "../machines/auth-machine"
+import { MachineAtoms } from "../lib/atom-runtime"
 
-export const counterMachineAtom = machineAtoms.make(counterMachine)
+const makeAuthMachine = (input: AuthMachineInput) => MachineAtoms.make(AuthMachine, input)
+type AuthMachineAtom = ReturnType<typeof makeAuthMachine>
 
-export const counterStateAtom = AtomMachine.select(
-  counterMachineAtom,
-  "counter"
-)
-```
+const AuthMachineContext = createContext<AuthMachineAtom | null>(null)
 
-"Global" means every import reaches this bridge under the same atom registry.
-Consumers read `counterStateAtom` and use `counterMachineAtom.send` directly.
-Do not add a redundant `counterSendAtom` alias.
+export function AuthMachineProvider({
+  children,
+  input
+}: {
+  readonly children: ReactNode
+  readonly input: AuthMachineInput
+}) {
+  const machine = useMachineAtom(() => makeAuthMachine(input))
 
-## 2. A machine with startup input selected through a family
+  return (
+    <AuthMachineContext.Provider value={machine}>
+      {children}
+    </AuthMachineContext.Provider>
+  )
+}
 
-Use the family key as machine identity. The same value can also be startup
-input:
+export function useAuthMachine(): AuthMachineAtom {
+  const machine = useContext(AuthMachineContext)
+  if (machine === null) {
+    throw new Error("useAuthMachine must be used inside AuthMachineProvider")
+  }
+  return machine
+}
+```
 
-```ts
-import { machineAtoms } from "@/lib/atom-runtime"
-import { AtomMachine } from "@typeonce/effect-machine/reactivity"
-import { Atom } from "effect/unstable/reactivity"
-import { processMachine } from "./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.
 
-export const processFamily = Atom.family((query: string) => {
-  const machine = machineAtoms.make(processMachine, { query })
+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:
 
-  return {
-    detailsAtom: AtomMachine.select(machine, "process"),
-    resultAtom: AtomMachine.select(machine, "process.Ready"),
-    sendAtom: machine.send
-  }
-})
+```tsx
+<AuthMachineProvider key={attemptId} input={input}>
+  <AuthCard />
+</AuthMachineProvider>
 ```
 
-A consumer calls `processFamily(query)` and uses the returned focused atoms. If
-several nested components need the same scope, an optional Context can expose
-`ReturnType<typeof processFamily>`. The provider resolves the query once instead
-of drilling it through every component.
-
-Changing `query` selects another family member and therefore another machine.
-If a changing value should update the current workflow, model it as an event.
+Put the owner above a Suspense boundary. React can then retain the same machine
+while a state-reading descendant suspends.
 
-## 3. Reusing one machine definition for multiple instances
+## Render state-owned data
 
-Define the dialog adapter once:
+Subscribe in the smallest component that renders a state path:
 
-```ts
-import { machineAtoms } from "@/lib/atom-runtime"
+```tsx
+import { useAtomSuspense } from "@effect/atom-react"
 import { AtomMachine } from "@typeonce/effect-machine/reactivity"
-import { dialogMachine } from "./machine"
+import { Option } from "effect"
+
+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} />
+  })
+}
+```
 
-export function makeDialogScope() {
-  const machine = machineAtoms.make(dialogMachine)
+`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
+absence with an empty string, `null`, or a global boolean.
 
-  return {
-    isOpenAtom: AtomMachine.matches(machine, "Open"),
-    isClosedAtom: AtomMachine.matches(machine, "Closed"),
-    openStateAtom: AtomMachine.select(machine, "Open"),
-    sendAtom: machine.send
-  }
+Repeated calls with the same machine and path return the same atom, so path
+selection is safe during render without `useMemo`. Equal selected values do not
+notify the component.
+
+Nested paths keep the same ownership:
+
+```tsx
+function PasswordField() {
+  const machine = useAuthMachine()
+  const password = useAtomSuspense(
+    AtomMachine.select(machine, "Editing.Password")
+  ).value
+
+  return Option.match(password, {
+    onNone: () => null,
+    onSome: ({ password }) => <input type="password" value={password} />
+  })
 }
+```
+
+Place independent subscriptions in independent descendants:
 
-export type DialogScope = ReturnType<typeof makeDialogScope>
+```tsx
+function AuthCard() {
+  return (
+    <>
+      <EditingFields />
+      <VerificationFields />
+      <FailureMessage />
+      <SubmitButton />
+    </>
+  )
+}
 ```
 
-Choose one of the following ownership forms.
+Atom granularity cannot isolate hooks that all live in `AuthCard`. Any selected
+change rerenders the component that called the hook.
 
-### React-tree-owned instance
+## Send without subscribing
+
+Use the writable atom directly:
 
 ```tsx
-const DialogContext = createContext<DialogScope | null>(null)
+import { useAtomSet } from "@effect/atom-react"
 
-export function DialogProvider({ children }: { children: ReactNode }) {
-  const [scope] = useState(makeDialogScope)
+function SubmitButton() {
+  const machine = useAuthMachine()
+  const send = useAtomSet(machine.send)
 
   return (
-    <DialogContext.Provider value={scope}>
-      {children}
-    </DialogContext.Provider>
+    <button onClick={() => send({ _tag: "Submitted" })}>
+      Continue
+    </button>
   )
 }
 ```
 
-Each provider owns one independent dialog. Descendants use a small
-`useDialog()` hook and subscribe to the focused atom they need. Pass
-`DialogScope` through props when Context is unnecessary. Do not add a wrapper
-component whose only job is forwarding the scope.
+`useAtomSet` mounts the writable atom and does not subscribe the component to
+its value.
 
-### Stable keyed instances shared across scattered components
+## Whole-result and custom selections
 
-Use one private family to create the scope for an ID. Public selector families
-reach that same scope:
+Reading the full result is correct when a component renders the complete
+machine state:
 
-```ts
-import { Atom } from "effect/unstable/reactivity"
+```tsx
+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} />
+  })
+}
+```
 
-const dialogScopeFamily = Atom.family((dialogId: string) => {
-  const scope = makeDialogScope()
-
-  return {
-    isOpenAtom: scope.isOpenAtom.pipe(
-      Atom.withLabel(`dialog:${dialogId}:isOpen-source`)
-    ),
-    openStateAtom: scope.openStateAtom.pipe(
-      Atom.withLabel(`dialog:${dialogId}:openState-source`)
-    ),
-    sendAtom: scope.sendAtom.pipe(
-      Atom.withLabel(`dialog:${dialogId}:send-source`)
-    )
-  }
-})
+That component rerenders for every result change. Current
+`@effect/atom-react` does not select from the successful value in
+`useAtomSuspense`. Until it does, use typed path selectors for state-owned UI,
+or declare a custom derived atom once in a strongly owned scope. Do not create
+a fresh derived atom on every render.
+
+## Share a keyed machine outside one React owner
 
-export const dialogIsOpenFamily = Atom.family((dialogId: string) => {
-  const scope = dialogScopeFamily(dialogId)
+`AtomMachine.family` is for registry-owned machines that unrelated consumers
+find by startup input. It is not the default for one React-owned workflow.
 
-  return Atom.transform(
-    scope.sendAtom,
-    (get) => get(scope.isOpenAtom)
-  ).pipe(Atom.withLabel(`dialog:${dialogId}:isOpen`))
+```ts
+export const processAtoms = MachineAtoms.family(ProcessMachine, {
+  atoms: {
+    details: AtomMachine.select("Processing"),
+    ready: AtomMachine.matches("Ready"),
+    send: (machine) => machine.send
+  }
 })
+```
 
-export const dialogOpenStateFamily = Atom.family((dialogId: string) => {
-  const scope = dialogScopeFamily(dialogId)
+Consumers use the input as the shared identity key:
 
-  return Atom.transform(
-    scope.sendAtom,
-    (get) => get(scope.openStateAtom)
-  ).pipe(Atom.withLabel(`dialog:${dialogId}:openState`))
-})
+```tsx
+const details = useAtomSuspense(processAtoms.details(input)).value
+const send = useAtomSet(processAtoms.send(input))
 ```
 
-Components using the same `dialogId` share one machine. Different IDs create
-independent machines. The two public projections let consumers subscribe
-independently. Both remain writable through `Atom.transform`, so either can send
-the inferred dialog events.
+Each public projection retains its private machine owner. Keeping only
+`details(input)` or `send(input)` is safe. Do not return a weakly held composite
+scope and retain only one field from it.
 
-Use `dialogId` in atom labels for diagnostics. Do not pass it into
-`dialogMachine` as unused fake input.
+Family keys use Effect `Equal` and `Hash` semantics. Keep them immutable. If a
+changing value should update one running workflow, model it as an event instead
+of changing the family key.
 
-## 4. Selecting process-owned child machines
+## Module-owned machines
 
-Bind a machine definition once when a parent owns a runtime-sized set of child
-machines:
+A no-input machine may intentionally have one module-owned identity:
 
 ```ts
-const Plant = Machine.childFamily(plantMachine)
+export const CounterMachineAtom = MachineAtoms.make(CounterMachine)
+export const CounterStateAtom = AtomMachine.select(CounterMachineAtom, "Count")
+```
+
+Every consumer using the same `AtomRegistry` reaches the same running machine.
+Different registries still run independent instances.
+
+## Child machines
 
-export const centralMachineAtom = machineAtoms.make(centralMachine)
+Direct child selectors follow the active child and preserve inactivity:
 
-export const plantScopeFamily = Atom.family((plantId: string) => {
-  const plant = centralMachineAtom.child(Plant(plantId))
+```tsx
+const editor = machine.child(Editor)
+const editing = useAtomSuspense(
+  AtomMachine.selectSnapshotChild(editor, "Editing")
+).value
+```
+
+An inactive child or path returns `Option.none()`. Re-entry follows the
+replacement child instance.
+
+Use `AtomMachine.familyChild` when a parent owns a runtime-sized set of keyed
+children:
 
-  return {
-    stateAtom: plant.state,
-    isBrokenAtom: AtomMachine.matchesChild(plant, "Broken"),
-    sendAtom: plant.send,
-    stopAtom: plant.stop
+```ts
+const Plant = Machine.childFamily(PlantMachine)
+
+export const plantAtoms = AtomMachine.familyChild(CentralMachineAtom, {
+  child: (plantId: string) => Plant(plantId),
+  atoms: {
+    broken: AtomMachine.matchesChild("Broken"),
+    state: (plant) => plant.state,
+    send: (plant) => plant.send
   }
 })
 ```
 
-`Plant(plantId)` may be reconstructed wherever the id is available. Child
-lookup and bridge reuse match by machine identity and id, not descriptor object
-identity. Before the parent spawns that child, selectors contain `Option.none`
-and `matchesChild` is `false`. They follow the child after startup and return to
-the inactive values after it stops.
+## Registry and rendering semantics
+
+A `MachineAtom` identifies one machine per `AtomRegistry`. Passing the same
+machine atom through two registry providers creates two independent runtimes.
+Unmounting a React owner releases its mount. The registry stops the machine
+after its final subscription and configured idle retention expire.
+`registry.dispose()` stops it immediately.
+
+`useMachineAtom` does not start a machine during server rendering because
+React effects do not run on the server. Reading a machine atom during server
+render follows `@effect/atom-react` server-read behavior, so choose an explicit
+client boundary when server startup would be undesirable.

package/docs/machine-review.md

@@ -65,27 +65,29 @@ const handlers = {
 Review check: search for `.resolve(...)` callbacks that only return an empty
 `target.from()` and remove the callback.
 
-## Let `Atom.family` own keyed identity
+## Choose React ownership or keyed family lookup
 
-Treat `useMemo` around an atom family lookup as a warning sign. `Atom.family`
-already returns the same retained object for the same key, including when
-separate components perform the lookup.
+Use `useMachineAtom` when one React subtree owns the workflow, including a
+machine with startup input:
 
 ```tsx
-// Redundant and local to one component
-const scope = useMemo(() => processFamily(processId), [processId])
-
-// The family owns identity
-const scope = processFamily(processId)
+const machine = useMachineAtom(() => machineAtoms.make(processMachine, input))
 ```
 
-If the component constructs the atoms or machine scope directly, move that
-construction into a module-level family:
+Pass the stable machine through props or Context. Startup input is captured
+once. Send an event to change the running workflow, or change the owner's React
+key to replace it.
 
-```ts
-export const processFamily = Atom.family((processId: string) => {
-  const machine = machineAtoms.make(processMachine, { processId })
+Use `AtomMachine.family` when unrelated consumers must find one shared machine
+by its startup input. Effect Atom keeps a family value for an equal key while
+that returned value is reachable. Current runtimes may hold family values
+through `WeakRef`. Retaining one field from a composite family value does not
+retain the composite itself:
 
+```ts
+// Unsafe when consumers retain only stateAtom or sendAtom
+const processScope = Atom.family((input: ProcessInput) => {
+  const machine = machineAtoms.make(processMachine, input)
   return {
     stateAtom: AtomMachine.select(machine, "process"),
     sendAtom: machine.send
@@ -93,17 +95,33 @@ export const processFamily = Atom.family((processId: string) => {
 })
 ```
 
-Use a stable domain key. A new key means a different machine instance. Send an
-event when a value should update the current workflow instead.
+`AtomMachine.family` returns direct atom families whose atoms retain the
+private machine bridge:
+
+```ts
+export const processAtoms = machineAtoms.family(processMachine, {
+  atoms: {
+    state: AtomMachine.select("process"),
+    send: (machine) => machine.send
+  }
+})
+
+const stateAtom = processAtoms.state(input)
+const sendAtom = processAtoms.send(input)
+```
+
+No component `useMemo` is needed. The registry retains the public atom while a
+hook subscribes to it, and that atom retains the machine owner. Equal inputs
+use Effect `Equal` and `Hash` semantics and select the same family value.
 
-`useMemo` may still be useful for unrelated expensive calculations. It should
-not establish atom or machine identity. For one instance owned only by a React
-subtree, use a lazy `useState(makeScope)` initializer as described in the React
-guide.
+For a no-input machine, use one module-level bridge or `useMachineAtom` in the
+owning React subtree. Do not add an unused family key.
 
-Review check: search for `useMemo` around atom creation, family lookup, or
-`machineAtoms.make`. Replace component-local identity with `Atom.family`, or
-with an intentional component-owned scope.
+Review check: search for composite `Atom.family` values that own a machine,
+`useMemo` around family lookup, repeated input propagation through one React
+subtree, and component-local calls to `machineAtoms.make` without a stable
+owner. Choose `AtomMachine.family` only when consumers need shared keyed
+lookup.
 
 ## Justify each `RegistryProvider`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeonce/effect-machine",
-  "version": "0.27.1",
+  "version": "0.29.0",
   "description": "Schema-first state machines and statecharts for Effect",
   "author": "Sandro Maglione",
   "repository": {