rn-gamekit 0.1.0

package/src/react/pointerCoalescer.ts

@@ -0,0 +1,234 @@
+/**
+ * Pointer coalescer (T7).
+ *
+ * Pure, worklet-safe state machine that throttles move forwarding from the
+ * UI runtime: at most one move crosses runtimes per configured interval
+ * (default: one fixed step), always carrying the latest dirty position.
+ * Edges are never throttled or dropped:
+ *
+ * - `down` forwards the begin immediately (latency-critical) and establishes
+ *   the single active pointer; a secondary pointer is ignored.
+ * - `move` updates the latest dirty position and forwards it at most once
+ *   per interval.
+ * - `flush` forwards the latest deferred move even if native touch movement
+ *   has paused.
+ * - `up` forwards the final position in the terminal edge and releases the
+ *   active pointer.
+ * - `cancel` neutralizes exactly once.
+ * - `reset` drops all queued state (layout revision, unmount).
+ *
+ * The coalescer is not the authoritative owner: ownership, edge sampling,
+ * and containment re-validation stay on the JS side (input buffer).
+ * Time is injected so ordering and frequency are testable without a device.
+ */
+
+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: 'end'; readonly pointerId: number; readonly x: number; readonly y: number }
+  | { readonly kind: 'cancel' };
+
+export interface PointerCoalescer {
+  /** A pointer went down at a surface point. Returns the events to forward. */
+  down(pointerId: number, x: number, y: number, nowMs: number): readonly CoalescedPointerEvent[];
+  /** A pointer moved. Returns at most one (coalesced) move per interval. */
+  move(pointerId: number, x: number, y: number, nowMs: number): readonly CoalescedPointerEvent[];
+  /** Forward a deferred move when the frame clock reaches the interval. */
+  flush(nowMs: number): readonly CoalescedPointerEvent[];
+  /** A pointer lifted. Returns the final point and the terminal edge together. */
+  up(pointerId: number, x: number, y: number, nowMs: number): readonly CoalescedPointerEvent[];
+  /** Neutralize the active pointer. Returns the cancel event exactly once. */
+  cancel(nowMs: number): readonly CoalescedPointerEvent[];
+  /** Drop all queued state without emitting anything (layout/unmount). */
+  reset(): void;
+}
+
+interface ActivePointer {
+  readonly pointerId: number;
+  readonly lastForwardMs: number;
+  readonly pendingMove:
+    | { readonly x: number; readonly y: number }
+    | undefined;
+}
+
+/** Explicit coalescer state stored in one UI-runtime SharedValue. */
+export interface PointerCoalescerState {
+  readonly maxMoveIntervalMs: number;
+  readonly active: ActivePointer | undefined;
+}
+
+/** One native touch input consumed by the pure coalescer reducer. */
+export type PointerCoalescerInput =
+  | {
+      readonly kind: 'down' | 'move' | 'up';
+      readonly pointerId: number;
+      readonly x: number;
+      readonly y: number;
+      readonly nowMs: number;
+    }
+  | { readonly kind: 'cancel'; readonly nowMs: number }
+  | { readonly kind: 'flush'; readonly nowMs: number }
+  | { readonly kind: 'reset' };
+
+/** Immutable state plus the ordered events produced by one coalescer input. */
+export interface PointerCoalescerTransition {
+  readonly state: PointerCoalescerState;
+  readonly events: readonly CoalescedPointerEvent[];
+}
+
+/** Create fresh state for a UI-runtime coalescer. */
+export function createPointerCoalescerState(
+  maxMoveIntervalMs: number,
+): PointerCoalescerState {
+  'worklet';
+  return { maxMoveIntervalMs, active: undefined };
+}
+
+/**
+ * Advance pointer coalescing without relying on mutable worklet closures.
+ *
+ * RNGH registers each touch callback as a separate worklet. Closure-captured
+ * objects may therefore be serialized into independent copies; callers must
+ * keep the returned state in one SharedValue and pass it into every handler.
+ */
+export function reducePointerCoalescer(
+  state: PointerCoalescerState,
+  input: PointerCoalescerInput,
+): PointerCoalescerTransition {
+  'worklet';
+  if (input.kind === 'reset') {
+    return { state: createPointerCoalescerState(state.maxMoveIntervalMs), events: [] };
+  }
+
+  if (input.kind === 'down') {
+    if (state.active !== undefined) {
+      return { state, events: [] };
+    }
+    return {
+      state: {
+        ...state,
+        active: {
+          pointerId: input.pointerId,
+          lastForwardMs: input.nowMs,
+          pendingMove: undefined,
+        },
+      },
+      events: [
+        {
+          kind: 'begin',
+          pointerId: input.pointerId,
+          x: input.x,
+          y: input.y,
+        },
+      ],
+    };
+  }
+
+  if (input.kind === 'cancel') {
+    if (state.active === undefined) {
+      return { state, events: [] };
+    }
+    return {
+      state: { ...state, active: undefined },
+      events: [{ kind: 'cancel' }],
+    };
+  }
+
+  const active = state.active;
+
+  if (input.kind === 'flush') {
+    if (active === undefined || active.pendingMove === undefined) {
+      return { state, events: [] };
+    }
+    if (input.nowMs - active.lastForwardMs < state.maxMoveIntervalMs) {
+      return { state, events: [] };
+    }
+    return {
+      state: {
+        ...state,
+        active: {
+          ...active,
+          lastForwardMs: input.nowMs,
+          pendingMove: undefined,
+        },
+      },
+      events: [
+        {
+          kind: 'move',
+          pointerId: active.pointerId,
+          x: active.pendingMove.x,
+          y: active.pendingMove.y,
+        },
+      ],
+    };
+  }
+
+  if (active === undefined || active.pointerId !== input.pointerId) {
+    return { state, events: [] };
+  }
+
+  if (input.kind === 'up') {
+    return {
+      state: { ...state, active: undefined },
+      // The terminal event carries the newest point, subsuming a deferred move.
+      events: [
+        {
+          kind: 'end',
+          pointerId: input.pointerId,
+          x: input.x,
+          y: input.y,
+        },
+      ],
+    };
+  }
+
+  const shouldForward =
+    input.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 },
+  };
+  return {
+    state: { ...state, active: nextActive },
+    events: shouldForward
+      ? [
+          {
+            kind: 'move',
+            pointerId: input.pointerId,
+            x: input.x,
+            y: input.y,
+          },
+        ]
+      : [],
+  };
+}
+
+/**
+ * Stateful RN-runtime adapter retained for pure tests and non-worklet callers.
+ * UI gesture handlers use `reducePointerCoalescer` with a SharedValue instead.
+ */
+export function createPointerCoalescer(maxMoveIntervalMs: number): PointerCoalescer {
+  let state = createPointerCoalescerState(maxMoveIntervalMs);
+
+  const dispatch = (input: PointerCoalescerInput): readonly CoalescedPointerEvent[] => {
+    const transition = reducePointerCoalescer(state, input);
+    state = transition.state;
+    return transition.events;
+  };
+
+  const coalescer: PointerCoalescer = {
+    down: (pointerId: number, x: number, y: number, nowMs: number) =>
+      dispatch({ kind: 'down', pointerId, x, y, nowMs }),
+    move: (pointerId: number, x: number, y: number, nowMs: number) =>
+      dispatch({ kind: 'move', pointerId, x, y, nowMs }),
+    flush: (nowMs: number) => dispatch({ kind: 'flush', nowMs }),
+    up: (pointerId: number, x: number, y: number, nowMs: number) =>
+      dispatch({ kind: 'up', pointerId, x, y, nowMs }),
+    cancel: (nowMs: number) => dispatch({ kind: 'cancel', nowMs }),
+    reset: () => {
+      dispatch({ kind: 'reset' });
+    },
+  };
+  return Object.freeze(coalescer);
+}

