rn-gamekit 0.1.0 → 0.2.1

package/src/react/particles/useParticlePresentation.ts

@@ -0,0 +1,261 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useSharedValue, type SharedValue } from 'react-native-reanimated';
+
+import type {
+  GameLifecycleSource,
+  GameSessionStatus,
+} from '../../core/session/types';
+import type {
+  ParticleSystem,
+  ParticleUiRegistry,
+} from '../../particles/types';
+
+export type SessionStatus = GameSessionStatus;
+
+/**
+ * What the presentation hook hands to views (T15-SF1): a SCALAR active-time
+ * clock written every running frame, plus the bounded emission registry
+ * transferred only when membership changes. No per-frame bulk arrays cross
+ * the runtime boundary.
+ */
+export interface ParticlePresentation {
+  readonly clock: SharedValue<number>;
+  readonly registry: SharedValue<ParticleUiRegistry>;
+  /** Imperative manual-pause control, independent of the session source. */
+  setManualPaused(paused: boolean): void;
+}
+
+const EMPTY_REGISTRY: ParticleUiRegistry = Object.freeze({
+  registryRevision: -1,
+  activeClock: 0,
+  effects: Object.freeze({}),
+});
+
+function defaultSchedule(tick: () => void): () => void {
+  const id = requestAnimationFrame(tick);
+  return () => cancelAnimationFrame(id);
+}
+
+/**
+ * Own THE exclusive presentation clock for one system (T15-F1/T15-RF3).
+ *
+ * Per-frame runtime work is ONE scalar write (`clock.value`); the bounded
+ * emission registry is transferred only when membership changes (T15-SF1).
+ *
+ * Pause sources are applied through ONE effect-owned control so transitions
+ * stop/start the scheduler immediately — including while the driver is idle
+ * or asleep (T15-SF3). Scheduling runs only when the system is running AND
+ * at least one particle is active; it fully stops otherwise and restarts
+ * from resume/wake transitions.
+ */
+export function useParticlePresentation(
+  system: ParticleSystem,
+  options?: {
+    /**
+     * The owning session's lifecycle source (T20.3) — the preferred way to
+     * follow a session. Supplied by `GameView` through
+     * `useGameLifecycleSource()`. When set, it takes precedence over the
+     * legacy `sessionStatus`/`sessionSubscribe` options.
+     */
+    readonly lifecycle?: GameLifecycleSource;
+    /** Legacy reader: read the owning session's status each frame / on change. */
+    readonly sessionStatus?: () => SessionStatus;
+    /** Legacy reactive subscription for session status changes. */
+    readonly sessionSubscribe?: (
+      listener: (status: SessionStatus) => void,
+    ) => () => void;
+    /** Independent user/lab pause reader; a running session cannot cancel it. */
+    readonly manualPaused?: () => boolean;
+    /** Injectable scheduler for deterministic headless/mounted tests. */
+    readonly schedule?: (tick: () => void) => () => void;
+    /** Injectable clock for deterministic deltas in tests. */
+    readonly now?: () => number;
+  },
+): ParticlePresentation {
+  const binding = useMemo(() => system.bindPresentation(), [system]);
+  const clock = useSharedValue(binding.activeClock);
+  const registry = useSharedValue<ParticleUiRegistry>(EMPTY_REGISTRY);
+  // T20F-R2: the driver effect must key ONLY on ownership inputs. Shared
+  // values are stable in Reanimated; the refs keep the effect closures
+  // pointing at the latest instance even where mocks hand back fresh objects.
+  const clockRef = useRef(clock);
+  const registryRef = useRef(registry);
+  useEffect(() => {
+    clockRef.current = clock;
+    registryRef.current = registry;
+  }, [clock, registry]);
+
+  // Latest-source refs (frame loop + reactive callbacks read these).
+  const lifecycleRef = useRef(options?.lifecycle);
+  lifecycleRef.current = options?.lifecycle;
+  const sessionRef = useRef(options?.sessionStatus);
+  sessionRef.current = options?.sessionStatus;
+  const manualReaderRef = useRef(options?.manualPaused);
+  manualReaderRef.current = options?.manualPaused;
+  const scheduleRef = useRef(options?.schedule ?? defaultSchedule);
+  const nowRef = useRef(options?.now ?? (() => Date.now()));
+  // Manual pause lives OUTSIDE render so the imperative setter is stable and
+  // reactive without depending on animation frames.
+  const manualPausedRef = useRef(false);
+
+  // Stable control ref owned by the effect (T15-TF2): the public setter and
+  // every pause transition route through this without capturing stale state.
+  const controlRef = useRef<{
+    applyPause(): void;
+    syncRegistry(): void;
+    updateScheduling(): void;
+  }>({ applyPause: () => {}, syncRegistry: () => {}, updateScheduling: () => {} });
+
+  // T20F-R2: STABLE across re-renders — it reads only refs plus `system`, so
+  // the driver effect below keeps a single acquire/subscription for the
+  // lifetime of one system instead of rebinding on every parent render.
+  const applyCombinedPause = useCallback((): void => {
+    if (system.status === 'disposed') return;
+    const session = lifecycleRef.current
+      ? lifecycleRef.current.getStatus()
+      : (sessionRef.current?.() ?? 'running');
+    const effectivePaused =
+      manualPausedRef.current ||
+      (manualReaderRef.current?.() ?? false) ||
+      session === 'paused' ||
+      session === 'disposed';
+    if (effectivePaused) system.pauseIfRunning();
+    else system.resumeIfPaused();
+  }, [system]);
+
+  useEffect(() => {
+    const driver = binding.acquireDriver();
+    let cancelled = false;
+    let cancelSchedule: (() => void) | null = null;
+    let last = nowRef.current();
+
+    const stopScheduling = (): void => {
+      if (cancelSchedule) {
+        cancelSchedule();
+        cancelSchedule = null;
+      }
+    };
+
+    const startScheduling = (): void => {
+      if (cancelled || cancelSchedule !== null) return;
+      last = nowRef.current();
+      let canceller: (() => void) | null = null;
+      // The executed tick clears its own handle so the next frame may be
+      // scheduled from inside stepFrame (self-perpetuating loop).
+      canceller = scheduleRef.current(() => {
+        if (cancelSchedule === canceller) cancelSchedule = null;
+        stepFrame();
+      });
+      cancelSchedule = canceller ?? null;
+    };
+
+    const syncRegistry = (): void => {
+      if (binding.registryRevision !== registryRef.current.value.registryRevision) {
+        // Bounded transfer: only on membership changes (T15-SF1). Expiration
+        // bumps the revision too, so the terminal prune ships (T15-TF1).
+        registryRef.current.value = binding.buildUiRegistry();
+      }
+    };
+
+    const stepFrame = (): void => {
+      if (cancelled) return;
+      const now = nowRef.current();
+      const dt = Math.max(0, Math.min((now - last) / 1000, 0.1));
+      last = now;
+
+      applyCombinedPause();
+      driver.step(dt);
+      syncRegistry();
+
+      // ALWAYS publish the terminal scalar — including the step that
+      // transitions to zero actives, so renderers hide the expired record
+      // before we sleep (T15-TF1).
+      clockRef.current.value = binding.activeClock;
+
+      // T20L-R2: the frame path enforces the same running guard as the
+      // reactive path — a paused step cannot expire particles, so scheduling
+      // another frame while paused would spin the driver forever.
+      if (system.status === 'running' && !driver.isIdle()) {
+        startScheduling();
+        return;
+      }
+      // Paused or idle: fully stop; resume transitions and emissions restart us.
+      stopScheduling();
+    };
+
+    // Effect-owned scheduling control (T15-TF2): pause transitions call this
+    // synchronously via the stable ref.
+    controlRef.current = {
+      applyPause: applyCombinedPause,
+      syncRegistry,
+      updateScheduling(): void {
+        applyCombinedPause();
+        syncRegistry();
+        if (cancelled || system.status === 'disposed') {
+          stopScheduling();
+          return;
+        }
+        // Schedule only when running AND something is active.
+        if (system.status === 'running' && !driver.isIdle()) {
+          startScheduling();
+        } else {
+          stopScheduling();
+        }
+      },
+    };
+
+    // Reactive pause application + registry sync + reschedule.
+    driver.setWakeListener(() => controlRef.current.updateScheduling());
+
+    // Initial synchronous application at bind time.
+    applyCombinedPause();
+
+    stepFrame();
+
+    return () => {
+      cancelled = true;
+      driver.setWakeListener(null);
+      stopScheduling();
+      driver.release();
+    };
+  }, [system, binding, applyCombinedPause]);
+
+  // T20F-R2: the lifecycle subscription is keyed by the SOURCE identity, not
+  // by render — one subscribe/detach per system generation. Status changes
+  // route through the effect-owned control so pause transitions stay
+  // synchronous without rebinding the driver.
+  const lifecycleSource = options?.lifecycle ?? null;
+  const legacySubscribe = options?.sessionSubscribe ?? null;
+  useEffect(() => {
+    const onSessionStatus = (status: SessionStatus): void => {
+      sessionRef.current = () => status;
+      controlRef.current.updateScheduling();
+    };
+    const detach =
+      lifecycleSource !== null
+        ? lifecycleSource.subscribe(onSessionStatus)
+        : legacySubscribe?.(onSessionStatus);
+    // T20F-R2 re-review: a REPLACED source may already be paused (or running)
+    // — apply its current status immediately instead of waiting for its next
+    // transition, so paused emissions are never accepted in between.
+    controlRef.current.updateScheduling();
+    return detach;
+  }, [lifecycleSource, legacySubscribe]);
+
+  // Initial registry transfer at bind time.
+  useEffect(() => {
+    registryRef.current.value = binding.buildUiRegistry();
+  }, [binding]);
+
+  const setManualPaused = useCallback(
+    (paused: boolean): void => {
+      manualPausedRef.current = paused;
+      // Route through the effect-owned control: applies combined sources AND
+      // stops/starts the scheduler immediately (T15-TF2).
+      controlRef.current.updateScheduling();
+    },
+    [],
+  );
+
+  return { clock, registry, setManualPaused };
+}

