react-native-screen-transitions 3.2.0-beta.3 → 3.2.1

package/README.md

@@ -9,10 +9,9 @@ Customizable screen transitions for React Native. Build gesture-driven, shared e
 ## Features
 
 - **Full Animation Control** – Define exactly how screens enter, exit, and respond to gestures
-- **Shared Elements** – Measure-driven transitions between screens using the Bounds API
-- **Gesture Support** – Swipe-to-dismiss with edge or full-screen activation, works with ScrollViews
-- **Two Stack Options** – Pure JS stack (recommended) or native stack integration
-- **Stack Progress** – Track animation progress across the entire stack, not just adjacent screens
+- **Shared Elements** – Smooth transitions between screens using the Bounds API
+- **Gesture Support** – Swipe-to-dismiss with edge or full-screen activation
+- **Stack Progress** – Track animation progress across the entire stack
 - **Ready-Made Presets** – Instagram, Apple Music, X (Twitter) style transitions included
 
 ## Installation
@@ -34,65 +33,7 @@ npm install react-native-reanimated react-native-gesture-handler \
 
 ## Quick Start
 
-This package provides three stack navigators:
-
-| Stack                         | Description                                                                        |
-| ----------------------------- | ---------------------------------------------------------------------------------- |
-| **Blank Stack** (recommended) | Pure JavaScript stack with full control over transitions, overlays, and gestures.  |
-| **Native Stack**              | Extends `@react-navigation/native-stack`. Full overlay support, native primitives. |
-| **Component Stack**           | Standalone navigator without React Navigation. For internal/embedded navigation.   |
-
-### Choosing a Stack
-
-For most apps, **start with Blank Stack**. It's the most flexible and has full feature support.
-
-| Stack               | Best For                                                                          |
-| ------------------- | --------------------------------------------------------------------------------- |
-| **Blank Stack**     | Most apps. Full control, all features, JS-based with native performance.          |
-| **Native Stack**    | When you need native screen primitives. Has some trade-offs.                      |
-| **Component Stack** | Embedded flows (wizards, popovers). Isolated from React Navigation. Experimental. |
-
-All three stacks share the same animation API – `screenStyleInterpolator`, gestures, overlays, and presets work identically across them.
-
-### Blank Stack Philosophy
-
-The Blank Stack is intentionally **blank** - transparent screens with no default animations. Unlike platform navigators that impose iOS or Android-style transitions, the Blank Stack gives you a clean slate.
-
-**Why no defaults?**
-
-- **Full creative control** – You define exactly how screens appear, not the OS
-- **Consistency across platforms** – Same animation on iOS and Android
-- **No fighting the framework** – No need to override or disable built-in behaviors
-
-Every screen starts invisible and static. You bring it to life with your own `screenStyleInterpolator`. This encourages intentional, custom transitions rather than settling for platform defaults.
-
-Under the hood, the Blank Stack uses `react-native-screens` for native-level performance. All animation and gesture logic runs on the UI thread via Reanimated worklets.
-
-```tsx
-// A screen with no options = invisible, no animation
-<Stack.Screen name="Detail" component={DetailScreen} />
-
-// Add your own transition
-<Stack.Screen
-  name="Detail"
-  component={DetailScreen}
-  options={{
-    screenStyleInterpolator: ({ progress, layouts }) => {
-      "worklet";
-      return {
-        contentStyle: {
-          opacity: progress,
-          transform: [
-            { translateY: interpolate(progress, [0, 1], [layouts.screen.height, 0]) }
-          ],
-        },
-      };
-    },
-  }}
-/>
-```
-
-### Blank Stack Setup
+### 1. Create a Stack
 
 ```tsx
 import { createBlankStackNavigator } from "react-native-screen-transitions/blank-stack";
@@ -116,17 +57,12 @@ function App() {
 }
 ```
 
-### Blank Stack with Expo Router
+### 2. With Expo Router
 
 ```tsx
-import type {
-  ParamListBase,
-  StackNavigationState,
-} from "@react-navigation/native";
 import { withLayoutContext } from "expo-router";
 import {
   createBlankStackNavigator,
-  type BlankStackNavigationEventMap,
   type BlankStackNavigationOptions,
 } from "react-native-screen-transitions/blank-stack";
 
@@ -134,9 +70,7 @@ const { Navigator } = createBlankStackNavigator();
 
 export const Stack = withLayoutContext<
   BlankStackNavigationOptions,
-  typeof Navigator,
-  StackNavigationState<ParamListBase>,
-  BlankStackNavigationEventMap
+  typeof Navigator
 >(Navigator);
 ```
 
@@ -144,7 +78,7 @@ export const Stack = withLayoutContext<
 
 ## Presets
 
-Built-in animation presets you can spread into screen options:
+Use built-in presets for common transitions:
 
 ```tsx
 <Stack.Screen
@@ -155,569 +89,486 @@ Built-in animation presets you can spread into screen options:
 />
 ```
 
