rn-gamekit 0.1.0

package/src/react/bindAppLifecycle.ts

@@ -0,0 +1,79 @@
+import type { GameSessionStatus } from '../core/session/types';
+
+/** Minimal AppState-like source used to keep this seam platform-neutral. */
+export interface AppLifecycleSource {
+  /** The current app state, read synchronously at bind time. */
+  readonly currentState: string | null | undefined;
+  addEventListener(
+    state: 'change',
+    listener: (next: string) => void,
+  ): { remove(): void };
+}
+
+/** Session operations the lifecycle binding may drive. */
+export interface AppLifecycleSession {
+  /** Read the current session status. */
+  getStatus(): GameSessionStatus;
+  /** Pause simulation and discard suspended wall time. */
+  pause(): void;
+  /** Resume a paused session. */
+  resume(): void;
+}
+
+/**
+ * Pause a running session when the app becomes inactive or backgrounded and
+ * resume it on foreground only when this binding performed that pause.
+ *
+ * Platform-neutral: the React adapter supplies React Native's `AppState`.
+ * The initial `currentState` is synchronized at bind time, so an app that
+ * mounts while already backgrounded never leaves a session running
+ * invisibly. Manual pauses that precede backgrounding are never claimed, and
+ * a session that another actor resumed (or disposed) meanwhile is not
+ * resumed again. Cleanup clears the binding flag so a late foreground event
+ * cannot restart an unmounted game.
+ */
+export function bindAppLifecycle(
+  source: AppLifecycleSource,
+  session: AppLifecycleSession,
+): () => void {
+  let pausedByLifecycle = false;
+
+  const pauseForBackground = () => {
+    if (session.getStatus() === 'running') {
+      session.pause();
+      pausedByLifecycle = true;
+    }
+  };
+
+  // Synchronize the initial app state before any change event arrives.
+  if (source.currentState === 'inactive' || source.currentState === 'background') {
+    pauseForBackground();
+  }
+
+  const subscription = source.addEventListener('change', (next) => {
+    if (next === 'active') {
+      if (pausedByLifecycle) {
+        pausedByLifecycle = false;
+        // Resume only if the session is still paused; a different actor may
+        // have resumed or disposed it while the app was backgrounded.
+        if (session.getStatus() === 'paused') {
+          session.resume();
+        }
+      }
+      return;
+    }
+    if (next === 'inactive' || next === 'background') {
+      pauseForBackground();
+    }
+  });
+
+  let cleanedUp = false;
+  return () => {
+    if (cleanedUp) {
+      return;
+    }
+    cleanedUp = true;
+    subscription.remove();
+    pausedByLifecycle = false;
+  };
+}

package/src/react/bindGameSession.ts

@@ -0,0 +1,41 @@
+import type { InputMap, SceneMap } from '../definition/types';
+import type { CommitFrame, GameSession } from '../core/session/types';
+
+/**
+ * Bind a live session to an imperative presentation sink.
+ *
+ * This platform-neutral lifecycle seam keeps the React adapter testable
+ * without loading React Native or Skia in the headless test runner. The sink
+ * receives commit frames only (simulation frequency), never per-display
+ * frames, and a stale write can never replace a newer commit: revisions are
+ * strictly increasing per session, and the initial envelope is presented
+ * through the same guard.
+ */
+export function bindGameSession<TScenes extends SceneMap, TInput extends InputMap>(
+  game: GameSession<TScenes, TInput>,
+  present: (frame: CommitFrame<TScenes>) => void,
+): () => void {
+  let lastRevision = -1;
+  const presentIfNewer = (frame: CommitFrame<TScenes>) => {
+    if (frame.revision <= lastRevision) {
+      return;
+    }
+    lastRevision = frame.revision;
+    present(frame);
+  };
+  presentIfNewer(game.getRenderFrame());
+  const subscription = game.addCommitListener(presentIfNewer);
+  game.start();
+  let cleanedUp = false;
+
+  return () => {
+    if (cleanedUp) {
+      return;
+    }
+    cleanedUp = true;
+    subscription.remove();
+    if (game.status !== 'disposed') {
+      game.pause();
+    }
+  };
+}

package/src/react/gestureLifecycle.ts

