@typeonce/effect-machine 0.28.0 → 0.30.0

package/dist/unstable/reactivity/AtomMachine.js

@@ -52,8 +52,8 @@ const SelectorProjectionTypeId = "~effect/reactivity/AtomMachine/SelectorProject
  * Selects the typed value for an active state path.
  *
  * Valid paths and their selected value types are inferred from the bridge.
- * The derived atom suppresses structurally equal updates. Keep the returned
- * atom stable when constructing it inside a component.
+ * The derived atom suppresses structurally equal updates. Repeated calls with
+ * the same bridge and path return the same atom.
  *
  * **Example**
  *
@@ -87,8 +87,8 @@ export const select = dual(2, internal.select);
  * Selects the typed logical snapshot for an active state path.
  *
  * Unlike {@link select}, the selected value retains its child snapshot
- * topology. The derived atom suppresses structurally equal updates. Keep the
- * returned atom stable when constructing it inside a component.
+ * topology. The derived atom suppresses structurally equal updates. Repeated
+ * calls with the same bridge and path return the same atom.
  *
  * @category combinators
  * @since 0.7.0
@@ -98,8 +98,8 @@ export const selectSnapshot = dual(2, internal.selectSnapshot);
  * Selects the typed value for an active state path in a directly owned child.
  *
  * Valid paths and their selected value types are inferred from the child
- * bridge. An inactive child produces `Option.none()`. Keep the returned atom
- * stable when constructing it inside a component.
+ * bridge. An inactive child produces `Option.none()`. Repeated calls with the
+ * same child bridge and path return the same atom.
  *
  * **Example**
  *
@@ -118,7 +118,8 @@ export const selectChild = dual(2, internal.selectChild);
  *
  * An inactive child or state path produces `Option.none()`. Unlike
  * {@link selectChild}, the selected value retains its child snapshot topology.
- * The derived atom suppresses structurally equal updates.
+ * The derived atom suppresses structurally equal updates. Repeated calls with
+ * the same child bridge and path return the same atom.
  *
  * @category combinators
  * @since 0.7.0
@@ -128,8 +129,9 @@ export const selectSnapshotChild = dual(2, internal.selectSnapshotChild);
  * Returns whether a state path is active.
  *
  * Valid paths are inferred from the bridge snapshot.
- * The derived atom suppresses equal updates. Runtime failures remain in the
- * typed failure channel.
+ * The derived atom suppresses equal updates. Repeated calls with the same
+ * bridge and path return the same atom. Runtime failures remain in the typed
+ * failure channel.
  *
  * **Example**
  *
@@ -161,8 +163,8 @@ export const matches = dual(2, internal.matches);
  * Returns whether a state path is active in a directly owned child.
  *
  * Valid paths are inferred from the child bridge snapshot.
- * An inactive child produces `false`. Keep the returned atom stable when
- * constructing it inside a component.
+ * An inactive child produces `false`. Repeated calls with the same child
+ * bridge and path return the same atom.
  *
  * @category combinators
  * @since 0.4.0
@@ -255,6 +257,26 @@ export const familyChild = internal.familyChild;
  * @since 0.4.0
  */
 export const make = internal.make;
