@typeonce/effect-machine-react 0.31.1 → 0.32.0

package/README.md

@@ -1,26 +1,54 @@
 # @typeonce/effect-machine-react
 
-React ownership hooks for machine atoms created by
+React ownership and typed state rendering for
 [`@typeonce/effect-machine`](../effect-machine/README.md).
 
 ```tsx
-import { useMachineAtom } from "@typeonce/effect-machine-react"
+import { createMachineContext, MachineState } from "@typeonce/effect-machine-react"
+import { AtomMachine } from "@typeonce/effect-machine/reactivity"
+import { Suspense } from "react"
+import { AuthMachine } from "./auth-machine"
 
-function AuthProvider({ input, children }: Props) {
-  const machine = useMachineAtom(() => MachineAtoms.make(AuthMachine, input))
+const Auth = createMachineContext(AtomMachine.factory(AuthMachine))
 
+function AuthRoute({ input }: Props) {
   return (
-    <AuthContext.Provider value={machine}>
-      {children}
-    </AuthContext.Provider>
+    <Auth.Provider input={input}>
+      <Suspense fallback={<Loading />}>
+        <AuthForm />
+      </Suspense>
+    </Auth.Provider>
+  )
+}
+
+function AuthForm() {
+  const machine = Auth.useMachine()
+  return (
+    <MachineState machine={machine} path="Editing" inactive={null}>
+      {({ value }) => <EmailField email={value.email} />}
+    </MachineState>
   )
 }
 ```
 
-`useMachineAtom` strongly owns one machine atom, mounts it after commit, and
-does not subscribe the owner to machine state. Descendants subscribe to the
-specific state paths they render with `AtomMachine.select`,
-`AtomMachine.selectSnapshot`, or `AtomMachine.matches`.
+Each Provider creates an independent machine in the current Atom registry,
+including when two Providers receive equal inputs. Supply an Atom
+`RegistryProvider` at the application boundary. Bind Effect services through
+`AtomMachine.runtime(...)` before creating a factory when the machine needs them.
+
+The Provider owns the reference without subscribing to state changes.
+`MachineState` subscribes to its typed path and infers the callback snapshot.
+Inactive paths render `inactive` (null by default); startup suspends and failures
+propagate to the nearest error boundary. Keep the owner above Suspense.
+
+Input is startup-only. Send an event to update a running workflow, or change the
+Provider's React `key` to start a new one. Machines without input have a Provider
+without an `input` prop.
+
+`useMachineAtom(() => makeMachine(input))` remains available for custom owners.
+Use `AtomMachine.select`, `selectSnapshot`, and `matches` for custom granular
+subscriptions. Read `.result` for the whole logical snapshot or `.snapshot` for
+runtime status; the bridge has no separate `.state` projection.
 
-Machine input is startup-only. Send an event to update a running workflow, or
-change the provider's React `key` to replace it with a new machine.
+See the [React guide](../effect-machine/docs/effect-atom-react.md) for events,
+services, child machines, and registry-owned families.

package/dist/MachineAtom.d.ts

@@ -1,16 +1,58 @@
+import type { Machine } from "@typeonce/effect-machine";
 import type { AtomMachine } from "@typeonce/effect-machine/reactivity";
+import type * as React from "react";
 type AnyMachineAtom = AtomMachine.MachineAtom<any, never, any, any, any, any>;
 /**
- * Creates one machine atom for a committed React owner and mounts its machine
- * reference without subscribing the owner to machine state.
- *
- * The factory is startup-only. Later changes to values captured by the factory
- * do not replace the machine. Send an event to change a running workflow, or
- * change the owner's React `key` to create a new machine.
+ * Creates one bridge per React owner and mounts its reference without subscribing
+ * the owner to state changes. The factory is startup-only. Change the owner's
+ * React key to start a fresh machine. Keep this owner above any Suspense boundary
+ * that reads the machine.
  *
  * @category hooks
  * @since 0.29.0
  */
 export declare const useMachineAtom: <A extends AnyMachineAtom>(create: () => A) => A;
