feat(actor): add dispatchPromise for non-Effect boundaries

Promise-based dispatch for React event handlers, framework hooks, and
tests that operate outside the Effect runtime.

- Add dispatchPromise to ActorRef interface and implementation
- 2 new tests: matching and non-matching via Promise API
- Add changeset for minor release

Author: cevr

.changeset/dispatch-api.md

@@ -0,0 +1,11 @@
+---
+"effect-machine": minor
+---
+
+Add `dispatch` and `dispatchPromise` to ActorRef — synchronous event processing with transition receipts.
+
+**`dispatch(event)`** — Effect-based. Sends event through the queue (preserving serialization) and returns `ProcessEventResult<State>` with `{ transitioned, previousState, newState, lifecycleRan, isFinal }`. OTP `gen_server:call` equivalent.
+
+**`dispatchPromise(event)`** — Promise-based. Same semantics as `dispatch` for use at non-Effect boundaries (React event handlers, framework hooks, tests).
+
+Also exports `ProcessEventResult` from the public API.

src/actor.ts

@@ -181,6 +181,12 @@ export interface ActorRef<State extends { readonly _tag: string }, Event> {
    */
   readonly dispatch: (event: Event) => Effect.Effect<ProcessEventResult<State>>;
 
+  /**
+   * Promise-based dispatch — send event and get back the transition result.
+   * Use at non-Effect boundaries (React event handlers, framework hooks, tests).
+   */
+  readonly dispatchPromise: (event: Event) => Promise<ProcessEventResult<State>>;
+
   /**
    * Subscribe to state changes (sync callback)
    * Returns unsubscribe function
@@ -549,6 +555,7 @@ export const buildActorRefCore = <
       }
     },
     dispatch,
+    dispatchPromise: (event) => Effect.runPromise(dispatch(event)),
     subscribe: (fn) => {
       listeners.add(fn);
       return () => {

test/dispatch.test.ts

@@ -166,3 +166,35 @@ describe("ActorRef.dispatch", () => {
     }),
   );
 });
+
+describe("ActorRef.dispatchPromise", () => {
+  it.scopedLive("returns ProcessEventResult as Promise", () =>
+    Effect.gen(function* () {
+      const machine = createMachine();
+      const actor = yield* Machine.spawn(machine);
+
+      const result = yield* Effect.promise(() =>
+        actor.dispatchPromise(TestEvent.Start({ value: 99 })),
+      );
+
+      expect(result.transitioned).toBe(true);
+      expect(result.previousState._tag).toBe("Idle");
+      expect(result.newState._tag).toBe("Active");
+      if (result.newState._tag === "Active") {
+        expect(result.newState.value).toBe(99);
+      }
+    }),
+  );
+
+  it.scopedLive("non-matching event returns transitioned false", () =>
+    Effect.gen(function* () {
+      const machine = createMachine();
+      const actor = yield* Machine.spawn(machine);
+
+      const result = yield* Effect.promise(() => actor.dispatchPromise(TestEvent.Unknown));
+
+      expect(result.transitioned).toBe(false);
+      expect(result.newState._tag).toBe("Idle");
+    }),
+  );
+});