Fix #5480: narrow ActorOptions.snapshot and getPersistedSnapshot() to SnapshotFrom<TLogic>

.changeset/fix-snapshot-type-5480.md

@@ -0,0 +1,13 @@
+---
+'xstate': patch
+'@xstate/react': patch
+---
+
+Fix `ActorOptions.snapshot` and `Actor.getPersistedSnapshot()` to return `SnapshotFrom<TLogic>` instead of `Snapshot<unknown>`, so that rehydrating a machine from a persisted snapshot no longer produces TypeScript errors.
+
+```ts
+const persisted = actor.getPersistedSnapshot(); // typed SnapshotFrom<TMachine>
+useMachine(machine, { snapshot: persisted }); // now typechecks
+```
+
+Resolves [#5480](https://github.com/statelyai/xstate/issues/5480).

packages/core/src/createActor.ts

@@ -784,9 +784,12 @@ export class Actor<TLogic extends AnyActorLogic>
    * Can be restored with {@link ActorOptions.state}
    * @see https://stately.ai/docs/persistence
    */
-  public getPersistedSnapshot(): Snapshot<unknown>;
-  public getPersistedSnapshot(options?: unknown): Snapshot<unknown> {
-    return this.logic.getPersistedSnapshot(this._snapshot, options);
+  public getPersistedSnapshot(): SnapshotFrom<TLogic>;
+  public getPersistedSnapshot(options?: unknown): SnapshotFrom<TLogic> {
+    return this.logic.getPersistedSnapshot(
+      this._snapshot,
+      options
+    ) as SnapshotFrom<TLogic>;
   }
 
   public [symbolObservable](): InteropSubscribable<SnapshotFrom<TLogic>> {

packages/core/src/types.ts

@@ -1865,10 +1865,10 @@ export interface ActorOptions<TLogic extends AnyActorLogic> {
    * Can be generated with {@link Actor.getPersistedSnapshot}.
    * @see https://stately.ai/docs/persistence
    */
-  snapshot?: Snapshot<unknown>;
+  snapshot?: SnapshotFrom<TLogic>;
 
   /** @deprecated Use `snapshot` instead. */
-  state?: Snapshot<unknown>;
+  state?: SnapshotFrom<TLogic>;
 
   /** The source actor logic. */
   src?: string | AnyActorLogic;

packages/xstate-react/test/createActorContext.test.tsx

@@ -3,6 +3,7 @@ import {
   assign,
   fromPromise,
   Snapshot,
+  SnapshotFrom,
   InspectionEvent
 } from 'xstate';
 import { fireEvent, screen, render, waitFor } from '@testing-library/react';
@@ -374,7 +375,7 @@ describe('createActorContext', () => {
       }
     });
     const SomeContext = createActorContext(machine);
-    let persistedState: Snapshot<unknown> | undefined = undefined;
+    let persistedState: SnapshotFrom<typeof machine> | undefined = undefined;
 
     const Component = () => {
       const actorRef = SomeContext.useActorRef();

packages/xstate-react/test/types.test.tsx

@@ -1,5 +1,11 @@
 import { render } from '@testing-library/react';
-import { ActorRefFrom, assign, createMachine, setup } from 'xstate';
+import {
+  ActorRefFrom,
+  assign,
+  createActor,
+  createMachine,
+  setup
+} from 'xstate';
 import {
   useActor,
   useActorRef,
@@ -218,3 +224,29 @@ it('useMachine types work for machines with a specified id and state with an aft
     return state.matches('enabled');
   }
 });
+
+// https://github.com/statelyai/xstate/issues/5480
+it('useMachine accepts a rehydrated snapshot from getPersistedSnapshot #5480', () => {
+  const counterMachine = setup({}).createMachine({
+    initial: 'idle',
+    states: {
+      idle: {},
+      active: {}
+    }
+  });
+
+  // Round-trip: getPersistedSnapshot() -> useMachine(machine, { snapshot })
+  // Both sides must typecheck without `as any` casts or @ts-expect-error.
+  function App() {
+    const actorRef = createActor(counterMachine).start();
+    const persistedState = actorRef.getPersistedSnapshot();
+
+    const [, , restoredRef] = useMachine(counterMachine, {
+      snapshot: persistedState
+    });
+
+    return <span data-testid="value">{restoredRef.getSnapshot().value}</span>;
+  }
+
+  render(<App />);
+});

packages/xstate-react/test/useActor.test.tsx

@@ -9,6 +9,7 @@ import {
   ActorRef,
   DoneActorEvent,
   Snapshot,
+  SnapshotFrom,
   StateFrom,
   assign,
   createActor,
@@ -86,7 +87,7 @@ describeEachReactMode('useActor (%s)', ({ suiteKey, render }) => {
 
   const Fetcher: React.FC<{
     onFetch: () => Promise<any>;
-    persistedState?: Snapshot<unknown>;
+    persistedState?: SnapshotFrom<typeof fetchMachine>;
   }> = ({
     onFetch = () => {
       return new Promise((res) => res('some data'));