@rafaelaugusto/jolt 0.1.0-beta.8 → 0.1.0-rc.1

package/src/sensors/index.ts

@@ -0,0 +1,246 @@
+import { Application, Trace } from '@nativescript/core'
+import { onReducedMotion, reducedMotion } from '../config.js'
+import {
+  motionValue,
+  springValue,
+  liveValueInput,
+  type DerivedValue,
+  type SpringValue,
+} from '../motion-value.js'
+import type { MotionScope } from '../motion-scope.js'
+import { createSensorDriver, rememberSensorDriver, type SensorDriver } from './native.js'
+
+export type SensorKind = 'rotation' | 'gravity'
+export type SensorStatus =
+  | 'idle'
+  | 'starting'
+  | 'active'
+  | 'paused'
+  | 'unavailable'
+  | 'error'
+  | 'replaying'
+  | 'disposed'
+export interface SensorOptions {
+  /** Milliseconds; 'auto' requests the display interval. Hardware may deliver less often. Minimum 5 ms. */
+  interval?: number | 'auto'
+  /** Right-handed x right, y up, z out of the screen. Defaults to interface coordinates. */
+  coordinates?: 'device' | 'interface'
+  /** Decorative motion stops sampling under Reduce Motion by default. */
+  reducedMotion?: 'pause' | 'continue'
+  scope?: MotionScope
+  /** Availability/lifecycle boundaries only. Never a callback for every reading. */
+  onStatus?: (status: SensorStatus) => void
+}
+export interface SensorSnapshot {
+  status: SensorStatus
+  available: boolean
+  error: string | null
+  /** Monotonic hardware timestamp, milliseconds since boot; not a wall-clock date. */
+  timestamp: number | null
+  samples: number
+  frames: number
+  callbacks: number
+  processingMs: number
+  interval: number
+  values: number[]
+}
+interface SensorBase {
+  readonly kind: SensorKind
+  readonly status: SensorStatus
+  readonly available: boolean
+  readonly paused: boolean
+  readonly disposed: boolean
+  /** Read on demand; installs no JS polling. Rotation values are radians, then quaternion xyzw. */
+  snapshot(): SensorSnapshot
+  pause(): void
+  play(): void
+  dispose(): void
+}
+export interface RotationSensor extends SensorBase {
+  readonly kind: 'rotation'
+  /** Relative extrinsic XYZ angles (equivalently intrinsic ZYX), radians. Map to degrees for Jolt rotation. */
+  readonly x: DerivedValue
+  readonly y: DerivedValue
+  readonly z: DerivedValue
+  /** Unit quaternion xyzw; prefer quaternion interpolation for full rotations. */
+  readonly quaternion: Readonly<{
+    x: DerivedValue
+    y: DerivedValue
+    z: DerivedValue
+    w: DerivedValue
+  }>
+  /** Set the current device pose as the identity rotation at the next reading. */
+  recenter(): void
+}
+export interface GravitySensor extends SensorBase {
+  readonly kind: 'gravity'
+  /** Downward gravitational acceleration in m/s²; a flat, face-up phone reports z ≈ -9.80665. */
+  readonly x: DerivedValue
+  readonly y: DerivedValue
+  readonly z: DerivedValue
+}
+export type Sensor = RotationSensor | GravitySensor
+export function sensor(kind: 'rotation', options?: SensorOptions): RotationSensor
+export function sensor(kind: 'gravity', options?: SensorOptions): GravitySensor
+export function sensor(kind: SensorKind, options?: SensorOptions): Sensor
+export function sensor(kind: SensorKind, options: SensorOptions = {}): Sensor {
+  if (kind !== 'rotation' && kind !== 'gravity')
+    throw new TypeError('sensor() supports rotation and gravity.')
+  if (!options || typeof options !== 'object')
+    throw new TypeError('Expected sensor options.')
+  const interval = options.interval ?? 'auto'
+  if (
+    interval !== 'auto' &&
+    (!Number.isFinite(interval) || interval < 5 || interval > 1000)
+  )
+    throw new RangeError('Sensor interval must be auto or 5–1000 milliseconds.')
+  const coordinates = options.coordinates ?? 'interface'
+  if (!['device', 'interface'].includes(coordinates))
+    throw new TypeError('Invalid sensor coordinates.')
+  if (
+    options.reducedMotion !== undefined &&
+    !['pause', 'continue'].includes(options.reducedMotion)
+  )
+    throw new TypeError('Invalid reduced-motion sensor policy.')
+  if (options.onStatus !== undefined && typeof options.onStatus !== 'function')
+    throw new TypeError('onStatus must be a function.')
+  if (options.scope?.disposed || options.scope?.suspended)
+    throw new Error('Sensor scope must be active.')
+  const nodes: SpringValue[] = []
+  const releases: (() => void)[] = []
+  let native: SensorDriver | undefined,
+    ended = false,
+    held = false,
+    background = false
+  let lastStatus: SensorStatus | undefined
+  const demand = new Set<number>()
+  const blocked = () =>
+    held || background || (options.reducedMotion !== 'continue' && reducedMotion())
+  const changed = () => {
+    if (!native || ended) return
+    const status = native.snapshot().status
+    for (const value of nodes)
+      liveValueInput(value).active(
+        status === 'active' || status === 'replaying' || status === 'starting',
+      )
+    if (status !== lastStatus) {
+      lastStatus = status
+      try {
+        options.onStatus?.(status)
+      } catch (error) {
+        Trace.write(
+          `Jolt sensor status listener failed: ${String(error)}`,
+          Trace.categories.Error,
+          Trace.messageType.error,
+        )
+      }
+    }
+  }
+  const update = () => {
+    native?.enabled(demand.size > 0 && !blocked(), blocked())
+    changed()
+  }
+  const suspend = () => {
+    background = true
+    update()
+  }
+  const resume = () => {
+    background = false
+    update()
+  }
+  try {
+    for (let i = 0; i < (kind === 'rotation' ? 7 : 3); i++)
+      nodes.push(
+        springValue(motionValue(kind === 'rotation' && i === 6 ? 1 : 0), { duration: 0 }),
+      )
+    native = createSensorDriver(
+      kind,
+      { interval: interval === 'auto' ? 0 : interval, coordinates },
+      nodes,
+      changed,
+    )
+    nodes.forEach((value, i) =>
+      releases.push(
+        liveValueInput(value).demand((active) => {
+          if (active) demand.add(i)
+          else demand.delete(i)
+          update()
+        }),
+      ),
+    )
+    releases.push(onReducedMotion(update))
+    Application.on(Application.suspendEvent, suspend)
+    Application.on(Application.resumeEvent, resume)
+    releases.push(() => {
+      Application.off(Application.suspendEvent, suspend)
+      Application.off(Application.resumeEvent, resume)
+    })
+    const source = {
+      kind,
+      x: nodes[0]!,
+      y: nodes[1]!,
+      z: nodes[2]!,
+      ...(kind === 'rotation'
+        ? {
+            quaternion: Object.freeze({
+              x: nodes[3]!,
+              y: nodes[4]!,
+              z: nodes[5]!,
+              w: nodes[6]!,
+            }),
+            recenter: () => {
+              if (!ended) native!.recenter()
+            },
+          }
+        : {}),
+      get status() {
+        return ended ? ('disposed' as const) : native!.snapshot().status
+      },
+      get available() {
+        return native!.snapshot().available
+      },
+      get paused() {
+        return held
+      },
+      get disposed() {
+        return ended
+      },
+      snapshot() {
+        return {
+          ...native!.snapshot(),
+          ...(ended ? { status: 'disposed' as const } : {}),
+        }
+      },
+      pause() {
+        if (!ended) {
+          held = true
+          update()
+        }
+      },
+      play() {
+        if (!ended) {
+          if (native!.snapshot().status === 'error') native!.enabled(false, true)
+          held = false
+          update()
+        }
+      },
+      dispose() {
+        if (ended) return
+        ended = true
+        native!.dispose()
+        releases.splice(0).forEach((release) => release())
+        nodes.forEach((value) => value.dispose())
+      },
+    } as Sensor
+    rememberSensorDriver(source, native)
+    options.scope?.add(source)
+    changed()
+    return source
+  } catch (error) {
+    ended = true
+    native?.dispose()
+    releases.forEach((release) => release())
+    nodes.forEach((value) => value.dispose())
+    throw error
+  }
+}

