@solidrt/core 0.0.63 → 0.0.65

package/src/velocity.ts

@@ -1,9 +1,15 @@
 // The velocity tracker every recognizer reads at a lift: the pointer's
 // speed from the positions of its last VELOCITY_WINDOW_MS as a
-// least-squares line, not the last two samples. The final sample before a
-// lift is often stationary, and frame batching makes the last delta a
-// whole frame old, so a two-point estimate reads anything from zero to a
-// jolt; a fit over the window reads the finger's actual speed. One
+// least-squares quadratic read at the newest sample (Flutter's
+// VelocityTracker, Android's LSQ2), not the last two samples. The final
+// sample before a lift is often stationary, and frame batching makes the
+// last delta a whole frame old, so a two-point estimate reads anything from
+// zero to a jolt; a fit over the window reads the finger's actual speed.
+// Quadratic, not a line: a flick accelerates into the lift, and a line
+// reads the window's average speed, well under the speed at the lift. The
+// line stays as the guard: a quadratic overshoots under a hard brake and
+// can point backward, so an axis where the two disagree in direction
+// reads zero. One
 // estimator whatever recognizer asks (createPan, createTransform, the
 // pointer feed), so the 2d camera and a control after it never re-derive
 // their own.
@@ -11,8 +17,11 @@
 // Samples are positions in whatever frame the caller measures (the
 // recognizers push the node's parent frame, so the velocity applies 1:1
 // as their deltas do; a swipe classifier pushes window pixels, the
-// finger's own travel) with performance.now() at handler time, the
-// precedent in transform.ts: PointerEvent carries no timestamp.
+// finger's own travel), each with the `timeStamp` of the pointer event it
+// came from. The tracker reads no clock: the read at a lift takes the
+// up's `timeStamp`, and a move's stamp is the time of the position it
+// carries, so the age of the last one is how long the pointer had been
+// there, at any frame rate.
 
 // Fit horizon: Flutter's and Android's VelocityTracker window.
 const VELOCITY_WINDOW_MS = 100
@@ -21,11 +30,26 @@ const VELOCITY_WINDOW_MS = 100
 const VELOCITY_MAX = 8000
 // A position unchanged for this long at the read means the finger rested
 // before lifting: the velocity is zero, whatever the window still holds.
-// Measured from the last sample that MOVED, not the newest sample's age:
-// the runtime's resampler delivers an extrapolated step and its correction
-// up to two frames after the finger stopped, and any same-position
-// re-delivery must not restart the clock either.
+// Measured from when the pointer reached the position it is at, not from
+// the newest sample's age: a same-position re-delivery must not restart
+// the clock.
 const VELOCITY_REST_MS = 50
+// A gap this long (ms) between two consecutive samples means the pointer
+// stopped in between (Flutter's and Android's assume-stopped time): what
+// came before the gap is an earlier motion and stays out of the fit. A
+// slow drag delivers a sample only when the finger moves, so its history
+// is full of such pauses.
+const VELOCITY_STOP_GAP_MS = 40
+// Travel (px) the fitted samples must cover to be a motion at all. A finger
+// leaving the panel shifts its contact by a pixel or two in its last
+// samples (measured: up to 2.7 px over 8 to 25 ms on a tablet), which a
+// fit over so short a span reads as 60 to 450 px/s. The pan slop's
+// distance: under it nothing was dragged.
+const VELOCITY_MIN_TRAVEL = 8
+// Samples closer in time than this (ms) are one instant to the fit: two
+// samples of one frame carry the same stamp, and a curve pinned by such a
+// pair reads a jolt.
+const VELOCITY_MIN_STEP_MS = 1
 // Ring capacity: a 100 ms window holds 12 samples at 120 Hz; the rest is
 // room for a burst of same-frame samples.
 const VELOCITY_SAMPLES = 20
@@ -37,16 +61,20 @@ export const FLING_MIN_VELOCITY = 50
 export type Velocity = { vx: number; vy: number }
 
 export interface VelocityTracker {
-  /** Record a position; `at` defaults to performance.now(). */
-  push(x: number, y: number, at?: number): void
+  /** Record a position at time `at`, ms: the `timeStamp` of the event
+   * that carried it. Real positions only: a `predicted` move is not where
+   * the pointer was, and is left out. */
+  push(x: number, y: number, at: number): void
   /** Translate every sample: a recognizer rebasing its reference point
    * (a finger joining or leaving a transform) keeps the history
    * continuous instead of dropping it. */
   shift(dx: number, dy: number): void
   reset(): void
-  /** The speed at `at` (default now), px/s per axis: a least-squares fit
-   * over the window, zero after a rest, clamped to VELOCITY_MAX. */
-  velocity(at?: number): Velocity
+  /** The speed at time `at` (the lift's `timeStamp`), px/s per axis: a
+   * least-squares quadratic over the window read at its newest sample,
+   * zero after a rest or when the motion since the last pause is a
+   * twitch, clamped to VELOCITY_MAX. */
+  velocity(at: number): Velocity
 }
 
 const ZERO: Velocity = { vx: 0, vy: 0 }