-| Preset                                 | Description                                     |
-| -------------------------------------- | ----------------------------------------------- |
-| `SlideFromTop()`                       | Slides in from top, vertical gesture dismiss    |
-| `SlideFromBottom()`                    | Slides in from bottom, vertical gesture dismiss |
-| `ZoomIn()`                             | Scales in with fade, no gesture                 |
-| `DraggableCard()`                      | Multi-directional drag with card scaling        |
-| `ElasticCard()`                        | Elastic drag with overlay darkening             |
-| `SharedIGImage({ sharedBoundTag })`    | Instagram-style shared image transition         |
-| `SharedAppleMusic({ sharedBoundTag })` | Apple Music-style shared element                |
-| `SharedXImage({ sharedBoundTag })`     | X (Twitter)-style image transition              |
+| Preset                                 | Description                             |
+| -------------------------------------- | --------------------------------------- |
+| `SlideFromTop()`                       | Slides in from top                      |
+| `SlideFromBottom()`                    | Slides in from bottom (modal-style)     |
+| `ZoomIn()`                             | Scales in with fade                     |
+| `DraggableCard()`                      | Multi-directional drag with scaling     |
+| `ElasticCard()`                        | Elastic drag with overlay               |
+| `SharedIGImage({ sharedBoundTag })`    | Instagram-style shared image            |
+| `SharedAppleMusic({ sharedBoundTag })` | Apple Music-style shared element        |
+| `SharedXImage({ sharedBoundTag })`     | X (Twitter)-style image transition      |
 
 ---
 
 ## Custom Animations
 
-### Understanding Progress
+### The Basics
 
-The `progress` value tells you where a screen is in its lifecycle:
+Every screen has a `progress` value that goes from 0 → 1 → 2:
 
 ```
-0 ──────────────── 1 ──────────────── 2
-│                  │                  │
-Screen is          Screen is          Screen is
-OFF-SCREEN         FULLY VISIBLE      OFF-SCREEN
-(entering)         (active)           (exiting)
+0 ─────────── 1 ─────────── 2
+entering     visible      exiting
 ```
 
-When you navigate from Screen A to Screen B:
+When navigating from A to B:
+- **Screen B**: progress goes `0 → 1` (entering)
+- **Screen A**: progress goes `1 → 2` (exiting)
 
-- **Screen B** (entering): `progress` animates from `0` → `1`
-- **Screen A** (exiting): `progress` animates from `1` → `2`
-
-### Basic Examples
-
-**Fade in/out:**
+### Simple Fade
 
 ```tsx
-screenStyleInterpolator: ({ progress }) => {
-  "worklet";
-  // At 0: opacity = 0 (invisible)
-  // At 1: opacity = 1 (visible)
-  // At 2: opacity = 0 (invisible again)
-  return {
-    contentStyle: {
-      opacity: interpolate(progress, [0, 1, 2], [0, 1, 0]),
-    },
-  };
-};
+options={{
+  screenStyleInterpolator: ({ progress }) => {
+    "worklet";
+    return {
+      contentStyle: {
+        opacity: interpolate(progress, [0, 1, 2], [0, 1, 0]),
+      },
+    };
+  },
+}}
 ```
 
-**Slide from right:**
+### Slide from Right
 
 ```tsx
-screenStyleInterpolator: ({ progress, layouts: { screen } }) => {
-  "worklet";
-  // At 0: off-screen to the right
-  // At 1: centered (0)
-  // At 2: off-screen to the left
-  return {
-    contentStyle: {
-      transform: [
-        {
+options={{
+  screenStyleInterpolator: ({ progress, layouts: { screen } }) => {
+    "worklet";
+    return {
+      contentStyle: {
+        transform: [{
           translateX: interpolate(
             progress,
             [0, 1, 2],
             [screen.width, 0, -screen.width * 0.3]
           ),
-        },
-      ],
-    },
-  };
-};
+        }],
+      },
+    };
+  },
+}}
 ```
 
-**Slide from bottom (modal-style):**
+### Slide from Bottom
 
 ```tsx
-screenStyleInterpolator: ({ progress, layouts: { screen } }) => {
-  "worklet";
-  return {
-    contentStyle: {
-      transform: [
-        {
+options={{
+  screenStyleInterpolator: ({ progress, layouts: { screen } }) => {
+    "worklet";
+    return {
+      contentStyle: {
+        transform: [{
           translateY: interpolate(progress, [0, 1], [screen.height, 0]),
-        },
-      ],
-    },
-  };
-};
+        }],
+      },
+    };
+  },
+}}
 ```
 
-### Writing Your Interpolator
-
-Every `screenStyleInterpolator` must:
+### Return Styles
 
-1. Be marked with `"worklet"` (runs on UI thread)
-2. Return an object with style properties
+Your interpolator can return:
 
 ```tsx
-import { interpolate } from "react-native-reanimated";
-
-<Stack.Screen
-  name="Detail"
-  options={{
-    screenStyleInterpolator: ({ progress, layouts: { screen } }) => {
-      "worklet";
-
-      return {
-        contentStyle: {
-          // Your animated styles here
-        },
-      };
-    },
-    transitionSpec: {
-      open: Transition.Specs.DefaultSpec,
-      close: Transition.Specs.DefaultSpec,
-    },
-  }}
-/>;
+return {
+  contentStyle: { ... },   // Main screen
+  overlayStyle: { ... },   // Semi-transparent backdrop
+  ["my-id"]: { ... },      // Specific element via styleId
+};
 ```
 
-### Interpolator Props
+### Animation Specs
 
