@rafaelaugusto/jolt 0.1.0-beta.13 → 0.1.0-beta.15

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

@@ -0,0 +1,114 @@
+package org.rafaelaugusto.jolt;
+
+/** Bounded, allocation-free particle state. Units are DIPs, seconds and degrees.
+ * Android supplies elapsed wall time; the same engine runs in deterministic JVM tests. */
+public final class ParticleSimulation {
+    public static final int MAX_PARTICLES = 10000;
+    public final int shape, source;
+    public final float size;
+    private final int[] palette;
+    private final double rate, lifetime, duration;
+    private final float velocity, velocityRange, angle, spread, gravity, spin, spinRange;
+    private final boolean fade;
+    private double[] births;
+    private float[] xs, ys, vxs, vys, rotations, spins;
+    private int[] colors;
+    private int live, peak;
+    private long scheduled, emitted, skipped;
+    private long random;
+    private double time;
+
+    public ParticleSimulation(int[] palette, int shape, int source, double rate,
+            double lifetimeMs, float size, float velocity, float velocityRange,
+            float angle, float spread, float gravity, float spin, float spinRange,
+            boolean fade, double durationMs, long seed) {
+        if (palette == null || palette.length == 0 || palette.length > 32 || shape < 0 || shape > 2 || source < 0 || source > 2)
+            throw new IllegalArgumentException("Invalid particle colors, shape or source");
+        if (!finite(rate) || rate <= 0 || rate > 50000 || !finite(lifetimeMs) || lifetimeMs < 1 || lifetimeMs > 60000
+                || !finite(durationMs) || (durationMs != -1 && (durationMs < 1 || durationMs > Integer.MAX_VALUE - lifetimeMs - 50))
+                || !finite(size) || size < 1 || size > 128 || !finite(velocity) || velocity < 0 || velocity > 10000
+                || !finite(velocityRange) || velocityRange < 0 || velocityRange > 10000
+                || !finite(angle) || Math.abs(angle) > 360 || !finite(spread) || spread < 0 || spread > 360
+                || !finite(gravity) || Math.abs(gravity) > 10000 || !finite(spin) || Math.abs(spin) > 3600
+                || !finite(spinRange) || spinRange < 0 || spinRange > 3600)
+            throw new IllegalArgumentException("Invalid particle settings");
+        this.palette = palette.clone();
+        this.shape = shape; this.source = source; this.rate = rate;
+        lifetime = lifetimeMs / 1000; duration = durationMs < 0 ? Double.POSITIVE_INFINITY : durationMs / 1000;
+        this.size = size; this.velocity = velocity; this.velocityRange = velocityRange;
+        this.angle = angle; this.spread = spread; this.gravity = gravity;
+        this.spin = spin; this.spinRange = spinRange; this.fade = fade;
+        random = seed == 0 ? 1 : seed;
+        double population = rate * Math.min(lifetime, duration);
+        if (population > MAX_PARTICLES + 0.000001) throw new IllegalArgumentException("Particle population exceeds 10000");
+        int capacity = Math.max(1, Math.min(MAX_PARTICLES, (int)Math.ceil(population)));
+        births = new double[capacity]; xs = new float[capacity]; ys = new float[capacity];
+        vxs = new float[capacity]; vys = new float[capacity]; rotations = new float[capacity];
+        spins = new float[capacity]; colors = new int[capacity];
+    }
+
+    private static boolean finite(double value) { return !Double.isNaN(value) && !Double.isInfinite(value); }
+    private float unit() {
+        // xorshift64*: deterministic internal seed, never part of the public JS contract.
+        random ^= random >>> 12; random ^= random << 25; random ^= random >>> 27;
+        return ((random * 2685821657736338717L) >>> 40) / 16777216f;
+    }
+    private float variation(float range) { return (unit() * 2 - 1) * range; }
+
+    /** Advance directly to the current time, skipping already-dead births after a stall.
+     * No backlog of expired particles and no integration steps proportional to missed frames. */
+    public void advance(double elapsedSeconds, float width, float height) {
+        if (births == null || !finite(elapsedSeconds)) return;
+        time = Math.max(time, Math.max(0, elapsedSeconds));
+        for (int i = live - 1; i >= 0; i--) {
+            if (time - births[i] >= lifetime - 0.000000001) {
+                int last = --live;
+                births[i] = births[last]; xs[i] = xs[last]; ys[i] = ys[last];
+                vxs[i] = vxs[last]; vys[i] = vys[last]; rotations[i] = rotations[last];
+                spins[i] = spins[last]; colors[i] = colors[last];
+            }
+        }
+        long until = (long)Math.floor(Math.min(time, duration) * rate + 0.0000001);
+        long dead = Math.min(until, (long)Math.floor(Math.max(0, time - lifetime) * rate + 0.0000001));
+        if (dead > scheduled) { skipped += dead - scheduled; scheduled = dead; }
+        // scheduled is monotonic; at most capacity particles can be alive in this interval.
+        while (scheduled < until) {
+            long index = ++scheduled;
+            if (live >= births.length) { skipped++; continue; }
+            int i = live++;
+            births[i] = index / rate;
+            xs[i] = source == 0 ? width * .5f : unit() * width;
+            ys[i] = source == 1 ? 0 : source == 2 ? height : height * .5f;
+            double direction = Math.toRadians(angle + variation(spread * .5f));
+            float speed = velocity + variation(velocityRange);
+            vxs[i] = (float)Math.cos(direction) * speed;
+            vys[i] = (float)Math.sin(direction) * speed;
+            rotations[i] = shape == 1 ? unit() * 360 : 0;
+            spins[i] = spin + variation(spinRange);
+            colors[i] = palette[(int)((index - 1) % palette.length)];
+            emitted++;
+        }
+        peak = Math.max(peak, live);
+    }
+
+    public float x(int i) { return xs[i] + vxs[i] * (float)(time - births[i]); }
+    public float y(int i) { float age = (float)(time - births[i]); return ys[i] + vys[i] * age + gravity * age * age * .5f; }
+    public float rotation(int i) { return rotations[i] + spins[i] * (float)(time - births[i]); }
+    public int color(int i) {
+        int color = colors[i];
+        if (!fade) return color;
+        int alpha = Math.round((color >>> 24) * (float)Math.max(0, 1 - (time - births[i]) / lifetime));
+        return (color & 0x00ffffff) | (alpha << 24);
+    }
+    public boolean finished() { return time >= duration + lifetime || (time >= duration && live == 0); }
+    public int live() { return live; }
+    public int peak() { return peak; }
+    public int capacity() { return births == null ? 0 : births.length; }
+    public long emitted() { return emitted; }
+    public long skipped() { return skipped; }
+    public double time() { return time; }
+    public void clear() {
+        live = 0;
+        births = null; xs = ys = vxs = vys = rotations = spins = null; colors = null;
+    }
+}