@@ -61,15 +89,8 @@ export function createVelocityTracker(): VelocityTracker {
   // Ring: `count` samples ending at index `head - 1`.
   let head = 0
   let count = 0
-  // When the position last changed (the rest rule's clock).
-  let movedAt = -Infinity
   return {
-    push(x, y, at = performance.now()) {
-      if (count === 0) movedAt = at
-      else {
-        let last = (head - 1 + VELOCITY_SAMPLES) % VELOCITY_SAMPLES
-        if (xs[last] !== x || ys[last] !== y) movedAt = at
-      }
+    push(x, y, at) {
       xs[head] = x
       ys[head] = y
       ts[head] = at
@@ -87,41 +108,83 @@ export function createVelocityTracker(): VelocityTracker {
       head = 0
       count = 0
     },
-    velocity(at = performance.now()) {
+    velocity(at) {
       if (count < 2) return ZERO
+      let newest = (head - 1 + VELOCITY_SAMPLES) % VELOCITY_SAMPLES
+      // The rest rule's clock: when the pointer reached the position it is
+      // at, the oldest of the newest samples that share it.
+      let movedAt = ts[newest]!
+      for (let i = 1; i < count; i++) {
+        let k = (head - 1 - i + VELOCITY_SAMPLES) % VELOCITY_SAMPLES
+        if (xs[k] !== xs[newest] || ys[k] !== ys[newest]) break
+        movedAt = ts[k]!
+      }
       if (at - movedAt > VELOCITY_REST_MS) return ZERO
-      // Means over the window, then the slope of each axis against time.
-      let n = 0
-      let tm = 0
-      let xm = 0
-      let ym = 0
+      // Sums over the window, time and position measured from the newest
+      // sample so the fit's slope at t = 0 is the answer: the power sums
+      // of t, each axis's moments against them, and how many distinct
+      // times (VELOCITY_MIN_STEP_MS apart) the window holds.
+      let s0 = 0
+      let s1 = 0
+      let s2 = 0
+      let s3 = 0
+      let s4 = 0
+      let x0 = 0
+      let x1 = 0
+      let x2 = 0
+      let y0 = 0
+      let y1 = 0
+      let y2 = 0
+      let times = 0
+      let prev = Infinity
+      // The sample after this one in time, and the fit's oldest position.
+      let later = ts[newest]!
+      let farX = 0
+      let farY = 0
       for (let i = 0; i < count; i++) {
         let k = (head - 1 - i + VELOCITY_SAMPLES) % VELOCITY_SAMPLES
         if (at - ts[k]! > VELOCITY_WINDOW_MS) break
-        n++
-        tm += ts[k]!
-        xm += xs[k]!
-        ym += ys[k]!
-      }
-      if (n < 2) return ZERO
-      tm /= n
-      xm /= n
-      ym /= n
-      let tt = 0
-      let tx = 0
-      let ty = 0
-      for (let i = 0; i < n; i++) {
-        let k = (head - 1 - i + VELOCITY_SAMPLES) % VELOCITY_SAMPLES
-        let dt = ts[k]! - tm
-        tt += dt * dt
-        tx += dt * (xs[k]! - xm)
-        ty += dt * (ys[k]! - ym)
+        if (later - ts[k]! > VELOCITY_STOP_GAP_MS) break
+        later = ts[k]!
+        let t = ts[k]! - ts[newest]!
+        if (prev - t >= VELOCITY_MIN_STEP_MS) {
+          times++
+          prev = t
+        }
+        let x = xs[k]! - xs[newest]!
+        let y = ys[k]! - ys[newest]!
+        farX = x
+        farY = y
+        let tt = t * t
+        s0 += 1
+        s1 += t
+        s2 += tt
+        s3 += tt * t
+        s4 += tt * tt
+        x0 += x
+        x1 += t * x
+        x2 += tt * x
+        y0 += y
+        y1 += t * y
+        y2 += tt * y
       }
       // Every sample the same age (one batched frame): no slope to read.
-      if (tt === 0) return ZERO
+      if (times < 2) return ZERO
+      if (Math.hypot(farX, farY) < VELOCITY_MIN_TRAVEL) return ZERO
+      // One axis's slope at t = 0, px per ms: the quadratic
+      // c0 + c1 t + c2 t^2 (c1 by Cramer's rule) once three distinct times
+      // pin it, the line before that; zero where the quadratic points
+      // against the line.
+      let det = s0 * (s2 * s4 - s3 * s3) - s1 * (s1 * s4 - s2 * s3) + s2 * (s1 * s3 - s2 * s2)
+      let slope = (m0: number, m1: number, m2: number) => {
+        let line = (s0 * m1 - s1 * m0) / (s0 * s2 - s1 * s1)
+        if (times < 3) return line
+        let curve = (s0 * (m1 * s4 - s3 * m2) - m0 * (s1 * s4 - s3 * s2) + s2 * (s1 * m2 - m1 * s2)) / det
+        return curve * line < 0 ? 0 : curve
+      }
       // Slopes are px per ms; the result is px per second.
-      let vx = (tx / tt) * 1000
-      let vy = (ty / tt) * 1000
+      let vx = slope(x0, x1, x2) * 1000
+      let vy = slope(y0, y1, y2) * 1000
       let speed = Math.hypot(vx, vy)
       if (speed > VELOCITY_MAX) {
         let f = VELOCITY_MAX / speed

package/src/window.ts

@@ -181,6 +181,21 @@ let animationFrames = new Map<number, Function>()
 // callbacks. Defaults to 60 until the first displayRefreshRate event arrives.
 let refreshRate = 60
 
+// The tick of the latest frame the runtime delivered (see frameTime).
+let latestTick = 0
+
+export interface FrameOptions {
+  /**
+   * Whether the callback is a request for frames (default true). With
+   * `demand: false` it asks for nothing: it still runs before every frame
+   * the runtime delivers, painted or not, but it does not keep the app
+   * rendering. What it writes requests its frame as any write does, so a
+   * loop that changes something a few times a second presents a few times
+   * a second.
+   */
+  demand?: boolean
+}
+
 /**
  * Calls `fn` before every frame is painted: `tick` is the time in ms, `frame` is
  * the present count, and `rate` is the current refresh rate in Hz. `tick`
@@ -203,8 +218,16 @@ let refreshRate = 60
  * one - an effect's apply phase, an event handler - the returned cleanup is
  * the only handle, so return it from the apply (`return onFrame(...)`) to run
  * a loop only while a condition holds.
+ *
+ * A registered callback is a standing request for the next frame: the app
+ * renders and presents every refresh while it is registered, whatever the
+ * body does. `{ demand: false }` registers it without that request, for a
+ * loop that follows time and only sometimes changes the picture (a sprite
+ * clip stepping at 8 fps, a countdown that ticks once a second): it is
+ * called on the same ticks, and the app presents only when it writes.
  */
-export function onFrame(fn: (tick: number, frame: number, rate: number) => void) {
+export function onFrame(fn: (tick: number, frame: number, rate: number) => void, options?: FrameOptions) {
+  let demand = options?.demand !== false
   let frameId: number = null!
   // Cancellation is a flag, not map membership: while a frame runs the whole
   // callback map is swapped out, so a cleanup() called from another onFrame
@@ -219,7 +242,7 @@ export function onFrame(fn: (tick: number, frame: number, rate: number) => void)
     // pending onFrame callback is a standing request for the next frame.
     frameId = nextFrameId++
     animationFrames.set(frameId, extendedFn)
-    requestFrame()
+    if (demand) requestFrame()
     try {
       fn(tick, frame, rate)
     } catch (err) {
@@ -229,7 +252,7 @@ export function onFrame(fn: (tick: number, frame: number, rate: number) => void)
 
   frameId = nextFrameId++
   animationFrames.set(frameId, extendedFn)
-  requestFrame()
+  if (demand) requestFrame()
 
   let cleanup = () => {
     cancelled = true
@@ -239,6 +262,20 @@ export function onFrame(fn: (tick: number, frame: number, rate: number) => void)
   return cleanup
 }
 
+/**
+ * The time of the current frame in ms: the `tick` its onFrame callbacks
+ * receive, readable anywhere without registering one. Inside a frame (a
+ * frame callback, an effect, the render pass) it is that frame's tick;
+ * between frames (an event handler, a timer) it is the latest frame's. It
+ * is 0 before the first frame. Not reactive, and reading it requests no
+ * frame. Use it to time things against the app's own clock from code that
+ * has no tick in hand: it follows the dev tools' clock control, `srt
+ * render` and a test, where performance.now() does not.
+ */
+export function frameTime(): number {
+  return latestTick
+}
+
 // ------ Resize ----------------
 
 // Insets: each value is the distance from the corresponding window edge, like
@@ -538,6 +575,7 @@ export function attachWindow(nodeId: number) {
   // registered and run on the first real render event, before the first
   // paint with their writes applied.
   function runFrame(t: number, frame: number, bootstrap = false) {
+    if (!bootstrap) latestTick = t
     if (!bootstrap && animationFrames.size > 0) {
       let frames = animationFrames
       animationFrames = new Map()