case management screen
multi-file upload
multi-step onboarding
approval workflow
bulk operation dashboard
notification center
chat / inbox
background sync panel
wizard dengan autosave
modal stack dengan confirm workflow
long-running import/export job monitor

owns state
receives events
updates itself through legal transitions
may emit snapshots
may send events to other actors
may start/stop child actors
may run async work through invoked/spawned actors

React component:
  snapshot -> render
  user action -> send(event)

Actor:
  event -> transition
  transition -> next snapshot
  transition -> effects/child actors/messages

Component mana yang butuh state ini?

Proses apa yang memiliki state ini?
Kapan proses ini dimulai?
Kapan proses ini selesai?
Siapa yang boleh mengirim event ke proses ini?
Snapshot apa yang boleh dibaca UI?
Apa yang terjadi saat proses gagal, dibatalkan, atau ditinggalkan?

1. Ada lifecycle jelas:
   idle -> editing -> validating -> submitting -> succeeded/failed

2. Ada banyak event legal/ilegal:
   submit hanya legal jika valid
   retry hanya legal setelah failed
   cancel hanya legal saat pending

3. Ada async work yang perlu cancellation atau request identity.

4. Ada banyak instance proses sejenis:
   upload file A/B/C masing-masing punya progress dan failure.

5. Ada parent-child workflow:
   dashboard actor mengelola banyak row actors.

6. Ada workflow yang perlu observability:
   audit trail, breadcrumb, state transition logging.

7. Ada risiko impossible state:
   isSubmitting true tapi submitResult juga null dan error lama masih tampil.

input lokal sederhana
boolean toggle lokal
computed derived value
view-only formatting
state ephemeral yang tidak punya lifecycle kompleks

Jika kamu bisa menjelaskan state dengan satu value dan dua event, pakai useState.
Jika kamu butuh invariant beberapa field, pakai reducer.
Jika kamu butuh lifecycle process dengan event legal/ilegal, pertimbangkan machine.
Jika kamu butuh banyak process instance yang hidup/mati dinamis, pertimbangkan actor model.

1. Ownership
   State apa yang dimiliki actor?

2. Events
   Event apa yang diterima?

3. Snapshot
   Data apa yang diekspos untuk UI/actor lain?

4. Commands/effects
   External work apa yang boleh dijalankan?

5. Lifecycle
   Kapan actor dibuat, dihentikan, reset, atau diganti?

6. Supervision
   Siapa yang menangani failure child actor?

send({ type: 'SET_ANYTHING', key: 'status', value: 'done' });

type UploadEvent =
  | { type: 'file.selected'; file: File }
  | { type: 'upload.requested' }
  | { type: 'upload.progress'; loaded: number; total: number }
  | { type: 'upload.succeeded'; assetId: string }
  | { type: 'upload.failed'; reason: string }
  | { type: 'upload.cancelled' }
  | { type: 'retry.requested' };

type UploadSnapshot = {
  rawMachineState: unknown;
  mutableContext: any;
  internalQueue: unknown[];
  abortController: AbortController | null;
};

type UploadViewSnapshot = {
  phase: 'idle' | 'selected' | 'uploading' | 'failed' | 'completed';
  fileName: string | null;
  progressPercent: number;
  canStart: boolean;
  canCancel: boolean;
  canRetry: boolean;
  errorMessage: string | null;
  assetId: string | null;
};

Apa yang harus ditampilkan?
Tombol mana yang enabled?
Pesan apa yang muncul?
Event apa yang bisa dikirim sekarang?

review decision
multi-step form
bulk approval
checkout
file import

idle -> editing -> validating -> submitting -> success/error

row actor for file upload
case actor for expanded case row
chat thread actor
notification actor

upload queue actor
case selection actor
task board actor

websocket actor
broadcast-channel actor
timer actor
online-status actor
analytics actor

modal stack actor
toast queue actor
command palette actor

draft
validation
touched/dirty
server error mapping
autosave
submit
resume

invoke:
  actor hidup karena parent sedang berada di state tertentu
  actor berhenti ketika state itu keluar
  cocok untuk finite/known async work

spawn:
  actor dibuat secara dinamis
  actor bisa hidup sampai dihentikan eksplisit/lifecycle parent selesai
  cocok untuk jumlah actor yang dinamis/unknown

