rn-gamekit 0.1.0 → 0.2.0

package/lib/module/react/bindAppLifecycle.js

@@ -1,5 +1,7 @@
 "use strict";
 
+import { createCleanupList } from "./cleanupList.js";
+
 /** Minimal AppState-like source used to keep this seam platform-neutral. */
 
 /** Session operations the lifecycle binding may drive. */
@@ -17,7 +19,12 @@
  * cannot restart an unmounted game.
  */
 export function bindAppLifecycle(source, session) {
+  // GS-REACT-02: setup is transactional — every stage registers its release
+  // as it completes, so a later failure unwinds everything acquired so far.
+  const cleanups = createCleanupList();
   let pausedByLifecycle = false;
+  let currentState = source.currentState ?? 'active';
+  const isInactive = state => state === 'inactive' || state === 'background';
   const pauseForBackground = () => {
     if (session.getStatus() === 'running') {
       session.pause();
@@ -25,33 +32,55 @@ export function bindAppLifecycle(source, session) {
     }
   };
 
-  // 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();
+  // T10.6: an external start() while the host is inactive is deterministically
+  // returned to paused. The binder observes status transitions and re-pauses
+  // any running transition that happens while the app is not active, so a
+  // frame loop cannot escape into the background.
+  let statusSubscription;
+  try {
+    if (session.addStatusListener !== undefined) {
+      statusSubscription = session.addStatusListener(status => {
+        if (status === 'running' && isInactive(currentState)) {
+          session.pause();
+          pausedByLifecycle = true;
         }
-      }
-      return;
+      });
+      cleanups.add(() => statusSubscription?.remove());
     }
-    if (next === 'inactive' || next === 'background') {
+
+    // Synchronize the initial app state before any change event arrives.
+    if (isInactive(source.currentState)) {
       pauseForBackground();
     }
-  });
+    const subscription = source.addEventListener('change', next => {
+      currentState = 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 (isInactive(next)) {
+        pauseForBackground();
+      }
+    });
+    cleanups.add(() => subscription.remove());
+  } catch (error) {
+    cleanups.releaseAll();
+    throw error;
+  }
   let cleanedUp = false;
   return () => {
     if (cleanedUp) {
       return;
     }
     cleanedUp = true;
-    subscription.remove();
+    cleanups.releaseAll();
     pausedByLifecycle = false;
   };
 }

package/lib/module/react/bindAppLifecycle.js.map

