@solidrt/2d 0.0.58 → 0.0.59

package/AGENTS.md

@@ -55,7 +55,7 @@ Contents:
 ### Three faces
 
 THREE faces, layered: the node-backed live layer (layer.ts:
-`createSpriteLayer`/`addSprite`/`setSprite`/`removeSprite` plus
+`createSpriteLayer`/`addSprite`/`setSprite`/`destroySprite` plus
 `addGroup`/`setGroup`/`setSpriteParent`/`setSpriteTransition`/
 `setGroupTransition` - plain objects, no signals, usable without
 components), the records layer (records.ts: `createRecordLayer` - the
@@ -95,7 +95,7 @@ real draw order says so with `orderBy` ("y" or "renderOrder" - see below).
 
 Growth (past `capacity`, doubling): pose sinks move in ONE core
 `retargetRecords` call (full republish next flush), style re-uploads,
-`setDraw({ instanceBuffers })` swaps both, old buffers destroyed.
+`setDrawBuffers({ buffers })` swaps both, old buffers destroyed.
 
 ### Picking
 
@@ -139,11 +139,14 @@ the mover stay in the plane with no 2d narrowphase of their own.
 Groups (`addGroup`/`<Group>`) are plain arena nodes (x, y, rotation,
 UNIFORM scale - a group is a frame, never a sprite size; sprite w/h
 lives in the sprite node's scale, which is why sprites cannot parent
-sprites). Child sprite pose fields are local to the group. `removeGroup`
-removes the SUBTREE: child sprites and groups die with it (remove means
-destroy here, as for removeSprite; re-parent a child out first to keep
-it). @solidrt/3d's `remove` instead DETACHES a re-addable subtree - its
-nodes exist outside a scene, sprites cannot exist outside their layer.
+sprites). Child sprite pose fields are local to the group. `destroyGroup`
+destroys the SUBTREE: child sprites and groups die with it (re-parent a
+child out first to keep it), children first so each plays its own
+`exit` and the group stays their frame until the last has settled. One
+removal verb, the same word with the same meaning as @solidrt/3d's
+`destroy`: a sprite cannot exist outside its layer, so there is no
+detach here (3d's `remove`), and a sprite that should come back is
+hidden (`visible: false`).
 A handle's x/y are local to its group; `worldPosition(sprite | group)`
 reads the layer-pixel position composed through every enclosing group
 from the core's world matrix (@solidrt/3d's worldPosition).
@@ -186,7 +189,7 @@ the WRITE path only - whatever computes the motion is excluded and is
 usually the dominant cost, e.g. a 24k-particle sim measured ~25ms with
 a near-free publish) - the axis is
 WHERE MOTION IS COMPUTED, not retained-vs-dynamic. The sprite functions
-(addSprite/setSprite/getSprite/removeSprite) work on both layer kinds;
+(addSprite/setSprite/getSprite/destroySprite) work on both layer kinds;
 record sprites have `node: null` and no groups.
 
 ### Layer space
