Articles/Integrations

⬡ Integrations/2026-04-10Advanced

Antigravity × XState v5 State Machine Design Guide — Build Type-Safe UI Flows, Workflows, and Form Validation

Learn how to combine XState v5 with Antigravity to design and implement complex UI state transitions, multi-step forms, and async workflows with full type safety and practical code examples.

xstate state-machine typescript²⁶ react³ workflow⁴⁹ form-validation antigravity⁴²⁹

✦ Premium Article

Setup and context — Why State Machines Matter More Than Ever

Frontend complexity keeps growing. Multi-step forms, real-time sync, payment flows, auth state management — when you build these with just useState and useEffect, you inevitably run into hard-to-reproduce bugs: missing state transitions, race conditions, and "impossible states" that shouldn't exist but somehow do.

XState v5 brings finite state machines (FSMs) and statecharts to TypeScript with full type safety. When combined with Antigravity's AI agents, you can go from designing state transition diagrams to generating code and tests in a single workflow.

This guide covers everything from XState v5 fundamentals to production-ready patterns, all with working code. It's written for intermediate to advanced engineers who have React/TypeScript experience (see Antigravity × React Complete Guide for a refresher) and are feeling the pain of complex state management.

XState v5 Core Architecture and Antigravity Integration

State Machine Fundamentals

In XState v5, you declare state transitions as a "machine definition." The API was completely redesigned from v4 to be far more TypeScript-friendly.

// Basic XState v5 machine definition
import { setup, createActor, assign } from 'xstate';
 
// Use setup() for type-safe machine definition
const toggleMachine = setup({
  types: {
    context: {} as { count: number },
    events: {} as { type: 'TOGGLE' } | { type: 'RESET' },
  },
  actions: {
    increment: assign({
      count: ({ context }) => context.count + 1,
    }),
  },
}).createMachine({
  id: 'toggle',
  initial: 'inactive',
  context: { count: 0 },
  states: {
    inactive: {
      on: {
        TOGGLE: {
          target: 'active',
          actions: 'increment',
        },
      },
    },
    active: {
      on: {
        TOGGLE: 'inactive',
        RESET: {
          target: 'inactive',
          actions: assign({ count: 0 }),
        },
      },
    },
  },
});
 
// Create an actor to execute state transitions
const actor = createActor(toggleMachine);
actor.subscribe((state) => {
  console.log(`State: ${state.value}, Count: ${state.context.count}`);
  // State: inactive, Count: 0
});
actor.start();
actor.send({ type: 'TOGGLE' });
// State: active, Count: 1

Leveraging Antigravity for Machine Design

Antigravity's AI agents can generate state transition diagrams from natural language and convert them into XState v5 code. Adding the following rules to your .antigravity/rules directory improves the quality of AI-generated state machines.

// .antigravity/rules/xstate.md
## XState v5 Code Generation Rules
- Always use the setup() API and define context and event types
- Do not use v4's Machine() or interpret() (v5 uses createMachine / createActor)
- Pre-define actions in setup()'s actions object and reference them by string
- Define guard conditions in setup()'s guards
- Implement async operations using invoke (Promise/Observable) or spawn (child Actors)

When you tell Antigravity's chat panel to "design a state machine for the auth flow," it generates type-safe code that follows these rules.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦You'll be able to diagnose and eliminate 'impossible state' bugs in complex UIs using state machine visualization and formal verification

✦You can immediately apply five production-ready patterns — multi-step forms, auth flows, WebSocket management, parallel uploads, and real-time inspection — to your own projects

✦You'll master XState v5's Actor Model, Spawn, and Inspect API to build autonomous workflow engines that integrate with AI agents

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Pattern 1: Multi-Step Form State Management

Multi-step forms for user registration, subscription sign-ups, and checkout flows are a classic state management challenge. Designing them as state machines lets you prevent invalid transitions at the type level — for example, making it impossible to reach the payment screen before completing the address form.

import { setup, assign } from 'xstate';
 
// Form data type definitions
interface FormContext {
  personalInfo: {
    name: string;
    email: string;
  } | null;
  address: {
    postalCode: string;
    prefecture: string;
    city: string;
    line1: string;
  } | null;
  payment: {
    cardToken: string;
    last4: string;
  } | null;
  errors: Record<string, string>;
  currentStep: number;
}
 
