@solidrt/2d 0.0.64 → 0.0.65

package/AGENTS.md

@@ -110,7 +110,7 @@ being shared with e.g. a 3d scene costs nothing in JS.
 
 ### Spatial queries
 
-Spatial queries (`checks/collision-check.tsx` pins the contract): the
+Spatial queries (`tests/collision.test.tsx` pins the contract): the
 3d scene's trio one dimension down, Godot's PhysicsDirectSpaceState2D
 and CharacterBody2D in their names. `layer.raycast(x, y, dx, dy,
 opts?)` is every shown sprite the ray strikes, nearest first, with
@@ -350,7 +350,7 @@ the nearest view (the `<SpriteLayer>`'s own or the enclosing
 axes, frames only while `active()`. A view's feed normalizes a drag by
 the leaf's own box, so a leaf under a designSize fit pans and zooms
 correctly. camera2d.ts imports `@solidrt/core/input` and
-`@solidrt/core/camera-control` only, so checks/camera2d-check.ts pins
+`@solidrt/core/camera-control` only, so tests/camera2d.test.ts pins
 the clamp, anchoring, glides, the framing, the lanes, damped bounds,
 inertia and the axes headless; examples/camera.tsx (function face) and
 examples/pick.tsx (`<Camera2d>`) are the live guards. The shared
@@ -468,13 +468,16 @@ re-runs an effect per sprite per frame for nothing.
 ### Frame animation
 
 Frame animation (animation.ts): `createAnimation(frames, fps, { loop })`
-is a clip with a shared wall-clock timer stepping every attached sprite
+is a clip with a shared clock on the app's frame time (it freezes with
+the dev clock and plays at its own speed under `srt render`) stepping
+every attached sprite
 (`anim.add(sprite)` / `remove`; `play`/`pause`; `frame()`/`playing()`
 read the clock, methods like the 3d mixer's `playing()`; `loop: false`
 holds the last frame and fires `onFinish`, the mixer's name for it in
-@solidrt/3d). One timer per playing clip, one setSprite
-per sprite per STEP - an 8fps cycle is 8 publishes a second regardless of
-display rate, and a paused clip costs nothing. A sprite belongs to at
+@solidrt/3d). One no-demand frame callback per playing clip, one
+setSprite per sprite per STEP - an 8fps cycle is 8 publishes and 8
+presents a second regardless of display rate, and a paused clip costs
+nothing. A sprite belongs to at
 most one animation (add detaches the previous); removed sprites prune
 lazily on the next step. Works on both layer kinds; with `<Sprite>`,
 attach via `ref` and leave the `frame` prop off - the clip owns that
@@ -485,7 +488,7 @@ keeps, so other props stay reactive).
 
 frames.ts, pick.ts, camera.ts, camera-motion.ts, dispatch.ts,
 oversample-math.ts and tiles-math.ts (the tile grid's chunk and slot
-math, checks/tiles-check.ts) are pure (no GPU imports) BY DESIGN so they
+math, tests/tiles.test.ts) are pure (no GPU imports) BY DESIGN so they
 can be checked headless; keep them that way.
 
 ## The baked tile layer (tiles.ts)
@@ -625,6 +628,9 @@ is never both a tap and a pan), was the only pointer down for its whole
 press (a pinch never taps), with `tapCount` counting repeats within 300
 ms and 20 px on the same target (a double tap is `tapCount === 2`).
 Wheel walks like a move with `deltaX/deltaY`. Every event carries