package/src/sensors/native.ts

@@ -0,0 +1,72 @@
+import { Application, isIOS } from '@nativescript/core'
+import { nativeLiveNode } from '../live-spring-driver.js'
+import { liveValueInput, type SpringValue } from '../motion-value.js'
+import type { SensorKind, SensorSnapshot } from './index.js'
+export interface SensorDriver {
+  enabled(active: boolean, paused: boolean): void
+  snapshot(): SensorSnapshot
+  recenter(): void
+  replay(trace: string): void
+  dispose(): void
+}
+const drivers = new WeakMap<object, SensorDriver>()
+export function rememberSensorDriver(source: object, driver: SensorDriver) {
+  drivers.set(source, driver)
+}
+export function sensorDriver(source: { disposed: boolean }): SensorDriver {
+  const driver = drivers.get(source)
+  if (!driver || source.disposed) throw new Error('Expected a live Jolt sensor.')
+  return driver
+}
+export type SensorFactory = (
+  kind: SensorKind,
+  options: { interval: number; coordinates: string },
+  nodes: readonly SpringValue[],
+  changed: () => void,
+) => SensorDriver
+let override: SensorFactory | undefined
+export function setSensorFactory(factory: SensorFactory | undefined) {
+  override = factory
+}
+export const createSensorDriver: SensorFactory = (kind, options, values, changed) => {
+  if (override) return override(kind, options, values, changed)
+  const nodes = values.map((value) => nativeLiveNode(liveValueInput(value).node))
+  if (isIOS) {
+    if (typeof JoltSensorSource === 'undefined')
+      throw new Error('Rebuild the native app to use sensor().')
+    const native = JoltSensorSource.createOptionsOnState(
+      kind,
+      JSON.stringify(options),
+      changed,
+    )
+    nodes.forEach((node, index) => native.connectIndex(node as JoltLiveSpring, index))
+    return {
+      enabled: (active, paused) => native.setEnabledPaused(active, paused),
+      snapshot: () => JSON.parse(native.snapshot()),
+      recenter: () => native.recenter(),
+      replay: (trace) => native.replay(trace),
+      dispose: () => native.dispose(),
+    }
+  }
+  if (
+    typeof org === 'undefined' ||
+    typeof org.rafaelaugusto.jolt.SensorSource !== 'function'
+  )
+    throw new Error('Rebuild the native app to use sensor().')
+  const native = new org.rafaelaugusto.jolt.SensorSource(
+    Application.android.context,
+    kind,
+    JSON.stringify(options),
+    new org.rafaelaugusto.jolt.SensorSource.Listener({ changed }),
+  )
+  nodes.forEach((node, index) =>
+    native.connect(node as org.rafaelaugusto.jolt.LiveSpring, index),
+  )
+  return {
+    enabled: (active, paused) => native.setEnabled(active, paused),
+    snapshot: () => JSON.parse(native.snapshot()),
+    recenter: () => native.recenter(),
+    replay: (trace) => native.replay(trace),
+    dispose: () => native.dispose(),
+  }
+}

