@solidrt/core 0.0.63 → 0.0.65

package/src/input-keyboard.ts

@@ -17,7 +17,9 @@
 //
 // Held state is a count behind a signal, so a source's rate is reactive
 // (a held key wakes a control's frame loop) and a blur - the up that never
-// arrives once focus has left - clears it. Composites clamp nothing: the
+// arrives once focus has left - clears it. A source also reports when its
+// keys last changed (the key event's timeStamp; nothing after a blur,
+// which is no release by the player). Composites clamp nothing: the
 // map's combination does (W and D together read [1, -1] before the
 // vec2 clamp to unit length, so diagonals walk at the same speed).
 //
@@ -60,9 +62,11 @@ let matches = (event: KeyEvent, key: string): boolean => {
   return key.length === 4 && key.startsWith("Key") && event.key.toLowerCase() === key[3]!.toLowerCase()
 }
 
-// A set of specs with a reactive "how many are held" count.
+// A set of specs with a reactive "how many are held" count, and the time
+// of the key event that last changed which are held.
 function held(specs: Spec[]) {
   let down = new Set<string>()
+  let changedAt: number | null = null
   // ownedWrite: a map forwards key events from wherever its handlers sit.
   let [count, setCount] = createSignal(0, { ownedWrite: true })
   return {
@@ -72,14 +76,18 @@ function held(specs: Spec[]) {
       // on its most specific matches (a repeat under a newly held Shift
       // moves "Tab" to "Shift+Tab" and back), an up frees them all.
       let onKey = specs.filter(s => matches(event, s.key))
+      let before = [...down].join()
       for (let s of onKey) down.delete(s.text)
       if (isDown) for (let s of mostSpecific(onKey, s => s.mods, event)) down.add(s.text)
+      if ([...down].join() !== before) changedAt = event.timeStamp
       setCount(down.size)
     },
     blur() {
+      if (down.size > 0) changedAt = null
       down.clear()
       setCount(0)
     },
+    changedAt: () => changedAt,
     has(text: string) {
       return down.has(text)
     },
@@ -95,6 +103,7 @@ function key(spec: string): InputSource<"button"> {
     id: `${DEVICE}:key:${spec}`,
     device: DEVICE,
     rate: () => state.count() > 0,
+    changedAt: state.changedAt,
     key: state.key,
     blur: state.blur,
   }

package/src/input-map.ts

@@ -76,7 +76,8 @@ export type DeviceName = "keyboard" | "gamepad" | "pointer"
  * One device control as an input source. `rate` reads its current value
  * (reactive); `deltas` subscribes a sink to the amounts a gesture
  * produces; `key`/`blur` receive the key events a map forwards
- * (InputMap.handlers). A source may carry any subset.
+ * (InputMap.handlers); `changedAt` says when the rate last changed. A
+ * source may carry any subset.
  */
 export interface InputSource<K extends ActionKind = ActionKind> {
   readonly kind: K
@@ -90,6 +91,16 @@ export interface InputSource<K extends ActionKind = ActionKind> {
    * may leave it out and never counts as the active device. */
   readonly device?: DeviceName
   rate?: () => ActionValue<K>
+  /**
+   * When `rate` last changed: the `timeStamp` (ms) of the input event that
+   * changed it, or null when the value was dropped and not let go by the
+   * player (a blur releases every held key with no event), and before any
+   * change. What `tap` and `doubleTap` measure with, so a button source
+   * has to carry it to sit under one: the time travels with the value,
+   * since whoever sees the change sees it after the event is gone. Not
+   * reactive.
+   */
+  changedAt?: () => number | null
   deltas?: (sink: DeltaSink) => () => void
   key?: (event: KeyEvent, down: boolean) => void
   blur?: () => void

package/src/input-pointer.ts

@@ -454,7 +454,7 @@ export function createPointerFeed(options: PointerFeedOptions = {}): PointerFeed
           if (downs.size === 1) {
             opening = { id: e.pointerId, x: e.clientX, y: e.clientY, mods: mods(e), alone: true }
             finger.reset()
-            finger.push(e.clientX, e.clientY)
+            finger.push(e.clientX, e.clientY, e.timeStamp)
           } else if (opening) opening.alone = false
         }
       },
@@ -465,7 +465,7 @@ export function createPointerFeed(options: PointerFeedOptions = {}): PointerFeed
         transform.handlers.onPointerMove(e)
         hold.move(e)
         taps.move(e)
-        if (opening && opening.id === e.pointerId) finger.push(e.clientX, e.clientY)
+        if (opening && opening.id === e.pointerId && !e.predicted) finger.push(e.clientX, e.clientY, e.timeStamp)
       },
       onPointerUp(e) {
         if (downs.get(e.pointerId) !== (e.button ?? PRIMARY)) return
@@ -475,7 +475,7 @@ export function createPointerFeed(options: PointerFeedOptions = {}): PointerFeed
         taps.up(e)
         if (opening && opening.id === e.pointerId) {
           if (opening.alone && downs.size === 0) {
-            let direction: SwipeDirection | null = classifySwipe(finger.velocity(), { dx: e.clientX - opening.x, dy: e.clientY - opening.y })
+            let direction: SwipeDirection | null = classifySwipe(finger.velocity(e.timeStamp), { dx: e.clientX - opening.x, dy: e.clientY - opening.y })
             if (direction) swipe.fire(opening.mods, direction)
           }
           opening = null

package/src/input-processors.ts

@@ -6,11 +6,15 @@
 // the plain press on another action, and the consumer reads one bool.
 //
 // Timing: an interaction watches its source's rate under a root of its
-// own and keeps time with setTimeout, so it works headless and needs no
-// frame loop; the root is disposed with the creating scope (a component
-// body) and lives for the session without one. `tap` and `doubleTap`
-// are edges, not levels: they read pressed for one task, long enough
-// for a map's onPress to fire, then release on their own.
+// own, so it works headless and needs no frame loop; the root is disposed
+// with the creating scope (a component body) and lives for the session
+// without one. `hold` keeps time with setTimeout. `tap` and `doubleTap`
+// measure between the source's edges with the source's own time
+// (`changedAt`, the timeStamp of the input event behind each edge): they
+// see an edge at the flush, after the event is gone, so they read no
+// clock of their own, and a source without `changedAt` cannot sit under
+// them. They are edges, not levels: they read pressed for one task, long
+// enough for a map's onPress to fire, then release on their own.
 //
 // Every processor composes the source's id (`invert(gamepad:leftStick)`,
 // `hold(400,keyboard:key:Space)`), so a saved binding restores through
@@ -49,6 +53,13 @@ let checkButtonSource = (what: string, source: InputSource): void => {
   if (source.kind !== "button") throw new Error(`${what}: "${source.label}" is a ${source.kind}, not a button`)
 }
 
+let checkTimedSource = (what: string, source: InputSource): void => {
+  checkButtonSource(what, source)
+  if (typeof source.changedAt !== "function") {
+    throw new Error(`${what}: "${source.label}" does not say when it changes (no changedAt), so its presses cannot be timed`)
+  }
+}
+
 let checkMs = (what: string, ms: number): void => {
   if (!Number.isFinite(ms) || ms < 0) throw new Error(`${what}: ms must be a non-negative number, got ${String(ms)}`)
 }
@@ -98,11 +109,13 @@ export function scale<K extends "axis" | "vec2">(source: InputSource<K>, factor:
 }
 
 // A button source derived from one button source's press and release
-// edges: `edge(down, now)` runs on each, with `set` for the derived
-// state and `later` for a timer that the disposal clears.
+// edges: `edge(down, at)` runs on each, with `set` for the derived
+// state and `later` for a timer that the disposal clears. `at` is the
+// source's time for the edge (its changedAt), null when it has none: a
+// source that carries no time, or a value that was dropped (a blur).
 type EdgeHooks = { set: (pressed: boolean) => void; later: (ms: number, run: () => void) => void; clearLater: () => void }
 
-function derived(source: InputSource<"button">, label: string, id: string, edge: (down: boolean, now: number, hooks: EdgeHooks) => void): InputSource<"button"> {
+function derived(source: InputSource<"button">, label: string, id: string, edge: (down: boolean, at: number | null, hooks: EdgeHooks) => void): InputSource<"button"> {
   // ownedWrite: the edges land inside an effect and timers.
   let [pressed, setPressed] = createSignal(false, { ownedWrite: true })
   let timer: ReturnType<typeof setTimeout> | null = null
@@ -124,7 +137,7 @@ function derived(source: InputSource<"button">, label: string, id: string, edge:
     createEffect(
       () => source.rate!(),
       (down, prev) => {
-        if (down !== prev) edge(down, performance.now(), hooks)
+        if (down !== prev) edge(down, source.changedAt?.() ?? null, hooks)
       },
       { defer: true },
     )
@@ -151,7 +164,7 @@ let pulse = (hooks: EdgeHooks): void => {
 export function hold(source: InputSource<"button">, ms = HOLD_MS): InputSource<"button"> {
   checkButtonSource("hold", source)
   checkMs("hold", ms)
-  return derived(source, `${source.label} (hold ${ms} ms)`, `hold(${ms},${source.id})`, (down, _now, hooks) => {
+  return derived(source, `${source.label} (hold ${ms} ms)`, `hold(${ms},${source.id})`, (down, _at, hooks) => {
     if (down) hooks.later(ms, () => hooks.set(true))
     else {
       hooks.clearLater()
@@ -161,40 +174,55 @@ export function hold(source: InputSource<"button">, ms = HOLD_MS): InputSource<"
 }
 
 /** A press released within `ms` (default 200): pressed for one task on the
- * release, so onPress fires once per tap and a long press is not one. */
+ * release, so onPress fires once per tap and a long press is not one. A
+ * press the player did not let go (a blur dropped it) is no tap. The
+ * source has to say when it changes (`changedAt`). */
 export function tap(source: InputSource<"button">, ms = TAP_MS): InputSource<"button"> {
-  checkButtonSource("tap", source)
+  checkTimedSource("tap", source)
   checkMs("tap", ms)
-  let downAt = 0
-  return derived(source, `${source.label} (tap)`, `tap(${ms},${source.id})`, (down, now, hooks) => {
-    if (down) downAt = now
-    else if (now - downAt <= ms) pulse(hooks)
+  let downAt: number | null = null
+  return derived(source, `${source.label} (tap)`, `tap(${ms},${source.id})`, (down, at, hooks) => {
+    if (down) downAt = at
+    else {
+      if (at !== null && downAt !== null && at - downAt <= ms) pulse(hooks)
+      downAt = null
+    }
   })
 }
 
 /** Two taps (each within `tapMs`, default 200) at most `gapMs` (default
- * 300) apart: pressed for one task on the second release. */
+ * 300) apart: pressed for one task on the second release. A press the
+ * player did not let go (a blur dropped it) is no tap and ends the pair.
+ * The source has to say when it changes (`changedAt`). */
 export function doubleTap(source: InputSource<"button">, gapMs = DOUBLE_TAP_GAP_MS, tapMs = TAP_MS): InputSource<"button"> {
-  checkButtonSource("doubleTap", source)
+  checkTimedSource("doubleTap", source)
   checkMs("doubleTap", gapMs)
   checkMs("doubleTap", tapMs)
-  let downAt = 0
+  let downAt: number | null = null
   let lastTap = -Infinity
-  return derived(source, `${source.label} (double tap)`, `doubleTap(${gapMs},${tapMs},${source.id})`, (down, now, hooks) => {
+  return derived(source, `${source.label} (double tap)`, `doubleTap(${gapMs},${tapMs},${source.id})`, (down, at, hooks) => {
     if (down) {
-      downAt = now
+      downAt = at
       return
     }
-    if (now - downAt > tapMs) return
-    if (now - lastTap <= gapMs) {
+    let pressedAt = downAt
+    downAt = null
+    if (at === null || pressedAt === null) {
+      lastTap = -Infinity
+      return
+    }
+    if (at - pressedAt > tapMs) return
+    if (at - lastTap <= gapMs) {
       lastTap = -Infinity
       pulse(hooks)
-    } else lastTap = now
+    } else lastTap = at
   })
 }
 
 /** Pressed while every source is: Shift+click on one action, a two-button
- * combo on a pad. Key events reach each keyboard source among them. */
+ * combo on a pad. Key events reach each keyboard source among them. It
+ * changes when the last of its sources to change did (`changedAt`, when
+ * each of them carries one). */
 export function chord(...sources: InputSource<"button">[]): InputSource<"button"> {
   if (sources.length < 2) throw new Error("chord: needs at least two button sources")
   for (let s of sources) checkButtonSource("chord", s)
@@ -204,6 +232,18 @@ export function chord(...sources: InputSource<"button">[]): InputSource<"button"
     id: `chord(${sources.map(s => s.id).join(",")})`,
     device: sources[0]!.device,
     rate: () => sources.every(s => s.rate?.() === true),
+    changedAt: sources.every(s => s.changedAt)
+      ? () => {
+          let latest: number | null = null
+          for (let s of sources) {
+            let at = s.changedAt!()
+            // One source dropped (a blur): so was the chord.
+            if (at === null) return null
+            if (latest === null || at > latest) latest = at
+          }
+          return latest
+        }
+      : undefined,
     key: (event, down) => {
       for (let s of sources) s.key?.(event, down)
     },

package/src/pan.ts

@@ -108,7 +108,7 @@ export function createPan(options: PanOptions) {
           armed = null
           origin = { x: e.parentX, y: e.parentY }
           tracker.reset()
-          tracker.push(e.parentX, e.parentY)
+          if (!e.predicted) tracker.push(e.parentX, e.parentY, e.timeStamp)
           options.onPanStart?.()
         } else {
           // The arena is resolved against us; the drag belongs elsewhere.
@@ -117,7 +117,8 @@ export function createPan(options: PanOptions) {
         return
       }
       if (active === e.pointerId && origin) {
-        tracker.push(e.parentX, e.parentY)
+        // The pan follows a predicted position; its velocity does not.
+        if (!e.predicted) tracker.push(e.parentX, e.parentY, e.timeStamp)
         options.onPanMove?.(e.parentX - origin.x, e.parentY - origin.y)
         origin = { x: e.parentX, y: e.parentY }
       }
@@ -126,7 +127,7 @@ export function createPan(options: PanOptions) {
       if (active === e.pointerId) {
         // The up is not a sample: it sits where the last move left the
         // pointer, and its age is what tells a rest from a flick.
-        let velocity = flingVelocity(tracker.velocity())
+        let velocity = flingVelocity(tracker.velocity(e.timeStamp))
         reset()
         options.onPanEnd?.(velocity)
       } else if (armed === e.pointerId) {

package/src/renderer.ts

@@ -1,6 +1,6 @@
 // createErrorBoundary comes from signals, not solid-js: solid-js marks it
 // @internal (an app writes <Errored>, a renderer reaches for the primitive)
-// and strips it from its .d.ts, so the solid-js re-export types as any.
+// and leaves it out of its public types.
 import { createErrorBoundary, createRoot, onCleanup, NotReadyError, untrack } from "@solidjs/signals"
 import { createRenderer } from "@solidjs/universal"
 import type { Element } from "solid-js"

package/src/runtime-modules.d.ts

@@ -61,7 +61,8 @@ declare module "*.srtm" {
 // stream ("pointerMove"/"pointerDown"/... consumed by window.ts),
 // "pointerFrame" (the move-batch terminator: fires after all of a frame's
 // pointer moves have dispatched, every pointer the same age - multi-pointer
-// recognizers measure there), and "render" (the per-frame signal).
+// recognizers measure there; its `timeStamp` is theirs), and "render" (the
+// per-frame signal).
 declare module "srt:events" {
   export function on(event: string, callback: (data: any) => void): () => void
   export function once(event: string, callback: (data: any) => void): () => void
@@ -235,3 +236,69 @@ declare module "srt:apps" {
 declare module "srt:render" {
   export function renderFrame(): void
 }
+
+// The engine verbs of an app test (lattice, dev client only), which
+// @solidrt/test builds its surface on; tests import that, not this.
+// The verbs work only in an engine a test host built (`srt test`) and throw
+// anywhere else. App time there is frame / frameRate and nothing else: no
+// frame runs unless one is asked for.
+declare module "srt:test" {
+  /**
+   * Runs one frame: timers due by its time fire, then frame callbacks and
+   * the flush, then the draw if anything demanded one. Fulfills once the
+   * frame has run. One frame at a time: throws while the previous one is
+   * still pending.
+   */
+  export function frame(): Promise<void>
+  /** The frames per second this engine steps at (60 unless set). */
+  export function frameRate(): number
+  /** Another frame rate, a positive integer. Throws once a frame has run. */
+  export function setFrameRate(fps: number): void
+  /** App time as of the last frame, in milliseconds; 0 before the first. */
+  export function time(): number
+  /**
+   * Fulfills once the window's size has reached the engine, at once when
+   * it already has. No frame runs for it and no time passes: a mounted
+   * window builds its first frame on that size.
+   */
+  export function windowReady(): Promise<void>
+  /**
+   * Expands `events` (JSON text, the control API's `/input` event shape)
+   * into the steps that are sent and returns what passes before each:
+   * `[ms, frames]` per step, at least that much time and that many frames.
+   * Throws on an invalid event, before anything is sent. The steps are then
+   * sent with `inputStep`, in order.
+   */
+  export function inputPlan(events: string): [ms: number, frames: number][]
+  /**
+   * Sends step `index` of the current plan into the input pipeline: a
+   * down, an up, a key or a wheel is dispatched on arrival, ahead of the
+   * next frame; a move with that frame.
+   */
+  export function inputStep(index: number): void
+  /**
+   * Runs frames until the app is at rest: nothing in flight, no timer due,
+   * no frame demanded. Work in flight is waited for with no app time
+   * passing. Rejects once `maxMs` of app time have passed without rest,
+   * with what is left in the message.
+   */
+  export function settle(maxMs: number): Promise<void>
+  /**
+   * Delivers a link the way an OS-routed one arrives (the raw string, on
+   * the `link` event, ahead of the next frame). Returns whether anything
+   * listens for links.
+   */
+  export function link(link: string): boolean
+  /**
+   * Calls a debug command the app registered with `registerDebug`. `args`
+   * and the result are JSON text (null for no args). Throws on an unknown
+   * name, a throwing command and a result JSON cannot carry.
+   */
+  export function debug(name: string, args: string | null): string
+  /**
+   * The pixels a node's subtree paints: RGBA8, premultiplied, rows top to
+   * bottom, at the display scale. Drawn at once from the tree as it is; no
+   * frame runs and no app time passes.
+   */
+  export function capture(node: number): { width: number; height: number; data: Uint8Array }
+}

package/src/swipe.ts

@@ -80,8 +80,8 @@ export function createSwipe(options: SwipeOptions) {
   // The down's window position and the finger's window-px velocity, over
   // every event the wrapped pan sees.
   let down: { id: number; x: number; y: number } | null = null
-  // The lift's window position, set just before the pan's up runs.
-  let lift: { x: number; y: number } | null = null
+  // The lift's window position and time, set just before the pan's up runs.
+  let lift: { x: number; y: number; at: number } | null = null
   let finger = createVelocityTracker()
   let pan = createPan({
     get axis() {
@@ -92,7 +92,7 @@ export function createSwipe(options: SwipeOptions) {
     onPanEnd: velocity => {
       let direction: SwipeDirection | null = null
       if (down && lift) {
-        direction = classifySwipe(finger.velocity(), { dx: lift.x - down.x, dy: lift.y - down.y }, directions())
+        direction = classifySwipe(finger.velocity(lift.at), { dx: lift.x - down.x, dy: lift.y - down.y }, directions())
       }
       if (direction) options.onSwipe?.(direction, velocity)
       options.onSwipeEnd?.(velocity)
@@ -104,16 +104,16 @@ export function createSwipe(options: SwipeOptions) {
       if (down === null && (e.button == null || e.button === 0)) {
         down = { id: e.pointerId, x: e.clientX, y: e.clientY }
         finger.reset()
-        finger.push(e.clientX, e.clientY)
+        finger.push(e.clientX, e.clientY, e.timeStamp)
       }
       pan.handlers.onPointerDown(e)
     },
     onPointerMove: (e: PointerEvent) => {
-      if (down && down.id === e.pointerId) finger.push(e.clientX, e.clientY)
+      if (down && down.id === e.pointerId && !e.predicted) finger.push(e.clientX, e.clientY, e.timeStamp)
       pan.handlers.onPointerMove(e)
     },
     onPointerUp: (e: PointerEvent) => {
-      if (down && down.id === e.pointerId) lift = { x: e.clientX, y: e.clientY }
+      if (down && down.id === e.pointerId) lift = { x: e.clientX, y: e.clientY, at: e.timeStamp }
       pan.handlers.onPointerUp(e)
       if (down && down.id === e.pointerId) {
         down = null