package/src/react/pointerContainment.ts

@@ -0,0 +1,23 @@
+/**
+ * UI-side containment mirror (T7).
+ *
+ * The exact same viewport formula the JS binding uses to reject begins in
+ * `fit` letterbox space, workletized so the Manual gesture can fail before
+ * activation. JS re-validates on receipt; this mirror only prevents an
+ * obviously invalid begin from activating the gesture at all.
+ */
+import type { ResolvedViewport2D } from '../viewport2d';
+
+/** Whether a surface point may begin a gesture in the interactive content. */
+export function isBeginAllowed(
+  viewport: ResolvedViewport2D | undefined,
+  x: number,
+  y: number,
+): boolean {
+  'worklet';
+  if (viewport === undefined) {
+    return false;
+  }
+  const { x: boundsX, y: boundsY, width, height } = viewport.contentBounds;
+  return x >= boundsX && y >= boundsY && x <= boundsX + width && y <= boundsY + height;
+}

package/src/react/sprites/GameSprite.tsx

@@ -0,0 +1,192 @@
+/**
+ * `GameSprite` — the common GameKit sprite integration (T7.6).
+ *
+ * Accepts the renderer's commit/alpha shared values, narrows the snapshot
+ * by `scene`, invokes one worklet `select` mapper, and drives the
+ * underlying `Sprite` through coherent derived values. The selector's scene
+ * typing is exact — a `scene="play"` selector receives only the play
+ * snapshot without casts.
+ */
+import { useDerivedValue, type SharedValue } from 'react-native-reanimated';
+
+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 { Sprite, type SpriteAnimatable, type SpriteAnimatableBoolean, type SpriteProps } from './Sprite';
+
+/** Interpolation context for the select mapper. */
+export interface GameSpriteSelectContext<
+  TScenes extends SceneMap,
+  TSceneName extends Extract<keyof TScenes, string>,
+> {
+  /** The previous commit's snapshot for the selected scene. */
+  readonly previous: SceneSnapshot<TScenes[TSceneName]>;
+  /** The current commit's snapshot for the selected scene. */
+  readonly current: SceneSnapshot<TScenes[TSceneName]>;
+  /** Presentation interpolation alpha in [0, 1]. */
+  readonly alpha: number;
+}
+
+/** The discrete + interpolated presentation selection. */
+export interface GameSpriteSelection {
+  /** World position (interpolated when the selector requests it). */
+  readonly x: number;
+  readonly y: number;
+  /** Rotation in radians around the anchor. */
+  readonly rotation?: number;
+  /** Uniform scale around the anchor. */
+  readonly scale?: number;
+  /** The clip to select from the sprite sheet (discrete). */
+  readonly clip?: string;
+  /** Elapsed time within the clip in milliseconds (discrete). */
+  readonly elapsedMs?: number;
+  /** The exact frame name (discrete; overrides clip + elapsedMs). */
+  readonly frame?: string;
+  /** Explicit flips (discrete). */
+  readonly flipX?: boolean;
+  readonly flipY?: boolean;
+  /** Opacity in [0, 1]. */
+  readonly opacity?: number;
+  /** Hide the sprite. */
+  readonly visible?: boolean;
+}
+
+export interface GameSpriteProps<
+  TScenes extends SceneMap,
+  TSceneName extends Extract<keyof TScenes, string>,
+> {
+  /** The scene whose snapshot the selector reads. */
+  readonly scene: TSceneName;
+  /** The renderer's latest commit. */
+  readonly commit: SharedValue<CommitFrame<TScenes>>;
+  /** The renderer's presentation alpha. */
+  readonly alpha: SharedValue<number>;
+  /** The loaded asset; the renderer borrows and never disposes it. */
+  readonly source: LoadedImage | LoadedSpriteSheet;
+  /** Normalized anchor in [0, 1] relative to the selected frame. */
+  readonly anchor?: { readonly x: number; readonly y: number };
+  /** Worklet mapper from the scene snapshots to presentation values. */
+  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>,
+>({
+  scene,
+  commit,
+  alpha,
+  source,
+  anchor,
+  select,
+}: GameSpriteProps<TScenes, TSceneName>) {
+  const selection = useDerivedValue(() => {
+    'worklet';
+    const envelope = commit.value;
+    if (envelope.scene !== scene) {
+      return undefined;
+    }
+    const current = envelope.current as never as SceneSnapshot<TScenes[TSceneName]>;
+    if (current === undefined) {
+      // The frame has not been seeded for this session yet (session swap on
+      // the persistent surface): present nothing until the first commit.
+      return undefined;
+    }
+    const context = {
+      // The first commit has no previous snapshot; the current one stands in
+      // so the initial presentation interpolates from itself (alpha 0).
+      previous:
+        (envelope.previous ?? envelope.current) as never as SceneSnapshot<TScenes[TSceneName]>,
+      current,
+      alpha: alpha.value,
+    } as GameSpriteSelectContext<TScenes, TSceneName>;
+    return select(context);
+  }, [commit, alpha, scene, select]);
+
+  const x = useDerivedValue(() => selection.value?.x ?? 0);
+  const y = useDerivedValue(() => selection.value?.y ?? 0);
+  const rotation = useDerivedValue(() => selection.value?.rotation ?? 0);
+  const scale = useDerivedValue(() => selection.value?.scale ?? 1);
+  const opacity = useDerivedValue(() => selection.value?.opacity ?? 1);
+  const flipX = useDerivedValue(() => selection.value?.flipX ?? false);
+  const flipY = useDerivedValue(() => selection.value?.flipY ?? false);
+  const visible = useDerivedValue(() => selection.value?.visible ?? true);
+  const frameName = useDerivedValue(() => {
+    'worklet';
+    const selectionValue = selection.value;
+    if (selectionValue === undefined) {
+      return undefined;
+    }
+    if (selectionValue.frame !== undefined) {
+      return selectionValue.frame;
+    }
+    if (selectionValue.clip === undefined) {
+      return undefined;
+    }
+    if (source.descriptor.kind !== 'sprite-sheet') {
+      return undefined;
+    }
+    // R3: the sampler reads the descriptor's animation table (clips), never
+    // the frame-rectangle map; the returned frame name is resolved against
+    // the frame rectangles in the Sprite's rect modifier.
+    const sheet = source as LoadedSpriteSheet;
+    return spriteFrameNameForClip(
+      sheet.descriptor.animations,
+      selectionValue.clip,
+      selectionValue.elapsedMs ?? 0,
+    );
+  });
+
+  const animated = {
+    x: x as SpriteAnimatable,
+    y: y as SpriteAnimatable,
+    rotation: rotation as SpriteAnimatable,
+    scale: scale as SpriteAnimatable,
+    opacity: opacity as SpriteAnimatable,
+    flipX: flipX as SpriteAnimatableBoolean,
+    flipY: flipY as SpriteAnimatableBoolean,
+    visible: visible as SpriteAnimatableBoolean,
+  };
+
+  const props = {
+    source,
+    frame: source.descriptor.kind === 'sprite-sheet' ? (frameName as never) : undefined,
+    anchor,
+    ...animated,
+  } as unknown as SpriteProps;
+  return <Sprite {...props} />;
+}

package/src/react/sprites/GameWorld2D.tsx

@@ -0,0 +1,46 @@
+/**
+ * `GameWorld2D` — the viewport transform group (T7.6).
+ *
+ * Applies the resolved viewport offset/scale exactly once to all child
+ * sprites. It adds no camera state, subscribes no React per frame, and is
+ * not a camera API. Raw Skia nodes may be nested inside.
+ */
+import type { ReactNode } from 'react';
+import { Group } from '@shopify/react-native-skia';
+import { useDerivedValue, type SharedValue } from 'react-native-reanimated';
+
+import type { ResolvedViewport2D } from '../../viewport2d/types';
+
+/**
+ * The viewport transform as a Skia element list:
+ * `T(offset) · S(scale)` — logical units map to surface points.
+ */
+export function viewportTransform(viewport: ResolvedViewport2D | undefined): readonly (
+  | { readonly translateX: number }
+  | { readonly translateY: number }
+  | { readonly scaleX: number }
+  | { readonly scaleY: number }
+)[] {
+  'worklet';
+  if (viewport === undefined) {
+    return [];
+  }
+  return [
+    { translateX: viewport.offsetX },
+    { translateY: viewport.offsetY },
+    { scaleX: viewport.scale },
+    { scaleY: viewport.scale },
+  ];
+}
+
+export function GameWorld2D({
+  viewport,
+  children,
+}: {
+  /** The resolved viewport shared value supplied to the renderer. */
+  readonly viewport: SharedValue<ResolvedViewport2D | undefined>;
+  readonly children: ReactNode;
+}) {
+  const transform = useDerivedValue(() => viewportTransform(viewport.value));
+  return <Group transform={transform as never}>{children}</Group>;
+}

package/src/react/sprites/Sprite.tsx

@@ -0,0 +1,194 @@
+/**
+ * `Sprite` — the retained sprite primitive (T7.6).
+ *
+ * Renders one full-image sprite or one sprite-sheet frame through a
+ * source-verified Skia path: full images use `<Image>`; sheet frames use a
+ * single-entry Atlas (the RSXform carries rotation + position, a wrapping
+ * Group applies the scale/flip part around the anchor). All animatable
+ * properties accept plain numbers or Reanimated shared/derived values
+ * without mirroring them through React state. Drawing order is React child
+ * order. The sprite never subscribes React to the game frame.
+ */
+import { useMemo } from 'react';
+import { Atlas, Group, type SkImage, type SamplingOptions } from '@shopify/react-native-skia';
+import { useDerivedValue, type SharedValue } from 'react-native-reanimated';
+import { useRectBuffer, useRSXformBuffer } from '@shopify/react-native-skia';
+
+import type { LoadedImage, LoadedSpriteSheet } from '../../assets/types';
+import {
+  computeSpriteRsxform,
+  resolveSpriteFrameRect,
+  spriteGroupCorrection,
+  type SpriteTransformInput,
+} from './spriteTransform';
+
+export { resolveSpriteFrameRect, type SpriteFrameRect } from './spriteTransform';
+
+export type SpriteAnimatable = number | SharedValue<number>;
+export type SpriteAnimatableBoolean = boolean | SharedValue<boolean>;
+export type SpriteAnimatableString = string | SharedValue<string>;
+
+export interface SpriteProps {
+  /** The loaded asset; the renderer borrows and never disposes it. */
+  readonly source: LoadedImage | LoadedSpriteSheet;
+  /** Frame name for sprite sheets; ignored for full images. A shared value
+   * may carry undefined while the selection has not been published. */
+  readonly frame?: SpriteAnimatableString | SharedValue<string | undefined>;
+  /** Clip name for sprite sheets; the frame is selected from it. */
+  readonly clip?: SpriteAnimatableString;
+  /** Elapsed milliseconds within the clip (frame selection). */
+  readonly elapsedMs?: SpriteAnimatable;
+  /** World position in logical units. */
+  readonly x?: SpriteAnimatable;
+  readonly y?: SpriteAnimatable;
+  /** Rotation in radians around the anchor. */
+  readonly rotation?: SpriteAnimatable;
+  /** Uniform scale around the anchor. */
+  readonly scale?: SpriteAnimatable;
+  /** Normalized anchor in [0, 1] relative to the selected frame. */
+  readonly anchor?: { readonly x: number; readonly y: number };
+  /** Explicit flips preserve the anchor. */
+  readonly flipX?: SpriteAnimatableBoolean;
+  readonly flipY?: SpriteAnimatableBoolean;
+  /** Opacity in [0, 1]. */
+  readonly opacity?: SpriteAnimatable;
+  /** Optional tint color applied to the draw. */
+  readonly tint?: string;
+  /** Sampling for the texture; pixel-art defaults to nearest. */
+  readonly sampling?: SamplingOptions;
+  /** Hide the sprite without unmounting it. */
+  readonly visible?: SpriteAnimatableBoolean;
+}
+
+export function Sprite({
+  source,
+  frame,
+  clip,
+  elapsedMs = 0,
+  x = 0,
+  y = 0,
+  rotation = 0,
+  scale = 1,
+  anchor = { x: 0, y: 0 },
+  flipX = false,
+  flipY = false,
+  opacity = 1,
+  tint,
+  sampling,
+  visible = true,
+}: SpriteProps) {
+  const image = source.image as SkImage;
+
+  // Worklet-safe frame resolution: an explicit `frame` wins; otherwise the
+  // clip + elapsed time select the frame (the clip/elapsed may be animated
+  // shared values, so the resolution happens inside the rect modifier).
+  const resolveFrameRectWorklet = (
+    rect: { setXYWH(x: number, y: number, width: number, height: number): void },
+  ): void => {
+    'worklet';
+    const clipValue = typeof clip === 'string' ? clip : clip?.value;
+    const elapsedValue = typeof elapsedMs === 'number' ? elapsedMs : elapsedMs?.value;
+    let name: string | undefined = typeof frame === 'string' ? frame : frame?.value;
+    if (name === undefined && source.descriptor.kind === 'sprite-sheet' && clipValue !== undefined) {
+      const sheet = source as LoadedSpriteSheet;
+      // R3: resolve the clip through the descriptor's animation table, then
+      // the returned frame name through the frame rectangles below.
+      const animation = sheet.descriptor.animations[clipValue];
+      if (animation !== undefined && animation.frames.length > 0) {
+        const duration = animation.frameDurationMs;
+        const count = animation.frames.length;
+        const index =
+          animation.mode === 'once'
+            ? Math.min(Math.floor((elapsedValue ?? 0) / duration), count - 1)
+            : Math.floor((elapsedValue ?? 0) / duration) % count;
+        name = animation.frames[index] ?? animation.frames[0];
+      }
+    }
+    const frameRect =
+      source.descriptor.kind === 'image'
+        ? { x: 0, y: 0, width: (source as LoadedImage).width, height: (source as LoadedImage).height }
+        : name === undefined
+          ? undefined
+          : (source as LoadedSpriteSheet).frames[name];
+    if (frameRect === undefined) {
+      if (name === undefined) {
+        // RF4: the selection has not been published yet (scene mismatch or a
+        // shared frame before its first value): present nothing, never throw.
+        rect.setXYWH(0, 0, 0, 0);
+        return;
+      }
+      throw new Error(
+        `frame ${JSON.stringify(name)} does not belong to this sprite sheet (loaded frames: ${Object.keys((source as LoadedSpriteSheet).frames).join(', ')})`,
+      );
+    }
+    rect.setXYWH(frameRect.x, frameRect.y, frameRect.width, frameRect.height);
+  };
+
+  const staticFrame = typeof frame === 'string' ? frame : undefined;
+  const frameSize = useMemo(() => resolveSpriteFrameRect(source, staticFrame), [source, staticFrame]);
+  const input: SpriteTransformInput = {
+    x,
+    y,
+    rotation,
+    scale,
+    flipX,
+    flipY,
+    anchorX: anchor.x,
+    anchorY: anchor.y,
+    frameWidth: frameSize.width,
+    frameHeight: frameSize.height,
+  };
+
+  const rects = useRectBuffer(1, resolveFrameRectWorklet);
+  const xforms = useRSXformBuffer(1, (xform) => {
+    'worklet';
+    // RF4: resolve the selected frame's rectangle and dimensions in the same
+    // worklet update so the anchor math always uses the current frame size.
+    const name = typeof frame === 'string' ? frame : frame?.value;
+    let width = frameSize.width;
+    let height = frameSize.height;
+    if (name !== undefined && source.descriptor.kind === 'sprite-sheet') {
+      const rect = (source as LoadedSpriteSheet).frames[name];
+      if (rect !== undefined) {
+        width = rect.width;
+        height = rect.height;
+      }
+    }
+    const result = computeSpriteRsxform({
+      ...input,
+      frameWidth: width,
+      frameHeight: height,
+    });
+    xform.set(result.scos, result.ssin, result.tx, result.ty);
+  });
+  const groupTransform = useMemo(
+    () => spriteGroupCorrection(input) as unknown as Parameters<typeof Group>[0]['transform'],
+    // The correction reads animated values at draw time; the element list
+    // identity is stable (values are shared-value reads inside the group).
+    [anchor.x, anchor.y, frameSize.width, frameSize.height],
+  );
+  const colors = useMemo(() => (tint === undefined ? undefined : [tint]), [tint]);
+
+  // The Skia Group has no `visible` prop: hiding is expressed as a combined
+  // opacity so the component stays mounted (topology is never remounted per
+  // frame) while the draw is fully transparent. RF4: derived on the UI
+  // runtime for every static/shared combination of opacity and visible.
+  const effectiveOpacity = useDerivedValue(() => {
+    'worklet';
+    const o = typeof opacity === 'number' ? opacity : opacity.value;
+    const v = typeof visible === 'boolean' ? visible : visible.value;
+    return v ? o : 0;
+  }, [opacity, visible]);
+
+  return (
+    <Group transform={groupTransform as never} opacity={effectiveOpacity}>
+      <Atlas
+        image={image}
+        sprites={rects}
+        transforms={xforms}
+        colors={colors as never}
+        sampling={(sampling ?? 'nearest') as never}
+      />
+    </Group>
+  );
+}