package/src/react/pointerBinding.ts

@@ -1,6 +1,16 @@
+import type { CameraCut2D } from '../camera2d';
+import { logicalToWorld2D } from '../camera2d';
 import type { InputController } from '../core/input/types';
 import type { Point2D } from '../geometry/types';
 import { containsSurfacePoint, surfaceToWorld, type ResolvedViewport2D } from '../viewport2d';
+/** One accepted surface -> world conversion with its exact inputs (T12-TF3). */
+export interface PointerSample2D {
+  readonly surface: { readonly x: number; readonly y: number };
+  readonly viewport: ResolvedViewport2D;
+  readonly camera: CameraCut2D | undefined;
+  readonly world: { readonly x: number; readonly y: number };
+}
+
 import type { CoalescedPointerEvent } from './pointerCoalescer';
 
 /**
@@ -9,6 +19,12 @@ import type { CoalescedPointerEvent } from './pointerCoalescer';
  * 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.
+ *
+ * T12-F4: the packet also carries the presented camera cut sampled AT
+ * EVENT TIME on the UI runtime. JS inverts through that stamp — never a
+ * later lazy read — so the world coordinate matches the camera under the
+ * finger when the touch happened, even while the camera follows, zooms,
+ * rotates, or shakes.
  */
 export type PointerPacket = CoalescedPointerEvent & {
   /** Monotonic adapter-owned binding generation (F3 follow-up). */
@@ -19,6 +35,8 @@ export type PointerPacket = CoalescedPointerEvent & {
   readonly seq: number;
   /** UI-runtime timestamp of the forward (F1 latency causality). */
   readonly atMs: number;
+  /** The presented camera cut at event time; absent for no-camera games. */
+  readonly camera?: CameraCut2D | undefined;
 };
 
 /** Monotonic generation source for factory-created bindings (F3). */
@@ -32,6 +50,12 @@ export interface PointerBindingIdentity<TName extends string> {
   readonly action: TName;
   /** Identity token for the viewport provider (changes on layout owner swaps). */
   readonly viewport: unknown;
+  /**
+   * Identity token for the presented camera provider (T12.4). Changes when
+   * the camera surface is replaced, so a fresh binding generation stamps
+   * packets under the new camera owner.
+   */
+  readonly camera: unknown;
 }
 
 /** A binding plus the identity it was created for. */
@@ -53,7 +77,8 @@ export function createPointerBinding<TName extends string>(
     previous !== undefined &&
     previous.identity.input === identity.input &&
     previous.identity.action === identity.action &&
-    previous.identity.viewport === identity.viewport
+    previous.identity.viewport === identity.viewport &&
+    previous.identity.camera === identity.camera
   ) {
     return { entry: previous, created: false };
   }
@@ -78,9 +103,11 @@ export function createPointerBinding<TName extends string>(
  * Platform-neutral pointer binding seam.
  *
  * It converts gesture positions from surface coordinates into logical world
- * coordinates through the current resolved viewport, rejects begins that
+ * coordinates through the current resolved viewport (T12.4: and through the
+ * currently presented camera when the game has one), rejects begins that
  * start in `fit` letterbox space, and forwards semantic events into the
- * session input buffer. The high-level `handleTouches*` methods mirror the
+ * session input buffer. Containment always happens BEFORE camera inversion:
+ * letterbox space is rejected regardless of the camera. 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.
@@ -89,6 +116,7 @@ export class PointerBinding<TActionName extends string> {
   readonly #action: TActionName;
   readonly #input: InputController<TActionName>;
   readonly #getViewport: () => ResolvedViewport2D | undefined;
+  readonly #onSample: ((sample: PointerSample2D) => void) | undefined;
   readonly #generation: number;
   #disposed = false;
 
@@ -97,13 +125,39 @@ export class PointerBinding<TActionName extends string> {
     input: InputController<TActionName>,
     getViewport: () => ResolvedViewport2D | undefined,
     generation: number,
+    onSample?: (sample: PointerSample2D) => void,
   ) {
     this.#action = action;
     this.#input = input;
     this.#getViewport = getViewport;
+    this.#onSample = onSample;
     this.#generation = generation;
   }
 
+  /**
+   * Surface -> world through the viewport and the EVENT-TIME camera cut
+   * (T12.4, T12-F4).
+   *
+   * The frozen order: inverse viewport first, then inverse camera, using
+   * the camera stamp sampled by the UI worklet when the touch happened —
+   * the same camera the renderer drew at that moment. Without a camera
+   * stamp this is exactly `surfaceToWorld`.
+   */
+  #toWorld(viewport: ResolvedViewport2D, point: Point2D, camera: CameraCut2D | undefined): Point2D {
+    const logical = surfaceToWorld(viewport, point);
+    const world =
+      camera === undefined ? logical : logicalToWorld2D(logical, camera.camera, viewport.visibleLogicalBounds);
+    // T12-TF3: report one accepted conversion with its exact inputs and
+    // output — the lab measures the round trip from the real pipeline.
+    this.#onSample?.({
+      surface: { x: point.x, y: point.y },
+      viewport,
+      camera,
+      world,
+    });
+    return world;
+  }
+
   /**
    * The monotonic adapter-owned generation this binding belongs to (F3).
    * Generations never reset to zero, so a replacement binding and the
@@ -129,13 +183,13 @@ export class PointerBinding<TActionName extends string> {
     }
     switch (packet.kind) {
       case 'begin':
-        this.handleTouchesDown(packet.pointerId, packet.x, packet.y);
+        this.handleTouchesDown(packet.pointerId, packet.x, packet.y, packet.camera);
         break;
       case 'move':
-        this.handleTouchesMove(packet.pointerId, packet.x, packet.y);
+        this.handleTouchesMove(packet.pointerId, packet.x, packet.y, packet.camera);
         break;
       case 'end':
-        this.handleTouchesUp(packet.pointerId, packet.x, packet.y);
+        this.handleTouchesUp(packet.pointerId, packet.x, packet.y, packet.camera);
         break;
       case 'cancel':
         this.handleTouchesCancelled();
@@ -150,7 +204,11 @@ export class PointerBinding<TActionName extends string> {
    * 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 {
+  begin(
+    pointerId: number,
+    surfacePoint: Point2D,
+    camera?: CameraCut2D,
+  ): boolean {
     if (this.#disposed) {
       return false;
     }
@@ -161,12 +219,12 @@ export class PointerBinding<TActionName extends string> {
     if (!containsSurfacePoint(viewport, surfacePoint)) {
       return false;
     }
-    this.#input.begin(this.#action, pointerId, surfaceToWorld(viewport, surfacePoint));
+    this.#input.begin(this.#action, pointerId, this.#toWorld(viewport, surfacePoint, camera));
     return true;
   }
 
   /** Move a pointer. Conversion remains unbounded outside content bounds. */