@@ -1 +1 @@
-{"version":3,"names":["bindAppLifecycle","source","session","pausedByLifecycle","pauseForBackground","getStatus","pause","currentState","subscription","addEventListener","next","resume","cleanedUp","remove"],"sourceRoot":"../../../src","sources":["react/bindAppLifecycle.ts"],"mappings":";;AAEA;;AAUA;;AAUA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASA,gBAAgBA,CAC9BC,MAA0B,EAC1BC,OAA4B,EAChB;EACZ,IAAIC,iBAAiB,GAAG,KAAK;EAE7B,MAAMC,kBAAkB,GAAGA,CAAA,KAAM;IAC/B,IAAIF,OAAO,CAACG,SAAS,CAAC,CAAC,KAAK,SAAS,EAAE;MACrCH,OAAO,CAACI,KAAK,CAAC,CAAC;MACfH,iBAAiB,GAAG,IAAI;IAC1B;EACF,CAAC;;EAED;EACA,IAAIF,MAAM,CAACM,YAAY,KAAK,UAAU,IAAIN,MAAM,CAACM,YAAY,KAAK,YAAY,EAAE;IAC9EH,kBAAkB,CAAC,CAAC;EACtB;EAEA,MAAMI,YAAY,GAAGP,MAAM,CAACQ,gBAAgB,CAAC,QAAQ,EAAGC,IAAI,IAAK;IAC/D,IAAIA,IAAI,KAAK,QAAQ,EAAE;MACrB,IAAIP,iBAAiB,EAAE;QACrBA,iBAAiB,GAAG,KAAK;QACzB;QACA;QACA,IAAID,OAAO,CAACG,SAAS,CAAC,CAAC,KAAK,QAAQ,EAAE;UACpCH,OAAO,CAACS,MAAM,CAAC,CAAC;QAClB;MACF;MACA;IACF;IACA,IAAID,IAAI,KAAK,UAAU,IAAIA,IAAI,KAAK,YAAY,EAAE;MAChDN,kBAAkB,CAAC,CAAC;IACtB;EACF,CAAC,CAAC;EAEF,IAAIQ,SAAS,GAAG,KAAK;EACrB,OAAO,MAAM;IACX,IAAIA,SAAS,EAAE;MACb;IACF;IACAA,SAAS,GAAG,IAAI;IAChBJ,YAAY,CAACK,MAAM,CAAC,CAAC;IACrBV,iBAAiB,GAAG,KAAK;EAC3B,CAAC;AACH","ignoreList":[]}
+{"version":3,"names":["createCleanupList","bindAppLifecycle","source","session","cleanups","pausedByLifecycle","currentState","isInactive","state","pauseForBackground","getStatus","pause","statusSubscription","addStatusListener","undefined","status","add","remove","subscription","addEventListener","next","resume","error","releaseAll","cleanedUp"],"sourceRoot":"../../../src","sources":["react/bindAppLifecycle.ts"],"mappings":";;AACA,SAASA,iBAAiB,QAAQ,kBAAe;;AAEjD;;AAUA;;AAgBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,gBAAgBA,CAC9BC,MAA0B,EAC1BC,OAA4B,EAChB;EACZ;EACA;EACA,MAAMC,QAAQ,GAAGJ,iBAAiB,CAAC,CAAC;EACpC,IAAIK,iBAAiB,GAAG,KAAK;EAC7B,IAAIC,YAAY,GAAGJ,MAAM,CAACI,YAAY,IAAI,QAAQ;EAElD,MAAMC,UAAU,GAAIC,KAAgC,IAClDA,KAAK,KAAK,UAAU,IAAIA,KAAK,KAAK,YAAY;EAEhD,MAAMC,kBAAkB,GAAGA,CAAA,KAAM;IAC/B,IAAIN,OAAO,CAACO,SAAS,CAAC,CAAC,KAAK,SAAS,EAAE;MACrCP,OAAO,CAACQ,KAAK,CAAC,CAAC;MACfN,iBAAiB,GAAG,IAAI;IAC1B;EACF,CAAC;;EAED;EACA;EACA;EACA;EACA,IAAIO,kBAAgD;EACpD,IAAI;IACF,IAAIT,OAAO,CAACU,iBAAiB,KAAKC,SAAS,EAAE;MAC3CF,kBAAkB,GAAGT,OAAO,CAACU,iBAAiB,CAAEE,MAAM,IAAK;QACzD,IAAIA,MAAM,KAAK,SAAS,IAAIR,UAAU,CAACD,YAAY,CAAC,EAAE;UACpDH,OAAO,CAACQ,KAAK,CAAC,CAAC;UACfN,iBAAiB,GAAG,IAAI;QAC1B;MACF,CAAC,CAAC;MACFD,QAAQ,CAACY,GAAG,CAAC,MAAMJ,kBAAkB,EAAEK,MAAM,CAAC,CAAC,CAAC;IAClD;;IAEA;IACA,IAAIV,UAAU,CAACL,MAAM,CAACI,YAAY,CAAC,EAAE;MACnCG,kBAAkB,CAAC,CAAC;IACtB;IAEA,MAAMS,YAAY,GAAGhB,MAAM,CAACiB,gBAAgB,CAAC,QAAQ,EAAGC,IAAI,IAAK;MAC/Dd,YAAY,GAAGc,IAAI;MACnB,IAAIA,IAAI,KAAK,QAAQ,EAAE;QACrB,IAAIf,iBAAiB,EAAE;UACrBA,iBAAiB,GAAG,KAAK;UACzB;UACA;UACA,IAAIF,OAAO,CAACO,SAAS,CAAC,CAAC,KAAK,QAAQ,EAAE;YACpCP,OAAO,CAACkB,MAAM,CAAC,CAAC;UAClB;QACF;QACA;MACF;MACA,IAAId,UAAU,CAACa,IAAI,CAAC,EAAE;QACpBX,kBAAkB,CAAC,CAAC;MACtB;IACF,CAAC,CAAC;IACFL,QAAQ,CAACY,GAAG,CAAC,MAAME,YAAY,CAACD,MAAM,CAAC,CAAC,CAAC;EAC3C,CAAC,CAAC,OAAOK,KAAK,EAAE;IACdlB,QAAQ,CAACmB,UAAU,CAAC,CAAC;IACrB,MAAMD,KAAK;EACb;EAEA,IAAIE,SAAS,GAAG,KAAK;EACrB,OAAO,MAAM;IACX,IAAIA,SAAS,EAAE;MACb;IACF;IACAA,SAAS,GAAG,IAAI;IAChBpB,QAAQ,CAACmB,UAAU,CAAC,CAAC;IACrBlB,iBAAiB,GAAG,KAAK;EAC3B,CAAC;AACH","ignoreList":[]}