type FormEvent =
  | { type: 'SUBMIT_PERSONAL'; data: FormContext['personalInfo'] }
  | { type: 'SUBMIT_ADDRESS'; data: FormContext['address'] }
  | { type: 'SUBMIT_PAYMENT'; data: FormContext['payment'] }
  | { type: 'BACK' }
  | { type: 'VALIDATION_ERROR'; errors: Record<string, string> }
  | { type: 'RETRY' };
 
const multiStepFormMachine = setup({
  types: {
    context: {} as FormContext,
    events: {} as FormEvent,
  },
  guards: {
    isPersonalInfoValid: ({ event }) => {
      if (event.type \!== 'SUBMIT_PERSONAL') return false;
      const d = event.data;
      return \!\!d && d.name.length > 0 && d.email.includes('@');
    },
    isAddressValid: ({ event }) => {
      if (event.type \!== 'SUBMIT_ADDRESS') return false;
      const d = event.data;
      return \!\!d && d.postalCode.length === 7 && d.city.length > 0;
    },
  },
  actions: {
    savePersonalInfo: assign({
      personalInfo: ({ event }) =>
        event.type === 'SUBMIT_PERSONAL' ? event.data : null,
      currentStep: 2,
    }),
    saveAddress: assign({
      address: ({ event }) =>
        event.type === 'SUBMIT_ADDRESS' ? event.data : null,
      currentStep: 3,
    }),
    savePayment: assign({
      payment: ({ event }) =>
        event.type === 'SUBMIT_PAYMENT' ? event.data : null,
    }),
    setErrors: assign({
      errors: ({ event }) =>
        event.type === 'VALIDATION_ERROR' ? event.errors : {},
    }),
    clearErrors: assign({ errors: {} }),
  },
}).createMachine({
  id: 'multiStepForm',
  initial: 'personalInfo',
  context: {
    personalInfo: null,
    address: null,
    payment: null,
    errors: {},
    currentStep: 1,
  },
  states: {
    personalInfo: {
      on: {
        SUBMIT_PERSONAL: [
          {
            guard: 'isPersonalInfoValid',
            target: 'address',
            actions: ['clearErrors', 'savePersonalInfo'],
          },
          {
            target: 'personalInfo',
            actions: {
              type: 'setErrors',
            },
          },
        ],
      },
    },
    address: {
      on: {
        SUBMIT_ADDRESS: [
          {
            guard: 'isAddressValid',
            target: 'payment',
            actions: ['clearErrors', 'saveAddress'],
          },
          { target: 'address' },
        ],
        BACK: 'personalInfo',
      },
    },
    payment: {
      on: {
        SUBMIT_PAYMENT: {
          target: 'processing',
          actions: 'savePayment',
        },
        BACK: 'address',
      },
    },
    processing: {
      invoke: {
        src: 'submitOrder',
        onDone: 'success',
        onError: 'paymentError',
      },
    },
    paymentError: {
      on: {
        RETRY: 'payment',
      },
    },
    success: {
      type: 'final',
    },
  },
});

Integrating with React Components

// Using with React (@xstate/react v5)
import { useMachine } from '@xstate/react';
 
function CheckoutForm() {
  const [state, send] = useMachine(multiStepFormMachine, {
    actors: {
      submitOrder: fromPromise(async ({ input }) => {
        const res = await fetch('/api/checkout', {
          method: 'POST',
          body: JSON.stringify(input),
        });
        if (\!res.ok) throw new Error('Payment failed');
        return res.json();
      }),
    },
  });
 
  // Render the appropriate component based on current state
  return (
    <div>
      <StepIndicator current={state.context.currentStep} />
      {state.matches('personalInfo') && (
        <PersonalInfoStep
          onSubmit={(data) => send({ type: 'SUBMIT_PERSONAL', data })}
          errors={state.context.errors}
        />
      )}
      {state.matches('address') && (
        <AddressStep
          onSubmit={(data) => send({ type: 'SUBMIT_ADDRESS', data })}
          onBack={() => send({ type: 'BACK' })}
        />
      )}
      {state.matches('payment') && (
        <PaymentStep
          onSubmit={(data) => send({ type: 'SUBMIT_PAYMENT', data })}
          onBack={() => send({ type: 'BACK' })}
        />
      )}
      {state.matches('processing') && <LoadingSpinner />}
      {state.matches('success') && <SuccessMessage />}
      {state.matches('paymentError') && (
        <ErrorMessage onRetry={() => send({ type: 'RETRY' })} />
      )}
    </div>
  );
}

Pattern 2: Auth Flow — OAuth, MFA, and Session Management

