rn-gamekit 0.1.0 → 0.2.1

package/src/react/bindGameSession.ts

@@ -1,5 +1,6 @@
 import type { InputMap, SceneMap } from '../definition/types';
 import type { CommitFrame, GameSession } from '../core/session/types';
+import { createCleanupList } from './cleanupList';
 
 /**
  * Bind a live session to an imperative presentation sink.
@@ -15,6 +16,9 @@ export function bindGameSession<TScenes extends SceneMap, TInput extends InputMa
   game: GameSession<TScenes, TInput>,
   present: (frame: CommitFrame<TScenes>) => void,
 ): () => void {
+  // GS-REACT-02: setup is transactional — the commit listener registered
+  // below is released when the subsequent start() throws.
+  const cleanups = createCleanupList();
   let lastRevision = -1;
   const presentIfNewer = (frame: CommitFrame<TScenes>) => {
     if (frame.revision <= lastRevision) {
@@ -25,7 +29,13 @@ export function bindGameSession<TScenes extends SceneMap, TInput extends InputMa
   };
   presentIfNewer(game.getRenderFrame());
   const subscription = game.addCommitListener(presentIfNewer);
-  game.start();
+  cleanups.add(() => subscription.remove());
+  try {
+    game.start();
+  } catch (error) {
+    cleanups.releaseAll();
+    throw error;
+  }
   let cleanedUp = false;
 
   return () => {
@@ -33,7 +43,7 @@ export function bindGameSession<TScenes extends SceneMap, TInput extends InputMa
       return;
     }
     cleanedUp = true;
-    subscription.remove();
+    cleanups.releaseAll();
     if (game.status !== 'disposed') {
       game.pause();
     }

package/src/react/camera2d/GameLayer2D.tsx

@@ -0,0 +1,43 @@
+/**
+ * `GameLayer2D` — an ordered parallax layer (T12.5).
+ *
+ * A small rendering primitive, not a scene graph: the layer draws its
+ * children with the presented camera whose center contribution is scaled
+ * per axis by the parallax factor. JSX order is render order; no z-index
+ * scheduler exists.
+ *
+ * Frozen policy: parallax scales only the camera center contribution. Zoom
+ * and rotation apply fully at every factor; factor 1 is the primary layer,
+ * factor 0 is camera-fixed on that axis. The correction is a pure
+ * translation relative to the parent camera, so layers never double-apply
+ * zoom or rotation.
+ */
+import type { ReactNode } from 'react';
+import { Group } from '@shopify/react-native-skia';
+import { useDerivedValue } from 'react-native-reanimated';
+
+import { layerParallaxTransform2D, useGameWorldContext } from '../sprites/GameWorld2D';
+
+function assertFiniteParallax(value: number, axis: 'x' | 'y'): void {
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`GameLayer2D parallax.${axis} must be finite, got ${String(value)}`);
+  }
+}
+
+export function GameLayer2D({
+  parallax = { x: 1, y: 1 },
+  children,
+}: {
+  /** Per-axis parallax factor; defaults to the primary layer `{ x: 1, y: 1 }`. */
+  readonly parallax?: { readonly x: number; readonly y: number };
+  readonly children: ReactNode;
+}) {
+  assertFiniteParallax(parallax.x, 'x');
+  assertFiniteParallax(parallax.y, 'y');
+  const { viewport, camera } = useGameWorldContext();
+  const transform = useDerivedValue(() => {
+    'worklet';
+    return layerParallaxTransform2D(camera?.value, viewport.value, parallax.x, parallax.y);
+  });
+  return <Group transform={transform as never}>{children}</Group>;
+}

package/src/react/camera2d/defineGameCamera2D.ts