+`timeStamp` and `predicted` as the element event has them (time input
+with the first; a `predicted` move is one to draw with, not to measure
+with - core's AGENTS.md has both), and
 `native`, the leaf's element event, for core's recognizers (`createPan`
 to drag a sprite with slop, `createTransform` under the camera); a plain
 `onPointerMove` also fires on hover, so a sprite drag gates on its own
@@ -632,7 +638,7 @@ pressed flag from down to up (`native.button` is set on down/up only).
 Root listeners all run, in registration order (the root is the last
 stop, nothing is left to claim); a record layer has no groups, so the
 chain is the sprite then the root. Event x/y are layer pixels with the
-camera undone. checks/dispatch-check.ts pins the walk, claiming, capture,
+camera undone. tests/dispatch.test.ts pins the walk, claiming, capture,
 hover, wheel and tap rules headless.
 
 ## Traps
@@ -782,7 +788,7 @@ hover, wheel and tap rules headless.
 - Every rotation must agree on direction (clockwise, y-down):
   `pointInSprite` in pick.ts with the vertex stage's `iRot`, and
   `projectCamera` in camera.ts with `uCameraRot` and `<TileLayer>`'s view
-  transform. The differential checks (pick-check.ts, camera-check.ts)
+  transform. The differential tests (tests/pick.test.ts, tests/camera.test.ts)
   guard the JS math against oracles but NOT against the shader - if you
   touch one rotation, touch all, then run examples/camera-probe.tsx (the
   live guard: shader vs projectCamera, node/record parity, the pointer

package/examples/README.md

@@ -1,7 +1,7 @@
 # @solidrt/2d examples
 
 Single-concept sprite-layer patterns. Each file is a complete, runnable app
-(`bunx srt run <file>` from the repo root) demonstrating exactly one thing -
+(`bun run srt run <file>` from the repo root) demonstrating exactly one thing -
 copy one and adapt it.
 
 - `sprites.tsx` - the layer at its natural scale: 500 sprites bouncing at

package/examples/anim.tsx

@@ -1,6 +1,7 @@
 // Frame animation via createAnimation: a row of sprites sharing one looping
 // clip (one clock, one setSprite per sprite per STEP - an app's whole crowd
-// animates off a handful of timers, no onFrame loop), plus a one-shot clip
+// animates off a handful of no-demand frame callbacks, presenting only on
+// a step), plus a one-shot clip
 // that holds its last frame and fires onFinish. Self-asserting: samples the
 // sprites' frames against the wall clock and logs ANIM-OK / ANIM-FAIL.
 //
@@ -15,7 +16,7 @@ import logoBytes from "./logo.png" with { type: "binary" }
 const W = 520
 const H = 200
 const SPRITE = 96
-// Slow enough that timer jitter cannot blur a sampled frame boundary: the
+// Slow enough that a late timer cannot blur a sampled frame boundary: the
 // checks sample mid-frame, half a period from either edge.
 const LOOP_FPS = 2
 const SHOT_FPS = 5
@@ -53,9 +54,9 @@ function App() {
     return indexOf(getSprite(sprite)!.frame)
   }
 
-  // Sample mid-frame against the wall clock. At LOOP_FPS = 2 a frame is
-  // 500ms; the clip steps within ~250ms of a boundary (tick at half a
-  // period), so mid-frame samples have ~250ms of margin either way.
+  // Sample mid-frame on timers. At LOOP_FPS = 2 a frame is 500ms and the
+  // clip steps on the display frame a boundary falls in, so mid-frame
+  // samples have ~250ms of margin either way.
   let period = 1000 / LOOP_FPS
   setTimeout(() => {
     check(shownIndex(looped[0]!) === 0, "loop shows frame 0 in its first period")

package/examples/camera-probe.tsx

@@ -1,7 +1,7 @@
 // Camera-mapping probe: the live guard that the three spellings of the
 // camera mapping agree - projectCamera (camera.ts), the vertex stages'
 // uCameraRot (shaders.ts), and pointer dispatch's unprojectCamera
-// (layer.ts). The headless check (checks/camera-check.ts) ties
+// (layer.ts). The headless check (tests/camera.test.ts) ties
 // projectCamera to the <view>-prop oracle but cannot see the shader; this
 // probe closes that gap on a real client. Self-asserting: watch the logs
 // for CAMERA lines ending in CAMERA-OK. Run it after touching ANY

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/2d",
-  "version": "0.0.64",
+  "version": "0.0.65",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -14,8 +14,11 @@
     "examples/",
     "AGENTS.md"
   ],
+  "devDependencies": {
+    "@solidrt/test": "0.0.65"
+  },
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.9",
-    "@solidrt/core": "0.0.64"
+    "@solidjs/signals": "2.0.0-rc.13",
+    "@solidrt/core": "0.0.65"
   }
 }

package/src/animation.ts

@@ -1,24 +1,21 @@
 // Sprite frame animation: a clip (frames + fps) with a shared clock that
-// steps every attached sprite's frame through setSprite. One timer per
-// playing clip and one frame write per attached sprite per STEP (not per
-// display frame), so an 8fps walk cycle generates 8 publishes a second and
-// a paused clip costs nothing - the demand-gate story unchanged. The clip
+// steps every attached sprite's frame through setSprite. One frame callback
+// per playing clip, registered without demand, and one frame write per
+// attached sprite per STEP (not per display frame), so an 8fps walk cycle
+// generates 8 publishes and 8 presents a second and a paused clip costs
+// nothing - the demand-gate story unchanged. The clock is the app's frame
+// time: the clip freezes and resumes with the dev tools' clock, plays at
+// its own speed under `srt render`, and a step lands on the frame it is
+// due in. The clip
 // does not own its sprites (destroySprite prunes lazily on the next step),
 // and a sprite belongs to at most one animation. Plain JS over setSprite,
 // so it works on both layer kinds and composes with <Sprite> via ref (leave
 // the frame prop off - the clip owns that field).
-import { getOwner, onCleanup } from "@solidrt/core"
+import { getOwner, onCleanup, onFrame, runWithOwner } from "@solidrt/core"
 import type { Frame } from "./frames.ts"
 import type { Sprite } from "./layer.ts"
 import { setSprite } from "./layer.ts"
 
-// Timer period as a fraction of the clip's frame duration: the step index
-// is computed from the wall clock (drift-free), so the timer only decides
-// how late after a frame boundary the step lands - half a frame bounds
-// that lateness at half a frame, where a full-frame period could show a
-// frame almost a whole frame late.
-const TICK_RATIO = 0.5
-
 export type AnimationOptions = {
   /** Wrap around (default) or play once and hold the last frame. */
   loop?: boolean
@@ -61,7 +58,7 @@ let attachedTo = new WeakMap<Sprite, SpriteAnimation>()
 /**
  * A frame animation clip: `frames` (usually a slice of a `grid()` result)
  * played at `fps`. Sprites attach with `add`; the clip steps their `frame`
- * on its own wall-clock timer, independent of display rate.
+ * on the app's frame time, independent of display rate.
  */
 export function createAnimation(frames: Frame[], fps: number, opts?: AnimationOptions): SpriteAnimation {
   if (frames.length === 0) throw new Error("createAnimation: frames is empty")
@@ -74,24 +71,30 @@ export function createAnimation(frames: Frame[], fps: number, opts?: AnimationOp
   let playing = true
   let ended = false
   let disposed = false
-  let timer: number | null = null
-  let elapsedBase = 0 // ms of clip time accumulated before the running stretch
-  let runStart = 0 // performance.now() when the clock last started
+  // The running clock's frame callback, null while stopped.
+  let stop: (() => void) | null = null
+  let elapsed = 0 // ms of clip time played so far
+  // The frame time the clip last advanced to, null until the running
+  // clock's first frame: that one only anchors, so a clip starts at the
+  // frame it was started in, whenever in it.
+  let lastTick: number | null = null
 
   function startClock(): void {
-    if (timer !== null || !playing || sprites.size === 0) return
+    if (stop !== null || !playing || sprites.size === 0) return
     // A looping single-frame clip never changes; a one-shot still needs
     // the clock once, to end.
     if (loop && frames.length === 1) return
-    runStart = performance.now()
-    timer = setInterval(tick, (1000 / fps) * TICK_RATIO)
+    lastTick = null
+    // No demand: the clip follows the frames the app runs anyway and asks
+    // for one only by writing a step. Under no owner: the clock is the
+    // clip's (stopClock ends it), not the scope's that attached a sprite.
+    stop = runWithOwner(null, () => onFrame(tick, { demand: false }))
   }
 
   function stopClock(): void {
-    if (timer === null) return
-    elapsedBase += performance.now() - runStart
-    clearInterval(timer)
-    timer = null
+    if (stop === null) return
+    stop()
+    stop = null
   }
 
   function writeAll(): void {
@@ -112,8 +115,11 @@ export function createAnimation(frames: Frame[], fps: number, opts?: AnimationOp
     writeAll()
   }
 
-  function tick(): void {
-    let raw = Math.floor(((elapsedBase + performance.now() - runStart) * fps) / 1000)
+  function tick(now: number): void {
+    // Never backward: across a hot reload the frame time restarts.
+    if (lastTick !== null) elapsed += Math.max(0, now - lastTick)
+    lastTick = now
+    let raw = Math.floor((elapsed * fps) / 1000)
     if (!loop && raw >= frames.length) {
       // The last frame has shown for its full duration: hold it and stop.
       setIndex(frames.length - 1)
@@ -147,7 +153,7 @@ export function createAnimation(frames: Frame[], fps: number, opts?: AnimationOp
       if (disposed || playing) return
       if (ended) {
         ended = false
-        elapsedBase = 0
+        elapsed = 0
         current = 0
         writeAll()
       }

package/src/camera.ts

@@ -1,6 +1,6 @@
 // The 2d camera vocabulary, pure: the one camera type both layers share
 // and its world <-> screen mapping as plain functions - no GPU or GUI
-// imports, so the checks rig (checks/camera-check.ts) exercises this
+// imports, so its test (tests/camera.test.ts) exercises this
 // module headless on the flux binary. Three consumers implement or undo
 // exactly this mapping and must agree with it: the vertex stages
 // (shaders.ts, uCamera + uCameraRot), the tile layer's composite

package/src/camera2d.ts

@@ -23,7 +23,7 @@
 // business - an input map over the view's pointer feed, a pad, a debug
 // command - and `camera2dBindings` in input.ts is the standard wiring
 // (drag pans, pinch and wheel zoom, twist rolls). This module imports no
-// GUI or runtime module, so checks/camera2d-check.ts runs it headless.
+// GUI or runtime module, so tests/camera2d.test.ts runs it headless.
 //
 // Conventions, decided against Godot's Camera2D, Unity's Cinemachine and
 // Three's MapControls (plus the map/whiteboard libraries for the canvas

package/src/components/tile-layer.tsx

@@ -136,7 +136,7 @@ export let TileLayer: VoidComponent<TileLayerProps> = props => {
   // World -> screen: p maps to pivot + R(rotation) * zoom * (p - camera) -
   // projectCamera (camera.ts) spelled with element transforms as origin at
   // the camera point, rotate + scale there, then translate the camera point
-  // onto the pivot. checks/camera-check.ts holds the two spellings together.
+  // onto the pivot. tests/camera.test.ts holds the two spellings together.
   let camX = () => props.camera?.x ?? 0
   let camY = () => props.camera?.y ?? 0
   return (

package/src/dispatch.ts

@@ -17,7 +17,7 @@
 // counted up for repeats (DOM's detail, Unity's clickCount).
 //
 // Pure BY DESIGN (types and camera.ts, nothing with GPU imports) so
-// checks/dispatch-check.ts drives it headless with a fake pick.
+// tests/dispatch.test.ts drives it headless with a fake pick.
 
 import type { PointerEvent as ElementPointerEvent } from "@solidrt/core"
 import { unprojectCamera } from "./camera.ts"
@@ -47,8 +47,6 @@ export type DispatchDeps = {
   root: ViewHandle
   /** The root's listeners, in registration order. */
   listeners: Set<LayerPointerListener>
-  /** The clock for tap repeats (default performance.now; checks inject). */
-  now?: () => number
 }
 
 type HandlerName = "onPointerDown" | "onPointerMove" | "onPointerUp" | "onWheel" | "onTap"
@@ -61,6 +59,8 @@ type InternalEvent = {
   currentTarget: Sprite | SpriteGroup | ViewHandle
   x: number
   y: number
+  timeStamp: number
+  predicted: boolean
   pointerId: number
   pointerType: string
   button?: number
@@ -89,7 +89,6 @@ type Press = {
 }
 
 export function spriteDispatch(deps: DispatchDeps): (layout: (() => { width: number; height: number }) | null) => LayerHandlers {
-  let now = deps.now ?? (() => performance.now())
   let presses = new Map<number, Press>()
   let hover = new Map<number, Sprite>()
   let lastTap: { time: number; cx: number; cy: number; target: Sprite | null; count: number } | null = null
@@ -135,6 +134,8 @@ export function spriteDispatch(deps: DispatchDeps): (layout: (() => { width: num
         currentTarget: sprite ?? deps.root,
         x,
         y,
+        timeStamp: e.timeStamp,
+        predicted: e.predicted,
         pointerId: e.pointerId,
         pointerType: e.pointerType,
         button: e.button,
@@ -199,7 +200,7 @@ export function spriteDispatch(deps: DispatchDeps): (layout: (() => { width: num
         // press, released over the target it pressed (empty space for the
         // layer itself).
         if (press.moved || !press.alone || topmost(x, y) !== press.target) return
-        let time = now()
+        let time = e.timeStamp
         let repeat =
           lastTap !== null &&
           time - lastTap.time <= TAP_INTERVAL_MS &&

package/src/frames.ts

@@ -1,5 +1,5 @@
 // Atlas frame math, pure: names and grid coordinates to normalized UV rects.
-// No GPU or GUI imports, so the checks rig (checks/frames-check.ts) exercises
+// No GPU or GUI imports, so its test (tests/frames.test.ts) exercises
 // this module headless on the flux binary.
 
 /**

package/src/layer.ts

@@ -265,6 +265,11 @@ export type LayerEventBase = {
   /** Pointer position in LAYER pixels (the camera mapping undone). */
   x: number
   y: number
+  /** When the event happened, ms: the element event's `timeStamp`. */
+  timeStamp: number
+  /** The element event's `predicted`: a move the pointer was never
+   * reported at. Draw with it, do not measure with it. */
+  predicted: boolean
   pointerId: number
   pointerType: string
   button?: number

package/src/oversample-math.ts

@@ -1,5 +1,5 @@
 // The pure oversample math: arithmetic on plain numbers, no GPU or window
-// imports, so the headless check (checks/oversample-check.ts) drives it
+// imports, so the headless check (tests/oversample.test.ts) drives it
 // directly. oversample.ts wraps it with the device limits; components/
 // adds the measured inputs (window box, display scale, camera).
 

package/src/oversample.ts

@@ -6,6 +6,7 @@
 // instead of snapping to uneven widths). okf/backlog/2d-layer-display-scale.md.
 // The pure math lives in oversample-math.ts (checkable headless); this
 // module binds it to the device limits and adds the thrash sentinel.
+import { frameTime } from "@solidrt/core"
 import { limits } from "@solidrt/core/gpu"
 import { fitOversampleWithin } from "./oversample-math.ts"
 
@@ -36,7 +37,9 @@ export function fitOversample(scale: number, targetW: number, targetH: number, b
  * healthy layer settles in a change or two (mount, then the post-resize
  * scale); reaching this count means something re-picks every frame. */
 const THRASH_CHANGES = 4
-/** The window those changes must land in, ms. */
+/** The window those changes must land in, ms of the app's frame time: a
+ * warning about what happens per frame counts on the clock frames run on,
+ * so it means the same under `srt render` and a paused dev clock. */
 const THRASH_WINDOW_MS = 1000
 
 /**
@@ -52,7 +55,7 @@ export function thrashSentinel(what: string): () => void {
   let warned = false
   return () => {
     if (warned) return
-    let now = performance.now()
+    let now = frameTime()
     stamps.push(now)
     while (stamps.length > 0 && now - stamps[0]! > THRASH_WINDOW_MS) stamps.shift()
     if (stamps.length < THRASH_CHANGES) return

package/src/pick.ts

@@ -1,5 +1,5 @@
-// Picking narrowphase, pure: no GPU or GUI imports, so the checks rig
-// (checks/pick-check.ts) exercises this module headless on the flux binary.
+// Picking narrowphase, pure: no GPU or GUI imports, so its test
+// (tests/pick.test.ts) exercises this module headless on the flux binary.
 // layer.ts walks its draw order calling this per sprite (topmost first).
 
 /** Exact containment test against a rotated rect (center, size, rotation). */

package/src/tiles-math.ts

@@ -1,6 +1,6 @@
 // The pure tile-grid math: cell and rect validation, a cell's chunk and
 // record slot, and the walk of a rect chunk by chunk - plain arithmetic
-// with no GPU imports, so the headless check (checks/tiles-check.ts)
+// with no GPU imports, so the headless check (tests/tiles.test.ts)
 // drives it directly; tiles.ts wraps it with the chunk textures.
 
 /** Throw unless (col, row) is a cell of the cols x rows grid. */