Modern authentication flows involve numerous state transitions: OAuth redirects, multi-factor authentication (MFA), token refreshes, and more. Modeling these as a state machine helps prevent security gaps.

import { setup, assign, fromPromise } from 'xstate';
 
interface AuthContext {
  user: { id: string; email: string; role: string } | null;
  accessToken: string | null;
  refreshToken: string | null;
  mfaRequired: boolean;
  mfaMethod: 'totp' | 'sms' | null;
  error: string | null;
  retryCount: number;
}
 
const authMachine = setup({
  types: {
    context: {} as AuthContext,
    events: {} as
      | { type: 'LOGIN'; email: string; password: string }
      | { type: 'OAUTH_START'; provider: 'google' | 'github' }
      | { type: 'OAUTH_CALLBACK'; code: string; state: string }
      | { type: 'MFA_SUBMIT'; code: string }
      | { type: 'LOGOUT' }
      | { type: 'TOKEN_EXPIRED' }
      | { type: 'SESSION_CHECK' },
  },
  actors: {
    loginWithCredentials: fromPromise(
      async ({ input }: { input: { email: string; password: string } }) => {
        const res = await fetch('/api/auth/login', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(input),
        });
        if (\!res.ok) throw new Error('Authentication failed');
        return res.json();
      }
    ),
    verifyMfa: fromPromise(
      async ({ input }: { input: { code: string; token: string } }) => {
        const res = await fetch('/api/auth/mfa/verify', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(input),
        });
        if (\!res.ok) throw new Error('MFA verification failed');
        return res.json();
      }
    ),
    refreshAccessToken: fromPromise(
      async ({ input }: { input: { refreshToken: string } }) => {
        const res = await fetch('/api/auth/refresh', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(input),
        });
        if (\!res.ok) throw new Error('Token refresh failed');
        return res.json();
      }
    ),
  },
  guards: {
    requiresMfa: ({ event }) => {
      return event.type === 'xstate.done.actor' && event.output?.mfaRequired;
    },
    canRetry: ({ context }) => context.retryCount < 3,
  },
}).createMachine({
  id: 'auth',
  initial: 'idle',
  context: {
    user: null,
    accessToken: null,
    refreshToken: null,
    mfaRequired: false,
    mfaMethod: null,
    error: null,
    retryCount: 0,
  },
  states: {
    idle: {
      on: {
        LOGIN: 'authenticating',
        OAUTH_START: 'oauthRedirect',
        SESSION_CHECK: 'checkingSession',
      },
    },
    checkingSession: {
      invoke: {
        src: 'refreshAccessToken',
        input: ({ context }) => ({
          refreshToken: context.refreshToken ?? '',
        }),
        onDone: {
          target: 'authenticated',
          actions: assign({
            accessToken: ({ event }) => event.output.accessToken,
            user: ({ event }) => event.output.user,
          }),
        },
        onError: 'idle',
      },
    },
    authenticating: {
      invoke: {
        src: 'loginWithCredentials',
        input: ({ event }) => ({
          email: (event as any).email,
          password: (event as any).password,
        }),
        onDone: [
          {
            guard: 'requiresMfa',
            target: 'mfaChallenge',
            actions: assign({
              mfaRequired: true,
              mfaMethod: ({ event }) => event.output.mfaMethod,
            }),
          },
          {
            target: 'authenticated',
            actions: assign({
              user: ({ event }) => event.output.user,
              accessToken: ({ event }) => event.output.accessToken,
              refreshToken: ({ event }) => event.output.refreshToken,
              error: null,
            }),
          },
        ],
        onError: {
          target: 'authError',
          actions: assign({
            error: ({ event }) => (event.error as Error).message,
            retryCount: ({ context }) => context.retryCount + 1,
          }),
        },
      },
    },
    mfaChallenge: {
      on: {
        MFA_SUBMIT: 'verifyingMfa',
      },
    },
    verifyingMfa: {
      invoke: {
        src: 'verifyMfa',
        input: ({ event, context }) => ({
          code: (event as any).code,
          token: context.accessToken ?? '',
        }),
        onDone: {
          target: 'authenticated',
          actions: assign({
            user: ({ event }) => event.output.user,
            accessToken: ({ event }) => event.output.accessToken,
            mfaRequired: false,
          }),
        },
        onError: {
          target: 'mfaChallenge',
          actions: assign({
            error: 'Invalid verification code. Please try again.',
          }),
        },
      },
    },
    oauthRedirect: {
      entry: ({ event }) => {
        if (event.type === 'OAUTH_START') {
          window.location.href = `/api/auth/oauth/${event.provider}`;
        }
      },
      on: {
        OAUTH_CALLBACK: 'authenticating',
      },
    },
    authenticated: {
      on: {
        LOGOUT: {
          target: 'idle',
          actions: assign({
            user: null,
            accessToken: null,
            refreshToken: null,
            error: null,
          }),
        },
        TOKEN_EXPIRED: 'refreshingToken',
      },
    },
    refreshingToken: {
      invoke: {
        src: 'refreshAccessToken',
        input: ({ context }) => ({
          refreshToken: context.refreshToken ?? '',
        }),
        onDone: {
          target: 'authenticated',
          actions: assign({
            accessToken: ({ event }) => event.output.accessToken,
          }),
        },
        onError: {
          target: 'idle',
          actions: assign({
            user: null,
            accessToken: null,
            refreshToken: null,
            error: 'Your session has expired. Please log in again.',
          }),
        },
      },
    },
    authError: {
      on: {
        LOGIN: {
          guard: 'canRetry',
          target: 'authenticating',
        },
      },
    },
  },
});