package/platforms/android/proguard-rules.pro

@@ -19,3 +19,5 @@
 -keep class org.rafaelaugusto.jolt.PhotoZoom$* { *; }
 -keep class org.rafaelaugusto.jolt.GradientLayer { *; }
 -keep class org.rafaelaugusto.jolt.GradientLayer$* { *; }
+-keep class org.rafaelaugusto.jolt.ParticleEmitter { *; }
+-keep class org.rafaelaugusto.jolt.ParticleEmitter$* { *; }

package/src/android-plugin.d.ts

@@ -1,4 +1,52 @@
 declare namespace org.rafaelaugusto.jolt {
+  class ParticleEmitter {
+    constructor(
+      target: android.view.View,
+      overlay: boolean,
+      colors: native.Array<number>,
+      shape: number,
+      source: number,
+      rate: number,
+      lifetimeMs: number,
+      size: number,
+      velocity: number,
+      velocityRange: number,
+      angle: number,
+      spread: number,
+      gravity: number,
+      spin: number,
+      spinRange: number,
+      fade: boolean,
+      durationMs: number,
+      listener: ParticleEmitter.Listener,
+    )
+    start(): void
+    refresh(cornerPixels: number): void
+    stop(): void
+    static getActiveCount(): number
+    isStopped(): boolean
+    getLiveCount(): number
+    getPeakCount(): number
+    getCapacity(): number
+    getEmittedCount(): number
+    getSkippedCount(): number
+    getFrameCount(): number
+    getDrawCount(): number
+    getWorkNanos(): number
+    getDrawNanos(): number
+    getDensity(): number
+    getTimeSeconds(): number
+    isObserving(): boolean
+    getOriginInWindow(): native.Array<number>
+    getParticle(index: number): native.Array<number>
+    getFrameIntervals(): native.Array<number>
+    getBounds(): android.graphics.Rect
+  }
+  namespace ParticleEmitter {
+    class Listener {
+      constructor(implementation: { onEnd(): void })
+    }
+  }
   class PhotoZoom {
     constructor(
       image: android.widget.ImageView,
@@ -116,6 +164,14 @@ declare namespace org.rafaelaugusto.jolt {
       reverse: boolean,
       listener: GradientLayer.Listener,
     ): void
+    control(elapsed: number, paused: boolean): void
+    isPlaying(): boolean
+    getGeometry(): native.Array<number>
+    getCorner(): number
+    getStops(): native.Array<number>
+    getColors(): native.Array<number>
+    getSampleCount(): number
+    dispose(): void
     cancel(): void
   }
   namespace GradientLayer {

package/src/driver/android-gradient.ts

@@ -28,8 +28,10 @@ export function androidGradient(
   }
   let stack: android.graphics.drawable.LayerDrawable | undefined
   let queued = false
+  let removed = false
 
   const wrap = () => {
+    if (removed) return
     const native = view.nativeViewProtected as android.view.View | undefined
     if (!native) return
     const corner = typeof view.borderRadius === 'number' ? view.borderRadius : 0
@@ -87,6 +89,9 @@ export function androidGradient(
         }),
       )
       return {
+        control(elapsed, paused) {
+          if (active) layer.control(Math.round(elapsed), paused)
+        },
         cancel() {
           if (!active) return
           active = false
@@ -96,10 +101,12 @@ export function androidGradient(
       }
     },
     remove() {
+      if (removed) return
+      removed = true
       view.off('loaded', wrap)
       view.style.off('backgroundInternalChange', rewrap)
       view.style.off('borderTopLeftRadiusChange', rewrap)
-      layer.cancel()
+      layer.dispose()
       const native = view.nativeViewProtected as android.view.View | undefined
       if (native && stack && native.getBackground() === stack)
         native.setBackground(stack.getDrawable(0))

package/src/driver/android-particles.ts

@@ -0,0 +1,118 @@
+import { Application, Color, Utils, type View } from '@nativescript/core'
+import { onReducedMotion, reducedMotion } from '../config.js'
+import type { ParticleSettings } from '../particles.js'
+
+type NativeEmitter = org.rafaelaugusto.jolt.ParticleEmitter
+const live = new WeakMap<View, { emitter?: NativeEmitter; burst?: NativeEmitter }>()
+
+/** Internal diagnostic seam for native conformance, not a public animation API. */
+export function currentAndroidParticles(view: View, overlay = false) {
+  return live.get(view)?.[overlay ? 'burst' : 'emitter']
+}
+
+export function androidParticles(
+  view: View,
+  settings: ParticleSettings,
+  overlay: boolean,
+  owners: WeakMap<View, () => void>,
+): () => void {
+  let stopped = false,
+    queued = false
+  let emitter: NativeEmitter | undefined,
+    target: android.view.View | undefined,
+    unwatch: (() => void) | undefined
+  const key = overlay ? 'burst' : 'emitter'
+  const stop = () => {
+    if (stopped) return
+    stopped = true
+    view.off('loaded', schedule)
+    view.off('layoutChanged', schedule)
+    view.off('unloaded', stop)
+    view.style.off('borderTopLeftRadiusChange', schedule)
+    Application.off(Application.suspendEvent, stop)
+    unwatch?.()
+    unwatch = undefined
+    if (owners.get(view) === stop) owners.delete(view)
+    const active = live.get(view)
+    if (active && active[key] === emitter) {
+      delete active[key]
+      if (!active.emitter && !active.burst) live.delete(view)
+    }
+    const native = emitter
+    emitter = target = undefined
+    native?.stop()
+  }
+  const update = () => {
+    if (!view.isLoaded) return
+    if (reducedMotion()) return stop()
+    const native = view.nativeViewProtected as android.view.View | undefined
+    if (target && target !== native) return stop()
+    if (emitter) {
+      emitter.refresh(
+        (typeof view.borderRadius === 'number' ? view.borderRadius : 0) *
+          Utils.layout.getDisplayDensity(),
+      )
+      return
+    }
+    if (!native?.getWindowToken() || native.getWidth() <= 0 || native.getHeight() <= 0)
+      return
+    const colors = Array.create('int', settings.colors.length)
+    settings.colors.forEach((color, i) => {
+      colors[i] = new Color(color).argb | 0
+    })
+    target = native
+    emitter = new org.rafaelaugusto.jolt.ParticleEmitter(
+      native,
+      overlay,
+      colors,
+      settings.shape === 'circle' ? 0 : settings.shape === 'rectangle' ? 1 : 2,
+      settings.source === 'center' ? 0 : settings.source === 'top' ? 1 : 2,
+      settings.rate,
+      settings.lifetime,
+      settings.size,
+      settings.velocity,
+      settings.velocityRange,
+      settings.angle,
+      settings.spread,
+      settings.gravity,
+      settings.spin,
+      settings.spinRange,
+      settings.fadeOut,
+      settings.duration ?? -1,
+      new org.rafaelaugusto.jolt.ParticleEmitter.Listener({ onEnd: stop }),
+    )
+    const active = live.get(view) ?? {}
+    active[key] = emitter
+    live.set(view, active)
+    emitter.refresh(
+      (typeof view.borderRadius === 'number' ? view.borderRadius : 0) *
+        Utils.layout.getDisplayDensity(),
+    )
+    emitter.start()
+  }
+  function schedule() {
+    if (stopped || queued) return
+    queued = true
+    void Promise.resolve().then(() => {
+      queued = false
+      if (stopped) return
+      try {
+        update()
+      } catch (error) {
+        stop()
+        throw error
+      }
+    })
+  }
+  owners.set(view, stop)
+  view.on('loaded', schedule)
+  view.on('layoutChanged', schedule)
+  view.on('unloaded', stop)
+  view.style.on('borderTopLeftRadiusChange', schedule)
+  Application.on(Application.suspendEvent, stop)
+  unwatch = onReducedMotion((reduced) => {
+    if (reduced) stop()
+  })
+  schedule()
+  return stop
+}

package/src/driver/ios-gradient.ts

@@ -47,7 +47,8 @@ export function iosGradient(view: View, type: GradientType): GradientPainter {
     CATransaction.setDisableActions(true)
     if (layer.superlayer !== host.layer) host.layer.insertSublayerAtIndex(layer, 0)
     layer.frame = host.layer.bounds
-    layer.cornerRadius = host.layer.cornerRadius
+    layer.cornerRadius =
+      typeof view.borderRadius === 'number' ? view.borderRadius : host.layer.cornerRadius
     if (current) {
       const model = values(current)
       layer.colors = model.colors
@@ -59,9 +60,13 @@ export function iosGradient(view: View, type: GradientType): GradientPainter {
   }
   view.on('loaded', attach)
   view.on('layoutChanged', attach)
+  view.style.on('borderTopLeftRadiusChange', attach)
 
   return {
     paint(frame) {
+      layer.speed = 1
+      layer.timeOffset = 0
+      layer.beginTime = 0
       current = frame
       generation++
       for (const key of keys) layer.removeAnimationForKey(`jolt:gradient:${key}`)
@@ -73,7 +78,14 @@ export function iosGradient(view: View, type: GradientType): GradientPainter {
       attach()
       const sampled = frames.map(values)
       const now = CACurrentMediaTime()
+      const parentTime = () =>
+        layer.superlayer?.convertTimeFromLayer(CACurrentMediaTime(), null) ??
+        CACurrentMediaTime()
       CATransaction.begin()
+      CATransaction.setDisableActions(true)
+      layer.speed = 1
+      layer.timeOffset = 0
+      layer.beginTime = layer.superlayer?.convertTimeFromLayer(now, null) ?? now
       if (timing.repeat !== Infinity)
         CATransaction.setCompletionBlock(() => {
           if (instance === generation) onEnd(true)
@@ -83,7 +95,7 @@ export function iosGradient(view: View, type: GradientType): GradientPainter {
         animation.values = NSArray.arrayWithArray(sampled.map((value) => value[key]))
         animation.keyTimes = NSArray.arrayWithArray(times as number[])
         animation.duration = Math.max(timing.duration, 1) / 1000
-        animation.beginTime = layer.convertTimeFromLayer(now + timing.delay / 1000, null)
+        animation.beginTime = Math.max(0.000001, timing.delay / 1000)
         animation.fillMode = kCAFillModeBackwards
         if (timing.repeat > 0) {
           animation.autoreverses = timing.reverse
@@ -95,6 +107,15 @@ export function iosGradient(view: View, type: GradientType): GradientPainter {
       }
       CATransaction.commit()
       return {
+        control(elapsed, paused) {
+          if (instance !== generation) return
+          CATransaction.begin()
+          CATransaction.setDisableActions(true)
+          layer.speed = paused ? 0 : 1
+          layer.timeOffset = paused ? elapsed / 1000 : 0
+          layer.beginTime = paused ? 0 : parentTime() - elapsed / 1000
+          CATransaction.commit()
+        },
         cancel() {
           if (instance !== generation) return
           generation++
@@ -107,6 +128,7 @@ export function iosGradient(view: View, type: GradientType): GradientPainter {
       generation++
       view.off('loaded', attach)
       view.off('layoutChanged', attach)
+      view.style.off('borderTopLeftRadiusChange', attach)
       layer.removeAllAnimations()
       layer.removeFromSuperlayer()
     },

package/src/engine.ts

@@ -457,11 +457,17 @@ export class ViewAnimation implements PlaybackAnimation {
       createClock(() => driver.now())
     if (this._paused) this.clock.pause()
     this.view.on('unloaded', this.unloaded)
-    this.haptics = playHaptics(this.view, tracks, this.haptic, driver, now, () =>
-      this.time(),
-    )
-    if (this._paused) this.haptics?.pause()
     for (const entry of this.entries) this.playEntry(entry)
+    // Register discrete feedback after the visual animators. Android dispatches
+    // these callbacks in registration order within a frame: feedback should see
+    // that frame's updated pose, not the preceding frame's position.
+    // Scale-zero native playback may already have completed synchronously.
+    if (!this.settled) {
+      this.haptics = playHaptics(this.view, tracks, this.haptic, driver, now, () =>
+        this.time(),
+      )
+      if (this._paused) this.haptics?.pause()
+    }
     if (this.pendingProgress !== undefined) {
       const progress = this.pendingProgress
       this.pendingProgress = undefined

package/src/gradient-binding.ts

@@ -0,0 +1,158 @@
+import { parseColor, type ColorValue } from './color.js'
+import { reducedMotion } from './config.js'
+import {
+  isDerived,
+  valueSource,
+  type DerivedValue,
+  type DerivedColor,
+} from './motion-value.js'
+import type { GradientFrame } from './gradient.js'
+
+export interface GradientBindings {
+  colors?: readonly (ColorValue | DerivedColor)[]
+  stops?: readonly (number | DerivedValue)[]
+  angle?: number | DerivedValue
+  center?: { readonly x?: number | DerivedValue; readonly y?: number | DerivedValue }
+  radius?: number | DerivedValue
+}
+
+export type GradientComponent =
+  'angle' | 'x' | 'y' | 'radius' | `color:${number}` | `stop:${number}`
+export type GradientSource = ReturnType<typeof valueSource>
+export type GradientComponentValue = number | GradientSource
+export type GradientPatch = Map<GradientComponent, GradientComponentValue>
+
+export function cloneFrame(frame: GradientFrame): GradientFrame {
+  return { ...frame, colors: [...frame.colors], stops: [...frame.stops] }
+}
+
+export function put(frame: GradientFrame, key: GradientComponent, value: number) {
+  if (key.startsWith('color:')) frame.colors[Number(key.slice(6))] = value
+  else if (key.startsWith('stop:')) frame.stops[Number(key.slice(5))] = value
+  else frame[key as 'angle' | 'x' | 'y' | 'radius'] = value
+}
+
+export function take(frame: GradientFrame, key: GradientComponent) {
+  if (key.startsWith('color:')) return frame.colors[Number(key.slice(6))]!
+  if (key.startsWith('stop:')) return frame.stops[Number(key.slice(5))]!
+  return frame[key as 'angle' | 'x' | 'y' | 'radius']
+}
+
+/** Validate structural/static inputs before touching any existing owner. */
+export function gradientPatch(values: GradientBindings, count: number): GradientPatch {
+  if (!values || typeof values !== 'object' || Array.isArray(values))
+    throw new TypeError('Gradient values must be an object.')
+  const patch: GradientPatch = new Map()
+  const add = (key: GradientComponent, value: unknown, color = false) => {
+    if (value === undefined) return
+    if (isDerived(value)) patch.set(key, valueSource(value, color))
+    else if (color) patch.set(key, parseColor(value as ColorValue))
+    else {
+      if (typeof value !== 'number' || !Number.isFinite(value))
+        throw new RangeError(`Invalid gradient ${key}: ${String(value)}.`)
+      if (key === 'radius' && value < 0)
+        throw new RangeError('Gradient radius must not be negative.')
+      if (key.startsWith('stop:') && (value < 0 || value > 1))
+        throw new RangeError('Gradient stops must be from 0 to 1.')
+      patch.set(key, value)
+    }
+  }
+  if (values.colors !== undefined) {
+    if (
+      !Array.isArray(values.colors) ||
+      values.colors.length < 2 ||
+      values.colors.length > 8
+    )
+      throw new RangeError('A gradient needs between two and eight colors.')
+    count = values.colors.length
+    Array.from(values.colors).forEach((value, i) => {
+      if (value === undefined) throw new TypeError('Gradient colors cannot be empty.')
+      add(`color:${i}`, value, true)
+    })
+  }
+  if (values.stops !== undefined) {
+    if (!Array.isArray(values.stops) || values.stops.length !== count)
+      throw new RangeError('Gradient stops need one value per color.')
+    Array.from(values.stops).forEach((value, i) => {
+      if (value === undefined) throw new TypeError('Gradient stops cannot be empty.')
+      add(`stop:${i}`, value)
+    })
+    if (
+      values.stops.every((value) => typeof value === 'number') &&
+      values.stops.some((value, i) => i > 0 && value < (values.stops![i - 1] as number))
+    )
+      throw new RangeError('Gradient stops must be ordered without going back.')
+  } else if (values.colors !== undefined) {
+    // Preserve the concrete API's rule: replacing colors resets unspecified stops.
+    values.colors.forEach((_, i) => patch.set(`stop:${i}`, i / (count - 1)))
+  }
+  add('angle', values.angle)
+  if (
+    values.center !== undefined &&
+    (!values.center || typeof values.center !== 'object')
+  )
+    throw new TypeError('Gradient center needs x/y components.')
+  add('x', values.center?.x)
+  add('y', values.center?.y)
+  add('radius', values.radius)
+  return patch
+}
+
+export interface GradientBase {
+  at(delta: number): GradientFrame
+  remaining: number
+  elapsed(): number
+}
+
+/** Native windows share a source clock. Only setup/commands/window boundaries enter JS. */
+export function gradientProgram(base: GradientBase, bindings: GradientPatch) {
+  const roots = new Map<object, ReturnType<GradientSource['snapshot']>>()
+  for (const value of bindings.values())
+    if (typeof value !== 'number' && !roots.has(value.identity))
+      roots.set(value.identity, value.snapshot())
+  const moving = [...roots.values()].filter((state) => state.running)
+  const remaining = Math.max(
+    base.remaining,
+    ...moving.map((state) => state.track.end - state.elapsed),
+    0,
+  )
+  const duration = Math.min(4000, remaining)
+  const anchor = moving[0]
+  const elapsed = anchor
+    ? () => Math.max(0, anchor.time() - anchor.elapsed)
+    : base.elapsed
+  const reduced = reducedMotion()
+  const at = (delta: number) => {
+    const frame = cloneFrame(base.at(delta))
+    for (const [key, source] of bindings) {
+      if (typeof source === 'number') {
+        put(frame, key, source)
+        continue
+      }
+      const state = roots.get(source.identity)!
+      const geometry = key === 'angle' || key === 'x' || key === 'y' || key === 'radius'
+      const input =
+        reduced && geometry && state.running
+          ? state.track.to
+          : state.running
+            ? state.track.valueAt(state.elapsed + delta)
+            : state.value
+      const value = source.read(input)
+      if (!Number.isFinite(value))
+        throw new RangeError(`Nonfinite gradient binding: ${key}.`)
+      put(frame, key, value)
+    }
+    // Project the complete vector without sorting colors. Spring overshoot may
+    // merge adjacent stops; their identity and order are retained.
+    frame.radius = Math.max(0, frame.radius)
+    frame.stops = frame.stops.map((stop) => Math.min(1, Math.max(0, stop)))
+    for (let i = 1; i < frame.stops.length; i++)
+      frame.stops[i] = Math.max(frame.stops[i - 1]!, frame.stops[i]!)
+    return frame
+  }
+  const current = at(0)
+  const steps = Math.max(1, Math.ceil((duration * 60) / 1000))
+  const times = Array.from({ length: steps + 1 }, (_, i) => i / steps)
+  const frames = times.map((time) => at(time * duration))
+  return { current, frames, times, duration, remaining, elapsed, at }
+}