ai-engineering-loop 1.13.0 → 1.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. package/.agents/skills/ai-engineering-loop/SKILL.md +62 -0
  2. package/.agents/skills/ai-engineering-loop/references/loop-commands.md +20 -0
  3. package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
  4. package/.agents/skills/ai-engineering-loop/references/loop-goal.md +10 -0
  5. package/.agents/skills/ai-engineering-loop/references/loop-hosts.md +44 -0
  6. package/.agents/skills/ai-engineering-loop/references/loop-maker.md +8 -0
  7. package/.agents/skills/ai-engineering-loop/references/loop-review.md +18 -0
  8. package/.agents/skills/ai-engineering-loop/references/loop-risky.md +9 -0
  9. package/.agents/skills/ai-engineering-loop/references/loop-verify.md +20 -0
  10. package/.claude/skills/ai-engineering-loop/SKILL.md +28 -47
  11. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +20 -0
  12. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
  13. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +10 -0
  14. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +44 -0
  15. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +8 -0
  16. package/.claude/skills/ai-engineering-loop/references/loop-review.md +18 -0
  17. package/.claude/skills/ai-engineering-loop/references/loop-risky.md +9 -0
  18. package/.claude/skills/ai-engineering-loop/references/loop-verify.md +20 -0
  19. package/CHANGELOG.md +116 -0
  20. package/README.md +90 -5
  21. package/README.npm.md +6 -2
  22. package/THIRD_PARTY_NOTICES.md +29 -0
  23. package/adapters/dot/README.md +1 -1
  24. package/adapters/dot/skills/dot-dev-skill-router/SKILL.md +24 -16
  25. package/adapters/project-onboarding/SKILL.md +27 -0
  26. package/adapters/project-onboarding/references/output.md +29 -0
  27. package/adapters/quality/skills/ael-code-simplifier/SKILL.md +43 -0
  28. package/adapters/quality/skills/ael-receiving-code-review/SKILL.md +37 -0
  29. package/bin/ai-engineering-loop.js +1270 -75
  30. package/core/grill-policy.md +1 -1
  31. package/core/root-cause-analysis.md +6 -0
  32. package/core/runtime-safety.md +31 -3
  33. package/evals/cases/21-tier-t0-docs.json +34 -0
  34. package/evals/cases/22-tier-t1-small-pass.json +30 -0
  35. package/evals/cases/23-tier-t1-blocker.json +26 -0
  36. package/evals/cases/24-tier-t1-auth-escalates.json +30 -0
  37. package/lib/auto-update.js +488 -0
  38. package/lib/budget.js +31 -1
  39. package/lib/cli-args.js +95 -0
  40. package/lib/docs.js +91 -0
  41. package/lib/doctor.js +9 -14
  42. package/lib/gates.js +114 -1
  43. package/lib/host-skill-build.js +121 -0
  44. package/lib/hosts/agent-formats.js +135 -0
  45. package/lib/hosts/commands.js +126 -0
  46. package/lib/hosts/detect.js +56 -0
  47. package/lib/hosts/doctor.js +76 -0
  48. package/lib/hosts/redetect.js +60 -0
  49. package/lib/hosts/registry.js +271 -0
  50. package/lib/hosts/table.js +35 -0
  51. package/lib/migrations.js +84 -0
  52. package/lib/project-registry.js +148 -0
  53. package/lib/run-abandon.js +116 -0
  54. package/lib/run-state.js +6 -3
  55. package/lib/sync-hosts.js +456 -130
  56. package/lib/tier.js +134 -0
  57. package/lib/update-manager.js +17 -1
  58. package/lib/update-notice.js +192 -0
  59. package/lib/user-state.js +80 -0
  60. package/lib/verification-recorder.js +44 -0
  61. package/migrations/README.md +21 -0
  62. package/package.json +8 -4
  63. package/.agents/devil-advocate.md +0 -79
  64. package/.agents/judge.md +0 -58
  65. package/.agents/workflows/ai-engineering-loop.md +0 -24
  66. package/.claude/commands/ai-engineering-loop.md +0 -11
  67. package/.gemini/skills/ai-engineering-loop/SKILL.md +0 -74
  68. package/.gemini/skills/animate/RECIPES.md +0 -324
  69. package/.gemini/skills/animate/SKILL.md +0 -207
  70. package/.gemini/skills/animate-expo/RECIPES.md +0 -385
  71. package/.gemini/skills/animate-expo/SKILL.md +0 -263
  72. package/.gemini/skills/animation-vocabulary/SKILL.md +0 -181
  73. package/.gemini/skills/apple-design/SKILL.md +0 -290
  74. package/.gemini/skills/ask-sonner/API.md +0 -64
  75. package/.gemini/skills/ask-sonner/SKILL.md +0 -88
  76. package/.gemini/skills/backend-development/SKILL.md +0 -272
  77. package/.gemini/skills/backend-development/references/api-design-guidelines.md +0 -95
  78. package/.gemini/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  79. package/.gemini/skills/backend-development/references/security-checklist.md +0 -60
  80. package/.gemini/skills/emil-design-eng/SKILL.md +0 -674
  81. package/.gemini/skills/find-animation-opportunities/SKILL.md +0 -140
  82. package/.gemini/skills/improve-animations/AUDIT.md +0 -115
  83. package/.gemini/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  84. package/.gemini/skills/improve-animations/SKILL.md +0 -109
  85. package/.gemini/skills/mobile-native/SKILL.md +0 -311
  86. package/.gemini/skills/pick-ui-library/SKILL.md +0 -85
  87. package/.gemini/skills/prototype/PICKER.md +0 -197
  88. package/.gemini/skills/prototype/SKILL.md +0 -98
  89. package/.gemini/skills/review-animations/SKILL.md +0 -120
  90. package/.gemini/skills/review-animations/STANDARDS.md +0 -187
  91. package/.gemini/skills/write-swift/SKILL.md +0 -396
  92. package/.grok/commands/ai-engineering-loop.md +0 -11
  93. package/.grok/skills/ai-engineering-loop/SKILL.md +0 -94
  94. package/.grok/skills/animate/RECIPES.md +0 -324
  95. package/.grok/skills/animate/SKILL.md +0 -207
  96. package/.grok/skills/animate-expo/RECIPES.md +0 -385
  97. package/.grok/skills/animate-expo/SKILL.md +0 -263
  98. package/.grok/skills/animation-vocabulary/SKILL.md +0 -181
  99. package/.grok/skills/apple-design/SKILL.md +0 -290
  100. package/.grok/skills/ask-sonner/API.md +0 -64
  101. package/.grok/skills/ask-sonner/SKILL.md +0 -88
  102. package/.grok/skills/backend-development/SKILL.md +0 -272
  103. package/.grok/skills/backend-development/references/api-design-guidelines.md +0 -95
  104. package/.grok/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  105. package/.grok/skills/backend-development/references/security-checklist.md +0 -60
  106. package/.grok/skills/emil-design-eng/SKILL.md +0 -674
  107. package/.grok/skills/find-animation-opportunities/SKILL.md +0 -140
  108. package/.grok/skills/improve-animations/AUDIT.md +0 -115
  109. package/.grok/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  110. package/.grok/skills/improve-animations/SKILL.md +0 -109
  111. package/.grok/skills/mobile-native/SKILL.md +0 -311
  112. package/.grok/skills/pick-ui-library/SKILL.md +0 -85
  113. package/.grok/skills/prototype/PICKER.md +0 -197
  114. package/.grok/skills/prototype/SKILL.md +0 -98
  115. package/.grok/skills/review-animations/SKILL.md +0 -120
  116. package/.grok/skills/review-animations/STANDARDS.md +0 -187
  117. package/.grok/skills/write-swift/SKILL.md +0 -396