@@ -0,0 +1,59 @@
+/**
+ * Camera2D definition (T12.3).
+ *
+ * A static, declarative camera binding: `select` reads the authored camera
+ * from committed frames, and the optional `cut` predicate signals an
+ * explicit cut (teleports, respawns) where interpolation must snap. The
+ * binding is owned by `GameView` and never by the renderer or the pointer
+ * adapter, so both consume the same presented generation.
+ */
+import type { Camera2D } from '../../camera2d';
+
+/** Failure context for a camera selector/cut/validation failure (GS-CAMERA-02). */
+export interface GameCameraErrorInfo {
+  /** Which stage of the commit transaction failed. */
+  readonly phase: 'select' | 'cut' | 'validate';
+  /** The original thrown value, preserved verbatim. */
+  readonly error: unknown;
+  /** The scene whose commit failed. */
+  readonly scene: string;
+}
+
+/** The static camera definition supplied to `GameView`. */
+export interface GameCamera2DDefinition<TFrame> {
+  /**
+   * Read the authored camera from a committed frame. Runs once per commit
+   * on the JS runtime; returning the same value keeps the camera static.
+   */
+  readonly select: (frame: TFrame) => Camera2D;
+  /**
+   * Optional explicit cut signal evaluated per commit. Returning true
+   * snaps presentation (no interpolation into the new camera), joining the
+   * automatic cuts for scene transitions, session replacement, and
+   * binding-generation changes.
+   */
+  readonly cut?: (frame: TFrame) => boolean;
+  /**
+   * Optional failure reporter (GS-CAMERA-02). Invoked at most once per
+   * failure episode with the failing phase and scene; a successful commit
+   * resets deduplication. Failures without a reporter keep the last valid
+   * presentation silently.
+   */
+  readonly onError?: (info: GameCameraErrorInfo) => void;
+}
+
+/** Validate and return a camera definition. */
+export function defineGameCamera2D<TFrame>(
+  definition: GameCamera2DDefinition<TFrame>,
+): GameCamera2DDefinition<TFrame> {
+  if (typeof definition.select !== 'function') {
+    throw new Error('defineGameCamera2D requires a select function');
+  }
+  if (definition.cut !== undefined && typeof definition.cut !== 'function') {
+    throw new Error('defineGameCamera2D requires cut to be a function when provided');
+  }
+  if (definition.onError !== undefined && typeof definition.onError !== 'function') {
+    throw new Error('defineGameCamera2D requires onError to be a function when provided');
+  }
+  return definition;
+}

package/src/react/camera2d/usePresentedCameraBinding.ts