+/** Props for a typed render of one active state path.
+ * @category models
+ * @since 0.32.0
+ */
+export interface MachineStateProps<State extends Machine.Machine.AtomicSnapshot<string, unknown>, Event, Error, Output, StartError, Emitted, Path extends Machine.Snapshot.Path<State>> {
+    readonly machine: AtomMachine.MachineAtom<State, Event, Error, Output, StartError, Emitted>;
+    readonly path: Path;
+    readonly inactive?: React.ReactNode;
+    readonly children: (state: Machine.Snapshot.At<State, NoInfer<Path>>) => React.ReactNode;
+}
+/**
+ * Subscribes only this renderer to a state path. Startup suspends and failures
+ * propagate to the nearest error boundary. Inactive child states render
+ * `inactive`, which defaults to null.
+ *
+ * @category components
+ * @since 0.32.0
+ */
+export declare const MachineState: <State extends Machine.Machine.AtomicSnapshot<string, unknown>, Event, Error, Output, StartError, Emitted, const Path extends Machine.Snapshot.Path<State>>(props: MachineStateProps<State, Event, Error, Output, StartError, Emitted, Path>) => React.ReactNode;
+/** An isolated React owner and accessor for a bridge factory.
+ * @category models
+ * @since 0.32.0
+ */
+export interface MachineContext<Args extends [] | [unknown], A extends AnyMachineAtom> {
+    readonly Provider: React.ComponentType<{
+        readonly children?: React.ReactNode;
+    } & (Args extends [] ? {
+        readonly input?: never;
+    } : {
+        readonly input: Args[0];
+    })>;
+    readonly useMachine: () => A;
+}
+/**
+ * Creates a context from an AtomMachine factory. Each Provider owns a fresh
+ * bridge in its current registry. Input is read once at startup; use a new React
+ * key for a new owner. The Provider does not subscribe to machine state.
+ *
+ * @category constructors
+ * @since 0.32.0
+ */
+export declare const createMachineContext: <Args extends [] | [unknown], A extends AnyMachineAtom>(create: (...args: Args) => A) => MachineContext<Args, A>;
 export {};
 //# sourceMappingURL=MachineAtom.d.ts.map

