@rafaelaugusto/jolt 0.1.0-beta.5 → 0.1.0-beta.6

package/platforms/android/java/org/rafaelaugusto/jolt/NumberRoll.java

@@ -0,0 +1,190 @@
+package org.rafaelaugusto.jolt;
+
+import android.animation.Animator;
+import android.animation.AnimatorListenerAdapter;
+import android.animation.ValueAnimator;
+import android.graphics.Canvas;
+import android.graphics.Paint;
+import android.text.SpannableStringBuilder;
+import android.text.Spanned;
+import android.text.method.TransformationMethod;
+import android.text.style.ReplacementSpan;
+import android.view.animation.LinearInterpolator;
+import android.view.animation.PathInterpolator;
+import android.widget.TextView;
+
+/** Rolls the changed positions of a TextView with one native animator. */
+public final class NumberRoll {
+    public interface Callback {
+        void onEnd(boolean finished);
+    }
+
+    private static final int MAX_POSITIONS = 256;
+    private final TextView view;
+    private final CharSequence original;
+    private final CharSequence shown;
+    private final TransformationMethod method;
+    private final DigitSpan[] spans;
+    private final int[] starts;
+    private final int[] ends;
+    private final float[] times;
+    private final float[] values;
+    private final long duration;
+    private final long delay;
+    private final long stagger;
+    private final long fade;
+    private final boolean tabular;
+    private final Callback callback;
+    private final PathInterpolator ease = new PathInterpolator(0f, 0f, 0.58f, 1f);
+    private ValueAnimator animator;
+    private CharSequence current;
+    private boolean removedMethod;
+    private boolean ended;
+
+    // Positions are ordered from the end of the text; each one starts `stagger` after the previous.
+    public NumberRoll(TextView view, int[] starts, int[] ends, String[] previous, int direction,
+            float[] times, float[] values, long duration, long delay, long stagger, float shift,
+            long fade, boolean tabular, Callback callback) {
+        this.view = view;
+        this.original = view.getText();
+        // NativeScript installs a TransformationMethod that rebuilds the displayed text from its
+        // own model, discarding spans set from here. Work on what is displayed and remove it while rolling.
+        this.method = view.getTransformationMethod();
+        CharSequence displayed = method != null && original != null ? method.getTransformation(original, view) : original;
+        this.shown = displayed != null ? displayed : "";
+        this.starts = starts;
+        this.ends = ends;
+        this.times = times;
+        this.values = values;
+        this.duration = duration;
+        this.delay = delay;
+        this.stagger = stagger;
+        this.fade = fade;
+        this.tabular = tabular;
+        this.callback = callback;
+        spans = new DigitSpan[starts.length];
+        for (int i = 0; i < starts.length; i++) {
+            String old = i < previous.length && previous[i] != null ? previous[i] : "";
+            spans[i] = new DigitSpan(old, direction, shift, values.length > 0 ? values[0] : shift);
+        }
+    }
+
+    public boolean isSupported() {
+        if (original == null || starts.length == 0 || starts.length > MAX_POSITIONS) return false;
+        if (ends.length != starts.length || times.length < 2 || times.length != values.length) return false;
+        int length = shown.length();
+        for (int i = 0; i < starts.length; i++) {
+            if (starts[i] < 0 || ends[i] > length || starts[i] >= ends[i]) return false;
+        }
+        return true;
+    }
+
+    public void start() {
+        if (ended || animator != null) return;
+        if (tabular) view.setFontFeatureSettings("tnum");
+        SpannableStringBuilder spannable = new SpannableStringBuilder(shown);
+        for (int i = 0; i < spans.length; i++) {
+            spannable.setSpan(spans[i], starts[i], ends[i], Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
+        }
+        if (method != null) {
+            removedMethod = true;
+            view.setTransformationMethod(null);
+        }
+        view.setText(spannable);
+        current = view.getText();
+        final long total = delay + duration + stagger * (spans.length - 1);
+        animator = ValueAnimator.ofFloat(0f, 1f);
+        animator.setDuration(Math.max(total, 1));
+        animator.setInterpolator(new LinearInterpolator());
+        animator.addUpdateListener(animation -> update(animation.getAnimatedFraction() * total));
+        animator.addListener(new AnimatorListenerAdapter() {
+            @Override
+            public void onAnimationEnd(Animator animation) {
+                finish(true);
+            }
+        });
+        animator.start();
+    }
+
+    public void cancel() {
+        finish(false);
+        if (animator != null) animator.cancel();
+    }
+
+    private void update(float elapsed) {
+        for (int i = 0; i < spans.length; i++) {
+            float local = elapsed - delay - stagger * i;
+            spans[i].set(sample(local), alpha(local));
+        }
+        view.invalidate();
+    }
+
+    private float sample(float local) {
+        if (local <= 0) return values[0];
+        if (local >= duration) return values[values.length - 1];
+        float t = local / duration;
+        int i = 1;
+        while (i < times.length - 1 && times[i] < t) i++;
+        float span = times[i] - times[i - 1];
+        float fraction = span > 0 ? (t - times[i - 1]) / span : 1f;
+        return values[i - 1] + (values[i] - values[i - 1]) * fraction;
+    }
+
+    private float alpha(float local) {
+        if (local <= 0) return 0f;
+        if (fade <= 0 || local >= fade) return 1f;
+        return ease.getInterpolation(local / fade);
+    }
+
+    private void finish(boolean finished) {
+        if (ended) return;
+        ended = true;
+        if (current != null && view.getText() == current) view.setText(original);
+        if (removedMethod) view.setTransformationMethod(method);
+        callback.onEnd(finished);
+    }
+
+    /** Draws the new glyphs sliding in over the old ones sliding out, clipped to the line. */
+    static final class DigitSpan extends ReplacementSpan {
+        private final String previous;
+        private final int direction;
+        private final float shift;
+        private float offset;
+        private float alpha;
+
+        DigitSpan(String previous, int direction, float shift, float offset) {
+            this.previous = previous;
+            this.direction = direction;
+            this.shift = shift;
+            this.offset = offset;
+        }
+
+        void set(float offset, float alpha) {
+            this.offset = offset;
+            this.alpha = alpha;
+        }
+
+        @Override
+        public int getSize(Paint paint, CharSequence text, int start, int end, Paint.FontMetricsInt fm) {
+            if (fm != null) paint.getFontMetricsInt(fm);
+            return Math.round(Math.max(paint.measureText(text, start, end), paint.measureText(previous)));
+        }
+
+        @Override
+        public void draw(Canvas canvas, CharSequence text, int start, int end, float x, int top, int y,
+                int bottom, Paint paint) {
+            int base = paint.getAlpha();
+            float width = getSize(paint, text, start, end, null);
+            canvas.save();
+            canvas.clipRect(x, top, x + width, bottom);
+            paint.setAlpha(Math.round(base * alpha));
+            canvas.drawText(text, start, end, x, y + direction * offset, paint);
+            if (!previous.isEmpty()) {
+                paint.setAlpha(Math.round(base * (1f - alpha)));
+                canvas.drawText(previous, x, y + direction * (offset - shift), paint);
+            }
+            paint.setAlpha(base);
+            canvas.restore();
+        }
+    }
+}

package/platforms/android/java/org/rafaelaugusto/jolt/TextReveal.java

@@ -0,0 +1,180 @@
+package org.rafaelaugusto.jolt;
+
+import android.animation.Animator;
+import android.animation.AnimatorListenerAdapter;
+import android.animation.ValueAnimator;
+import android.text.SpannableStringBuilder;
+import android.text.Spanned;
+import android.text.TextPaint;
+import android.text.method.TransformationMethod;
+import android.text.style.CharacterStyle;
+import android.text.style.UpdateAppearance;
+import android.view.animation.Interpolator;
+import android.view.animation.LinearInterpolator;
+import android.view.animation.PathInterpolator;
+import android.widget.TextView;
+import java.text.BreakIterator;
+import java.util.ArrayList;
+import java.util.List;
+
+/** Fades a TextView's text in piece by piece. Layout, truncation and the real text stay as they are. */
+public final class TextReveal {
+    public interface Callback {
+        void onEnd(boolean finished);
+    }
+
+    private static final int MAX_PIECES = 256;
+    private static final Interpolator EASE_OUT = new PathInterpolator(0f, 0f, 0.58f, 1f);
+    private final TextView view;
+    private final long duration;
+    private final long stagger;
+    private final long delay;
+    private final float offset;
+    private final Callback callback;
+    private final CharSequence original;
+    private final CharSequence shown;
+    private final TransformationMethod method;
+    private final Piece[] pieces;
+    private ValueAnimator animator;
+    private boolean settled;
+
+    public TextReveal(TextView view, boolean byWord, long duration, long stagger, long delay, float offset, Callback callback) {
+        this.view = view;
+        this.duration = Math.max(duration, 1);
+        this.stagger = stagger;
+        this.delay = delay;
+        this.offset = offset;
+        this.callback = callback;
+        CharSequence text = view.getText();
+        this.original = text == null ? "" : text;
+        // NativeScript's transformation method rebuilds the displayed text from its own model,
+        // so pieces are measured on what is drawn and the spans go on that text.
+        this.method = view.getTransformationMethod();
+        CharSequence displayed = method != null ? method.getTransformation(original, view) : original;
+        this.shown = displayed == null ? "" : displayed;
+        this.pieces = split(shown.toString(), byWord);
+    }
+
+    public boolean isSupported() {
+        return pieces.length <= MAX_PIECES;
+    }
+
+    public void start() {
+        if (settled || animator != null) return;
+        if (pieces.length == 0) {
+            settle(true);
+            return;
+        }
+        SpannableStringBuilder spannable = new SpannableStringBuilder(shown);
+        for (Piece piece : pieces) {
+            piece.alpha = 0f;
+            piece.shift = offset;
+            spannable.setSpan(piece, piece.start, piece.end, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
+        }
+        if (method != null) view.setTransformationMethod(null);
+        view.setText(spannable);
+        final long total = delay + duration + (pieces.length - 1) * stagger;
+        animator = ValueAnimator.ofFloat(0f, 1f);
+        animator.setDuration(total);
+        animator.setInterpolator(new LinearInterpolator());
+        animator.addUpdateListener(new ValueAnimator.AnimatorUpdateListener() {
+            @Override
+            public void onAnimationUpdate(ValueAnimator animation) {
+                update(animation.getAnimatedFraction() * total);
+                view.invalidate();
+            }
+        });
+        animator.addListener(new AnimatorListenerAdapter() {
+            @Override
+            public void onAnimationEnd(Animator animation) {
+                settle(true);
+            }
+        });
+        animator.start();
+    }
+
+    public void cancel() {
+        settle(false);
+    }
+
+    private void update(float time) {
+        for (int i = 0; i < pieces.length; i++) {
+            float local = (time - delay - i * stagger) / duration;
+            float eased = local <= 0f ? 0f : local >= 1f ? 1f : EASE_OUT.getInterpolation(local);
+            pieces[i].alpha = eased;
+            pieces[i].shift = offset * (1f - eased);
+        }
+    }
+
+    private void settle(boolean finished) {
+        if (settled) return;
+        settled = true;
+        ValueAnimator running = animator;
+        animator = null;
+        if (running != null) running.cancel();
+        CharSequence current = view.getText();
+        // An app change already replaced the spans; its text wins.
+        if (current instanceof Spanned && ((Spanned) current).getSpans(0, current.length(), Piece.class).length > 0) {
+            view.setText(original);
+        }
+        if (method != null && view.getTransformationMethod() == null) view.setTransformationMethod(method);
+        callback.onEnd(finished);
+    }
+
+    private static Piece[] split(String text, boolean byWord) {
+        List<Piece> pieces = new ArrayList<>();
+        BreakIterator iterator = byWord ? BreakIterator.getWordInstance() : BreakIterator.getCharacterInstance();
+        iterator.setText(text);
+        int start = iterator.first();
+        for (int end = iterator.next(); end != BreakIterator.DONE; start = end, end = iterator.next()) {
+            if (byWord ? isWord(text, start, end) : !isBlank(text, start, end)) pieces.add(new Piece(start, end));
+        }
+        if (byWord) {
+            // Spaces and punctuation stay with the word before them, so every visible mark is revealed.
+            for (int i = 0; i < pieces.size(); i++) {
+                Piece piece = pieces.get(i);
+                if (i == 0) piece.start = 0;
+                piece.end = i + 1 < pieces.size() ? pieces.get(i + 1).start : text.length();
+            }
+            if (pieces.isEmpty() && !isBlank(text, 0, text.length())) pieces.add(new Piece(0, text.length()));
+        }
+        return pieces.toArray(new Piece[0]);
+    }
+
+    private static boolean isWord(String text, int start, int end) {
+        for (int i = start; i < end; ) {
+            int point = text.codePointAt(i);
+            if (Character.isLetterOrDigit(point)) return true;
+            i += Character.charCount(point);
+        }
+        return false;
+    }
+
+    private static boolean isBlank(String text, int start, int end) {
+        for (int i = start; i < end; ) {
+            int point = text.codePointAt(i);
+            if (!Character.isWhitespace(point) && !Character.isSpaceChar(point)) return false;
+            i += Character.charCount(point);
+        }
+        return true;
+    }
+
+    /** Only changes how its range is drawn, so the TextView's layout never sees it. */
+    private static final class Piece extends CharacterStyle implements UpdateAppearance {
+        int start;
+        int end;
+        float alpha;
+        float shift;
+
+        Piece(int start, int end) {
+            this.start = start;
+            this.end = end;
+        }
+
+        @Override
+        public void updateDrawState(TextPaint paint) {
+            paint.setAlpha(Math.round(paint.getAlpha() * alpha));
+            paint.baselineShift += Math.round(shift);
+        }
+    }
+}

package/platforms/android/proguard-rules.pro

@@ -5,3 +5,9 @@
     public android.graphics.drawable.Drawable getWrappedDrawable();
 }
 -keep class org.rafaelaugusto.jolt.DecorationTarget { *; }
+-keep class org.rafaelaugusto.jolt.KeyboardFollower { *; }
+-keep class org.rafaelaugusto.jolt.KeyboardFollower$* { *; }
+-keep class org.rafaelaugusto.jolt.TextReveal { *; }
+-keep class org.rafaelaugusto.jolt.TextReveal$* { *; }
+-keep class org.rafaelaugusto.jolt.NumberRoll { *; }
+-keep class org.rafaelaugusto.jolt.NumberRoll$* { *; }

package/src/android-plugin.d.ts

@@ -0,0 +1,64 @@
+declare namespace org.rafaelaugusto.jolt {
+  class KeyboardFollower {
+    constructor(
+      view: android.view.View,
+      offset: number,
+      listener: KeyboardFollower.Listener,
+    )
+    attach(): void
+    detach(): void
+  }
+  namespace KeyboardFollower {
+    class Listener {
+      constructor(implementation: {
+        onStart(): void
+        onSettled(translation: number): void
+      })
+    }
+  }
+  class TextReveal {
+    constructor(
+      view: android.widget.TextView,
+      byWord: boolean,
+      duration: number,
+      stagger: number,
+      delay: number,
+      offset: number,
+      callback: TextReveal.Callback,
+    )
+    isSupported(): boolean
+    start(): void
+    cancel(): void
+  }
+  namespace TextReveal {
+    class Callback {
+      constructor(implementation: { onEnd(finished: boolean): void })
+    }
+  }
+  class NumberRoll {
+    constructor(
+      view: android.widget.TextView,
+      starts: androidNative.Array<number>,
+      ends: androidNative.Array<number>,
+      previous: androidNative.Array<string>,
+      direction: number,
+      times: androidNative.Array<number>,
+      values: androidNative.Array<number>,
+      duration: number,
+      delay: number,
+      stagger: number,
+      shift: number,
+      fade: number,
+      tabular: boolean,
+      callback: NumberRoll.Callback,
+    )
+    isSupported(): boolean
+    start(): void
+    cancel(): void
+  }
+  namespace NumberRoll {
+    class Callback {
+      constructor(implementation: { onEnd(finished: boolean): void })
+    }
+  }
+}

package/src/animate.ts

@@ -5,6 +5,7 @@ import {
 } from './decoration.js'
 import { playbackGroup } from './playback-group.js'
 import type { PlaybackAnimation } from './playback.js'
+import { preparePath, type PreparedPath } from './path.js'
 import { View } from '@nativescript/core'
 import {
   isColorProperty,
@@ -38,13 +39,14 @@ import type {
   DecayVelocity,
   Keyframes,
   KeyframeValue,
+  KeyframeProperty,
   Stagger,
   Target,
 } from './types.js'
 
 interface Options {
   base: Transition
-  overrides: Partial<Record<keyof Keyframes, Transition>>
+  overrides: Partial<Record<KeyframeProperty | 'path', Transition>>
   stagger: number | Stagger | undefined
   relative: boolean | undefined
   haptic: Haptic | undefined
@@ -65,7 +67,7 @@ export function animate(
   animation: Keyframes | PresetName,
   options?: AnimateOptions | SpringName,
 ): PlaybackAnimation {
-  const { keyframes, base, overrides, stagger, relative, haptic } = prepare(
+  const { keyframes, base, overrides, stagger, relative, haptic, path } = prepare(
     animation,
     options,
   )
@@ -78,7 +80,7 @@ export function animate(
       else if (isDecorationProperty(property)) validateDecorationTarget(view, property)
     return new ViewAnimation(
       view,
-      plan(keyframes, base, overrides, 0, relative),
+      plan(keyframes, base, overrides, 0, relative, path),
       feedback,
     )
   }
@@ -88,23 +90,19 @@ export function animate(
     for (const property of Object.keys(keyframes))
       if (isColorProperty(property)) validateColorTarget(view, property)
       else if (isDecorationProperty(property)) validateDecorationTarget(view, property)
-  return playbackGroup(
-    views.map(
-      (view, index) =>
-        new ViewAnimation(
-          view,
-          plan(
-            keyframes,
-            base,
-            overrides,
-            staggerDelay(stagger, index, views.length),
-            relative,
-          ),
-          feedback,
-          true,
-        ),
+  const plans = views.map((_, index) =>
+    plan(
+      keyframes,
+      base,
+      overrides,
+      staggerDelay(stagger, index, views.length),
+      relative,
+      path,
     ),
   )
+  return playbackGroup(
+    views.map((view, index) => new ViewAnimation(view, plans[index]!, feedback, true)),
+  )
 }
 
 /** Starts at the current translation and slows down from a velocity in DIPs per second. */
@@ -183,7 +181,7 @@ export function decay(
 /** Stops all or selected properties at their current values. `scale` stops both axes. */
 export function stop(
   target: Target | readonly Target[],
-  properties?: readonly (keyof Keyframes)[],
+  properties?: readonly KeyframeProperty[],
 ) {
   const expanded = properties?.flatMap<Property>((property) =>
     property === 'scale' ? ['scaleX', 'scaleY'] : [property],
@@ -225,6 +223,17 @@ function isList<T>(target: T | readonly T[]): target is readonly T[] {
 function prepare(
   animation: Keyframes | PresetName,
   options?: AnimateOptions | SpringName,
+) {
+  const prepared = resolveAnimation(animation, options)
+  return {
+    ...prepared,
+    path: preparePath(prepared.keyframes, prepared.base, prepared.overrides),
+  }
+}
+
+function resolveAnimation(
+  animation: Keyframes | PresetName,
+  options?: AnimateOptions | SpringName,
 ) {
   const user = normalize(options)
   if (typeof animation !== 'string') return { keyframes: animation, ...user }
@@ -271,7 +280,7 @@ function normalize(options: AnimateOptions | SpringName | undefined): Options {
     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)) {
+    else if (key === 'path' || key === 'scale' || isProperty(key)) {
       overrides[key] = typeof value === 'string' ? spring(value as SpringName) : value
     } else base[key] = value
   }
@@ -284,8 +293,25 @@ function plan(
   overrides: Options['overrides'],
   offset: number,
   relative = false,
+  path?: PreparedPath,
 ): Plan[] {
-  return expand(keyframes).map(([property, frames]) => {
+  return expand(keyframes, path).map(([property, frames]) => {
+    if (path?.properties.includes(property as 'x' | 'y' | 'rotate')) {
+      if (
+        !Number.isFinite(path.transition.delay + offset) ||
+        path.transition.delay + offset < 0
+      )
+        throw new RangeError(
+          'Path delays, including stagger, must be finite and nonnegative.',
+        )
+      return {
+        property,
+        keyframes: frames,
+        transition: { ...path.transition, delay: path.transition.delay + offset },
+        relative,
+        path,
+      }
+    }
     const override =
       overrides[property] ?? (property.startsWith('scale') ? overrides.scale : undefined)
     const transition = resolveTransition(
@@ -303,31 +329,55 @@ export function startingValues(
   animation: Keyframes | PresetName,
   options?: AnimateOptions | SpringName,
 ) {
-  const { keyframes, relative } = prepare(animation, options)
+  const { keyframes, relative, path } = prepare(animation, options)
   if (!keyframes) throw new Error(`Unknown preset "${animation}".`)
   return new Map(
-    expand(keyframes).map(([property, [first]]) => [
+    expand(keyframes, path).map(([property, [first]]) => [
       property,
       relative && !isColorProperty(property) ? null : first!,
     ]),
   )
 }
 
-function expand(keyframes: Keyframes): [Property, (number | null)[]][] {
+/** Each property the animation touches, with the value it leaves behind when that is known up front. */
+export function endingValues(
+  animation: Keyframes | PresetName,
+  options?: AnimateOptions | SpringName,
+) {
+  const { keyframes, base, overrides, relative, path } = prepare(animation, options)
+  return new Map(
+    plan(keyframes, base, overrides, 0, relative, path).map(
+      ({ property, keyframes: frames, transition, path: owned }) => {
+        const finite = Number.isFinite(transition.repeat)
+        const backwards = transition.reverse && finite && transition.repeat % 2 === 1
+        const unknown = owned !== undefined || (relative && !isColorProperty(property))
+        const frame = !finite || backwards ? frames[0] : frames.at(-1)
+        return [property, unknown ? null : frame!]
+      },
+    ),
+  )
+}
+
+function expand(
+  keyframes: Keyframes,
+  path?: PreparedPath,
+): [Property, (number | null)[]][] {
   const expanded: [Property, (number | null)[]][] = []
-  for (const [key, value] of Object.entries(keyframes) as [
-    keyof Keyframes,
-    KeyframeValue | ColorKeyframes | undefined,
-  ][]) {
-    if (value === undefined) continue
+  for (const [key, value] of Object.entries(keyframes)) {
+    if (value === undefined || key === 'path' || key === 'orient') continue
     if (key !== 'scale' && !isProperty(key)) throw new Error(`Can't animate "${key}".`)
 
     const properties: Property[] = key === 'scale' ? ['scaleX', 'scaleY'] : [key]
     for (const property of properties) {
       if (key === 'scale' && keyframes[property] !== undefined) continue
-      expanded.push([property, toKeyframes(property, value)])
+      expanded.push([
+        property,
+        toKeyframes(property, value as KeyframeValue | ColorKeyframes),
+      ])
     }
   }
+  for (const [property, value] of path?.starts ?? [])
+    expanded.push([property, [value, value]])
   return expanded
 }
 

package/src/config.ts

@@ -0,0 +1,46 @@
+import { getDriver } from './driver/index.js'
+
+export interface JoltConfig {
+  /** Playback speed for every engine animation. `0.2` plays everything five times slower. */
+  timeScale?: number
+  /**
+   * When transforms, paths, decorations and decay jump to their end instead of animating.
+   * `user` follows the platform setting. Opacity and colors still animate.
+   */
+  reducedMotion?: 'user' | 'always' | 'never'
+}
+
+const settings: Required<JoltConfig> = { timeScale: 1, reducedMotion: 'user' }
+const preferences: readonly JoltConfig['reducedMotion'][] = ['user', 'always', 'never']
+
+/**
+ * Global settings, applied to animations that start after the call.
+ *
+ * ```ts
+ * configure({ timeScale: 0.2 }) // tune a spring in slow motion
+ * configure({ reducedMotion: 'always' }) // check the reduced layout
+ * ```
+ */
+export function configure(options: JoltConfig): void {
+  if (options === null || typeof options !== 'object')
+    throw new TypeError('configure() takes an options object.')
+  const { timeScale, reducedMotion } = options
+  if (timeScale !== undefined && (!Number.isFinite(timeScale) || timeScale <= 0))
+    throw new RangeError(`Time scale must be a positive finite number, got ${timeScale}.`)
+  if (reducedMotion !== undefined && !preferences.includes(reducedMotion))
+    throw new TypeError(
+      `Reduced motion must be 'user', 'always' or 'never', got ${String(reducedMotion)}.`,
+    )
+  if (timeScale !== undefined) settings.timeScale = timeScale
+  if (reducedMotion !== undefined) settings.reducedMotion = reducedMotion
+}
+
+export function timeScale(): number {
+  return settings.timeScale
+}
+
+/** Whether motion is reduced right now. `user` asks the platform each time. */
+export function reducedMotion(): boolean {
+  if (settings.reducedMotion === 'user') return getDriver().reducedMotion?.() ?? false
+  return settings.reducedMotion === 'always'
+}