@rafaelaugusto/jolt 0.1.0-beta.0 → 0.1.0-beta.10

package/README.md

@@ -1,6 +1,23 @@
-# Jolt
-
-Native animations for [NativeScript](https://nativescript.org): presets, springs, keyframes and stagger, one call each.
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rafaelaugustos/jolt/main/.github/assets/logo-dark.png">
+    <img src="https://raw.githubusercontent.com/rafaelaugustos/jolt/main/.github/assets/logo.png" alt="Jolt" width="280">
+  </picture>
+</p>
+
+<p align="center">
+  Native animations for <a href="https://nativescript.org">NativeScript</a>: presets, springs, keyframes and stagger, one call each.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@rafaelaugusto/jolt"><img src="https://img.shields.io/npm/v/@rafaelaugusto/jolt/next?label=npm%40next" alt="npm"></a>
+  <a href="https://github.com/rafaelaugustos/jolt/actions/workflows/ci.yml"><img src="https://github.com/rafaelaugustos/jolt/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/rafaelaugustos/jolt/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@rafaelaugusto/jolt" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="https://jolt.rafaelaugusto.dev">Documentation</a> · <a href="https://jolt.rafaelaugusto.dev/pt-BR/">Documentação em português</a>
+</p>
 
 ```ts
 import { animate } from '@rafaelaugusto/jolt'
@@ -14,6 +31,42 @@ NativeScript's `view.animate()` covers the basics and stops there: one curve for
 
 Jolt computes the motion once, in JavaScript, when the animation starts, and hands it to the platform as keyframes: Core Animation on iOS, `ObjectAnimator` on Android. Nothing runs in JavaScript while it plays. Springs follow real physics, and an animation that interrupts another one starts from where the view is, at the speed it was going.
 
+## Features
+
+- [25 presets](#presets) to enter, exit and draw attention: `fadeInUp`, `popIn`, `shake`, `heartbeat`...
+- [Springs](#springs) described by feel (`bouncy`), by `bounce` and `duration`, or by stiffness, damping and mass.
+- [Corners, borders and shadows](#corners-borders-and-shadows) with native playback and selective stopping.
+- [Motion paths](#motion-along-a-path) with optional tangent orientation on iOS and Android.
+- [Colors](#colors) for backgrounds, borders and text, interpolated in OKLab on iOS and Android.
+- [Motion scopes and states](https://jolt.rafaelaugusto.dev/guide/motion-controllers) for component cleanup and coordinated visual states.
+- [Animated touch targets](https://jolt.rafaelaugusto.dev/guide/interaction-surface) with an opt-in native interaction surface.
+- [Layout changes](https://jolt.rafaelaugusto.dev/guide/layout): insertion, removal, reorder and resize of container children.
+- [Drag](https://jolt.rafaelaugusto.dev/guide/drag) with bounds, snap points, rubberband and native release physics.
+- [Decay](#decay) from a release velocity, with optional snap points.
+- [Keyframes and tweens](#tweens) with an easing per segment and exact keyframe times.
+- [Stagger](#several-views) across several views, from the first, the last or the center.
+- [List rows](#list-rows) that play an entrance as they scroll into view, every time or once per item.
+- [Sequences](#sequences) with overlapping arrivals, shared starts and absolute timeline positions.
+- [Press effects](#press) that follow the finger and let go when a scroll takes over.
+- [Vue directives and a transition component](#vue) from the optional `@rafaelaugusto/jolt/vue` entry.
+- [Text entrances](#text) by letter or word on iOS and Android, preserving the Label’s layout and accessibility.
+- [Rolling numbers](#rolling-numbers) that slide only the changed digits in and out, on iOS and Android.
+- [SF Symbol effects](#sf-symbols) and animated icon replacement on iOS 17+.
+- [Shimmer](#shimmer) for loading placeholders on iOS.
+- [Liquid images](#liquid-images) with native texture deformation on iOS.
+- [Image effects](https://jolt.rafaelaugusto.dev/guide/image-effects): ripple, touch distortion and dissolve with native Metal/AGSL rendering and explicit fallback.
+- [Photo zoom and pan](https://jolt.rafaelaugusto.dev/guide/photo-zoom): native pinch, double tap, bounds and vertical dismissal intents.
+- [Loaders](#loaders) with dots, bars and ring styles on iOS.
+- [Circular reveal](#circular-reveal) to show or hide content from a point on iOS.
+- [Haptics](#haptics) at arrival or at marked points in an animation on iOS.
+- [Particles and confetti](#particles-and-confetti) on iOS.
+- [Scroll-linked animations](#scroll-linked-animations) for parallax and collapsing headers.
+- [Keyboard following](#follow-the-keyboard) for composers that rise with the keyboard, at its speed and curve.
+- [Playback controls](#pause-play-and-scrub) to pause, continue and scrub a finite timeline.
+- [Time scale and reduced motion](#time-scale-and-reduced-motion): slow everything down while tuning, and follow the platform's reduced-motion setting by default.
+- [Interruptions](#interrupting-and-stopping) that pick up the value and velocity on screen, with no jump.
+- [Native playback](#how-it-works): Core Animation on iOS, `ObjectAnimator` on Android, nothing in JavaScript while it plays.
+
 ## Install
 
 ```sh
@@ -22,6 +75,8 @@ npm install @rafaelaugusto/jolt@next
 
 It's in beta for now, published under the `next` tag. Requires `@nativescript/core` 8.9 or later. It doesn't depend on a framework: it takes a view, or an element that holds one.
 
+On iOS 15+, Jolt requests up to 120 Hz on ProMotion displays. Set `CADisableMinimumFrameDurationOnPhone` to `true` in the app's `App_Resources/iOS/Info.plist` and rebuild to enable higher rates on iPhone. See the [iOS setup](https://jolt.rafaelaugusto.dev/guide/install#promotion-on-ios); the system still chooses the actual refresh rate.
+
 ## Animating
 
 `animate(target, keyframes, transition?)` takes a view and where to take it:
@@ -30,14 +85,17 @@ It's in beta for now, published under the `next` tag. Requires `@nativescript/co
 animate(card, { opacity: 0.5, y: -20 })
 ```
 
-| Property             | Unit                                     |
-| -------------------- | ---------------------------------------- |
-| `opacity`            |                                          |
-| `x`, `y`             | DIPs, same as `translateX`, `translateY` |
-| `scale`              | sets `scaleX` and `scaleY` together      |
-| `scaleX`, `scaleY`   |                                          |
-| `rotate`             | degrees                                  |
-| `rotateX`, `rotateY` | degrees, with perspective                |
+| Property                                  | Unit                                     |
+| ----------------------------------------- | ---------------------------------------- |
+| `opacity`                                 |                                          |
+| `x`, `y`                                  | DIPs, same as `translateX`, `translateY` |
+| `scale`                                   | sets `scaleX` and `scaleY` together      |
+| `scaleX`, `scaleY`                        |                                          |
+| `rotate`                                  | degrees                                  |
+| `rotateX`, `rotateY`                      | degrees, with perspective                |
+| `backgroundColor`, `borderColor`, `color` | NativeScript color string or `Color`     |
+
+3D rotations and flip presets use the view's `perspective` on both platforms (NativeScript defaults to 1000 DIPs). Set `card.perspective = 600` for stronger depth. Android applies the display density when configuring its camera distance; it keeps the perspective when a rotation ends or stops at an angle.
 
 A single value animates from wherever the view is. An array is a list of keyframes, and `null` stands for the current value:
 
@@ -46,6 +104,15 @@ animate(card, { x: [0, 100] }) // from 0, whatever x is now
 animate(card, { x: [null, 20, -20, null] }) // out and back to where it was
 ```
 
+With `relative: true`, translation and rotation keyframes are offsets from the current value. Scale and opacity keyframes multiply it instead. Each scale axis keeps its own base, and `null` still means the current value.
+
+```ts
+animate(card, { x: [0, -10, 10, 0] }, { relative: true }) // shake around its current x
+animate(card, { scale: [1, 1.06, 1] }, { relative: true }) // grow by 6% and return
+```
+
+The base is captured once when the view is ready and its tracks are created, before any delay or stagger. Repeats reuse that base. A relative step in a sequence resolves when the step starts; an unloaded view waits until it loads.
+
 The target can be a view, or anything that holds one: a NativeScript-Vue template ref, an Angular `ElementRef`.
 
 ```vue
@@ -59,11 +126,69 @@ const open = () => animate(card.value, 'popIn')
 </template>
 ```
 
-A view that isn't loaded yet takes its first keyframe right away and plays once it's on screen. Calling `animate(title, 'fadeInUp')` in `onMounted` doesn't flash the title before it fades in.
+A view that isn't loaded yet takes its first absolute keyframe right away and plays once it's on screen. Calling `animate(title, 'fadeInUp')` in `onMounted` doesn't flash the title before it fades in. Relative animations leave the view's values alone until it loads.
+
+## Vue
+
+```vue
+<script setup lang="ts">
+import { JoltTransition, vAnimate, vPress } from '@rafaelaugusto/jolt/vue'
+</script>
+
+<template>
+  <Label v-animate="'fadeInUp'" text="Hello" />
+  <GridLayout v-press="{ scale: 0.95 }" />
+  <JoltTransition enter="popIn" leave="fadeOut">
+    <Label v-if="saved" text="Saved" />
+  </JoltTransition>
+</template>
+```
+
+`@rafaelaugusto/jolt/vue` is a separate entry point for NativeScript-Vue 3, so the core stays framework free. `v-animate` plays when the element mounts and again when its value changes, `v-press` is `press()` for templates, and `JoltTransition` wraps Vue's `BaseTransition` so a view can animate out before `v-if` removes it. Register everything with `app.use(Jolt)` or import what a component needs. See the [Vue guide](https://jolt.rafaelaugusto.dev/guide/vue).
+
+## Motion along a path
+
+```ts
+animate(
+  plane,
+  { path: 'M0 0 C80 -120 200 -120 280 0', orient: true },
+  { duration: 1200, ease: 'linear' },
+)
+```
+
+SVG coordinates are translations in DIPs. `orient: true` aligns artwork facing +X with the forward tangent. One shared progression drives native `x`, `y` and optional `rotate` tracks, with arc-length sampling, tweens, springs, delay, repeats, stagger, relative offsets and playback controls. Paths own those coordinates; use a `path` transition override to time them together. Parsing and sampling happen once; no JavaScript runs per frame. See the [path guide](https://jolt.rafaelaugusto.dev/guide/paths) for SVG commands, orientation and geometry limits.
+
+## Corners, borders and shadows
+
+```ts
+animate(card, { borderRadius: 40, borderWidth: 6 }, { duration: 800 })
+```
+
+Uniform circular borders work on iOS and Android. On iOS, configure one outer `boxShadow` and animate `shadowOpacity`, `shadowRadius` (half Core's CSS blur radius), `shadowOffsetX` and `shadowOffsetY`. On Android, animate `elevation` and `translationZ` for native shadows. Dimensions use DIPs; interruption, springs, repeats and selective stop work as usual. Border width animates the stroke while content uses the final layout. Clip paths, nonuniform geometry and Android radius changes with CSS shadows are rejected. Rebuild Android after upgrading. See the [guide and platform limits](https://jolt.rafaelaugusto.dev/guide/decorations).
+
+## Colors
+
+```ts
+animate(
+  card,
+  {
+    backgroundColor: '#263b27',
+    borderColor: ['#b6ee64', '#e5a1ff'],
+    color: '#f4caff',
+  },
+  { duration: 800 },
+)
+```
+
+Color strings and NativeScript `Color` objects work as targets or keyframes; `null` starts from the visible color. Colors interpolate in premultiplied OKLab and stay absolute with `relative: true`. Interruptions, repeats and `stop(card, ['backgroundColor'])` use the same API as transforms. Colors default to a 300 ms tween.
+
+`borderColor` requires the same starting color on every edge; widths and corner radii may differ. Text color supports Label and Button on iOS, and TextBase on Android. Explicit formatted-span colors stay intact. On iOS, text uses a native alpha-mask layer preserving UILabel's layout; emoji, attachments, text shadows and masks above four million pixels keep the final model color and resolve `false`. Edits, restyling and unloading cancel text playback and restore the current text. Gradients and images themselves are not interpolated. iOS background-color playback on an image background is skipped to preserve Core’s rasterized image; the final model color is applied. See the [color guide](https://jolt.rafaelaugusto.dev/guide/colors).
+
+Android includes a Java animation target; rebuild the native app after installing or upgrading Jolt.
 
 ## Transitions
 
-The third argument says how to get there. Without one, transforms move with a spring and `opacity` eases over 300ms. Keyframes tween.
+The third argument says how to get there. Without one, transforms move with a spring and opacity and colors ease over 300ms. Keyframes tween.
 
 ### Springs
 
@@ -94,6 +219,18 @@ animate(
 
 Tweens take 300ms and `easeOut` unless told otherwise. `ease` takes `linear`, `ease`, `easeIn`, `easeOut`, `easeInOut`, `circIn`, `circOut`, `circInOut`, `backIn`, `backOut`, `backInOut`, `anticipate`, a cubic bezier (`[0.2, 0, 0, 1]`) or any function from 0..1 to a value. With keyframes, pass one per segment. `times` places each keyframe between 0 and 1.
 
+With `easeTrack: true`, one `ease` runs over the whole track instead, and the value moves in straight lines between keyframes, the way React Native's `interpolate` places its output range on an eased value:
+
+```ts
+animate(
+  spark,
+  { y: [0, -30, -12, 0] },
+  { duration: 900, ease: 'easeOut', easeTrack: true, times: [0, 0.4, 0.7, 1] },
+)
+```
+
+An easing that overshoots, like `backOut`, extends the first or last segment, as `interpolate` does with `extrapolate: 'extend'`. `easeTrack` takes a single `ease` and applies to tweens only.
+
 Custom easing functions run once, when the animation starts, like springs do. They don't cost anything per frame.
 
 ### Per property
@@ -120,6 +257,31 @@ animate(
 
 `delay` is in milliseconds, and the view takes the first keyframe during it. `repeat` is how many more times to play, `Infinity` until stopped. `repeatType: 'reverse'` plays every other repeat backwards. Repeats play natively too.
 
+`repeatDelay` holds the end value for that many milliseconds before each repeat. The first play doesn't wait, and neither does the end of the last one. With `'reverse'` it waits at both ends:
+
+```ts
+animate(
+  z,
+  { y: [0, -40], opacity: [0, 1] },
+  { duration: 1200, repeat: Infinity, repeatDelay: 1800 },
+)
+```
+
+The wait is part of the native keyframes, so it costs no JavaScript while it plays. Stopping during the wait leaves the view at the held value.
+
+## Decay
+
+```ts
+import { decay } from '@rafaelaugusto/jolt'
+
+decay(card, { x: 600 }) // DIPs per second
+decay(card, { x: 600 }, { friction: 0.998, snap: [0, 320] })
+```
+
+Starts from the current translation and slows down exponentially. `friction` multiplies velocity per millisecond; smaller values stop sooner. `snap` projects the landing and springs directly to the closest stop, preserving the supplied velocity. Use `{ snap: { x: [0, 320], y: [-200, 0] } }` for independent axes.
+
+Shares interruption, `stop()` and awaitable completion with `animate()`. Both platforms use native keyframes with no JavaScript per frame. See the [decay guide](https://jolt.rafaelaugusto.dev/guide/decay).
+
 ## Presets
 
 ```ts
@@ -134,7 +296,9 @@ animate(spinner, 'spin', { repeat: Infinity })
 | Exit      | `fadeOut`, `fadeOutUp`, `fadeOutDown`, `fadeOutLeft`, `fadeOutRight`, `zoomOut`, `popOut`                |
 | Attention | `pulse`, `bounce`, `shake`, `wiggle`, `heartbeat`, `jelly`, `flash`, `tada`, `spin`                      |
 
-Directions follow animate.css: `fadeInUp` comes up from below, `fadeOutUp` leaves upwards. Every preset is plain keyframes and a transition, listed in [`src/presets.ts`](./src/presets.ts) and exported as `presets`.
+Directions follow animate.css: `fadeInUp` comes up from below, `fadeOutUp` leaves upwards. Each built-in preset is plain keyframes and a transition, listed in [`src/presets.ts`](./src/presets.ts) and exported as `presets`.
+
+Attention presets use `relative: true`: `shake` around `x: 40` returns to 40, `pulse` preserves the current scale, and `flash` returns to the current opacity. `spin` adds a full turn to the current rotation. Pass `{ relative: false }` to use their absolute keyframes instead. Enter and exit presets remain absolute.
 
 Options with timing only (`delay`, `repeat`, `stagger`) keep the preset's curves. Options with a curve (`duration`, `ease`, a spring) replace them:
 
@@ -144,6 +308,29 @@ animate(card, 'fadeInUp', { duration: 600 }) // a 600ms tween instead
 animate(card, 'fadeInUp', 'bouncy') // a bouncy spring instead
 ```
 
+Register your own keyframes and transition with `definePreset`:
+
+```ts
+import { animate, definePreset } from '@rafaelaugusto/jolt'
+
+declare module '@rafaelaugusto/jolt' {
+  interface Presets {
+    cardIn: true
+  }
+}
+
+definePreset('cardIn', {
+  keyframes: { opacity: [0, 1], y: [40, 0] },
+  transition: { type: 'spring', bounce: 0.2, opacity: { duration: 150 } },
+})
+
+animate(card, 'cardIn')
+```
+
+Register presets during app startup, before using them in `animate()` or `sequence()`. The `Presets` declaration adds the name to TypeScript; it does not register anything at runtime. Custom presets follow the same timing and curve overrides as built-ins, including per-property options and `stagger`.
+
+Registering a custom name again replaces its definition for future animations. Built-in names cannot be replaced through `definePreset`, and the exported `presets` object continues to contain only the built-ins.
+
 ## Several views
 
 Pass an array to animate them together, and `stagger` to start them one after another:
@@ -155,6 +342,15 @@ animate(tiles, 'popIn', { stagger: { each: 30, from: 'center' } })
 
 `from` is `'first'` (the default), `'last'`, `'center'` or an index.
 
+## List rows
+
+```ts
+const unlink = animateItems(listView, 'fadeInUp')
+animateItems(listView, 'fadeInUp', { once: true })
+```
+
+Each row of a `ListView` plays the entrance as the list hands it out. Rows are recycled while you scroll, so a row reused for another item starts the entrance again, or settles at the end values when that item was already shown and `once` is set. Items are tracked by object identity, or by index for primitives. The return value removes the effect and settles every row; unloading the list does the same. See the [list guide](https://jolt.rafaelaugusto.dev/guide/lists) for CollectionView and sectioned lists.
+
 ## Sequences
 
 ```ts
@@ -167,7 +363,20 @@ await sequence([
 
 Each step takes the same arguments as `animate`, or is a function that starts an animation. A step starts once the previous one looks done: a spring that's close to its target and staying there counts, even if it's still settling, so steps don't wait on the last pixel. The whole sequence finishes once every step has.
 
-Views in later steps take their first keyframe when the sequence starts, so the title above stays hidden until its turn instead of showing up and disappearing.
+Views in later steps take their first absolute keyframe when the sequence starts, so the title above stays hidden until its turn instead of showing up and disappearing. Relative steps and `null` keyframes wait until their step starts to read the current value.
+
+Use `at` to change the timing:
+
+```ts
+sequence([
+  [logo, 'popIn'],
+  [title, 'fadeInUp', { at: '-150' }],
+  [buttons, 'fadeIn', { at: '<' }],
+  [footer, 'fadeIn', { at: 900 }],
+])
+```
+
+A signed string offsets the previous arrival (`'-150'` before, `'+100'` after), `'<'` shares its activation, and a number selects absolute milliseconds. Each step's own delay still applies. Negative offsets use loaded tracks' spring/stagger arrival forecasts; absolute steps are independent. `stop()` cancels future launches and stops every started step. Position timers respect Android animator duration scale. JavaScript runs at step boundaries, so blocked JS can delay a launch. See [timelines](https://jolt.rafaelaugusto.dev/guide/sequences) for callback forecasts, interruption and loading behavior.
 
 ## Press
 
@@ -179,6 +388,166 @@ press(tile, { scale: 0.9, rotate: -4 }, 'bouncy')
 
 Animates to the given values while a finger is down, and back to where the view was once it lifts, or once the touch is cancelled by a scroll taking over. Views with `isEnabled` set to `false` don't react. It returns a function that removes the effect.
 
+## SF Symbols
+
+```ts
+import { symbolEffect } from '@rafaelaugusto/jolt'
+
+symbolEffect(bell, 'bounce')
+symbolEffect(favorite, { replace: 'sys://heart.fill' })
+```
+
+Takes a NativeScript `Image` with a `sys://` source, or a ref holding one. Supports `bounce`, `pulse`, `scale` and `variableColor`, with native playback, completion and cancellation. Replacement keeps the Image's source in sync. Scale holds until stopped; bounce, pulse and variable color can repeat with `{ repeat: true }`.
+
+Effects require iOS 17+. Earlier iOS versions and Reduce Motion skip decorative effects and replace icons immediately. Android calls resolve with `false` without changing the image. See [SF Symbol effects](https://jolt.rafaelaugusto.dev/guide/symbol-effects) for options and lifecycle behavior.
+
+## Shimmer
+
+```ts
+import { shimmer } from '@rafaelaugusto/jolt'
+
+const stopShimmer = shimmer(placeholder, { duration: 1500 })
+stopShimmer() // when the content is ready
+```
+
+A native gradient mask sweeps across the placeholder and its children. It follows layout changes, preserves existing masks and releases native resources while the view is unloaded, resuming on load. Reduce Motion keeps the placeholder static. iOS only for now; Android calls return a no-op cleanup function. See the [shimmer guide](https://jolt.rafaelaugusto.dev/guide/shimmer).
+
+## Liquid images
+
+```ts
+import { liquid } from '@rafaelaugusto/jolt'
+
+const flow = liquid(orb, { intensity: 0.9, duration: 7200 })
+flow.pause()
+flow.resume()
+flow.stop()
+```
+
+Parts of the image move relative to each other through a native repeating texture warp. Transparency and stretch are preserved; pause freezes the current shape and stop restores the original image. Reduce Motion keeps the image static. iOS only; Android returns an inert handle. See the [liquid image guide](https://jolt.rafaelaugusto.dev/guide/liquid).
+
+## Loaders
+
+```ts
+import { loader } from '@rafaelaugusto/jolt'
+
+const stopLoading = loader(slot, { style: 'dots', color: '#71717a', size: 48 })
+stopLoading() // when the content is ready
+```
+
+Choose `dots`, `bars` or `ring`. Each indicator uses one native animation replicated across a layer, fits inside its target and stays centered as the target resizes. Reduce Motion shows a static indicator. Unloading releases native resources; loading resumes until explicitly stopped. iOS only for now. See the [loaders guide](https://jolt.rafaelaugusto.dev/guide/loaders).
+
+## Circular reveal
+
+```ts
+import { reveal, conceal } from '@rafaelaugusto/jolt'
+
+await reveal(details, { from: { x: 40, y: 40 }, duration: 500 })
+await conceal(details, { to: { x: 40, y: 40 } })
+```
+
+A native circle reveals the view's content or contracts to hide it. Reversing continues from the circle on screen. Existing masks are restored when the effect ends; conceal finishes with `visibility = 'hidden'`, preserving layout space. Reduce Motion applies the final visibility immediately. iOS only for now. See the [circular reveal guide](https://jolt.rafaelaugusto.dev/guide/reveal) for cancellation and layout behavior.
+
+## Text
+
+```ts
+import { animateText } from '@rafaelaugusto/jolt'
+
+await animateText(title)
+await animateText(title, { by: 'word', stagger: 100 })
+```
+
+Reveal a Label letter by letter or a word at a time. On iOS, TextKit keeps the complete text layout, including wrapped lines, attributed styles and composed emoji, and Core Animation plays temporary glyph images. On Android, spans that only affect drawing fade and lift each piece under one native animator, keeping the TextView's text, line breaks and truncation. The original Label remains the single accessibility element. Stop restores the full text; Reduce Motion and Android's Remove animations skip the entrance. Rebuild Android apps after upgrading to include the native class. See the [text guide](https://jolt.rafaelaugusto.dev/guide/text) for options and limits.
+
+## Rolling numbers
+
+```ts
+import { rollTo } from '@rafaelaugusto/jolt'
+
+await rollTo(balance, 1249.9, { format: (value) => value.toFixed(2) })
+```
+
+Change a Label's number and only the digits that differ roll: each one slides out while its replacement slides in on a spring. Positions align on the units digit, so `99` becomes `100` by rolling two digits and adding one. The label holds the final text from the first frame; glyph layers on iOS and a native span animator on Android do the drawing, and tabular figures keep the width stable. Rebuild Android after upgrading. See the [rolling numbers guide](https://jolt.rafaelaugusto.dev/guide/rolling) for options and limits.
+
+## Haptics
+
+```ts
+animate(card, { y: 0 }, { type: 'spring', haptic: 'light' })
+animate(button, 'bounce', { haptic: { style: 'light', times: [0.6, 1] } })
+```
+
+Choose `light`, `medium` or `heavy`. By default, one impact fires when the animation visually arrives. Explicit points can mark each landing of a bounce. Delays and stagger follow the animation; interruptions, stopping and unloading cancel pending feedback. iOS only for now. See the [haptics guide](https://jolt.rafaelaugusto.dev/guide/haptics) for timing and device behavior.
+
+## Particles and confetti
+
+```ts
+import { confetti, particles } from '@rafaelaugusto/jolt'
+
+confetti(button, { count: 80, colors: ['#facc15', '#ef4444', '#3b82f6'] })
+const stopSnow = particles(scene, { source: 'top', angle: 90, velocity: 45 })
+stopSnow() // remove the emitter and its particles
+```
+
+Confetti bursts into the target's window and cleans itself up. `particles()` adds an emitter to the view for snow, sparks, bubbles or other effects. Both use Core Animation without JavaScript per frame, respect Reduce Motion and stop on unload. iOS only for now. See the [particles guide](https://jolt.rafaelaugusto.dev/guide/particles).
+
+## Scroll-linked animations
+
+```ts
+import { scrollLinked } from '@rafaelaugusto/jolt'
+
+const unlink = scrollLinked(
+  scrollView,
+  header,
+  { y: [0, -60], opacity: [1, 0] },
+  { range: [0, 120] },
+)
+```
+
+A paused native animation follows the ScrollView offset in DIPs, with linear interpolation and clamped progress. Scrolling backward restores earlier frames. Use `axis: 'x'` for horizontal scrolling; descending ranges reverse the mapping. `unlink()` freezes the current frame and removes the binding; unloading either view also cleans it up. Scroll events update progress through JavaScript, so this binding needs the main thread to remain available. See the [guide](https://jolt.rafaelaugusto.dev/guide/scroll-linked).
+
+## Follow the keyboard
+
+```ts
+import { followKeyboard } from '@rafaelaugusto/jolt'
+
+const release = followKeyboard(composer)
+```
+
+The view rises by exactly the distance the keyboard would cover it, with the keyboard's own duration and curve, and settles back when it hides. On iOS the keyboard notifications drive a `UIView` animation; on Android 11+ a native `WindowInsetsAnimation` callback moves the view on every frame, with and without `adjustResize`. The view's `translateY` is written so later animations start from the position on screen. Rebuild Android after upgrading. See the [guide](https://jolt.rafaelaugusto.dev/guide/keyboard).
+
+To react in other ways, `onKeyboard()` reports how much of the window the keyboard covers, with a transition that moves in step with it:
+
+```ts
+const off = onKeyboard(({ visible, transition }) => {
+  animate(header, { scale: visible ? 0.8 : 1 }, transition)
+})
+```
+
+`useKeyboard()` from `/vue` keeps a ref in sync until unmount.
+
+## Pause, play and scrub
+
+```ts
+const animation = animate(card, 'flipInY')
+animation.pause()
+animation.progress = 0.4
+animation.play()
+```
+
+`animate()` and `decay()` return a `PlaybackAnimation` with `pause()`, `play()`, `progress`, `paused` and `duration`. Progress runs from 0 to 1 across delays, repeats and stagger. It preserves the paused/playing state; a paused endpoint can scrub backward. Other animations on the same view keep moving. Infinite loops support pause/play but reject progress. Completed and stopped handles remain terminal. Sequence and effect handles keep their existing controls. See [playback](https://jolt.rafaelaugusto.dev/guide/playback) for lifecycle, haptics and gesture examples.
+
+## Time scale and reduced motion
+
+```ts
+import { configure } from '@rafaelaugusto/jolt'
+
+configure({ timeScale: 0.2 }) // everything five times slower
+configure({ reducedMotion: 'always' }) // transforms jump, opacity still fades
+```
+
+Tuning a spring at full speed is guesswork. The scale applies to every engine animation started after the call, on iOS and Android alike: durations, delays, stagger, sequence positions and spring time stretch together, keyframes stay dense, and an interruption still picks up the value and velocity on screen. Native loops such as shimmer and loaders keep their own timing.
+
+With Reduce Motion on iOS or Remove animations on Android, translations, scale, rotation, paths, decorations and decay jump to their end values while opacity and colors still animate. `'user'` is the default; `'always'` and `'never'` override the platform for the whole library. `reducedMotion()` reads the result, `onReducedMotion(callback)` watches it, and `useReducedMotion()` from `/vue` keeps a ref in sync. See the [guide](https://jolt.rafaelaugusto.dev/guide/configure).
+
 ## Interrupting and stopping
 
 Starting an animation on a property that's already animating takes it over: the new one starts from the value on screen, with the same velocity, so a card can change its mind halfway without a jump. Other properties of the previous animation keep going.
@@ -190,38 +559,79 @@ const animation = animate(card, { x: 300 })
 animation.stop() // the card stays where it is
 
 stop(card) // stops everything running on the card
+stop(card, ['x', 'scale']) // stops translation on x and both scale axes
+```
+
+Selected properties stay at their current values; the others keep animating. `scaleX` and `scaleY` can also be stopped separately. Pass an empty array to stop nothing, or omit it to stop everything. This works with arrays of targets too.
+
+If part of an animation is stopped, its `finished` promise resolves with `false` once its remaining properties finish.
+
+`set()` places a view without animating it, and stops whatever animates those properties:
+
+```ts
+set(logo, { opacity: 1, scale: 1, y: 0 })
 ```
 
+It takes one value per property, the same properties as `animate()`. The next animation starts from there. See [setting values](https://jolt.rafaelaugusto.dev/guide/interrupting#setting-values-without-animating).
+
 ## How it works
 
-When an animation starts, Jolt resolves where each property starts from (the value on screen, or the keyframes you gave), and computes the whole curve: easing, keyframes, spring physics. It samples the curve 60 times per second of motion, and keeps keyframe times exact. Linear segments aren't sampled at all.
+When an animation starts, Jolt resolves where each property starts from (the value on screen, or the keyframes you gave), and computes the whole curve: easing, keyframes, spring physics and exponential decay. It samples the curve 60 times per second of motion, and keeps keyframe times exact. Linear numeric segments use only their endpoints. Long tween segments and free decays cap sampling at 6,001 keyframes. Color tracks add intermediate OKLab samples even with linear timing.
 
 The samples go to the platform in one go:
 
 - **iOS**: a `CAKeyframeAnimation` per property on the view's layer (`opacity`, `transform.translation.x`, `transform.scale.y`, `transform.rotation.z`...). Core Animation composes them, so `x` and `scale` can belong to different animations, and plays them in the render server.
 - **Android**: an `ObjectAnimator` per property with `Keyframe`s and a linear interpolator, on the view's `alpha`, `translationX`, `scaleY`, `rotation`...
 
+Solid [colors](#colors) use CGColor keyframes on iOS and int keyframes through a native Java target on Android. iOS text uses a UILabel alpha mask so glyph positions stay fixed while the color layer animates.
+
 Before playing, the final values are set on the NativeScript view, like `view.animate()` does, so `view.translateX` already holds the target while the animation runs. Stopping writes back the values on screen.
 
-Each running property remembers its curve and start time, so Jolt knows the value and velocity of any property at any moment without asking the platform. That's what lets an interruption pick up the motion where it was. On Android, where an animator starts on the next frame, it reads the value on screen instead.
+Native playback does not isolate Android View animations from a blocked UI thread. Main-runtime JavaScript shares that thread, and `withLayer()` only caches drawing. Move suitable CPU work to a Worker and keep view updates small. See the [busy JavaScript guide](https://jolt.rafaelaugusto.dev/guide/android-performance) and [Android diagnostic](./benchmarks/android-busy.md).
+
+On Android, opacity animations temporarily cache hardware-accelerated containers with children in a hardware layer. Jolt waits for the fade to start and restores the layer on completion, stop, replacement or unload. Existing app-configured layers are preserved; empty, unmeasured and larger-than-screen containers are skipped. See the [fade-layer benchmark](./benchmarks/android-fade.md) for measurement and memory tradeoffs.
+
+Each running property remembers its curve and start time. On Android, interruptions read the displayed value and the animator's current play time, so inherited velocity follows the system's animator duration scale. Early spring arrivals use a native timing marker with completion callbacks only; other sequences advance on native completion. Delays, repeats and disabled animations follow the same platform clock, without JavaScript running per frame.
 
 ## Not there yet
 
-- Only transforms and opacity. Colors, size and layout changes aren't animated yet.
-- No gestures: dragging something and letting it fly with its velocity is next.
-- No layout or shared element transitions.
+- `animate()` supports transforms, opacity, colors, uniform corners and borders, and platform shadows. Size and layout changes ([#21](https://github.com/rafaelaugustos/jolt/issues/21)) aren't animated yet.
+- Gesture composition and nested-scroll handoff remain separate work ([#51](https://github.com/rafaelaugustos/jolt/issues/51)).
+- No layout or shared element transitions ([#21](https://github.com/rafaelaugustos/jolt/issues/21), [#24](https://github.com/rafaelaugustos/jolt/issues/24)).
 
 ## API
 
-**Animating**: `animate(target, keyframes | preset, transition?)`, `stop(target)`, `sequence(steps)`, `press(target, pressed?, transition?)`.
+**Animating**: `animate(target, keyframes | preset, transition?)`, `decay(target, velocity, options?)`, `stop(target, properties?)`, `sequence(steps)`, `press(target, pressed?, transition?)`, `drag(target, options?)`, `symbolEffect(image, effect, options?)`, `shimmer(target, options?)`, `liquid(image, options?)`, `loader(target, options?)`, `reveal(target, options?)`, `conceal(target, options?)`, `confetti(target, options?)`, `particles(target, options?)`.
+
+`animateLayout(container, change?, options?)` animates the next layout of direct children; `motionScope().animateLayout()` owns it through component lifecycle. Cancellation settles temporary offsets into the final layout.
+
+`interactionSurface(target)` opts a view/subtree into native touch geometry during animation; returns `{ disposed, dispose() }`. Register before playback; rebuild iOS after upgrading.
 
-**Animations** returned by them: `await`, `finished`, `stop()`.
+`drag()` returns a controller with `position`, `dragging`, `settling`, `cancel()`, `pause()`, `play()` and `dispose()`. `motionScope().drag()` owns it through component lifecycle.
 
-**Helpers**: `presets`, `springs`, `cubicBezier`, plus the types (`Keyframes`, `Transition`, `Spring`, `Tween`, `PresetName`, `SpringName`, `Easing`, `Animation`, `Target`...).
+`liquid()` returns a `LiquidEffect` with `pause()`, `resume()` and `stop()`.
+
+**Animations** from `animate()`, `decay()`, `sequence()`, `symbolEffect()`, `reveal()` and `conceal()`: `await`, `finished`, `stop()`. `press()`, `shimmer()`, `loader()`, `confetti()` and `particles()` return cleanup functions.
+
+**Helpers**: `definePreset`, `presets`, `springs`, `cubicBezier`, plus the types (`Keyframes`, `Transition`, `Spring`, `Tween`, `Preset`, `Presets`, `PresetName`, `SpringName`, `Easing`, `Animation`, `Target`...).
 
 ## Demo
 
-[`demo/`](./demo) is a NativeScript-Vue app with every preset, the three springs on a ball you can interrupt, stagger, press effects, loops and a sequence on launch.
+[`demo/`](./demo) opens an interactive assistant on iOS and Android: a fan of document tools, a voice screen with letter-by-letter text, and a staged conversation with document previews and a rolling countdown, with the screens cross-fading through the Vue entry. Open **Help → Watch demo** to replay the flow. The orb is an animated illustration; speech, documents and audio are sample data.
+
+|                                                                             Assistant                                                                              |                                                                      Presets                                                                       |                                                                                       Springs                                                                                       |                                                                        Stagger                                                                        |
+| :----------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------: |
+| <img src="https://raw.githubusercontent.com/rafaelaugustos/jolt/main/.github/assets/demo-assistant.gif" width="200" alt="The assistant replaying its flow on iOS"> | <img src="https://raw.githubusercontent.com/rafaelaugustos/jolt/main/.github/assets/demo-presets.gif" width="200" alt="fadeInUp, popIn and shake"> | <img src="https://raw.githubusercontent.com/rafaelaugustos/jolt/main/.github/assets/demo-springs.gif" width="200" alt="smooth, snappy and bouncy springs on an interruptible ball"> | <img src="https://raw.githubusercontent.com/rafaelaugustos/jolt/main/.github/assets/demo-stagger.gif" width="200" alt="Rows entering with a stagger"> |
+
+|                                                                            Sequences                                                                            |                                                                  Press (Android)                                                                   |                                                                   Rolling numbers                                                                   |                                                                     Text (Android)                                                                      |
+| :-------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------: |
+| <img src="https://raw.githubusercontent.com/rafaelaugustos/jolt/main/.github/assets/demo-sequences.gif" width="200" alt="Overlapping steps and steps in order"> | <img src="https://raw.githubusercontent.com/rafaelaugustos/jolt/main/.github/assets/demo-press-android.gif" width="200" alt="Three press effects"> | <img src="https://raw.githubusercontent.com/rafaelaugustos/jolt/main/.github/assets/demo-rolling.gif" width="200" alt="Digits rolling up and down"> | <img src="https://raw.githubusercontent.com/rafaelaugustos/jolt/main/.github/assets/demo-text-android.gif" width="200" alt="Letter and word entrances"> |
+
+|                                                                            Layout (iOS)                                                                             |                                                                                  Drag and snap (iOS)                                                                                  |                                                                                    Image effects (iOS)                                                                                     |                                                                               Photo zoom (iOS)                                                                                |
+| :-----------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
+| <img src="https://raw.githubusercontent.com/rafaelaugustos/jolt/main/.github/assets/demo-layout-ios.gif" width="200" alt="Native cards insert, reorder and expand"> | <img src="https://raw.githubusercontent.com/rafaelaugustos/jolt/main/.github/assets/demo-drag-ios.gif" width="200" alt="A card and panel follow real drags and settle within bounds"> | <img src="https://raw.githubusercontent.com/rafaelaugustos/jolt/main/.github/assets/demo-image-effects-ios.gif" width="200" alt="Ripple, touch distortion and dissolve on a raster image"> | <img src="https://raw.githubusercontent.com/rafaelaugustos/jolt/main/.github/assets/demo-photo-zoom-ios.gif" width="200" alt="A photo responds to pinch, pan and double tap"> |
+
+The animation playground opens with `--playground` on iOS and `--es playground true` on Android, with presets, interruptible springs, decay, text, press effects, list rows, the keyboard composer and the native iOS helpers. See the [demo guide](./docs/guide/demo.md) for preview arguments and implementation notes. Every visual feature guide in the [documentation](https://jolt.rafaelaugusto.dev) includes a recording of the real native demo, in English and Portuguese.
 
 With the [NativeScript CLI](https://docs.nativescript.org/setup/) installed:
 
@@ -240,10 +650,16 @@ ns run ios         # or: ns run android
 npm test           # unit tests
 npm run typecheck  # including the iOS and Android drivers, against the platform typings
 npm run build
+npm run docs:check-media
+npm run docs:build
 ```
 
+Visual changes require reviewed recordings before completion or release. See [Contributing](./CONTRIBUTING.md).
+
 The tests run the engine against a fake platform driver ([`test/helpers.ts`](./test/helpers.ts)) with its own clock: it records the keyframes it would play and ends them when the clock passes their end.
 
+For on-device measurements, see the [iOS animation startup benchmark](./benchmarks/README.md).
+
 ### Releasing
 
 1. Bump `version` in `package.json` (`npm version <version> --no-git-tag-version`) and move the changes under it in `CHANGELOG.md`.
@@ -254,4 +670,4 @@ Publishing authenticates with the `NPM_TOKEN` secret, or with [trusted publishin
 
 ## License
 
-[MIT](./LICENSE)
+[MIT](./LICENSE). Maintained by Rafael Augusto and [Cortex Labs](https://getcortexlabs.com/).