-| Prop             | Description                                              |
-| ---------------- | -------------------------------------------------------- |
-| `progress`       | Combined progress (0-2). 0=entering, 1=active, 2=exiting |
-| `stackProgress`  | Accumulated progress across entire stack (0, 1, 2, 3...) |
-| `current`        | Current screen state (progress, closing, gesture, meta)  |
-| `previous`       | Previous screen state (may be undefined)                 |
-| `next`           | Next screen state (may be undefined)                     |
-| `layouts.screen` | Screen dimensions `{ width, height }`                    |
-| `insets`         | Safe area insets `{ top, right, bottom, left }`          |
-| `focused`        | Whether current screen is the topmost                    |
-| `active`         | The screen driving the transition                        |
-| `inactive`       | The screen NOT driving the transition                    |
-| `bounds`         | Function to access shared element positions              |
+Control timing with spring configs:
 
-### Screen State (`current`, `previous`, `next`, `active`, `inactive`)
-
-Each screen state contains:
-
-| Property    | Description                                           |
-| ----------- | ----------------------------------------------------- |
-| `progress`  | Animation progress for this screen (0 or 1)           |
-| `closing`   | Whether screen is closing (0 or 1)                    |
-| `animating` | Whether screen is currently animating (0 or 1)        |
-| `gesture`   | Gesture values (x, y, normalizedX, normalizedY, etc.) |
-| `meta`      | Custom metadata from screen options                   |
+```tsx
+options={{
+  screenStyleInterpolator: myInterpolator,
+  transitionSpec: {
+    open: { stiffness: 1000, damping: 500, mass: 3 },
+    close: { stiffness: 1000, damping: 500, mass: 3 },
+  },
+}}
+```
 
-### Understanding `active` and `inactive`
+---
 
-The `active` and `inactive` props help you write cleaner conditional logic:
+## Gestures
 
-- **`active`** – The screen driving the transition. When focused, this is `current`. When not focused, this is `next`.
-- **`inactive`** – The screen NOT driving the transition. When focused, this is `previous`. When not focused, this is `current`.
+Enable swipe-to-dismiss:
 
 ```tsx
-// Check if the inactive screen wants to disable an animation
-const disableTranslateY = props.inactive?.meta?.disableTranslateYAnimation;
-
-// Check if the active screen is animating or closing
-const isAnimating = props.active.animating;
-const isClosing = props.active.closing;
+options={{
+  gestureEnabled: true,
+  gestureDirection: "vertical",
+  ...Transition.Presets.SlideFromBottom(),
+}}
 ```
 
-### Using `meta` for Conditional Logic
+### Gesture Options
+
+| Option                    | Description                            |
+| ------------------------- | -------------------------------------- |
+| `gestureEnabled`          | Enable swipe-to-dismiss                |
+| `gestureDirection`        | Direction(s) for swipe gesture         |
+| `gestureActivationArea`   | Where gesture can start                |
+| `gestureResponseDistance` | Pixel threshold for activation         |
+| `gestureVelocityImpact`   | How much velocity affects dismissal    |
 
-Use `meta` to pass custom data for conditional animation logic. This is more robust than checking route names:
+### Gesture Direction
 
 ```tsx
-// Screen A sets meta to affect how Screen B animates
-<Stack.Screen
-  name="ScreenA"
-  options={{
-    meta: { disableTranslateYAnimation: true },
-  }}
-/>
+gestureDirection: "horizontal"          // swipe left to dismiss
+gestureDirection: "horizontal-inverted" // swipe right to dismiss
+gestureDirection: "vertical"            // swipe down to dismiss
+gestureDirection: "vertical-inverted"   // swipe up to dismiss
+gestureDirection: "bidirectional"       // any direction
 
-// Screen B checks inactive screen's meta
-<Stack.Screen
-  name="ScreenB"
-  options={{
-    screenStyleInterpolator: (props) => {
-      "worklet";
-
-      // When entering from ScreenA, inactive = ScreenA (previous)
-      // When going back to ScreenA, inactive = ScreenB (current)
-      const disableY = props.inactive?.meta?.disableTranslateYAnimation;
-
-      return {
-        contentStyle: {
-          transform: [{ translateY: disableY ? 0 : translateY }],
-        },
-      };
-    },
-  }}
-/>
+// Or combine multiple:
+gestureDirection: ["horizontal", "vertical"]
 ```
 
-You can also react to screen state changes within components:
+### Gesture Activation Area
 
 ```tsx
-const animation = useScreenAnimation();
-
-useAnimatedReaction(
-  () => animation.value,
-  (props) => {
-    // React to next screen's meta
-    if (props.next?.meta?.scalesOthers) {
-      scale.value = withTiming(0);
-    }
-  }
-);
-```
-
-### Return Value
+// Simple - same for all edges
+gestureActivationArea: "edge"    // only from screen edges
+gestureActivationArea: "screen"  // anywhere on screen
 
-```tsx
-return {
-  contentStyle: { ... },        // Main screen content
-  overlayStyle: { ... },        // Semi-transparent overlay
-  ["my-element"]: { ... },      // Styles for Transition.View with styleId="my-element"
-};
+// Per-side configuration
+gestureActivationArea: {
+  left: "edge",
+  right: "screen",
+  top: "edge",
+  bottom: "screen",
+}
 ```
 
