@solidrt/2d 0.0.55 → 0.0.56

package/AGENTS.md

@@ -18,31 +18,46 @@ moved subtrees in Rust, and picking walks the core BVH.
   `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).
+  `SpriteLayer`/`Sprite`/`Group`/`Camera2d` 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.
+  `[u0, v0, u1, v1, tint rgba, renderOrder]`, 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).
+  opaque-or-transparent pixel art never notices, and a scene that needs a
+  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.
 - 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.
+  rotated-rect via the node's local box) and returns ALL hits topmost
+  first (highest slot) - the all-hits shape of @solidrt/3d's pick, so
+  `pick(x, y)[0]` is the topmost; `pickRect` is the BVH overlap query
+  (exact for rotated sprites, the marquee), unordered. 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.
+  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.
+  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).
+- `visible` (@solidrt/3d's setVisible, in the setSprite/setGroup bag;
+  default true) is core node visibility: hidden, the pose slot zeroes
+  (nothing drawn) and pick/pickRect skip the node; a group's flag hides
+  its WHOLE subtree while each child keeps its own. Handle, slot, style
+  records and transition state stay, so showing restores the sprite as
+  it was. Node layer only - on a record sprite it throws (hide those by
+  zeroing w or h).
 - `flipX`/`flipY` mirror on the UV SIDE: the style/record write swaps
   u0/u1 (v0/v1), so w/h stay the drawn size, a scale transition never sees
   a flip, and picking is unchanged (the vertex stage still carries no
@@ -54,19 +69,82 @@ moved subtrees in Rust, and picking walks the core BVH.
   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
+  rgba]` (`FLOATS_PER_SPRITE`), draw order = insertion order (or key
+  order with `orderBy` - see below), 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
+  sprites: 12.9ms raw records vs 30.8ms via setSprite; both figures are
+  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;
   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.
