@solidrt/2d 0.0.52

package/AGENTS.md

@@ -0,0 +1,219 @@
+# @solidrt/2d - agent notes
+
+An instanced sprite layer above `@solidrt/core/gpu`: one atlas texture, N
+quads in ONE draw call, composited into the app as an ordinary `<texture>`
+leaf. The live layer backs every sprite with a SPATIAL ARENA node (never a
+rendertree element - `d-texture` sprites are the right tool up to the low
+thousands; measured ~0.65us paint and ~15KB memory per NODE, and every
+moved node is two setProperty FFI calls per frame). The node makes sprites
+citizens of the spatial core: native producers (node transitions, animation
+clips, physics) reach them through `sprite.node`, hierarchy recomputes
+moved subtrees in Rust, and picking walks the core BVH.
+
+## The model
+
+- THREE faces, layered: the node-backed live layer (layer.ts:
+  `createSpriteLayer`/`addSprite`/`setSprite`/`removeSprite` plus
+  `addGroup`/`setGroup`/`setSpriteParent`/`setSpriteTransition`/
+  `setGroupTransition` - plain objects, no signals, usable without
+  components), the records layer (records.ts: `createRecordLayer` - the
+  raw escape hatch, below), and the component face (components.tsx:
+  `SpriteLayer`/`Sprite`/`Group` over context).
+- Node layer ownership split, two instance-buffer slots on one pipeline:
+  slot 0 is the POSE buffer `[x, y, angle, sx, sy]` written ONLY by the
+  core (each sprite node's Pose2D record sink; one coalesced buffer write
+  per flush however many nodes moved), slot 1 the STYLE buffer
+  `[u0, v0, u1, v1, tint rgba]`, JS-owned, published through the zero-copy
+  write lease. NEVER write the pose buffer from JS - the core's staging
+  mirror owns it and will overwrite.
+- Sprites hold FIXED instance slots: draw order is slot order, removal
+  zeroes the pose (zero scale = nothing drawn) and recycles the slot to
+  the next add. No painter's-insertion-order guarantee across removals;
+  opaque-or-transparent pixel art never notices, z-ordered translucency is
+  the sort-key backlog item (okf/backlog/2d-sprite-sort-key.md).
+- 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.
+- Picking is the core index: `pick` raycasts [x, y, -1] along +z (exact
+  rotated-rect via the node's local box), topmost = highest slot;
+  `pickRect` is the BVH overlap query (exact for rotated sprites, the
+  marquee). Both filter to the layer's own nodes - the arena is shared
+  with e.g. a 3d scene.
+- 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.
+- Mutations batch to a microtask: style lease publish + count setDraw +
+  `spatial.flush()`. No mutation, no publish, no frame: a static layer
+  costs zero, the same demand-gate story as the rest of the platform.
+- The records layer (`createRecordLayer`) keeps the old model whole: 13
+  JS-owned floats per sprite `[cx, cy, w, h, u0, v0, u1, v1, rot, tint
+  rgba]` (`FLOATS_PER_SPRITE`), draw order = insertion order, remove
+  shifts, `layer.records` + `touch()` raw writes, JS pick walk. It is the
+  escape hatch for motion only JS can compute at scale (measured 30k
+  sprites: 12.9ms raw records vs 30.8ms via setSprite) - the axis is
+  WHERE MOTION IS COMPUTED, not retained-vs-dynamic. The sprite functions
+  (addSprite/setSprite/getSprite/removeSprite) work on both layer kinds;
+  record sprites have `node: null` and no groups.
+- Layer space is pixels, top-left origin, y-down - the render tree's frame.
+  The pipeline's clip space is y-down too (core gpu.ts pixel contract), so
+  the vertex stage carries NO flip anywhere. Do not add one.
+- The camera (`setCamera`/the `camera` prop) is a shared-params write
+  (`uCamera`: offset + zoom), one call however many sprites exist. Picking
+  undoes it, so events arrive in world (layer) pixels.
+- Retargeted motion is NATIVE: `setSpriteTransition(sprite, { position:
+  { duration: 700, bounce: 0.3 }, ... })` (or the `transition` prop) makes
+  setSprite writes TARGETS the core animates toward - position/scale
+  (w/h) on the shared spring/tween math, rotation along the quaternion
+  geodesic (always the short arc; a spring keeps its velocity through
+  retargets). JS costs one write per target CHANGE, zero per frame; the
+  running tracks drive frame demand themselves, and settled sprites cost
+  nothing (bench: 400 retargets ~4ms, once a second - vs ~5ms per FRAME
+  moving the same population imperatively). 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.
+- Frame-rate motion only JS can compute (physics, flocking) bypasses the
+  declarative layer: `ref` the sprite, call `setSprite` from `onFrame` (a
+  ~7us core transform write per moved sprite - fine to a few thousand;
+  past that use the records layer). Signals carry structure and slow
+  state - a `<Sprite x={sig()}>` re-running 60 times a second works but
+  re-runs an effect per sprite per frame for nothing.
+- frames.ts and pick.ts are pure (no GPU imports) BY DESIGN so they can be
+  checked headless; keep them that way.
+
+## The baked tile layer (tiles.ts)
+
+Static 2D bulk as a few quads: on tiled GPUs the budget is primitive count
+(core agents/performance.md), so a 100x100 tile world must not be 10,000
+quads per frame. `createTileLayer(cols, rows, tileW, tileH, atlas)` bakes
+the world into CHUNKED `render: "manual"` targets (default ~512px of tiles
+per chunk, `chunkTiles` to tune), each chunk a small copy of the sprite
+pipeline (shaders.ts) with FIXED record slots - an empty tile is a
+zero-size quad, instance count is constant per chunk. Records hold WORLD
+pixel coordinates; each chunk target's `uCamera` is its pixel origin, so
+the shared vertex stage does the chunk-local mapping. Chunks allocate on
+the first `setTile` that reaches them - an empty chunk costs nothing, a
+sparse world is bounded by its content, and world size is bounded by
+memory, not `maxTextureSize`. `setTile` batches to a microtask whose flush
+publishes and re-bakes ONLY dirty chunks. After that the layer is static
+textures: zero per-frame cost however many tiles exist.
+
+Scrolling never re-bakes: the `<TileLayer>` camera prop (`TileCamera`) is
+a transform on the composited world view - the world point (x, y) pinned
+to the viewport point (pivotX, pivotY), scaled by zoom, ROTATED by
+rotation about the pivot. Pivot (0,0) makes `{x, y, zoom}` mean what the
+sprite layer's camera means, so one signal drives both; rotation is the
+ship-flies-over-the-map camera and costs the same transform write. The
+grid shape is creation-fixed (recreate to resize). Tiles are data, not
+children: there is no `<Tile>` component on purpose - write cells through
+`ref` with `setTile`. Not built yet: camera-driven residency (bake far
+chunks on approach, evict) - okf/backlog/2d-baked-layers.md.
+
+## Components
+
+| Component | Props |
+|---|---|
+| `SpriteLayer` | width, height (layer pixels), atlas (TextureId), capacity?, clearColor?, camera?, label?, ref?, output?, events? |
+| `Sprite` | x, y (center; local to the enclosing `<Group>`), w, h, frame?, rotation? (radians, clockwise), tint? ([r,g,b,a] 0..1), transition?, onPointer{Down,Move,Up,Enter,Leave}?, ref? |
+| `Group` | x?, y?, rotation?, scale? (uniform, scales the subtree), transition?, ref? |
+| `TileLayer` | cols, rows, tileW, tileH, atlas (TextureId), clearColor?, filter?, chunkTiles?, camera? (TileCamera: x, y, zoom, rotation, pivotX, pivotY), label?, ref? |
+
+`SpriteLayer` owns the layer and renders the built-in `<texture>` leaf
+carrying the layer's pointer handlers (opt out with `events={false}`; compose
+yourself with `output`, then spread `useSpriteLayer().handlers` onto your
+leaf). `Sprite` renders nothing - it allocates a record through context and
+syncs props into it.
+`GroupContext` is `createContext<SpriteGroup | null>(null)` on purpose: an
+optional parent needs a non-undefined default, since Solid 2 throws on a
+resolved `undefined` even when one was passed as the default.
+
+Pointer events: exact rotated-rect containment, topmost sprite first, capture
+per pointerId (a drag keeps delivering to the grabbed sprite with live
+coordinates), enter/leave paired per pointer. No bubbling - the sprite list
+is flat. Event x/y are layer pixels with the camera undone.
+
+## Traps
+
+- The atlas is NOT owned by the layer: layers come and go, atlases usually
+  live app-long. Dispose atlases yourself (or let the reactive owner do it -
+  createAtlas registers with the owning scope like every core texture).
+- `capacity` is a reservation, not a limit, on both layer kinds; reserve
+  realistically to skip the growth copies. On the records layer, do not
+  cache `layer.records` across addSprite - growth replaces the array.
+- Node layer: `sprite.node` is public FOR BINDING PRODUCERS, not for
+  lifecycle - never destroyNode it yourself (removeSprite 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).
+- With a transition set, the sprite's fields (and getSprite) read the
+  TARGET, not the mid-flight pose - the JS mirror is what setSprite
+  composes partial writes from, and targets are the right thing to
+  compose. Picking and the pose buffer see the actual mid-flight pose
+  (what is on screen). Clearing the transition (null) keeps the
+  mid-flight pose on the node while the mirror still holds the old
+  target: the next setSprite write snaps to whatever it says.
+- Node layer picking reads the index as of the last core flush; `pick`/
+  `pickRect` run the layer's pending batch first, so write-then-pick in
+  one tick is coherent. Producers moving nodes between flushes are one
+  frame stale to picking, like every query.
+- Records layer: record order is draw order: `removeSprite` 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
+  memcpy, microseconds at 10k; the node layer's style publish is the same
+  whole-prefix shape. Dirty ranges were deliberately not built until a
+  measurement asks.
+- The node layer's STYLE slots are not compacted: a removed sprite leaves
+  its style floats in place (invisible - the pose is zeroed) until the
+  slot recycles. Do not read style truth from the buffer; getSprite reads
+  the JS mirror.
+- `createImage` is the wrong loader for pixel-art atlases: it never forwards
+  sampler options, so it is always `filter: "linear"`. `createAtlas` decodes
+  bytes and passes `filter: "nearest"` through - use it, or `decodeImage` +
+  `createTexture` directly.
+- Tint multiplies the sampled texel (`texture * tint`) and the pipeline
+  blends with `blend: "alpha"` in record order. The layer's OUTPUT obeys the
+  premultiplied-alpha contract to the extent the atlas does: PNG decode
+  yields straight alpha, and a translucent texel tinted translucent can
+  composite slightly wrong at the edges. Opaque-or-transparent pixel art
+  (the overwhelming case) is exact. A premultiply-on-decode option is the
+  fix if it ever matters; note it, do not silently add it.
+- `pointInSprite` in pick.ts and the vertex stage's rotation must agree on
+  direction (clockwise, y-down). The differential check (pick-check.ts)
+  guards the math against an oracle but NOT against the shader - if you
+  touch one rotation, touch both.
+- Sprite handles go inert on removal (`sprite.layer === null`); setSprite on
+  an inert handle is a silent no-op (matching the throw-in-dev policy would
+  mean throwing, but removal racing a queued pointer event is routine, not
+  a bug).
+- The `<Sprite>` effect syncs ALL seven fields when ANY prop changes (one
+  effect, one tuple). Fine at component scale; if a profile ever blames it,
+  split the effects before inventing anything cleverer.
+- `<TileLayer>`'s world view is WORLD sized (cols * tileW) and takes that
+  much layout space: put it inside a clipping container (`overflow="clip"`)
+  sized to the viewport, or camera panning shows the world hanging out of
+  the box.
+- `clearColor` is PER CHUNK: never-written regions have no chunk and render
+  nothing, so a full-bleed ground color belongs on the container behind the
+  layer (a `d-rect` under it), not on clearColor.
+- Tile layer zoom/rotation scale the BAKED chunk textures at composite time
+  (the sprite layer's zoom re-samples the atlas in-shader), so the tile
+  layer's `filter` option is what pixel art must set to "nearest" - on top
+  of the atlas's own nearest from createAtlas; they are different samplers.
+- A dirty chunk flush publishes and re-bakes that chunk in full. Fine on
+  change-only cadence; per-frame setTile churn re-bakes chunks per frame -
+  that is sprite-layer work, not tile work.
+- Chunk allocation is MONOTONIC: nothing evicts, so texture memory is
+  proportional to the touched area (~920KB per resident chunk at the
+  default size) and every resident chunk keeps a composited leaf. Bounded
+  worlds only; streaming/infinite is stage B2 in
+  okf/backlog/2d-baked-layers.md.
+- The sprite layer's camera cannot rotate (uCamera is offset + zoom); a
+  sprite layer riding a rotating TileCamera needs
+  okf/backlog/2d-sprite-camera-rotation.md first. Rotating the sprite
+  layer's OUTPUT leaf instead is wrong - it is viewport-sized, the corners
+  cut.

package/README.md

@@ -0,0 +1,51 @@
+# @solidrt/2d
+
+An instanced sprite layer for SolidRT: one atlas, one GPU buffer, thousands
+of sprites in a single draw call, composited into your app as an ordinary
+texture element.
+
+*Status: experimental. Expect API churn.*
+
+```tsx
+import { render } from "@solidrt/core"
+import { createAtlas, grid, Sprite, SpriteLayer } from "@solidrt/2d"
+import sheet from "./sheet.png" with { type: "binary" }
+
+let atlas = createAtlas(sheet, { filter: "nearest" })
+let frames = grid(4, 4, { width: atlas.width, height: atlas.height })
+
+render(() => (
+  <window>
+    <SpriteLayer width={720} height={480} atlas={atlas.texture}>
+      <Sprite x={100} y={120} w={32} h={32} frame={frames[0]} />
+      <Sprite x={200} y={160} w={32} h={32} frame={frames[5]} rotation={0.4} />
+    </SpriteLayer>
+  </window>
+))
+```
+
+The rendertree already handles 2D well: a `d-texture` with atlas sub-rects is
+a sprite, with native transitions, gesture-arena pointer events, and
+per-element inspectability, and it carries populations into the low
+thousands. This package is for what lies beyond that: dense, per-frame
+animated populations - entities, particles, bullets - where per-sprite
+property writes through the JS boundary are the bottleneck. Sprite records
+live in one `Float32Array` and publish to the GPU through SolidRT's zero-copy
+buffer write lease; moving ten thousand sprites is ten thousand float stores
+and one bulk publish, not twenty thousand FFI calls.
+
+Two layers, like `@solidrt/3d`: an imperative core
+(`createSpriteLayer` / `addSprite` / `setSprite` - per-frame motion calls
+these from `onFrame`) and the component face (`SpriteLayer` / `Sprite`) for
+structure and slow state. A static layer publishes nothing and costs nothing;
+the paint-order story is the painter's algorithm (insertion order); pointer
+events hit-test exact rotated rects, topmost first, with pointer capture.
+
+v1 scope: atlas creation and slicing (`createAtlas`, `grid`, `namedFrames`),
+the sprite layer with camera pan/zoom, sprite pointer events, and the
+component face. Staged next: baked/tilemap layers (static worlds as one
+quad), z-ordering, frame animation helpers, and the retro presets (pixel
+canvas, palette and scanline passes) - see `okf/backlog/`.
+
+The full model and the sharp edges are in [AGENTS.md](AGENTS.md); runnable
+patterns in [examples/](examples/).

package/examples/README.md

@@ -0,0 +1,21 @@
+# @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 -
+copy one and adapt it.
+
+- `sprites.tsx` - the layer at its natural scale: 500 sprites bouncing at
+  frame rate, moved imperatively with `setSprite` from `onFrame` while the
+  tree holds one texture leaf. Atlas from PNG bytes (`createAtlas`) sliced
+  2x2 with `grid()`.
+- `tiles.tsx` - the baked tile layer: a 128x128 world (6144px - bigger than
+  one texture may be) baked into lazily-allocated chunks, flown over by a
+  ship-style camera (fixed screen pivot, the world panning and ROTATING
+  under it via the `<TileLayer>` camera prop - transform writes, never a
+  re-bake), and a timer editing tiles to show that a `setTile` batch
+  re-bakes only the chunks it touches.
+- `pick.tsx` - sprite pointer events through the component face: exact
+  rotated-rect hit testing topmost-first, pointer capture (drag a sprite and
+  the events keep naming it), click-vs-drag slop, and removal through a
+  signal so `<For>` unmounts the `<Sprite>` and the layer compacts its draw
+  order.

package/examples/parity.tsx

@@ -0,0 +1,204 @@
+// Node-vs-records parity probe: the same deterministic sprite population
+// rendered through the node-backed live layer (spatial arena nodes, pose
+// buffer core-written) and the records layer (13 JS-owned floats), side by
+// side. Self-asserting: after the first frames it readTexture-compares the
+// two outputs pixel by pixel (the pose round-trips through the core's
+// Pose2D decomposition, so only alpha-edge pixels may flip), cross-checks
+// picking at random points, exercises pickRect, groups and slot recycling,
+// and benches addSprite plus a move-everything frame on both layers. Watch
+// the logs for PARITY/BENCH lines ending in PARITY-OK.
+import { onFrame, render } from "@solidrt/core"
+import { readTexture } from "@solidrt/core/gpu"
+import {
+  addGroup,
+  addSprite,
+  createAtlas,
+  createRecordLayer,
+  createSpriteLayer,
+  getSprite,
+  grid,
+  removeSprite,
+  setGroup,
+  setSprite,
+} from "@solidrt/2d"
+import type { SpriteHandle } from "@solidrt/2d"
+import logoBytes from "./logo.png" with { type: "binary" }
+
+const N = 200
+const W = 360
+const H = 360
+const SEED = 0x2d2d
+
+// Deterministic PRNG (mulberry32) so both layers see identical sprites.
+function rng(seed: number): () => number {
+  let a = seed >>> 0
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0
+    let t = a
+    t = Math.imul(t ^ (t >>> 15), t | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+function App() {
+  let atlas = createAtlas(logoBytes, { label: "logo-atlas" })
+  let frames = grid(2, 2, { width: atlas.width, height: atlas.height })
+  let nodes = createSpriteLayer(W, H, atlas.texture, { capacity: 64, clearColor: [0.05, 0.05, 0.09, 1], label: "nodes" })
+  let records = createRecordLayer(W, H, atlas.texture, { capacity: 64, clearColor: [0.05, 0.05, 0.09, 1], label: "records" })
+
+  let fields = (r: () => number) => ({
+    x: 20 + r() * (W - 40),
+    y: 20 + r() * (H - 40),
+    w: 16 + r() * 48,
+    h: 16 + r() * 48,
+    rotation: r() * Math.PI * 2,
+    frame: frames[Math.floor(r() * 4) % 4]!,
+    tint: [0.5 + r() * 0.5, 0.5 + r() * 0.5, 0.5 + r() * 0.5, 1] as [number, number, number, number],
+  })
+
+  // Population (the capacity of 64 forces both growth paths, including the
+  // pose-buffer retarget).
+  let nodeSprites: SpriteHandle[] = []
+  let recSprites: SpriteHandle[] = []
+  let r1 = rng(SEED)
+  let t0 = performance.now()
+  for (let i = 0; i < N; i++) nodeSprites.push(addSprite(nodes, fields(r1)))
+  let tNodesAdd = performance.now() - t0
+  let r2 = rng(SEED)
+  t0 = performance.now()
+  for (let i = 0; i < N; i++) recSprites.push(addSprite(records, fields(r2)))
+  let tRecsAdd = performance.now() - t0
+  console.log(`BENCH addSprite x${N}: nodes ${tNodesAdd.toFixed(2)}ms, records ${tRecsAdd.toFixed(2)}ms`)
+
+  let failures: string[] = []
+  let check = (ok: boolean, what: string) => {
+    if (!ok) failures.push(what)
+    console.log(`PARITY ${ok ? "ok" : "FAIL"}: ${what}`)
+  }
+
+  // Slot recycling: remove one, add another, the layer stays coherent.
+  {
+    let extra = addSprite(nodes, { x: 10, y: 10, w: 8, h: 8 })
+    let slotBefore = extra._slot
+    removeSprite(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)
+  }
+
+  let pixelParity = () => {
+    let a = readTexture(nodes.texture)
+    let b = readTexture(records.texture)
+    if (a.width !== b.width || a.height !== b.height) {
+      check(false, `sizes differ: ${a.width}x${a.height} vs ${b.width}x${b.height}`)
+      return
+    }
+    let off = 0
+    for (let i = 0; i < a.data.length; i += 4) {
+      if (
+        Math.abs(a.data[i]! - b.data[i]!) > 8 ||
+        Math.abs(a.data[i + 1]! - b.data[i + 1]!) > 8 ||
+        Math.abs(a.data[i + 2]! - b.data[i + 2]!) > 8 ||
+        Math.abs(a.data[i + 3]! - b.data[i + 3]!) > 8
+      ) {
+        off++
+      }
+    }
+    let total = a.data.length / 4
+    let pct = (off / total) * 100
+    check(pct < 0.5, `pixels within tolerance (${off}/${total} off, ${pct.toFixed(3)}%)`)
+  }
+
+  let pickParity = () => {
+    let r = rng(SEED ^ 0xffff)
+    let byNode = new Map(nodeSprites.map((s, i) => [s, i]))
+    let byRec = new Map(recSprites.map((s, i) => [s, i]))
+    let mismatches = 0
+    for (let i = 0; i < 200; i++) {
+      let x = r() * W
+      let y = r() * H
+      let a = nodes.pick(x, y)
+      let b = records.pick(x, y)
+      let ai = a ? byNode.get(a) : null
+      let bi = b ? byRec.get(b) : null
+      if (ai !== bi) mismatches++
+    }
+    check(mismatches <= 1, `pick agrees at random points (${mismatches} mismatches)`)
+  }
+
+  let rectQuery = () => {
+    // Left half of the layer: every hit must at least touch it by AABB,
+    // every sprite fully inside it must be reported.
+    let hits = new Set(nodes.pickRect(0, 0, W / 2, H))
+    let missed = 0
+    let phantom = 0
+    for (let s of nodeSprites) {
+      let f = getSprite(s)!
+      let radius = (Math.hypot(f.w, f.h) / 2) * 1.001
+      let inside = f.x + radius <= W / 2 && f.x - radius >= 0 && f.y - radius >= 0 && f.y + radius <= H
+      let touches = f.x - radius <= W / 2
+      if (inside && !hits.has(s)) missed++
+      if (!touches && hits.has(s)) phantom++
+    }
+    check(missed === 0 && phantom === 0, `pickRect covers the left half (${hits.size} hits, ${missed} missed, ${phantom} phantom)`)
+  }
+
+  let groups = () => {
+    // A group at (100, 100) rotated 90deg clockwise: a child sprite at
+    // local (50, 0) lands at world (100, 150) in y-down space.
+    let g = addGroup(nodes, { x: 100, y: 100 })
+    let child = addSprite(nodes, { parent: g, x: 50, y: 0, w: 10, h: 10 })
+    setGroup(g, { rotation: Math.PI / 2 })
+    queueMicrotask(() => {
+      check(nodes.pick(100, 150) === child, "group rotation carries the child sprite")
+      check(nodes.pick(150, 100) !== 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)
+      // The group node stays for the layer to dispose.
+    })
+  }
+
+  let bench = () => {
+    let r = rng(SEED ^ 0xabcd)
+    let t = performance.now()
+    for (let i = 0; i < N; i++) setSprite(nodeSprites[i]!, { x: 20 + r() * (W - 40), y: 20 + r() * (H - 40) })
+    let tNodes = performance.now() - t
+    r = rng(SEED ^ 0xabcd)
+    t = performance.now()
+    for (let i = 0; i < N; i++) setSprite(recSprites[i]!, { x: 20 + r() * (W - 40), y: 20 + r() * (H - 40) })
+    let tRecs = performance.now() - t
+    console.log(`BENCH move x${N}: nodes ${tNodes.toFixed(2)}ms, records ${tRecs.toFixed(2)}ms`)
+    // Put both populations back so the parity compare still holds.
+    let ra = rng(SEED)
+    for (let i = 0; i < N; i++) setSprite(nodeSprites[i]!, fields(ra))
+    let rb = rng(SEED)
+    for (let i = 0; i < N; i++) setSprite(recSprites[i]!, fields(rb))
+  }
+
+  let frame = 0
+  onFrame(() => {
+    frame++
+    if (frame === 3) {
+      bench()
+      groups()
+    }
+    if (frame === 6) {
+      pixelParity()
+      pickParity()
+      rectQuery()
+      console.log(failures.length === 0 ? "PARITY-OK" : `PARITY-FAIL: ${failures.join("; ")}`)
+    }
+  })
+
+  return (
+    <window flexDirection="row" alignItems="center" justifyContent="center" gap={8}>
+      <texture src={nodes.texture} width={W} height={H} />
+      <texture src={records.texture} width={W} height={H} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/pick.tsx

@@ -0,0 +1,90 @@
+// Sprite pointer events through the component face: the built-in leaf
+// carries the layer's handlers, so <Sprite onPointer*> props receive events
+// with LAYER-pixel coordinates and exact rotated-rect hit testing, topmost
+// sprite first. Drag a sprite to move it - the layer captures the pointer on
+// down, so the drag keeps delivering to the grabbed sprite even when the
+// pointer outruns it. A click (press and release without moving) cycles the
+// tint. Shift-click removes the sprite, exercising slot recycling (the
+// freed pose slot zeroes and waits for the next add); structure lives in a
+// signal, so <For> unmounts the removed <Sprite>.
+import { createSignal, render, For } from "@solidrt/core"
+import { createAtlas, grid, setSprite, Sprite, SpriteLayer } from "@solidrt/2d"
+import type { Frame, SpriteHandle } from "@solidrt/2d"
+import logoBytes from "./logo.png" with { type: "binary" }
+
+const W = 720
+const H = 720
+
+const TINTS: [number, number, number, number][] = [
+  [1, 1, 1, 1],
+  [1, 0.5, 0.5, 1],
+  [0.5, 1, 0.6, 1],
+  [0.55, 0.7, 1, 1],
+]
+
+type Item = { id: number; x: number; y: number; frame: Frame }
+
+function App() {
+  let atlas = createAtlas(logoBytes, { label: "logo-atlas" })
+  let frames = grid(2, 2, { width: atlas.width, height: atlas.height })
+  let [items, setItems] = createSignal<Item[]>([
+    { id: 0, x: 200, y: 240, frame: frames[0]! },
+    { id: 1, x: 420, y: 300, frame: frames[1]! },
+    { id: 2, x: 300, y: 470, frame: frames[2]! },
+    { id: 3, x: 520, y: 500, frame: frames[3]! },
+  ])
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <SpriteLayer width={W} height={H} atlas={atlas.texture} capacity={64} clearColor={[0.05, 0.05, 0.09, 1]}>
+        <For each={items()}>
+          {item => {
+            let tintIndex = 0
+            let down = false
+            let moved = false
+            let downX = 0
+            let downY = 0
+            let handle: SpriteHandle | undefined
+            return (
+              <Sprite
+                ref={s => (handle = s)}
+                x={item.x}
+                y={item.y}
+                w={96}
+                h={96}
+                frame={item.frame}
+                onPointerDown={e => {
+                  down = true
+                  moved = false
+                  downX = e.x
+                  downY = e.y
+                }}
+                onPointerMove={e => {
+                  // onPointerMove also fires on plain hover; only a captured
+                  // move (button held since the down) drags. A few pixels of
+                  // slop keep an ordinary click from registering as a drag.
+                  if (!down) return
+                  if (!moved && Math.hypot(e.x - downX, e.y - downY) < 4) return
+                  moved = true
+                  if (handle) setSprite(handle, { x: e.x, y: e.y })
+                }}
+                onPointerUp={e => {
+                  down = false
+                  if (moved) return
+                  if (e.shiftKey) {
+                    setItems(items().filter(other => other.id !== item.id))
+                    return
+                  }
+                  tintIndex = (tintIndex + 1) % TINTS.length
+                  if (handle) setSprite(handle, { tint: TINTS[tintIndex] })
+                }}
+              />
+            )
+          }}
+        </For>
+      </SpriteLayer>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/springs.tsx

@@ -0,0 +1,69 @@
+// Native node transitions at the sprite layer's scale: every sprite
+// declares a spring, and the app writes TARGETS - one setSprite per sprite
+// per shuffle (about once a second), ZERO JS per frame. The core
+// integrates all the springs each frame and publishes one coalesced
+// pose-buffer write; between shuffles the app runs no code at all (there
+// is no onFrame here - the running tracks drive frame demand themselves,
+// and once everything settles the layer costs nothing). Compare
+// sprites.tsx, which moves the same population imperatively every frame:
+// here the JS cost is proportional to target CHANGES, not frames. The
+// console logs each shuffle's burst cost.
+//
+// Rotation targets ride the quaternion geodesic, so a spin to a new
+// 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.
+import { render } from "@solidrt/core"
+import { addSprite, createAtlas, createSpriteLayer, grid, setSprite, setSpriteTransition } from "@solidrt/2d"
+import logoBytes from "./logo.png" with { type: "binary" }
+
+const COLS = 20
+const ROWS = 20
+const COUNT = COLS * ROWS
+const W = 720
+const H = 720
+const SPRITE = 30
+
+function App() {
+  let atlas = createAtlas(logoBytes, { label: "logo-atlas" })
+  let frames = grid(2, 2, { width: atlas.width, height: atlas.height })
+  let layer = createSpriteLayer(W, H, atlas.texture, {
+    capacity: COUNT,
+    clearColor: [0.05, 0.05, 0.09, 1],
+    label: "springs",
+  })
+
+  let slotX = (slot: number) => ((slot % COLS) + 0.5) * (W / COLS)
+  let slotY = (slot: number) => (Math.floor(slot / COLS) + 0.5) * (H / ROWS)
+
+  // 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 shuffle = () => {
+    for (let i = slots.length - 1; i > 0; i--) {
+      let j = Math.floor(Math.random() * (i + 1))
+      ;[slots[i], slots[j]] = [slots[j]!, slots[i]!]
+    }
+    let start = performance.now()
+    for (let k = 0; k < COUNT; k++) {
+      setSprite(sprites[k]!, { x: slotX(slots[k]!), y: slotY(slots[k]!), rotation: Math.random() * Math.PI * 2 })
+    }
+    let ms = performance.now() - start
+    console.log(`retarget x${COUNT}: ${ms.toFixed(2)} ms; JS idles until the next shuffle`)
+  }
+  setInterval(shuffle, 1200)
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <texture src={layer.texture} width={W} height={H} />
+    </window>
+  )
+}
+
+render(() => <App />)