react-native-ease: Instructions file for Codex

Agent Instructions for react-native-ease

Overview

react-native-ease is a React Native library that provides declarative, native-powered animations via a single EaseView component. It uses Core Animation (iOS) and ObjectAnimator/SpringAnimation (Android) — no JS animation loop, no worklets, no C++ runtime.

Fabric (new architecture) only. Does not support the old architecture.

Project Structure

src/                          # TypeScript source (library)
  EaseView.tsx                # React component — flattens props to native
  EaseViewNativeComponent.ts  # Codegen spec — defines native props/events
  types.ts                    # Public TypeScript types
  index.tsx                   # Public exports
  __tests__/                  # Jest tests

ios/
  EaseView.h                  # Native view header (ObjC++)
  EaseView.mm                 # Native view implementation (Core Animation)

android/src/main/java/com/ease/
  EaseView.kt                 # Native view (ObjectAnimator/SpringAnimation)
  EaseViewManager.kt          # ViewManager with @ReactProp setters
  EasePackage.kt              # Package registration

example/                      # Demo app (separate workspace)
  src/App.tsx                 # Main demo screen with animation examples
  src/ComparisonScreen.tsx    # Comparison with Reanimated
  src/components/             # Shared demo components (Section, Button, TabBar)

Architecture

The JS component (EaseView.tsx) takes structured props (animate, transition, etc.) and flattens them into individual native props defined in the codegen spec (EaseViewNativeComponent.ts). When those flat props change on the native side, the native view diffs previous vs new values and creates platform-native animations.

Prop flattening example:

animate={{ opacity: 0.5, scale: 1.2 }}  →  animateOpacity=0.5, animateScale=1.2
transition={{ type: 'spring', damping: 10 }}  →  transitionType="spring", transitionDamping=10

Key design pattern: All animation logic lives on the native side. The JS layer is purely a prop resolver — no animation state, no timers, no refs.