@xstate/react 7.0.0-alpha.6 → 7.0.0-beta.0

package/README.md

@@ -10,7 +10,7 @@ This package contains utilities for using [XState](https://github.com/statelyai/
 1. Install `xstate` and `@xstate/react`:
 
 ```bash
-npm i xstate @xstate/react
+npm i xstate@beta @xstate/react@beta
 ```
 
 2. Import the `useMachine` hook:

package/dist/declarations/src/createActorContext.d.ts

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import { Actor, ActorOptions, AnyActorLogic, SnapshotFrom } from 'xstate';
+/** @public */
 export declare function createActorContext<TLogic extends AnyActorLogic>(actorLogic: TLogic, actorOptions?: ActorOptions<TLogic>): {
     useSelector: <T>(selector: (snapshot: SnapshotFrom<TLogic>) => T, compare?: (a: T, b: T) => boolean) => T;
     useActorRef: () => Actor<TLogic>;
@@ -7,5 +8,10 @@ export declare function createActorContext<TLogic extends AnyActorLogic>(actorLo
         children: React.ReactNode;
         options?: ActorOptions<TLogic>;
         logic?: TLogic;
+        /**
+         * An already-created actor (e.g. from `restoreActor`) to provide instead
+         * of creating one from `logic` and `options`. Create it once.
+         */
+        actor?: Actor<TLogic>;
     }) => React.ReactElement<any, any>;
 };

package/dist/declarations/src/shallowEqual.d.ts

@@ -1 +1,2 @@
+/** @public */
 export declare function shallowEqual(objA: any, objB: any): boolean;

package/dist/declarations/src/useActor.d.ts

@@ -1,4 +1,12 @@
 import { Actor, ActorOptions, AnyActorLogic, SnapshotFrom, type ConditionalRequired, type IsNotNever, type RequiredActorOptionsKeys, type RequiredActorOptionsFor } from 'xstate';
+/**
+ * Creates an actor from `logic` (or uses an already-created `actor`, e.g. from
+ * `restoreActor`) and subscribes to its snapshot. Create a passed actor once,
+ * e.g. `useState(() => restoreActor(machine, persisted))[0]`.
+ *
+ * @public
+ */
+export declare function useActor<TLogic extends AnyActorLogic>(actor: Actor<TLogic>): [SnapshotFrom<TLogic>, Actor<TLogic>['send'], Actor<TLogic>];
 export declare function useActor<TLogic extends AnyActorLogic>(logic: TLogic, ...[options]: ConditionalRequired<[
     options?: ActorOptions<TLogic> & RequiredActorOptionsFor<TLogic>
 ], IsNotNever<RequiredActorOptionsKeys<TLogic>>>): [SnapshotFrom<TLogic>, Actor<TLogic>['send'], Actor<TLogic>];

package/dist/declarations/src/useActorRef.d.ts

@@ -1,8 +1,21 @@
 import { Actor, ActorOptions, AnyActorLogic, Observer, SnapshotFrom, type ConditionalRequired, type IsNotNever, type RequiredActorOptionsKeys, type RequiredActorOptionsFor } from 'xstate';
