rn-gamekit 0.1.0 → 0.2.0

package/src/core/session/createGameSession.ts

@@ -1,3 +1,4 @@
+import type { AssetGroupMap } from '../../assets/types';
 import type { GameDefinition, InputMap, SceneMap } from '../../definition/types';
 import type { SceneTransitionController } from '../../scene/types';
 import { createAnimationFrameDriver, type FrameDriver, type FrameHandle } from '../frameDriver';
@@ -14,8 +15,54 @@ import {
 } from './types';
 import type { SessionDiagnostics } from './diagnostics';
 import { createDeepFreeze, type DeepFreezer } from './deepFreeze';
+import type { GameEventDescriptor } from '../../events/types';
+import type { AnyGameEventEnvelope } from '../../events/types';
+import { GameEventError } from '../../events/errors';
+import { cloneAndValidatePayload } from '../../events/payload';
 
 const DEFAULT_FIXED_STEP_MS = 1000 / 60;
+
+/**
+ * A captured failure: an explicit boolean record so an arbitrary thrown
+ * value (including `undefined`) is never confused with "no failure".
+ */
+interface CapturedFailure {
+  readonly failed: true;
+  readonly value: unknown;
+}
+
+type FailureRecord = { readonly failed: false } | CapturedFailure;
+
+const NO_FAILURE: FailureRecord = { failed: false };
+
+/** Run a closure and capture its thrown value, whatever its type. */
+function captureFailure(run: () => void): FailureRecord {
+  try {
+    run();
+    return NO_FAILURE;
+  } catch (error) {
+    return { failed: true, value: error };
+  }
+}
+
+/** Surface a captured failure, throwing `undefined` if that was the value. */
+function throwFailure(record: FailureRecord): void {
+  if (record.failed) {
+    throw record.value;
+  }
+}
+
+/**
+ * Immutably compose two failures into one lossless error: an AggregateError
+ * with a stable message and ordered `errors`. Neither thrown value is
+ * mutated or wrapped away.
+ */
+function composeFailures(first: unknown, second: unknown): unknown {
+  return new AggregateError(
+    [first, second],
+    'Lifecycle operation failed with multiple errors',
+  );
+}
 const DEFAULT_MAX_CATCH_UP_STEPS = 5;
 
 interface SessionOptions {
@@ -30,11 +77,14 @@ interface SessionOptions {
 interface ErasedScene {
   readonly actions: readonly string[];
   readonly transitions: readonly string[];
+  readonly emits?: readonly string[];
+  readonly events?: unknown;
   create(): unknown;
   update(frame: {
     readonly state: unknown;
     readonly input: InputFrame<string>;
     readonly transition: SceneTransitionController<string>;
+    readonly events: { emit(name: string, payload: unknown): void };
     readonly tick: number;
     readonly sceneTick: number;
     readonly deltaSeconds: number;
@@ -50,6 +100,11 @@ interface ActiveScene {
   readonly definition: ErasedScene;
   state: unknown;
   sceneTick: number;
+  /**
+   * Set before user cleanup runs: a throwing disposer never runs again —
+   * not on retry, not on session disposal — for this scene instance.
+   */
+  disposalAttempted: boolean;
 }
 
 type TransitionIntent =
@@ -84,9 +139,10 @@ export function createGameSession<
   const TScenes extends SceneMap,
   const TInput extends InputMap,
   const TInitialScene extends keyof TScenes,
+  const TEventDefs extends Record<string, GameEventDescriptor<unknown>> = Record<string, never>,
 >(
-  definition: GameDefinition<TScenes, TInput, TInitialScene>,
-): GameSession<TScenes, TInput> {
+  definition: GameDefinition<TScenes, TInput, TInitialScene, AssetGroupMap, TEventDefs>,
+): GameSession<TScenes, TInput, TEventDefs> {
   return createGameSessionWithDriver(definition, {
     frameDriver: createAnimationFrameDriver(),
   });
@@ -97,10 +153,11 @@ export function createGameSessionWithDriver<
   const TScenes extends SceneMap,
   const TInput extends InputMap,
   const TInitialScene extends keyof TScenes,
+  const TEventDefs extends Record<string, GameEventDescriptor<unknown>> = Record<string, never>,
 >(
-  definition: GameDefinition<TScenes, TInput, TInitialScene>,
+  definition: GameDefinition<TScenes, TInput, TInitialScene, AssetGroupMap, TEventDefs>,
   options: SessionOptions,
-): GameSession<TScenes, TInput> {
+): GameSession<TScenes, TInput, TEventDefs> {
   const fixedStepMs = options.fixedStepMs ?? DEFAULT_FIXED_STEP_MS;
   const maxCatchUpSteps = options.maxCatchUpSteps ?? DEFAULT_MAX_CATCH_UP_STEPS;
   const maxFrameDeltaMs = options.maxFrameDeltaMs ?? fixedStepMs * DEFAULT_MAX_CATCH_UP_STEPS;
@@ -119,6 +176,37 @@ export function createGameSessionWithDriver<
     throw new RangeError('maxFrameDeltaMs must be a finite positive number');
   }
 
+  // T13: event definitions and per-scene emit declarations.
+  const eventDefs = (definition as unknown as { events?: Record<string, GameEventDescriptor<unknown>> }).events;
+  const hasEvents = eventDefs !== undefined && eventDefs !== null;
+  const allowedEventNames = hasEvents ? new Set(Object.keys(eventDefs!)) : new Set<string>();
+  const allowedEmitsByScene = new Map<string, Set<string>>();
+  // Validate per-scene emits are declared events and that the scene's `events` reference matches the game's.
+  for (const [name, scene] of Object.entries(definition.scenes)) {
+    const erased = scene as unknown as ErasedScene;
+    const emits = erased.emits ?? [];
+    for (const ev of emits) {
+      if (!allowedEventNames.has(ev)) {
+        throw new Error(`Scene "${name}" declares unknown event "${ev}"`);
+      }
+    }
+    allowedEmitsByScene.set(name, new Set(emits as string[]));
+    // Runtime identity check for the branded event definitions.
+    if (erased.events !== undefined) {
+      if (!hasEvents) {
+        throw new Error(`Scene "${name}" is bound to events but the game has no events map`);
+      }
+      if (erased.events !== eventDefs) {
+        throw new Error(
+          `Scene "${name}" is bound to a different events object than the game. Pass the same defineGameEvents() result to both defineScene({ events }) and defineGame({ events }).`,
+        );
+      }
+    } else if (emits.length > 0) {
+      throw new Error(
+        `Scene "${name}" declares emits but is not bound to the game's events. Pass \`events\` to defineScene.`,
+      );
+    }
+  }
   const erasedSceneMap: Record<string, ErasedScene> = {};
   for (const [name, scene] of Object.entries(definition.scenes)) {
     const erased = scene as unknown as ErasedScene;
@@ -144,9 +232,16 @@ export function createGameSessionWithDriver<
   const initialState = freezeObject(initialDefinition.create());
   let initialSnapshot: DeepReadonly<unknown>;
   try {
-    initialSnapshot = deepFreeze(initialDefinition.snapshot({ state: initialState }));
+    initialSnapshot = deepFreeze(initialDefinition.snapshot({ state: initialState }), {
+      scene: initialSceneName,
+    });
   } catch (error) {
-    initialDefinition.dispose?.(initialState);
+    // GS-SCENE-02: the cleanup failure must not replace the snapshot
+    // failure — compose losslessly in a stable order instead.
+    const cleanupFailure = captureFailure(() => initialDefinition.dispose?.(initialState));
+    if (cleanupFailure.failed) {
+      throw composeFailures(error, cleanupFailure.value);
+    }
     throw error;
   }
 
@@ -155,6 +250,7 @@ export function createGameSessionWithDriver<
     definition: initialDefinition,
     state: initialState,
     sceneTick: 0,
+    disposalAttempted: false,
   };
   let sceneName: string = initialSceneName;
   let currentSnapshot: DeepReadonly<unknown> = initialSnapshot;
@@ -167,6 +263,12 @@ export function createGameSessionWithDriver<
   let accumulatorMs = 0;
   let tick = 0;
   let pendingTransition: TransitionIntent | undefined;
+  /**
+   * Set when an outgoing scene disposal throws: the retained scene is
+   * explicitly non-resumable — `start()` refuses to update it until a
+   * transition or restart replaces it. Cleared on every successful install.
+   */
+  let sceneFaulted = false;
   let hardCutPending = false;
   let publishedThisCallback = false;
   let updateInProgress = false;
@@ -182,6 +284,129 @@ export function createGameSessionWithDriver<
     stepMs: fixedStepMs,
   }) as unknown as CommitFrame<TScenes>;
   const listeners = new Set<(frame: CommitFrame<TScenes>) => void>();
+  const statusListeners = new Set<(status: GameSessionStatus) => void>();
+  let deliveringStatus = false;
+  const queuedStatuses: GameSessionStatus[] = [];
+  let releaseStatusListeners = false;
+
+  // T13: per-session event listeners.
+  const eventListeners = new Map<string, Set<(event: AnyGameEventEnvelope) => void | Promise<void>>>();
+
+  // Centralized, non-recursive error sink for game event listeners.
+  // A failing reporter must not pause the session or escape into the fixed-step loop.
+  const reportGameEventListenerError = (name: string, error: unknown): void => {
+    try {
+      console.error(`Game event listener for "${name}" threw:`, error);
+    } catch {
+      // Swallow reporter failures — the session must remain running and siblings must still run.
+    }
+  };
+
+  const deliverEvents = (envelopes: readonly AnyGameEventEnvelope[]): void => {
+    // Snapshot per tick: a listener added during this tick's delivery receives
+    // only later ticks, and a removal prevents only future ticks.
+    const snapshots = new Map<string, readonly ((event: AnyGameEventEnvelope) => void | Promise<void>)[]>();
+    for (const env of envelopes) {
+      if (!snapshots.has(env.name)) {
+        const set = eventListeners.get(env.name);
+        snapshots.set(env.name, set ? [...set] : []);
+      }
+    }
+    for (const envelope of envelopes) {
+      const snapshot = snapshots.get(envelope.name) ?? [];
+      for (const listener of snapshot) {
+        let result: unknown;
+        try {
+          result = listener(envelope);
+        } catch (error) {
+          reportGameEventListenerError(envelope.name, error);
+          continue;
+        }
+        if (result !== null && typeof result === 'object' && typeof (result as Promise<unknown>).then === 'function') {
+          (result as Promise<unknown>).catch((error) => {
+            reportGameEventListenerError(envelope.name, error);
+          });
+        }
+      }
+    }
+  };
+
+  const NO_EVENT_EMITTER = Object.freeze({
+    emit() {
+      throw new GameEventError('This game has no events or this scene does not emit any events');
+    },
+  }) as { emit(name: string, payload: unknown): void };
+
+  // Deliver one transition pass to a snapshot. A throwing listener never
+  // aborts the pass: the remaining snapshot listeners still run, and the
+  // first failure is rethrown once every queued transition has been
+  // delivered (the transition itself is already authoritative).
+  const deliverStatusPass = (current: GameSessionStatus): FailureRecord => {
+    let firstFailure: FailureRecord = NO_FAILURE;
+    for (const listener of [...statusListeners]) {
+      try {
+        listener(current);
+      } catch (error) {
+        if (!firstFailure.failed) {
+          firstFailure = { failed: true, value: error };
+        }
+      }
+    }
+    return firstFailure;
+  };
+
+  const notifyStatus = (): void => {
+    if (deliveringStatus) {
+      // Re-entrant transition from inside a listener: queue it so every
+      // listener observes complete states, never a half-applied transition.
+      queuedStatuses.push(status);
+      return;
+    }
+    deliveringStatus = true;
+    let firstFailure: FailureRecord = NO_FAILURE;
+    try {
+      const passFailure = deliverStatusPass(status);
+      if (!firstFailure.failed) {
+        firstFailure = passFailure;
+      }
+      while (queuedStatuses.length > 0) {
+        const queued = queuedStatuses.shift() as GameSessionStatus;
+        const queuedFailure = deliverStatusPass(queued);
+        if (!firstFailure.failed) {
+          firstFailure = queuedFailure;
+        }
+      }
+    } finally {
+      deliveringStatus = false;
+      if (releaseStatusListeners) {
+        releaseStatusListeners = false;
+        statusListeners.clear();
+        diagnostics?.onStatusListenerCount?.(statusListeners.size);
+      }
+    }
+    throwFailure(firstFailure);
+  };
+
+  // Status becomes authoritative only after the command's scheduling and
+  // input side effects are safe; listeners then observe the committed value.
+  const setStatus = (next: GameSessionStatus): void => {
+    if (status === next) {
+      return;
+    }
+    status = next;
+    notifyStatus();
+  };
+
+  // Error-path pause: complete the transition and notify, but never let a
+  // status-listener failure mask the original error that caused the pause.
+  const pauseAndRethrow = (original: unknown): never => {
+    try {
+      pauseInternal();
+    } catch {
+      // The original error is the actionable one; listeners were notified.
+    }
+    throw original;
+  };
 
   const assertLive = () => {
     if (status === 'disposed') {
@@ -189,7 +414,9 @@ export function createGameSessionWithDriver<
     }
   };
   const isDisposed = () => status === 'disposed';
-  const inputBuffer = createInputBuffer(definition.input, assertLive);
+  // T10.4: gameplay input is rejected at the shared boundary while paused
+  // (before the queue and before the accepted-input diagnostics).
+  const inputBuffer = createInputBuffer(definition.input, assertLive, () => status === 'paused');
 
   // Simulation commits are the only presentation updates (T5): a commit
   // happens on the initial baseline, after every presentation callback that
@@ -226,7 +453,6 @@ export function createGameSessionWithDriver<
     if (status !== 'running') {
       return;
     }
-    status = 'paused';
     generation += 1;
     if (frameHandle !== undefined) {
       options.frameDriver.cancelFrame(frameHandle);
@@ -235,15 +461,28 @@ export function createGameSessionWithDriver<
     previousTimestampMs = undefined;
     accumulatorMs = 0;
     inputBuffer.reset();
+    setStatus('paused');
   };
 
   const commitOrPause = () => {
     try {
       commit();
     } catch (error) {
-      pauseInternal();
-      throw error;
+      pauseAndRethrow(error);
+    }
+  };
+
+  /**
+   * Dispose one scene instance exactly once. The attempt flag is set before
+   * user cleanup runs, so a throwing disposer is never retried for this
+   * instance — by transition retries or by session disposal.
+   */
+  const disposeSceneInstance = (scene: ActiveScene, state: unknown): void => {
+    if (scene.disposalAttempted) {
+      return;
     }
+    scene.disposalAttempted = true;
+    scene.definition.dispose?.(state);
   };
 
   /**
@@ -277,7 +516,9 @@ export function createGameSessionWithDriver<
     try {
       targetState = freezeObject(targetDefinition.create());
       targetCreated = true;
-      targetSnapshot = deepFreeze(targetDefinition.snapshot({ state: targetState }));
+      targetSnapshot = deepFreeze(targetDefinition.snapshot({ state: targetState }), {
+        scene: targetName,
+      });
     } catch (error) {
       if (targetCreated) {
         try {
@@ -290,15 +531,17 @@ export function createGameSessionWithDriver<
     }
 
     try {
-      activeScene.definition.dispose?.(outgoingFinalState);
+      disposeSceneInstance(activeScene, outgoingFinalState);
     } catch (error) {
-      // The outgoing scene's dispose already ran (possibly partially) and is
-      // not retried; the old scene remains active with that honest caveat.
+      // The outgoing scene's dispose already ran (possibly partially) and
+      // is never retried; the old scene remains active but explicitly
+      // faulted. The prepared target is still cleaned up, and a failing
+      // target cleanup composes losslessly with the outgoing failure.
+      sceneFaulted = true;
       if (targetCreated) {
-        try {
-          targetDefinition.dispose?.(targetState);
-        } catch {
-          // Best effort.
+        const targetFailure = captureFailure(() => targetDefinition.dispose?.(targetState));
+        if (targetFailure.failed) {
+          throw composeFailures(error, targetFailure.value);
         }
       }
       throw error;
@@ -312,7 +555,9 @@ export function createGameSessionWithDriver<
       definition: targetDefinition,
       state: targetState,
       sceneTick: 0,
+      disposalAttempted: false,
     };
+    sceneFaulted = false;
     sceneName = targetName;
     currentSnapshot = targetSnapshot;
     previousSnapshot = targetSnapshot;
@@ -383,6 +628,31 @@ export function createGameSessionWithDriver<
     });
   };
 
+  // One scheduler-failure policy for successor scheduling (GS-SESSION-02).
+  // The initial `start()` path keeps its own restore-previous-status policy
+  // because no running state was ever published there. On failure: clear the
+  // handle, invalidate the generation so late callbacks are no-ops,
+  // neutralize input via the pause path, and publish paused while preserving
+  // the scheduling error — a throwing status listener composes with it
+  // instead of masking it. Never retries automatically.
+  const failScheduling = (error: unknown): never => {
+    frameHandle = undefined;
+    try {
+      pauseInternal();
+    } catch (statusError) {
+      throw composeFailures(error, statusError);
+    }
+    throw error;
+  };
+
+  const scheduleSuccessor = (activeGeneration: number): void => {
+    try {
+      schedule(activeGeneration);
+    } catch (error) {
+      failScheduling(error);
+    }
+  };
+
   const schedule = (activeGeneration: number) => {
     frameHandle = options.frameDriver.requestFrame((timestampMs) => {
       if (status !== 'running' || generation !== activeGeneration) {
@@ -394,16 +664,17 @@ export function createGameSessionWithDriver<
         diagnostics.onDisplayCallback();
       }
 
-      // A pending external transition commits at the next fixed-step boundary
-      // without advancing simulation tick/time.
+      // A pending external transition commits at the next frame-driver
+      // callback — a zero-step callback may carry it — without advancing
+      // simulation tick/time. The target scene first updates at the next
+      // due fixed step; accumulated timing debt is preserved.
       if (pendingTransition !== undefined) {
         const pending = pendingTransition;
         pendingTransition = undefined;
         try {
           commitTransition(pending, activeScene.state, undefined);
         } catch (error) {
-          pauseInternal();
-          throw error;
+          pauseAndRethrow(error);
         }
         commitOrPause();
         if (status !== 'running' || generation !== activeGeneration) {
@@ -417,7 +688,7 @@ export function createGameSessionWithDriver<
           commitOrPause();
         }
         if (status === 'running' && generation === activeGeneration) {
-          schedule(activeGeneration);
+          scheduleSuccessor(activeGeneration);
         }
         return;
       }
@@ -439,6 +710,42 @@ export function createGameSessionWithDriver<
           stepsRan = true;
           const nextTick = tick + 1;
           const nextSceneTick = activeScene.sceneTick + 1;
+          const sceneNameForTick = activeScene.name;
+          const allowedEmits = allowedEmitsByScene.get(sceneNameForTick) ?? new Set<string>();
+
+          // T13: per-tick transactional emitter.
+          let stagedThisTick: AnyGameEventEnvelope[] = [];
+          let ordinal = 0;
+          let emitterInvalidated = false;
+          const emitter: { emit(name: string, payload: unknown): void } = hasEvents
+            ? {
+                emit(name: string, payload: unknown) {
+                  if (emitterInvalidated) {
+                    throw new GameEventError('Game event emitter is only valid during its owning scene update');
+                  }
+                  if (!allowedEventNames.has(name)) {
+                    throw new GameEventError(`Event "${name}" is not declared by this game`);
+                  }
+                  if (!allowedEmits.has(name)) {
+                    throw new GameEventError(`Scene "${sceneNameForTick}" cannot emit event "${name}" (missing from its emits list)`);
+                  }
+                  const cloned = cloneAndValidatePayload(payload, name, 'payload');
+                  const envelope = Object.freeze({
+                    name,
+                    payload: cloned,
+                    tick: nextTick,
+                    scene: sceneNameForTick,
+                    sceneTick: nextSceneTick,
+                    ordinal: ordinal++,
+                  }) as AnyGameEventEnvelope;
+                  stagedThisTick.push(envelope);
+                },
+              }
+            : (NO_EVENT_EMITTER as { emit(name: string, payload: unknown): void });
+          if (hasEvents) {
+            Object.freeze(emitter);
+          }
+
           const sampleStart = diagnostics === undefined ? 0 : now();
           const input = inputBuffer.sample();
           if (diagnostics !== undefined) {
@@ -448,18 +755,31 @@ export function createGameSessionWithDriver<
           activeUpdateScope = scope;
           updateInProgress = true;
           const updateStart = diagnostics === undefined ? 0 : now();
-          const nextState = freezeObject(
-            activeScene.definition.update({
-              state: activeScene.state,
-              input,
-              transition: makeTransitionController(scope),
-              tick: nextTick,
-              sceneTick: nextSceneTick,
-              deltaSeconds: fixedStepMs / 1000,
-              elapsedSeconds: (nextTick * fixedStepMs) / 1000,
-              sceneElapsedSeconds: (nextSceneTick * fixedStepMs) / 1000,
-            }),
-          );
+          let nextState: unknown;
+          try {
+            nextState = freezeObject(
+              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+              (activeScene.definition.update as any)({
+                state: activeScene.state,
+                input,
+                transition: makeTransitionController(scope),
+                events: emitter,
+                tick: nextTick,
+                sceneTick: nextSceneTick,
+                deltaSeconds: fixedStepMs / 1000,
+                elapsedSeconds: (nextTick * fixedStepMs) / 1000,
+                sceneElapsedSeconds: (nextSceneTick * fixedStepMs) / 1000,
+              }),
+            );
+          } catch (error) {
+            // Update failed: discard staged events, invalidate emitter.
+            stagedThisTick = [];
+            emitterInvalidated = true;
+            activeUpdateScope = undefined;
+            updateInProgress = false;
+            throw error;
+          }
+          emitterInvalidated = true;
           activeUpdateScope = undefined;
           updateInProgress = false;
           if (diagnostics !== undefined) {
@@ -473,7 +793,17 @@ export function createGameSessionWithDriver<
             // A transition requested during update commits after this update
             // completes successfully. The update consumed one fixed step; the
             // hard-cut frame publishes at the end of this presentation callback.
-            commitTransition(intent, nextState, nextTick, true);
+            try {
+              commitTransition(intent, nextState, nextTick, true);
+            } catch (error) {
+              // Transition preparation/disposal failed: discard staged events.
+              stagedThisTick = [];
+              throw error;
+            }
+            // Successful transition tick: staged events commit with source tick/scene.
+            if (stagedThisTick.length > 0) {
+              deliverEvents(stagedThisTick);
+            }
             accumulatorMs = Math.max(0, accumulatorMs - fixedStepMs);
             // F4: the transition consumed one fixed step; report it as such
             // and never as a zero-step callback (zero-step fires only when
@@ -484,12 +814,24 @@ export function createGameSessionWithDriver<
             break;
           }
           const snapshotStart = diagnostics === undefined ? 0 : now();
-          const rawSnapshot = activeScene.definition.snapshot({ state: nextState });
+          let rawSnapshot: unknown;
+          try {
+            rawSnapshot = activeScene.definition.snapshot({ state: nextState });
+          } catch (error) {
+            stagedThisTick = [];
+            throw error;
+          }
           if (diagnostics !== undefined) {
             diagnostics.onSnapshot(now() - snapshotStart);
           }
           const freezeStart = diagnostics === undefined ? 0 : now();
-          const nextSnapshot = deepFreeze(rawSnapshot);
+          let nextSnapshot: DeepReadonly<unknown>;
+          try {
+            nextSnapshot = deepFreeze(rawSnapshot, { scene: sceneNameForTick, tick: nextTick });
+          } catch (error) {
+            stagedThisTick = [];
+            throw error;
+          }
           if (diagnostics !== undefined) {
             diagnostics.onDeepFreeze(now() - freezeStart);
           }
@@ -501,6 +843,10 @@ export function createGameSessionWithDriver<
           previousSnapshot = currentSnapshot;
           currentSnapshot = nextSnapshot;
           tick = nextTick;
+          // Successful tick: deliver staged events in tick order, then emission order.
+          if (stagedThisTick.length > 0) {
+            deliverEvents(stagedThisTick);
+          }
           accumulatorMs = Math.max(0, accumulatorMs - fixedStepMs);
           catchUpSteps += 1;
           if (diagnostics !== undefined) {
@@ -513,8 +859,7 @@ export function createGameSessionWithDriver<
       } catch (error) {
         activeUpdateScope = undefined;
         updateInProgress = false;
-        pauseInternal();
-        throw error;
+        pauseAndRethrow(error);
       }
 
       if (catchUpSteps === maxCatchUpSteps && accumulatorMs >= fixedStepMs) {
@@ -539,12 +884,12 @@ export function createGameSessionWithDriver<
         commitOrPause();
       }
       if (status === 'running' && generation === activeGeneration) {
-        schedule(activeGeneration);
+        scheduleSuccessor(activeGeneration);
       }
     });
   };
 
-  const session: GameSession<TScenes, TInput> = {
+  const session: GameSession<TScenes, TInput, TEventDefs> = {
     get status() {
       return status;
     },
@@ -558,21 +903,44 @@ export function createGameSessionWithDriver<
       if (status === 'running') {
         return;
       }
-      status = 'running';
+      if (sceneFaulted) {
+        throw new GameSessionLifecycleError(
+          'The active scene failed disposal and is explicitly non-resumable: ' +
+            'replace it with setScene() or restartScene() before start(), or dispose the session.',
+        );
+      }
+      const previous = status;
       previousTimestampMs = undefined;
       accumulatorMs = 0;
       const activeGeneration = ++generation;
-      schedule(activeGeneration);
+      try {
+        schedule(activeGeneration);
+      } catch (error) {
+        // Do not publish `running` when scheduling could not be established.
+        status = previous;
+        throw error;
+      }
+      setStatus('running');
     },
     pause() {
       assertLive();
-      pauseInternal();
-      if (pendingTransition !== undefined) {
-        const pending = pendingTransition;
-        pendingTransition = undefined;
-        commitTransition(pending, activeScene.state, undefined);
-        commitOrPause();
+      const pauseFailure = captureFailure(() => pauseInternal());
+      // The command must complete: a pending external transition is resolved
+      // at the pause boundary even when a status listener threw, so a later
+      // start() can never commit a stale transition on an unexpected frame.
+      const transitionFailure = captureFailure(() => {
+        if (pendingTransition !== undefined) {
+          const pending = pendingTransition;
+          pendingTransition = undefined;
+          commitTransition(pending, activeScene.state, undefined);
+          commitOrPause();
+        }
+      });
+      if (pauseFailure.failed && transitionFailure.failed) {
+        throw composeFailures(pauseFailure.value, transitionFailure.value);
       }
+      throwFailure(pauseFailure);
+      throwFailure(transitionFailure);
     },
     setScene(name: keyof TScenes) {
       assertLive();
@@ -617,14 +985,29 @@ export function createGameSessionWithDriver<
         options.frameDriver.cancelFrame(frameHandle);
         frameHandle = undefined;
       }
-      status = 'disposed';
       generation += 1;
       previousTimestampMs = undefined;
       accumulatorMs = 0;
       pendingTransition = undefined;
       inputBuffer.reset();
-      listeners.clear();
-      activeScene.definition.dispose?.(activeScene.state);
+      eventListeners.clear();
+      // Terminal cleanup is unconditional: `disposed` is delivered to the
+      // full listener snapshot (including the re-entrant queued pass), then
+      // every listener and the scene are released exactly once even when a
+      // status listener throws. The release flag is set BEFORE the
+      // notification so notifyStatus's finally performs the clear; for the
+      // re-entrant path the clear happens after the queued pass drains.
+      releaseStatusListeners = true;
+      const notificationFailure = captureFailure(() => setStatus('disposed'));
+      const cleanupFailure = captureFailure(() => {
+        listeners.clear();
+        disposeSceneInstance(activeScene, activeScene.state);
+      });
+      if (notificationFailure.failed && cleanupFailure.failed) {
+        throw composeFailures(notificationFailure.value, cleanupFailure.value);
+      }
+      throwFailure(notificationFailure);
+      throwFailure(cleanupFailure);
     },
     getRenderFrame() {
       const alpha = commitFrame.hardCut
@@ -646,6 +1029,50 @@ export function createGameSessionWithDriver<
         },
       });
     },
+    addStatusListener(listener) {
+      assertLive();
+      statusListeners.add(listener);
+      diagnostics?.onStatusListenerCount?.(statusListeners.size);
+      let removed = false;
+      return Object.freeze({
+        remove() {
+          if (removed) {
+            return;
+          }
+          removed = true;
+          statusListeners.delete(listener);
+          diagnostics?.onStatusListenerCount?.(statusListeners.size);
+        },
+      });
+    },
+    addGameEventListener: ((name: string, listener: (event: AnyGameEventEnvelope) => void | Promise<void>) => {
+      assertLive();
+      if (!hasEvents || !allowedEventNames.has(name)) {
+        throw new GameEventError(`Event "${String(name)}" is not declared by this game`);
+      }
+      let set = eventListeners.get(name);
+      if (set === undefined) {
+        set = new Set();
+        eventListeners.set(name, set);
+      }
+      set.add(listener as (event: AnyGameEventEnvelope) => void | Promise<void>);
+      let removed = false;
+      return Object.freeze({
+        remove() {
+          if (removed) {
+            return;
+          }
+          removed = true;
+          const existing = eventListeners.get(name);
+          if (existing) {
+            existing.delete(listener as (event: AnyGameEventEnvelope) => void | Promise<void>);
+            if (existing.size === 0) {
+              eventListeners.delete(name);
+            }
+          }
+        },
+      });
+    }) as unknown as GameSession<TScenes, TInput, TEventDefs>['addGameEventListener'],
   };
 
   return Object.freeze(session);