@rafaelaugusto/jolt 0.1.0-beta.9 → 0.1.0-rc.2

package/src/testing/clock.ts

@@ -0,0 +1,128 @@
+import type { View } from '@nativescript/core'
+import type { Driver } from '../driver/index.js'
+import type { Property } from '../properties.js'
+import type { Track } from '../track.js'
+
+interface Playback {
+  view: View
+  track: Track
+  started: number
+  offset: number
+  held: boolean
+  handle?: unknown
+  end: (finished?: boolean) => void
+  done: boolean
+}
+
+/** Isolated test clock. Optional native tracks are held and sought at the exact logical time. */
+export class ReplayClock implements Driver {
+  private time = 0
+  private tracks = new Set<Playback>()
+  private timers = new Set<{ at: number; callback(): void }>()
+  private frames = new Set<() => void>()
+  constructor(
+    private native?: Driver,
+    private reduced = false,
+  ) {
+    if (native && !native.control)
+      throw new Error('Native replay requires a seekable driver.')
+  }
+  now = () => this.time
+  get resources() {
+    return this.tracks.size + this.timers.size + this.frames.size
+  }
+  frame(callback: () => void) {
+    this.frames.add(callback)
+    return () => {
+      this.frames.delete(callback)
+    }
+  }
+  after(ms: number, callback: () => void) {
+    const timer = { at: this.time + ms, callback }
+    this.timers.add(timer)
+    return () => {
+      this.timers.delete(timer)
+    }
+  }
+  play(
+    view: View,
+    track: Track,
+    started: number,
+    end: (finished?: boolean) => void,
+  ): Playback {
+    const playback: Playback = {
+      view,
+      track,
+      started,
+      offset: 0,
+      held: false,
+      end,
+      done: false,
+    }
+    if (this.native) {
+      playback.handle = this.native.play(view, track, this.native.now(), () => {})
+      this.native.control!(view, playback.handle, 0, true, 'pause')
+    }
+    this.tracks.add(playback)
+    return playback
+  }
+  elapsed(handle: unknown) {
+    const p = handle as Playback
+    return p.offset + (p.held ? 0 : this.time - p.started)
+  }
+  control(_view: View, handle: unknown, elapsed: number, paused: boolean) {
+    const p = handle as Playback
+    p.offset = elapsed
+    p.started = this.time
+    p.held = paused
+    this.native?.control!(p.view, p.handle, elapsed, true, 'seek')
+  }
+  stop(_view: View, handle: unknown) {
+    this.finish(handle as Playback, false)
+  }
+  private finish(p: Playback, completed: boolean) {
+    if (p.done) return
+    p.done = true
+    this.tracks.delete(p)
+    if (this.native) this.native.stop(p.view, p.handle)
+    p.end(completed)
+  }
+  presented(view: View, property: Property) {
+    return this.native?.presented(view, property)
+  }
+  sync(view: View, excluding?: Property) {
+    this.native?.sync?.(view, excluding)
+  }
+  reducedMotion() {
+    return this.reduced
+  }
+  advanceTo(at: number) {
+    if (!Number.isFinite(at) || at < this.time)
+      throw new RangeError('Replay time must be finite and monotonic.')
+    this.time = at
+    // No interpolation of missing frames: callbacks see the original elapsed gap.
+    for (const p of [...this.tracks]) {
+      this.native?.control!(p.view, p.handle, this.elapsed(p), true, 'seek')
+      if (!p.held && this.elapsed(p) >= p.track.end) this.finish(p, true)
+    }
+    for (const timer of [...this.timers]) {
+      if (timer.at <= at && this.timers.delete(timer)) timer.callback()
+    }
+    const frames = [...this.frames]
+    this.frames.clear()
+    for (const callback of frames) callback()
+  }
+  dispose() {
+    let error: unknown
+    for (const p of [...this.tracks]) {
+      try {
+        this.finish(p, false)
+      } catch (failure) {
+        error ??= failure
+      }
+    }
+    this.timers.clear()
+    this.frames.clear()
+    if (error) throw error
+  }
+}

package/src/testing/handoff-recorder.ts

