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

package/dist/symbol-effect.js

@@ -0,0 +1,186 @@
+import { Image, ImageSource, isIOS } from '@nativescript/core';
+import { toView } from './animate.js';
+const running = new WeakMap();
+const names = ['bounce', 'pulse', 'scale', 'variableColor'];
+/**
+ * Plays an iOS 17+ SF Symbol effect on a NativeScript Image.
+ * Scale holds until stopped; replacements also update the Image's src.
+ *
+ * ```ts
+ * symbolEffect(icon, 'bounce')
+ * symbolEffect(icon, { replace: 'sys://heart.fill' })
+ * ```
+ */
+export function symbolEffect(target, effect, options = {}) {
+    const view = toView(target);
+    if (!(view instanceof Image))
+        throw new TypeError('symbolEffect expects an Image.');
+    if (typeof effect === 'string'
+        ? !names.includes(effect)
+        : !effect ||
+            typeof effect.replace !== 'string' ||
+            !/^sys:\/\/[^\s/]+$/.test(effect.replace)) {
+        throw new TypeError('Expected a symbol effect name or { replace: "sys://name" }.');
+    }
+    const speed = options.speed ?? 1;
+    if (!Number.isFinite(speed) || speed <= 0)
+        throw new RangeError('Symbol effect speed must be a positive finite number.');
+    if (options.repeat !== undefined && typeof options.repeat !== 'boolean')
+        throw new TypeError('Symbol effect repeat must be a boolean.');
+    if (options.repeat && (typeof effect !== 'string' || effect === 'scale'))
+        throw new TypeError('Only bounce, pulse and variableColor can repeat.');
+    return new SymbolAnimation(view, effect, speed, options.repeat ?? false);
+}
+class SymbolAnimation {
+    view;
+    effect;
+    speed;
+    repeat;
+    finished;
+    resolve;
+    settled = false;
+    started = false;
+    changingSource = false;
+    waitingForLoad;
+    native;
+    nativeEffect;
+    replacement;
+    constructor(view, effect, speed, repeat) {
+        this.view = view;
+        this.effect = effect;
+        this.speed = speed;
+        this.repeat = repeat;
+        this.finished = new Promise((resolve) => (this.resolve = resolve));
+        this.waitingForLoad = !view.isLoaded;
+        running.get(view)?.stop();
+        running.set(view, this);
+        view.on('unloaded', this.stop);
+        view.on('srcChange', this.sourceChanged);
+        view.on('imageSourceChange', this.imageChanged);
+        view.on('loaded', this.loaded);
+        view.on('isLoadingChange', this.start);
+        this.start();
+    }
+    then(onfulfilled, onrejected) {
+        return this.finished.then(onfulfilled, onrejected);
+    }
+    stop = () => this.end(false, true);
+    sourceChanged = () => {
+        if (!this.changingSource)
+            this.stop();
+    };
+    imageChanged = () => {
+        if (this.changingSource)
+            return;
+        if (this.started)
+            this.stop();
+        else
+            this.start();
+    };
+    loaded = () => {
+        this.waitingForLoad = false;
+        this.start();
+    };
+    start = () => {
+        if (this.settled || this.started)
+            return;
+        if (!isIOS)
+            return this.end(false);
+        const { view, effect } = this;
+        // isLoaded becomes true before NativeScript resumes native property updates.
+        // Wait for the loaded event so intermediate image resets don't start playback.
+        if (this.waitingForLoad ||
+            !view.isLoaded ||
+            !view.nativeViewProtected ||
+            view.isLoading)
+            return;
+        this.started = true;
+        const native = (this.native = view.nativeViewProtected);
+        const reducedMotion = UIAccessibilityIsReduceMotionEnabled();
+        if (typeof effect !== 'string') {
+            // Resolve first so a symbol absent on this OS doesn't clear the current image.
+            if (!ImageSource.fromSystemImageSync(effect.replace.slice(6))?.ios)
+                return this.end(false);
+            const previous = native.image;
+            const loadMode = view.loadMode;
+            this.changingSource = true;
+            try {
+                // Let NativeScript update its source, tint, configuration and pending loads.
+                // Both assignments happen in this turn, before UIKit draws the next frame.
+                view.loadMode = 'sync';
+                view.src = effect.replace;
+            }
+            finally {
+                view.loadMode = loadMode;
+                this.changingSource = false;
+            }
+            // A source-change listener may have started another effect or changed the src.
+            if (this.settled)
+                return;
+            if (view.src !== effect.replace)
+                return this.end(false);
+            const image = native.image;
+            if (!image)
+                return this.end(false);
+            if (reducedMotion ||
+                !previous?.symbolImage ||
+                !native.respondsToSelector('setSymbolImage:withContentTransition:options:completion:'))
+                return this.end(true);
+            this.replacement = image;
+            native.image = previous;
+            native.setSymbolImageWithContentTransitionOptionsCompletion(image, NSSymbolReplaceContentTransition.transition(), this.options(), this.completed);
+            return;
+        }
+        if (reducedMotion ||
+            !native.image?.symbolImage ||
+            !native.respondsToSelector('addSymbolEffect:options:animated:completion:'))
+            return this.end(false);
+        const factories = {
+            bounce: NSSymbolBounceEffect,
+            pulse: NSSymbolPulseEffect,
+            scale: NSSymbolScaleEffect,
+            variableColor: NSSymbolVariableColorEffect,
+        };
+        this.nativeEffect = factories[effect].effect();
+        native.addSymbolEffectOptionsAnimatedCompletion(this.nativeEffect, this.options(), true, this.completed);
+    };
+    options() {
+        const options = this.repeat
+            ? NSSymbolEffectOptions.optionsWithRepeating()
+            : NSSymbolEffectOptions.optionsWithNonRepeating();
+        return options.optionsWithSpeed(this.speed);
+    }
+    completed = (context) => {
+        // Scale's entrance can complete while the effect is still holding its state.
+        if (context.finished && (this.effect === 'scale' || this.repeat))
+            return;
+        this.end(context.finished);
+    };
+    end(finished, remove = false) {
+        if (this.settled)
+            return;
+        this.settled = true;
+        const { view, native, nativeEffect, replacement } = this;
+        view.off('loaded', this.loaded);
+        view.off('isLoadingChange', this.start);
+        view.off('unloaded', this.stop);
+        view.off('srcChange', this.sourceChanged);
+        view.off('imageSourceChange', this.imageChanged);
+        if (running.get(view) === this)
+            running.delete(view);
+        if (remove && native) {
+            if (nativeEffect)
+                native.removeSymbolEffectOfType(nativeEffect);
+            // Content transitions have no removal API. Keep the destination icon.
+            if (replacement && native.image === replacement) {
+                native.image = null;
+                native.image = replacement;
+            }
+        }
+        this.native = undefined;
+        this.nativeEffect = undefined;
+        this.replacement = undefined;
+        this.resolve(finished);
+    }
+}
+//# sourceMappingURL=symbol-effect.js.map