-export declare function useIdleActorRef<TLogic extends AnyActorLogic>(logic: TLogic, ...[options]: ConditionalRequired<[
+/**
+ * An already-created actor (e.g. from `restoreActor`). Hooks use it as is
+ * instead of creating one from logic.
+ */
+export declare function isActor(value: unknown): value is Actor<AnyActorLogic>;
+export declare function useIdleActorRef<TLogic extends AnyActorLogic>(logicOrActor: TLogic | Actor<TLogic>, ...[options]: ConditionalRequired<[
     options?: ActorOptions<TLogic> & RequiredActorOptionsFor<TLogic>
 ], IsNotNever<RequiredActorOptionsKeys<TLogic>>>): [Actor<TLogic>, (actorRef: Actor<TLogic>) => void];
 export declare function useActorLifecycle<TLogic extends AnyActorLogic>(actorRef: Actor<TLogic>, setActorRef: (actorRef: Actor<TLogic>) => void, createReplacement: () => Actor<TLogic>): void;
+/**
+ * Creates an actor from `logic` (or uses an already-created `actor`, e.g. from
+ * `restoreActor`), starts it on mount and stops it on unmount. Create a passed
+ * actor once, e.g. `useState(() => restoreActor(machine, persisted))[0]`.
+ *
+ * @public
+ */
+export declare function useActorRef<TLogic extends AnyActorLogic>(actor: Actor<TLogic>, observerOrListener?: Observer<SnapshotFrom<TLogic>> | ((value: SnapshotFrom<TLogic>) => void)): Actor<TLogic>;
 export declare function useActorRef<TLogic extends AnyActorLogic>(machine: TLogic, ...[options, observerOrListener]: IsNotNever<RequiredActorOptionsKeys<TLogic>> extends true ? [
     options: ActorOptions<TLogic> & RequiredActorOptionsFor<TLogic>,
     observerOrListener?: Observer<SnapshotFrom<TLogic>> | ((value: SnapshotFrom<TLogic>) => void)

package/dist/declarations/src/useMachine.d.ts

@@ -1,5 +1,11 @@
 import { Actor, ActorOptions, AnyStateMachine, StateFrom, type ConditionalRequired, type IsNotNever, type RequiredActorOptionsKeys, type RequiredActorOptionsFor } from 'xstate';
-/** @alias useActor */
+/**
+ * @alias useActor
+ *
+ * @deprecated Use `useActor(machine, options)`.
+ * @public
+ */
+export declare function useMachine<TMachine extends AnyStateMachine>(actor: Actor<TMachine>): [StateFrom<TMachine>, Actor<TMachine>['send'], Actor<TMachine>];
 export declare function useMachine<TMachine extends AnyStateMachine>(machine: TMachine, ...[options]: ConditionalRequired<[
     options?: ActorOptions<TMachine> & RequiredActorOptionsFor<TMachine>
 ], IsNotNever<RequiredActorOptionsKeys<TMachine>>>): [StateFrom<TMachine>, Actor<TMachine>['send'], Actor<TMachine>];

package/dist/declarations/src/useSelector.d.ts

@@ -1,4 +1,5 @@
 import { AnyActorRef } from 'xstate';
+/** @public */
 export declare function useSelector<TActor extends Pick<AnyActorRef, 'subscribe' | 'getSnapshot'> | undefined, T>(actor: TActor, selector: (snapshot: TActor extends {
     getSnapshot(): infer TSnapshot;
 } ? TSnapshot : undefined) => T, compare?: (a: T, b: T) => boolean): T;

package/dist/xstate-react.cjs.js

@@ -35,15 +35,23 @@ function isStateMachine(logic) {
   return typeof logic.provide === 'function' && !!logic.config && !!logic.sources;
 }
 
+/**
+ * An already-created actor (e.g. from `restoreActor`). Hooks use it as is
+ * instead of creating one from logic.
+ */
+function isActor(value) {
+  return value instanceof xstate.Actor;
+}
+
 // The hook updates the sources of its machine on later renders. A per-hook
 // copy keeps those updates from reaching the caller's machine, which may be
 // shared by other actors.
 function ownLogic(logic) {
   return isStateMachine(logic) ? logic.provide({}) : logic;
 }
-function useIdleActorRef(logic, ...[options]) {
+function useIdleActorRef(logicOrActor, ...[options]) {
   const [actorRef, setActorRef] = React.useState(() => {
-    return xstate.createActor(ownLogic(logic), options);
+    return isActor(logicOrActor) ? logicOrActor : xstate.createActor(ownLogic(logicOrActor), options);
   });
   // An object whose identity changes only when React Fast Refresh re-renders
   // this component. Fast Refresh ignores dependency lists while it applies an
@@ -57,6 +65,11 @@ function useIdleActorRef(logic, ...[options]) {
   // `machine.provide()` for the same machine config.
   // TODO: consider using `useAsapEffect` that would do this in `useInsertionEffect` is that's available
   useIsomorphicLayoutEffect__default["default"](() => {
+    // A ready actor is owned as is; its logic is not updated by later renders.
+    if (isActor(logicOrActor)) {
+      return;
+    }
+    const logic = logicOrActor;
     const currentLogic = actorRef.logic;
     refreshSignalRef.current !== refreshSignal;
     refreshSignalRef.current = refreshSignal;
@@ -103,8 +116,20 @@ function useActorLifecycle(actorRef, setActorRef, createReplacement) {
     };
   }, [actorRef]);
 }
-function useActorRef(machine, ...[options, observerOrListener]) {
-  const [actorRef, setActorRef] = useIdleActorRef(machine, options);
+
+/**
+ * Creates an actor from `logic` (or uses an already-created `actor`, e.g. from
+ * `restoreActor`), starts it on mount and stops it on unmount. Create a passed
+ * actor once, e.g. `useState(() => restoreActor(machine, persisted))[0]`.
+ *
+ * @public
+ */
+
+function useActorRef(logicOrActor, ...args) {
+  const readyActor = isActor(logicOrActor);
+  const options = readyActor ? undefined : args[0];
+  const observerOrListener = readyActor ? args[0] : args[1];
+  const [actorRef, setActorRef] = useIdleActorRef(logicOrActor, options);
   React.useEffect(() => {
     if (!observerOrListener) {
       return;
@@ -121,6 +146,8 @@ function useActorRef(machine, ...[options, observerOrListener]) {
 function defaultCompare(a, b) {
   return a === b;
 }
+
+/** @public */
 function useSelector(actor, selector, compare = defaultCompare) {
   const subscribe = React.useCallback(handleStoreChange => {
     if (!actor) {
@@ -145,15 +172,17 @@ function useSelector(actor, selector, compare = defaultCompare) {
   return selectedSnapshot;
 }
 
+/** @public */
 function createActorContext(actorLogic, actorOptions) {
   const ReactContext = /*#__PURE__*/React__namespace.createContext(null);
   const OriginalProvider = ReactContext.Provider;
   function Provider({
     children,
     logic: providedLogic = actorLogic,
-    options: providedOptions
+    options: providedOptions,
+    actor: providedActor
   }) {
-    const actor = useActorRef(providedLogic, {
+    const actor = useActorRef(providedActor ?? providedLogic, providedActor ? undefined : {
       ...actorOptions,
       ...providedOptions
     });
@@ -191,6 +220,8 @@ function is(x, y) {
     return x !== x && y !== y;
   }
 }
+
+/** @public */
 function shallowEqual(objA, objB) {
   if (is(objA, objB)) return true;
   if (typeof objA !== 'object' || objA === null || typeof objB !== 'object' || objB === null) {
@@ -207,8 +238,17 @@ function shallowEqual(objA, objB) {
   return true;
 }
 
-function useActor(logic, ...[options]) {
-  const [actorRef, setActorRef] = useIdleActorRef(logic, options);
+/**
+ * Creates an actor from `logic` (or uses an already-created `actor`, e.g. from
+ * `restoreActor`) and subscribes to its snapshot. Create a passed actor once,
+ * e.g. `useState(() => restoreActor(machine, persisted))[0]`.
+ *
+ * @public
+ */
+
+function useActor(logic, options) {
+  const readyActor = isActor(logic);
+  const [actorRef, setActorRef] = useIdleActorRef(logic, ...[options]);
   const getSnapshot = React.useCallback(() => {
     return actorRef.getSnapshot();
   }, [actorRef]);
@@ -226,12 +266,18 @@ function useActor(logic, ...[options]) {
   if (snapshotWithStatus?.status === 'error') {
     throw snapshotWithStatus.error;
   }
-  useActorLifecycle(actorRef, setActorRef, () => xstate.createActor(actorRef.logic, options));
+  useActorLifecycle(actorRef, setActorRef, () => xstate.createActor(actorRef.logic, readyActor ? actorRef.options : options));
   return [actorSnapshot, actorRef.send, actorRef];
 }
 
-/** @alias useActor */
-function useMachine(machine, ...[options]) {
+/**
+ * @alias useActor
+ *
+ * @deprecated Use `useActor(machine, options)`.
+ * @public
+ */
+
+function useMachine(machine, options) {
   return useActor(machine, options);
 }
 

package/dist/xstate-react.development.cjs.js

@@ -35,15 +35,23 @@ function isStateMachine(logic) {
   return typeof logic.provide === 'function' && !!logic.config && !!logic.sources;
 }
 
+/**
+ * An already-created actor (e.g. from `restoreActor`). Hooks use it as is
+ * instead of creating one from logic.
+ */
+function isActor(value) {
+  return value instanceof xstate.Actor;
+}
+
 // The hook updates the sources of its machine on later renders. A per-hook
 // copy keeps those updates from reaching the caller's machine, which may be
 // shared by other actors.
 function ownLogic(logic) {
   return isStateMachine(logic) ? logic.provide({}) : logic;
 }
-function useIdleActorRef(logic, ...[options]) {
+function useIdleActorRef(logicOrActor, ...[options]) {
   const [actorRef, setActorRef] = React.useState(() => {
-    return xstate.createActor(ownLogic(logic), options);
+    return isActor(logicOrActor) ? logicOrActor : xstate.createActor(ownLogic(logicOrActor), options);
   });
   // An object whose identity changes only when React Fast Refresh re-renders
   // this component. Fast Refresh ignores dependency lists while it applies an
@@ -57,6 +65,11 @@ function useIdleActorRef(logic, ...[options]) {
   // `machine.provide()` for the same machine config.
   // TODO: consider using `useAsapEffect` that would do this in `useInsertionEffect` is that's available
   useIsomorphicLayoutEffect__default["default"](() => {
+    // A ready actor is owned as is; its logic is not updated by later renders.
+    if (isActor(logicOrActor)) {
+      return;
+    }
+    const logic = logicOrActor;
     const currentLogic = actorRef.logic;
     const refreshed = refreshSignalRef.current !== refreshSignal;
     refreshSignalRef.current = refreshSignal;
@@ -113,8 +126,20 @@ function useActorLifecycle(actorRef, setActorRef, createReplacement) {
     };
   }, [actorRef]);
 }
-function useActorRef(machine, ...[options, observerOrListener]) {
-  const [actorRef, setActorRef] = useIdleActorRef(machine, options);
+
+/**
+ * Creates an actor from `logic` (or uses an already-created `actor`, e.g. from
+ * `restoreActor`), starts it on mount and stops it on unmount. Create a passed
+ * actor once, e.g. `useState(() => restoreActor(machine, persisted))[0]`.
+ *
+ * @public
+ */
+
+function useActorRef(logicOrActor, ...args) {
+  const readyActor = isActor(logicOrActor);
+  const options = readyActor ? undefined : args[0];
+  const observerOrListener = readyActor ? args[0] : args[1];
+  const [actorRef, setActorRef] = useIdleActorRef(logicOrActor, options);
   React.useEffect(() => {
     if (!observerOrListener) {
       return;
@@ -131,6 +156,8 @@ function useActorRef(machine, ...[options, observerOrListener]) {
 function defaultCompare(a, b) {
   return a === b;
 }
+
+/** @public */
 function useSelector(actor, selector, compare = defaultCompare) {
   const subscribe = React.useCallback(handleStoreChange => {
     if (!actor) {
@@ -155,15 +182,17 @@ function useSelector(actor, selector, compare = defaultCompare) {
   return selectedSnapshot;
 }
 
+/** @public */
 function createActorContext(actorLogic, actorOptions) {
   const ReactContext = /*#__PURE__*/React__namespace.createContext(null);
   const OriginalProvider = ReactContext.Provider;
   function Provider({
     children,
     logic: providedLogic = actorLogic,
-    options: providedOptions
+    options: providedOptions,
+    actor: providedActor
   }) {
-    const actor = useActorRef(providedLogic, {
+    const actor = useActorRef(providedActor ?? providedLogic, providedActor ? undefined : {
       ...actorOptions,
       ...providedOptions
     });
@@ -201,6 +230,8 @@ function is(x, y) {
     return x !== x && y !== y;
   }
 }
+
+/** @public */
 function shallowEqual(objA, objB) {
   if (is(objA, objB)) return true;
   if (typeof objA !== 'object' || objA === null || typeof objB !== 'object' || objB === null) {
@@ -217,11 +248,20 @@ function shallowEqual(objA, objB) {
   return true;
 }
 
-function useActor(logic, ...[options]) {
-  if (!!logic && 'send' in logic && typeof logic.send === 'function') {
-    throw new Error(`useActor() expects actor logic (e.g. a machine), but received an ActorRef. Use the useSelector(actorRef, ...) hook instead to read the ActorRef's snapshot.`);
+/**
+ * Creates an actor from `logic` (or uses an already-created `actor`, e.g. from
+ * `restoreActor`) and subscribes to its snapshot. Create a passed actor once,
+ * e.g. `useState(() => restoreActor(machine, persisted))[0]`.
+ *
+ * @public
+ */
+
+function useActor(logic, options) {
+  const readyActor = isActor(logic);
+  if (!readyActor && !!logic && 'send' in logic && typeof logic.send === 'function') {
+    throw new Error(`useActor() expects actor logic (e.g. a machine), but received an ActorRef. Pass an Actor created with createActor()/restoreActor(), or use the useSelector(actorRef, ...) hook to read an ActorRef's snapshot.`);
   }
-  const [actorRef, setActorRef] = useIdleActorRef(logic, options);
+  const [actorRef, setActorRef] = useIdleActorRef(logic, ...[options]);
   const getSnapshot = React.useCallback(() => {
     return actorRef.getSnapshot();
   }, [actorRef]);
@@ -239,12 +279,18 @@ function useActor(logic, ...[options]) {
   if (snapshotWithStatus?.status === 'error') {
     throw snapshotWithStatus.error;
   }
-  useActorLifecycle(actorRef, setActorRef, () => xstate.createActor(actorRef.logic, options));
+  useActorLifecycle(actorRef, setActorRef, () => xstate.createActor(actorRef.logic, readyActor ? actorRef.options : options));
   return [actorSnapshot, actorRef.send, actorRef];
 }
 
-/** @alias useActor */
-function useMachine(machine, ...[options]) {
+/**
+ * @alias useActor
+ *
+ * @deprecated Use `useActor(machine, options)`.
+ * @public
+ */
+
+function useMachine(machine, options) {
   return useActor(machine, options);
 }
 

package/dist/xstate-react.development.esm.js

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { useEffect, useState, useMemo, useRef, useCallback } from 'react';
 import useIsomorphicLayoutEffect from 'use-isomorphic-layout-effect';
-import { _toObserver, createActor, _hotSwapActorLogic } from 'xstate';
+import { _toObserver, createActor, _hotSwapActorLogic, Actor } from 'xstate';
 import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/shim/with-selector';
 import { useSyncExternalStore } from 'use-sync-external-store/shim';
 
@@ -9,15 +9,23 @@ function isStateMachine(logic) {
   return typeof logic.provide === 'function' && !!logic.config && !!logic.sources;
 }
 
+/**
+ * An already-created actor (e.g. from `restoreActor`). Hooks use it as is
+ * instead of creating one from logic.
+ */
+function isActor(value) {
+  return value instanceof Actor;
+}
+
 // The hook updates the sources of its machine on later renders. A per-hook
 // copy keeps those updates from reaching the caller's machine, which may be
 // shared by other actors.
 function ownLogic(logic) {
   return isStateMachine(logic) ? logic.provide({}) : logic;
 }
-function useIdleActorRef(logic, ...[options]) {
+function useIdleActorRef(logicOrActor, ...[options]) {
   const [actorRef, setActorRef] = useState(() => {
-    return createActor(ownLogic(logic), options);
+    return isActor(logicOrActor) ? logicOrActor : createActor(ownLogic(logicOrActor), options);
   });
   // An object whose identity changes only when React Fast Refresh re-renders
   // this component. Fast Refresh ignores dependency lists while it applies an
@@ -31,6 +39,11 @@ function useIdleActorRef(logic, ...[options]) {
   // `machine.provide()` for the same machine config.
   // TODO: consider using `useAsapEffect` that would do this in `useInsertionEffect` is that's available
   useIsomorphicLayoutEffect(() => {
+    // A ready actor is owned as is; its logic is not updated by later renders.
+    if (isActor(logicOrActor)) {
+      return;
+    }
+    const logic = logicOrActor;
     const currentLogic = actorRef.logic;
     const refreshed = refreshSignalRef.current !== refreshSignal;
     refreshSignalRef.current = refreshSignal;
@@ -87,8 +100,20 @@ function useActorLifecycle(actorRef, setActorRef, createReplacement) {
     };
   }, [actorRef]);
 }
-function useActorRef(machine, ...[options, observerOrListener]) {
-  const [actorRef, setActorRef] = useIdleActorRef(machine, options);
+
+/**
+ * Creates an actor from `logic` (or uses an already-created `actor`, e.g. from
+ * `restoreActor`), starts it on mount and stops it on unmount. Create a passed
+ * actor once, e.g. `useState(() => restoreActor(machine, persisted))[0]`.
+ *
+ * @public
+ */
+
+function useActorRef(logicOrActor, ...args) {
+  const readyActor = isActor(logicOrActor);
+  const options = readyActor ? undefined : args[0];
+  const observerOrListener = readyActor ? args[0] : args[1];
+  const [actorRef, setActorRef] = useIdleActorRef(logicOrActor, options);
   useEffect(() => {
     if (!observerOrListener) {
       return;
@@ -105,6 +130,8 @@ function useActorRef(machine, ...[options, observerOrListener]) {
 function defaultCompare(a, b) {
   return a === b;
 }
+
+/** @public */
 function useSelector(actor, selector, compare = defaultCompare) {
   const subscribe = useCallback(handleStoreChange => {
     if (!actor) {
@@ -129,15 +156,17 @@ function useSelector(actor, selector, compare = defaultCompare) {
   return selectedSnapshot;
 }
 
+/** @public */
 function createActorContext(actorLogic, actorOptions) {
   const ReactContext = /*#__PURE__*/React.createContext(null);
   const OriginalProvider = ReactContext.Provider;
   function Provider({
     children,
     logic: providedLogic = actorLogic,
-    options: providedOptions
+    options: providedOptions,
+    actor: providedActor
   }) {
-    const actor = useActorRef(providedLogic, {
+    const actor = useActorRef(providedActor ?? providedLogic, providedActor ? undefined : {
       ...actorOptions,
       ...providedOptions
     });
@@ -175,6 +204,8 @@ function is(x, y) {
     return x !== x && y !== y;
   }
 }
+
+/** @public */
 function shallowEqual(objA, objB) {
   if (is(objA, objB)) return true;
   if (typeof objA !== 'object' || objA === null || typeof objB !== 'object' || objB === null) {
@@ -191,11 +222,20 @@ function shallowEqual(objA, objB) {
   return true;
 }
 
-function useActor(logic, ...[options]) {
-  if (!!logic && 'send' in logic && typeof logic.send === 'function') {
-    throw new Error(`useActor() expects actor logic (e.g. a machine), but received an ActorRef. Use the useSelector(actorRef, ...) hook instead to read the ActorRef's snapshot.`);
+/**
+ * Creates an actor from `logic` (or uses an already-created `actor`, e.g. from
+ * `restoreActor`) and subscribes to its snapshot. Create a passed actor once,
+ * e.g. `useState(() => restoreActor(machine, persisted))[0]`.
+ *
+ * @public
+ */
+
+function useActor(logic, options) {
+  const readyActor = isActor(logic);
+  if (!readyActor && !!logic && 'send' in logic && typeof logic.send === 'function') {
+    throw new Error(`useActor() expects actor logic (e.g. a machine), but received an ActorRef. Pass an Actor created with createActor()/restoreActor(), or use the useSelector(actorRef, ...) hook to read an ActorRef's snapshot.`);
   }
-  const [actorRef, setActorRef] = useIdleActorRef(logic, options);
+  const [actorRef, setActorRef] = useIdleActorRef(logic, ...[options]);
   const getSnapshot = useCallback(() => {
     return actorRef.getSnapshot();
   }, [actorRef]);
@@ -213,12 +253,18 @@ function useActor(logic, ...[options]) {
   if (snapshotWithStatus?.status === 'error') {
     throw snapshotWithStatus.error;
   }
-  useActorLifecycle(actorRef, setActorRef, () => createActor(actorRef.logic, options));
+  useActorLifecycle(actorRef, setActorRef, () => createActor(actorRef.logic, readyActor ? actorRef.options : options));
   return [actorSnapshot, actorRef.send, actorRef];
 }
 
-/** @alias useActor */
-function useMachine(machine, ...[options]) {
+/**
+ * @alias useActor
+ *
+ * @deprecated Use `useActor(machine, options)`.
+ * @public
+ */
+
+function useMachine(machine, options) {
   return useActor(machine, options);
 }
 

package/dist/xstate-react.esm.js

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { useEffect, useState, useMemo, useRef, useCallback } from 'react';
 import useIsomorphicLayoutEffect from 'use-isomorphic-layout-effect';
-import { _toObserver, createActor } from 'xstate';
+import { _toObserver, createActor, Actor } from 'xstate';
 import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/shim/with-selector';
 import { useSyncExternalStore } from 'use-sync-external-store/shim';
 
@@ -9,15 +9,23 @@ function isStateMachine(logic) {
   return typeof logic.provide === 'function' && !!logic.config && !!logic.sources;
 }
 
+/**
+ * An already-created actor (e.g. from `restoreActor`). Hooks use it as is
+ * instead of creating one from logic.
+ */
+function isActor(value) {
+  return value instanceof Actor;
+}
+
 // The hook updates the sources of its machine on later renders. A per-hook
 // copy keeps those updates from reaching the caller's machine, which may be
 // shared by other actors.
 function ownLogic(logic) {
   return isStateMachine(logic) ? logic.provide({}) : logic;
 }
-function useIdleActorRef(logic, ...[options]) {
+function useIdleActorRef(logicOrActor, ...[options]) {
   const [actorRef, setActorRef] = useState(() => {
-    return createActor(ownLogic(logic), options);
+    return isActor(logicOrActor) ? logicOrActor : createActor(ownLogic(logicOrActor), options);
   });
   // An object whose identity changes only when React Fast Refresh re-renders
   // this component. Fast Refresh ignores dependency lists while it applies an
@@ -31,6 +39,11 @@ function useIdleActorRef(logic, ...[options]) {
   // `machine.provide()` for the same machine config.
   // TODO: consider using `useAsapEffect` that would do this in `useInsertionEffect` is that's available
   useIsomorphicLayoutEffect(() => {
+    // A ready actor is owned as is; its logic is not updated by later renders.
+    if (isActor(logicOrActor)) {
+      return;
+    }
+    const logic = logicOrActor;
     const currentLogic = actorRef.logic;
     refreshSignalRef.current !== refreshSignal;
     refreshSignalRef.current = refreshSignal;
@@ -77,8 +90,20 @@ function useActorLifecycle(actorRef, setActorRef, createReplacement) {
     };
   }, [actorRef]);
 }
-function useActorRef(machine, ...[options, observerOrListener]) {
-  const [actorRef, setActorRef] = useIdleActorRef(machine, options);
+
+/**
+ * Creates an actor from `logic` (or uses an already-created `actor`, e.g. from
+ * `restoreActor`), starts it on mount and stops it on unmount. Create a passed
+ * actor once, e.g. `useState(() => restoreActor(machine, persisted))[0]`.
+ *
+ * @public
+ */
+
+function useActorRef(logicOrActor, ...args) {
+  const readyActor = isActor(logicOrActor);
+  const options = readyActor ? undefined : args[0];
+  const observerOrListener = readyActor ? args[0] : args[1];
+  const [actorRef, setActorRef] = useIdleActorRef(logicOrActor, options);
   useEffect(() => {
     if (!observerOrListener) {
       return;
@@ -95,6 +120,8 @@ function useActorRef(machine, ...[options, observerOrListener]) {
 function defaultCompare(a, b) {
   return a === b;
 }
+
+/** @public */
 function useSelector(actor, selector, compare = defaultCompare) {
   const subscribe = useCallback(handleStoreChange => {
     if (!actor) {
@@ -119,15 +146,17 @@ function useSelector(actor, selector, compare = defaultCompare) {
   return selectedSnapshot;
 }
 
+/** @public */
 function createActorContext(actorLogic, actorOptions) {
   const ReactContext = /*#__PURE__*/React.createContext(null);
   const OriginalProvider = ReactContext.Provider;
   function Provider({
     children,
     logic: providedLogic = actorLogic,
-    options: providedOptions
+    options: providedOptions,
+    actor: providedActor
   }) {
-    const actor = useActorRef(providedLogic, {
+    const actor = useActorRef(providedActor ?? providedLogic, providedActor ? undefined : {
       ...actorOptions,
       ...providedOptions
     });
@@ -165,6 +194,8 @@ function is(x, y) {
     return x !== x && y !== y;
   }
 }
+
+/** @public */
 function shallowEqual(objA, objB) {
   if (is(objA, objB)) return true;
   if (typeof objA !== 'object' || objA === null || typeof objB !== 'object' || objB === null) {
@@ -181,8 +212,17 @@ function shallowEqual(objA, objB) {
   return true;
 }
 
-function useActor(logic, ...[options]) {
-  const [actorRef, setActorRef] = useIdleActorRef(logic, options);
+/**
+ * Creates an actor from `logic` (or uses an already-created `actor`, e.g. from
+ * `restoreActor`) and subscribes to its snapshot. Create a passed actor once,
+ * e.g. `useState(() => restoreActor(machine, persisted))[0]`.
+ *
+ * @public
+ */
+
+function useActor(logic, options) {
+  const readyActor = isActor(logic);
+  const [actorRef, setActorRef] = useIdleActorRef(logic, ...[options]);
   const getSnapshot = useCallback(() => {
     return actorRef.getSnapshot();
   }, [actorRef]);
@@ -200,12 +240,18 @@ function useActor(logic, ...[options]) {
   if (snapshotWithStatus?.status === 'error') {
     throw snapshotWithStatus.error;
   }
-  useActorLifecycle(actorRef, setActorRef, () => createActor(actorRef.logic, options));
+  useActorLifecycle(actorRef, setActorRef, () => createActor(actorRef.logic, readyActor ? actorRef.options : options));
   return [actorSnapshot, actorRef.send, actorRef];
 }
 
-/** @alias useActor */
-function useMachine(machine, ...[options]) {
+/**
+ * @alias useActor
+ *
+ * @deprecated Use `useActor(machine, options)`.
+ * @public
+ */
+
+function useMachine(machine, options) {
   return useActor(machine, options);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xstate/react",
-  "version": "7.0.0-alpha.6",
+  "version": "7.0.0-beta.0",
   "description": "XState tools for React",
   "keywords": [
     "state",
@@ -54,7 +54,7 @@
   },
   "peerDependencies": {
     "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
-    "xstate": "^6.0.0-alpha.70"
+    "xstate": "^6.0.0-beta.0"
   },
   "dependencies": {
     "use-isomorphic-layout-effect": "^1.1.2",
@@ -69,7 +69,7 @@
     "react-dom": "^19.0.0",
     "rxjs": "^7.8.1",
     "zod": "^3.25.51",
-    "xstate": "^6.0.0-alpha.70"
+    "xstate": "^6.0.0-beta.0"
   },
   "scripts": {}
 }