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

package/src/testing/replay.ts

@@ -0,0 +1,149 @@
+import {
+  parseTrace,
+  traceRandom,
+  type InteractionTrace,
+  type TraceInput,
+  type TraceState,
+} from './trace.js'
+
+export interface ReplayAdapter {
+  input(event: TraceInput): void | Promise<void>
+  read(id: string): TraceState
+  dispose(): void | Promise<void>
+  /** Owned subscriptions/handles remaining after dispose; must be zero. */
+  resources(): number
+}
+export interface ReplayObservation {
+  at: number
+  id: string
+  expected: TraceState
+  observed: TraceState
+  positionError: number
+  velocityError: number
+  passed: boolean
+}
+export interface ReplayReport {
+  passed: boolean
+  observations: ReplayObservation[]
+  errors: string[]
+  remainingResources: number
+  trace: InteractionTrace
+  /** A compact expected/observed SVG, useful as a failure artifact. */
+  plot: string
+}
+export interface ReplayOptions {
+  advanceTo(at: number): void | Promise<void>
+  /** Construct fresh state for each replay. Include the supplied seed in random effects. */
+  create(trace: InteractionTrace, random: () => number): ReplayAdapter
+  signal?: { readonly aborted: boolean }
+}
+
+/** Ordered replay at original timestamps. A 250 ms gap advances once, never fifteen fake frames. */
+export async function replayInteraction(
+  value: InteractionTrace | string,
+  options: ReplayOptions,
+): Promise<ReplayReport> {
+  const trace = parseTrace(value)
+  const observations: ReplayObservation[] = [],
+    errors: string[] = []
+  let adapter: ReplayAdapter | undefined,
+    remainingResources = 0
+  try {
+    if (!trace.entries.some((entry) => 'expected' in entry))
+      throw new Error('A regression trace needs at least one checkpoint.')
+    adapter = options.create(trace, traceRandom(trace.seed))
+    let previous = -1
+    for (const entry of trace.entries) {
+      if (options.signal?.aborted) throw new Error('Replay cancelled.')
+      if (entry.at !== previous) {
+        await options.advanceTo(entry.at)
+        previous = entry.at
+      }
+      if ('input' in entry) await adapter.input(entry.input)
+      else {
+        const value = adapter.read(entry.id)
+        const observed = {
+          position: value.position,
+          velocity: value.velocity,
+          settled: value.settled,
+        }
+        const positionError = Math.abs(observed.position - entry.expected.position)
+        const velocityError = Math.abs(observed.velocity - entry.expected.velocity)
+        const passed =
+          typeof observed.position === 'number' &&
+          typeof observed.velocity === 'number' &&
+          typeof observed.settled === 'boolean' &&
+          Number.isFinite(positionError) &&
+          Number.isFinite(velocityError) &&
+          positionError <= entry.tolerance.position &&
+          velocityError <= entry.tolerance.velocity &&
+          observed.settled === entry.expected.settled
+        observations.push({
+          at: entry.at,
+          id: entry.id,
+          expected: entry.expected,
+          observed: { ...observed },
+          positionError,
+          velocityError,
+          passed,
+        })
+        if (!passed)
+          errors.push(
+            `${entry.id} at ${entry.at} ms: position error ${positionError}, velocity error ${velocityError}, settled ${observed.settled} (expected ${entry.expected.settled}).`,
+          )
+      }
+    }
+  } catch (error) {
+    errors.push(error instanceof Error ? error.message : 'Replay adapter failed.')
+  } finally {
+    if (adapter) {
+      try {
+        await adapter.dispose()
+      } catch {
+        errors.push('Replay adapter disposal failed.')
+      }
+      try {
+        remainingResources = adapter.resources()
+        if (!Number.isSafeInteger(remainingResources) || remainingResources !== 0)
+          errors.push('Replay left owned subscriptions or handles alive.')
+      } catch {
+        remainingResources = -1
+        errors.push('Replay resource audit failed.')
+      }
+    }
+  }
+  return {
+    passed: errors.length === 0,
+    observations,
+    errors,
+    remainingResources,
+    trace,
+    plot: replayPlot(observations),
+  }
+}
+
+/** IDs are validated by parseTrace; plotted values must be finite before entering SVG. */
+export function replayPlot(samples: readonly ReplayObservation[]): string {
+  const finite = samples.filter((s) =>
+    [s.at, s.expected.position, s.observed.position].every(Number.isFinite),
+  )
+  const end = Math.max(1, ...finite.map((s) => s.at))
+  const min = Math.min(
+    0,
+    ...finite.flatMap((s) => [s.expected.position, s.observed.position]),
+  )
+  const max = Math.max(
+    min + 1,
+    ...finite.flatMap((s) => [s.expected.position, s.observed.position]),
+  )
+  const point = (at: number, y: number) =>
+    `${(40 + (at / end) * 560).toFixed(2)},${(180 - ((y - min) / (max - min)) * 140).toFixed(2)}`
+  const ids = [...new Set(finite.map((s) => s.id))]
+  const lines = ids
+    .map((id) => {
+      const rows = finite.filter((s) => s.id === id)
+      return `<polyline fill="none" stroke="#176b5b" stroke-width="2" points="${rows.map((s) => point(s.at, s.expected.position)).join(' ')}"/><polyline fill="none" stroke="#b7355f" stroke-width="2" stroke-dasharray="4 3" points="${rows.map((s) => point(s.at, s.observed.position)).join(' ')}"/>`
+    })
+    .join('')
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="640" height="220" viewBox="0 0 640 220"><rect width="640" height="220" fill="#faf8f1"/><g font-family="sans-serif" font-size="12" fill="#202630"><text x="20" y="20">Presentation position (DIP): green expected / pink observed</text><text x="40" y="205">0 ms</text><text x="540" y="205">${end.toFixed(0)} ms</text><text x="8" y="45">${max.toFixed(0)}</text><text x="8" y="180">${min.toFixed(0)}</text></g><path d="M40 35 V180 H605" fill="none" stroke="#bfc5be"/>${lines}</svg>`
+}

package/src/testing/scroll-handoff-native.ts

@@ -0,0 +1,201 @@
+import { isIOS, ScrollView, Utils, type View } from '@nativescript/core'
+import { GestureSurface } from '../gestures/index.js'
+import {
+  liveSpringDriver,
+  nativeLiveNode,
+  type LiveNode,
+  type LiveBinding,
+} from '../live-spring-driver.js'
+import { retainScrollDelegate } from '../driver/ios-scroll-delegate.js'
+import { nativeTracePosition } from './native.js'
+import {
+  handoffIds,
+  handoffInput,
+  handoffMotions,
+  type HandoffIds,
+} from './scroll-handoff.js'
+import type { TraceMotion } from './trace.js'
+import type { ReplayAdapter } from './replay.js'
+
+/** Isolated native contact replay. Uses the production gesture session's consumption code.
+ * It holds the sheet at release; free spring settling and OS recognition are separate tests.
+ */
+export function nativeScrollHandoffTraceGraph(
+  motions: readonly TraceMotion[],
+  surface: GestureSurface,
+  scroll: ScrollView,
+  ids: HandoffIds = handoffIds,
+): ReplayAdapter {
+  const config = handoffMotions(motions, ids)
+  let parent: View | undefined = scroll.parent as View | undefined
+  while (parent && parent !== surface) parent = parent.parent as View | undefined
+  if (
+    !(surface instanceof GestureSurface) ||
+    !(scroll instanceof ScrollView) ||
+    scroll.orientation !== 'vertical' ||
+    parent !== surface ||
+    !surface.isLoaded ||
+    !scroll.isLoaded
+  )
+    throw new TypeError(
+      'Handoff replay requires a loaded GestureSurface and descendant vertical ScrollView.',
+    )
+  if (
+    isIOS
+      ? typeof JoltGestureSession === 'undefined' ||
+        !JoltGestureSession.supportsScrollReplay?.()
+      : typeof org === 'undefined' ||
+        !org.rafaelaugusto.jolt.GestureSession.supportsScrollReplay?.()
+  )
+    throw new Error('Rebuild the native app to use scroll handoff replay.')
+  if (Math.abs(scroll.scrollableHeight - config.scroll.max) > 1)
+    throw new RangeError('The loaded scroll range differs from the recorded geometry.')
+  if (
+    isIOS
+      ? JoltGestureSession.hasSession(surface.nativeViewProtected)
+      : (
+          surface.nativeViewProtected as org.rafaelaugusto.jolt.GestureSurface
+        ).hasSession()
+  )
+    throw new Error('Replay requires an unowned gesture surface.')
+  const count = () =>
+    isIOS ? JoltLiveSpring.nodeCount() : org.rafaelaugusto.jolt.LiveSpring.nodeCount()
+  const baseline = count(),
+    nodes: LiveNode[] = []
+  const surfaceInput = surface.isUserInteractionEnabled,
+    scrollInput = scroll.isUserInteractionEnabled
+  let claimedInput = false
+  let binding: LiveBinding | undefined,
+    releaseDelegate = () => {},
+    disposed = false,
+    ownsVelocity = false
+  let session:
+    | {
+        input(phase: number, delta: number, velocity: number): void
+        offset(value: number): void
+        dispose(): void
+      }
+    | undefined
+  const dispose = () => {
+    if (disposed) return
+    disposed = true
+    try {
+      session?.dispose()
+    } finally {
+      releaseDelegate()
+      binding?.cancel()
+      nodes.forEach((node) => node.dispose())
+      if (claimedInput) {
+        surface.isUserInteractionEnabled = surfaceInput
+        scroll.isUserInteractionEnabled = scrollInput
+      }
+    }
+  }
+  try {
+    const physics = {
+      stiffness: config.sheet.stiffness,
+      damping: config.sheet.damping,
+      mass: config.sheet.mass,
+      restDelta: 0.001,
+      restSpeed: 0.01,
+    }
+    for (const initial of [0, config.sheet.initial, 1, 0])
+      nodes.push(liveSpringDriver().create(initial, physics, false))
+    const options = JSON.stringify({
+      replay: true,
+      axis: 2,
+      threshold: 8,
+      failOffset: 12,
+      minX: 0,
+      maxX: 0,
+      minY: config.sheet.min,
+      maxY: config.sheet.max,
+      minScale: 1,
+      maxScale: 1,
+      pinch: false,
+      rotate: false,
+      tap: false,
+      doubleTap: false,
+    })
+    if (isIOS) {
+      const n = nodes.map(nativeLiveNode) as JoltLiveSpring[]
+      const native = JoltGestureSession.attachScrollXYScaleRotationOptionsOnState(
+        surface.nativeViewProtected,
+        scroll.nativeViewProtected,
+        n[0]!,
+        n[1]!,
+        n[2]!,
+        n[3]!,
+        options,
+        () => {},
+      )
+      session = {
+        input: (phase, delta, velocity) =>
+          native.replayScrollDeltaVelocity(phase, delta, velocity),
+        offset: (value) => native.replayScrollOffset(value),
+        dispose: () => native.dispose(),
+      }
+      releaseDelegate = retainScrollDelegate(scroll, () => native.refreshScrollDelegate())
+    } else {
+      const n = nodes.map(nativeLiveNode) as org.rafaelaugusto.jolt.LiveSpring[]
+      const native = new org.rafaelaugusto.jolt.GestureSession(
+        surface.nativeViewProtected,
+        scroll.nativeViewProtected,
+        n[0]!,
+        n[1]!,
+        n[2]!,
+        n[3]!,
+        options,
+        new org.rafaelaugusto.jolt.GestureSession.Listener({ onState() {} }),
+      )
+      session = {
+        input: (phase, delta, velocity) => native.replayScroll(phase, delta, velocity),
+        offset: (value) => native.replayScrollOffset(value),
+        dispose: () => native.dispose(),
+      }
+    }
+    // Claim input and bind only after native ownership validation succeeds.
+    claimedInput = true
+    surface.isUserInteractionEnabled = false
+    scroll.isUserInteractionEnabled = false
+    binding = nodes[1]!.bind(surface, 'y', [])
+    session.offset(config.scroll.initial)
+  } catch (error) {
+    dispose()
+    throw error
+  }
+  const input = handoffInput((phase, delta, velocity) => {
+    const before = nodes[1]!.position()
+    session!.input(phase, delta, velocity)
+    ownsVelocity = phase === 2 && nodes[1]!.position() !== before
+  })
+  return {
+    input(event) {
+      if (disposed) throw new Error('Handoff graph is disposed.')
+      if (event.type === 'gesture' && event.id === ids.sheet) input.gesture(event)
+      else if (event.type === 'scroll' && event.id === ids.scroll) {
+        if (event.offset < 0 || event.offset > config.scroll.max)
+          throw new RangeError('Scroll offset is outside the recorded bounds.')
+        session!.offset(event.offset)
+      } else if (event.type === 'lifecycle') input.lifecycle(event.state)
+      else throw new Error(`Handoff has no adapter for ${event.type}.`)
+    },
+    read(id) {
+      if (id !== ids.sheet && id !== ids.scroll)
+        throw new Error('Unknown handoff view ID.')
+      const offset = isIOS
+        ? (scroll.nativeViewProtected as UIScrollView).contentOffset.y +
+          (scroll.nativeViewProtected as UIScrollView).adjustedContentInset.top
+        : Utils.layout.toDeviceIndependentPixels(
+            (scroll.nativeViewProtected as android.view.View).getScrollY(),
+          )
+      return {
+        position: id === ids.sheet ? nativeTracePosition(surface, 'y') : offset,
+        velocity: id === ids.sheet && ownsVelocity ? nodes[1]!.velocity() : 0,
+        settled: !input.contact && !nodes[1]!.moving(),
+      }
+    },
+    dispose,
+    resources: () => (disposed ? Math.max(0, count() - baseline) : nodes.length + 2),
+  }
+}

package/src/testing/scroll-handoff.ts

@@ -0,0 +1,140 @@
+import type { ReplayAdapter } from './replay.js'
+import { parseTrace, type TraceInput, type TraceMotion } from './trace.js'
+
+export interface HandoffIds {
+  sheet: string
+  scroll: string
+}
+export const handoffIds: HandoffIds = { sheet: 'sheet', scroll: 'scroll' }
+
+/** Both entries describe bounded y positions; no free-running spring is part of this adapter. */
+export function handoffMotions(motions: readonly TraceMotion[], ids = handoffIds) {
+  // Reuse the trace schema rather than trusting a cast from a file or consumer.
+  const validated = parseTrace({
+    version: 1,
+    seed: 0,
+    settings: { timeScale: 1, reducedMotion: false },
+    metadata: {
+      platform: 'test',
+      os: 'test',
+      model: 'test',
+      refreshRate: 60,
+      density: 1,
+      width: 1,
+      height: 1,
+    },
+    motions,
+    entries: [],
+  }).motions
+  const sheet = validated.find((m) => m.id === ids.sheet),
+    scroll = validated.find((m) => m.id === ids.scroll)
+  if (
+    validated.length !== 2 ||
+    !sheet ||
+    !scroll ||
+    sheet === scroll ||
+    validated.some((m) => m.kind !== 'drag' || m.axis !== 'y' || m.snap.length) ||
+    scroll.min !== 0
+  )
+    throw new TypeError(
+      'Handoff needs two distinct y drag motions, no snap, and scroll min 0.',
+    )
+  return { sheet, scroll }
+}
+
+/** Normalize cumulative contact positions once; membership changes rebase without a delta. */
+export function handoffInput(
+  send: (phase: number, delta: number, velocity: number) => void,
+) {
+  let contact = false,
+    suspended = false,
+    previous = 0,
+    pointers = ''
+  return {
+    get contact() {
+      return contact
+    },
+    gesture(event: Extract<TraceInput, { type: 'gesture' }>) {
+      if (suspended) return
+      if (event.phase === 'begin') {
+        contact = true
+        previous = event.y
+        pointers = event.pointers.join(',')
+        send(1, 0, 0)
+      } else if (contact && event.phase === 'move') {
+        const next = event.pointers.join(',')
+        const changed = pointers !== next
+        const delta = changed ? 0 : event.y - previous
+        previous = event.y
+        pointers = next
+        send(2, delta, changed ? 0 : event.velocityY)
+      } else if (contact) {
+        contact = false
+        send(event.phase === 'cancel' ? 4 : 3, 0, 0)
+      }
+    },
+    lifecycle(state: string) {
+      if (state === 'suspend' || state === 'unload') {
+        suspended = true
+        contact = false
+        send(4, 0, 0)
+      } else suspended = false
+    },
+  }
+}
+
+/** Independent headless contract: scroll to its top before pulling the sheet down;
+ * expand the sheet before scrolling content up. Native replay exercises the production policy.
+ */
+export function scrollHandoffTraceGraph(
+  motions: readonly TraceMotion[],
+  ids: HandoffIds = handoffIds,
+): ReplayAdapter {
+  const config = handoffMotions(motions, ids)
+  let y = config.sheet.initial,
+    offset = config.scroll.initial,
+    velocity = 0,
+    disposed = false
+  const input = handoffInput((phase, delta, speed) => {
+    if (phase !== 2) {
+      velocity = 0
+      return
+    }
+    const before = y
+    if (delta > 0) {
+      const content = Math.min(offset, delta)
+      offset -= content
+      y = Math.min(config.sheet.max, y + delta - content)
+    } else {
+      const panel = Math.min(y - config.sheet.min, -delta)
+      y -= panel
+      offset = Math.min(config.scroll.max, offset - delta - panel)
+    }
+    velocity = y === before ? 0 : speed
+  })
+  return {
+    input(event) {
+      if (disposed) throw new Error('Handoff graph is disposed.')
+      if (event.type === 'gesture' && event.id === ids.sheet) input.gesture(event)
+      else if (event.type === 'scroll' && event.id === ids.scroll) {
+        if (event.offset < 0 || event.offset > config.scroll.max)
+          throw new RangeError('Scroll offset is outside the recorded bounds.')
+        offset = event.offset
+      } else if (event.type === 'lifecycle') input.lifecycle(event.state)
+      else throw new Error(`Handoff has no adapter for ${event.type}.`)
+    },
+    read(id) {
+      if (id !== ids.sheet && id !== ids.scroll)
+        throw new Error('Unknown handoff view ID.')
+      return {
+        position: id === ids.sheet ? y : offset,
+        velocity: id === ids.sheet ? velocity : 0,
+        settled: !input.contact,
+      }
+    },
+    dispose() {
+      disposed = true
+    },
+    resources: () => (disposed ? 0 : 1),
+  }
+}

package/src/testing/sensors.ts

@@ -0,0 +1,41 @@
+import type { Sensor } from '../sensors/index.js'
+import { sensorDriver } from '../sensors/native.js'
+/** Explicit canonical test inputs. These are synthetic samples, never evidence from device hardware. */
+export interface SensorSample {
+  /** Relative milliseconds from the start of playback. */
+  time: number
+  /** Device-coordinate quaternion xyzw for rotation; downward m/s² xyz for gravity. */
+  values: readonly number[]
+  /** Interface clockwise basis angle from device coordinates, in degrees. */
+  orientation?: 0 | 90 | 180 | 270
+}
+/** Play finite test inputs through the native sensor pipeline; hardware is detached during playback. */
+export function replaySensor(source: Sensor, samples: readonly SensorSample[]): void {
+  if (!Array.isArray(samples) || samples.length < 2 || samples.length > 10000)
+    throw new RangeError('Use 2–10000 sensor samples.')
+  let previous = -1
+  for (const sample of samples) {
+    if (
+      !Number.isFinite(sample.time) ||
+      sample.time <= previous ||
+      sample.time > 60000 ||
+      sample.time < 0
+    )
+      throw new RangeError('Sensor times must increase within 0–60000 milliseconds.')
+    previous = sample.time
+    if (
+      !Array.isArray(sample.values) ||
+      sample.values.length !== (source.kind === 'rotation' ? 4 : 3) ||
+      sample.values.some((value: number) => !Number.isFinite(value))
+    )
+      throw new TypeError('Invalid canonical sensor sample.')
+    if (source.kind === 'rotation' && Math.hypot(...sample.values) < 1e-8)
+      throw new RangeError('A quaternion cannot be zero.')
+    if (
+      sample.orientation !== undefined &&
+      ![0, 90, 180, 270].includes(sample.orientation)
+    )
+      throw new RangeError('Invalid interface orientation.')
+  }
+  sensorDriver(source).replay(JSON.stringify(samples))
+}