package/dist/MachineAtom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MachineAtom.d.ts","sourceRoot":"","sources":["../src/MachineAtom.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAA;AAGtE,KAAK,cAAc,GAAG,WAAW,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AAE7E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,cAAc,EAAE,QAAQ,MAAM,CAAC,KAAG,CAI1E,CAAA"}
+{"version":3,"file":"MachineAtom.d.ts","sourceRoot":"","sources":["../src/MachineAtom.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAA;AACtE,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAA;AAGnC,KAAK,cAAc,GAAG,WAAW,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AAE7E;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,SAAS,cAAc,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAA2B,CAAA;AAEvG;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAChC,KAAK,SAAS,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,KAAK,EACL,KAAK,EACL,MAAM,EACN,UAAU,EACV,OAAO,EACP,IAAI,SAAS,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;IAEzC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,CAAA;IAC3F,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACnC,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,SAAS,CAAA;CACzF;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE,CACzB,KAAK,SAAS,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,KAAK,EACL,KAAK,EACL,MAAM,EACN,UAAU,EACV,OAAO,EACP,KAAK,CAAC,IAAI,SAAS,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAE/C,KAAK,EAAE,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,KAC7E,KAAK,CAAC,SAAiC,CAAA;AAE5C;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,IAAI,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,SAAS,cAAc;IACnF,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,aAAa,CAClC;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;KAAE,GACvC,CAAC,IAAI,SAAS,EAAE,GAAG;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG;QAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;KAAE,CAAC,CAC/E,CAAA;IACD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;CAC7B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,EAAE,CAAC,IAAI,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,SAAS,cAAc,EACvF,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,KACzB,cAAc,CAAC,IAAI,EAAE,CAAC,CAAiC,CAAA"}

package/dist/MachineAtom.js

@@ -1,25 +1,36 @@
 /**
- * React ownership for machine atoms.
+ * React ownership and state rendering for machine atoms.
  *
  * @since 0.29.0
  */
 "use client";
-import { useAtomMount } from "@effect/atom-react";
-import * as React from "react";
+import * as internal from "./internal/react.js";
 /**
- * Creates one machine atom for a committed React owner and mounts its machine
- * reference without subscribing the owner to machine state.
- *
- * The factory is startup-only. Later changes to values captured by the factory
- * do not replace the machine. Send an event to change a running workflow, or
- * change the owner's React `key` to create a new machine.
+ * Creates one bridge per React owner and mounts its reference without subscribing
+ * the owner to state changes. The factory is startup-only. Change the owner's
+ * React key to start a fresh machine. Keep this owner above any Suspense boundary
+ * that reads the machine.
  *
  * @category hooks
  * @since 0.29.0
  */
-export const useMachineAtom = (create) => {
-    const [machine] = React.useState(create);
-    useAtomMount(machine.ref);
-    return machine;
-};
+export const useMachineAtom = internal.useMachineAtom;
+/**
+ * Subscribes only this renderer to a state path. Startup suspends and failures
+ * propagate to the nearest error boundary. Inactive child states render
+ * `inactive`, which defaults to null.
+ *
+ * @category components
+ * @since 0.32.0
+ */
+export const MachineState = internal.MachineState;
+/**
+ * Creates a context from an AtomMachine factory. Each Provider owns a fresh
+ * bridge in its current registry. Input is read once at startup; use a new React
+ * key for a new owner. The Provider does not subscribe to machine state.
+ *
+ * @category constructors
+ * @since 0.32.0
+ */
+export const createMachineContext = internal.createMachineContext;
 //# sourceMappingURL=MachineAtom.js.map

package/dist/MachineAtom.js.map

@@ -1 +1 @@
-{"version":3,"file":"MachineAtom.js","sourceRoot":"","sources":["../src/MachineAtom.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,CAAA;AAEZ,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAI9B;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAA2B,MAAe,EAAK,EAAE;IAC7E,MAAM,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IACxC,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACzB,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA"}
+{"version":3,"file":"MachineAtom.js","sourceRoot":"","sources":["../src/MachineAtom.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,CAAA;AAKZ,OAAO,KAAK,QAAQ,MAAM,qBAAqB,CAAA;AAI/C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAqD,QAAQ,CAAC,cAAc,CAAA;AAqBvG;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAUF,QAAQ,CAAC,YAAY,CAAA;AAc5C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAEF,QAAQ,CAAC,oBAAoB,CAAA"}

package/dist/internal/react.d.ts

@@ -0,0 +1,10 @@
+import type { Machine } from "@typeonce/effect-machine";
+import { AtomMachine } from "@typeonce/effect-machine/reactivity";
+import * as React from "react";
+import type { MachineContext, MachineStateProps } from "../MachineAtom.js";
+type AnyMachineAtom = AtomMachine.MachineAtom<any, never, any, any, any, any>;
+export declare const useMachineAtom: <A extends AnyMachineAtom>(create: () => A) => A;
+export declare const MachineState: <State extends Machine.Machine.AtomicSnapshot<string, unknown>, Event, Error, Output, StartError, Emitted, const Path extends Machine.Snapshot.Path<State>>(props: MachineStateProps<State, Event, Error, Output, StartError, Emitted, Path>) => React.ReactNode;
+export declare const createMachineContext: <Args extends [] | [unknown], A extends AnyMachineAtom>(create: (...args: Args) => A) => MachineContext<Args, A>;
+export {};
+//# sourceMappingURL=react.d.ts.map

package/dist/internal/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../../src/internal/react.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAA;AAEjE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAE1E,KAAK,cAAc,GAAG,WAAW,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AAE7E,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,cAAc,EAAE,QAAQ,MAAM,CAAC,KAAG,CAI1E,CAAA;AAED,eAAO,MAAM,YAAY,GACvB,KAAK,SAAS,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,KAAK,EACL,KAAK,EACL,MAAM,EACN,UAAU,EACV,OAAO,EACP,KAAK,CAAC,IAAI,SAAS,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAE/C,OAAO,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,KAC/E,KAAK,CAAC,SAOR,CAAA;AAED,eAAO,MAAM,oBAAoB,GAAI,IAAI,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,SAAS,cAAc,EACxF,QAAQ,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,KAC3B,cAAc,CAAC,IAAI,EAAE,CAAC,CAaxB,CAAA"}

package/dist/internal/react.js

@@ -0,0 +1,33 @@
+import { useAtomMount, useAtomSuspense } from "@effect/atom-react";
+import { AtomMachine } from "@typeonce/effect-machine/reactivity";
+import { Option } from "effect";
+import * as React from "react";
+export const useMachineAtom = (create) => {
+    const [machine] = React.useState(create);
+    useAtomMount(machine.ref);
+    return machine;
+};
+export const MachineState = (props) => {
+    const selected = React.useMemo(() => AtomMachine.selectSnapshot(props.machine, props.path), [
+        props.machine,
+        props.path
+    ]);
+    const snapshot = useAtomSuspense(selected).value;
+    return Option.isSome(snapshot) ? props.children(snapshot.value) : props.inactive ?? null;
+};
+export const createMachineContext = (create) => {
+    const Context = React.createContext(undefined);
+    const Provider = (props) => {
+        // Input belongs to this committed owner. A new React key creates a new owner.
+        const machine = useMachineAtom(() => create(...("input" in props ? [props.input] : [])));
+        return React.createElement(Context.Provider, { value: machine }, props.children);
+    };
+    const useMachine = () => {
+        const machine = React.useContext(Context);
+        if (machine === undefined)
+            throw new Error("Machine context must be read inside its Provider");
+        return machine;
+    };
+    return Object.freeze({ Provider, useMachine });
+};
+//# sourceMappingURL=react.js.map

package/dist/internal/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../../src/internal/react.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAElE,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAA;AACjE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAK9B,MAAM,CAAC,MAAM,cAAc,GAAG,CAA2B,MAAe,EAAK,EAAE;IAC7E,MAAM,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IACxC,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACzB,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,CAS1B,KAAgF,EAC/D,EAAE;IACnB,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,cAAc,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE;QAC1F,KAAK,CAAC,OAAO;QACb,KAAK,CAAC,IAAI;KACX,CAAC,CAAA;IACF,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAA;IAChD,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAA;AAC1F,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,MAA4B,EACH,EAAE;IAC3B,MAAM,OAAO,GAAG,KAAK,CAAC,aAAa,CAAgB,SAAS,CAAC,CAAA;IAC7D,MAAM,QAAQ,GAAG,CAAC,KAAwE,EAAmB,EAAE;QAC7G,8EAA8E;QAC9E,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAS,CAAC,CAAC,CAAA;QAChG,OAAO,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAA;IAClF,CAAC,CAAA;IACD,MAAM,UAAU,GAAG,GAAM,EAAE;QACzB,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAA;QACzC,IAAI,OAAO,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAA;QAC9F,OAAO,OAAO,CAAA;IAChB,CAAC,CAAA;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,CAA4B,CAAA;AAC3E,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeonce/effect-machine-react",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "description": "React ownership hooks for Effect Machine atoms",
   "author": "Sandro Maglione",
   "repository": {
@@ -34,7 +34,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@typeonce/effect-machine": "^0.31.1"
+    "@typeonce/effect-machine": "^0.32.0"
   },
   "peerDependencies": {
     "@effect/atom-react": "4.0.0-rc.112",

package/src/MachineAtom.ts

@@ -1,29 +1,87 @@
 /**
- * React ownership for machine atoms.
+ * React ownership and state rendering for machine atoms.
  *
  * @since 0.29.0
  */
 "use client"
 
-import { useAtomMount } from "@effect/atom-react"
+import type { Machine } from "@typeonce/effect-machine"
 import type { AtomMachine } from "@typeonce/effect-machine/reactivity"
-import * as React from "react"
+import type * as React from "react"
+import * as internal from "./internal/react.js"
 
 type AnyMachineAtom = AtomMachine.MachineAtom<any, never, any, any, any, any>
 
 /**
- * Creates one machine atom for a committed React owner and mounts its machine
- * reference without subscribing the owner to machine state.
- *
- * The factory is startup-only. Later changes to values captured by the factory
- * do not replace the machine. Send an event to change a running workflow, or
- * change the owner's React `key` to create a new machine.
+ * Creates one bridge per React owner and mounts its reference without subscribing
+ * the owner to state changes. The factory is startup-only. Change the owner's
+ * React key to start a fresh machine. Keep this owner above any Suspense boundary
+ * that reads the machine.
  *
  * @category hooks
  * @since 0.29.0
  */
-export const useMachineAtom = <A extends AnyMachineAtom>(create: () => A): A => {
-  const [machine] = React.useState(create)
-  useAtomMount(machine.ref)
-  return machine
+export const useMachineAtom: <A extends AnyMachineAtom>(create: () => A) => A = internal.useMachineAtom
+
+/** Props for a typed render of one active state path.
+ * @category models
+ * @since 0.32.0
+ */
+export interface MachineStateProps<
+  State extends Machine.Machine.AtomicSnapshot<string, unknown>,
+  Event,
+  Error,
+  Output,
+  StartError,
+  Emitted,
+  Path extends Machine.Snapshot.Path<State>
+> {
+  readonly machine: AtomMachine.MachineAtom<State, Event, Error, Output, StartError, Emitted>
+  readonly path: Path
+  readonly inactive?: React.ReactNode
+  readonly children: (state: Machine.Snapshot.At<State, NoInfer<Path>>) => React.ReactNode
+}
+
+/**
+ * Subscribes only this renderer to a state path. Startup suspends and failures
+ * propagate to the nearest error boundary. Inactive child states render
+ * `inactive`, which defaults to null.
+ *
+ * @category components
+ * @since 0.32.0
+ */
+export const MachineState: <
+  State extends Machine.Machine.AtomicSnapshot<string, unknown>,
+  Event,
+  Error,
+  Output,
+  StartError,
+  Emitted,
+  const Path extends Machine.Snapshot.Path<State>
+>(
+  props: MachineStateProps<State, Event, Error, Output, StartError, Emitted, Path>
+) => React.ReactNode = internal.MachineState
+
+/** An isolated React owner and accessor for a bridge factory.
+ * @category models
+ * @since 0.32.0
+ */
+export interface MachineContext<Args extends [] | [unknown], A extends AnyMachineAtom> {
+  readonly Provider: React.ComponentType<
+    & { readonly children?: React.ReactNode }
+    & (Args extends [] ? { readonly input?: never } : { readonly input: Args[0] })
+  >
+  readonly useMachine: () => A
 }
+
+/**
+ * Creates a context from an AtomMachine factory. Each Provider owns a fresh
+ * bridge in its current registry. Input is read once at startup; use a new React
+ * key for a new owner. The Provider does not subscribe to machine state.
+ *
+ * @category constructors
+ * @since 0.32.0
+ */
+export const createMachineContext: <Args extends [] | [unknown], A extends AnyMachineAtom>(
+  create: (...args: Args) => A
+) => MachineContext<Args, A> = internal.createMachineContext

package/src/internal/react.ts

@@ -0,0 +1,50 @@
+import { useAtomMount, useAtomSuspense } from "@effect/atom-react"
+import type { Machine } from "@typeonce/effect-machine"
+import { AtomMachine } from "@typeonce/effect-machine/reactivity"
+import { Option } from "effect"
+import * as React from "react"
+import type { MachineContext, MachineStateProps } from "../MachineAtom.js"
+
+type AnyMachineAtom = AtomMachine.MachineAtom<any, never, any, any, any, any>
+
+export const useMachineAtom = <A extends AnyMachineAtom>(create: () => A): A => {
+  const [machine] = React.useState(create)
+  useAtomMount(machine.ref)
+  return machine
+}
+
+export const MachineState = <
+  State extends Machine.Machine.AtomicSnapshot<string, unknown>,
+  Event,
+  Error,
+  Output,
+  StartError,
+  Emitted,
+  const Path extends Machine.Snapshot.Path<State>
+>(
+  props: MachineStateProps<State, Event, Error, Output, StartError, Emitted, Path>
+): React.ReactNode => {
+  const selected = React.useMemo(() => AtomMachine.selectSnapshot(props.machine, props.path), [
+    props.machine,
+    props.path
+  ])
+  const snapshot = useAtomSuspense(selected).value
+  return Option.isSome(snapshot) ? props.children(snapshot.value) : props.inactive ?? null
+}
+
+export const createMachineContext = <Args extends [] | [unknown], A extends AnyMachineAtom>(
+  create: (...args: Args) => A
+): MachineContext<Args, A> => {
+  const Context = React.createContext<A | undefined>(undefined)
+  const Provider = (props: { readonly input?: unknown; readonly children?: React.ReactNode }): React.ReactNode => {
+    // Input belongs to this committed owner. A new React key creates a new owner.
+    const machine = useMachineAtom(() => create(...("input" in props ? [props.input] : []) as Args))
+    return React.createElement(Context.Provider, { value: machine }, props.children)
+  }
+  const useMachine = (): A => {
+    const machine = React.useContext(Context)
+    if (machine === undefined) throw new Error("Machine context must be read inside its Provider")
+    return machine
+  }
+  return Object.freeze({ Provider, useMachine }) as MachineContext<Args, A>
+}