-### Using `styleId` for Individual Elements
+### With ScrollViews
 
-Animate specific elements within a screen:
+Use transition-aware scrollables so gestures work correctly:
 
 ```tsx
-// In screen options
-screenStyleInterpolator: ({ progress }) => {
-  "worklet";
-  return {
-    "hero-image": {
-      opacity: interpolate(progress, [0, 1], [0, 1]),
-      transform: [{ scale: interpolate(progress, [0, 1], [0.8, 1]) }],
-    },
-  };
-};
+<Transition.ScrollView>
+  {/* content */}
+</Transition.ScrollView>
 
-// In component
-<Transition.View styleId="hero-image">
-  <Image source={...} />
-</Transition.View>
+<Transition.FlatList data={items} renderItem={...} />
 ```
 
+Gesture rules with scrollables:
+- **vertical** – only activates when scrolled to top
+- **vertical-inverted** – only activates when scrolled to bottom
+- **horizontal** – only activates at left/right scroll edges
+
 ---
 
 ## Shared Elements (Bounds API)
 
-Animate elements between screens by measuring their positions.
+Animate elements between screens by tagging them.
 
-### 1. Tag Elements on Both Screens
+### 1. Tag the Source
 
 ```tsx
-// Source screen
 <Transition.Pressable
   sharedBoundTag="avatar"
   onPress={() => navigation.navigate("Profile")}
 >
   <Image source={avatar} style={{ width: 50, height: 50 }} />
 </Transition.Pressable>
+```
+
+### 2. Tag the Destination
 
-// Destination screen
+```tsx
 <Transition.View sharedBoundTag="avatar">
   <Image source={avatar} style={{ width: 200, height: 200 }} />
 </Transition.View>
 ```
 
-### 2. Use Bounds in Interpolator
+### 3. Use in Interpolator
 
 ```tsx
 screenStyleInterpolator: ({ bounds }) => {
   "worklet";
-
-  const avatarStyles = bounds({
-    id: "avatar",
-    method: "transform", // "transform" | "size" | "content"
-    space: "relative", // "relative" | "absolute"
-    scaleMode: "match", // "match" | "none" | "uniform"
-    anchor: "center", // positioning anchor
-  });
-
   return {
-    avatar: avatarStyles,
+    avatar: bounds({ id: "avatar", method: "transform" }),
   };
 };
 ```
 
 ### Bounds Options
 
-| Option      | Values                                 | Description                            |
-| ----------- | -------------------------------------- | -------------------------------------- |
-| `id`        | string                                 | The `sharedBoundTag` to match          |
-| `method`    | `"transform"` `"size"` `"content"`     | How to animate (scale vs width/height) |
-| `space`     | `"relative"` `"absolute"`              | Coordinate space                       |
-| `scaleMode` | `"match"` `"none"` `"uniform"`         | How to handle aspect ratio             |
-| `anchor`    | `"center"` `"top"` `"topLeading"` etc. | Transform origin                       |
-| `target`    | `"bound"` `"fullscreen"` or custom     | Destination target                     |
-| `raw`       | boolean                                | Return raw values instead of styles    |
+| Option      | Values                             | Description                   |
+| ----------- | ---------------------------------- | ----------------------------- |
+| `id`        | string                             | The `sharedBoundTag` to match |
+| `method`    | `"transform"` `"size"` `"content"` | How to animate                |
+| `space`     | `"relative"` `"absolute"`          | Coordinate space              |
+| `scaleMode` | `"match"` `"none"` `"uniform"`     | Aspect ratio handling         |
+| `raw`       | boolean                            | Return raw values             |
 
-### Raw Values
-
-```tsx
-const raw = bounds({ id: "avatar", method: "transform", raw: true });
-// { translateX, translateY, scaleX, scaleY }
-```
+---
 
-### Bounds Utilities
+## Overlays
 
-Access additional bounds data for custom animations:
+Persistent UI that animates with the stack:
 
 ```tsx
-screenStyleInterpolator: ({ bounds, progress }) => {
-  "worklet";
+const TabBar = ({ focusedIndex, progress }) => {
+  const style = useAnimatedStyle(() => ({
+    transform: [{ translateY: interpolate(progress.value, [0, 1], [100, 0]) }],
+  }));
+  return <Animated.View style={[styles.tabBar, style]} />;
+};
 
-  // Get the active link between source and destination
-  const link = bounds.getLink("avatar");
-  // { source: { bounds, styles }, destination: { bounds, styles } }
+<Stack.Screen
+  name="Home"
+  options={{
+    overlay: TabBar,
+    overlayShown: true,
+  }}
+/>
+```
 
-  // Interpolate a style property (e.g., borderRadius) between source and destination
-  const borderRadius = bounds.interpolateStyle("avatar", "borderRadius");
+### Overlay Props
 
-  // Or access raw values for custom logic
-  const sourceBorderRadius = link?.source?.styles?.borderRadius ?? 0;
+| Prop           | Description                    |
+| -------------- | ------------------------------ |
+| `focusedRoute` | Currently focused route        |
+| `focusedIndex` | Index of focused screen        |
+| `routes`       | All routes in the stack        |
+| `progress`     | Stack progress (derived value) |
+| `navigation`   | Navigation prop                |
+| `meta`         | Custom metadata from options   |
 
