XState State Machine Patterns

# XState State Machine Patterns for Google Antigravity

State machines provide predictable, debuggable application logic. This guide covers XState implementation patterns optimized for Google Antigravity IDE with Gemini 3 assistance.

## Core State Machine Configuration

```typescript
// machines/authMachine.ts
import { createMachine, assign } from 'xstate';

interface AuthContext {
  user: User | null;
  error: string | null;
  attempts: number;
  lastAttempt: Date | null;
}

type AuthEvent =
  | { type: 'LOGIN'; email: string; password: string }
  | { type: 'LOGOUT' }
  | { type: 'REFRESH_TOKEN' }
  | { type: 'SESSION_EXPIRED' }
  | { type: 'RETRY' };

export const authMachine = createMachine({
  id: 'auth',
  initial: 'idle',
  context: {
    user: null,
    error: null,
    attempts: 0,
    lastAttempt: null,
  } as AuthContext,
  states: {
    idle: {
      on: {
        LOGIN: {
          target: 'authenticating',
          actions: assign({
            attempts: (ctx) => ctx.attempts + 1,
            lastAttempt: () => new Date(),
            error: null,
          }),
        },
      },
    },
    authenticating: {
      invoke: {
        id: 'loginService',
        src: 'login',
        onDone: {
          target: 'authenticated',
          actions: assign({
            user: (_, event) => event.data.user,
            attempts: 0,
            error: null,
          }),
        },
        onError: {
          target: 'error',
          actions: assign({
            error: (_, event) => event.data.message,
          }),
        },
      },
    },
    authenticated: {
      entry: ['notifyLoginSuccess', 'startSessionTimer'],
      exit: ['clearSessionTimer'],
      on: {
        LOGOUT: {
          target: 'idle',
          actions: assign({ user: null }),
        },
        SESSION_EXPIRED: 'refreshing',
        REFRESH_TOKEN: 'refreshing',
      },
    },
    refreshing: {
      invoke: {
        id: 'refreshService',
        src: 'refreshToken',
        onDone: {
          target: 'authenticated',
          actions: assign({
            user: (_, event) => event.data.user,
          }),
        },
        onError: {
          target: 'idle',
          actions: assign({
            user: null,
            error: (_, event) => event.data.message,
          }),
        },
      },
    },
    error: {
      on: {
        RETRY: [
          {
            target: 'idle',
            cond: 'canRetry',
          },
          {
            target: 'locked',
          },
        ],
      },
    },
    locked: {
      after: {
        LOCKOUT_DURATION: 'idle',
      },
    },
  },
}, {
  guards: {
    canRetry: (context) => context.attempts < 3,
  },
  delays: {
    LOCKOUT_DURATION: 30000,
  },
  services: {
    login: async (_, event) => {
      const response = await fetch('/api/auth/login', {
        method: 'POST',
        body: JSON.stringify({ email: event.email, password: event.password }),
      });
      if (!response.ok) throw new Error('Authentication failed');
      return response.json();
    },
    refreshToken: async () => {
      const response = await fetch('/api/auth/refresh', { method: 'POST' });
      if (!response.ok) throw new Error('Token refresh failed');
      return response.json();
    },
  },
  actions: {
    notifyLoginSuccess: () => console.log('Login successful'),
    startSessionTimer: () => {},
    clearSessionTimer: () => {},
  },
});
```

## React Integration with Hooks

```typescript
// hooks/useAuthMachine.ts
import { useMachine } from '@xstate/react';
import { authMachine } from '../machines/authMachine';
import { useEffect } from 'react';

export function useAuth() {
  const [state, send, service] = useMachine(authMachine, {
    devTools: process.env.NODE_ENV === 'development',
  });

  useEffect(() => {
    const subscription = service.subscribe((state) => {
      console.log('Auth state:', state.value);
    });
    return subscription.unsubscribe;
  }, [service]);

  return {
    state: state.value,
    user: state.context.user,
    error: state.context.error,
    isAuthenticated: state.matches('authenticated'),
    isLoading: state.matches('authenticating') || state.matches('refreshing'),
    isLocked: state.matches('locked'),
    login: (email: string, password: string) => 
      send({ type: 'LOGIN', email, password }),
    logout: () => send({ type: 'LOGOUT' }),
    retry: () => send({ type: 'RETRY' }),
  };
}
```

## Complex Form State Machine

```typescript
// machines/formMachine.ts
import { createMachine, assign } from 'xstate';

export const formMachine = createMachine({
  id: 'form',
  initial: 'editing',
  context: {
    values: {},
    errors: {},
    touched: {},
    isValid: false,
    submitCount: 0,
  },
  states: {
    editing: {
      on: {
        CHANGE: {
          actions: ['updateValue', 'validateField'],
        },
        BLUR: {
          actions: ['markTouched', 'validateField'],
        },
        SUBMIT: [
          { target: 'submitting', cond: 'isFormValid' },
          { actions: 'validateAll' },
        ],
      },
    },
    submitting: {
      invoke: {
        src: 'submitForm',
        onDone: 'success',
        onError: {
          target: 'editing',
          actions: 'setSubmitError',
        },
      },
    },
    success: {
      type: 'final',
      entry: 'notifySuccess',
    },
  },
});
```

## Best Practices

1. **Visualize First**: Use XState Visualizer to design state machines before coding
2. **Keep Context Minimal**: Store only essential data in machine context
3. **Type Everything**: Leverage TypeScript for event and context type safety
4. **Test States**: Write tests for each state transition path
5. **Use Guards**: Implement conditional transitions with guard functions
6. **Spawn Actors**: Use actor model for parallel processes

Google Antigravity's Gemini 3 excels at understanding complex state logic and can generate XState machines from natural language descriptions of your application flow.