load current case
submit current form
validate current step
wait for timeout
listen while state active

one actor per uploaded file
one actor per chat thread
one actor per active job
one actor per editable row
one actor per background task

Memakai global spawned actor untuk semua hal hanya agar bisa diakses dari mana saja.

parent sends command/event to child
child emits event/result to parent
parent reads child snapshot
parent aggregates child state
sibling communication lewat parent mediator

RowActor A -> RowActor B -> RowActor C

RowActor A -> ParentActor -> RowActor B

type Listener<TSnapshot> = (snapshot: TSnapshot) => void;

type Actor<TEvent, TSnapshot> = {
  send(event: TEvent): void;
  getSnapshot(): TSnapshot;
  subscribe(listener: Listener<TSnapshot>): () => void;
  stop(): void;
};

function createActor<TEvent, TSnapshot>(options: {
  initialSnapshot: TSnapshot;
  transition: (snapshot: TSnapshot, event: TEvent) => TSnapshot;
}): Actor<TEvent, TSnapshot> {
  let snapshot = options.initialSnapshot;
  let stopped = false;
  const listeners = new Set<Listener<TSnapshot>>();

  function emit() {
    for (const listener of listeners) {
      listener(snapshot);
    }
  }

  return {
    send(event) {
      if (stopped) return;
      const next = options.transition(snapshot, event);
      if (Object.is(next, snapshot)) return;
      snapshot = next;
      emit();
    },
    getSnapshot() {
      return snapshot;
    },
    subscribe(listener) {
      if (stopped) return () => {};
      listeners.add(listener);
      return () => listeners.delete(listener);
    },
    stop() {
      stopped = true;
      listeners.clear();
    },
  };
}

import { useSyncExternalStore } from 'react';

function useActorSnapshot<TEvent, TSnapshot>(actor: Actor<TEvent, TSnapshot>) {
  return useSyncExternalStore(
    actor.subscribe,
    actor.getSnapshot,
    actor.getSnapshot,
  );
}

type CounterEvent =
  | { type: 'increment' }
  | { type: 'decrement' };

type CounterSnapshot = {
  count: number;
  canDecrement: boolean;
};

const counterActor = createActor<CounterEvent, CounterSnapshot>({
  initialSnapshot: { count: 0, canDecrement: false },
  transition(snapshot, event) {
    switch (event.type) {
      case 'increment': {
        const count = snapshot.count + 1;
        return { count, canDecrement: count > 0 };
      }
      case 'decrement': {
        const count = Math.max(0, snapshot.count - 1);
        return { count, canDecrement: count > 0 };
      }
    }
  },
});

function CounterView() {
  const snapshot = useActorSnapshot(counterActor);

  return (
    <section>
      <p>{snapshot.count}</p>
      <button onClick={() => counterActor.send({ type: 'decrement' })} disabled={!snapshot.canDecrement}>
        -
      </button>
      <button onClick={() => counterActor.send({ type: 'increment' })}>
        +
      </button>
    </section>
  );
}

send event
read snapshot
subscribe snapshot
stop actor

Store:
  data container + update functions
  focus: current data and selectors

Actor:
  behavior process + event protocol
  focus: legal transitions, lifecycle, messages, child actors

User memilih banyak file.
Setiap file punya progress sendiri.
File bisa cancel/retry sendiri.
Queue punya aggregate progress.
Beberapa file boleh upload paralel, tapi maksimal 3.
Jika route ditinggalkan, active upload harus cancel/confirm.

type UploadItem = {
  id: string;
  file: File;
  status: 'queued' | 'uploading' | 'failed' | 'done';
  progress: number;
  error?: string;
};

file actor registry
concurrency limit
aggregate progress
bulk cancel
bulk retry
which files are active

selected file
upload phase
progress
abort controller/request id
retry count
final asset id
per-file error

type UploadQueueEvent =
  | { type: 'files.added'; files: File[] }
  | { type: 'file.remove.requested'; fileId: string }
  | { type: 'file.start.requested'; fileId: string }
  | { type: 'file.cancel.requested'; fileId: string }
  | { type: 'file.retry.requested'; fileId: string }
  | { type: 'file.progressed'; fileId: string; loaded: number; total: number }
  | { type: 'file.completed'; fileId: string; assetId: string }
  | { type: 'file.failed'; fileId: string; reason: string }
  | { type: 'queue.cancelAll.requested' };