The key insight here is how MFA branching is expressed declaratively through guard conditions. With useState, you'd end up with scattered conditionals like isMfaRequired && isAuthenticated && \!isLoading, which become a breeding ground for bugs.

Pattern 3: Real-Time Sync — WebSocket Connection Management

WebSocket-based real-time features involve complex state transitions: connecting, disconnecting, reconnecting, and exponential backoff.

import { setup, assign, fromCallback } from 'xstate';
 
interface WsContext {
  socket: WebSocket | null;
  url: string;
  retryCount: number;
  maxRetries: number;
  messages: Array<{ id: string; data: unknown; timestamp: number }>;
}
 
const websocketMachine = setup({
  types: {
    context: {} as WsContext,
    events: {} as
      | { type: 'CONNECT' }
      | { type: 'DISCONNECT' }
      | { type: 'SEND'; data: unknown }
      | { type: 'MESSAGE_RECEIVED'; data: unknown }
      | { type: 'CONNECTION_OPENED'; socket: WebSocket }
      | { type: 'CONNECTION_CLOSED'; code: number }
      | { type: 'CONNECTION_ERROR'; error: Event },
  },
  actors: {
    websocketConnection: fromCallback(({ sendBack, input }) => {
      const ws = new WebSocket(input.url);
 
      ws.onopen = () => sendBack({
        type: 'CONNECTION_OPENED',
        socket: ws,
      });
      ws.onmessage = (evt) => sendBack({
        type: 'MESSAGE_RECEIVED',
        data: JSON.parse(evt.data),
      });
      ws.onclose = (evt) => sendBack({
        type: 'CONNECTION_CLOSED',
        code: evt.code,
      });
      ws.onerror = (evt) => sendBack({
        type: 'CONNECTION_ERROR',
        error: evt,
      });
 
      return () => ws.close();
    }),
  },
  guards: {
    canRetry: ({ context }) => context.retryCount < context.maxRetries,
    isNormalClosure: ({ event }) =>
      event.type === 'CONNECTION_CLOSED' && event.code === 1000,
  },
}).createMachine({
  id: 'websocket',
  initial: 'disconnected',
  context: {
    socket: null,
    url: 'wss://api.example.com/ws',
    retryCount: 0,
    maxRetries: 5,
    messages: [],
  },
  states: {
    disconnected: {
      on: { CONNECT: 'connecting' },
    },
    connecting: {
      invoke: {
        src: 'websocketConnection',
        input: ({ context }) => ({ url: context.url }),
      },
      on: {
        CONNECTION_OPENED: {
          target: 'connected',
          actions: assign({
            socket: ({ event }) => event.socket,
            retryCount: 0,
          }),
        },
        CONNECTION_ERROR: [
          { guard: 'canRetry', target: 'reconnecting' },
          { target: 'failed' },
        ],
      },
    },
    connected: {
      on: {
        SEND: {
          actions: ({ context, event }) => {
            context.socket?.send(JSON.stringify(event.data));
          },
        },
        MESSAGE_RECEIVED: {
          actions: assign({
            messages: ({ context, event }) => [
              ...context.messages,
              {
                id: crypto.randomUUID(),
                data: event.data,
                timestamp: Date.now(),
              },
            ],
          }),
        },
        CONNECTION_CLOSED: [
          { guard: 'isNormalClosure', target: 'disconnected' },
          { guard: 'canRetry', target: 'reconnecting' },
          { target: 'failed' },
        ],
        DISCONNECT: {
          target: 'disconnected',
          actions: ({ context }) => {
            context.socket?.close(1000, 'User disconnected');
          },
        },
      },
    },
    reconnecting: {
      after: {
        // Exponential backoff: 1s, 2s, 4s, 8s, 16s
        RECONNECT_DELAY: 'connecting',
      },
      entry: assign({
        retryCount: ({ context }) => context.retryCount + 1,
      }),
    },
    failed: {
      on: {
        CONNECT: {
          target: 'connecting',
          actions: assign({ retryCount: 0 }),
        },
      },
    },
  },
  delays: {
    RECONNECT_DELAY: ({ context }) =>
      Math.min(1000 * Math.pow(2, context.retryCount), 30000),
  },
});

