concurrent-safe-state-machines_skill

Overview

This skill teaches how to design deterministic state machines that remain correct under concurrent rendering, re-entrancy, and StrictMode double-invocation. It focuses on patterns that make transitions idempotent, side effects isolatable, and reads immune to torn/interleaved renders. The result is predictable UI state, easier reasoning, and robust tests that hold under randomized scheduling.

How this skill works

The approach models every transition as a pure, replay-tolerant reducer and separates effects into deterministic setup/cleanup pairs. Reducers are idempotent so repeated or interleaved invocations yield the same next-state. Side effects are scheduled and cleaned up so double-invocation and cancellation don’t produce visible divergence. The skill also includes strategies to avoid torn reads by deriving UI from a single source of truth and using snapshotting where appropriate.

When to use it

• Building UI components that must be correct under React 18 concurrent rendering and StrictMode double-invocation
• Designing systems where re-entrant handlers or async updates may interleave state transitions
• Implementing complex workflows or wizards where partial updates can leave inconsistent state
• Creating libraries or shared components that must guarantee deterministic behavior across environments

Best practices

• Model state transitions as pure functions with explicit input and output; avoid hidden mutable closures
• Make reducers idempotent: repeated application with the same inputs must produce the same state
• Isolate side effects with clear setup and cleanup so effects are safe to run multiple times
• Document invariants and a transition table; assert them in tests and at runtime when feasible
• Use property-based and randomized scheduling tests to uncover race-like interleavings

Example use cases

• A multi-step form whose validation and navigation remain consistent under re-renders and canceled effects
• An offline-first sync engine that must remain correct when retries, cancellations, or duplicate work occur
• A shared component library that guarantees deterministic state across different consumer render strategies
• Complex modal/dialog stacks with nested lifecycles that must not leak state when rapidly mounted/unmounted