package/src/sequence.ts

@@ -10,7 +10,12 @@ import {
   stopView,
   type Animation,
 } from './engine.js'
-import { createClock } from './playback.js'
+import { createClock, registerPlayback, playbackSource } from './playback.js'
+import {
+  isMotionValue,
+  type MotionValue,
+  type ValueAnimationOptions,
+} from './motion-value.js'
 import type { PresetName } from './presets.js'
 import { writeValue, type Property } from './properties.js'
 import type { SpringName } from './transition.js'
@@ -28,6 +33,34 @@ export type Step =
     ]
   | (() => Animation)
 
+/** A participant that can genuinely freeze and continue, rather than restart. */
+export interface PlayableAnimation extends Animation {
+  pause(): void
+  play(): void
+  readonly paused: boolean
+  readonly duration?: number
+}
+
+export type TimelineStep =
+  | Exclude<Step, () => Animation>
+  | readonly [
+      MotionValue,
+      number | readonly (number | null)[],
+      ((ValueAnimationOptions & { at?: SequencePosition }) | SpringName)?,
+    ]
+  | { readonly at?: SequencePosition; readonly run: () => PlayableAnimation }
+  | (() => PlayableAnimation)
+
+export interface TimelineAnimation extends PlayableAnimation {
+  /** Unknown until every step has activated and every participant reports a duration. */
+  readonly duration: number | undefined
+}
+
+/** Overlapping steps with a shared pause/resume control, including pending launches. */
+export function timeline(steps: readonly TimelineStep[]): TimelineAnimation {
+  return compose(steps, true) as TimelineAnimation
+}
+
 /**
  * By default a step starts once the previous one looks done. `at` can overlap
  * that arrival, share the previous start, or select an absolute timeline time.
@@ -44,26 +77,54 @@ export type Step =
  * ```
  */
 export function sequence(steps: readonly Step[]): Animation {
+  return compose(steps, false)
+}
+
+function compose(
+  steps: readonly TimelineStep[] | readonly Step[],
+  controlled: boolean,
+): Animation {
   const prepared = steps.map((step) => {
     if (typeof step === 'function') return { step, position: undefined }
-    const [target, animation, options] = step
+    if (!Array.isArray(step)) {
+      const descriptor = step as { at?: SequencePosition; run: () => PlayableAnimation }
+      if (typeof descriptor.run !== 'function')
+        throw new TypeError('A timeline step needs a run() factory.')
+      return { step: descriptor.run, position: parsePosition(descriptor.at) }
+    }
+    const [target, animation, options] = step as Exclude<
+      TimelineStep,
+      Function | { run: () => PlayableAnimation }
+    >
     if (typeof options !== 'object' || options === null)
       return { step, position: undefined }
     const { at, ...transition } = options
     const position = parsePosition(at)
     return { step: [target, animation, transition] as Step, position }
   })
-  applyStartingValues(prepared.map(({ step }) => step))
+  applyStartingValues(
+    prepared
+      .map(({ step }) => step as Step)
+      .filter((step) => typeof step === 'function' || !isMotionValue(step[0])),
+  )
 
   const driver = getDriver()
   const slowdown = 1 / timeScale()
   // Absolute positions share the platform clock, including Android duration scale.
-  const clock = prepared.some(({ position }) => typeof position === 'number')
-    ? (driver.clock?.(Infinity) ?? createClock(() => driver.now()))
-    : undefined
+  const clock =
+    controlled || prepared.some(({ position }) => typeof position === 'number')
+      ? (driver.clock?.(Infinity) ?? createClock(() => driver.now()))
+      : undefined
   const started: Animation[] = []
   const cancellations = new Set<() => void>()
   let stopped = false
+  let paused = false
+  let settled = false
+  let completed = false
+  let changed = () => {}
+  const resumeChildren = new Set<PlayableAnimation>()
+  const waits = new Set<{ at: number; fire(): void; cancel(): void; schedule(): void }>()
+  const time = () => clock?.time() ?? 0
   let resolveScheduled!: () => void
   let rejectScheduled!: (reason: unknown) => void
   const scheduled = new Promise<void>((resolve, reject) => {
@@ -77,28 +138,55 @@ export function sequence(steps: readonly Step[]): Animation {
       position,
       onStart: new Set<() => void>(),
       animation: undefined as Animation | undefined,
+      start: undefined as number | undefined,
     }
   })
   const cancelSchedule = () => {
     for (const cancel of cancellations) cancel()
     cancellations.clear()
-    clock?.cancel()
+    for (const wait of waits) wait.cancel()
+    waits.clear()
+    if (!controlled || stopped || settled) clock?.cancel()
   }
   const fail = (error: unknown) => {
     if (stopped) return
     stopped = true
+    settled = true
     cancelSchedule()
     states.forEach((state) => state.onStart.clear())
     started.forEach((child) => child.stop())
+    changed()
     rejectScheduled(error)
   }
   const launch = (index: number) => {
     const state = states[index]!
     if (stopped || state.animation) return
+    if (paused) {
+      wait(0, () => launch(index))
+      return
+    }
     try {
       const step = state.step
-      const child = typeof step === 'function' ? step() : animate(...step)
+      const child =
+        typeof step === 'function'
+          ? step()
+          : (animate as (...args: any[]) => Animation)(...(step as any[]))
+      if (controlled && !isPlayable(child)) {
+        child?.stop?.()
+        throw new TypeError(
+          'A timeline participant must expose pause(), play() and paused; use sequence() for non-playable effects.',
+        )
+      }
       state.animation = child
+      state.start = time()
+      if (controlled) {
+        try {
+          const playback = playbackSource(child).read()
+          if (playback.ready) state.start = Math.max(0, time() - playback.time)
+        } catch {
+          /* A custom playable participant can omit a clock. */
+        }
+      }
       started.push(child)
       // Observe setup failures immediately, even while other steps are still
       // scheduled. Nested sequences can reject before this one reaches arrival.
@@ -110,25 +198,51 @@ export function sequence(steps: readonly Step[]): Animation {
         cancelSchedule()
         resolveScheduled()
       }
+      changed()
     } catch (error) {
       fail(error)
     }
   }
   const wait = (ms: number, callback: () => void) => {
     if (stopped) return
-    if (ms <= 0) {
-      callback()
+    if (!controlled) {
+      if (ms <= 0) {
+        callback()
+        return
+      }
+      let cancel = () => {}
+      let fired = false
+      const off = driver.after(ms, () => {
+        fired = true
+        cancellations.delete(cancel)
+        if (!stopped) callback()
+      })
+      cancel = off
+      if (!fired) cancellations.add(cancel)
       return
     }
-    let cancel = () => {}
-    let fired = false
-    const off = driver.after(ms, () => {
-      fired = true
-      cancellations.delete(cancel)
-      if (!stopped) callback()
-    })
-    cancel = off
-    if (!fired) cancellations.add(cancel)
+    let off = () => {}
+    const waiting = {
+      at: time() + Math.max(0, ms),
+      fire() {
+        off()
+        waits.delete(waiting)
+        if (!stopped) callback()
+      },
+      cancel() {
+        off()
+        off = () => {}
+      },
+      schedule() {
+        waiting.cancel()
+        if (paused || stopped) return
+        const remaining = waiting.at - time()
+        if (remaining <= 0) waiting.fire()
+        else off = driver.after(remaining, waiting.fire)
+      },
+    }
+    waits.add(waiting)
+    waiting.schedule()
   }
 
   for (let index = 0; index < states.length; index++) {
@@ -214,7 +328,11 @@ export function sequence(steps: readonly Step[]): Animation {
   const arrived = scheduled.then(() => Promise.all(started.map(arrivalOf)))
   const finished = arrived.then(async () => {
     const results = await Promise.all(started.map((animation) => animation.finished))
-    return !stopped && results.length === steps.length && results.every(Boolean)
+    completed = !stopped && results.length === steps.length && results.every(Boolean)
+    settled = true
+    clock?.cancel()
+    changed()
+    return completed
   })
 
   const animation: Animation = {
@@ -222,13 +340,69 @@ export function sequence(steps: readonly Step[]): Animation {
     stop() {
       if (stopped) return
       stopped = true
+      settled = true
       cancelSchedule()
       states.forEach((state) => state.onStart.clear())
       resolveScheduled()
       started.forEach((animation) => animation.stop())
+      resumeChildren.clear()
+      changed()
     },
     then: (onfulfilled, onrejected) => finished.then(onfulfilled, onrejected),
   }
+  if (controlled) {
+    const duration = () => {
+      if (pending) return undefined
+      let total = 0
+      for (const state of states) {
+        const child = state.animation as PlayableAnimation | undefined
+        if (!child || child.duration === undefined) return undefined
+        try {
+          if (!playbackSource(child).read().ready) return undefined
+        } catch {
+          /* custom playable */
+        }
+        total = Math.max(total, (state.start ?? 0) + child.duration)
+      }
+      return total
+    }
+    Object.defineProperties(animation, {
+      paused: { get: () => paused },
+      duration: { get: duration },
+    })
+    Object.assign(animation, {
+      pause() {
+        if (paused || settled) return
+        paused = true
+        clock?.pause()
+        for (const wait of waits) wait.cancel()
+        for (const child of started as PlayableAnimation[]) {
+          if (!child.paused) {
+            resumeChildren.add(child)
+            child.pause()
+          }
+        }
+        changed()
+      },
+      play() {
+        if (!paused || settled) return
+        paused = false
+        clock?.play()
+        for (const child of resumeChildren) child.play()
+        resumeChildren.clear()
+        for (const wait of [...waits]) wait.schedule()
+        changed()
+      },
+    })
+    changed = registerPlayback(animation, () => ({
+      time: time(),
+      duration: duration() ?? Infinity,
+      paused,
+      ready: duration() !== undefined,
+      settled,
+      completed,
+    }))
+  }
   setArrival(animation, arrived)
   return animation
 }
@@ -276,3 +450,18 @@ function applyStartingValues(steps: readonly Step[]) {
     }
   }
 }
+
+function isPlayable(animation: Animation): animation is PlayableAnimation {
+  const handle = animation as PlayableAnimation | undefined
+  return (
+    !!handle &&
+    typeof handle.pause === 'function' &&
+    typeof handle.play === 'function' &&
+    typeof handle.paused === 'boolean' &&
+    typeof handle.stop === 'function' &&
+    typeof handle.finished?.then === 'function' &&
+    typeof handle.finished?.catch === 'function' &&
+    (handle.duration === undefined ||
+      (typeof handle.duration === 'number' && handle.duration >= 0))
+  )
+}