package/dist/symbol-effect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-effect.js","sourceRoot":"","sources":["../src/symbol-effect.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { View } from '@nativescript/core';
+import type { Haptic } from './haptics.js';
 import type { SpringName, Transition } from './transition.js';
 /** A value to animate to, or keyframes. `null` stands for the value the view has when the animation starts. */
 export type KeyframeValue = number | readonly (number | null)[];
@@ -32,7 +33,11 @@ export interface Stagger {
 export type AnimateOptions = Transition & {
     [K in keyof Keyframes]?: Transition | SpringName;
 } & {
+    /** Offset translations/rotations and multiply scale/opacity by their values at the start. */
+    relative?: boolean;
     /** With several targets, delays each one by this much more than the previous. */
     stagger?: number | Stagger;
+    /** iOS impact feedback at arrival, or at explicit points in a finite animation. */
+    haptic?: Haptic;
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE7D,+GAA+G;AAC/G,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAA;AAE/D,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,qCAAqC;IACrC,CAAC,CAAC,EAAE,aAAa,CAAA;IACjB,qCAAqC;IACrC,CAAC,CAAC,EAAE,aAAa,CAAA;IACjB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,eAAe;IACf,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,OAAO,CAAC,EAAE,aAAa,CAAA;CACxB;AAED,+FAA+F;AAC/F,MAAM,MAAM,MAAM,GAChB,IAAI,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAA;CAAE,CAAA;AAEzE,MAAM,WAAW,OAAO;IACtB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;CAC5C;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG;KACvC,CAAC,IAAI,MAAM,SAAS,CAAC,CAAC,EAAE,UAAU,GAAG,UAAU;CACjD,GAAG;IACF,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAC3B,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE7D,+GAA+G;AAC/G,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAA;AAE/D,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,qCAAqC;IACrC,CAAC,CAAC,EAAE,aAAa,CAAA;IACjB,qCAAqC;IACrC,CAAC,CAAC,EAAE,aAAa,CAAA;IACjB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,eAAe;IACf,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,OAAO,CAAC,EAAE,aAAa,CAAA;CACxB;AAED,+FAA+F;AAC/F,MAAM,MAAM,MAAM,GAChB,IAAI,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAA;CAAE,CAAA;AAEzE,MAAM,WAAW,OAAO;IACtB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;CAC5C;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG;KACvC,CAAC,IAAI,MAAM,SAAS,CAAC,CAAC,EAAE,UAAU,GAAG,UAAU;CACjD,GAAG;IACF,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IAC1B,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafaelaugusto/jolt",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.2",
   "description": "Native animations for NativeScript: presets, springs, keyframes and stagger in one call.",
   "keywords": [
     "nativescript",
@@ -39,10 +39,14 @@
     "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
     "dev": "tsc -p tsconfig.build.json --watch",
     "typecheck": "tsc --noEmit",
+    "benchmark:typecheck": "tsc -p benchmarks/tsconfig.json",
     "test": "vitest run",
     "test:watch": "vitest",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
     "prepack": "npm run build"
   },
   "peerDependencies": {
@@ -54,6 +58,7 @@
     "@nativescript/types-ios": "^9.1.3",
     "prettier": "^3.9.10",
     "typescript": "^7.0.2",
+    "vitepress": "^1.6.4",
     "vitest": "^5.0.4"
   },
   "engines": {

package/src/animate.ts

@@ -7,7 +7,8 @@ import {
   type Animation,
   type Plan,
 } from './engine.js'
-import { presets, type PresetName } from './presets.js'
+import { getPreset, type PresetName } from './presets.js'
+import { resolveHaptic, type Haptic } from './haptics.js'
 import { isProperty, type Property } from './properties.js'
 import {
   hasCurve,
@@ -29,6 +30,8 @@ interface Options {
   base: Transition
   overrides: Partial<Record<keyof Keyframes, Transition>>
   stagger: number | Stagger | undefined
+  relative: boolean | undefined
+  haptic: Haptic | undefined
 }
 
 /**
@@ -46,10 +49,18 @@ export function animate(
   animation: Keyframes | PresetName,
   options?: AnimateOptions | SpringName,
 ): Animation {
-  const { keyframes, base, overrides, stagger } = prepare(animation, options)
+  const { keyframes, base, overrides, stagger, relative, haptic } = prepare(
+    animation,
+    options,
+  )
+  const feedback = resolveHaptic(haptic)
 
   if (!isList(target)) {
-    return new ViewAnimation(toView(target), plan(keyframes, base, overrides, 0))
+    return new ViewAnimation(
+      toView(target),
+      plan(keyframes, base, overrides, 0, relative),
+      feedback,
+    )
   }
 
   const views = target.map(toView)
@@ -58,15 +69,28 @@ export function animate(
       (view, index) =>
         new ViewAnimation(
           view,
-          plan(keyframes, base, overrides, staggerDelay(stagger, index, views.length)),
+          plan(
+            keyframes,
+            base,
+            overrides,
+            staggerDelay(stagger, index, views.length),
+            relative,
+          ),
+          feedback,
         ),
     ),
   )
 }
 
-/** Stops every animation running on the view, leaving it where it is. */
-export function stop(target: Target | readonly Target[]) {
-  for (const view of toViews(target)) stopView(view)
+/** Stops all or selected properties at their current values. `scale` stops both axes. */
+export function stop(
+  target: Target | readonly Target[],
+  properties?: readonly (keyof Keyframes)[],
+) {
+  const expanded = properties?.flatMap<Property>((property) =>
+    property === 'scale' ? ['scaleX', 'scaleY'] : [property],
+  )
+  for (const view of toViews(target)) stopView(view, expanded)
 }
 
 /** Plays several animations as one: finished once they all are, and stopped together. */
@@ -107,35 +131,53 @@ function prepare(
   const user = normalize(options)
   if (typeof animation !== 'string') return { keyframes: animation, ...user }
 
-  const preset = presets[animation]
-  if (!preset) throw new Error(`Unknown preset "${animation}".`)
+  const preset = getPreset(animation)
   const own = normalize(preset.transition)
   return {
-    keyframes: preset.keyframes as Keyframes,
+    keyframes: preset.keyframes,
     base: mergeTransitions(own.base, user.base),
     overrides: hasCurve(user.base)
       ? user.overrides
       : { ...own.overrides, ...user.overrides },
-    stagger: user.stagger,
+    stagger: user.stagger ?? own.stagger,
+    relative: user.relative ?? own.relative,
+    haptic: user.haptic ?? own.haptic,
   }
 }
 
 function normalize(options: AnimateOptions | SpringName | undefined): Options {
-  if (options === undefined) return { base: {}, overrides: {}, stagger: undefined }
+  if (options === undefined)
+    return {
+      base: {},
+      overrides: {},
+      stagger: undefined,
+      relative: undefined,
+      haptic: undefined,
+    }
   if (typeof options === 'string')
-    return { base: spring(options), overrides: {}, stagger: undefined }
+    return {
+      base: spring(options),
+      overrides: {},
+      stagger: undefined,
+      relative: undefined,
+      haptic: undefined,
+    }
 
   const base: Record<string, unknown> = {}
   const overrides: Options['overrides'] = {}
   let stagger: Options['stagger']
+  let relative: Options['relative']
+  let haptic: Options['haptic']
   for (const [key, value] of Object.entries(options)) {
     if (value === undefined) continue
     if (key === 'stagger') stagger = value as Options['stagger']
+    else if (key === 'relative') relative = value as Options['relative']
+    else if (key === 'haptic') haptic = value as Options['haptic']
     else if (key === 'scale' || isProperty(key)) {
       overrides[key] = typeof value === 'string' ? spring(value as SpringName) : value
     } else base[key] = value
   }
-  return { base, overrides, stagger }
+  return { base, overrides, stagger, relative, haptic }
 }
 
 function plan(
@@ -143,6 +185,7 @@ function plan(
   base: Transition,
   overrides: Options['overrides'],
   offset: number,
+  relative = false,
 ): Plan[] {
   return expand(keyframes).map(([property, frames]) => {
     const override =
@@ -153,17 +196,19 @@ function plan(
       frames.length,
     )
     transition.delay += offset
-    return { property, keyframes: frames, transition }
+    return { property, keyframes: frames, transition, relative }
   })
 }
 
 /** Each property the animation touches, with the value it starts from when it sets one. */
-export function startingValues(animation: Keyframes | PresetName) {
-  const keyframes =
-    typeof animation === 'string' ? presets[animation]?.keyframes : animation
+export function startingValues(
+  animation: Keyframes | PresetName,
+  options?: AnimateOptions | SpringName,
+) {
+  const { keyframes, relative } = prepare(animation, options)
   if (!keyframes) throw new Error(`Unknown preset "${animation}".`)
   return new Map(
-    expand(keyframes as Keyframes).map(([property, [first]]) => [property, first!]),
+    expand(keyframes).map(([property, [first]]) => [property, relative ? null : first!]),
   )
 }
 

package/src/driver/ios.ts

@@ -5,6 +5,7 @@ import { after, type Driver } from './index.js'
 interface Handle {
   layers: CALayer[]
   key: string
+  onStop?: () => void
 }
 
 const keyPaths: Record<Property, string> = {
@@ -51,11 +52,23 @@ export function createIOSDriver(): Driver {
       const layers = layersOf(view)
       const key = `jolt:${track.property}`
       const rotation = track.property.startsWith('rotate')
+      const infinite = track.repeat === Infinity
       if (track.property === 'rotateX' || track.property === 'rotateY') {
         ensurePerspective(view, layers)
       }
 
       const animation = CAKeyframeAnimation.animationWithKeyPath(keyPaths[track.property])
+      // iOS 15+. The app must opt in through CADisableMinimumFrameDurationOnPhone.
+      if (animation.respondsToSelector('setPreferredFrameRateRange:')) {
+        const nativeView = view.nativeViewProtected as UIView
+        const screen = nativeView.window?.screen ?? UIScreen.mainScreen
+        const maximum = Math.min(120, screen.maximumFramesPerSecond)
+        animation.preferredFrameRateRange = CAFrameRateRangeMake(
+          Math.min(80, maximum),
+          maximum,
+          maximum,
+        )
+      }
       animation.values = NSArray.arrayWithArray(
         track.values.map((value) => (rotation ? radians(value) : value)),
       )
@@ -63,22 +76,29 @@ export function createIOSDriver(): Driver {
       animation.duration = Math.max(track.duration, 1) / 1000
       animation.beginTime = (startedAt + track.delay) / 1000
       animation.fillMode = kCAFillModeBackwards
+      // Keep infinite loops when iOS removes animations on backgrounding.
+      // They are removed explicitly when stopped or replaced.
+      animation.removedOnCompletion = !infinite
       if (track.repeat > 0) {
         animation.autoreverses = track.reverse
         animation.repeatCount = track.reverse ? (track.repeat + 1) / 2 : track.repeat + 1
       }
 
       CATransaction.begin()
-      CATransaction.setCompletionBlock(onEnd)
+      // iOS completes the transaction on backgrounding even if the loop is retained.
+      if (!infinite) CATransaction.setCompletionBlock(onEnd)
       for (const layer of layers) layer.addAnimationForKey(animation, key)
       CATransaction.commit()
 
-      return { layers, key }
+      return { layers, key, onStop: infinite ? onEnd : undefined }
     },
 
     stop(_view, handle) {
-      const { layers, key } = handle as Handle
+      const playing = handle as Handle
+      const { layers, key, onStop } = playing
+      playing.onStop = undefined
       for (const layer of layers) layer.removeAnimationForKey(key)
+      onStop?.()
     },
 
     presented: () => undefined,

package/src/engine.ts

@@ -1,5 +1,6 @@
 import type { View } from '@nativescript/core'
 import { getDriver } from './driver/index.js'
+import { playHaptics, type HapticOptions } from './haptics.js'
 import { readValue, writeValue, type Property } from './properties.js'
 import { createTrack, type Track } from './track.js'
 import type { ResolvedTransition } from './transition.js'
@@ -7,11 +8,11 @@ import type { ResolvedTransition } from './transition.js'
 export interface Animation extends PromiseLike<boolean> {
   /**
    * Resolves with `true` once the animation played to the end, or with `false`
-   * if it was stopped or another animation took over one of its properties.
+   * if it was stopped, superseded or skipped.
    * Never rejects.
    */
   readonly finished: Promise<boolean>
-  /** Stops where it is. The view keeps the values it had at that moment. */
+  /** Stops playback. Property animations keep their current values; symbol effects are removed. */
   stop(): void
 }
 
@@ -20,6 +21,7 @@ export interface Plan {
   /** `null` stands for the value the property has when the animation starts. */
   keyframes: readonly (number | null)[]
   transition: ResolvedTransition
+  relative?: boolean
 }
 
 interface Entry {
@@ -55,10 +57,12 @@ export class ViewAnimation implements Animation {
   private cancelWait: (() => void) | undefined
   private arrive!: () => void
   private cancelArrival: (() => void) | undefined
+  private haptics: ReturnType<typeof playHaptics>
 
   constructor(
     readonly view: View,
     plans: readonly Plan[],
+    private readonly haptic?: HapticOptions,
   ) {
     this.finished = new Promise((resolve) => (this.resolve = resolve))
     setArrival(this, new Promise<void>((resolve) => (this.arrive = resolve)))
@@ -76,6 +80,7 @@ export class ViewAnimation implements Animation {
   stop() {
     if (this.settled) return
     this.cancelWait?.()
+    this.haptics?.cancel()
     const now = getDriver().now()
     for (const entry of this.entries) {
       if (!entry.done) release(entry, now, true)
@@ -85,7 +90,10 @@ export class ViewAnimation implements Animation {
   }
 
   ended(finished: boolean) {
-    if (!finished) this.complete = false
+    if (!finished) {
+      this.complete = false
+      this.haptics?.cancel()
+    }
     if (--this.pending === 0) this.settle()
   }
 
@@ -94,7 +102,7 @@ export class ViewAnimation implements Animation {
     const now = driver.now()
     const entries = entriesOf(this.view)
 
-    const tracks = plans.map(({ property, keyframes, transition }) => {
+    const tracks = plans.map(({ property, keyframes, transition, relative }) => {
       const previous = entries.get(property)
       let current: number
       let velocity = 0
@@ -108,7 +116,13 @@ export class ViewAnimation implements Animation {
       }
       return createTrack(
         property,
-        keyframes.map((value) => value ?? current),
+        keyframes.map((value) => {
+          if (value === null) return current
+          if (!relative) return value
+          return property === 'opacity' || property.startsWith('scale')
+            ? current * value
+            : current + value
+        }),
         transition,
         velocity,
       )
@@ -130,6 +144,8 @@ export class ViewAnimation implements Animation {
       this.pending++
     }
 
+    this.haptics = playHaptics(this.view, tracks, this.haptic, driver, now)
+
     for (const entry of this.entries) {
       entry.handle = driver.play(this.view, entry.track, now, () => {
         if (entry.done) return
@@ -147,7 +163,8 @@ export class ViewAnimation implements Animation {
   }
 
   private waitForLoad(plans: readonly Plan[]) {
-    for (const { property, keyframes } of plans) {
+    for (const { property, keyframes, relative } of plans) {
+      if (relative) continue
       const first = keyframes[0]
       if (first !== null && first !== undefined) writeValue(this.view, property, first)
     }
@@ -166,6 +183,9 @@ export class ViewAnimation implements Animation {
     if (this.settled) return
     this.settled = true
     this.cancelArrival?.()
+    if (this.complete) this.haptics?.finish()
+    else this.haptics?.cancel()
+    this.haptics = undefined
     this.arrive()
     this.resolve(this.complete)
   }