+/**
+ * Specializes a machine definition into a reusable bridge constructor.
+ *
+ * The returned function preserves the machine's startup input arity and exact
+ * bridge type. Every call creates a fresh `MachineAtom`; it does not cache by
+ * input or start the machine before an `AtomRegistry` reads or mounts it.
+ *
+ * **Example**
+ *
+ * ```ts
+ * const makeSearchMachine = AtomMachine.factory(searchMachine)
+ * const search = makeSearchMachine({ query: "effect" })
+ *
+ * type SearchMachineAtom = ReturnType<typeof makeSearchMachine>
+ * ```
+ *
+ * @category constructors
+ * @since 0.30.0
+ */
+export const factory = internal.factory;
 /**
  * Creates a lazy atom bridge from a decoded logical snapshot.
  *
@@ -267,11 +289,12 @@ export const make = internal.make;
  */
 export const resume = internal.resume;
 /**
- * Creates an `AtomMachine` factory that owns a shared Effect runtime.
+ * Binds `AtomMachine` constructors to a shared Effect runtime.
  *
  * Use this when an application runs many machines from the same service layer.
- * The returned factory keeps runtime provisioning at the composition boundary,
- * while every call to `make` still creates an independent machine bridge.
+ * The returned interface keeps runtime provisioning at the composition seam,
+ * while every call to `make` or a specialized `factory` still creates an
+ * independent machine bridge.
  *
  * @category constructors
  * @since 0.4.0

package/dist/unstable/reactivity/AtomMachine.js.map

@@ -1 +1 @@
-{"version":3,"file":"AtomMachine.js","sourceRoot":"","sources":["../../../src/unstable/reactivity/AtomMachine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAMtC,OAAO,KAAK,QAAQ,MAAM,gCAAgC,CAAA;AAK1D;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AAE9D;;;;;GAKG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAMpE,MAAM,0BAA0B,GAAG,qDAAqD,CAAA;AAoIxF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,SAAS,GAE+C,QAAQ,CAAC,SAAS,CAAA;AAEvF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAE+D,QAAQ,CAAC,UAAU,CAAA;AAEzG;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAMvB,QAAQ,CAAC,cAAc,CAAA;AAwJ3B,MAAM,yBAAyB,GAAG,oDAAoD,CAAA;AACtF,MAAM,wBAAwB,GAAG,mDAAmD,CAAA;AA0BpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,MAAM,MAAM,GA0Cf,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;AAE5B;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GA0CvB,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAA;AAEpC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,WAAW,GAsCpB,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAA;AAEjC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAoC5B,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,MAAM,OAAO,GAsChB,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;AAE7B;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GA2BrB,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAA;AAElC,MAAM,uBAAuB,GAAG,kDAAkD,CAAA;AAkJlF,MAAM,yBAAyB,GAAG,oDAAoD,CAAA;AAyFtF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,MAAM,GAkBgE,QAAQ,CAAC,MAAa,CAAA;AAEzG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,WAAW,GAYqC,QAAQ,CAAC,WAAkB,CAAA;AAExF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,IAAI,GAqDb,QAAQ,CAAC,IAAI,CAAA;AAEjB;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,MAAM,GASf,QAAQ,CAAC,MAAM,CAAA;AAEnB;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,IAAI,GAEoB,QAAQ,CAAC,IAAI,CAAA"}
+{"version":3,"file":"AtomMachine.js","sourceRoot":"","sources":["../../../src/unstable/reactivity/AtomMachine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAMtC,OAAO,KAAK,QAAQ,MAAM,gCAAgC,CAAA;AAK1D;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AAE9D;;;;;GAKG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAMpE,MAAM,0BAA0B,GAAG,qDAAqD,CAAA;AAoIxF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,SAAS,GAE+C,QAAQ,CAAC,SAAS,CAAA;AAEvF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAE+D,QAAQ,CAAC,UAAU,CAAA;AAEzG;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAMvB,QAAQ,CAAC,cAAc,CAAA;AAwJ3B,MAAM,yBAAyB,GAAG,oDAAoD,CAAA;AACtF,MAAM,wBAAwB,GAAG,mDAAmD,CAAA;AA0BpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,MAAM,MAAM,GA0Cf,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;AAE5B;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GA0CvB,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAA;AAEpC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,WAAW,GAsCpB,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAA;AAEjC;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAoC5B,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,MAAM,OAAO,GAsChB,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;AAE7B;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GA2BrB,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAA;AAElC,MAAM,uBAAuB,GAAG,kDAAkD,CAAA;AAkJlF,MAAM,yBAAyB,GAAG,oDAAoD,CAAA;AAyGtF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,MAAM,GAkBgE,QAAQ,CAAC,MAAa,CAAA;AAEzG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,WAAW,GAYqC,QAAQ,CAAC,WAAkB,CAAA;AAExF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,IAAI,GAqDb,QAAQ,CAAC,IAAI,CAAA;AAEjB;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,OAAO,GAM+C,QAAQ,CAAC,OAAO,CAAA;AAEnF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,MAAM,GASf,QAAQ,CAAC,MAAM,CAAA;AAEnB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,IAAI,GAEoB,QAAQ,CAAC,IAAI,CAAA"}

package/docs/effect-atom-react.md

@@ -1,208 +1,343 @@
-# Effect Atom and React patterns
+# Effect Atom and React
 
-This guide records the folder organization and four 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"
+
+const makeAuthMachine = MachineAtoms.factory(AuthMachine)
+type AuthMachineAtom = ReturnType<typeof makeAuthMachine>
+
+const AuthMachineContext = createContext<AuthMachineAtom | null>(null)
 
-export const counterMachineAtom = machineAtoms.make(counterMachine)
+export function AuthMachineProvider({
+  children,
+  input
+}: {
+  readonly children: ReactNode
+  readonly input: AuthMachineInput
+}) {
+  const machine = useMachineAtom(() => makeAuthMachine(input))
+
+  return (
+    <AuthMachineContext.Provider value={machine}>
+      {children}
+    </AuthMachineContext.Provider>
+  )
+}
 
-export const counterStateAtom = AtomMachine.select(
-  counterMachineAtom,
-  "counter"
-)
+export function useAuthMachine(): AuthMachineAtom {
+  const machine = useContext(AuthMachineContext)
+  if (machine === null) {
+    throw new Error("useAuthMachine must be used inside AuthMachineProvider")
+  }
+  return machine
+}
 ```
 
-"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.
+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.
 
-## 2. A keyed machine with startup input
+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:
 
-`AtomMachine.family` uses the machine input as both startup input and family
-key. It returns one direct atom family for each entry in `atoms`:
+```tsx
+<AuthMachineProvider key={attemptId} input={input}>
+  <AuthCard />
+</AuthMachineProvider>
+```
 
-```ts
-import { machineAtoms } from "@/lib/atom-runtime"
+Put the owner above a Suspense boundary. React can then retain the same machine
+while a state-reading descendant suspends.
+
+## Render state-owned data
+
+Subscribe in the smallest component that renders a state path:
+
+```tsx
+import { useAtomSuspense } from "@effect/atom-react"
 import { AtomMachine } from "@typeonce/effect-machine/reactivity"
-import { processMachine } 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 const processAtoms = machineAtoms.family(processMachine, {
-  atoms: {
-    details: AtomMachine.select("process"),
-    result: AtomMachine.select("process.Ready"),
-    send: (machine) => machine.send
-  },
-  label: (input, name) => `process:${input.query}:${name}`
-})
+`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.
+
+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} />
+  })
+}
 ```
 
-React consumes each projected family directly:
+Place independent subscriptions in independent descendants:
 
 ```tsx
-const input = { query }
-const details = useAtomValue(processAtoms.details(input))
-const send = useAtomSet(processAtoms.send(input))
+function AuthCard() {
+  return (
+    <>
+      <EditingFields />
+      <VerificationFields />
+      <FailureMessage />
+      <SubmitButton />
+    </>
+  )
+}
 ```
 
-Each public atom retains its private machine bridge. Keeping only `details` or
-only `send` is safe. The bridge still starts lazily in the registry and stops
-when that registry releases or disposes it. A writable source remains writable,
-and a projection keeps the source atom's equality function.
+Atom granularity cannot isolate hooks that all live in `AuthCard`. Any selected
+change rerenders the component that called the hook.
+
+## Send without subscribing
+
+Use the writable atom directly:
+
+```tsx
+import { useAtomSet } from "@effect/atom-react"
 
-The family uses Effect `Equal` and `Hash` semantics. Equal records such as
-`{ query: "effect" }` select the same family value even when reconstructed.
-Keep inputs immutable because mutating a hashed key makes later lookup
-unreliable. Different input values select independent machines. If a changing
-value should update one running workflow, model the change as an event instead
-of putting it in the machine input.
+function SubmitButton() {
+  const machine = useAuthMachine()
+  const send = useAtomSet(machine.send)
 
-Service-free machines use the module function directly:
+  return (
+    <button onClick={() => send({ _tag: "Submitted" })}>
+      Continue
+    </button>
+  )
+}
+```
+
+`useAtomSet` mounts the writable atom and does not subscribe the component to
+its value.
+
+## Query concrete event acceptance
+
+`Machine.can` composes with `machine.snapshot` through a derived atom. Declare
+the projection once for a module-level machine, or create it once alongside a
+React-owned machine:
+
+```tsx
+import { Effect, Equal } from "effect"
+import { Atom } from "effect/unstable/reactivity"
+import { Machine } from "@typeonce/effect-machine"
+import { useAtomSet, useAtomSuspense } from "@effect/atom-react"
+import { useState } from "react"
+
+const makeCanSubmitAtom = (machine: AuthMachineAtom) =>
+  Atom.make((get) =>
+    get.result(machine.snapshot).pipe(
+      Effect.flatMap((snapshot) => {
+        if (snapshot.status === "active") {
+          return Machine.can(AuthMachine, snapshot.state, { _tag: "Submitted" })
+        }
+        if (snapshot.status === "error") {
+          return Effect.failCause(snapshot.cause)
+        }
+        return Effect.succeed(false)
+      })
+    )
+  ).pipe(Atom.withEquality(Equal.equals))
+
+function SubmitButton() {
+  const machine = useAuthMachine()
+  const [canSubmitAtom] = useState(() => makeCanSubmitAtom(machine))
+  const canSubmit = useAtomSuspense(canSubmitAtom).value
+  const send = useAtomSet(machine.send)
+
+  return (
+    <button
+      disabled={!canSubmit}
+      onClick={() => send({ _tag: "Submitted" })}
+    >
+      Continue
+    </button>
+  )
+}
+```
+
+Startup still suspends, startup and runtime failures reach the error boundary,
+and invalid event input remains a `MachineSchemaDecodeError`. Done and stopped
+machines return `false`. When the event payload itself changes reactively, read
+it from another atom inside the same derived atom.
+
+## Whole-result and custom selections
+
+Reading the full result is correct when a component renders the complete
+machine state:
+
+```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} />
+  })
+}
+```
+
+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
+
+`AtomMachine.family` is for registry-owned machines that unrelated consumers
+find by startup input. It is not the default for one React-owned workflow.
 
 ```ts
-export const processAtoms = AtomMachine.family(processMachine, {
+export const processAtoms = MachineAtoms.family(ProcessMachine, {
   atoms: {
-    details: AtomMachine.select("process"),
+    details: AtomMachine.select("Processing"),
+    ready: AtomMachine.matches("Ready"),
     send: (machine) => machine.send
   }
 })
 ```
 
-## 3. Reusing one machine definition for multiple instances
+Consumers use the input as the shared identity key:
 
-Define the dialog adapter once:
+```tsx
+const details = useAtomSuspense(processAtoms.details(input)).value
+const send = useAtomSet(processAtoms.send(input))
+```
 
-```ts
-import { machineAtoms } from "@/lib/atom-runtime"
-import { AtomMachine } from "@typeonce/effect-machine/reactivity"
-import { dialogMachine } from "./machine"
+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.
 
-export function makeDialogScope() {
-  const machine = machineAtoms.make(dialogMachine)
+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.
 
-  return {
-    isOpenAtom: AtomMachine.matches(machine, "Open"),
-    isClosedAtom: AtomMachine.matches(machine, "Closed"),
-    openStateAtom: AtomMachine.select(machine, "Open"),
-    sendAtom: machine.send
-  }
-}
+## Module-owned machines
+
+A no-input machine may intentionally have one module-owned identity:
 
-export type DialogScope = ReturnType<typeof makeDialogScope>
+```ts
+export const CounterMachineAtom = MachineAtoms.make(CounterMachine)
+export const CounterStateAtom = AtomMachine.select(CounterMachineAtom, "Count")
 ```
 
-### React-tree-owned instance
+Every consumer using the same `AtomRegistry` reaches the same running machine.
+Different registries still run independent instances.
 
-```tsx
-const DialogContext = createContext<DialogScope | null>(null)
+## Child machines
 
-export function DialogProvider({ children }: { children: ReactNode }) {
-  const [scope] = useState(makeDialogScope)
+Direct child selectors follow the active child and preserve inactivity:
 
-  return (
-    <DialogContext.Provider value={scope}>
-      {children}
-    </DialogContext.Provider>
-  )
-}
+```tsx
+const editor = machine.child(Editor)
+const editing = useAtomSuspense(
+  AtomMachine.selectSnapshotChild(editor, "Editing")
+).value
 ```
 
-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.
+An inactive child or path returns `Option.none()`. Re-entry follows the
+replacement child instance.
 
-For a no-input machine, use one module-level bridge or an explicitly owned
-React scope. Do not add a family key that the machine does not consume. When an
-ID is part of startup semantics, declare it in the machine input and use
-`AtomMachine.family`.
-
-## 4. Selecting process-owned child machines
-
-Bind a machine definition once when a parent owns a runtime-sized set of child
-machines:
+Use `AtomMachine.familyChild` when a parent owns a runtime-sized set of keyed
+children:
 
 ```ts
-const Plant = Machine.childFamily(plantMachine)
-
-export const centralMachineAtom = machineAtoms.make(centralMachine)
+const Plant = Machine.childFamily(PlantMachine)
 
-export const plantAtoms = AtomMachine.familyChild(centralMachineAtom, {
+export const plantAtoms = AtomMachine.familyChild(CentralMachineAtom, {
   child: (plantId: string) => Plant(plantId),
   atoms: {
+    broken: AtomMachine.matchesChild("Broken"),
     state: (plant) => plant.state,
-    isBroken: AtomMachine.matchesChild("Broken"),
-    send: (plant) => plant.send,
-    stop: (plant) => plant.stop
+    send: (plant) => plant.send
   }
 })
-
-const broken = useAtomValue(plantAtoms.isBroken(plantId))
-const send = useAtomSet(plantAtoms.send(plantId))
 ```
 
-`familyChild` keeps child lookup separate from root machine startup. Each
-projected atom retains the child bridge returned for its key.
+## 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.
 
-`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.
+`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,11 +65,25 @@ const handlers = {
 Review check: search for `.resolve(...)` callbacks that only return an empty
 `target.from()` and remove the callback.
 
-## Use retained families for keyed machine input
+## Choose React ownership or keyed family lookup
 
-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:
+Use `useMachineAtom` when one React subtree owns the workflow, including a
+machine with startup input:
+
+```tsx
+const makeProcessMachine = machineAtoms.factory(processMachine)
+const machine = useMachineAtom(() => makeProcessMachine(input))
+```
+
+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.
+
+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
@@ -82,8 +96,8 @@ const processScope = Atom.family((input: ProcessInput) => {
 })
 ```
 
-Use `AtomMachine.family` for an input-bearing machine. It returns direct atom
-families whose atoms retain the private machine bridge:
+`AtomMachine.family` returns direct atom families whose atoms retain the
+private machine bridge:
 
 ```ts
 export const processAtoms = machineAtoms.family(processMachine, {
@@ -101,14 +115,14 @@ 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.
 
-For a no-input machine, use one module-level bridge or a lazy
-`useState(makeScope)` value owned by a React subtree. Do not add an unused key.
+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 composite `Atom.family` values that own a machine,
-`useMemo` around family lookup, and component-local calls to
-`machineAtoms.make`. Replace an input-bearing machine with
-`AtomMachine.family`. Give a no-input instance an explicit module or React-tree
-owner.
+`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`