@solidrt/2d 0.0.57 → 0.0.59

package/examples/anim.tsx

@@ -62,15 +62,15 @@ function App() {
   }, period / 2)
   setTimeout(() => {
     check(shownIndex(looped[1]!) === 1, "loop advanced to frame 1")
-    check(looping.frame === shownIndex(looped[1]!), "anim.frame matches the sprite's shown frame")
+    check(looping.frame() === shownIndex(looped[1]!), "anim.frame matches the sprite's shown frame")
   }, period * 1.5)
   setTimeout(() => {
     check(shownIndex(looped[2]!) === 0, "loop wrapped back to frame 0 after a full cycle")
     // One-shot: 4 frames at 5fps end at 800ms - long since done here.
     check(shownIndex(shotSprite) === frames.length - 1, "one-shot holds its last frame")
-    check(!shot.playing, "one-shot stopped playing")
+    check(!shot.playing(), "one-shot stopped playing")
     check(ended === 1, `onFinish fired once, got ${ended}`)
-    check(looping.playing, "the looping clip is still playing")
+    check(looping.playing(), "the looping clip is still playing")
     console.log(failures.length === 0 ? "ANIM-OK" : `ANIM-FAIL: ${failures.join("; ")}`)
   }, period * 4.5)
 

package/examples/parity.tsx

@@ -17,7 +17,7 @@ import {
   createSpriteLayer,
   getSprite,
   grid,
-  removeSprite,
+  destroySprite,
   setGroup,
   setSprite,
 } from "@solidrt/2d"
@@ -83,11 +83,11 @@ function App() {
   {
     let extra = addSprite(nodes, { x: 10, y: 10, w: 8, h: 8 })
     let slotBefore = extra._slot
-    removeSprite(extra)
+    destroySprite(extra)
     let reused = addSprite(nodes, { x: -100, y: -100, w: 0, h: 0 })
     check(reused._slot === slotBefore, "removed slot recycles to the next add")
     check(getSprite(extra) === null, "removed handle is inert")
-    removeSprite(reused)
+    destroySprite(reused)
   }
 
   let pixelParity = () => {
@@ -158,7 +158,7 @@ function App() {
       check(nodes.pick(150, 100)[0] !== child, "the ungrouped position no longer hits")
       let f = getSprite(child)!
       check(f.x === 50 && f.y === 0, "getSprite reads the local pose")
-      removeSprite(child)
+      destroySprite(child)
       // The group node stays for the layer to dispose.
     })
   }

package/examples/springs.tsx

@@ -13,8 +13,15 @@
 // random angle always takes the short arc, and the position spring keeps
 // its velocity when a shuffle lands mid-flight - retarget as fast as you
 // like, the motion stays continuous.
+//
+// Tap a sprite and it LEAVES: destroySprite lets go of the handle, and the
+// `exit` on its scale entry shrinks it away on an ease-in of its own while
+// the sprite is a ghost - drawn, but no tap or pick reaches it - then the
+// core frees it. A fresh sprite pops into the empty slot a moment later,
+// entering from scale zero (`from`); no settle callback, no bookkeeping.
 import { decodeImage, render } from "@solidrt/core"
-import { addSprite, createAtlas, createSpriteLayer, grid, setSprite, setSpriteTransition } from "@solidrt/2d"
+import { addSprite, createAtlas, createSpriteLayer, destroySprite, grid, setSprite, setSpriteTransition } from "@solidrt/2d"
+import type { SpriteHandle, SpriteTransition } from "@solidrt/2d"
 import logoBytes from "./logo.png" with { type: "binary" }
 
 const COLS = 20
@@ -23,6 +30,16 @@ const COUNT = COLS * ROWS
 const W = 720
 const H = 720
 const SPRITE = 30
