@solidrt/2d 0.0.55 → 0.0.57

package/examples/README.md

@@ -12,10 +12,52 @@ copy one and adapt it.
   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.
+  re-bake), seeded by ONE `setTiles` rect write over a Uint16Array of
+  frame indices (the layer's `frames` table; -1 where the world is
+  empty, and those chunks never allocate), and a timer editing tiles to
+  show that a `setTile` batch re-bakes only the chunks it touches.
+- `anim.tsx` - frame animation with `createAnimation`: three sprites share
+  one looping clip (one clock, stepped by wall time independent of display
+  rate) and a one-shot clip holds its last frame and fires `onEnd`.
+  Self-asserting - watch the logs for ANIM-OK.
+- `camera.tsx` - the 2d camera (`createCamera2d`) over a world larger than
+  the window, driving the layer's one view from an input map the app
+  binds (`camera2dBindings` over the view's pointer feed, bridged from
+  the view's root with `feedPointer`, and any pad): drag empty space to
+  pan with inertia, wheel/pinch to zoom about the pointer, tap empty
+  space to glide there (the view's `onTap` with `e.sprite` null), tap a
+  sprite to select it, drag a sprite to move it (the sprite stops its
+  down, so the camera never pans under it), F to follow a roaming sprite
+  through a dead zone, R to spin the view, Space to fit the world. The
+  VIEW's `handlers` spread onto its leaf; `update(dt)` from `onFrame` is
+  the only per-frame call. Debug commands `camera`, `mode`, `selected`
+  and `first` drive it headless.
+- `pick.tsx` - the event model through the component face: exact
+  rotated-rect hit testing topmost-first, `onTap` (the dispatch's own
+  click, no slop bookkeeping), a claimed press dragging a sprite under a
+  `<Camera2d>` that pans empty space and zooms on wheel, the layer's own
+  `onTap` seeing misses with `e.sprite` null (and `tapCount` for double
+  taps), and removal through a signal so `<For>` unmounts the `<Sprite>`
+  and the layer recycles the slot. A corner `<View2d>` inset shows the
+  same sprites again under a `<Camera2d>` of its own (drag or wheel on
+  the inset moves only the inset's camera; a sprite tapped or dragged
+  there responds as in the main view). The `state` debug command reads
+  both cameras and the sprite positions back.
+- `views.tsx` - layer views (`layer.createView`, the only way a layer
+  shows): the world rendered twice from ONE set of sprites - the
+  window-filling main view under a `createCamera2d` and a corner minimap
+  showing the whole world at the fit zoom, a stroked rect outlining the
+  main view rect through `map.project`. A tap on the minimap glides the main camera there (the
+  view's root listener, `e.x`/`e.y` in world pixels), and a tap on a
+  sprite in the minimap selects it as in the main view (the same sprite
+  handlers, the walk ending at the view). Debug commands `state`,
+  `camera`, `selected` and `first` drive it headless.
+- `split-screen.tsx` - one `<SpriteLayer output={false}>` (sprites, no
+  leaf of its own) shown through two `<View2d>` panes filling the window
+  side by side, each with a `<Camera2d>` of its own following one of two
+  roaming sprites through a dead zone, so the two poses differ every
+  frame; wheel zooms a pane alone while its follow keeps tracking, a tap
+  on a sprite in either pane tints it in both (one sprite, two views).
+  Each pane's map binds `gamepad.next()`: the first pad to press any
+  button drives pane 0, the next pane 1. The `cameras` debug command
+  reads both poses back.

package/examples/anim.tsx

@@ -0,0 +1,84 @@
+// 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
+// that holds its last frame and fires onFinish. Self-asserting: samples the
+// sprites' frames against the wall clock and logs ANIM-OK / ANIM-FAIL.
+//
+// The atlas is the core logo sliced 2x2 by grid(): a 4-frame "clip". Real
+// art would slice a sheet the same way and pass a consecutive slice of the
+// frames array per animation.
+import { decodeImage, render } from "@solidrt/core"
+import { addSprite, createAnimation, createAtlas, createSpriteLayer, getSprite, grid } from "@solidrt/2d"
+import type { Frame, SpriteHandle } from "@solidrt/2d"
+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
+// checks sample mid-frame, half a period from either edge.
+const LOOP_FPS = 2
+const SHOT_FPS = 5
+
+function App() {
+  let atlas = createAtlas(decodeImage(logoBytes), { label: "logo-atlas" })
+  let frames = grid(atlas, 2, 2)
+  let layer = createSpriteLayer(atlas.texture, { label: "anim" })
+  let view = layer.createView({ width: W, height: H, clearColor: [0.05, 0.05, 0.09, 1] })
+
+  // Three sprites share the looping clip - one clock steps all of them.
+  let looping = createAnimation(frames, LOOP_FPS)
+  let looped: SpriteHandle[] = []
+  for (let i = 0; i < 3; i++) {
+    let sprite = addSprite(layer, { x: 80 + i * 120, y: H / 2, w: SPRITE, h: SPRITE })
+    looping.add(sprite)
+    looped.push(sprite)
+  }
+
+  // The one-shot: plays through once, holds the last frame, fires onFinish.
+  let shot = createAnimation(frames, SHOT_FPS, { loop: false })
+  let ended = 0
+  shot.onFinish = () => ended++
+  let shotSprite = addSprite(layer, { x: 440, y: H / 2, w: SPRITE, h: SPRITE })
+  shot.add(shotSprite)
+
+  let failures: string[] = []
+  function check(ok: boolean, what: string) {
+    if (!ok) failures.push(what)
+  }
+  function indexOf(frame: Frame): number {
+    return frames.findIndex(f => Math.abs(f.u0 - frame.u0) < 1e-6 && Math.abs(f.v0 - frame.v0) < 1e-6)
+  }
+  function shownIndex(sprite: SpriteHandle): number {
+    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.
+  let period = 1000 / LOOP_FPS
+  setTimeout(() => {
+    check(shownIndex(looped[0]!) === 0, "loop shows frame 0 in its first period")
+  }, 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")
+  }, 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(ended === 1, `onFinish fired once, got ${ended}`)
+    check(looping.playing, "the looping clip is still playing")
+    console.log(failures.length === 0 ? "ANIM-OK" : `ANIM-FAIL: ${failures.join("; ")}`)
+  }, period * 4.5)
+
+  return (
+    <window alignItems="center" justifyContent="center">
+      <texture src={view.texture} width={W} height={H} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/camera-probe.tsx

@@ -0,0 +1,202 @@
+// 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
+// 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
+// rotation in the package (the touch-one-rotation-touch-all rule in
+// AGENTS.md).
+//
+// What it checks, all under one rotated + pivoted camera:
+// 1. The shader implements projectCamera: a probe sprite samples opaque
+//    at its PROJECTED pixel and background at the unrotated position.
+// 2. VERTEX (records) and VERTEX_SPLIT (nodes) agree: pixel parity
+//    between the two layer kinds.
+// 3. Pointer dispatch round-trips: a pointer at the projected screen
+//    point hits the sprite and reports its world coordinates.
+// 4. Tile chunks bake with the pinned identity camera rotation.
+import { decodeImage, onFrame, render } from "@solidrt/core"
+import { readTexture } from "@solidrt/core/gpu"
+import {
+  addSprite,
+  createAtlas,
+  createRecordLayer,
+  createSpriteLayer,
+  createTileLayer,
+  FULL_FRAME,
+  grid,
+  projectCamera,
+} from "@solidrt/2d"
+import type { CameraUpdate, SpriteHandle, SpritePointerEvent } from "@solidrt/2d"
+import logoBytes from "./logo.png" with { type: "binary" }
+
+const W = 360
+const H = 360
+const N = 40
+const SEED = 0xcafe
+
+// Chosen so the probe sprite at world (320, 320) projects on-screen
+// (~185, ~208) while its unrotated position (20, 20) maps back to a world
+// point far outside the population's reach - both sample points are clean.
+const CAM: CameraUpdate = { x: 300, y: 300, zoom: 1, rotation: 0.6, pivotX: 180, pivotY: 180 }
+
+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(decodeImage(logoBytes), { label: "logo-atlas" })
+  let frames = grid(atlas, 2, 2)
+  let nodes = createSpriteLayer(atlas.texture, { label: "cam-nodes" })
+  let records = createRecordLayer(atlas.texture, { label: "cam-records" })
+  let nodeView = nodes.createView({ width: W, height: H, label: "cam-nodes" })
+  let recordView = records.createView({ width: W, height: H, label: "cam-records" })
+  nodeView.setCamera(CAM)
+  recordView.setCamera(CAM)
+
+  // The same deterministic population on both layers, kept inside world
+  // 20..100 so its reach (~145 with rotation) stays clear of both sample
+  // points.
+  let fields = (r: () => number) => ({
+    x: 20 + r() * 80,
+    y: 20 + r() * 80,
+    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],
+  })
+  let r1 = rng(SEED)
+  for (let i = 0; i < N; i++) addSprite(nodes, fields(r1))
+  let r2 = rng(SEED)
+  for (let i = 0; i < N; i++) addSprite(records, fields(r2))
+
+  // The probe sprite: the FULL logo frame (its central 10% is fully
+  // opaque, so the projected center samples opaque), isolated from the
+  // population.
+  let probe: SpriteHandle = addSprite(nodes, { x: 320, y: 320, w: 40, h: 40, frame: FULL_FRAME })
+  addSprite(records, { x: 320, y: 320, w: 40, h: 40, frame: FULL_FRAME })
+
+  // A small tile layer: the bake path with the pinned identity rotation.
+  // The checked tile (2, 2) gets the full frame (opaque center texel).
+  let tiles = createTileLayer(8, 8, 16, 16, atlas.texture, { label: "cam-tiles" })
+  for (let i = 0; i < 8; i++) tiles.setTile(i, i, i === 2 ? FULL_FRAME : frames[i % 4]!)
+
+  let failures: string[] = []
+  let check = (ok: boolean, what: string) => {
+    if (!ok) failures.push(what)
+    console.log(`CAMERA ${ok ? "ok" : "FAIL"}: ${what}`)
+  }
+
+  let alphaAt = (img: { width: number; height: number; data: Uint8Array | Uint8ClampedArray }, sx: number, sy: number, n: number) => {
+    // The target is oversampled n times the layer size; sample the texel
+    // at the scaled screen point.
+    let px = Math.min(img.width - 1, Math.max(0, Math.round(sx * n)))
+    let py = Math.min(img.height - 1, Math.max(0, Math.round(sy * n)))
+    return img.data[(py * img.width + px) * 4 + 3]!
+  }
+
+  let shaderCheck = () => {
+    let img = readTexture(nodeView.texture)
+    let n = nodeView.oversample
+    let [sx, sy] = projectCamera(CAM, 320, 320)
+    check(sx > 8 && sx < W - 8 && sy > 8 && sy < H - 8, `projected probe on screen (${sx.toFixed(1)}, ${sy.toFixed(1)})`)
+    check(alphaAt(img, sx, sy, n) > 0, "probe center opaque at its PROJECTED pixel")
+    // Where a pre-rotation shader would draw it: (world - cam) * zoom.
+    let ux = (320 - CAM.x!) * CAM.zoom!
+    let uy = (320 - CAM.y!) * CAM.zoom!
+    check(Math.hypot(ux - sx, uy - sy) > 40, "rotated and unrotated positions are far apart")
+    check(alphaAt(img, ux, uy, n) === 0, "background at the UNROTATED position")
+    let [cx, cy] = projectCamera(CAM, CAM.x!, CAM.y!)
+    check(Math.abs(cx - CAM.pivotX!) < 1e-9 && Math.abs(cy - CAM.pivotY!) < 1e-9, "camera world point projects onto the pivot")
+  }
+
+  let pixelParity = () => {
+    let a = readTexture(nodeView.texture)
+    let b = readTexture(recordView.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, `node/record pixel parity under rotated camera (${off}/${total} off, ${pct.toFixed(3)}%)`)
+  }
+
+  let pointerRoundTrip = () => {
+    let got: SpritePointerEvent | null = null
+    probe.onPointerDown = e => (got = e)
+    let [sx, sy] = projectCamera(CAM, 320, 320)
+    // Synthesize the element event the built-in leaf would deliver (layout
+    // null: localX/localY are layer pixels already).
+    nodeView.handlers.onPointerDown({
+      localX: sx,
+      localY: sy,
+      pointerId: 1,
+      pointerType: "mouse",
+      button: 0,
+      shiftKey: false,
+      ctrlKey: false,
+      altKey: false,
+      metaKey: false,
+    } as never)
+    // TS narrows `got` to null (the write is inside the handler call above).
+    let hit = got as SpritePointerEvent | null
+    check(hit !== null && hit.sprite === probe, "pointer at the projected pixel hits the probe")
+    check(hit !== null && Math.abs(hit.x - 320) < 1e-6 && Math.abs(hit.y - 320) < 1e-6, `pointer event carries world coords (${hit ? `${hit.x.toFixed(3)}, ${hit.y.toFixed(3)}` : "none"})`)
+    check(nodes.pick(320, 320)[0] === probe, "pick in world space still hits the probe")
+  }
+
+  let tileBake = () => {
+    let chunk = tiles.chunks[0]
+    if (!chunk) {
+      check(false, "tile chunk allocated")
+      return
+    }
+    let img = readTexture(chunk.texture)
+    let n = tiles.oversample
+    // Tile (2, 2) center at world (40, 40), chunk origin (0, 0).
+    check(alphaAt(img, 40, 40, n) > 0, "tile bakes opaque with the pinned identity camera rotation")
+    check(alphaAt(img, 40, 8, n) === 0, "empty cell stays clear")
+  }
+
+  let frame = 0
+  onFrame(() => {
+    frame++
+    if (frame === 6) {
+      shaderCheck()
+      pixelParity()
+      pointerRoundTrip()
+      tileBake()
+      console.log(failures.length === 0 ? "CAMERA-OK" : `CAMERA-FAIL: ${failures.join("; ")}`)
+    }
+  })
+
+  return (
+    <window flexDirection="row" alignItems="center" justifyContent="center" gap={8}>
+      <texture src={nodeView.texture} width={W} height={H} />
+      <texture src={recordView.texture} width={W} height={H} />
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/camera.tsx

@@ -0,0 +1,196 @@
+// The 2d camera (createCamera2d) over a world larger than the window,
+// attached at the layer's root: drag empty space to pan with inertia on
+// release, wheel or pinch anywhere to zoom about the pointer, tap empty
+// space to glide the view there. The sprites take part in the same
+// walk: a tap on one selects it (tint), a drag on one moves it - the
+// sprite stops its down, which claims the press, so the camera never
+// pans under a sprite drag. Keys switch modes - F follows the roaming
+// sprite through a dead zone with damping, R spins the view about its
+// center, Space fits the whole world. The camera is one setCamera write
+// per changed frame (a shared-params write); no sprite moves for the
+// camera's sake. The layer fills the window through the function face
+// (starlings' shape): the app owns the <texture> leaf and spreads the
+// LAYER's handlers on it; the camera listens at the root through attach.
+//
+// Debug commands, for driving it from the control API: `camera` returns
+// the pose (and parks it when given x/y/zoom/rotation), `mode` sets
+// { follow, spin } or runs { fit: true }, `selected` returns the selected
+// sprite's world position (null when none), `first` the first sprite's -
+// the one to aim synthetic taps and drags at.
+import { createEffect, createInputMap, createPointerFeed, decodeImage, displayScale, gamepad, onFrame, render, windowSize } from "@solidrt/core"
+import { addSprite, camera2dActions, camera2dBindings, createAtlas, createCamera2d, createSpriteLayer, feedPointer, fitOversample, grid, setSprite } from "@solidrt/2d"
+import type { Camera2dHandle, SpriteHandle } from "@solidrt/2d"
+import { registerDebug } from "srt:dev"
+import logoBytes from "./logo.png" with { type: "binary" }
+
+const WORLD = { width: 2400, height: 1600 }
+const COUNT = 300
+const SPRITE = 64
+const ROAMER = 96
+const MAX_ZOOM = 4
+// The roamer's Lissajous path: radians per second per axis, and how much
+// of the world it sweeps.
+const ROAM_RATE_X = 0.23
+const ROAM_RATE_Y = 0.31
+const ROAM_SPAN = 0.4
+// Spin rate while R is on, radians per second.
+const SPIN_RATE = 0.4
+// The follow dead zone, fractions of the viewport.
+const DEAD_ZONE = { width: 0.3, height: 0.3 }
+// Largest frame step, seconds: a stall eases on from here instead of
+// teleporting.
+const MAX_DT = 0.1
+const TINT: [number, number, number, number] = [0.6, 0.7, 0.9, 1]
+const SELECTED_TINT: [number, number, number, number] = [1, 0.95, 0.5, 1]
+
+let cam!: Camera2dHandle
+let following = false
+let spinning = false
+// The roamer's world position, for the `mode` debug command.
+let roamerAt = { x: 0, y: 0 }
+let selected: SpriteHandle | null = null
+let first: SpriteHandle | null = null
+// The sprite holding a press (onPointerMove also fires on plain hover;
+// only the captured moves drag).
+let dragging: SpriteHandle | null = null
+
+function App() {
+  let atlas = createAtlas(decodeImage(logoBytes), { label: "logo-atlas" })
+  let frames = grid(atlas, 2, 2)
+  // The window's logical size, mirrored for the layer and the camera.
+  let win = { width: 1, height: 1 }
+  let layer = createSpriteLayer(atlas.texture, { capacity: COUNT + 1, label: "camera" })
+  // The layer's one view here: the window. The camera drives it and
+  // listens at its root.
+  let view = layer.createView({ width: win.width, height: win.height, clearColor: [0.05, 0.05, 0.09, 1] })
+  let select = (sprite: SpriteHandle | null) => {
+    if (selected) setSprite(selected, { tint: TINT })
+    selected = sprite
+    if (selected) setSprite(selected, { tint: SELECTED_TINT })
+  }
+  for (let i = 0; i < COUNT; i++) {
+    let sprite = addSprite(layer, {
+      x: Math.random() * WORLD.width,
+      y: Math.random() * WORLD.height,
+      w: SPRITE,
+      h: SPRITE,
+      frame: frames[i % 4],
+      rotation: Math.random() * Math.PI * 2,
+      tint: TINT,
+    })
+    // The sprite claims its press: the camera at the root never sees this
+    // pointer again, so dragging the sprite moves it instead of the view.
+    sprite.onPointerDown = e => {
+      e.stopPropagation()
+      dragging = sprite
+    }
+    sprite.onPointerUp = () => (dragging = null)
+    sprite.onPointerMove = e => {
+      if (dragging === sprite) setSprite(sprite, { x: e.x, y: e.y })
+    }
+    sprite.onTap = () => select(sprite)
+    if (first === null) first = sprite
+  }
+  let roamer = addSprite(layer, { x: WORLD.width / 2, y: WORLD.height / 2, w: ROAMER, h: ROAMER, frame: frames[0], tint: [1, 0.8, 0.3, 1] })
+
+  cam = createCamera2d(view, {
+    viewport: () => win,
+    world: WORLD,
+    maxZoom: MAX_ZOOM,
+    deadZone: DEAD_ZONE,
+  })
+  // The camera's input: the view's pointer feed (fed from the view's root,
+  // after the sprites' claims) and any pad, bound to the control's actions
+  // (ARCHITECTURE.md: the app wires devices, the control takes the map).
+  let pointer = createPointerFeed()
+  feedPointer(view, pointer)
+  let input = createInputMap(camera2dActions)
+  input.bind(camera2dBindings({ pointer, gamepad: gamepad() }))
+  input.drive(cam.axes)
+  // A tap that reached the root landed on empty space (a sprite's tap
+  // still bubbles here with e.sprite set, so the miss is the null case).
+  view.listen({
+    onTap: e => {
+      if (e.sprite) return
+      select(null)
+      following = false
+      cam.glideTo(e.x, e.y)
+    },
+  })
+
+  createEffect(
+    () => ({ size: windowSize(), scale: displayScale() }),
+    ({ size, scale }) => {
+      win.width = Math.max(1, size.width)
+      win.height = Math.max(1, size.height)
+      view.setSize(win.width, win.height)
+      view.setOversample(fitOversample(scale, win.width, win.height, win.width * win.height * scale * scale))
+    },
+  )
+
+  let last = 0
+  onFrame(tick => {
+    let t = tick / 1000
+    let dt = Math.min(MAX_DT, Math.max(0, t - last))
+    last = t
+    let rx = WORLD.width / 2 + Math.sin(t * ROAM_RATE_X) * WORLD.width * ROAM_SPAN
+    let ry = WORLD.height / 2 + Math.sin(t * ROAM_RATE_Y) * WORLD.height * ROAM_SPAN
+    setSprite(roamer, { x: rx, y: ry, rotation: t })
+    roamerAt.x = rx
+    roamerAt.y = ry
+    if (following) cam.follow(rx, ry)
+    if (spinning) cam.set({ rotation: cam.camera().rotation! + SPIN_RATE * dt })
+    cam.update(dt)
+  })
+
+  return (
+    <window
+      onKeyDown={e => {
+        if (e.key === "f") {
+          following = !following
+          if (!following) cam.unfollow()
+        } else if (e.key === "r") {
+          spinning = !spinning
+        } else if (e.key === " ") {
+          following = false
+          cam.unfollow()
+          cam.fit(undefined, { glide: true })
+        }
+      }}
+    >
+      <texture src={view.texture} position="absolute" left={0} top={0} width={windowSize().width} height={windowSize().height} {...view.handlers} />
+      <view pointerEvents="none" gap={6} padding={20}>
+        <text color="#eef4ff" fontSize={24} fontWeight={700}>
+          Camera
+        </text>
+        <text color="#a9bcd6" fontSize={15}>
+          drag empty space to pan (flick for inertia) - wheel or pinch to zoom - tap empty space to glide there - tap a sprite to select, drag it to move - F follow - R spin - Space fit
+        </text>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)
+
+registerDebug("camera", (args?: Record<string, unknown>) => {
+  let pose: Record<string, number> = {}
+  for (let key of ["x", "y", "zoom", "rotation"]) {
+    if (typeof args?.[key] === "number") pose[key] = args[key] as number
+  }
+  if (Object.keys(pose).length > 0) cam.set(pose)
+  return cam.camera()
+})
+
+registerDebug("mode", (args?: Record<string, unknown>) => {
+  if (typeof args?.follow === "boolean") {
+    following = args.follow
+    if (!following) cam.unfollow()
+  }
+  if (typeof args?.spin === "boolean") spinning = args.spin
+  if (args?.fit === true) cam.fit(undefined, { glide: true })
+  return { following, spinning, roamer: { ...roamerAt } }
+})
+
+registerDebug("selected", () => (selected ? { x: selected._x, y: selected._y } : null))
+registerDebug("first", () => (first ? { x: first._x, y: first._y } : null))

package/examples/parity.tsx

@@ -7,7 +7,7 @@
 // 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 { decodeImage, onFrame, render } from "@solidrt/core"
 import { readTexture } from "@solidrt/core/gpu"
 import {
   addGroup,
@@ -42,10 +42,12 @@ function rng(seed: number): () => number {
 }
 
 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 atlas = createAtlas(decodeImage(logoBytes), { label: "logo-atlas" })
+  let frames = grid(atlas, 2, 2)
+  let nodes = createSpriteLayer(atlas.texture, { capacity: 64, label: "nodes" })
+  let records = createRecordLayer(atlas.texture, { capacity: 64, label: "records" })
+  let nodeView = nodes.createView({ width: W, height: H, clearColor: [0.05, 0.05, 0.09, 1], label: "nodes" })
+  let recordView = records.createView({ width: W, height: H, clearColor: [0.05, 0.05, 0.09, 1], label: "records" })
 
   let fields = (r: () => number) => ({
     x: 20 + r() * (W - 40),
@@ -89,8 +91,8 @@ function App() {
   }
 
   let pixelParity = () => {
-    let a = readTexture(nodes.texture)
-    let b = readTexture(records.texture)
+    let a = readTexture(nodeView.texture)
+    let b = readTexture(recordView.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
@@ -119,8 +121,8 @@ function App() {
     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 a = nodes.pick(x, y)[0] ?? null
+      let b = records.pick(x, y)[0] ?? null
       let ai = a ? byNode.get(a) : null
       let bi = b ? byRec.get(b) : null
       if (ai !== bi) mismatches++
@@ -152,8 +154,8 @@ function App() {
     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")
+      check(nodes.pick(100, 150)[0] === child, "group rotation carries the child sprite")
+      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)
@@ -195,8 +197,8 @@ function App() {
 
   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} />
+      <texture src={nodeView.texture} width={W} height={H} />
+      <texture src={recordView.texture} width={W} height={H} />
     </window>
   )
 }