@@ -1,207 +0,0 @@
1
- ---
2
- name: animate
3
- description: Build an animation from scratch, making the decisions in the order that determines whether it feels right — should it animate at all, what purpose, which tool, which properties, which curve and duration, how it interrupts, how it exits. Writes the implementation. Use when asked to animate something, add motion, make a component feel alive, or build a transition. For critiquing existing motion use review-animations; for auditing a whole codebase use improve-animations.
4
- ---
5
-
6
- # Building Animations
7
-
8
- ## Initial Response
9
-
10
- When this skill is first invoked without a specific question, respond only with:
11
-
12
- > I'm ready to build animations that feel right, my knowledge comes from Emil Kowalski's animation philosophy.
13
-
14
- Do not provide any other information until the user asks a question.
15
-
16
- A construction skill. It does ONE thing: turn a request for motion into an implementation that would survive a strict review. It does not audit a codebase (that's `improve-animations`), critique a diff (that's `review-animations`), hunt for places that could animate (that's `find-animation-opportunities`), or build for React Native (that's `animate-expo`).
17
-
18
- ## Operating Posture
19
-
20
- You are a senior design engineer building the animation yourself. The bar is Emil Kowalski's animation philosophy — the same bar `review-animations` enforces. Write it so it passes that review the first time.
21
-
22
- Two failure modes, and the first is worse:
23
-
24
- 1. **Animating something that shouldn't animate.** The gate below exists to produce zero lines of code sometimes. That's a success, not a dodge.
25
- 2. **Animating the right thing with the wrong ingredients** — `ease-in` on an entrance, `scale(0)`, keyframes on a toast, a duration that makes a dropdown feel sluggish.
26
-
27
- Never present motion options as a menu. Make the call, state the reasoning in one line, write the code.
28
-
29
- ## Hard Rules
30
-
31
- 1. **Run the sequence in order.** Steps 1 and 2 gate everything. Don't reach for a curve before you know whether it animates at all.
32
- 2. **No approximated values.** Every curve, duration, and spring config comes from the tables below. Never invent `cubic-bezier(0.4, 0, 0.2, 1)` because it looks familiar.
33
- 3. **Extend the codebase's tokens, don't fork them.** If `--ease-out` or a duration scale already exists, use it. Adding a parallel system is a defect.
34
- 4. **Reduced motion and hover gating ship with the animation**, not as a follow-up.
35
- 5. **Cheapest tool that works.** Don't install a motion library for a fade.
36
-
37
- ## The Build Sequence
38
-
39
- ### 1. Should this animate at all?
40
-
41
- | Frequency | Decision |
42
- | --- | --- |
43
- | 100+ times/day (keyboard shortcuts, command palette toggle) | **No animation. Ever.** Stop here. |
44
- | Tens of times/day (hover effects, list navigation) | Near-imperceptible only — fast and subtle, or nothing |
45
- | Occasional (modals, drawers, toasts) | Standard animation |
46
- | Rare / first-time (onboarding, success, celebration) | The delight budget lives here |
47
-
48
- **Keyboard-initiated actions are a disqualifier, not a judgment call.** Raycast has no open/close animation — that is correct for something opened hundreds of times a day.
49
-
50
- If the request fails this gate, say so plainly and don't write the animation. Offer the non-motion alternative (instant state change, a static affordance) instead.
51
-
52
- ### 2. What is the purpose?
53
-
54
- Name it in one of these words before continuing:
55
-
56
- - **Feedback** — confirming the interface heard the user
57
- - **Spatial consistency** — showing where something came from or went
58
- - **State indication** — making a state change legible
59
- - **Preventing a jarring change** — bridging content that would otherwise teleport
60
- - **Explanation** — demonstrating how something works (marketing/onboarding only)
61
- - **Delight** — allowed *only* at the rare/first-time tier
62
-
63
- Can't name it? Don't build it. "It looks cool" on a frequently-seen element is a reason to stop.
64
-
65
- Also check **function**: data the user is reading or acting on should not move for style. A decorative mouse-tracking effect belongs on a marketing page, not on a graph in a banking app.
66
-
67
- ### 3. Pick the tool — cheapest that works
68
-
69
- Walk down; stop at the first that fits.
70
-
71
- | Need | Tool |
72
- | --- | --- |
73
- | Hover, press, color, a state toggle you control with a class or attribute | **CSS transition** |
74
- | Entry animation on mount, no JS state | **CSS `@starting-style`** |
75
- | Predetermined motion that must stay smooth while the page is busy loading | **CSS animation** (runs off the main thread) |
76
- | Programmatic control with CSS performance, no library | **WAAPI** (`element.animate()`) |
77
- | Springs, layout animations, exit animations, gesture-driven values | **Motion** (`motion.dev`) |
78
-
79
- CSS animations beat JS under load — they run off the main thread, while `requestAnimationFrame`-based animation drops frames while the browser loads, scripts, or paints. Use CSS for predetermined motion, JS for dynamic and interruptible motion.
80
-
81
- If the task needs a *component* rather than an animation — a toast, a drawer, a command menu, a dropdown — stop and invoke `pick-ui-library`. Hand-rolling those is how you end up with a `<div>` dropdown and no focus management.
82
-
83
- ### 4. Pick the properties
84
-
85
- - **`transform` and `opacity` only.** They skip layout and paint and run on the GPU. `width`/`height`/`margin`/`padding`/`top`/`left` trigger all three. (`clip-path` is the sanctioned fourth — see RECIPES.md. `height` is tolerated only for accordions, where there's no transform equivalent.)
86
- - **Never `scale(0)`.** Start from `scale(0.9–0.97)` + `opacity: 0`. Nothing in the real world appears from nothing.
87
- - **`transform-origin` at the trigger** for popovers, dropdowns, menus, tooltips — `var(--transform-origin)` in Base UI. **Modals are exempt**; they're not anchored to a trigger, so they stay centered.
88
- - **Percentages in `translate()`** are relative to the element's own size — `translateY(100%)` moves by its own height whatever the content. Prefer over hardcoded pixels.
89
- - **In Motion, use the full transform string.** `x`/`y`/`scale` shorthands are not hardware-accelerated and drop frames under load:
90
-
91
- ```jsx
92
- <motion.div animate={{ x: 100 }} /> // drops frames under load
93
- <motion.div animate={{ transform: "translateX(100px)" }} /> // hardware accelerated
94
- ```
95
-
96
- - **Never drive a child's transform from a CSS variable on the parent** — it recalculates styles for every child. Set `transform` on the element directly.
97
-
98
- ### 5. Easing and duration — or a spring
99
-
100
- **Easing**, in decision order:
101
-
102
- | Situation | Easing |
103
- | --- | --- |
104
- | Entering or exiting | `ease-out` |
105
- | Moving / morphing on screen | `ease-in-out` |
106
- | Hover / color change | `ease` |
107
- | Constant motion (marquee, progress) | `linear` |
108
- | Default | `ease-out` |
109
-
110
- **Never `ease-in` on UI.** It starts slow, delaying the exact moment the user is watching. `ease-out` at 200ms *feels* faster than `ease-in` at 200ms.
111
-
112
- Built-in CSS easings are too weak. Use these:
113
-
114
- ```css
115
- --ease-out: cubic-bezier(0.23, 1, 0.32, 1); /* strong ease-out for UI */
116
- --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1); /* strong ease-in-out for on-screen movement */
117
- --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1); /* iOS-like drawer curve (Ionic) */
118
- ```
119
-
120
- Need a curve that isn't here? Take it from [easing.dev](https://easing.dev/) or [easings.co](https://easings.co/). Don't hand-roll one.
121
-
122
- **Duration:**
123
-
124
- | Element | Duration |
125
- | --- | --- |
126
- | Button press feedback | 100–160ms |
127
- | Tooltips, small popovers | 125–200ms |
128
- | Dropdowns, selects | 150–250ms |
129
- | Modals, drawers | 200–500ms |
130
- | Marketing / explanatory | Can be longer |
131
-
132
- **UI animations stay under 300ms.** A 180ms dropdown feels more responsive than a 400ms one.
133
-
134
- **Reach for a spring instead** when the motion is drag with momentum, an element that should feel alive, a gesture the user can interrupt or reverse, or decorative mouse-tracking:
135
-
136
- ```js
137
- { type: "spring", duration: 0.5, bounce: 0.2 } // Apple-style — easier to reason about
138
- { type: "spring", mass: 1, stiffness: 100, damping: 10 } // traditional physics — more control
139
- ```
140
-
141
- Keep bounce at 0.1–0.3, and avoid bounce in most UI — reserve it for drag-to-dismiss and playful interactions.
142
-
143
- ### 6. Interruption and exit
144
-
145
- - **Transitions, not keyframes, for anything triggered rapidly** — toasts, toggles, anything a user can fire twice in a second. Transitions retarget from the current value; keyframes restart from zero.
146
- - **Springs for gestures**, because they carry velocity through an interruption.
147
- - **Exit the way it entered.** A toast that slides in from the bottom leaves through the bottom. Symmetric paths are what make swipe-to-dismiss feel obvious.
148
- - **Asymmetric timing where the user is deciding.** Slow on the deliberate phase (a hold-to-confirm press: 2s linear), snappy on the system response (release: 200ms ease-out).
149
-
150
- ### 7. Reduced motion and pointer gating
151
-
152
- Ships with the animation, every time.
153
-
154
- ```css
155
- @media (prefers-reduced-motion: reduce) {
156
- .element { animation: fade 0.2s ease; } /* keep opacity/color, drop transform-based motion */
157
- }
158
-
159
- @media (hover: hover) and (pointer: fine) {
160
- .element:hover { transform: scale(1.05); } /* touch fires false hovers on tap */
161
- }
162
- ```
163
-
164
- ```jsx
165
- const reduce = useReducedMotion();
166
- const closedX = reduce ? 0 : '-100%';
167
- ```
168
-
169
- Reduced motion means **fewer and gentler** animations, not zero — keep transitions that aid comprehension, remove movement and position changes.
170
-
171
- ## Recipes
172
-
173
- For ready-to-build implementations of the common cases — button press, dropdown, tooltip, modal, drawer, toast, accordion, stagger, hold-to-confirm, tab indicator, scroll reveal, drag-to-dismiss — see [RECIPES.md](RECIPES.md). Load it whenever the request matches one of those components; start from the recipe rather than from a blank file.
174
-
175
- ## Never Ship
176
-
177
- Self-check before you finish. Each of these is an automatic block in `review-animations`:
178
-
179
- | Never | Instead |
180
- | --- | --- |
181
- | `transition: all` | Name the exact properties |
182
- | `transform: scale(0)` entrance | `scale(0.95)` + `opacity: 0` |
183
- | `ease-in` on a UI element | `ease-out` or a strong custom curve |
184
- | Built-in `ease-out` on a deliberate animation | `cubic-bezier(0.23, 1, 0.32, 1)` |
185
- | Animation on a keyboard shortcut or 100+/day action | No animation |
186
- | UI duration over 300ms with no reason | 150–250ms |
187
- | `transform-origin: center` on a trigger-anchored popover | `var(--transform-origin)` (modals exempt) |
188
- | Keyframes on toasts, toggles, rapidly-triggered elements | CSS transitions |
189
- | Animating `width`/`height`/`margin`/`padding`/`top`/`left` | `transform` / `opacity` |
190
- | Motion `x`/`y`/`scale` props under load | Full `transform` string |
191
- | Ungated `:hover` motion | `@media (hover: hover) and (pointer: fine)` |
192
- | Missing `prefers-reduced-motion` | Gentler variant, not zero |
193
- | Everything entering at once | 30–80ms stagger |
194
-
195
- ## Output
196
-
197
- Write the code. Then, in at most a few lines:
198
-
199
- - **The gate result** — frequency tier and the named purpose. If something in the request was rejected, say which and why.
200
- - **The ingredients** — tool, properties, curve, duration or spring config, in one line each.
201
- - **What to feel-check** — if the result depends on feel you can't judge from code (a crossfade, a spring's bounce, the opacity/height balance in an entering list), say so and point at the check: play it at 2–5× duration or in the DevTools animation inspector, step it frame by frame, test gestures on a real device, and look again the next day with fresh eyes.
202
-
203
- Don't pad this into a report. The code is the deliverable.
204
-
205
- ## Tone
206
-
207
- Opinionated and brief. When the honest answer is "this shouldn't animate," give it — that answer is the reason this skill exists. When feel genuinely can't be settled from code, say so instead of guessing at a value.
@@ -1,385 +0,0 @@
1
- # Expo Animation Recipes
2
-
3
- Ready-to-build implementations for the cases that come up most in a React Native app. Start from the recipe, then adapt.
4
-
5
- ---
6
-
7
- ## Setup the recipes assume
8
-
9
- ```bash
10
- npx expo install react-native-reanimated react-native-worklets react-native-gesture-handler expo-haptics
11
- ```
12
-
13
- (`react-native-keyboard-controller` only for the keyboard recipe.) `expo install`, not `npm install` — it resolves the versions that match the SDK. The worklets Babel plugin is configured by `babel-preset-expo` automatically.
14
-
15
- `GestureHandlerRootView` wraps the app once — in Expo Router, the root `_layout`:
16
-
17
- ```jsx
18
- import { GestureHandlerRootView } from 'react-native-gesture-handler';
19
-
20
- export default function RootLayout() {
21
- return (
22
- <GestureHandlerRootView style={{ flex: 1 }}>
23
- <Stack />
24
- </GestureHandlerRootView>
25
- );
26
- }
27
- ```
28
-
29
- Imports and constants every recipe below shares:
30
-
31
- ```js
32
- import { useState, useEffect, useMemo } from 'react';
33
- import Animated, {
34
- useSharedValue, useAnimatedStyle, useAnimatedScrollHandler, useAnimatedReaction,
35
- withSpring, withTiming, interpolate, Extrapolation, Easing,
36
- FadeInDown, FadeOutDown, LinearTransition,
37
- } from 'react-native-reanimated';
38
- import { Gesture, GestureDetector } from 'react-native-gesture-handler';
39
- import { scheduleOnRN } from 'react-native-worklets';
40
- import * as Haptics from 'expo-haptics';
41
-
42
- const EASE_OUT = Easing.bezier(0.23, 1, 0.32, 1); // strong ease-out for UI
43
- const EASE_IN_OUT = Easing.bezier(0.77, 0, 0.175, 1); // on-screen movement
44
- const EASE_SHEET = Easing.bezier(0.32, 0.72, 0, 1); // iOS sheet curve
45
- ```
46
-
47
- Three conventions, explained once here instead of in every recipe:
48
-
49
- - **Shared values are read and written with `.get()` / `.set()`**, the form the Reanimated docs recommend for React Compiler support. `.value` still works, but the compiler can't see through it.
50
- - **`scheduleOnRN(fn, ...args)` replaces the deprecated `runOnJS(fn)(...args)`** for calling back to the React Native runtime from a worklet.
51
- - **Gestures are wrapped in `useMemo`.** Rebuilding a gesture on every render can reattach the recognizer and drop a drag that's mid-flight.
52
-
53
- **Gesture Handler v3:** Expo installs v2, and the recipes use its `Gesture.Pan()` builder. If the project is already on v3, the builder is legacy — each gesture is a hook taking one config object, with `onStart` → `onActivate`, `onEnd` → `onDeactivate`, and the `success` flag replaced by `event.canceled` (inverted). The hook manages its own identity, so drop the `useMemo`:
54
-
55
- ```jsx
56
- const pan = usePanGesture({
57
- activeOffsetY: [-10, 10],
58
- onActivate: () => { context.set(translateY.get()); },
59
- onUpdate: (e) => { translateY.set(context.get() + e.translationY); },
60
- onDeactivate: (e) => { /* settle with withSpring as below */ },
61
- });
62
- ```
63
-
64
- ---
65
-
66
- ## Two worklets you'll need everywhere
67
-
68
- Momentum projection decides *where a flick was going*, so a fast short swipe commits and a slow long one doesn't. Rubber-banding makes a boundary resist instead of stopping dead.
69
-
70
- ```js
71
- // Where the finger would come to rest if it kept decelerating.
72
- // Apple's exponential-decay form — not the v²/2a from physics class.
73
- function project(velocity, decelerationRate = 0.998) {
74
- 'worklet';
75
- return ((velocity / 1000) * decelerationRate) / (1 - decelerationRate);
76
- }
77
-
78
- // The further past the edge, the less the element follows.
79
- function rubberband(overshoot, dimension, constant = 0.55) {
80
- 'worklet';
81
- return (overshoot * dimension * constant) / (dimension + constant * Math.abs(overshoot));
82
- }
83
- ```
84
-
85
- ---
86
-
87
- ## Press feedback
88
-
89
- Every pressable in the app. This passes the frequency gate only because it's near-imperceptible: 120ms and a 3% scale is the ceiling for something touched this often — anything longer or larger belongs to rarer moments, per step 1 in SKILL.md. No gesture, no shared value — a CSS transition is the whole implementation.
90
-
91
- ```jsx
92
- import Animated from 'react-native-reanimated';
93
- import { Pressable, StyleSheet } from 'react-native';
94
-
95
- function PressableScale({ onPress, children }) {
96
- const [pressed, setPressed] = useState(false);
97
- return (
98
- <Pressable
99
- onPress={onPress}
100
- onPressIn={() => setPressed(true)}
101
- onPressOut={() => setPressed(false)}
102
- hitSlop={12}
103
- pressRetentionOffset={16}
104
- >
105
- <Animated.View style={[styles.box, pressed && styles.pressed]}>{children}</Animated.View>
106
- </Pressable>
107
- );
108
- }
109
-
110
- const styles = StyleSheet.create({
111
- box: {
112
- transform: [{ scale: 1 }],
113
- transitionProperty: 'transform',
114
- transitionDuration: '120ms',
115
- transitionTimingFunction: 'cubic-bezier(0.23, 1, 0.32, 1)',
116
- },
117
- pressed: { transform: [{ scale: 0.97 }] },
118
- });
119
- ```
120
-
121
- `setState` is fine here — it fires twice per press, not per frame. `hitSlop` brings a small icon up to the 44pt target without growing it; `pressRetentionOffset` stops a slight finger drift from cancelling.
122
-
123
- ---
124
-
125
- ## Bottom sheet you can drag to dismiss
126
-
127
- Before writing this: if the sheet is its own destination, use `presentation: 'formSheet'` (see **Screen transitions**) and get the platform's real sheet for free. Build this only when the sheet has to live inside an existing screen.
128
-
129
- ```jsx
130
- const translateY = useSharedValue(0);
131
- const context = useSharedValue(0);
132
-
133
- const pan = useMemo(() => Gesture.Pan()
134
- .activeOffsetY([-10, 10]) // let a horizontal swipe win; require intent before committing
135
- .onStart(() => {
136
- context.set(translateY.get()); // start from the current on-screen value, not from 0
137
- })
138
- .onUpdate((e) => {
139
- const next = context.get() + e.translationY;
140
- // downward is free; upward past the top resists
141
- translateY.set(next >= 0 ? next : rubberband(next, HEIGHT));
142
- })
143
- .onEnd((e) => {
144
- const projected = translateY.get() + project(e.velocityY);
145
- if (projected > HEIGHT * 0.4) {
146
- translateY.set(withSpring(HEIGHT, {
147
- duration: 300, dampingRatio: 1, velocity: e.velocityY, overshootClamping: true,
148
- }, (finished) => { if (finished) scheduleOnRN(onClose); }));
149
- } else {
150
- translateY.set(withSpring(0, { duration: 300, dampingRatio: 0.8, velocity: e.velocityY }));
151
- scheduleOnRN(Haptics.impactAsync, Haptics.ImpactFeedbackStyle.Light); // it snapped home
152
- }
153
- }), [onClose]);
154
-
155
- const sheetStyle = useAnimatedStyle(() => ({ transform: [{ translateY: translateY.get() }] }));
156
- ```
157
-
158
- The four details that separate this from a bad drag:
159
-
160
- - **`onStart` captures the current value.** Without it, grabbing a sheet mid-animation teleports it — the animation must continue from where the eye last saw it.
161
- - **Velocity decides, not distance.** `project()` means a quick flick dismisses even a few pixels down. Requiring 40% travel makes the sheet feel heavy.
162
- - **Velocity is handed to the spring**, so there's no seam between the finger releasing and the animation continuing. This is the single detail that most separates "fluid" from "fine".
163
- - **`overshootClamping` on dismissal** — otherwise the sheet springs past the bottom of the screen and flashes a gap.
164
-
165
- The backdrop derives from the same value, so it's always in sync and costs nothing:
166
-
167
- ```jsx
168
- const backdropStyle = useAnimatedStyle(() => ({
169
- opacity: interpolate(translateY.get(), [0, HEIGHT], [1, 0], Extrapolation.CLAMP),
170
- }));
171
- ```
172
-
173
- ---
174
-
175
- ## Swipe to delete a row
176
-
177
- Before writing this: gesture-handler ships [`ReanimatedSwipeable`](https://docs.swmansion.com/react-native-gesture-handler/docs/components/reanimated_swipeable/), which already does swipe-to-reveal actions — thresholds, overshoot, open/close methods — on the UI thread. Reach for it when the row reveals action buttons. Build the gesture yourself only when the interaction is different in kind: swipe-to-commit with momentum projection, like this one.
178
-
179
- ```jsx
180
- const x = useSharedValue(0);
181
- const context = useSharedValue(0);
182
-
183
- const pan = useMemo(() => Gesture.Pan()
184
- .activeOffsetX([-10, 10]) // must declare the axis, or it fights the vertical scroll
185
- .onStart(() => { context.set(x.get()); }) // grab mid-spring continues from where the row is, not from 0
186
- .onUpdate((e) => { x.set(Math.min(0, context.get() + e.translationX)); })
187
- .onEnd((e) => {
188
- const projected = x.get() + project(e.velocityX);
189
- if (projected < -SWIPE_THRESHOLD) {
190
- x.set(withTiming(-WIDTH, { duration: 200, easing: EASE_OUT }, (f) => {
191
- if (f) scheduleOnRN(onDelete, id);
192
- }));
193
- } else {
194
- x.set(withSpring(0, { duration: 300, dampingRatio: 1, velocity: e.velocityX }));
195
- }
196
- }), [onDelete, id]);
197
- ```
198
-
199
- Closing the gap the deleted row left is the list's job, not the row's:
200
-
201
- ```jsx
202
- const ROW_CLOSE = LinearTransition.duration(200); // module scope — builders rebuilt in render cost every re-render
203
-
204
- <Animated.FlatList data={items} itemLayoutAnimation={ROW_CLOSE} ... />
205
- ```
206
-
207
- `activeOffsetX` is the mobile-specific part. A pan handler inside a scroll view with no axis declared will steal vertical scrolls, and the list will feel broken in a way that looks like a scrolling bug rather than a gesture bug.
208
-
209
- ---
210
-
211
- ## Collapsing header on scroll
212
-
213
- ```jsx
214
- const scrollY = useSharedValue(0);
215
- const onScroll = useAnimatedScrollHandler((e) => { scrollY.set(e.contentOffset.y); });
216
-
217
- const titleStyle = useAnimatedStyle(() => ({
218
- opacity: interpolate(scrollY.get(), [0, 60], [1, 0], Extrapolation.CLAMP),
219
- transform: [{ translateY: interpolate(scrollY.get(), [0, 60], [0, -12], Extrapolation.CLAMP) }],
220
- }));
221
-
222
- <Animated.ScrollView onScroll={onScroll} scrollEventThrottle={16}>
223
- ```
224
-
225
- **Never animate the header's `height` to collapse it.** That runs a layout pass on the header and everything below it on every scroll frame — the one animation guaranteed to stutter, because it's competing with the scroll itself. Give the container a fixed height and translate the content inside it, clipping with `overflow: 'hidden'`.
226
-
227
- `Extrapolation.CLAMP` is not optional: without it, scrolling past 60 keeps driving opacity negative and the header reappears inverted at the bottom of a long list.
228
-
229
- ---
230
-
231
- ## List entrances
232
-
233
- ```jsx
234
- // The Reanimated docs recommend building layout animations outside components,
235
- // or in useMemo — an inline chain in JSX rebuilds the builder on every render.
236
- // A per-index delay can't live at module scope, so the row memoizes its own:
237
- function Row({ item, index }) {
238
- const entering = useMemo(() => FadeInDown.duration(250).delay(index * 40), [index]);
239
- return <Animated.View entering={entering}>{/* ... */}</Animated.View>;
240
- }
241
-
242
- {items.map((item, i) => <Row key={item.id} item={item} index={i} />)}
243
- ```
244
-
245
- Stagger 30–80ms. Longer feels slow, shorter reads as simultaneous.
246
-
247
- **Never put `entering` on a row inside `FlatList`, `FlashList`, or any virtualized list.** Rows are recycled, so the animation re-fires every time one scrolls back into view — the list appears to flicker while the user scrolls. Animate the list container once on mount, or use `itemLayoutAnimation` for reflow only.
248
-
249
- Entrance animations are for content the user asked for and is waiting on. A list they scroll past all day should already be there.
250
-
251
- ---
252
-
253
- ## Keyboard-synced UI
254
-
255
- Needs its own module and a one-time provider ([Expo keyboard guide](https://docs.expo.dev/guides/keyboard-handling/)):
256
-
257
- ```bash
258
- npx expo install react-native-keyboard-controller
259
- ```
260
-
261
- ```jsx
262
- import { KeyboardProvider } from 'react-native-keyboard-controller';
263
-
264
- // Root _layout, next to GestureHandlerRootView — hooks below do nothing without it.
265
- <KeyboardProvider>
266
- <Stack />
267
- </KeyboardProvider>
268
- ```
269
-
270
- ```jsx
271
- import { useReanimatedKeyboardAnimation } from 'react-native-keyboard-controller';
272
-
273
- const { height } = useReanimatedKeyboardAnimation(); // 0 → -keyboardHeight, on the UI thread
274
- const footerStyle = useAnimatedStyle(() => ({ transform: [{ translateY: height.get() }] }));
275
- ```
276
-
277
- Never build this from `Keyboard.addListener` plus a timing animation. The keyboard rides a private system curve, the event arrives on the JS thread after the keyboard has already started moving, and any duration you pick will visibly lag or lead it. The UI must be driven by the keyboard's actual position, frame by frame.
278
-
279
- ---
280
-
281
- ## Tab / segmented indicator
282
-
283
- Measure once, then animate transforms.
284
-
285
- ```jsx
286
- const [layouts, setLayouts] = useState({}); // measured with onLayout, not per frame
287
- const x = useSharedValue(0);
288
- const w = useSharedValue(0);
289
-
290
- useEffect(() => {
291
- const l = layouts[active];
292
- if (!l) return;
293
- x.set(withTiming(l.x, { duration: 250, easing: EASE_IN_OUT }));
294
- w.set(withTiming(l.width, { duration: 250, easing: EASE_IN_OUT }));
295
- }, [active, layouts]);
296
-
297
- const pillStyle = useAnimatedStyle(() => ({
298
- transform: [{ translateX: x.get() }],
299
- width: w.get(),
300
- }));
301
- ```
302
-
303
- This is the sanctioned `width` animation: the pill is absolutely positioned with no children, so nothing else re-lays-out, and its corner radius survives — `scaleX` would smear the corners into ovals.
304
-
305
- `ease-in-out`, because the pill is moving across the screen rather than entering or leaving it. Fire `Haptics.selectionAsync()` on the press, not when the pill lands.
306
-
307
- ---
308
-
309
- ## Screen transitions (Expo Router)
310
-
311
- Configure the native stack. Never rebuild a screen transition in JS: the native one runs on the platform side, keeps the interactive back gesture, and matches every other app on the device.
312
-
313
- ```jsx
314
- <Stack screenOptions={{ animation: reduced ? 'fade' : 'default' }}>
315
- <Stack.Screen name="settings" options={{ animation: 'slide_from_right', animationMatchesGesture: true }} />
316
- <Stack.Screen name="compose" options={{ presentation: 'modal' }} />
317
- <Stack.Screen name="filter" options={{
318
- presentation: 'formSheet',
319
- sheetAllowedDetents: 'fitToContents',
320
- sheetGrabberVisible: true,
321
- }} />
322
- </Stack>
323
- ```
324
-
325
- | Navigation | Option |
326
- | --- | --- |
327
- | Deeper into a hierarchy | `animation: 'default'` — the platform push, unmodified |
328
- | A self-contained task the user can abandon | `presentation: 'modal'` |
329
- | A short interruption: picker, filter, share | `presentation: 'formSheet'` with detents |
330
- | Between tabs | `animation: 'none'` |
331
- | Reduced motion | `animation: 'fade'` |
332
-
333
- `animationMatchesGesture: true` makes the iOS back swipe run your transition in reverse under the finger, instead of the default push. Set it whenever you set a custom `animation`, or dragging back looks like a different app than pushing forward.
334
-
335
- `formSheet` is native on both platforms, but not the same on both — the [Expo modal docs](https://docs.expo.dev/router/advanced/modals/#form-sheet-presentation) have the full list:
336
-
337
- - **Android caps detents at three.** A longer `sheetAllowedDetents` array works on iOS and silently truncates on Android — design for three.
338
- - **`sheetGrabberVisible` is iOS-only.** Android shows no grabber; don't rely on it as the only "this is draggable" affordance.
339
- - **Android form sheets can't host native headers or nested stacks.** Keep the sheet's content a single screen; if it needs its own navigation, use `presentation: 'modal'` instead.
340
- - **`fitToContents` needs explicitly sized content.** A `flex: 1` root has no intrinsic height to fit — size the content, or the detent is wrong.
341
-
342
- ---
343
-
344
- ## Toast
345
-
346
- ```jsx
347
- // Module scope — layout-animation builders live outside the component.
348
- const TOAST_ENTER = FadeInDown.duration(300).easing(EASE_OUT);
349
- const TOAST_EXIT = FadeOutDown.duration(250).easing(EASE_OUT);
350
-
351
- <Animated.View
352
- entering={TOAST_ENTER}
353
- exiting={TOAST_EXIT}
354
- style={{ position: 'absolute', bottom: insets.bottom + 16, left: 16, right: 16 }}
355
- />
356
- ```
357
-
358
- - **The 300ms cap holds here too.** A toast isn't an exception — it's uninvited, so if anything it should be quicker and quieter than motion the user asked for.
359
- - **It exits the way it entered.** Entering from the bottom and leaving to the side reads as two unrelated elements.
360
- - **Exit ~20% faster than entry.** The user has finished reading; the arrival deserves the time, the departure doesn't.
361
- - **Safe area insets, always.** A toast at `bottom: 16` sits under the home indicator on every modern iPhone.
362
-
363
- If toasts stack and the list reflows, add `itemLayoutAnimation` and expect to tune the opacity against the reflow by eye — there's no formula for that pair. Look at it again the next day.
364
-
365
- ---
366
-
367
- ## Firing something once at a threshold
368
-
369
- When a crossing point matters — a detent, a snap, a pull-to-refresh arming — don't poll it from JS and don't `scheduleOnRN` every frame.
370
-
371
- ```jsx
372
- const armed = useSharedValue(false);
373
-
374
- useAnimatedReaction(
375
- () => pullDistance.get() > REFRESH_THRESHOLD,
376
- (isArmed, wasArmed) => {
377
- if (isArmed !== wasArmed) {
378
- armed.set(isArmed);
379
- scheduleOnRN(Haptics.impactAsync, Haptics.ImpactFeedbackStyle.Light);
380
- }
381
- }
382
- );
383
- ```
384
-
385
- The comparison runs on the UI thread every frame; the JS call happens twice per pull. That's the pattern for every "do something when the animation reaches X".