type FileUploadEvent =
  | { type: 'start' }
  | { type: 'progress'; loaded: number; total: number }
  | { type: 'complete'; assetId: string }
  | { type: 'fail'; reason: string }
  | { type: 'cancel' }
  | { type: 'retry' };

UI event -> Queue actor
Queue actor -> child file actor
Child file actor -> Queue actor result/aggregate event
Queue actor snapshot -> UI

import { assign, createMachine, setup } from 'xstate';

type FileRef = unknown; // ActorRef type omitted for readability.

type QueueContext = {
  files: Record<string, FileRef>;
  order: string[];
  maxParallel: number;
};

const fileUploadMachine = setup({
  types: {} as {
    context: {
      id: string;
      file: File;
      progress: number;
      assetId: string | null;
      error: string | null;
    };
    events:
      | { type: 'start' }
      | { type: 'progress'; loaded: number; total: number }
      | { type: 'complete'; assetId: string }
      | { type: 'fail'; reason: string }
      | { type: 'cancel' }
      | { type: 'retry' };
  },
}).createMachine({
  initial: 'queued',
  context: ({ input }: any) => ({
    id: input.id,
    file: input.file,
    progress: 0,
    assetId: null,
    error: null,
  }),
  states: {
    queued: {
      on: { start: 'uploading' },
    },
    uploading: {
      on: {
        progress: {
          actions: assign({
            progress: ({ event }) => Math.round((event.loaded / event.total) * 100),
          }),
        },
        complete: {
          target: 'completed',
          actions: assign({ assetId: ({ event }) => event.assetId }),
        },
        fail: {
          target: 'failed',
          actions: assign({ error: ({ event }) => event.reason }),
        },
        cancel: 'cancelled',
      },
    },
    failed: {
      on: { retry: 'queued' },
    },
    completed: { type: 'final' },
    cancelled: { type: 'final' },
  },
});

const uploadQueueMachine = setup({
  types: {} as {
    context: QueueContext;
    events:
      | { type: 'files.added'; files: File[] }
      | { type: 'queue.cancelAll.requested' };
  },
}).createMachine({
  context: {
    files: {},
    order: [],
    maxParallel: 3,
  },
  on: {
    'files.added': {
      actions: assign(({ context, event, spawn }) => {
        const nextFiles = { ...context.files };
        const nextOrder = [...context.order];

        for (const file of event.files) {
          const id = crypto.randomUUID();
          const ref = spawn(fileUploadMachine, {
            id: `upload-${id}`,
            input: { id, file },
          });

          nextFiles[id] = ref;
          nextOrder.push(id);
        }

        return {
          files: nextFiles,
          order: nextOrder,
        };
      }),
    },
  },
});

Keep child refs opaque to most UI.
Expose derived list snapshots through selector/hooks.
Do not let random components mutate child actor internals.

type ActorRegistry<TRef> = {
  byId: Record<string, TRef>;
  order: string[];
};

register(id, ref)
unregister(id)
sendTo(id, event)
broadcast(event)
select(id)
aggregate snapshots
stop removed actors

type UploadQueueView = {
  total: number;
  completed: number;
  failed: number;
  uploading: number;
  aggregateProgress: number;
  canCancelAll: boolean;
  canRetryFailed: boolean;
};

Actor snapshots are external data.
If parent derives aggregate from child snapshots, it needs a subscription strategy.

1. Child sends result/progress events to parent.
2. Parent subscribes to children and updates aggregate.
3. UI subscribes to each child actor row separately.
4. External store tracks actor snapshot projection.

function UploadWidget() {
  const actorRef = useMemo(() => createActor(uploadQueueMachine).start(), []);

  useEffect(() => {
    return () => actorRef.stop();
  }, [actorRef]);

  // ...
}

const UploadActorContext = createContext<UploadActorRef | null>(null);

function UploadProvider({ children }: { children: React.ReactNode }) {
  const [snapshot, send, actorRef] = useMachine(uploadQueueMachine);

  return (
    <UploadActorContext.Provider value={actorRef}>
      {children}
    </UploadActorContext.Provider>
  );
}

/cases/:caseId/review
  ReviewRouteActor exists while route is active

websocket connection actor
online status actor
feature flag stream actor
notification queue actor