+- The camera (`setCamera`/the `camera` prop) is ONE `CameraUpdate` type
+  across both layers: offset, zoom, and rotation about a pivot (camera.ts
+  documents the semantics and the heading-upward convention,
+  `rotation = -h - pi/2`). On the sprite layer it is a shared-params
+  write (`uCamera` + `uCameraRot`, the rotation in-shader), one call
+  however many sprites exist; `projectCamera`/`unprojectCamera` export
+  the world <-> screen mapping as pure functions, and pointer dispatch
+  undoes the camera with the latter, so events arrive in world (layer)
+  pixels. Picking itself works in world space and never sees the camera.
+  `layer.camera()` reads the camera back (every field present - the
+  `CameraState` snapshot, @solidrt/3d's scene.camera()) and
+  `layer.project(x, y)` / `layer.unproject(x, y)` are the two pure
+  functions over it.
+- Camera control: `createCamera2d(layer | layers, { viewport: () =>
+  ({ width, height }), world?: { width, height }, min/maxZoom?, pivot?,
+  deadZone?: { width, height }, zoomSpeed?, followSpeed?, inertia?,
+  x?, y?, zoom?, rotation? })` - Godot's Camera2D and Three's
+  MapControls in one control over the shared CameraUpdate: drag to pan
+  with inertia on release, wheel and pinch zoom about the pointer, eased
+  `glideTo`/`fit`, `follow(x, y)` through a dead zone with damping,
+  rotation about the pivot, and world bounds that CONTAIN the view (an
+  axis whose view is wider than the world centers; limits ignore
+  rotation, Godot's rule). The pose is "world point at the pivot", the
+  pivot a viewport fraction defaulting to the center, so `camera().x/y`
+  is the view center and glideTo/follow land there (without a `world`,
+  the default pose puts world 0,0 at the pivot: a fill layer that wants
+  world = screen at rest takes `pivot: { x: 0, y: 0 }`). The first
+  argument is anything with the layers' `setCamera` (a sprite layer, a
+  record layer, both at once, or a signal setter feeding `<TileLayer
+  camera>`). Input runs on core's `createTransform` recognizer like the
+  3d orbit camera (arena arbitration, slop swallowed, one delta per
+  FRAME - a synthetic drag under a frozen clock pans nothing until frames
+  step). Two ways in: `cam.attach(layer)` listens at the layer's root, so
+  the camera sees exactly the presses the sprites let through (a sprite
+  that stops its down keeps the camera out of that drag; a wheel
+  anywhere zooms) and pushes the pose synchronously on input; the raw
+  `cam.handlers` spread onto a leaf without a dispatch (a tile world on
+  its own). Call `cam.update(dt)` from a frame loop (it pushes one
+  setCamera per driven layer when the pose changed and reports that),
+  gated on the reactive `cam.active()` (true while a glide, fling, fit
+  or follow needs frames, false at rest), read `cam.camera()` for
+  projectCamera. 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>` inside `<SpriteLayer>` is all of that wired
+  through context, the 3d `<OrbitCamera>` shape: options read at mount,
+  `viewport` defaulting to the layer's size, frames only while
+  `active()`. Anchors and deltas arrive in the leaf's own frame (core's
+  recognizers measure in the node's frames), so a leaf under a
+  designSize fit pans and zooms correctly. The motion is
+  camera-motion.ts, pure; checks/camera2d-check.ts pins the clamp,
+  anchoring, glides, follow and inertia headless, examples/camera.tsx
+  (function face, attach) and examples/pick.tsx (`<Camera2d>`) are the
+  live guards. Not yet, all additive: two-finger twist rotation,
+  rotation glides, a contain origin other than center, live option
+  props on `<Camera2d>` (the motion reads them once; remount for new
+  bounds).
+- Layer tint (`setTint(rgba)`/the `tint` option and prop, both layer
+  kinds): one `uTint` shared-params write multiplied over every sprite's
+  own tint - day/night, a dimmed parallax plane, a fade-in. Cheap to
+  animate (no record touches), unlike TileLayer's, which re-renders
+  resident chunks. The same contract as TileLayer.setTint, so one signal
+  drives a whole scene across layer kinds.
 - 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
@@ -75,7 +153,11 @@ moved subtrees in Rust, and picking walks the core BVH.
   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
+  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)
@@ -88,8 +170,21 @@ moved subtrees in Rust, and picking walks the core BVH.
   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.
+- 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
+  @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
+  most one animation (add detaches the previous); removed sprites prune
+  lazily on the next step. Works on both layer kinds; with `<Sprite>`,
+  attach via `ref` and leave the `frame` prop off - the clip owns that
+  field (the prop effect passes absent props as undefined, which setSprite
+  keeps, so other props stay reactive).
+- frames.ts, pick.ts, camera.ts, camera-motion.ts and dispatch.ts are pure
+  (no GPU imports) BY DESIGN so they can be checked headless; keep them
+  that way.
 
 ## The baked tile layer (tiles.ts)
 
@@ -108,39 +203,86 @@ 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
+Scrolling never re-bakes: the `<TileLayer>` camera prop (`TileCamera`, an
+alias of the shared `CameraUpdate`) 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. The type IS
+the sprite layer's camera type, so one signal drives a whole rotating
+scene across both layers (sprites ride the same rotation in-shader);
+rotation is the ship-flies-over-the-map camera and costs the same
+transform write. A tile
+world is FINITE, sized at creation - the contract, not a provisional
+limit (recreate to resize; a huge sparse world just picks big numbers,
+empty chunks cost nothing). 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.
+`ref` with `setTile`.
+
+Tinting, two levels: `setTile(col, row, frame, { tint })` writes the
+cell's record tint (same `[r, g, b, a]` 0..1 semantics as a sprite's
+tint; absent keys keep their values, a cell set from empty starts at
+`[1, 1, 1, 1]`), and `setTint(rgba)` / the `tint` option and prop tints
+the whole layer through the shared `uTint` uniform, multiplied over the
+per-cell tints - day/night, a dimmed parallax plane. A layer-tint write
+is not a record write (chunks re-render GPU-side, nothing re-uploads),
+but it does re-render every resident chunk: drive it from slow state,
+not per frame. 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?, oversample?, 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?, oversample?, camera? (TileCamera: x, y, zoom, rotation, pivotX, pivotY), label?, ref? |
+| `SpriteLayer` | width?, height? (layer pixels - both, or neither = FILL: the leaf lays out at 100% of its sized parent and the layer follows its box, so layer pixels are the leaf's own coordinates; mount-fixed, `output` requires explicit sizes, matching `<Scene>` in @solidrt/3d), atlas (TextureId), capacity?, clearColor?, camera?, tint? ([r,g,b,a] 0..1, over the whole layer), oversample?, maxOversample?, orderBy?, label?, ref?, output?, events?, onPointer{Down,Move,Up}?, onWheel?, onTap? (the root of the walk: `event.sprite` is the hit sprite or null over empty space) |
+| `Sprite` | x, y (center; local to the enclosing `<Group>`), w, h, frame?, rotation? (radians, clockwise), tint? ([r,g,b,a] 0..1), visible?, transition?, onPointer{Down,Move,Up,Enter,Leave}?, onWheel?, onTap?, ref? |
+| `Group` | x?, y?, rotation?, scale? (uniform, scales the subtree), visible? (the whole subtree), transition?, onPointer{Down,Move,Up}?, onWheel?, onTap? (bubbled from hit child sprites), ref? |
+| `Camera2d` | createCamera2d's options minus `viewport` (world?, min/maxZoom?, pivot?, deadZone?, zoomSpeed?, followSpeed?, inertia?, x?, y?, zoom?, rotation?), viewport? (`() => { width, height }`, default: the layer's size), ref? - a `<SpriteLayer>` child driving its camera from the layer's root; read at mount |
+| `TileLayer` | cols, rows, tileW, tileH, atlas (TextureId), chunkClearColor?, filter?, chunkTiles?, tint? ([r,g,b,a] 0..1, over the whole layer), oversample?, maxOversample?, 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.
+yourself with `output`, then spread `useSpriteLayer().layer.handlers` onto
+your leaf). `useSpriteLayer()` returns `{ layer, parent }` - the same shape
+as `useScene()` in `@solidrt/3d` - where `parent` is the enclosing
+`<Group>`'s handle (null at the layer root), so imperative
+`addSprite(layer, { parent })` mounts where the JSX sits. `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.
+Pointer events (dispatch.ts, both layer kinds): the DOM event model one
+tree deeper, with the LAYER as the root of the walk. Exact rotated-rect
+containment, topmost sprite first; down/move/up/wheel dispatch on the hit
+sprite, bubble through its enclosing groups and END AT THE LAYER's
+listeners (`layer.listen({...})`, the `<SpriteLayer onPointer*/onWheel/
+onTap>` props) - over empty space the walk is the layer alone, with
+`event.sprite` null. `event.sprite` stays the hit, `currentTarget` the
+handle whose handler runs (the layer at the end), `stopPropagation()`
+stops the walk, and a stopped DOWN claims the whole press: that pointer's
+move, up and tap never reach the layer either (the chain still bubbles).
+That one rule is how a sprite drags itself under a `<Camera2d>` without
+the view panning: stop the down, own the captured moves. Capture is per
+pointerId to the press target, the layer included (a drag from empty
+space keeps delivering to the root as it crosses sprites; a drag from a
+sprite keeps naming it with live coordinates). Enter/leave fire on the
+sprite alone - a group never receives them - while the root sees every
+move, so "hovering empty space" is a root move with `sprite` null. Taps
+are synthesized by the dispatch (DOM click, Unity's click handler):
+`onTap` fires after the up when the press released on the target it
+pressed within the slop (8 window px, core's recognizer slop, so a press
+is never both a tap and a pan), was the only pointer down for its whole
+press (a pinch never taps), with `tapCount` counting repeats within 300
+ms and 20 px on the same target (a double tap is `tapCount === 2`).
+Wheel walks like a move with `deltaX/deltaY`. Every event carries
+`native`, the leaf's element event, for core's recognizers (`createPan`
+to drag a sprite with slop, `createTransform` under the camera); a plain
+`onPointerMove` also fires on hover, so a sprite drag gates on its own
+pressed flag from down to up (`native.button` is set on down/up only).
+Root listeners all run, in registration order (the root is the last
+stop, nothing is left to claim); a record layer has no groups, so the
+chain is the sprite then the root. Event x/y are layer pixels with the
+camera undone. checks/dispatch-check.ts pins the walk, claiming, capture,
+hover, wheel and tap rules headless.
 
 ## Traps
 
@@ -149,7 +291,10 @@ is flat. Event x/y are layer pixels with the camera undone.
   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.
+  cache `layer.records` across addSprite - growth replaces the array and
+  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.
 - 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
@@ -158,8 +303,8 @@ is flat. Event x/y are layer pixels with the camera undone.
 - 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
+  compose. Picking, the pose buffer and `worldPosition` 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`/
@@ -173,6 +318,23 @@ is flat. Event x/y are layer pixels with the camera undone.
   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.
+- `orderBy` on BOTH layers: the core gathers publishes into key order
+  (gpu `instanceOrder`, radix sort + one extra memcpy, no per-record JS),
+  so a y-sorted crowd costs the same flush as an unsorted one. Records
+  and slots stay stably addressed; ties keep slot order; `pick()` still
+  resolves overlap by slot/record order. Records layer keys: "y" or a raw
+  `{ field, descending? }` offset into the 13-float record. Node layer
+  keys: `"y"` - WORLD y from the core-written pose buffer, so sprites
+  moved by native transitions (or any core producer) re-sort with zero JS
+  per frame - or `"renderOrder"` - the app-owned per-sprite `renderOrder`
+  field (style record float 8, default 0; @solidrt/3d's name for the same
+  knob), the explicit-layering key for painter-order scenes: raise a
+  dragged piece with `setSprite(hit, { renderOrder: ++top })`, back to 0
+  to restore. Either way the core gathers
+  pose AND style under ONE permutation and republishes the sibling buffer
+  itself when the key buffer re-orders (the multi-buffer stage of
+  okf/backlog/gpu-instance-order.md). `renderOrder` on a record-layer
+  sprite throws - its 13-float record has no key field.
 - 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
@@ -187,10 +349,14 @@ is flat. Event x/y are layer pixels with the camera undone.
   an atlas uploaded from straight-alpha pixels (`decodeImage(bytes, { alpha:
   "straight" })` + `createTexture`) draws color under transparent texels
   as opaque - the classic "keyed-out backdrop becomes a wash" symptom.
-- `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.
+- Every rotation must agree on direction (clockwise, y-down):
+  `pointInSprite` in pick.ts with the vertex stage's `iRot`, and
+  `projectCamera` in camera.ts with `uCameraRot` and `<TileLayer>`'s view
+  transform. The differential checks (pick-check.ts, camera-check.ts)
+  guard the JS math against oracles but NOT against the shader - if you
+  touch one rotation, touch all, then run examples/camera-probe.tsx (the
+  live guard: shader vs projectCamera, node/record parity, the pointer
+  round trip) and watch for CAMERA-OK.
 - 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
@@ -209,9 +375,14 @@ is flat. Event x/y are layer pixels with the camera undone.
   Both are LAYOUT components: neither can live inside a d-* subtree (the
   insert throws); for a detached parent, `<SpriteLayer output>` hands out
   the texture id for a `<d-texture>` of your own.
-- `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.
+- `chunkClearColor` is PER CHUNK, as named: 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 here. The flip side is FREE
+  TRANSPARENCY: with the default `[0,0,0,0]` clear, a mostly-unwritten
+  tile layer stacked over another composites with no mask, no alpha pass,
+  no shader - a sparse upper world (floating clouds over a sea) just
+  works, and per-cell alpha in the written cells carries through the
+  chunk (transparent clear + alpha blend).
 - Two samplers, two jobs. The ATLAS sampler (createAtlas `filter`) decides
   whether texels are hard blocks ("nearest", pixel art) or smooth
   ("linear"). The LAYER's output sampler (the sprite layer's target, the
@@ -224,12 +395,24 @@ is flat. Event x/y are layer pixels with the camera undone.
   (nearest inside keeps blocks square), the linear composite spreads the
   fraction over one device pixel at block edges. The components pick n
   every layout from their leaf's window box (`getBoundingBoxViewport` x
-  `displayScale()`, which composes designSize fits and camera zoom), within
+  `displayScale()`, which composes designSize fits and camera zoom; the
+  tile layer divides its camera rotation's AABB swell back out - rotation
+  is not a resolution factor - and shrinks only past a margin so an
+  oscillating measurement cannot re-bake in a loop), within
   a budget of the window's own device pixel count; the
   primitives default to 1 and take `{ oversample }` / `setOversample(n)`
   - with `output` on `<SpriteLayer>` there is no built-in leaf, so set it
-  yourself. Never fix a shimmer by snapping the fit to an integer: the
-  scene should fill its box at any ratio.
+  yourself with the exported `fitOversample`. The window budget bounds one
+  TARGET, which never binds for chunk-sized tile targets: a tile world's
+  texture memory is resident chunks x n squared, and `maxOversample` is
+  the cap that bounds it (auto-pick only; a 2x display otherwise picks 16x
+  the memory of n = 1, silently). A layer whose oversample changes more
+  than a few times in a second warns in the console (thrash: every change
+  resizes and redraws the targets, a tile layer re-bakes every resident
+  chunk) - pin `oversample` or set `maxOversample` when an animated
+  transform or camera legitimately sweeps the scale. Never fix a shimmer by
+  snapping the fit to an integer: the scene should fill its box at any
+  ratio.
 - Retro scrolling habits are the app's, not the layer's: keep the camera
   fractional (rounding it to design pixels makes motion step at the
   rounding rate, not the frame rate), and a game that wants whole-pixel
@@ -242,8 +425,9 @@ is flat. Event x/y are layer pixels with the camera undone.
   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.
+- The sprite layer's camera rotation is IN-SHADER (uCameraRot) on
+  purpose: rotating the layer's OUTPUT leaf instead is wrong - the output
+  is viewport-sized with the camera already applied, so a leaf transform
+  spins the cropped viewport and the corners cut. The tile layer gets
+  away with the transform-on-the-leaf camera only because its composited
+  view is the WORLD, not a viewport of it.

package/examples/README.md

@@ -14,8 +14,25 @@ copy one and adapt it.
   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.
+- `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, attached at the layer's root (`cam.attach(layer)`): drag
+  empty space to pan with inertia, wheel/pinch to zoom about the pointer,
+  tap empty space to glide there (the layer'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 LAYER'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. The `state` debug command reads the
+  camera and sprite positions back.

package/examples/anim.tsx

@@ -0,0 +1,86 @@
+// 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 { 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(logoBytes, { label: "logo-atlas" })
+  let frames = grid(2, 2, { width: atlas.width, height: atlas.height })
+  let layer = createSpriteLayer(W, H, atlas.texture, {
+    clearColor: [0.05, 0.05, 0.09, 1],
+    label: "anim",
+  })
+
+  // 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={layer.texture} width={W} height={H} />
+    </window>
+  )
+}
+
+render(() => <App />)