Exponential backoff with reconnection is expressed using after and dynamic delays. Compared to the traditional setTimeout + flag management approach, the logic is dramatically more readable.

Pattern 4: Actor Model for Parallel Processing

The real power of XState v5 lies in the Actor Model. You can spawn child actors from a parent machine and run independent state management in parallel.

import { setup, assign, fromPromise } from 'xstate';
 
// Child actor managing individual file uploads
const fileUploadMachine = setup({
  types: {
    context: {} as {
      file: File;
      progress: number;
      url: string | null;
      error: string | null;
    },
    events: {} as
      | { type: 'START' }
      | { type: 'PROGRESS'; value: number }
      | { type: 'CANCEL' },
    input: {} as { file: File },
  },
  actors: {
    uploadFile: fromPromise(async ({ input, self }) => {
      const formData = new FormData();
      formData.append('file', input.file);
 
      const xhr = new XMLHttpRequest();
      return new Promise((resolve, reject) => {
        xhr.upload.addEventListener('progress', (e) => {
          if (e.lengthComputable) {
            self.send({
              type: 'PROGRESS',
              value: Math.round((e.loaded / e.total) * 100),
            });
          }
        });
        xhr.addEventListener('load', () => {
          if (xhr.status === 200) {
            resolve(JSON.parse(xhr.responseText));
          } else {
            reject(new Error(`Upload failed: ${xhr.status}`));
          }
        });
        xhr.addEventListener('error', () =>
          reject(new Error('Network error'))
        );
        xhr.open('POST', '/api/upload');
        xhr.send(formData);
      });
    }),
  },
}).createMachine({
  id: 'fileUpload',
  initial: 'idle',
  context: ({ input }) => ({
    file: input.file,
    progress: 0,
    url: null,
    error: null,
  }),
  states: {
    idle: { on: { START: 'uploading' } },
    uploading: {
      invoke: {
        src: 'uploadFile',
        input: ({ context }) => ({ file: context.file }),
        onDone: {
          target: 'complete',
          actions: assign({
            url: ({ event }) => event.output.url,
            progress: 100,
          }),
        },
        onError: {
          target: 'error',
          actions: assign({
            error: ({ event }) => (event.error as Error).message,
          }),
        },
      },
      on: {
        PROGRESS: {
          actions: assign({
            progress: ({ event }) => event.value,
          }),
        },
        CANCEL: 'cancelled',
      },
    },
    complete: { type: 'final' },
    error: { on: { START: 'uploading' } },
    cancelled: { type: 'final' },
  },
});
 
// Parent machine managing batch uploads
const batchUploadMachine = setup({
  types: {
    context: {} as {
      uploads: Map<string, any>;
      completedCount: number;
      totalCount: number;
    },
    events: {} as
      | { type: 'ADD_FILES'; files: File[] }
      | { type: 'START_ALL' }
      | { type: 'FILE_COMPLETE'; fileId: string },
  },
}).createMachine({
  id: 'batchUpload',
  initial: 'idle',
  context: {
    uploads: new Map(),
    completedCount: 0,
    totalCount: 0,
  },
  states: {
    idle: {
      on: {
        ADD_FILES: {
          target: 'ready',
          actions: assign({
            totalCount: ({ event }) => event.files.length,
          }),
        },
      },
    },
    ready: {
      on: { START_ALL: 'uploading' },
    },
    uploading: {
      always: {
        guard: ({ context }) =>
          context.completedCount >= context.totalCount,
        target: 'done',
      },
      on: {
        FILE_COMPLETE: {
          actions: assign({
            completedCount: ({ context }) => context.completedCount + 1,
          }),
        },
      },
    },
    done: { type: 'final' },
  },
});