-  return {
-    avatar: {
-      ...bounds({ id: "avatar" }),
-      borderRadius,
-    },
-  };
-};
-```
+---
+
+## Transition Components
 
-| Method                                         | Description                                         |
-| ---------------------------------------------- | --------------------------------------------------- |
-| `bounds.getLink(id)`                           | Get source/destination bounds and styles for a tag  |
-| `bounds.interpolateStyle(id, prop, fallback?)` | Interpolate a numeric style between source and dest |
-| `bounds.getSnapshot(id, key)`                  | Manual lookup by specific screen key (edge cases)   |
+| Component               | Description                            |
+| ----------------------- | -------------------------------------- |
+| `Transition.View`       | Animated view with `sharedBoundTag`    |
+| `Transition.Pressable`  | Pressable that measures bounds         |
+| `Transition.ScrollView` | ScrollView with gesture coordination   |
+| `Transition.FlatList`   | FlatList with gesture coordination     |
+| `Transition.MaskedView` | For reveal effects (requires native)   |
 
 ---
 
-## Gestures
+## Hooks
+
+### useScreenAnimation
 
-Enable swipe-to-dismiss on screens:
+Access animation state inside a screen:
 
 ```tsx
-<Stack.Screen
-  name="Detail"
-  options={{
-    gestureEnabled: true,
-    gestureDirection: "vertical", // or "horizontal", ["vertical", "horizontal"]
-    gestureActivationArea: "edge", // or "screen", or { left: "edge", top: "screen" }
-    gestureResponseDistance: 50,
-    gestureVelocityImpact: 0.3,
-  }}
-/>
-```
+import { useScreenAnimation } from "react-native-screen-transitions";
 
-### Gesture Options
+function DetailScreen() {
+  const animation = useScreenAnimation();
 
-| Option                    | Description                                                                        |
-| ------------------------- | ---------------------------------------------------------------------------------- |
-| `gestureEnabled`          | Enable/disable gesture                                                             |
-| `gestureDirection`        | `"horizontal"` `"vertical"` `"horizontal-inverted"` `"vertical-inverted"` or array |
-| `gestureActivationArea`   | `"edge"` `"screen"` or per-side config                                             |
-| `gestureResponseDistance` | Distance threshold for gesture recognition                                         |
-| `gestureVelocityImpact`   | How much velocity affects dismissal decision                                       |
-| `gestureDrivesProgress`   | Whether gesture directly drives animation (default: true)                          |
+  const style = useAnimatedStyle(() => ({
+    opacity: animation.value.current.progress,
+  }));
 
-### Gestures with ScrollViews
+  return <Animated.View style={style}>...</Animated.View>;
+}
+```
 
-Use transition-aware scrollables so gestures work correctly:
+### useScreenState
+
+Get navigation state without animation values:
 
 ```tsx
-import Transition from "react-native-screen-transitions";
+import { useScreenState } from "react-native-screen-transitions";
 
-// Drop-in replacements
-<Transition.ScrollView>
-  {/* content */}
-</Transition.ScrollView>
+function DetailScreen() {
+  const { index, focusedRoute, routes, navigation } = useScreenState();
+  // ...
+}
+```
 
-<Transition.FlatList
-  data={items}
-  renderItem={...}
-/>
+### useHistory
 
-// Wrap custom lists
-const TransitionFlashList = Transition.createTransitionAwareComponent(
-  FlashList,
-  { isScrollable: true }
-);
-```
+Access navigation history across the app:
 
-Gesture rules with scrollables:
+```tsx
+import { useHistory } from "react-native-screen-transitions";
+
+function MyComponent() {
+  const { getRecent, getPath } = useHistory();
 
-- **vertical** – only starts when scrolled to top
-- **vertical-inverted** – only starts when scrolled to bottom
-- **horizontal** – only starts at left/right edge
+  const recentScreens = getRecent(5);  // Last 5 screens
+  const path = getPath(fromKey, toKey); // Path between screens
+}
+```
 
 ---
 
-## Overlays
+## Advanced Animation Props
 
-Both Blank Stack and Native Stack support persistent overlays that animate across screen transitions.
+The full `screenStyleInterpolator` receives these props:
 
-### Float Overlay
+| Prop             | Description                                              |
+| ---------------- | -------------------------------------------------------- |
+| `progress`       | Combined progress (0-2)                                  |
+| `stackProgress`  | Accumulated progress across entire stack                 |
+| `current`        | Current screen state                                     |
+| `previous`       | Previous screen state                                    |
+| `next`           | Next screen state                                        |
+| `active`         | Screen driving the transition                            |
+| `inactive`       | Screen NOT driving the transition                        |
+| `layouts.screen` | Screen dimensions                                        |
+| `insets`         | Safe area insets                                         |
+| `bounds`         | Shared element bounds function                           |
+
+### Screen State Properties
+
+Each screen state (`current`, `previous`, `next`, `active`, `inactive`) contains:
+
+| Property    | Description                              |
+| ----------- | ---------------------------------------- |
+| `progress`  | Animation progress (0 or 1)              |
+| `closing`   | Whether closing (0 or 1)                 |
+| `entering`  | Whether entering (0 or 1)                |
+| `animating` | Whether animating (0 or 1)               |
+| `gesture`   | Gesture values (x, y, normalized values) |
+| `meta`      | Custom metadata from options             |
+
+### Using `meta` for Conditional Logic
 
-A single overlay that persists above all screens:
+Pass custom data between screens:
 
 ```tsx
