rn-gamekit 0.1.0 → 0.2.0

package/src/react/GameView.tsx

@@ -6,6 +6,7 @@ import {
   useMemo,
   useRef,
   type ComponentType,
+  type MutableRefObject,
   type ReactNode,
 } from 'react';
 import {
@@ -18,13 +19,18 @@ import {
 import { useFrameCallback, useSharedValue, type SharedValue } from 'react-native-reanimated';
 import { scheduleOnRN } from 'react-native-worklets';
 
+import type { CameraCut2D } from '../camera2d';
 import type { InputMap, SceneMap } from '../definition/types';
 import type { AssetGroupMap, LoadedAssets } from '../assets/types';
 import type { CommitFrame, GameSession } from '../core/session/types';
 import type { ResolvedViewport2D } from '../viewport2d';
 import { advanceAlpha } from './alphaClock';
+import type { GameCamera2DDefinition } from './camera2d/defineGameCamera2D';
+import { usePresentedCameraBinding } from './camera2d/usePresentedCameraBinding';
 import { bindAppLifecycle } from './bindAppLifecycle';
 import { bindGameSession } from './bindGameSession';
+import { createCleanupList } from './cleanupList';
+import { createGameLifecycleSource, GameLifecycleProvider } from './lifecycleSource';
 import type { GameViewInstrumentation } from './instrumentation';
 import { bindingForViewport, type ViewportBinding } from './viewportBinding';
 
@@ -42,6 +48,12 @@ export interface GameRendererProps<
   readonly alpha: SharedValue<number>;
   /** Latest resolved viewport shared with the input adapter. */
   readonly viewport: SharedValue<ResolvedViewport2D | undefined>;
+  /**
+   * The presented camera cut (T12.3), present only when the game opts in
+   * via `camera2D`. Undefined until the first committed camera; camera
+   * movement never re-renders React.
+   */
+  readonly camera?: SharedValue<CameraCut2D | undefined>;
   /** The stable loaded asset lease (T7.5); shape-only renderers omit it. */
   readonly assets?: LoadedAssets<TAssets>;
 }
@@ -63,6 +75,13 @@ export interface GameViewProps<
   readonly presentationKey?: string | number;
   /** The stable loaded asset lease; shape-only games omit it. */
   readonly assets?: LoadedAssets<TAssets>;
+  /**
+   * Optional static camera binding (T12.3). When absent, the exact current
+   * viewport path is preserved. GameView owns the presented camera; the
+   * renderer receives it as a prop and the pointer adapter discovers it
+   * from the mounted surface.
+   */
+  readonly camera2D?: GameCamera2DDefinition<CommitFrame<TScenes>>;
   /** Stable Skia renderer component for the session's scene snapshots. */
   readonly renderer: ComponentType<GameRendererProps<TScenes, TAssets>>;
   /** Optional measurement callbacks for the Performance Lab (F1). */
@@ -89,6 +108,19 @@ export interface GameViewport {
 
 export const GameViewportContext = createContext<GameViewport | null>(null);
 
+/**
+ * Context supplying the presented camera to pointer input children.
+ *
+ * The shared value is owned by `GameView` (fed by the per-session
+ * presentation), so renderer and pointer adapter observe the same camera
+ * generation. `undefined` when the game has no camera.
+ */
+export interface GameCameraSurface {
+  readonly presented: SharedValue<CameraCut2D | undefined> | undefined;
+}
+
+export const GameCameraContext = createContext<GameCameraSurface | null>(null);
+
 /**
  * Mount a headless GameSession into a Skia canvas.
  *
@@ -120,17 +152,27 @@ function GamePresentation<
   renderer,
   viewportValue,
   instrumentationRef,
+  instrumentation,
+  cameraDefinition,
+  presentedCamera,
 }: {
   readonly game: GameSession<TScenes, TInput>;
   readonly assets: LoadedAssets<TAssets> | undefined;
   readonly renderer: ComponentType<GameRendererProps<TScenes, TAssets>>;
   readonly viewportValue: SharedValue<ResolvedViewport2D | undefined>;
-  readonly instrumentationRef: { readonly current: GameViewInstrumentation | undefined };
+  readonly instrumentationRef: MutableRefObject<GameViewInstrumentation | undefined>;
+  readonly instrumentation: GameViewInstrumentation | undefined;
+  readonly cameraDefinition: GameCamera2DDefinition<CommitFrame<TScenes>> | undefined;
+  readonly presentedCamera: SharedValue<CameraCut2D | undefined>;
 }) {
   const Renderer = renderer;
   const frame = useSharedValue<CommitFrame<TScenes>>(() => game.getRenderFrame());
   const alpha = useSharedValue(0);
-  const running = useSharedValue(true);
+  const cameraBinding = usePresentedCameraBinding(cameraDefinition, presentedCamera);
+  // T10.6: the presentation gate mirrors CORE status, not callback-local
+  // state — a direct session.pause() freezes presentation too. Idle holds
+  // until the binding starts the session.
+  const running = useSharedValue(game.status === 'running');
   // Binding epoch: bumped per (re)subscription so a replacement session whose
   // revision restarts at zero is still accepted by the UI clock.
   const epoch = useSharedValue(0);
@@ -140,36 +182,70 @@ function GamePresentation<
   // report the FIRST UI frame that saw a new commit.
   const observedRevision = useSharedValue(-1);
   const observedEpoch = useSharedValue(-1);
+  // GS-REACT-01: mirror whether the UI-observation diagnostic is enabled so
+  // the frame callback branches BEFORE timestamp reads and RN scheduling.
+  // Updated alongside the ref (same effect), never read during render.
+  const instrumentationEnabled = useSharedValue(
+    instrumentation?.onUiRevisionObserved !== undefined,
+  );
 
+  // GS-REACT-01: the ref and the UI-side enabled mirror update together so
+  // replacing instrumentation never restarts the session and the frame
+  // callback can branch before any timestamp read or RN scheduling.
   useEffect(() => {
-    epoch.value += 1;
-    // RF6: the frame is seeded at mount from this session; the keyed remount
-    // guarantees the renderer below never reads the previous session's frame.
-    frame.value = game.getRenderFrame();
-    const cleanupBinding = bindGameSession(game, (nextFrame) => {
-      frame.value = nextFrame;
-      instrumentationRef.current?.onPresentCommit?.(nextFrame.revision, Date.now());
-    });
-    const cleanupLifecycle = bindAppLifecycle(AppState, {
-      getStatus: () => game.status,
-      pause: () => {
-        running.value = false;
-        if (game.status !== 'disposed') {
-          game.pause();
-        }
-      },
-      resume: () => {
-        if (game.status !== 'disposed') {
-          game.start();
-          running.value = true;
-        }
-      },
-    });
+    instrumentationRef.current = instrumentation;
+    instrumentationEnabled.value = instrumentation?.onUiRevisionObserved !== undefined;
+  }, [instrumentation, instrumentationEnabled, instrumentationRef]);
+
+  useEffect(() => {
+    // GS-REACT-02: the mount wiring is one transaction. Every acquired
+    // subscription registers its release as it completes, so a failing
+    // stage unwinds everything before it; unmount releases all stages in
+    // reverse order without stopping at the first failure.
+    const cleanups = createCleanupList();
+    try {
+      epoch.value += 1;
+      // RF6: the frame is seeded at mount from this session; the keyed remount
+      // guarantees the renderer below never reads the previous session's frame.
+      frame.value = game.getRenderFrame();
+      // T10.6: subscribe to core status BEFORE the mount-time start, so the
+      // idle -> running transition cannot be missed and every lifecycle change
+      // (manual pause, app background, error path) drives the same mirror.
+      running.value = game.status === 'running';
+      const statusSubscription = game.addStatusListener((status) => {
+        running.value = status === 'running';
+      });
+      cleanups.add(() => statusSubscription.remove());
+      const cleanupBinding = bindGameSession(game, (nextFrame) => {
+        frame.value = nextFrame;
+        cameraBinding.commit(nextFrame);
+        instrumentationRef.current?.onPresentCommit?.(nextFrame.revision, Date.now());
+      });
+      cleanups.add(cleanupBinding);
+      const cleanupLifecycle = bindAppLifecycle(AppState, {
+        getStatus: () => game.status,
+        pause: () => {
+          if (game.status !== 'disposed') {
+            game.pause();
+          }
+        },
+        resume: () => {
+          if (game.status !== 'disposed') {
+            game.start();
+          }
+        },
+        addStatusListener: (listener) => game.addStatusListener(listener),
+      });
+      cleanups.add(cleanupLifecycle);
+      cleanups.add(() => cameraBinding.dispose());
+    } catch (error) {
+      cleanups.releaseAll();
+      throw error;
+    }
     return () => {
-      cleanupLifecycle();
-      cleanupBinding();
+      cleanups.releaseAll();
     };
-  }, [epoch, frame, game, running]);
+  }, [cameraBinding, epoch, frame, game, running]);
 
   // F1: the first UI frame that sees a new commit revision is reported back
   // to the RN runtime through scheduleOnRN — never by calling the JS hook
@@ -190,7 +266,12 @@ function GamePresentation<
     if (observedEpoch.value !== epoch.value || observedRevision.value !== envelope.revision) {
       observedEpoch.value = epoch.value;
       observedRevision.value = envelope.revision;
-      scheduleOnRN(reportUiObserved, envelope.revision, Date.now());
+      // GS-REACT-01: without an enabled observer there is no timestamp
+      // read and no RN scheduling — the disabled path performs no timing
+      // reads, packet creation, or cross-runtime calls.
+      if (instrumentationEnabled.value) {
+        scheduleOnRN(reportUiObserved, envelope.revision, Date.now());
+      }
     }
     const previousState = {
       epoch: clockEpoch.value,
@@ -209,6 +290,7 @@ function GamePresentation<
     clockEpoch.value = nextState.epoch;
     clockRevision.value = nextState.revision;
     alpha.value = nextState.alpha;
+    cameraBinding.present(alpha.value);
   });
 
   return (
@@ -216,6 +298,7 @@ function GamePresentation<
       frame={frame}
       alpha={alpha}
       viewport={viewportValue}
+      {...(cameraDefinition === undefined ? {} : { camera: presentedCamera })}
       {...(assets === undefined ? {} : { assets })}
     />
   );
@@ -249,8 +332,13 @@ export function GameView<
   children,
   style,
   instrumentation,
+  camera2D,
 }: GameViewProps<TScenes, TInput, TAssets>) {
   const instrumentationRef = useRef(instrumentation);
+  // T12.3: GameView owns the presented camera shared value so renderer and
+  // pointer adapter observe the same generation. Camera movement writes
+  // only shared values; React never re-renders for it.
+  const presentedCamera = useSharedValue<CameraCut2D | undefined>(undefined);
 
   const bindingRef = useRef<ViewportBinding | null>(null);
   bindingRef.current = bindingForViewport(game.viewport, bindingRef.current);
@@ -260,10 +348,14 @@ export function GameView<
     () => ({ binding, viewport: viewportValue }),
     [binding, viewportValue],
   );
-
-  useEffect(() => {
-    instrumentationRef.current = instrumentation;
-  }, [instrumentation]);
+  const cameraContext = useMemo<GameCameraSurface>(
+    () => ({ presented: camera2D === undefined ? undefined : presentedCamera }),
+    [camera2D, presentedCamera],
+  );
+  // T20.3: one lifecycle source per session — replacement sessions replace
+  // the source, so consumers bound to the old generation never observe the
+  // new one (the presentation subtree is remounted per session, RF6).
+  const lifecycle = useMemo(() => createGameLifecycleSource(game), [game]);
 
   useEffect(() => {
     viewportValue.value = binding.resolved;
@@ -278,34 +370,41 @@ export function GameView<
 
   return (
     <GameViewportContext.Provider value={viewportContext}>
-      <View
-        style={[styles.surface, style]}
-        onLayout={(event) => {
-          const { width, height } = event.nativeEvent.layout;
-          binding.setSurfaceSize({ width, height });
-          viewportValue.value = binding.resolved;
-        }}
-      >
-        <Canvas style={StyleSheet.absoluteFill}>
-          {/* RF6/T8.6: the per-session presentation is keyed by an explicit
-              presentation key when provided, otherwise by a stable
-              per-session identity — never object stringification — so the
-              frame/alpha/epoch initialize before the renderer can run. */}
-          <GamePresentation
-            key={presentationKey ?? sessionPresentationId(game)}
-            game={game}
-            assets={assets}
-            renderer={Renderer}
-            viewportValue={viewportValue}
-            instrumentationRef={instrumentationRef}
-          />
-        </Canvas>
-        {children === undefined ? null : (
-          <View pointerEvents="box-none" style={StyleSheet.absoluteFill}>
-            {children}
-          </View>
-        )}
-      </View>
+      <GameCameraContext.Provider value={cameraContext}>
+        <GameLifecycleProvider value={lifecycle}>
+          <View
+            style={[styles.surface, style]}
+            onLayout={(event) => {
+              const { width, height } = event.nativeEvent.layout;
+              binding.setSurfaceSize({ width, height });
+              viewportValue.value = binding.resolved;
+            }}
+          >
+          <Canvas style={StyleSheet.absoluteFill}>
+            {/* RF6/T8.6: the per-session presentation is keyed by an explicit
+                presentation key when provided, otherwise by a stable
+                per-session identity — never object stringification — so the
+                frame/alpha/epoch initialize before the renderer can run. */}
+            <GamePresentation
+              key={presentationKey ?? sessionPresentationId(game)}
+              game={game}
+              assets={assets}
+              renderer={Renderer}
+              viewportValue={viewportValue}
+              instrumentationRef={instrumentationRef}
+              instrumentation={instrumentation}
+              cameraDefinition={camera2D}
+              presentedCamera={presentedCamera}
+            />
+          </Canvas>
+          {children === undefined ? null : (
+            <View pointerEvents="box-none" style={StyleSheet.absoluteFill}>
+              {children}
+            </View>
+          )}
+        </View>
+        </GameLifecycleProvider>
+      </GameCameraContext.Provider>
     </GameViewportContext.Provider>
   );
 }