@@ -0,0 +1,73 @@
+import type { CoalescedPointerEvent } from './pointerCoalescer';
+
+/** RN-side mirror of whether the trailing-flush sampler should be mounted. */
+export interface SamplerMirrorState {
+  readonly generation: number;
+  readonly active: boolean;
+}
+
+/**
+ * Manual-gesture terminal lifecycle (F3).
+ *
+ * The RNGH 3 manual recognizer is activated explicitly on touch-down and
+ * must be returned to its terminal state explicitly: it stays active across
+ * separate touches and screen lifecycles otherwise. This pure decision
+ * drives the deactivation call in `GamePointerInput`; the recognizer-state
+ * operations themselves stay on the UI runtime.
+ */
+
+/** A single-pointer binding begins only with the first native touch. */
+export function canBeginPrimaryPointer(nativeTouchCount: number): boolean {
+  'worklet';
+  return nativeTouchCount === 1;
+}
+
+/** After an up edge, deactivate once RNGH reports that no touches remain. */
+export function deactivateAfterUp(remainingTouches: number): boolean {
+  'worklet';
+  return remainingTouches === 0;
+}
+
+/** Unexpected finalization while a pointer is still active must neutralize ownership. */
+export function cancelOnActiveFinalize(activePointerId: number | undefined): boolean {
+  'worklet';
+  return activePointerId !== undefined;
+}
+
+/**
+ * Sampler mirror for the F2 trailing flush (F2 lifecycle).
+ *
+ * The trailing-flush frame callback must stay active exactly while the
+ * coalescer owns a pointer. Returns `true` when a begin crossed (pointer
+ * owned), `false` when a terminal edge crossed (pointer released), and
+ * `undefined` for empty batches (secondary touches — never toggle the
+ * sampler) and flushed moves (the pointer stays owned).
+ */
+export function samplerMirrorFromBatch(
+  batch: readonly CoalescedPointerEvent[],
+): boolean | undefined {
+  'worklet';
+  if (batch.length === 0) {
+    return undefined;
+  }
+  const kind = batch[batch.length - 1]?.kind;
+  if (kind === 'begin') {
+    return true;
+  }
+  if (kind === 'end' || kind === 'cancel') {
+    return false;
+  }
+  return undefined;
+}
+
+/**
+ * Apply a UI-originated sampler update only when it belongs to the current
+ * binding generation.
+ */
+export function reduceSamplerMirrorState(
+  currentGeneration: number,
+  previous: SamplerMirrorState,
+  next: SamplerMirrorState,
+): SamplerMirrorState {
+  return next.generation === currentGeneration ? next : previous;
+}

package/src/react/instrumentation.ts

@@ -0,0 +1,54 @@
+/**
+ * Optional measurement seams for the mounted game pipeline (F1).
+ *
+ * These callbacks let the Performance Lab attribute results to the real
+ * mounted components — GameView presentation, RNGH raw touches, and
+ * UI→RN forwarding — instead of headless substitutes. They are optional,
+ * cost nothing when absent (a single optional chain at event sites, never
+ * per-frame), and are not part of the gameplay API contract: the playground
+ * lab is their only consumer until the device matrix approves them.
+ *
+ * Runtime ownership:
+ * - Pointer callbacks run on the **UI runtime** (inside gesture worklets);
+ *   pass stable workletized closures and only touch worklet-safe state
+ *   (shared values, counters).
+ * - `onPresentCommit` runs on the **RN runtime** (inside the commit
+ *   binding); pass a plain JS callback.
+ */
+
+import type { CoalescedPointerEvent } from './pointerCoalescer';
+
+/** Raw touch kinds as observed by the manual gesture callbacks. */
+export type PointerStageKind = 'down' | 'move' | 'up' | 'cancel';
+
+/** Pointer pipeline instrumentation (UI runtime callbacks). */
+export interface GamePointerInstrumentation {
+  /** A raw touch reached the manual gesture handlers. */
+  readonly onRawTouch?: (kind: PointerStageKind, pointerId: number, atMs: number) => void;
+  /** A coalesced event crossed from the UI runtime into the RN runtime. */
+  readonly onForwarded?: (
+    kind: CoalescedPointerEvent['kind'],
+    pointerId: number,
+    atMs: number,
+  ) => void;
+  /**
+   * RN runtime: the binding's verdict for a dispatched packet (F1). Only
+   * accepted packets may become latency samples; stale/rejected packets are
+   * counted but never sampled.
+   */
+  readonly onDispatchResult?: (seq: number, atMs: number, accepted: boolean) => void;
+  /** The trailing-flush sampler mounted (true) or unmounted (false). */
+  readonly onSamplerChanged?: (mounted: boolean) => void;
+}
+
+/** GameView presentation instrumentation (RN runtime callback). */
+export interface GameViewInstrumentation {
+  /** A commit was presented to the canvas frame shared value. */
+  readonly onPresentCommit?: (revision: number, atMs: number) => void;
+  /**
+   * UI runtime: the first UI frame that observed a new commit revision (the
+   * alpha clock's reset detects it). Skia GPU presentation is not proven by
+   * this hook, so latency consumers must name the stage honestly.
+   */
+  readonly onUiRevisionObserved?: (revision: number, atMs: number) => void;
+}