child upload failed -> queue marks failed count
form validation actor failed -> form actor displays error
websocket actor disconnected -> app status actor schedules reconnect
modal child rejected -> modal manager resolves promise with cancel

child throws, UI silently stuck pending

child failure is converted into explicit event
parent decides retry/cancel/escalate
UI snapshot exposes recovery options

retry policy
backoff
cancellation
cleanup
aggregate error reporting
user notification
audit/breadcrumb

route changes
modal closes
tab closes
user cancels
new request supersedes old request
permission changes
entity is deleted remotely

type WorkflowEvent =
  | { type: 'route.left' }
  | { type: 'cancel.requested' }
  | { type: 'entity.deleted.remotely' }
  | { type: 'request.superseded'; requestId: string };

A pending actor must know how to stop.
A stopped actor must not emit stale success into new workflow.
A cancelled actor must produce a known snapshot or final event.

event received
transition taken
state entered/exited
child actor spawned/stopped
command started
command succeeded/failed
retry scheduled
cancellation requested

{
  "actor": "review-case-CASE-123",
  "event": "submit.failed",
  "from": "submitting",
  "to": "failed",
  "reasonCode": "POLICY_VIOLATION"
}

{
  "field": "isLoading",
  "value": false
}

transition tests
illegal event tests
guard tests
invoke success/failure tests
spawn/stop lifecycle tests
parent-child communication tests
supervision tests
cancellation tests

it('does not submit invalid draft', () => {
  const actor = createActor(reviewMachine, {
    input: { caseId: 'CASE-1' },
  }).start();

  actor.send({ type: 'submit.requested' });

  expect(actor.getSnapshot().matches('editing')).toBe(true);
  expect(actor.getSnapshot().context.validationErrors.length).toBeGreaterThan(0);
});

it('marks queue completed when all child uploads complete', () => {
  const queue = createActor(uploadQueueMachine).start();

  queue.send({ type: 'files.added', files: [fileA, fileB] });
  queue.send({ type: 'file.completed', fileId: 'a', assetId: 'A1' });
  queue.send({ type: 'file.completed', fileId: 'b', assetId: 'B1' });

  expect(queue.getSnapshot().context.completedCount).toBe(2);
  expect(queue.getSnapshot().matches('completed')).toBe(true);
});

button sends correct event
snapshot renders correct state
disabled states match canX flags
focus/error announcement works

one root actor receives every event in the app
all components import same actorRef
no clear lifecycle

split by process boundary
scope actor to route/subtree
keep capability actors separate from workflow actors

send({ type: 'UPDATE', payload: any });
send({ type: 'SET_STATE', value: any });

model domain/UI events explicitly
name events as facts/intents
make illegal events impossible or ignored by state

spawned actors remain after row removed or route changed
background work continues after UI abandoned

define unregister/stop lifecycle
prefer invoke when lifecycle tied to state
stop spawned actor on removal/finalization
write tests for cleanup

parent directly mutates child context conceptually
parent has switch statements for every child internal state

child exposes compact snapshot
parent receives meaningful child events
hide child internals behind protocol

actors directly know each other IDs and protocols
changing one actor breaks another actor

route sibling communication through parent/coordinator
use event contracts
avoid arbitrary actor imports

component rerenders on every actor micro-change
large dashboard becomes sluggish

selector subscription
row-level actor subscription
derived read models
stable snapshots
memoized components

if (snapshot.matches('ready')) {
  actor.send({ type: 'start' });
}

commands belong in event handlers/effects/machine transitions
render must remain pure

[ ] What process does this actor represent?
[ ] What state does it own exclusively?
[ ] What events can it receive?
[ ] Which events are legal only in certain states?
[ ] What snapshot does UI read?
[ ] Who creates the actor?
[ ] Who stops the actor?
[ ] Can child actors leak?
[ ] How is cancellation handled?
[ ] How are failures supervised?
[ ] How is state observed/logged?
[ ] How are transitions tested without React?
[ ] Is this truly actor-worthy, or just local/reducer state?

Component tree answers:
  What renders where?

State topology answers:
  Which state lives where?

Actor model answers:
  Which processes exist, how do they communicate, and how do they die?

late response overwrites newer state
background task outlives screen
modal resolves twice
retry runs after cancel
row state belongs to wrong item after reorder
wizard step submits stale draft
permission changes while command is pending