-const FloatingHeader = ({ focusedIndex, routes, overlayAnimation }) => {
-  const style = useAnimatedStyle(() => ({
-    opacity: interpolate(overlayAnimation.value.progress, [0, 1], [0, 1]),
-  }));
+// Screen A
+options={{ meta: { hideTabBar: true } }}
 
-  return (
-    <Animated.View style={[styles.header, style]}>
-      <Text>
-        Screen {focusedIndex + 1} of {routes.length}
-      </Text>
-    </Animated.View>
-  );
+// Screen B reads it
+screenStyleInterpolator: (props) => {
+  "worklet";
+  const hideTabBar = props.inactive?.meta?.hideTabBar;
+  // ...
 };
-
-<Stack.Screen
-  name="Home"
-  options={{
-    overlay: FloatingHeader,
-    overlayMode: "float",
-    overlayShown: true,
-  }}
-/>;
 ```
 
-### Screen Overlay
+### Animate Individual Elements
 
-An overlay that moves with screen content:
+Use `styleId` to target specific elements:
 
 ```tsx
-<Stack.Screen
-  name="Detail"
-  options={{
-    overlay: DetailOverlay,
-    overlayMode: "screen",
-    overlayShown: true,
-  }}
-/>
+// In options
+screenStyleInterpolator: ({ progress }) => {
+  "worklet";
+  return {
+    "hero-image": {
+      opacity: interpolate(progress, [0, 1], [0, 1]),
+    },
+  };
+};
+
+// In component
+<Transition.View styleId="hero-image">
+  <Image source={...} />
+</Transition.View>
 ```
 
-### Overlay Props
+---
+
+## Stack Types
+
+All three stacks share the same animation API. Choose based on your needs:
+
+| Stack               | Best For                                                  |
+| ------------------- | --------------------------------------------------------- |
+| **Blank Stack**     | Most apps. Full control, all features.                    |
+| **Native Stack**    | When you need native screen primitives.                   |
+| **Component Stack** | Embedded flows, isolated from React Navigation. *(Experimental)* |
 
-| Prop               | Description                                               |
-| ------------------ | --------------------------------------------------------- |
-| `focusedRoute`     | Currently focused route                                   |
-| `focusedIndex`     | Index of focused screen                                   |
-| `routes`           | All routes in the stack                                   |
-| `meta`             | Custom metadata passed from screen options                |
-| `navigation`       | Navigation prop                                           |
-| `overlayAnimation` | Animation values with `progress` accumulated across stack |
-| `screenAnimation`  | Animation values for the current focused screen           |
+### Blank Stack
 
-### Passing Custom Data
+The default choice. Pure JavaScript with native-level performance via `react-native-screens`.
 
 ```tsx
+import { createBlankStackNavigator } from "react-native-screen-transitions/blank-stack";
+```
+
+### Native Stack
+
+Extends `@react-navigation/native-stack`. Requires `enableTransitions: true`.
+
+```tsx
+import { createNativeStackNavigator } from "react-native-screen-transitions/native-stack";
+
 <Stack.Screen
+  name="Detail"
   options={{
-    overlay: MyOverlay,
-    meta: {
-      title: "Step 1",
-      showProgress: true,
-    },
+    enableTransitions: true,
+    ...Transition.Presets.SlideFromBottom(),
   }}
-/>;
-
-// In overlay
-const MyOverlay = ({ meta }) => {
-  return <Text>{meta?.title}</Text>;
-};
+/>
 ```
 
----
-
-## Transition Components
+### Component Stack (Experimental)
 
-| Component               | Description                                            |
-| ----------------------- | ------------------------------------------------------ |
-| `Transition.View`       | Animated view, supports `styleId` and `sharedBoundTag` |
-| `Transition.Pressable`  | Pressable with bounds measurement on press             |
-| `Transition.ScrollView` | ScrollView with gesture coordination                   |
-| `Transition.FlatList`   | FlatList with gesture coordination                     |
-| `Transition.MaskedView` | For clipping during shared element transitions         |
+> **Note:** This API is experimental and may change based on community feedback.
 
-### Creating Custom Components
+Standalone navigator, not connected to React Navigation. Ideal for embedded flows.
 
 ```tsx
-const TransitionImage = Transition.createTransitionAwareComponent(
-  Animated.Image,
-  { isScrollable: false }
-);
+import { createComponentNavigator } from "react-native-screen-transitions/component-stack";
+
+const Stack = createComponentNavigator();
+
+<Stack.Navigator initialRoute="step1">
+  <Stack.Screen name="step1" component={Step1} />
+  <Stack.Screen name="step2" component={Step2} />
+</Stack.Navigator>
 ```
 
 ---
 
-## Hooks
+## Caveats & Trade-offs
 
-### `useScreenAnimation`
+### Native Stack
 
-Access animation state within a screen component:
+The Native Stack uses transparent modal presentation to intercept transitions. This has trade-offs:
 
-```tsx
-import { useScreenAnimation } from "react-native-screen-transitions";
+- **Delayed touch events** – Exiting screens may have briefly delayed touch response
+- **beforeRemove listeners** – Relies on navigation lifecycle events
+- **Rapid navigation** – Some edge cases with very fast navigation sequences
 
-function DetailScreen() {
-  const animation = useScreenAnimation();
+For most apps, Blank Stack avoids these issues entirely.
 
-  const style = useAnimatedStyle(() => {
-    const { current } = animation.value;
-    return {
-      opacity: current.progress,
-    };
-  });
+### Component Stack (Experimental)
 
-  return <Animated.View style={style}>...</Animated.View>;
-}
-```
+- **No deep linking** – Routes aren't part of your URL structure
+- **Isolated state** – Doesn't affect parent navigation
+- **Touch pass-through** – Uses `pointerEvents="box-none"` by default
 
 ---
 
-## Animation Specs
+## Experimental Features
 
-Configure spring/timing animations:
+### High Refresh Rate
 
-```tsx
-transitionSpec: {
-  open: {
-    stiffness: 1000,
-    damping: 500,
-    mass: 3,
-    overshootClamping: true,
-  },
-  close: {
-    stiffness: 1000,
-    damping: 500,
-    mass: 3,
-    overshootClamping: true,
-  },
-}
+Force maximum refresh rate during transitions (for 90Hz/120Hz displays):
 
-// Or use the default
-transitionSpec: {
-  open: Transition.Specs.DefaultSpec,
-  close: Transition.Specs.DefaultSpec,
-}
+```tsx
+options={{
+  experimental_enableHighRefreshRate: true,
+}}
 ```
 
 ---
 
 ## Masked View Setup
 
-Required for `SharedIGImage` and `SharedAppleMusic` presets. The masked view creates the "reveal" effect where content appears to expand from the shared element.
+Required for `SharedIGImage` and `SharedAppleMusic` presets. The masked view creates the "reveal" effect where content expands from the shared element.
 
 > **Note**: Requires native code. Will not work in Expo Go.
 
@@ -732,11 +583,9 @@ npm install @react-native-masked-view/masked-view
 cd ios && pod install
 ```
 
-### Complete Example
-
-Here's a full example showing how to set up an Apple Music-style shared element transition:
+### Full Example
 
-**1. Source Screen** – Tag pressable elements with `sharedBoundTag`:
+**1. Source Screen** – Tag pressable elements:
 
 ```tsx
 // app/index.tsx
@@ -767,7 +616,7 @@ export default function HomeScreen() {
 }
 ```
 
-**2. Destination Screen** – Wrap content with `MaskedView` and match the `sharedBoundTag`:
+**2. Destination Screen** – Wrap with MaskedView and match the tag:
 
 ```tsx
 // app/details.tsx
@@ -795,7 +644,7 @@ export default function DetailsScreen() {
 }
 ```
 
-**3. Layout** – Apply the shared element preset with dynamic `sharedBoundTag`:
+**3. Layout** – Apply the preset with dynamic tag:
 
 ```tsx
 // app/_layout.tsx
@@ -821,210 +670,16 @@ export default function RootLayout() {
 
 ### How It Works
 
-1. `Transition.Pressable` measures its bounds when pressed and stores them with the `sharedBoundTag`
-2. `Transition.View` on the destination screen registers as the target for that tag
-3. `Transition.MaskedView` clips the destination content to the animating shared element bounds
-4. The preset interpolates position, size, and the mask to create the seamless expand/collapse effect
-
----
-
-## Native Stack
-
-For cases where you need native screen primitives, use the native stack integration. This extends `@react-navigation/native-stack` with custom transition support.
-
-> **Note**: The native stack has limitations. It uses `beforeRemove` listeners and transparent modals to intercept transitions. The Blank Stack is recommended for most use cases.
-
-### Setup
-
-```tsx
-import { createNativeStackNavigator } from "react-native-screen-transitions/native-stack";
-
-const Stack = createNativeStackNavigator();
-
-<Stack.Screen
-  name="Detail"
-  options={{
-    enableTransitions: true, // Required to enable custom transitions
-    ...Transition.Presets.SlideFromBottom(),
-  }}
-/>;
-```
-
-### Expo Router Setup
-
-```tsx
-import type {
-  ParamListBase,
-  StackNavigationState,
-} from "@react-navigation/native";
-import { withLayoutContext } from "expo-router";
-import {
-  createNativeStackNavigator,
-  type NativeStackNavigationEventMap,
-  type NativeStackNavigationOptions,
-} from "react-native-screen-transitions/native-stack";
-
-const { Navigator } = createNativeStackNavigator();
-
-export const Stack = withLayoutContext<
-  NativeStackNavigationOptions,
-  typeof Navigator,
-  StackNavigationState<ParamListBase>,
-  NativeStackNavigationEventMap
->(Navigator);
-```
-
-### Native Stack Options
-
-All standard `@react-navigation/native-stack` options are available, plus:
-
-| Option                    | Type                                     | Description                                                        |
-| ------------------------- | ---------------------------------------- | ------------------------------------------------------------------ |
-| `enableTransitions`       | `boolean`                                | Enable custom transitions (sets presentation to transparent modal) |
-| `screenStyleInterpolator` | `ScreenStyleInterpolator`                | Function that returns animated styles                              |
-| `transitionSpec`          | `TransitionSpec`                         | Animation config for open/close                                    |
-| `gestureEnabled`          | `boolean`                                | Whether swipe-to-dismiss is allowed                                |
-| `gestureDirection`        | `GestureDirection \| GestureDirection[]` | Allowed swipe directions                                           |
-| `gestureVelocityImpact`   | `number`                                 | How much velocity affects dismissal                                |
-| `gestureResponseDistance` | `number`                                 | Distance threshold for gesture                                     |
-| `gestureDrivesProgress`   | `boolean`                                | Whether gesture drives animation                                   |
-| `gestureActivationArea`   | `GestureActivationArea`                  | Where gesture can start                                            |
-| `meta`                    | `Record<string, unknown>`                | Custom metadata for conditional animation logic                    |
-
-### Renamed Native Options
-
-To avoid collisions with custom gesture options, some native options are renamed:
-
-| React Navigation          | Renamed to                      |
-| ------------------------- | ------------------------------- |
-| `gestureDirection`        | `nativeGestureDirection`        |
-| `gestureEnabled`          | `nativeGestureEnabled`          |
-| `gestureResponseDistance` | `nativeGestureResponseDistance` |
-
-### Limitations
-
-- Relies on `beforeRemove` listener to intercept navigation
-- Uses transparent modal presentation
-- Some edge cases with rapid navigation
-
----
-
-## Component Stack (Experimental)
-
-A standalone navigator that operates **independently** from React Navigation. It uses React Navigation's isolation API under the hood but doesn't affect your primary navigation state.
-
-> **Experimental**: This API may change in future versions.
-
-### How It Differs
-
-Unlike Blank Stack and Native Stack which integrate with React Navigation:
-
-- **No deep linking** – Routes aren't part of your app's URL structure
-- **No navigation state sharing** – Completely isolated from parent navigators
-- **Transparent by default** – All screens use `pointerEvents="box-none"`, allowing touches to pass through to content behind. Your screen content handles its own touch areas.
-
-This makes Component Stack ideal for **overlay-style navigation** within a screen – think embedded wizards, popovers, or flows that shouldn't affect the main navigation.
-
-### Setup
-
-```tsx
-import {
-  createComponentNavigator,
-  useComponentNavigation,
-} from "react-native-screen-transitions/component-stack";
-import Transition from "react-native-screen-transitions";
-
-const Stack = createComponentNavigator();
-
-function OnboardingFlow() {
-  return (
-    <Stack.Navigator initialRoute="step1">
-      <Stack.Screen
-        name="step1"
-        component={Step1}
-        options={{
-          ...Transition.Presets.SlideFromBottom(),
-        }}
-      />
-      <Stack.Screen
-        name="step2"
-        component={Step2}
-        options={{
-          ...Transition.Presets.SlideFromBottom(),
-        }}
-      />
-    </Stack.Navigator>
-  );
-}
-
-function Step1() {
-  const navigation = useComponentNavigation();
-
-  return (
-    <View>
-      <Text>Step 1</Text>
-      <Button title="Next" onPress={() => navigation.push("step2")} />
-    </View>
-  );
-}
-```
-
-### Navigation API
-
-```tsx
-const navigation = useComponentNavigation();
-
-navigation.push("screenName", { param: "value" }); // Push a screen
-navigation.pop(); // Go back
-navigation.popTo("screenName"); // Pop to a specific screen
-navigation.reset("screenName"); // Reset to a single screen
-```
-
-### When to Use Component Stack
-
-- **Onboarding flows** – Self-contained multi-step experiences
-- **Wizards/Forms** – Multi-step forms within a screen
-- **Embedded navigation** – Navigation inside a modal or sheet
-- **Non-URL navigation** – When you don't need deep linking
-
----
-
-## Experimental Features
-
-### High Refresh Rate
-
-Force the display to run at maximum refresh rate during transitions. This can make animations smoother on high refresh rate displays (90Hz, 120Hz).
-
-```tsx
-<Stack.Screen
-  name="Detail"
-  options={{
-    experimental_enableHighRefreshRate: true,
-    ...Transition.Presets.SlideFromBottom(),
-  }}
-/>
-```
-
-> **Note**: This is experimental and may have performance implications. Test on target devices.
-
----
-
-## Migrating from Earlier Versions
-
-### Deprecated Props
-
-The following props are deprecated and will be removed in a future version:
-
-| Deprecated Prop         | Use Instead        |
-| ----------------------- | ------------------ |
-| `isActiveTransitioning` | `active.animating` |
-| `isDismissing`          | `active.closing`   |
+1. `Transition.Pressable` measures its bounds on press and stores them with the tag
+2. `Transition.View` on the destination registers as the target for that tag
+3. `Transition.MaskedView` clips content to the animating shared element bounds
+4. The preset interpolates position, size, and mask for a seamless expand/collapse effect
 
 ---
 
 ## Support
 
-This package is developed in my spare time. Updates and bug fixes may take time.
+This package is developed in my spare time.
 
 If you'd like to fuel the next release, [buy me a coffee](https://buymeacoffee.com/trpfsu)