package/src/react/pointerBinding.ts

@@ -0,0 +1,226 @@
+import type { InputController } from '../core/input/types';
+import type { Point2D } from '../geometry/types';
+import { containsSurfacePoint, surfaceToWorld, type ResolvedViewport2D } from '../viewport2d';
+import type { CoalescedPointerEvent } from './pointerCoalescer';
+
+/**
+ * A coalesced pointer event stamped with the binding epoch it was scheduled
+ * under (F6). Packets scheduled before a layout revision or binding
+ * replacement carry the old epoch and are rejected on the RN runtime, so a
+ * stale begin cannot reacquire input with old coordinates and a stale
+ * terminal edge cannot release a newer capture that reused the pointer id.
+ */
+export type PointerPacket = CoalescedPointerEvent & {
+  /** Monotonic adapter-owned binding generation (F3 follow-up). */
+  readonly generation: number;
+  /** Adapter-owned layout epoch; bumped on layout revisions and unmount. */
+  readonly layoutEpoch: number;
+  /** Monotonic UI-runtime forward sequence (F1 latency causality). */
+  readonly seq: number;
+  /** UI-runtime timestamp of the forward (F1 latency causality). */
+  readonly atMs: number;
+};
+
+/** Monotonic generation source for factory-created bindings (F3). */
+let nextFactoryGeneration = 1;
+
+/** The identity a pointer binding is scoped to. */
+export interface PointerBindingIdentity<TName extends string> {
+  /** The session input controller (identity changes when the session changes). */
+  readonly input: InputController<TName>;
+  /** The declared pointer action name. */
+  readonly action: TName;
+  /** Identity token for the viewport provider (changes on layout owner swaps). */
+  readonly viewport: unknown;
+}
+
+/** A binding plus the identity it was created for. */
+export interface PointerBindingEntry<TName extends string> {
+  readonly binding: PointerBinding<TName>;
+  readonly identity: PointerBindingIdentity<TName>;
+}
+
+/**
+ * Reuse the previous binding when the identity is unchanged, otherwise dispose
+ * it and create a fresh binding. Returns whether a new binding was created.
+ */
+export function createPointerBinding<TName extends string>(
+  identity: PointerBindingIdentity<TName>,
+  getViewport: () => ResolvedViewport2D | undefined,
+  previous: PointerBindingEntry<TName> | undefined,
+): { readonly entry: PointerBindingEntry<TName>; readonly created: boolean } {
+  if (
+    previous !== undefined &&
+    previous.identity.input === identity.input &&
+    previous.identity.action === identity.action &&
+    previous.identity.viewport === identity.viewport
+  ) {
+    return { entry: previous, created: false };
+  }
+  if (previous !== undefined) {
+    previous.binding.dispose();
+  }
+  return {
+    entry: {
+      binding: new PointerBinding(
+        identity.action,
+        identity.input,
+        getViewport,
+        nextFactoryGeneration++,
+      ),
+      identity,
+    },
+    created: true,
+  };
+}
+
+/**
+ * Platform-neutral pointer binding seam.
+ *
+ * It converts gesture positions from surface coordinates into logical world
+ * coordinates through the current resolved viewport, rejects begins that
+ * start in `fit` letterbox space, and forwards semantic events into the
+ * session input buffer. The high-level `handleTouches*` methods mirror the
+ * adapter's touch dispatch (including forwarding the final up position) so
+ * the full adapter behavior is testable without mounting native gesture
+ * views. Ownership and neutralization live in the input buffer.
+ */
+export class PointerBinding<TActionName extends string> {
+  readonly #action: TActionName;
+  readonly #input: InputController<TActionName>;
+  readonly #getViewport: () => ResolvedViewport2D | undefined;
+  readonly #generation: number;
+  #disposed = false;
+
+  constructor(
+    action: TActionName,
+    input: InputController<TActionName>,
+    getViewport: () => ResolvedViewport2D | undefined,
+    generation: number,
+  ) {
+    this.#action = action;
+    this.#input = input;
+    this.#getViewport = getViewport;
+    this.#generation = generation;
+  }
+
+  /**
+   * The monotonic adapter-owned generation this binding belongs to (F3).
+   * Generations never reset to zero, so a replacement binding and the
+   * worklet closures that stamp its packets agree by construction — no
+   * post-commit synchronization is needed.
+   */
+  get generation(): number {
+    return this.#generation;
+  }
+
+  /**
+   * Dispatch a coalesced packet stamped with its scheduling generation.
+   *
+   * Returns `false` (and forwards nothing) when the binding is disposed or
+   * the packet belongs to a different generation; the active gesture's
+   * packets keep flowing under the current generation with the latest
+   * viewport. Layout-epoch rejection happens on the adapter side (the epoch
+   * is adapter-owned and never resets, so it cannot desynchronize).
+   */
+  dispatch(packet: PointerPacket): boolean {
+    if (this.#disposed || packet.generation !== this.#generation) {
+      return false;
+    }
+    switch (packet.kind) {
+      case 'begin':
+        this.handleTouchesDown(packet.pointerId, packet.x, packet.y);
+        break;
+      case 'move':
+        this.handleTouchesMove(packet.pointerId, packet.x, packet.y);
+        break;
+      case 'end':
+        this.handleTouchesUp(packet.pointerId, packet.x, packet.y);
+        break;
+      case 'cancel':
+        this.handleTouchesCancelled();
+        break;
+    }
+    return true;
+  }
+
+  /**
+   * Begin a pointer at a surface point.
+   *
+   * Returns `false` when the layout is invalid or the point starts in
+   * letterbox space; the gesture must be rejected and never becomes the owner.
+   */
+  begin(pointerId: number, surfacePoint: Point2D): boolean {
+    if (this.#disposed) {
+      return false;
+    }
+    const viewport = this.#getViewport();
+    if (viewport === undefined) {
+      return false;
+    }
+    if (!containsSurfacePoint(viewport, surfacePoint)) {
+      return false;
+    }
+    this.#input.begin(this.#action, pointerId, surfaceToWorld(viewport, surfacePoint));
+    return true;
+  }
+
+  /** Move a pointer. Conversion remains unbounded outside content bounds. */
+  move(pointerId: number, surfacePoint: Point2D): void {
+    if (this.#disposed) {
+      return;
+    }
+    const viewport = this.#getViewport();
+    if (viewport === undefined) {
+      return;
+    }
+    this.#input.move(this.#action, pointerId, surfaceToWorld(viewport, surfacePoint));
+  }
+
+  /** End a pointer. The owning pointer is released by the input buffer. */
+  end(pointerId: number): void {
+    if (this.#disposed) {
+      return;
+    }
+    this.#input.end(this.#action, pointerId);
+  }
+
+  /** Cancel the active pointer (gesture cancellation, layout change, unmount). */
+  cancel(): void {
+    if (this.#disposed) {
+      return;
+    }
+    this.#input.cancel(this.#action);
+  }
+
+  /** Handle a touch-down gesture event with a surface position. */
+  handleTouchesDown(pointerId: number, x: number, y: number): boolean {
+    return this.begin(pointerId, { x, y });
+  }
+
+  /** Handle a touch-move gesture event with a surface position. */
+  handleTouchesMove(pointerId: number, x: number, y: number): void {
+    this.move(pointerId, { x, y });
+  }
+
+  /**
+   * Handle a touch-up gesture event with its final surface position.
+   *
+   * The final position is forwarded before ownership ends so the documented
+   * release frame contains the actual point where the pointer lifted.
+   */
+  handleTouchesUp(pointerId: number, x: number, y: number): void {
+    this.move(pointerId, { x, y });
+    this.end(pointerId);
+  }
+
+  /** Handle a platform touch cancellation. */
+  handleTouchesCancelled(): void {
+    this.cancel();
+  }
+
+  /** Stop forwarding events. Safe to call repeatedly. */
+  dispose(): void {
+    this.#disposed = true;
+  }
+}