-  move(pointerId: number, surfacePoint: Point2D): void {
+  move(pointerId: number, surfacePoint: Point2D, camera?: CameraCut2D): void {
     if (this.#disposed) {
       return;
     }
@@ -174,7 +232,7 @@ export class PointerBinding<TActionName extends string> {
     if (viewport === undefined) {
       return;
     }
-    this.#input.move(this.#action, pointerId, surfaceToWorld(viewport, surfacePoint));
+    this.#input.move(this.#action, pointerId, this.#toWorld(viewport, surfacePoint, camera));
   }
 
   /** End a pointer. The owning pointer is released by the input buffer. */
@@ -194,13 +252,13 @@ export class PointerBinding<TActionName extends string> {
   }
 
   /** Handle a touch-down gesture event with a surface position. */
-  handleTouchesDown(pointerId: number, x: number, y: number): boolean {
-    return this.begin(pointerId, { x, y });
+  handleTouchesDown(pointerId: number, x: number, y: number, camera?: CameraCut2D): boolean {
+    return this.begin(pointerId, { x, y }, camera);
   }
 
   /** Handle a touch-move gesture event with a surface position. */
-  handleTouchesMove(pointerId: number, x: number, y: number): void {
-    this.move(pointerId, { x, y });
+  handleTouchesMove(pointerId: number, x: number, y: number, camera?: CameraCut2D): void {
+    this.move(pointerId, { x, y }, camera);
   }
 
   /**
@@ -209,8 +267,8 @@ export class PointerBinding<TActionName extends string> {
    * 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 });
+  handleTouchesUp(pointerId: number, x: number, y: number, camera?: CameraCut2D): void {
+    this.move(pointerId, { x, y }, camera);
     this.end(pointerId);
   }
 

package/src/react/pointerCamera.ts

@@ -0,0 +1,33 @@
+/**
+ * Event-time camera selection for pointer packets (T12-SF1, T12-TF1).
+ *
+ * Internal module (not part of the public barrel): the ONE rule that pairs
+ * a forwarded pointer event with the presented camera at the event's own
+ * native sample. `GamePointerInput` and the focused tests import the same
+ * function, so the test can never drift from production.
+ */
+import type { CameraCut2D } from '../camera2d';
+import type { CoalescedPointerEvent } from './pointerCoalescer';
+
+/** A move's explicit capture: `captured: true` even when the value is
+ * undefined, so a captured-undefined camera is distinguishable from "no
+ * stamp" and never falls back to a later presentation (T12-SF1). */
+export interface PointerCameraCapture2D {
+  readonly captured: true;
+  readonly value: CameraCut2D | undefined;
+}
+
+/** The event-time camera for one forwarded event (worklet-safe). */
+export function packetCameraFor(
+  forwarded: CoalescedPointerEvent,
+  presented: CameraCut2D | undefined,
+): CameraCut2D | undefined {
+  'worklet';
+  if (forwarded.kind === 'move') {
+    const stamp = forwarded.stamp as PointerCameraCapture2D | undefined;
+    // A move ALWAYS carries its capture (possibly undefined): a captured
+    // undefined stays undefined — never fall back to a later camera.
+    return stamp !== undefined ? stamp.value : presented;
+  }
+  return presented;
+}

package/src/react/pointerCoalescer.ts

@@ -24,7 +24,19 @@
 
 export type CoalescedPointerEvent =
   | { readonly kind: 'begin'; readonly pointerId: number; readonly x: number; readonly y: number }
-  | { readonly kind: 'move'; readonly pointerId: number; readonly x: number; readonly y: number }
+  | {
+      readonly kind: 'move';
+      readonly pointerId: number;
+      readonly x: number;
+      readonly y: number;
+      /**
+       * Opaque event-time stamp (T12-RF3): captured with the native sample
+       * that produced this move and carried through deferral, so the
+       * presenter pairs coordinates and presentation state from the SAME
+       * native sample, never from a later flush frame.
+       */
+      readonly stamp?: unknown;
+    }
   | { readonly kind: 'end'; readonly pointerId: number; readonly x: number; readonly y: number }
   | { readonly kind: 'cancel' };
 
@@ -47,7 +59,7 @@ interface ActivePointer {
   readonly pointerId: number;
   readonly lastForwardMs: number;
   readonly pendingMove:
-    | { readonly x: number; readonly y: number }
+    | { readonly x: number; readonly y: number; readonly stamp?: unknown }
     | undefined;
 }
 
@@ -60,11 +72,20 @@ export interface PointerCoalescerState {
 /** One native touch input consumed by the pure coalescer reducer. */
 export type PointerCoalescerInput =
   | {
-      readonly kind: 'down' | 'move' | 'up';
+      readonly kind: 'down' | 'up';
+      readonly pointerId: number;
+      readonly x: number;
+      readonly y: number;
+      readonly nowMs: number;
+    }
+  | {
+      readonly kind: 'move';
       readonly pointerId: number;
       readonly x: number;
       readonly y: number;
       readonly nowMs: number;
+      /** Event-time stamp paired with this native sample (T12-RF3). */
+      readonly stamp?: unknown;
     }
   | { readonly kind: 'cancel'; readonly nowMs: number }
   | { readonly kind: 'flush'; readonly nowMs: number }
@@ -158,6 +179,7 @@ export function reducePointerCoalescer(
           pointerId: active.pointerId,
           x: active.pendingMove.x,
           y: active.pendingMove.y,
+          stamp: active.pendingMove.stamp,
         },
       ],
     };
@@ -182,12 +204,15 @@ export function reducePointerCoalescer(
     };
   }
 
+  // The remaining branch is the move input (down/up/cancel/flush/reset
+  // returned above); its optional stamp rides with the sample.
+  const moveInput = input as Extract<PointerCoalescerInput, { kind: 'move' }>;
   const shouldForward =
-    input.nowMs - active.lastForwardMs >= state.maxMoveIntervalMs;
+    moveInput.nowMs - active.lastForwardMs >= state.maxMoveIntervalMs;
   const nextActive: ActivePointer = {
-    pointerId: input.pointerId,
-    lastForwardMs: shouldForward ? input.nowMs : active.lastForwardMs,
-    pendingMove: shouldForward ? undefined : { x: input.x, y: input.y },
+    pointerId: moveInput.pointerId,
+    lastForwardMs: shouldForward ? moveInput.nowMs : active.lastForwardMs,
+    pendingMove: shouldForward ? undefined : { x: moveInput.x, y: moveInput.y, stamp: moveInput.stamp },
   };
   return {
     state: { ...state, active: nextActive },
@@ -195,9 +220,10 @@ export function reducePointerCoalescer(
       ? [
           {
             kind: 'move',
-            pointerId: input.pointerId,
-            x: input.x,
-            y: input.y,
+            pointerId: moveInput.pointerId,
+            x: moveInput.x,
+            y: moveInput.y,
+            stamp: moveInput.stamp,
           },
         ]
       : [],

package/src/react/sprites/GameSprite.tsx

@@ -13,8 +13,12 @@ import type { CommitFrame } from '../../core/session/types';
 import type { SceneSnapshot } from '../../scene/types';
 import type { SceneMap } from '../../definition/types';
 import type { LoadedImage, LoadedSpriteSheet } from '../../assets/types';
+import { spriteFrameNameForClip } from '../../sprites/sampleSpriteClip';
 import { Sprite, type SpriteAnimatable, type SpriteAnimatableBoolean, type SpriteProps } from './Sprite';
 
+/** Re-exported from the single sampler contract (GS-ANIMATION-01). */
+export { spriteFrameNameForClip };
+
 /** Interpolation context for the select mapper. */
 export interface GameSpriteSelectContext<
   TScenes extends SceneMap,
@@ -70,39 +74,6 @@ export interface GameSpriteProps<
   readonly select: (context: GameSpriteSelectContext<TScenes, TSceneName>) => GameSpriteSelection;
 }
 
-/**
- * Select the frame name for a clip + elapsed time (loop/once semantics).
- * Reads the descriptor's animation table; the result is resolved against
- * the frame rectangles by the caller. Reuses the pure sampler's semantics.
- */
-export function spriteFrameNameForClip(
-  animations: Readonly<
-    Record<
-      string,
-      {
-        readonly frames: readonly string[];
-        readonly frameDurationMs: number;
-        readonly mode: 'loop' | 'once';
-      }
-    >
-  >,
-  clip: string,
-  elapsedMs: number,
-): string {
-  'worklet';
-  const animation = animations[clip];
-  if (animation === undefined || animation.frames.length === 0) {
-    return clip;
-  }
-  const duration = animation.frameDurationMs;
-  const count = animation.frames.length;
-  const index =
-    animation.mode === 'once'
-      ? Math.min(Math.floor(elapsedMs / duration), count - 1)
-      : Math.floor(elapsedMs / duration) % count;
-  return animation.frames[index] ?? animation.frames[0] ?? clip;
-}
-
 export function GameSprite<
   TScenes extends SceneMap,
   TSceneName extends Extract<keyof TScenes, string>,