+// The pop-in / shrink-out of a sprite's size, and the pause before a
+// tapped-away sprite is replaced.
+const POP_MS = 300
+const RESPAWN_MS = 600
+
+const TRANSITION: SpriteTransition = {
+  position: { duration: 700, bounce: 0.3 },
+  rotation: { duration: 700 },
+  scale: { duration: POP_MS, bounce: 0.4, from: [0, 0], exit: { value: [0, 0], curve: "ease-in", duration: POP_MS / 2 } },
+}
 
 function App() {
   let atlas = createAtlas(decodeImage(logoBytes), { label: "logo-atlas" })
@@ -35,12 +52,17 @@ function App() {
 
   // Sprite k sits at grid slot slots[k]; each shuffle re-deals the slots.
   let slots = Array.from({ length: COUNT }, (_, i) => i)
-  let sprites = slots.map(slot =>
-    addSprite(layer, { x: slotX(slot), y: slotY(slot), w: SPRITE, h: SPRITE, frame: frames[slot % 4] }),
-  )
-  for (let sprite of sprites) {
-    setSpriteTransition(sprite, { position: { duration: 700, bounce: 0.3 }, rotation: { duration: 700 } })
+  let spawn = (k: number): SpriteHandle => {
+    let sprite = addSprite(layer, { x: slotX(slots[k]!), y: slotY(slots[k]!), w: SPRITE, h: SPRITE, frame: frames[k % 4] })
+    // Declared in the adding tick, so the `from` plays: the sprite pops in.
+    setSpriteTransition(sprite, TRANSITION)
+    sprite.onTap = () => {
+      destroySprite(sprite)
+      setTimeout(() => (sprites[k] = spawn(k)), RESPAWN_MS)
+    }
+    return sprite
   }
+  let sprites = slots.map((_, k) => spawn(k))
 
   let shuffle = () => {
     for (let i = slots.length - 1; i > 0; i--) {
@@ -58,7 +80,7 @@ function App() {
 
   return (
     <window alignItems="center" justifyContent="center">
-      <texture src={view.texture} width={W} height={H} />
+      <texture src={view.texture} width={W} height={H} {...view.handlers} />
     </window>
   )
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/2d",
-  "version": "0.0.57",
+  "version": "0.0.59",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -15,7 +15,7 @@
     "AGENTS.md"
   ],
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.6",
-    "@solidrt/core": "0.0.57"
+    "@solidjs/signals": "2.0.0-rc.8",
+    "@solidrt/core": "0.0.59"
   }
 }

package/src/animation.ts

@@ -3,7 +3,7 @@
 // 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
-// does not own its sprites (removeSprite prunes lazily on the next step),
+// 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).
@@ -28,10 +28,10 @@ export type AnimationOptions = {
 
 export type SpriteAnimation = {
   /** Current frame index into the clip. */
-  readonly frame: number
+  frame(): number
   /** True while the clock advances: born playing, false after pause() and
    * after a one-shot ends. */
-  readonly playing: boolean
+  playing(): boolean
   /**
    * Attach a sprite: it shows the clip's current frame immediately and
    * steps with the shared clock (every attached sprite shows the SAME
@@ -127,12 +127,8 @@ export function createAnimation(frames: Frame[], fps: number, opts?: AnimationOp
   }
 
   let handle: SpriteAnimation = {
-    get frame() {
-      return current
-    },
-    get playing() {
-      return playing
-    },
+    frame: () => current,
+    playing: () => playing,
     onFinish: undefined,
     add(sprite) {
       if (disposed) throw new Error("createAnimation: add on a disposed animation")

package/src/camera2d.ts

@@ -53,7 +53,8 @@ import { projectCamera, unprojectCamera } from "./camera.ts"
 import type { CameraUpdate } from "./camera.ts"
 
 // Glide rate toward a pending zoom or pose, e-foldings per second: high
-// enough that a wheel notch reads as one push, low enough to look smooth.
+// enough that a wheel notch reads as one push, low enough to look smooth
+// (the 3d controls' rate, motion.ts there); `damping` scales a notch's.
 const GLIDE_EASE = 9
 // A glide lands when the remaining zoom gap is under this (relative) ...
 const GLIDE_EPSILON = 0.002
@@ -86,6 +87,7 @@ const ROLL_RATE = 0.5
 /** What a 2d camera drives: anything with the layers' `setCamera`. */
 export type Camera2dTarget = { setCamera(update: CameraUpdate): void }
 
+/** The control's parameters: what set() takes and pose() returns filled. */
 export type Camera2dPose = {
   x?: number
   y?: number
@@ -121,6 +123,11 @@ export type Camera2dOptions = Camera2dPose & {
   panSpeed?: number
   zoomSpeed?: number
   rollSpeed?: number
+  /** How long an unbracketed zoom delta (a wheel notch) takes to ease in,
+   * as a multiple of the built-in settle time: 1 (the default) is the
+   * built-in ease, 2 coasts twice as long, 0 applies notches at once, as
+   * a pinch does. The 3d controls' knob, same meaning. */
+  damping?: number
   /** Multiplier over the built-in follow damping. */
   followSpeed?: number
   /** Whether a drag release keeps the view gliding (default true). */
@@ -133,6 +140,9 @@ export type Camera2d = {
   /** The pose as the layers receive it (a fresh object per call): the
    * argument for projectCamera/unprojectCamera. */
   camera(): CameraUpdate
+  /** Pose snapshot - the control's own four values, the shape set() takes
+   * (camera() adds the pivot the layers are told). */
+  pose(): Required<Camera2dPose>
   /** Merge a pose in (clamps apply) and push it. A snap: an x/y/zoom
    * write cancels a glide or fling in flight; rotation alone leaves them
    * running. */
@@ -222,6 +232,9 @@ function checkOptions(options: Camera2dOptions): void {
   }
   finite("pivot.x", options.pivot?.x)
   finite("pivot.y", options.pivot?.y)
+  if (options.damping !== undefined && !(Number.isFinite(options.damping) && options.damping >= 0)) {
+    throw new Error(`createCamera2d: damping must be a non-negative number, got ${options.damping}`)
+  }
   checkFraction("deadZone.width", options.deadZone?.width ?? 0)
   checkFraction("deadZone.height", options.deadZone?.height ?? 0)
 }
@@ -257,6 +270,7 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
   let panSpeed = () => options.panSpeed ?? 1
   let zoomExponent = () => options.zoomSpeed ?? 1
   let rollSpeed = () => options.rollSpeed ?? 1
+  let damping = () => options.damping ?? 1
   let followEase = () => FOLLOW_EASE * (options.followSpeed ?? 1)
   let inertia = () => options.inertia ?? true
 
@@ -443,7 +457,7 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
   let zoomAt = (sx: number, sy: number, factor: number, ease: boolean) => {
     positive("zoomAt factor", factor)
     readViewport()
-    if (!ease) {
+    if (!ease || damping() <= 0) {
       interrupt()
       zoomTo(sx, sy, zoom * factor)
       return
@@ -512,6 +526,7 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
 
   return {
     camera,
+    pose: () => ({ x, y, zoom, rotation }),
     active,
     axes,
     set(pose) {
@@ -654,7 +669,9 @@ export function createCamera2d(target: Camera2dTarget | Camera2dTarget[], option
         touch()
       }
       if (glide !== null && dt > 0) {
-        let k = 1 - Math.exp(-GLIDE_EASE * dt)
+        // A wheel notch's glide coasts as `damping` says; a commanded
+        // glide (glideTo, fit) at the built-in rate.
+        let k = 1 - Math.exp(-(glide.kind === "anchor" ? GLIDE_EASE / damping() : GLIDE_EASE) * dt)
         if (glide.kind === "anchor") {
           let gap = Math.log(glide.target / zoom)
           zoom = Math.abs(gap) < GLIDE_EPSILON ? glide.target : zoom * Math.exp(gap * k)

package/src/components/group.tsx

@@ -1,8 +1,8 @@
 import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
 import type { ParentComponent } from "@solidrt/core"
-import { addGroup, removeGroup, setGroup, setGroupTransition } from "../layer.ts"
+import { addGroup, destroyGroup, setGroup, setGroupTransition } from "../layer.ts"
 import type { SpriteGroup, SpritePointerEvent, SpriteTapEvent, SpriteWheelEvent, TransitionEndEvent } from "../layer.ts"
-import type { NodeTransition } from "flux:spatial"
+import type { SpriteTransition } from "../layer.ts"
 import { GroupContext, LayerContext } from "./context.ts"
 
 export type GroupProps = {
@@ -23,9 +23,9 @@ export type GroupProps = {
   onPointerUp?: (event: SpritePointerEvent) => void
   onWheel?: (event: SpriteWheelEvent) => void
   onTap?: (event: SpriteTapEvent) => void
-  /** How pose-prop changes animate (see setGroupTransition); the mount
-   * pose always snaps. */
-  transition?: NodeTransition | string | null
+  /** How pose-prop changes animate (see setGroupTransition). The mount
+   * pose snaps, unless a component's `from` animates it in from there. */
+  transition?: SpriteTransition | string | null
   /** A declared transition settled on one component. */
   onTransitionEnd?: (event: TransitionEndEvent) => void
   ref?: (group: SpriteGroup) => void
@@ -63,6 +63,6 @@ export let Group: ParentComponent<GroupProps> = props => {
     },
   )
   untrack(() => props.ref)?.(group)
-  onCleanup(() => removeGroup(group))
+  onCleanup(() => destroyGroup(group))
   return <GroupContext value={group}>{props.children}</GroupContext>
 }

package/src/components/sprite-layer.tsx

@@ -241,6 +241,14 @@ export let SpriteLayer: ParentComponent<SpriteLayerProps> = props => {
     }),
   )
   let events = untrack(() => props.events) !== false
+  // A feed on a built-in leaf carrying no handlers listens at a root no
+  // event reaches: a contradiction, so it throws (the dev validation
+  // policy) instead of feeding nothing.
+  if (pointer !== null && !events && !output) {
+    throw new Error(
+      "SpriteLayer: a pointer feed with events={false} receives nothing - the feed listens at the view's root, which only the leaf's handlers reach; keep events on, or compose the leaf with output and spread useSpriteLayer().viewport.handlers on it",
+    )
+  }
   let leaf: { id: number } | undefined
   // The view's pixel size: the props in fixed mode, the built-in leaf's
   // laid-out box in fill mode (getLayoutBox, the untransformed read, so a

package/src/components/sprite.tsx

@@ -1,8 +1,8 @@
 import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
 import type { VoidComponent } from "@solidrt/core"
-import { addSprite, removeSprite, setSprite, setSpriteTransition } from "../layer.ts"
+import { addSprite, destroySprite, setSprite, setSpriteTransition } from "../layer.ts"
 import type { Sprite as SpriteHandle, SpriteOptions, SpritePointerEvent, SpriteTapEvent, SpriteWheelEvent, TransitionEndEvent } from "../layer.ts"
-import type { NodeTransition } from "flux:spatial"
+import type { SpriteTransition } from "../layer.ts"
 import { GroupContext, LayerContext } from "./context.ts"
 
 /**
@@ -29,9 +29,9 @@ export type SpritePointerProps = {
 
 export type SpriteProps = SpriteOptions &
   SpritePointerProps & {
-    /** How pose-prop changes animate (see setSpriteTransition); the mount
-     * pose always snaps. */
-    transition?: NodeTransition | string | null
+    /** How pose-prop changes animate (see setSpriteTransition). The mount
+     * pose snaps, unless a component's `from` animates it in from there. */
+    transition?: SpriteTransition | string | null
     /** A declared transition settled on one component. */
     onTransitionEnd?: (event: TransitionEndEvent) => void
     ref?: (sprite: SpriteHandle) => void
@@ -67,6 +67,6 @@ export let Sprite: VoidComponent<SpriteProps> = props => {
     },
   )
   untrack(() => props.ref)?.(sprite)
-  onCleanup(() => removeSprite(sprite))
+  onCleanup(() => destroySprite(sprite))
   return null
 }

package/src/components/view2d.tsx

@@ -113,6 +113,14 @@ export let View2d: ParentComponent<View2dProps> = props => {
   )
   let output = untrack(() => props.output)
   let events = untrack(() => props.events) !== false
+  // A feed on a built-in leaf carrying no handlers listens at a root no
+  // event reaches: a contradiction, so it throws (the dev validation
+  // policy) instead of feeding nothing.
+  if (pointer !== null && !events && !output) {
+    throw new Error(
+      "View2d: a pointer feed with events={false} receives nothing - the feed listens at the view's root, which only the leaf's handlers reach; keep events on, or compose the leaf with output and spread view.handlers on it",
+    )
+  }
   let leaf: { id: number } | undefined
   // Auto oversample from the built-in leaf's window box, in device pixels,
   // per view pixel: the same pick as SpriteLayer's fixed mode.

package/src/dispatch.ts

@@ -22,7 +22,7 @@
 import type { PointerEvent as ElementPointerEvent } from "@solidrt/core"
 import { unprojectCamera } from "./camera.ts"
 import type { CameraUpdate } from "./camera.ts"
-import type { LayerPointerListener, Sprite, SpriteGroup, SpriteHandlers, SpritePointerEvent } from "./layer.ts"
+import type { LayerPointerListener, Sprite, SpriteGroup, LayerHandlers, SpritePointerEvent } from "./layer.ts"
 import type { ViewHandle } from "./views.ts"
 
 // Finger travel from the down point, in window pixels, past which a press
@@ -88,7 +88,7 @@ type Press = {
   alone: boolean
 }
 
-export function spriteDispatch(deps: DispatchDeps): (layout: (() => { width: number; height: number }) | null) => SpriteHandlers {
+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>()

package/src/index.ts

@@ -15,7 +15,7 @@
 // without Solid components) and the components (SpriteLayer/Sprite/Group/
 // View2d/TileLayer) on top. See AGENTS.md for the model and the traps.
 
-export { addGroup, addSprite, createSpriteLayer, getSprite, removeGroup, removeSprite, setGroup, setGroupTransition, setSprite, setSpriteParent, setSpriteTransition, worldPosition, POSE_FLOATS, STYLE_FLOATS } from "./layer.ts"
+export { addGroup, addSprite, createSpriteLayer, getSprite, destroyGroup, destroySprite, setGroup, setGroupTransition, setSprite, setSpriteParent, setSpriteTransition, worldPosition, POSE_FLOATS, STYLE_FLOATS } from "./layer.ts"
 export { createRecordLayer, FLOATS_PER_SPRITE } from "./records.ts"
 export type { RecordLayer as RecordLayerHandle, RecordLayerOptions } from "./records.ts"
 export { pointInSprite } from "./pick.ts"
@@ -35,7 +35,7 @@ export type {
   MoveResult,
   Overlap,
   QueryOptions,
-  RayHit,
+  Hit,
   Rect,
   LayerPointerEvent,
   LayerPointerListener,
@@ -43,12 +43,15 @@ export type {
   LayerWheelEvent,
   Sprite as SpriteHandle,
   SpriteGroup,
-  SpriteHandlers,
+  LayerHandlers,
   SpriteLayer as SpriteLayerHandle,
   SpriteLayerOptions,
   SpriteOptions,
   SpritePointerEvent,
   SpriteTapEvent,
+  SpriteEndpoint,
+  SpriteTransition,
+  SpriteTransitionSpec,
   SpriteWheelEvent,
   TransitionEndEvent,
   Volume,