rn-gamekit 0.1.0 → 0.2.1

package/src/core/session/deepFreeze.ts

@@ -22,6 +22,39 @@
 
 import type { DeepReadonly } from './types';
 
+/**
+ * Supported snapshot domain (GS-SCENE-03): plain records
+ * (`Object.prototype` or `null` prototype), arrays, and scalar values.
+ * Everything else — functions, symbols, bigints, and class instances
+ * (Map, Set, Date, typed arrays, custom classes, …) — is rejected at the
+ * publication boundary because freezing cannot secure it (`Object.freeze`
+ * on a Map does not freeze its entries; a frozen function stays callable).
+ */
+export class SnapshotDomainError extends Error {
+  /** Dot/bracket path from the snapshot root to the offending value. */
+  readonly path: string;
+  /** The scene whose snapshot was rejected, when the session supplied it. */
+  readonly scene?: string;
+  constructor(path: string, detail: string, scene?: string) {
+    super(
+      `Unsupported snapshot value at ${path}: ${detail}${
+        scene === undefined ? '' : ` (scene "${scene}")`
+      }. Snapshots must contain only plain records, arrays, and scalar values.`,
+    );
+    this.name = 'SnapshotDomainError';
+    this.path = path;
+    if (scene !== undefined) {
+      this.scene = scene;
+    }
+  }
+}
+
+/** Context the session attaches so rejections name the offending scene. */
+export interface SnapshotFreezeContext {
+  readonly scene?: string;
+  readonly tick?: number;
+}
+
 /** Whether a string is a canonical array index (`0 <= i < 2^32 - 1`). */
 /** Decimal digit count of a non-negative integer (0 <= value < 1e11). */
 function digitLength(value: number): number {
@@ -80,19 +113,77 @@ function isArrayIndexKey(key: string): boolean {
   return value <= 0xffffffff - 1;
 }
 
+/** Whether a value is a plain record (`Object.prototype` or `null` prototype). */
+function isPlainRecord(node: object): boolean {
+  const prototype = Object.getPrototypeOf(node);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/** Name an unsupported value for an actionable rejection message. */
+function describeUnsupported(node: unknown): string {
+  if (typeof node === 'function') {
+    return 'functions are not part of the snapshot domain';
+  }
+  if (typeof node === 'symbol') {
+    return 'symbols are not part of the snapshot domain';
+  }
+  if (typeof node === 'bigint') {
+    return 'bigints are not part of the snapshot domain';
+  }
+  const name =
+    typeof node === 'object' && node !== null
+      ? (node as { constructor?: { name?: unknown } }).constructor?.name
+      : undefined;
+  const label = typeof name === 'string' && name !== '' ? `${name} instances` : 'class instances';
+  return `${label} are not part of the snapshot domain (only plain records and arrays are supported)`;
+}
+
+/** Format a key-path segment stack as `a.b[0]` (root renders `<root>`). */
+function formatPath(path: readonly (string | number | symbol)[]): string {
+  if (path.length === 0) {
+    return '<root>';
+  }
+  let out = '';
+  for (const segment of path) {
+    if (typeof segment === 'number') {
+      out += `[${segment}]`;
+    } else if (typeof segment === 'symbol') {
+      out += `[${String(segment)}]`;
+    } else if (out === '') {
+      out = segment;
+    } else {
+      out += `.${segment}`;
+    }
+  }
+  return out;
+}
+
 export interface DeepFreezer {
-  <T>(value: T): DeepReadonly<T>;
+  <T>(value: T, context?: SnapshotFreezeContext): DeepReadonly<T>;
 }
 
 export function createDeepFreeze(): DeepFreezer {  const trusted = new WeakSet<object>();
 
-  return function deepFreeze<T>(value: T): DeepReadonly<T> {
+  return function deepFreeze<T>(value: T, context?: SnapshotFreezeContext): DeepReadonly<T> {
+    // Key path from the snapshot root, maintained as a segment stack and
+    // formatted only when a rejection needs it. try/finally is unnecessary:
+    // a throw abandons the traversal, and the stack is per call.
+    const path: (string | number | symbol)[] = [];
+    const reject = (node: unknown): never => {
+      throw new SnapshotDomainError(formatPath(path), describeUnsupported(node), context?.scene);
+    };
     if (typeof value !== 'object' || value === null) {
+      if (typeof value === 'function' || typeof value === 'symbol' || typeof value === 'bigint') {
+        reject(value);
+      }
       return value as DeepReadonly<T>;
     }
     const visiting = new WeakSet<object>();
     const freeze = (node: unknown): void => {
       if (typeof node !== 'object' || node === null) {
+        if (typeof node === 'function' || typeof node === 'symbol' || typeof node === 'bigint') {
+          reject(node);
+        }
         return;
       }
       if (trusted.has(node) || visiting.has(node)) {
@@ -102,7 +193,9 @@ export function createDeepFreeze(): DeepFreezer {  const trusted = new WeakSet<o
       if (Array.isArray(node)) {
         // Index fast path: avoids materialising an index-key array per array.
         for (let index = 0; index < node.length; index += 1) {
+          path.push(index);
           freeze(node[index]);
+          path.pop();
         }
         // F5: legal JavaScript arrays may also carry values on non-index
         // string keys and symbol keys. Only own keys are reachable snapshot
@@ -134,20 +227,28 @@ export function createDeepFreeze(): DeepFreezer {  const trusted = new WeakSet<o
             continue;
           }
           if (!isArrayIndexKey(name)) {
+            path.push(name);
             freeze((node as unknown as Record<PropertyKey, unknown>)[name]);
+            path.pop();
           }
         }
         const symbols = Object.getOwnPropertySymbols(node);
         for (let index = 0; index < symbols.length; index += 1) {
           const symbol = symbols[index];
           if (symbol !== undefined) {
+            path.push(symbol);
             freeze((node as unknown as Record<PropertyKey, unknown>)[symbol]);
+            path.pop();
           }
         }
-      } else {
+      } else if (isPlainRecord(node)) {
         for (const key of Reflect.ownKeys(node)) {
+          path.push(key);
           freeze((node as Record<PropertyKey, unknown>)[key]);
+          path.pop();
         }
+      } else {
+        reject(node);
       }
       Object.freeze(node);
       trusted.add(node);

package/src/core/session/diagnostics.ts

@@ -32,4 +32,6 @@ export interface SessionDiagnostics {
   onCommitNotification(): void;
   /** Listener count at publish time. */
   onListenerCount(count: number): void;
+  /** Status-listener count after registration or removal (T10 control plane). */
+  onStatusListenerCount?(count: number): void;
 }

package/src/core/session/types.ts

@@ -1,4 +1,5 @@
 import type { InputMap, SceneMap } from '../../definition/types';
+import type { GameEventDescriptor, GameEventEnvelope, InferGameEventMap } from '../../events/types';
 import type { SceneSnapshot } from '../../scene/types';
 import type { Viewport } from '../../viewport2d/types';
 import type { InputController } from '../input/types';
@@ -15,6 +16,29 @@ export type DeepReadonly<T> = T extends (...arguments_: never[]) => unknown
 /** Lifecycle states of a headless game session. */
 export type GameSessionStatus = 'idle' | 'running' | 'paused' | 'disposed';
 
+/**
+ * Minimal read-only lifecycle surface for presentation layers (T20.3).
+ *
+ * Exposes exactly what a renderer-side consumer needs to follow its owning
+ * session — the current status and a way to observe transitions — and
+ * nothing it must not have: no `start`, `pause`, `press`, `setScene`, event
+ * subscription, or other session internals. `GameView` owns one source per
+ * session and supplies it to its renderer subtree; haptics and particle
+ * presentation consume it instead of casting to private session methods or
+ * reaching for module-global coordinators.
+ */
+export interface GameLifecycleSource {
+  /** The owning session's current lifecycle status. */
+  getStatus(): GameSessionStatus;
+  /**
+   * Observe lifecycle transitions. Returns a detach function. Subscribing
+   * to a disposed session returns a no-op detach: the terminal notification
+   * was already delivered, and `addStatusListener` follows the
+   * disposed-error policy for new subscribers.
+   */
+  subscribe(listener: (status: GameSessionStatus) => void): () => void;
+}
+
 /** One renderer-neutral simulation commit produced by a game session. */
 export interface CommitFrameBase<TSnapshot> {
   /** Snapshot immediately before the latest simulation update. */
@@ -60,7 +84,11 @@ export interface GameSubscription {
 }
 
 /** A closure-backed, headless running instance of one game definition. */
-export interface GameSession<TScenes extends SceneMap = SceneMap, TInput extends InputMap = InputMap> {
+export interface GameSession<
+  TScenes extends SceneMap = SceneMap,
+  TInput extends InputMap = InputMap,
+  TEventDefs extends Record<string, GameEventDescriptor<unknown>> = Record<string, never>,
+> {
   /** Current lifecycle status. */
   readonly status: GameSessionStatus;
   /** The active scene name, updated by transitions and restarts. */
@@ -73,12 +101,28 @@ export interface GameSession<TScenes extends SceneMap = SceneMap, TInput extends
   start(): void;
   /** Pause simulation and discard suspended wall time. */
   pause(): void;
+  /**
+   * Observe lifecycle transitions at control frequency.
+   *
+   * The listener receives each actual status transition after it becomes
+   * authoritative (`idle`, `running`, `paused`, `disposed`); idempotent
+   * commands emit nothing, and no initial value is emitted on subscribe —
+   * read `status` for the snapshot. `disposed` is delivered exactly once
+   * before listeners are released. Listeners are called from a snapshot and
+   * a listener that issues another lifecycle command observes complete
+   * states; a throwing listener does not abort delivery, and the first
+   * failure is rethrown from the command after the pass completes. Status
+   * notifications are not render commits.
+   */
+  addStatusListener(listener: (status: GameSessionStatus) => void): GameSubscription;
   /**
    * Transition to a declared scene.
    *
-   * While running, the transition commits at the next fixed-step boundary.
-   * While idle or paused, it commits synchronously and publishes the new
-   * frame. Setting the current scene is an idempotent no-op.
+   * While running, the transition commits at the next frame-driver callback
+   * — even when no fixed step is due — without advancing simulation tick or
+   * time. The target scene first updates at the next due fixed step. While
+   * idle or paused, it commits synchronously and publishes the new frame.
+   * Setting the current scene is an idempotent no-op.
    */
   setScene(name: keyof TScenes): void;
   /** Recreate the active scene with fresh state. */
@@ -93,10 +137,39 @@ export interface GameSession<TScenes extends SceneMap = SceneMap, TInput extends
    * accumulated timing fraction at call time and is only meaningful for
    * headless inspection. Rendering uses the UI-owned alpha clock; the
    * envelope fields never change between commits.
+   *
+   * Event-time authority (GS-EVENT-02): this frame is the most recently
+   * PUBLISHED presentation frame, which can lag the authoritative tick
+   * when several simulation ticks run in one driver callback. Inside a
+   * game-event listener, the envelope (tick, scene, ordinal, payload) is
+   * the authority for that event — never re-read this frame to place the
+   * event. Put the data an effect needs into its small payload.
    */
   getRenderFrame(): GameRenderFrame<TScenes>;
   /** Observe simulation commits at commit frequency (never per display frame). */
   addCommitListener(listener: (frame: CommitFrame<TScenes>) => void): GameSubscription;
+  /**
+   * Observe deterministic game events after they commit (T13).
+   *
+   * Each listener receives committed envelopes for the subscribed name in
+   * deterministic `(tick, ordinal)` order. Delivery happens after the
+   * source tick's authoritative state commits and never during the update
+   * itself. Listeners run from a per-tick snapshot taken before the
+   * tick's first delivery (GS-EVENT-01): a listener added during delivery
+   * receives only later ticks, and a removal prevents only future ticks —
+   * neither affects the envelopes already staged for the running tick.
+   * Lifecycle calls during delivery (pause, setScene, dispose) take
+   * effect after the staged batch completes: every snapshotted listener
+   * still runs exactly once for the tick. Removing a listener is
+   * idempotent. A throwing listener does not suppress siblings or alter
+   * simulation; the error is reported via a visible non-recursive sink
+   * (`console.error`). Simulation never awaits an async effect started
+   * by a listener.
+   */
+  addGameEventListener<TName extends keyof InferGameEventMap<TEventDefs> & string>(
+    name: TName,
+    listener: (event: GameEventEnvelope<TName, InferGameEventMap<TEventDefs>[TName]>) => void | Promise<void>,
+  ): GameSubscription;
 }
 
 /** Error thrown when live work is requested from a disposed session. */

package/src/definition/defineGame.ts

@@ -1,4 +1,5 @@
 import type { AssetGroupMap } from '../assets/types';
+import type { GameEventDescriptor } from '../events/types';
 import type { GameDefinition, InputMap, SceneMap } from './types';
 
 type SceneActions<TScene> = TScene extends { readonly __actionType?: infer TAction }
@@ -29,6 +30,33 @@ type ValidateSceneTransitions<TScenes extends SceneMap> =
     ? unknown
     : { readonly __undeclaredSceneTransitions: UndeclaredSceneTransitions<TScenes> };
 
+type SceneEmits<TScene> = TScene extends { readonly __emitType?: infer TEmits }
+  ? Exclude<TEmits, undefined>
+  : never;
+
+type UndeclaredSceneEmits<
+  TScenes extends SceneMap,
+  TEventDefs extends Record<string, GameEventDescriptor<unknown>>,
+> = TEventDefs extends Record<string, never>
+  ? SceneEmits<TScenes[keyof TScenes]>
+  : Exclude<SceneEmits<TScenes[keyof TScenes]>, keyof TEventDefs & string>;
+
+type ValidateSceneEmits<
+  TScenes extends SceneMap,
+  TEventDefs extends Record<string, GameEventDescriptor<unknown>>,
+> = UndeclaredSceneEmits<TScenes, TEventDefs> extends never
+  ? unknown
+  : { readonly __undeclaredSceneEmits: UndeclaredSceneEmits<TScenes, TEventDefs> };
+
+type ValidateEventsWhenScenesEmit<
+  TScenes extends SceneMap,
+  TEventDefs extends Record<string, GameEventDescriptor<unknown>>,
+> = SceneEmits<TScenes[keyof TScenes]> extends never
+  ? unknown
+  : TEventDefs extends Record<string, never>
+    ? { readonly __eventsRequired: 'scenes declare emits but game has no events map' }
+    : unknown;
+
 /**
  * Declare a game.
  *
@@ -81,14 +109,44 @@ export function defineGame<
   const TInput extends InputMap = InputMap,
   const TInitialScene extends keyof TScenes = keyof TScenes,
   const TAssets extends AssetGroupMap = AssetGroupMap,
+  const TEventDefs extends Record<string, GameEventDescriptor<unknown>> = Record<string, never>,
 >(
-  definition: GameDefinition<TScenes, TInput, TInitialScene, TAssets> &
+  definition: GameDefinition<TScenes, TInput, TInitialScene, TAssets, TEventDefs> &
     ValidateSceneActions<TScenes, TInput> &
-    ValidateSceneTransitions<TScenes>,
-): GameDefinition<TScenes, TInput, TInitialScene, TAssets> {
+    ValidateSceneTransitions<TScenes> &
+    ValidateSceneEmits<TScenes, TEventDefs> &
+    ValidateEventsWhenScenesEmit<TScenes, TEventDefs>,
+): GameDefinition<TScenes, TInput, TInitialScene, TAssets, TEventDefs> {
   // The viewport config is part of the public session surface; freeze it so a
   // caller cannot mutate a live game's coordinate authority.
   Object.freeze(definition.viewport.logicalSize);
   Object.freeze(definition.viewport);
+  if (definition.events !== undefined) {
+    Object.freeze(definition.events);
+    // Runtime identity check: every scene that declares `events` must reference
+    // the same object as the game's `events`. This catches two different
+    // `defineGameEvents` instances with compatible shapes that would otherwise
+    // be structurally compatible at the type level.
+    for (const [name, scene] of Object.entries(definition.scenes)) {
+      const s = scene as unknown as { events?: unknown; emits?: readonly string[] };
+      if (s.events !== undefined && s.events !== definition.events) {
+        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 }).`,
+        );
+      }
+      if (s.events === undefined && s.emits !== undefined && s.emits.length > 0) {
+        throw new Error(
+          `Scene "${name}" declares emits but is not bound to the game's events. Pass \`events\` to defineScene.`,
+        );
+      }
+    }
+  } else {
+    for (const [name, scene] of Object.entries(definition.scenes)) {
+      const s = scene as unknown as { events?: unknown; emits?: readonly string[] };
+      if (s.events !== undefined) {
+        throw new Error(`Scene "${name}" is bound to events but the game has no events map`);
+      }
+    }
+  }
   return definition;
 }

package/src/definition/types.ts

@@ -1,4 +1,5 @@
 import type { AssetGroupMap, GameAssetManifest } from '../assets/types';
+import type { GameEventDescriptor } from '../events/types';
 import type { Viewport } from '../viewport2d/types';
 
 /** The button action supported by the runtime. */
@@ -37,6 +38,12 @@ export interface SceneDefinitionMarker {
   readonly __actionType?: string;
   /** @internal Type witness for transition targets declared by this scene. */
   readonly __transitionType?: string;
+  /** @internal Type witness for emitted event names. */
+  readonly __emitType?: string;
+  /** @internal Type witness for the game event map. */
+  readonly __eventMapType?: Record<string, unknown>;
+  /** @internal Type witness for the branded event definitions identity. */
+  readonly __eventDefsType?: Record<string, GameEventDescriptor<unknown>>;
 }
 
 /** The collection of functional scenes declared by a game. */
@@ -53,6 +60,7 @@ export interface GameDefinition<
   TInput extends InputMap = InputMap,
   TInitialScene extends keyof TScenes = keyof TScenes,
   TAssets extends AssetGroupMap = AssetGroupMap,
+  TEventDefs extends Record<string, GameEventDescriptor<unknown>> = Record<string, never>,
 > {
   /** The viewport configuration of the game. */
   readonly viewport: Viewport;
@@ -64,4 +72,6 @@ export interface GameDefinition<
   readonly scenes: TScenes;
   /** The scene created first when a session starts. */
   readonly initialScene: TInitialScene;
+  /** Typed game event declarations (T13). Absence keeps the no-event fast path. */
+  readonly events?: TEventDefs;
 }

package/src/events/defineGameEvents.ts

@@ -0,0 +1,46 @@
+import type { BrandedGameEventDefs, GameEventDescriptor } from './types';
+
+/**
+ * Create a type witness for one event payload.
+ *
+ * `gameEvent` owns no runtime resource — it returns a frozen empty
+ * descriptor whose generic preserves the payload type. Payload shapes are
+ * validated when events are staged, not when they are declared.
+ *
+ * @example
+ * ```ts
+ * const events = defineGameEvents({
+ *   'brick-hit': gameEvent<{ brickId: string; point: Point2D }>(),
+ * });
+ * ```
+ */
+export function gameEvent<TPayload>(): GameEventDescriptor<TPayload> {
+  return Object.freeze({}) as GameEventDescriptor<TPayload>;
+}
+
+function isValidEventName(name: string): boolean {
+  return name.length > 0 && name.length <= 128 && !name.includes('\0');
+}
+
+/**
+ * Define and freeze a game event map.
+ *
+ * Validates every name, freezes the declaration map and its entries,
+ * and preserves literal inference so `keyof typeof events` and the
+ * payload types flow through `defineGame`, scenes, and subscriptions
+ * without duplicate author-written unions.
+ */
+export function defineGameEvents<const T extends Record<string, GameEventDescriptor<unknown>>>(
+  definitions: T,
+): BrandedGameEventDefs<T> {
+  for (const [name, descriptor] of Object.entries(definitions)) {
+    if (!isValidEventName(name)) {
+      throw new Error(`Invalid game event name: "${name}"`);
+    }
+    if (descriptor === null || typeof descriptor !== 'object') {
+      throw new Error(`Game event "${name}" descriptor must be an object`);
+    }
+    Object.freeze(descriptor);
+  }
+  return Object.freeze({ ...definitions }) as BrandedGameEventDefs<T>;
+}

package/src/events/errors.ts

@@ -0,0 +1,14 @@
+/**
+ * Game event payload validation errors (T13).
+ *
+ * Every rejection identifies the event name and the exact payload path
+ * that caused the failure. The payload never captures React or native
+ * handles, sparse holes, cycles, or non-finite numbers.
+ */
+export class GameEventError extends Error {
+  override readonly name = 'GameEventError';
+
+  constructor(message: string) {
+    super(message);
+  }
+}

package/src/events/index.ts

@@ -0,0 +1,14 @@
+export { GameEventError } from './errors';
+export { cloneAndValidatePayload, PAYLOAD_LIMITS } from './payload';
+export { defineGameEvents, gameEvent } from './defineGameEvents';
+export { seedGameEvent } from './seed';
+export type {
+  AnyGameEventEnvelope,
+  GameEventDefinitions,
+  GameEventDescriptor,
+  GameEventEmitter,
+  GameEventEnvelope,
+  GameEventListener,
+  GameEventMap,
+  InferGameEventMap,
+} from './types';