@@ -216,7 +219,7 @@ functions over it.
 Camera control: `createCamera2d(view | views, { viewport: () =>
 ({ width, height }), world?: { width, height }, min/maxZoom?, pivot?,
 deadZone?: { width, height }, panSpeed?, zoomSpeed?, rollSpeed?,
-followSpeed?, inertia?, x?, y?, zoom?, rotation? })` - Godot's Camera2D
+damping?, followSpeed?, inertia?, x?, y?, zoom?, rotation? })` - Godot's Camera2D
 and Three's MapControls in one control over the shared CameraUpdate:
 pan with inertia on release, zoom about a point, eased `glideTo`/`fit`,
 `follow(x, y)` through a dead zone with damping, roll about the pivot,
@@ -242,7 +245,9 @@ finger; a rate slides at one viewport height per second), `zoom` (axis,
 octaves, positive in: a delta bracketed by a gesture - a pinch - applies
 at once about its focal point, an unbracketed one - a wheel notch -
 retargets an eased glide, which is how the control tells a finger from
-an impulse; notches compound on the pending target) and `roll` (axis,
+an impulse; notches compound on the pending target, and `damping` scales
+the settle time - 0 applies a notch at once - the 3d controls' knob) and
+`roll` (axis,
 turns); a pan gesture's begin stops any glide (a finger landing on a
 gliding view holds it) and its end flings with the drag's velocity. The
 verbs, each pushing the pose at once: `panBy(dx, dy)` screen pixels,
@@ -274,7 +279,8 @@ inertia and the axis rates, pushes one setCamera per driven view when
 the pose changed and reports that), gated on the reactive
 `cam.active()` (true while a glide, fling, fit, follow or pan gesture
 needs frames, or a rate drives; false at rest), read `cam.camera()` for
-projectCamera. The camera has NO tap of its own: taps are the
+projectCamera and `cam.pose()` for the control's own four values (the
+shape `set()` takes, the 3d controls' `pose()`). The camera has NO tap of its own: taps are the
 dispatch's (`onTap` on the root with `e.sprite` null is "tap on empty
 space"). `<Camera2d input={input}>` inside `<SpriteLayer>` is all of
 that wired through context, the 3d `<OrbitCamera>` shape: options read
@@ -357,13 +363,36 @@ moving the same population imperatively). Retargeting every frame is
 also a legitimate pattern, not an abuse: rewriting a spring's TARGET
 each frame to chase a moving point (a follow-camera trailing a moving
 sprite) rides the spring's smoothing for free - a spring keeps its
-velocity through retargets, so the chase stays fluid. Mount poses always snap (the
-component declares the transition after the first pose sync; the
-function face sets it after addSprite). Each natural settle calls the
-handle's `onTransitionEnd` (plain field, or the `<Sprite>`/`<Group>` prop)
-with `{ component }` - target-only, never on a cancel, snap or removal;
-the raw "spatialTransitionEnd" engine event (srt:events, node =
-sprite.node) stays for flux:spatial consumers. See examples/springs.tsx.
+velocity through retargets, so the chase stays fluid. A mount pose snaps
+unless a component's `from` (2d units: `position: { from: [x, y] }`,
+`rotation: { from: angle }`, `scale: { from: [w, h] }`, a group's
+`from: s`) animates the sprite in from there - once, and only when the
+declaration lands in the tick that added the sprite (the `<Sprite>` prop
+or a setSpriteTransition right after addSprite; a later one animates
+writes only). A component's `exit` (same units) is where it animates to
+when destroySprite/destroyGroup lets go of it: the sprite stays drawn
+while it leaves and is a GHOST meanwhile - no pick, raycast, overlap,
+sweep or pointer event sees it - then frees when the last exit settles
+(a bullet never hits a corpse; an entering sprite is live from its
+first frame, whatever `from` it passes through). Either endpoint takes
+the object form `{ value, duration?, curve?, bounce?, delay? }` to own
+its direction's motion (an ease-out enter, an ease-in exit), and `delay`
+on an entry holds its writes that long on the animation clock (a late
+frame catches up, so a hitch never shifts a held start). `stagger` (ms)
+goes on a GROUP's declaration (`setGroupTransition` / `<Group
+transition>`), never on the sprites: it spaces the enters and exits of
+everything under the group that begin in one frame by `index * stagger`
+(add order in, tree order out whatever the destroy order; nearest
+declaring group wins), and
+cascades nothing unless the sprites declare `from`/`exit` - a hand of
+cards fanning in, a menu popping in, is one `stagger` on the group. For
+the sprites straight under the layer (no group) the layer's root carries
+it: `createSpriteLayer(texture, { stagger })` / `layer.setStagger(ms)`.
+Each natural settle calls the handle's `onTransitionEnd` (plain field,
+or the `<Sprite>`/`<Group>` prop) with `{ component }` - target-only,
+never on a cancel, snap or exit; the raw "spatialTransitionEnd" engine
+event (srt:events, node = sprite.node) stays for flux:spatial consumers.
+See examples/springs.tsx (tap a sprite: it leaves through its `exit`).
 
 ### Frame-rate motion
 
@@ -378,8 +407,9 @@ re-runs an effect per sprite per frame for nothing.
 
 Frame animation (animation.ts): `createAnimation(frames, fps, { loop })`
 is a clip with a shared wall-clock timer stepping every attached sprite
-(`anim.add(sprite)` / `remove`; `play`/`pause`; `loop: false` holds the
-last frame and fires `onFinish`, the mixer's name for it in
+(`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
@@ -482,7 +512,9 @@ on approach, evict) - okf/backlog/2d-baked-layers.md.
 
 `SpriteLayer` owns the layer and its own view, rendered as the built-in
 `<texture>` leaf carrying the view's pointer handlers (opt out with
-`events={false}`; compose yourself with `output`, then spread
+`events={false}`, which throws at mount together with a `pointer` feed -
+the feed would listen at a root no event reaches; the same on `<View2d>`;
+compose yourself with `output`, then spread
 `useSpriteLayer().viewport.handlers` onto your leaf; `output={false}` for
 no own view at all). `useSpriteLayer()` returns `{ layer, parent,
 viewport, pointer }` - the same shape as `useScene()` in `@solidrt/3d` -
@@ -611,7 +643,7 @@ hover, wheel and tap rules headless.
   a hoisted reference becomes a dead copy whose writes publish nothing.
   `layer.withRecords(fn)` is the hoist-proof read; a bare `layer.records`
   at use time is equally live.
-- Records layer: record order is draw order: `removeSprite` shifts every
+- Records layer: record order is draw order: `destroySprite` shifts every
   later sprite down one slot (copyWithin + index fixup, O(later
   sprites)). Its flush publishes the WHOLE live prefix, not a dirty
   range: one moved sprite re-publishes count x 52 bytes - a single
@@ -650,7 +682,7 @@ hover, wheel and tap rules headless.
 ### Nodes, transitions and queries
 
 - Node layer: `sprite.node` is public FOR BINDING PRODUCERS, not for
-  lifecycle - never destroyNode it yourself (removeSprite owns that), and
+  lifecycle - never destroyNode it yourself (destroySprite owns that), and
   a transform written through flux:spatial directly bypasses the sprite's
   pose mirror, so a later setSprite with the old x wins (its compare sees
   no change to skip, but partial writes compose from the mirror).

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.58",
+  "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.58"
+    "@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,