@@ -0,0 +1,185 @@
+/**
+ * Presented camera binding (T12.3, T12-F2, T12-F3).
+ *
+ * Joins authored camera data to the UI presentation pipeline: `commit`
+ * runs per simulation commit on the JS runtime and evaluates the
+ * definition's selector AND cut predicate as ONE exception-safe
+ * transaction, validating the selected camera before any shared value is
+ * published. `present` runs on the UI runtime per display frame and
+ * delegates to the trusted scalar projector (a complete worklet call
+ * graph), writing the read-only `CameraCut2D` into the GameView-owned
+ * shared value that renderer and pointer adapter both consume.
+ *
+ * Cut semantics (snap instead of interpolate): scene transitions
+ * (`hardCut` or a scene-name change), explicit `cut` predicate hits,
+ * session replacement, and definition replacement — which is modeled as
+ * ONE pending cut owned by the replacement and consumed on its first
+ * successful commit, so later commits interpolate normally (T12-F3).
+ * A throwing selector or cut predicate retains the last valid presented
+ * value and leaves no half-updated state; the next valid commit recovers.
+ */
+import { useEffect, useMemo, useRef } from 'react';
+import { useSharedValue, type SharedValue } from 'react-native-reanimated';
+
+import { interpolateCameraScalar2D, type CameraCut2D } from '../../camera2d';
+import { cloneValidCamera2D } from '../../camera2d/validation';
+import type { CommitFrame } from '../../core/session/types';
+import type { SceneMap } from '../../definition/types';
+import type { GameCamera2DDefinition } from './defineGameCamera2D';
+
+/** A UI-side camera binding for one session presentation. */
+export interface PresentedCameraBinding<TScenes extends SceneMap> {
+  /** Evaluate the selector against one committed frame (JS runtime). */
+  commit(frame: CommitFrame<TScenes>): void;
+  /** Advance presentation by the current alpha (UI runtime worklet). */
+  present(alpha: number): void;
+  /** Drop the current state; the presented value stays as-is. */
+  dispose(): void;
+}
+
+function sameSceneName(first: string | undefined, second: string | undefined): boolean {
+  return first === second;
+}
+
+/**
+ * Create the camera binding for one presentation.
+ *
+ * The `presented` shared value is owned by `GameView` so the pointer
+ * adapter (a sibling of the renderer) reads the same generation.
+ */
+export function usePresentedCameraBinding<TScenes extends SceneMap>(
+  definition: GameCamera2DDefinition<CommitFrame<TScenes>> | undefined,
+  presented: SharedValue<CameraCut2D | undefined>,
+): PresentedCameraBinding<TScenes> {
+  const authoredPrevious = useSharedValue<CameraCut2D | undefined>(undefined);
+  const authoredCurrent = useSharedValue<CameraCut2D | undefined>(undefined);
+  const cutId = useSharedValue(0);
+  const sceneNameRef = useRef<string | undefined>(undefined);
+  // T12-F3: definition replacement is ONE pending cut, consumed by the
+  // first successful commit of the replacement binding — never a
+  // render-time boolean that stays true for the binding lifetime.
+  const pendingCutRef = useRef(false);
+
+  const definitionRef = useRef(definition);
+  useEffect(() => {
+    if (definitionRef.current === definition) {
+      return;
+    }
+    definitionRef.current = definition;
+    pendingCutRef.current = true;
+    authoredPrevious.value = undefined;
+    authoredCurrent.value = undefined;
+    sceneNameRef.current = undefined;
+    cutId.value += 1;
+    presented.value = undefined;
+  }, [authoredCurrent, authoredPrevious, cutId, definition, presented]);
+
+  const binding = useMemo<PresentedCameraBinding<TScenes>>(
+    () => {
+      // GS-CAMERA-02: one report per failure episode (phase + message),
+      // reset by the next successful commit so a later distinct failure
+      // stays visible.
+      let lastReportedFailureKey: string | null = null;
+      const reportCameraError = (
+        activeDefinition: GameCamera2DDefinition<CommitFrame<TScenes>>,
+        phase: 'select' | 'cut' | 'validate',
+        error: unknown,
+        frame: CommitFrame<TScenes>,
+      ): void => {
+        const onError = activeDefinition.onError;
+        if (onError === undefined) {
+          return;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        const key = `${phase}:${message}`;
+        if (key === lastReportedFailureKey) {
+          return;
+        }
+        lastReportedFailureKey = key;
+        try {
+          onError({ phase, error, scene: String(frame.scene) });
+        } catch {
+          // A throwing reporter must not break the last-valid fallback.
+        }
+      };
+      const markRecovered = (): void => {
+        lastReportedFailureKey = null;
+      };
+      return {
+      commit: (frame) => {
+        // GS-CAMERA-01: the binding identity is stable across definition
+        // replacements (the inner effect owns the pending cut), so a
+        // definition change never tears down presentation or restarts the
+        // session. Always read the current definition here.
+        const activeDefinition = definitionRef.current;
+        if (activeDefinition === undefined) {
+          return;
+        }
+        // One exception-safe transaction: select + cut + validation. A
+        // failure retains the last valid presented value and leaves no
+        // half-updated scene/cut state.
+        let camera;
+        let explicitCut = false;
+        let phase: 'select' | 'cut' | 'validate' = 'select';
+        try {
+          // T12-RF4 + T12-SF3: the selector output is validated AND copied
+          // at the JS commit boundary with the STRICT full-camera clone — a
+          // mutable selector result can never alias the authored values,
+          // and a partial camera is rejected, never completed with
+          // defaults.
+          const selected = activeDefinition.select(frame);
+          phase = 'cut';
+          explicitCut = activeDefinition.cut?.(frame) === true;
+          phase = 'validate';
+          camera = cloneValidCamera2D(selected);
+        } catch (error) {
+          reportCameraError(activeDefinition, phase, error, frame);
+          return;
+        }
+        markRecovered();
+        const pendingCut = pendingCutRef.current;
+        pendingCutRef.current = false;
+        const sceneChanged = !sameSceneName(sceneNameRef.current, String(frame.scene));
+        sceneNameRef.current = String(frame.scene);
+        const current: CameraCut2D = { camera, cutId: cutId.value };
+        if (pendingCut || explicitCut || sceneChanged || frame.hardCut) {
+          authoredPrevious.value = undefined;
+          cutId.value += 1;
+          authoredCurrent.value = { camera, cutId: cutId.value };
+          // GS-CAMERA-01: a valid hard cut installs the presented camera
+          // immediately — paused time presents coherently without waiting
+          // for the next present(alpha). Ordinary commits leave
+          // presentation to the frame clock so pause freezes interpolation.
+          presented.value = { camera, cutId: cutId.value };
+        } else {
+          authoredPrevious.value = authoredCurrent.value;
+          authoredCurrent.value = current;
+        }
+      },
+      present: (alpha: number) => {
+        'worklet';
+        const current = authoredCurrent.value;
+        if (current === undefined) {
+          return;
+        }
+        presented.value = {
+          camera: interpolateCameraScalar2D(authoredPrevious.value, current, alpha),
+          cutId: current.cutId,
+        };
+      },
+      dispose: () => {
+        authoredPrevious.value = undefined;
+        authoredCurrent.value = undefined;
+        presented.value = undefined;
+      },
+      };
+    },
+    // GS-CAMERA-01: stable identity across definition replacements — the
+    // inner effect owns the pending cut, so definition changes never tear
+    // down presentation or restart the session. `presented` is GameView-owned
+    // and stable per mount.
+    [presented],
+  );
+
+  return binding;
+}

package/src/react/cleanupList.ts

@@ -0,0 +1,48 @@
+/**
+ * Ordered, transactional release list for multi-stage setup (GS-REACT-02).
+ *
+ * Platform-neutral: no React import, so the headless binders and the React
+ * adapter share it. Stages register their release as they complete; a setup
+ * failure releases everything acquired so far, and the final cleanup runs
+ * every release in reverse registration order, composing failures
+ * losslessly instead of stopping at the first one.
+ */
+export interface CleanupList {
+  /** Register a release for a completed setup stage. */
+  add(release: () => void): void;
+  /**
+   * Run every registered release in reverse order. A lone failure rethrows
+   * unwrapped; several compose into an `AggregateError` in run order. The
+   * list drains, so releasing twice is a no-op.
+   */
+  releaseAll(): void;
+}
+
+export function createCleanupList(): CleanupList {
+  const releases: Array<() => void> = [];
+  return {
+    add(release: () => void): void {
+      releases.push(release);
+    },
+    releaseAll(): void {
+      const failures: unknown[] = [];
+      for (let index = releases.length - 1; index >= 0; index -= 1) {
+        try {
+          releases[index]?.();
+        } catch (error) {
+          failures.push(error);
+        }
+      }
+      releases.length = 0;
+      if (failures.length === 1) {
+        throw failures[0];
+      }
+      if (failures.length > 1) {
+        throw new AggregateError(
+          failures,
+          'Cleanup failed with multiple errors',
+        );
+      }
+    },
+  };
+}

package/src/react/instrumentation.ts

@@ -17,6 +17,8 @@
  */
 
 import type { CoalescedPointerEvent } from './pointerCoalescer';
+import type { CameraCut2D } from '../camera2d';
+import type { ResolvedViewport2D } from '../viewport2d';
 
 /** Raw touch kinds as observed by the manual gesture callbacks. */
 export type PointerStageKind = 'down' | 'move' | 'up' | 'cancel';
@@ -37,6 +39,29 @@ export interface GamePointerInstrumentation {
    * counted but never sampled.
    */
   readonly onDispatchResult?: (seq: number, atMs: number, accepted: boolean) => void;
+  /**
+   * RN runtime: the CAUSE of a rejected packet (T12-RF7) — layout-epoch
+   * staleness (rejected before dispatch) or binding staleness (generation
+   * mismatch or a disposed binding). One boolean cannot attribute causes.
+   */
+  readonly onDispatchRejected?: (
+    cause: 'layout-epoch' | 'binding',
+    seq: number,
+    atMs: number,
+  ) => void;
+  /**
+   * RN runtime: one ACCEPTED surface -> world conversion (T12-TF3), with
+   * the exact inputs and output of the authoritative binding — surface
+   * point, resolved mounted viewport, event-time presented camera cut, and
+   * the delivered world coordinate. Lab-only diagnostics; never a second
+   * gameplay transform.
+   */
+  readonly onPointerSample?: (sample: {
+    readonly surface: { readonly x: number; readonly y: number };
+    readonly viewport: ResolvedViewport2D;
+    readonly camera: CameraCut2D | undefined;
+    readonly world: { readonly x: number; readonly y: number };
+  }) => void;
   /** The trailing-flush sampler mounted (true) or unmounted (false). */
   readonly onSamplerChanged?: (mounted: boolean) => void;
 }
@@ -46,9 +71,12 @@ 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.
+   * The first UI frame that observed a new commit revision (the alpha
+   * clock's reset detects it), delivered ON THE RN RUNTIME: `GameView`
+   * detects the revision inside its UI frame callback and deliberately
+   * `scheduleOnRN`s this callback, so it must run on JS, never as a
+   * worklet. 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/lifecycleSource.ts

@@ -0,0 +1,58 @@
+/**
+ * T20.3: GameView owns one lifecycle source per session and supplies it to
+ * its renderer subtree through context. Presentation consumers (particle
+ * presentation, haptics binders) read the source instead of casting to
+ * private session methods or reaching for module-global coordinators.
+ *
+ * The source itself is a frozen plain value created by
+ * `createGameLifecycleSource`; replacing the session replaces the source, so
+ * a consumer bound to the old generation can never observe the new one.
+ */
+import { createContext, useContext } from 'react';
+import type {
+  GameLifecycleSource,
+  GameSession,
+  GameSessionStatus,
+} from '../core/session/types';
+import type { InputMap, SceneMap } from '../definition/types';
+
+export type { GameLifecycleSource, GameSessionStatus };
+
+const NOOP_DETACH = (): void => {};
+
+/**
+ * Create the read-only lifecycle source for one session. The returned value
+ * is a frozen plain value with exactly `getStatus` and `subscribe`.
+ */
+export function createGameLifecycleSource<TScenes extends SceneMap, TInput extends InputMap>(
+  session: GameSession<TScenes, TInput>,
+): GameLifecycleSource {
+  return Object.freeze({
+    getStatus: () => session.status,
+    subscribe(listener: (status: GameSessionStatus) => void): () => void {
+      // Disposed-error policy (mirrors useGameSessionStatus): the terminal
+      // notification was already delivered; never throw from a subscription.
+      if (session.status === 'disposed') return NOOP_DETACH;
+      const subscription = session.addStatusListener(listener);
+      return () => subscription.remove();
+    },
+  });
+}
+
+const GameLifecycleContext = createContext<GameLifecycleSource | undefined>(undefined);
+
+/** Supply the owning session's lifecycle source to a renderer subtree. */
+export const GameLifecycleProvider = GameLifecycleContext.Provider;
+
+/**
+ * Read the lifecycle source provided by the surrounding `GameView`.
+ *
+ * `undefined` means the consumer is mounted outside a `GameView` — a
+ * legitimate state for screens that drive presentation without a session
+ * (they pass no lifecycle to `useParticlePresentation` and keep manual pause
+ * independent). Inside a `GameView` the value is always present and is
+ * replaced together with the session.
+ */
+export function useGameLifecycleSource(): GameLifecycleSource | undefined {
+  return useContext(GameLifecycleContext);
+}