diff --git a/AGENTS.md b/AGENTS.md
index 6fda925..5905caf 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -111,3 +111,39 @@ Use conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, etc.
- **Spring damping ratio on Android is derived** from `damping`, `stiffness`, and `mass` using: `dampingRatio = damping / (2 * sqrt(stiffness * mass))`. iOS passes these values directly to `CASpringAnimation`.
- **Animation batching:** Both platforms track animation batches with a generation ID. When new animations start, any pending old-batch callbacks are fired as interrupted (`finished: false`).
- **Loop only works with timing animations**, not springs. Loop requires `initialAnimate` to define the start value.
+
+## Android UI Automation (agent-device)
+
+The example app has looping animations (Pulse, Banner) that prevent Android's `uiautomator` from reaching idle state, which breaks `agent-device snapshot` and `find` commands.
+
+### Workaround
+Before using `agent-device snapshot -i` or `find` on Android, either:
+
+1. **Stop looping animations in the app** — tap the Stop button on Pulse and Banner demos, OR
+2. **Disable system animations** (less ideal — also affects recording):
+ ```bash
+ adb shell settings put global window_animation_scale 0
+ adb shell settings put global transition_animation_scale 0
+ adb shell settings put global animator_duration_scale 0
+ # Re-enable after: set all back to 1
+ ```
+
+### iOS
+No workaround needed — `agent-device` uses XCTest accessibility on iOS which doesn't require idle state.
+
+### Android validation flow
+```bash
+# 1. Open app
+agent-device open ease.example --platform android --device "SM G996W"
+
+# 2. Stop looping demos (tap Stop buttons) or disable system animations
+
+# 3. Now snapshot works
+agent-device snapshot -i
+
+# 4. Navigate and interact by ref
+agent-device press @e9 # e.g. Replay button
+
+# 5. Screenshot/record
+agent-device screenshot /tmp/screenshot.png
+```
diff --git a/example/src/App.tsx b/example/src/App.tsx
index 8f4693f..74b5a94 100644
--- a/example/src/App.tsx
+++ b/example/src/App.tsx
@@ -45,18 +45,24 @@ function ButtonDemo() {
}
function BannerDemo() {
+ const [playing, setPlaying] = useState(true);
+
return (
@@ -68,24 +74,38 @@ function BannerDemo() {
+
);
}
function PulseDemo() {
+ const [playing, setPlaying] = useState(true);
+
return (
+
);
}
@@ -421,6 +441,72 @@ function StyleReRenderDemo() {
);
}
+const STAGGER_CARDS = [
+ { color: '#4a90d9', label: 'Card 1', delay: 0 },
+ { color: '#e06c75', label: 'Card 2', delay: 150 },
+ { color: '#98c379', label: 'Card 3', delay: 300 },
+ { color: '#d19a66', label: 'Card 4', delay: 450 },
+];
+
+function StaggeredCardsDemo() {
+ const [mountKey, setMountKey] = useState(0);
+
+ return (
+
+
+
+ );
+}
+
+function StaggeredCard({
+ color,
+ label,
+ delay,
+}: {
+ color: string;
+ label: string;
+ delay: number;
+}) {
+ const [visible, setVisible] = useState(delay === 0);
+
+ useEffect(() => {
+ if (delay > 0) {
+ const timer = setTimeout(() => setVisible(true), delay);
+ return () => clearTimeout(timer);
+ }
+ return undefined;
+ }, [delay]);
+
+ return (
+
+ {label}
+
+ );
+}
+
+function StaggeredCards() {
+ return (
+
+ {STAGGER_CARDS.map((card) => (
+
+ ))}
+
+ );
+}
+
function DemosScreen() {
return (
@@ -446,6 +532,7 @@ function DemosScreen() {
+
);
}
@@ -606,6 +693,22 @@ const styles = StyleSheet.create({
fontSize: 13,
fontWeight: '700',
},
+ staggerRow: {
+ flexDirection: 'row',
+ gap: 10,
+ },
+ staggerCard: {
+ flex: 1,
+ height: 100,
+ borderRadius: 12,
+ alignItems: 'center',
+ justifyContent: 'center',
+ },
+ staggerCardText: {
+ color: '#fff',
+ fontSize: 13,
+ fontWeight: '700',
+ },
styledCard: {
opacity: 0.6,
backgroundColor: '#2a2a4a',