@@ -0,0 +1,98 @@
+import {
+  isIOS,
+  Utils,
+  type ScrollView,
+  type EventData,
+  type TouchGestureEventData,
+} from '@nativescript/core'
+import { handoffIds, type HandoffIds } from './scroll-handoff.js'
+import type { TraceRecorder } from './trace.js'
+
+/** Opt-in raw OS contact capture, before recognizer arbitration. Only numeric window coordinates.
+ * The accepted engine baseline normalizes these inputs; this does not record OS recognition decisions.
+ */
+export function observeScrollHandoffInputs(
+  scroll: ScrollView,
+  recorder: Pick<TraceRecorder, 'input'>,
+  now: () => number,
+  ids: HandoffIds = handoffIds,
+): () => void {
+  let origin = 0,
+    previous = 0,
+    lastTime = 0,
+    contact = false
+  const changed = (raw: EventData) => {
+    const event = raw as TouchGestureEventData
+    const positions: number[] = []
+    if (isIOS) {
+      for (const pointer of event.getAllPointers()) {
+        const touch = pointer.ios as UITouch
+        if (touch.phase !== 3 && touch.phase !== 4 /* ended / cancelled */)
+          positions.push(touch.locationInView(null).y)
+      }
+    } else {
+      const native = event.android,
+        action = native.getActionMasked()
+      if (
+        action !== android.view.MotionEvent.ACTION_UP &&
+        action !== android.view.MotionEvent.ACTION_CANCEL
+      )
+        for (let i = 0; i < native.getPointerCount(); i++) {
+          if (
+            action === android.view.MotionEvent.ACTION_POINTER_UP &&
+            i === native.getActionIndex()
+          )
+            continue
+          positions.push(
+            Utils.layout.toDeviceIndependentPixels(
+              native.getRawY() - native.getY() + native.getY(i),
+            ),
+          )
+        }
+    }
+    const point = positions.length
+      ? positions.reduce((sum, y) => sum + y, 0) / positions.length
+      : previous
+    const time = now()
+    const begin = !contact && positions.length > 0 && event.action === 'down'
+    if (begin) {
+      contact = true
+      origin = previous = point
+      lastTime = time
+      recorder.input({
+        type: 'scroll',
+        id: ids.scroll,
+        offset: Math.max(0, scroll.verticalOffset),
+      })
+    }
+    if (!contact) return
+    const ended = !positions.length || event.action === 'cancel'
+    recorder.input({
+      type: 'gesture',
+      id: ids.sheet,
+      phase: begin
+        ? 'begin'
+        : !ended
+          ? 'move'
+          : event.action === 'cancel'
+            ? 'cancel'
+            : 'end',
+      x: 0,
+      y: point - origin,
+      velocityX: 0,
+      velocityY: ended ? 0 : ((point - previous) / Math.max(1, time - lastTime)) * 1000,
+      pointers: ended ? [] : Array.from({ length: positions.length }, (_, i) => i),
+    })
+    previous = point
+    lastTime = time
+    if (ended) contact = false
+  }
+  scroll.on('touch', changed)
+  let disposed = false
+  return () => {
+    if (!disposed) {
+      disposed = true
+      scroll.off('touch', changed)
+    }
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1,4 @@
+export * from './trace.js'
+export * from './replay.js'
+export { scrollHandoffTraceGraph, type HandoffIds } from './scroll-handoff.js'
+export { replaySensor, type SensorSample } from './sensors.js'

package/src/testing/native.ts

@@ -0,0 +1,386 @@
+import {
+  Application,
+  Device,
+  Screen,
+  GestureTypes,
+  isIOS,
+  Utils,
+  type View,
+  type PanGestureEventData,
+  type EventData,
+  type ScrollView,
+} from '@nativescript/core'
+import { animate } from '../animate.js'
+import { asRoot, bind, motionValue } from '../motion-value.js'
+import { drag, type Drag } from '../drag.js'
+import { motionScope } from '../motion-scope.js'
+import { getDriver, setDriver } from '../driver/index.js'
+import { reducedMotion, timeScale } from '../config.js'
+import { DragInput } from '../drag-input.js'
+import { onKeyboard } from '../keyboard.js'
+import { ReplayClock } from './clock.js'
+import { waitForPresentation } from './presentation.js'
+import { replayInteraction, type ReplayAdapter, type ReplayReport } from './replay.js'
+import {
+  parseTrace,
+  type InteractionTrace,
+  type TraceInput,
+  type TraceMotion,
+  type TraceState,
+  type TraceMetadata,
+  type TraceRecorder,
+} from './trace.js'
+
+export { ReplayClock }
+export { nativeScrollHandoffTraceGraph } from './scroll-handoff-native.js'
+export { observeScrollHandoffInputs } from './handoff-recorder.js'
+
+export const traceNow = () => getDriver().now()
+export const traceSettings = () => ({
+  timeScale: timeScale(),
+  reducedMotion: reducedMotion(),
+})
+export function traceMetadata(): TraceMetadata {
+  const screen = Screen.mainScreen
+  const refreshRate = isIOS
+    ? UIScreen.mainScreen.maximumFramesPerSecond
+    : (Application.android.foregroundActivity ?? Application.android.startActivity)
+        .getWindowManager()
+        .getDefaultDisplay()
+        .getRefreshRate()
+  return {
+    platform: isIOS ? 'ios' : 'android',
+    os: Device.osVersion,
+    model: Device.model,
+    refreshRate,
+    density: screen.scale,
+    width: screen.widthDIPs,
+    height: screen.heightDIPs,
+  }
+}
+
+/** Opt-in Core pan/environment capture. Pointer numbers are contact slots, never native handles. */
+export function observeTraceInputs(
+  view: View,
+  id: string,
+  recorder: Pick<TraceRecorder, 'input'>,
+  options: {
+    pan?: boolean
+    layout?: boolean
+    lifecycle?: boolean
+    keyboard?: boolean
+    scroll?: ScrollView
+  } = { pan: true },
+): () => void {
+  const off: (() => void)[] = [],
+    samples = new DragInput()
+  const on = (name: string, callback: (event: EventData) => void) => {
+    view.on(name, callback)
+    off.push(() => view.off(name, callback))
+  }
+  if (options.pan)
+    on('pan', (raw) => {
+      const event = raw as PanGestureEventData
+      if (event.state === 1) samples.reset()
+      const point = samples.read(event, view)
+      const count =
+        event.android?.current?.getPointerCount?.() ??
+        event.ios?.numberOfTouches ??
+        (event.state === 3 ? 0 : 1)
+      recorder.input({
+        type: 'gesture',
+        id,
+        phase: point.cancelled
+          ? 'cancel'
+          : event.state === 1
+            ? 'begin'
+            : event.state === 3
+              ? 'end'
+              : 'move',
+        x: point.x,
+        y: point.y,
+        velocityX: point.velocityX,
+        velocityY: point.velocityY,
+        pointers: Array.from({ length: Math.min(10, count) }, (_, index) => index),
+      })
+    })
+  if (options.layout)
+    on('layoutChanged', () => {
+      const location = view.getLocationInWindow(),
+        size = view.getActualSize()
+      if (location) recorder.input({ type: 'layout', id, ...location, ...size })
+    })
+  if (options.scroll) {
+    const scroll = options.scroll
+    const changed = () =>
+      recorder.input({ type: 'scroll', id, offset: scroll.verticalOffset })
+    scroll.on('scroll', changed)
+    off.push(() => scroll.off('scroll', changed))
+  }
+  if (options.keyboard)
+    off.push(
+      onKeyboard((state) => recorder.input({ type: 'keyboard', inset: state.height })),
+    )
+  if (options.lifecycle) {
+    const suspend = () => recorder.input({ type: 'lifecycle', state: 'suspend' })
+    const resume = () => recorder.input({ type: 'lifecycle', state: 'resume' })
+    Application.on(Application.suspendEvent, suspend)
+    Application.on(Application.resumeEvent, resume)
+    off.push(() => {
+      Application.off(Application.suspendEvent, suspend)
+      Application.off(Application.resumeEvent, resume)
+    })
+    on('unloaded', () => recorder.input({ type: 'lifecycle', state: 'unload' }))
+    on('loaded', () => recorder.input({ type: 'lifecycle', state: 'load' }))
+  }
+  let disposed = false
+  return () => {
+    if (!disposed) {
+      disposed = true
+      off.reverse().forEach((release) => release())
+    }
+  }
+}
+
+/** Same boundary as the native CI probe: no iOS model-layer fallback. */
+export function nativeTracePosition(view: View, axis: 'x' | 'y'): number {
+  if (isIOS) {
+    const layer = (view.nativeViewProtected as UIView).layer.presentationLayer()
+    if (!layer) throw new Error('Replay view has no native presentation layer.')
+    return Number(layer.valueForKeyPath(`transform.translation.${axis}`))
+  }
+  const native = view.nativeViewProtected as android.view.View
+  return Utils.layout.toDeviceIndependentPixels(
+    axis === 'x' ? native.getTranslationX() : native.getTranslationY(),
+  )
+}
+
+/** Dispatch normalized graph input, explicitly bypassing the OS recognizer. */
+export function replayPan(view: View, event: Extract<TraceInput, { type: 'gesture' }>) {
+  if (event.phase === 'begin') {
+    const touch = { eventName: 'touch', object: view, view, action: 'down' }
+    const observers = view.getGestureObservers?.(GestureTypes.touch)
+    if (observers?.length) {
+      for (const observer of [...observers]) observer.callback(touch as never)
+    } else view.notify(touch)
+  }
+  const data = {
+    eventName: 'pan',
+    object: view,
+    view,
+    state: { begin: 1, move: 2, end: 3, cancel: 0 }[event.phase],
+    deltaX: event.x,
+    deltaY: event.y,
+    // DragInput accepts this normalized structural payload on either platform.
+    ios: {
+      translationInView: () => ({ x: event.x, y: event.y }),
+      velocityInView: () => ({ x: event.velocityX, y: event.velocityY }),
+      numberOfTouches: event.pointers.length,
+    },
+  } as unknown as PanGestureEventData
+  const observers = view.getGestureObservers?.(GestureTypes.pan)
+  if (observers?.length) {
+    for (const observer of [...observers]) observer.callback(data)
+  } else view.notify(data)
+}
+
+export interface MotionTraceGraph extends ReplayAdapter {
+  /** Engine state for checkpoints recorded before handing them to native presentation probes. */
+  engineState(id: string): TraceState
+}
+
+/** Reference graph for interrupted springs and cancelled single-pointer drags. */
+export function motionTraceGraph(
+  motions: readonly TraceMotion[],
+  viewFor: (id: string) => View,
+  options: {
+    native?: boolean
+    /** Application-specific scroll/layout/keyboard routing. Unsupported events must throw. */
+    environment?: (event: TraceInput, graph: MotionTraceGraph) => void
+  } = {},
+): MotionTraceGraph {
+  const scope = motionScope()
+  let disposed = false
+  const nodes = new Map<
+    string,
+    {
+      config: TraceMotion
+      view: View
+      value: ReturnType<typeof motionValue>
+      drag?: Drag
+      settled: boolean
+      velocity: number
+      generation: number
+    }
+  >()
+  try {
+    for (const config of motions) {
+      const view = viewFor(config.id),
+        value = motionValue(config.initial)
+      const node = {
+        config,
+        view,
+        value,
+        settled: true,
+        velocity: 0,
+        generation: 0,
+        drag: undefined as Drag | undefined,
+      }
+      nodes.set(config.id, node)
+      scope.use(() => bind(view, { [config.axis]: value }))
+      if (config.kind === 'drag')
+        node.drag = scope.add(
+          drag(view, {
+            value,
+            axis: config.axis,
+            bounds:
+              config.axis === 'x'
+                ? { left: config.min, right: config.max }
+                : { top: config.min, bottom: config.max },
+            ...(config.snap.length ? { snap: config.snap } : {}),
+            onMove: (event) => {
+              node.velocity = config.axis === 'x' ? event.velocityX : event.velocityY
+            },
+            onCancel: () => {
+              node.velocity = 0
+            },
+          }),
+        )
+    }
+  } catch (error) {
+    scope.dispose()
+    throw error
+  }
+  const find = (id: string) => {
+    const node = nodes.get(id)
+    if (!node) throw new Error('Unknown replay view ID.')
+    return node
+  }
+  const graph: MotionTraceGraph = {
+    input(event) {
+      if (disposed) throw new Error('Replay graph is disposed.')
+      if (event.type === 'target') {
+        const node = find(event.id),
+          generation = ++node.generation
+        if (node.config.kind !== 'spring')
+          throw new Error('Target events require a spring motion.')
+        node.settled = false
+        const animation = scope.add(
+          animate(node.value, event.value, {
+            type: 'spring',
+            stiffness: node.config.stiffness,
+            damping: node.config.damping,
+            mass: node.config.mass,
+          }),
+        )
+        void animation.finished.then(() => {
+          if (generation === node.generation) node.settled = true
+        })
+      } else if (event.type === 'gesture') {
+        const node = find(event.id)
+        if (!node.drag) throw new Error('Gesture events require a drag motion.')
+        replayPan(node.view, event)
+      } else if (
+        event.type === 'lifecycle' &&
+        (event.state === 'suspend' || event.state === 'resume')
+      ) {
+        if (event.state === 'suspend') scope.suspend()
+        else scope.resume()
+      } else if (options.environment) options.environment(event, graph)
+      else throw new Error(`The reference graph has no adapter for ${event.type}.`)
+    },
+    engineState(id) {
+      const node = find(id)
+      return {
+        position: node.value.get(),
+        velocity: node.drag?.dragging
+          ? node.velocity
+          : asRoot(node.value).inspect().velocity,
+        settled: node.drag ? !node.drag.dragging && !node.drag.settling : node.settled,
+      }
+    },
+    read(id) {
+      const node = find(id),
+        state = graph.engineState(id)
+      return {
+        ...state,
+        position: options.native
+          ? nativeTracePosition(node.view, node.config.axis)
+          : state.position,
+      }
+    },
+    dispose() {
+      if (!disposed) {
+        disposed = true
+        scope.dispose()
+      }
+    },
+    resources: () =>
+      scope.size +
+      [...nodes.values()].reduce(
+        (sum, node) => sum + asRoot(node.value).inspect().resources,
+        0,
+      ),
+  }
+  return graph
+}
+
+let replaying = false
+/** Run in an isolated fixture. Installs the test driver temporarily and always restores it. */
+export async function replayWithDriver(
+  value: InteractionTrace | string,
+  create: (trace: InteractionTrace, random: () => number) => ReplayAdapter,
+  options: {
+    native?: boolean
+    signal?: { readonly aborted: boolean }
+    present?: () => Promise<void>
+  } = {},
+): Promise<ReplayReport> {
+  if (replaying) throw new Error('Only one isolated driver replay may run at a time.')
+  const trace = parseTrace(value),
+    previous = getDriver()
+  if (
+    timeScale() !== trace.settings.timeScale ||
+    reducedMotion() !== trace.settings.reducedMotion
+  )
+    throw new Error(
+      'Configure the isolated fixture to match the recorded timeScale and Reduced Motion settings first.',
+    )
+  const clock = new ReplayClock(
+    options.native ? previous : undefined,
+    trace.settings.reducedMotion,
+  )
+  const present =
+    options.present ??
+    (() => waitForPresentation((callback) => previous.frame(callback), options.signal))
+  replaying = true
+  setDriver(clock)
+  try {
+    return await replayInteraction(trace, {
+      signal: options.signal,
+      advanceTo: async (at) => {
+        clock.advanceTo(at)
+        if (options.native) await present()
+      },
+      create: (trace, random) => {
+        const adapter = create(trace, random)
+        return {
+          input: async (event) => {
+            await adapter.input(event)
+            if (options.native) await present()
+          },
+          read: (id) => adapter.read(id),
+          dispose: () => adapter.dispose(),
+          resources: () => adapter.resources() + clock.resources,
+        }
+      },
+    })
+  } finally {
+    try {
+      clock.dispose()
+    } finally {
+      setDriver(previous)
+      replaying = false
+    }
+  }
+}

package/src/testing/presentation.ts

@@ -0,0 +1,46 @@
+type Frame = (callback: () => void) => () => void
+
+/**
+ * NativeScript's first RAF outside a frame is a macrotask, not a display tick.
+ * Three nested callbacks cross at least two display ticks before reading a held
+ * presentation. Never poll for an expected value or retry a failed assertion.
+ */
+export function waitForPresentation(
+  frame: Frame,
+  signal?: { readonly aborted: boolean },
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let cancel = () => {},
+      callbacks = 0,
+      done = false
+    const finish = (error?: Error) => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      cancel()
+      if (error) reject(error)
+      else resolve()
+    }
+    const timer = setTimeout(
+      () => finish(new Error('Sampling presentation timed out after 1500 ms.')),
+      1500,
+    )
+    const next = () => {
+      if (signal?.aborted) {
+        finish(new Error('Sampling check cancelled.'))
+        return
+      }
+      try {
+        cancel = frame(() => {
+          if (done) return
+          if (signal?.aborted) finish(new Error('Sampling check cancelled.'))
+          else if (++callbacks === 3) finish()
+          else next()
+        })
+      } catch (error) {
+        finish(error instanceof Error ? error : new Error(String(error)))
+      }
+    }
+    next()
+  })
+}