Pattern 5: Inspect API for Visualization and Debugging

XState v5's Inspect API is a powerful tool for monitoring state machine behavior in real time, even in production.

import { createActor } from 'xstate';
import { createBrowserInspector } from '@statelyai/inspect';
 
// Enable Inspector only in development
const inspector = process.env.NODE_ENV === 'development'
  ? createBrowserInspector()
  : undefined;
 
const actor = createActor(authMachine, {
  inspect: inspector?.inspect,
});
 
// Custom Inspect handler for production telemetry
const productionInspector = (inspectionEvent: any) => {
  if (inspectionEvent.type === '@xstate.snapshot') {
    analytics.track('state_transition', {
      machineId: inspectionEvent.actorRef.id,
      state: inspectionEvent.snapshot.value,
      timestamp: Date.now(),
    });
  }
  if (inspectionEvent.type === '@xstate.event') {
    if (inspectionEvent.event.type.includes('error')) {
      errorTracking.capture({
        machineId: inspectionEvent.actorRef.id,
        event: inspectionEvent.event,
      });
    }
  }
};
 
const productionActor = createActor(authMachine, {
  inspect: productionInspector,
});

When debugging in Antigravity, you can integrate the Stately Inspector with Chrome DevTools to verify AI-generated state machine behavior in real time.

Testing Strategy for XState v5 with Antigravity

One of the greatest advantages of state machines is that they enable model-based testing. You can automatically generate test paths from the state transition graph.

import { createActor } from 'xstate';
import { describe, it, expect } from 'vitest';
 
describe('Auth Flow', () => {
  it('successful login → authenticated', async () => {
    const actor = createActor(authMachine);
    actor.start();
 
    expect(actor.getSnapshot().value).toBe('idle');
 
    actor.send({
      type: 'LOGIN',
      email: 'user@example.com',
      password: 'secure-password',
    });
 
    expect(actor.getSnapshot().value).toBe('authenticating');
 
    // Wait for invoke to complete
    await waitFor(actor, (state) => state.value === 'authenticated');
    expect(actor.getSnapshot().context.user).not.toBeNull();
  });
 
  it('MFA required → MFA challenge', async () => {
    const actor = createActor(authMachine);
    actor.start();
 
    actor.send({
      type: 'LOGIN',
      email: 'admin@example.com',
      password: 'secure-password',
    });
 
    await waitFor(actor, (state) => state.value === 'mfaChallenge');
    expect(actor.getSnapshot().context.mfaRequired).toBe(true);
 
    actor.send({ type: 'MFA_SUBMIT', code: '123456' });
    await waitFor(actor, (state) => state.value === 'authenticated');
  });
 
  it('retry limit exceeded → stuck in authError', async () => {
    const actor = createActor(authMachine, {
      actors: {
        loginWithCredentials: fromPromise(async () => {
          throw new Error('Server error');
        }),
      },
    });
    actor.start();
 
    // Fail 3 times
    for (let i = 0; i < 3; i++) {
      actor.send({ type: 'LOGIN', email: 'a@b.com', password: 'x' });
      await waitFor(actor, (state) => state.value === 'authError');
    }
 
    // 4th attempt is blocked by guard
    actor.send({ type: 'LOGIN', email: 'a@b.com', password: 'x' });
    expect(actor.getSnapshot().value).toBe('authError');
  });
});

For a deeper dive into test-driven development strategies, check out Antigravity × TDD Mastery. When you ask Antigravity's AI agent to "generate tests covering all transition paths for this state machine," it produces test code that covers every reachable state transition. You can also use the @xstate/test package's createTestModel to automatically enumerate test paths from the state graph.

Summary

By combining XState v5 with Antigravity's AI agents, you can handle complex UI state management through a unified pipeline: design, implement, test, and visualize — all with full type safety. State machines have an initial learning curve, but once adopted, they fundamentally eliminate state-related bugs.

The five patterns in this article — multi-step forms, auth flows, WebSocket management, Actor parallel processing, and Inspect visualization — are production-ready designs you can apply immediately. Start with features that have clear state transitions, like auth flows or forms. If you're interested in server-side fault-tolerant workflows, check out Antigravity × Temporal.io Production Guide as well.

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.