package/lib/module/react/bindGameSession.js

@@ -1,5 +1,7 @@
 "use strict";
 
+import { createCleanupList } from "./cleanupList.js";
+
 /**
  * Bind a live session to an imperative presentation sink.
  *
@@ -11,6 +13,9 @@
  * through the same guard.
  */
 export function bindGameSession(game, present) {
+  // 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 => {
     if (frame.revision <= lastRevision) {
@@ -21,14 +26,20 @@ export function bindGameSession(game, present) {
   };
   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 () => {
     if (cleanedUp) {
       return;
     }
     cleanedUp = true;
-    subscription.remove();
+    cleanups.releaseAll();
     if (game.status !== 'disposed') {
       game.pause();
     }

package/lib/module/react/bindGameSession.js.map

@@ -1 +1 @@
-{"version":3,"names":["bindGameSession","game","present","lastRevision","presentIfNewer","frame","revision","getRenderFrame","subscription","addCommitListener","start","cleanedUp","remove","status","pause"],"sourceRoot":"../../../src","sources":["react/bindGameSession.ts"],"mappings":";;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASA,eAAeA,CAC7BC,IAAkC,EAClCC,OAA8C,EAClC;EACZ,IAAIC,YAAY,GAAG,CAAC,CAAC;EACrB,MAAMC,cAAc,GAAIC,KAA2B,IAAK;IACtD,IAAIA,KAAK,CAACC,QAAQ,IAAIH,YAAY,EAAE;MAClC;IACF;IACAA,YAAY,GAAGE,KAAK,CAACC,QAAQ;IAC7BJ,OAAO,CAACG,KAAK,CAAC;EAChB,CAAC;EACDD,cAAc,CAACH,IAAI,CAACM,cAAc,CAAC,CAAC,CAAC;EACrC,MAAMC,YAAY,GAAGP,IAAI,CAACQ,iBAAiB,CAACL,cAAc,CAAC;EAC3DH,IAAI,CAACS,KAAK,CAAC,CAAC;EACZ,IAAIC,SAAS,GAAG,KAAK;EAErB,OAAO,MAAM;IACX,IAAIA,SAAS,EAAE;MACb;IACF;IACAA,SAAS,GAAG,IAAI;IAChBH,YAAY,CAACI,MAAM,CAAC,CAAC;IACrB,IAAIX,IAAI,CAACY,MAAM,KAAK,UAAU,EAAE;MAC9BZ,IAAI,CAACa,KAAK,CAAC,CAAC;IACd;EACF,CAAC;AACH","ignoreList":[]}
+{"version":3,"names":["createCleanupList","bindGameSession","game","present","cleanups","lastRevision","presentIfNewer","frame","revision","getRenderFrame","subscription","addCommitListener","add","remove","start","error","releaseAll","cleanedUp","status","pause"],"sourceRoot":"../../../src","sources":["react/bindGameSession.ts"],"mappings":";;AAEA,SAASA,iBAAiB,QAAQ,kBAAe;;AAEjD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,eAAeA,CAC7BC,IAAkC,EAClCC,OAA8C,EAClC;EACZ;EACA;EACA,MAAMC,QAAQ,GAAGJ,iBAAiB,CAAC,CAAC;EACpC,IAAIK,YAAY,GAAG,CAAC,CAAC;EACrB,MAAMC,cAAc,GAAIC,KAA2B,IAAK;IACtD,IAAIA,KAAK,CAACC,QAAQ,IAAIH,YAAY,EAAE;MAClC;IACF;IACAA,YAAY,GAAGE,KAAK,CAACC,QAAQ;IAC7BL,OAAO,CAACI,KAAK,CAAC;EAChB,CAAC;EACDD,cAAc,CAACJ,IAAI,CAACO,cAAc,CAAC,CAAC,CAAC;EACrC,MAAMC,YAAY,GAAGR,IAAI,CAACS,iBAAiB,CAACL,cAAc,CAAC;EAC3DF,QAAQ,CAACQ,GAAG,CAAC,MAAMF,YAAY,CAACG,MAAM,CAAC,CAAC,CAAC;EACzC,IAAI;IACFX,IAAI,CAACY,KAAK,CAAC,CAAC;EACd,CAAC,CAAC,OAAOC,KAAK,EAAE;IACdX,QAAQ,CAACY,UAAU,CAAC,CAAC;IACrB,MAAMD,KAAK;EACb;EACA,IAAIE,SAAS,GAAG,KAAK;EAErB,OAAO,MAAM;IACX,IAAIA,SAAS,EAAE;MACb;IACF;IACAA,SAAS,GAAG,IAAI;IAChBb,QAAQ,CAACY,UAAU,CAAC,CAAC;IACrB,IAAId,IAAI,CAACgB,MAAM,KAAK,UAAU,EAAE;MAC9BhB,IAAI,CAACiB,KAAK,CAAC,CAAC;IACd;EACF,CAAC;AACH","ignoreList":[]}

package/lib/module/react/camera2d/GameLayer2D.js

@@ -0,0 +1,50 @@
+"use strict";
+
+/**
+ * `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 { Group } from '@shopify/react-native-skia';
+import { useDerivedValue } from 'react-native-reanimated';
+import { layerParallaxTransform2D, useGameWorldContext } from "../sprites/GameWorld2D.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+function assertFiniteParallax(value, axis) {
+  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
+}) {
+  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 /*#__PURE__*/_jsx(Group, {
+    transform: transform,
+    children: children
+  });
+}
+//# sourceMappingURL=GameLayer2D.js.map

package/lib/module/react/camera2d/GameLayer2D.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Group","useDerivedValue","layerParallaxTransform2D","useGameWorldContext","jsx","_jsx","assertFiniteParallax","value","axis","Number","isFinite","RangeError","String","GameLayer2D","parallax","x","y","children","viewport","camera","transform"],"sourceRoot":"../../../../src","sources":["react/camera2d/GameLayer2D.tsx"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,KAAK,QAAQ,4BAA4B;AAClD,SAASC,eAAe,QAAQ,yBAAyB;AAEzD,SAASC,wBAAwB,EAAEC,mBAAmB,QAAQ,2BAAwB;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAEvF,SAASC,oBAAoBA,CAACC,KAAa,EAAEC,IAAe,EAAQ;EAClE,IAAI,CAACC,MAAM,CAACC,QAAQ,CAACH,KAAK,CAAC,EAAE;IAC3B,MAAM,IAAII,UAAU,CAAC,wBAAwBH,IAAI,wBAAwBI,MAAM,CAACL,KAAK,CAAC,EAAE,CAAC;EAC3F;AACF;AAEA,OAAO,SAASM,WAAWA,CAAC;EAC1BC,QAAQ,GAAG;IAAEC,CAAC,EAAE,CAAC;IAAEC,CAAC,EAAE;EAAE,CAAC;EACzBC;AAKF,CAAC,EAAE;EACDX,oBAAoB,CAACQ,QAAQ,CAACC,CAAC,EAAE,GAAG,CAAC;EACrCT,oBAAoB,CAACQ,QAAQ,CAACE,CAAC,EAAE,GAAG,CAAC;EACrC,MAAM;IAAEE,QAAQ;IAAEC;EAAO,CAAC,GAAGhB,mBAAmB,CAAC,CAAC;EAClD,MAAMiB,SAAS,GAAGnB,eAAe,CAAC,MAAM;IACtC,SAAS;;IACT,OAAOC,wBAAwB,CAACiB,MAAM,EAAEZ,KAAK,EAAEW,QAAQ,CAACX,KAAK,EAAEO,QAAQ,CAACC,CAAC,EAAED,QAAQ,CAACE,CAAC,CAAC;EACxF,CAAC,CAAC;EACF,oBAAOX,IAAA,CAACL,KAAK;IAACoB,SAAS,EAAEA,SAAmB;IAAAH,QAAA,EAAEA;EAAQ,CAAQ,CAAC;AACjE","ignoreList":[]}

package/lib/module/react/camera2d/defineGameCamera2D.js

@@ -0,0 +1,30 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+/** Failure context for a camera selector/cut/validation failure (GS-CAMERA-02). */
+
+/** The static camera definition supplied to `GameView`. */
+
+/** Validate and return a camera definition. */
+export function defineGameCamera2D(definition) {
+  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;
+}
+//# sourceMappingURL=defineGameCamera2D.js.map

package/lib/module/react/camera2d/defineGameCamera2D.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["defineGameCamera2D","definition","select","Error","cut","undefined","onError"],"sourceRoot":"../../../../src","sources":["react/camera2d/defineGameCamera2D.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;;AAUA;;AAuBA;AACA,OAAO,SAASA,kBAAkBA,CAChCC,UAA0C,EACV;EAChC,IAAI,OAAOA,UAAU,CAACC,MAAM,KAAK,UAAU,EAAE;IAC3C,MAAM,IAAIC,KAAK,CAAC,+CAA+C,CAAC;EAClE;EACA,IAAIF,UAAU,CAACG,GAAG,KAAKC,SAAS,IAAI,OAAOJ,UAAU,CAACG,GAAG,KAAK,UAAU,EAAE;IACxE,MAAM,IAAID,KAAK,CAAC,gEAAgE,CAAC;EACnF;EACA,IAAIF,UAAU,CAACK,OAAO,KAAKD,SAAS,IAAI,OAAOJ,UAAU,CAACK,OAAO,KAAK,UAAU,EAAE;IAChF,MAAM,IAAIH,KAAK,CAAC,oEAAoE,CAAC;EACvF;EACA,OAAOF,UAAU;AACnB","ignoreList":[]}

package/lib/module/react/camera2d/usePresentedCameraBinding.js

@@ -0,0 +1,177 @@
+"use strict";
+
+/**
+ * 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 } from 'react-native-reanimated';
+import { interpolateCameraScalar2D } from "../../camera2d.js";
+import { cloneValidCamera2D } from "../../camera2d/validation.js";
+
+/** A UI-side camera binding for one session presentation. */
+
+function sameSceneName(first, second) {
+  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(definition, presented) {
+  const authoredPrevious = useSharedValue(undefined);
+  const authoredCurrent = useSharedValue(undefined);
+  const cutId = useSharedValue(0);
+  const sceneNameRef = useRef(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(() => {
+    // 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 = null;
+    const reportCameraError = (activeDefinition, phase, error, frame) => {
+      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 = () => {
+      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';
+        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 = {
+          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 => {
+        '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;
+}
+//# sourceMappingURL=usePresentedCameraBinding.js.map

package/lib/module/react/camera2d/usePresentedCameraBinding.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useEffect","useMemo","useRef","useSharedValue","interpolateCameraScalar2D","cloneValidCamera2D","sameSceneName","first","second","usePresentedCameraBinding","definition","presented","authoredPrevious","undefined","authoredCurrent","cutId","sceneNameRef","pendingCutRef","definitionRef","current","value","binding","lastReportedFailureKey","reportCameraError","activeDefinition","phase","error","frame","onError","message","Error","String","key","scene","markRecovered","commit","camera","explicitCut","selected","select","cut","pendingCut","sceneChanged","hardCut","present","alpha","dispose"],"sourceRoot":"../../../../src","sources":["react/camera2d/usePresentedCameraBinding.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/react/cleanupList.js

@@ -0,0 +1,38 @@
+"use strict";
+
+/**
+ * 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 function createCleanupList() {
+  const releases = [];
+  return {
+    add(release) {
+      releases.push(release);
+    },
+    releaseAll() {
+      const failures = [];
+      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');
+      }
+    }
+  };
+}
+//# sourceMappingURL=cleanupList.js.map

package/lib/module/react/cleanupList.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createCleanupList","releases","add","release","push","releaseAll","failures","index","length","error","AggregateError"],"sourceRoot":"../../../src","sources":["react/cleanupList.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAYA,OAAO,SAASA,iBAAiBA,CAAA,EAAgB;EAC/C,MAAMC,QAA2B,GAAG,EAAE;EACtC,OAAO;IACLC,GAAGA,CAACC,OAAmB,EAAQ;MAC7BF,QAAQ,CAACG,IAAI,CAACD,OAAO,CAAC;IACxB,CAAC;IACDE,UAAUA,CAAA,EAAS;MACjB,MAAMC,QAAmB,GAAG,EAAE;MAC9B,KAAK,IAAIC,KAAK,GAAGN,QAAQ,CAACO,MAAM,GAAG,CAAC,EAAED,KAAK,IAAI,CAAC,EAAEA,KAAK,IAAI,CAAC,EAAE;QAC5D,IAAI;UACFN,QAAQ,CAACM,KAAK,CAAC,GAAG,CAAC;QACrB,CAAC,CAAC,OAAOE,KAAK,EAAE;UACdH,QAAQ,CAACF,IAAI,CAACK,KAAK,CAAC;QACtB;MACF;MACAR,QAAQ,CAACO,MAAM,GAAG,CAAC;MACnB,IAAIF,QAAQ,CAACE,MAAM,KAAK,CAAC,EAAE;QACzB,MAAMF,QAAQ,CAAC,CAAC,CAAC;MACnB;MACA,IAAIA,QAAQ,CAACE,MAAM,GAAG,CAAC,EAAE;QACvB,MAAM,IAAIE,cAAc,CACtBJ,QAAQ,EACR,qCACF,CAAC;MACH;IACF;EACF,CAAC;AACH","ignoreList":[]}

package/lib/module/react/lifecycleSource.js

@@ -0,0 +1,49 @@
+"use strict";
+
+/**
+ * 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';
+const NOOP_DETACH = () => {};
+
+/**
+ * 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(session) {
+  return Object.freeze({
+    getStatus: () => session.status,
+    subscribe(listener) {
+      // 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 = /*#__PURE__*/createContext(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() {
+  return useContext(GameLifecycleContext);
+}
+//# sourceMappingURL=lifecycleSource.js.map

package/lib/module/react/lifecycleSource.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createContext","useContext","NOOP_DETACH","createGameLifecycleSource","session","Object","freeze","getStatus","status","subscribe","listener","subscription","addStatusListener","remove","GameLifecycleContext","undefined","GameLifecycleProvider","Provider","useGameLifecycleSource"],"sourceRoot":"../../../src","sources":["react/lifecycleSource.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,aAAa,EAAEC,UAAU,QAAQ,OAAO;AAUjD,MAAMC,WAAW,GAAGA,CAAA,KAAY,CAAC,CAAC;;AAElC;AACA;AACA;AACA;AACA,OAAO,SAASC,yBAAyBA,CACvCC,OAAqC,EAChB;EACrB,OAAOC,MAAM,CAACC,MAAM,CAAC;IACnBC,SAAS,EAAEA,CAAA,KAAMH,OAAO,CAACI,MAAM;IAC/BC,SAASA,CAACC,QAA6C,EAAc;MACnE;MACA;MACA,IAAIN,OAAO,CAACI,MAAM,KAAK,UAAU,EAAE,OAAON,WAAW;MACrD,MAAMS,YAAY,GAAGP,OAAO,CAACQ,iBAAiB,CAACF,QAAQ,CAAC;MACxD,OAAO,MAAMC,YAAY,CAACE,MAAM,CAAC,CAAC;IACpC;EACF,CAAC,CAAC;AACJ;AAEA,MAAMC,oBAAoB,gBAAGd,aAAa,CAAkCe,SAAS,CAAC;;AAEtF;AACA,OAAO,MAAMC,qBAAqB,GAAGF,oBAAoB,CAACG,QAAQ;;AAElE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,sBAAsBA,CAAA,EAAoC;EACxE,OAAOjB,UAAU,CAACa,oBAAoB,CAAC;AACzC","ignoreList":[]}