@solidrt/core 0.0.64 → 0.0.65

package/src/transform.ts

@@ -21,8 +21,8 @@ const SPAN_SMOOTH = 0.28
 // thresholds is the hysteresis that keeps the gate from chattering.
 // All three step-based constants assume a ~65Hz frame rate (the captured
 // tablet); a 120Hz panel halves per-step deltas. If that ever bites,
-// convert the thresholds to px/s with performance.now() read at the
-// pointerFrame terminator.
+// convert the thresholds to px/s with the pointerFrame terminator's
+// timeStamp.
 const QUIET = 0.3
 const ENGAGE = 0.6
 const QUIET_SMOOTH = 0.19
@@ -147,6 +147,8 @@ export function createTransform(options: TransformOptions) {
   let spanRate = 0
   // Motion arrived this frame; measured and emitted at the terminator.
   let dirty = false
+  // A move of the current batch was predicted (see flush).
+  let predicted = false
   // The anchor must be retaken at the terminator (activation and set-change
   // rebases): mid-batch the pointer map is mixed-age, so anchoring
   // immediately would bake a jolt into the next delta. A rebase frame
@@ -208,8 +210,14 @@ export function createTransform(options: TransformOptions) {
   let owner: ArenaOwner = { cancel }
 
   // The per-frame measure point: runs at the pointerFrame terminator, when
-  // every tracked pointer's position is the same age.
-  let flush = () => {
+  // every tracked pointer's move of the batch has dispatched: the
+  // terminator's timeStamp (the latest of theirs) is the time of what is
+  // measured here.
+  let flush = (frame: { timeStamp: number }) => {
+    // The measure follows a predicted position; the velocity history takes
+    // real ones only.
+    let real = !predicted
+    predicted = false
     if (!active) return
     if (rebase) {
       // Anchor from same-age positions; emits nothing - an activation or
@@ -219,7 +227,7 @@ export function createTransform(options: TransformOptions) {
       let prev = ref
       ref = measure()
       if (prev) tracker.shift(ref.px - prev.px, ref.py - prev.py)
-      tracker.push(ref.px, ref.py)
+      if (real) tracker.push(ref.px, ref.py, frame.timeStamp)
       spanBase = ref.span
       smoothSpan = ref.span
       rebase = false
@@ -229,7 +237,7 @@ export function createTransform(options: TransformOptions) {
     if (!dirty || !ref) return
     dirty = false
     let m = measure()
-    tracker.push(m.px, m.py)
+    if (real) tracker.push(m.px, m.py, frame.timeStamp)
     let prevSpan = smoothSpan
     smoothSpan += (m.span - smoothSpan) * SPAN_SMOOTH
     spanRate += (Math.abs(smoothSpan - prevSpan) - spanRate) * QUIET_SMOOTH
@@ -285,6 +293,7 @@ export function createTransform(options: TransformOptions) {
     onPointerMove: (e: PointerEvent) => {
       if (!pointers.has(e.pointerId) || !ref) return
       pointers.set(e.pointerId, at(e))
+      if (e.predicted) predicted = true
       if (!active) {
         // Arming runs per event: the slop test tolerates a mixed-age
         // measure (8px against <=1 frame of staleness), and the arena
@@ -328,7 +337,7 @@ export function createTransform(options: TransformOptions) {
         if (pointers.size === 0) {
           // The lift's own position is not measured (no terminator
           // follows it); the fit over the delivered frames is the speed.
-          let velocity = flingVelocity(tracker.velocity())
+          let velocity = flingVelocity(tracker.velocity(e.timeStamp))
           active = false
           ref = null
           pinch = false

package/src/types.d.ts

@@ -280,6 +280,33 @@ export interface TransformProps {
 // the DOM MouseEvent). pointerType distinguishes mouse from touch; button is the
 // pressed button on down/up (0 = primary); the modifier flags mirror the DOM.
 export interface PointerEvent {
+  /**
+   * When the event happened, in milliseconds. Every input event carries one,
+   * on one clock, so two stamps subtract to the time between two events: a
+   * tap's length, the gap of a double tap, the age of the last move at a
+   * lift. It is the input's own time, not its delivery's: a move carries the
+   * time the pointer was at the position it reports, however late the
+   * frame that delivers it, and a down, an up, a wheel or a key the time
+   * the platform recorded for it. A `predicted` move runs ahead of its
+   * pointer, so the real move after it can carry an earlier time. Use it
+   * where you would reach for `performance.now()` in a handler: that one
+   * measures when the handler ran, not when the input happened, and it does
+   * not follow the dev clock, `srt render` or a test. The origin is
+   * arbitrary (compare stamps with each other, not with `performance.now()`,
+   * a timer or the `onFrame` tick).
+   */
+  timeStamp: number
+  /**
+   * True for a move whose position the pointer was never reported at. Touch
+   * is delivered in batches, and a batch can miss the frame it belongs to;
+   * the runtime then bridges the gap with one predicted step, so a drag
+   * does not stall and jump. Draw with it, as with any move. Do not measure
+   * with it: leave it out of a velocity or a path. If the finger had in
+   * fact stopped, the next move reports where it really is, with the time
+   * it got there, which is earlier than the predicted move's. False on
+   * every other event.
+   */
+  predicted: boolean
   clientX: number
   clientY: number
   /**
@@ -340,6 +367,9 @@ export interface WheelEvent extends PointerEvent {
 // to the window root alone. <window onKeyDown> is therefore the app-global
 // shortcut point.
 export interface KeyEvent {
+  /** When the key event happened, in milliseconds, on the clock of
+   * `PointerEvent.timeStamp`. */
+  timeStamp: number
   key: string
   code: string
   repeat: boolean
@@ -363,7 +393,19 @@ export interface TextEvent {
   text: string
 }
 
-export interface PointerProps {
+export interface NodeProps {
+  /**
+   * A stable name for the node, for whoever has to find it again with
+   * nothing visible to find it by: a test (`find({ label })` from
+   * `@solidrt/test`) or a dev tool (the tree record carries it and the
+   * tree query matches it). Never affects layout, paint or input. Prefer
+   * finding a node by its text where it has one: such a test breaks when
+   * what the user sees breaks.
+   */
+  label?: string
+}
+
+export interface PointerProps extends NodeProps {
   onPointerDown?: (event: PointerEvent) => void
   onPointerUp?: (event: PointerEvent) => void
   onPointerMove?: (event: PointerEvent) => void

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()