@solidrt/2d 0.0.55 → 0.0.56

package/src/layer.ts

@@ -11,8 +11,8 @@
 //
 // Two instance-buffer slots split ownership: slot 0 is the pose buffer,
 // written ONLY by the core (one coalesced write per flush however many
-// nodes moved); slot 1 is the style buffer [u0, v0, u1, v1, tint rgba],
-// JS-owned and published through the zero-copy write lease. Never write
+// nodes moved); slot 1 is the style buffer [u0, v0, u1, v1, tint rgba,
+// renderOrder], JS-owned and published through the zero-copy write lease. Never write
 // the pose buffer from JS - the core's staging mirror is the owner and
 // will overwrite. For motion only JS can compute at large populations, the
 // records layer (records.ts) is the escape hatch.
@@ -20,9 +20,12 @@
 // Sprites hold FIXED instance slots (freed slots recycle): draw order is
 // slot order, so removal never shifts records and pose sinks never rebind.
 // Layer space is pixels, top-left origin, y-down - the render tree's
-// frame. The camera is a shared-params write (uCamera), never per-sprite.
+// frame. The camera (offset, zoom, rotation about a pivot - CameraUpdate
+// in camera.ts) is a shared-params write (uCamera + uCameraRot), never
+// per-sprite; pointer dispatch (dispatch.ts) undoes it with
+// unprojectCamera.
 import { getOwner, onCleanup } from "@solidrt/core"
-import type { PointerEvent as ElementPointerEvent } from "@solidrt/core"
+import type { PointerEvent as ElementPointerEvent, WheelEvent as ElementWheelEvent } from "@solidrt/core"
 import {
   beginBufferWrite,
   createBuffer,
@@ -38,7 +41,10 @@ import type { BufferId, TextureId } from "@solidrt/core/gpu"
 import * as spatial from "flux:spatial"
 import type { NodeId, NodeTransition } from "flux:spatial"
 import { on } from "srt:events"
-import { checkOversample } from "./oversample.ts"
+import { checkCamera, projectCamera, unprojectCamera } from "./camera.ts"
+import type { CameraState, CameraUpdate } from "./camera.ts"
+import { spriteDispatch } from "./dispatch.ts"
+import { checkOversample, thrashSentinel } from "./oversample.ts"
 import type { Frame } from "./frames.ts"
 import { FULL_FRAME, writeFrame } from "./frames.ts"
 import type { RecordLayer } from "./records.ts"
@@ -46,8 +52,16 @@ import { FRAGMENT, INSTANCE_ATTRIBUTES_SPLIT, VERTEX_SPLIT } from "./shaders.ts"
 
 /** Floats per pose record (the core's Pose2D projection). */
 export const POSE_FLOATS = 5
-/** Floats per style record: [u0, v0, u1, v1, tintR, tintG, tintB, tintA]. */
-export const STYLE_FLOATS = 8
+
+// Float offset of world y in a pose record - what `orderBy: "y"` keys on.
+const POSE_Y_FIELD = 1
+/** Floats per style record:
+ * [u0, v0, u1, v1, tintR, tintG, tintB, tintA, renderOrder]. */
+export const STYLE_FLOATS = 9
+
+// Float offset of renderOrder in a style record - what `orderBy: "renderOrder"`
+// keys on.
+const STYLE_KEY_FIELD = 8
 
 const RESOLVED = Promise.resolve()
 
@@ -56,7 +70,9 @@ const TRANSFORM = new Float32Array(10)
 const FLAT_BOUNDS = new Float32Array([-0.5, -0.5, 0, 0.5, 0.5, 0])
 const RAY_ORIGIN = new Float32Array(3)
 const RAY_DIR = new Float32Array([0, 0, 1])
-const BOX = new Float32Array(6)
+const BOX = new Float32Array([0, 0, 0, 0, 0, 1, 0, 0, 0, 1])
+// worldPosition's world-matrix scratch (column-major; translation at 12, 13).
+const WORLD = new Float32Array(16)
 
 // Settle routing: the core's "spatialTransitionEnd" event carries the node
 // id, so the handles with a transition DECLARED are indexed by node (only
@@ -91,37 +107,60 @@ function declareTransition(node: NodeId, handle: Sprite | SpriteGroup, transitio
  * fields - they touch no GPU state (the scene-graph handler rule).
  */
 export type Sprite = {
-  /** The owning layer, null after removeSprite. */
-  layer: SpriteLayer | RecordLayer | null
+  /** The owning layer, null after removeSprite (which owns the write). */
+  readonly layer: SpriteLayer | RecordLayer | null
   /**
    * The sprite's SPATIAL ARENA node - the citizenship handle: bind core
    * producers to it or reach it through flux:spatial directly (the layer
    * still owns the node's life; destroy it only via removeSprite). Null
    * on a record layer's sprites.
    */
-  node: NodeId | null
+  readonly node: NodeId | null
   /** Instance slot: fixed for the sprite's life on the node layer, the
-   * shifting draw-order index on a record layer. */
-  _slot: number
-  /** Pose mirror (node layer): what setSprite composes transforms from. */
-  _x: number
-  _y: number
-  _w: number
-  _h: number
-  _rot: number
-  /** Mirror flags (both layer kinds): re-applied to every frame write. */
-  _flipX: boolean
-  _flipY: boolean
+   * shifting draw-order index on a record layer. Readable (readonly, like
+   * the other underscore fields: cheap reads without getSprite's
+   * allocation); writes go through setSprite. */
+  readonly _slot: number
+  /** Pose mirror (node layer): what setSprite composes transforms from.
+   * On a RECORD layer this mirror goes stale once records are written
+   * raw - there the records array is the truth. */
+  readonly _x: number
+  readonly _y: number
+  readonly _w: number
+  readonly _h: number
+  readonly _rot: number
+  /** Mirror flags (both layer kinds): re-applied to every frame write.
+   * The cheap way to read flip state. */
+  readonly _flipX: boolean
+  readonly _flipY: boolean
+  /** Visibility mirror (node layer; always true on a record layer's
+   * sprites). The cheap read; writes go through setSprite. */
+  readonly _visible: boolean
+  /** The enclosing group (null at the layer root, always null on a record
+   * layer's sprites) - the bubble path; writes go through
+   * setSpriteParent/addSprite's `parent`. */
+  readonly _parent: SpriteGroup | null
   onPointerDown?: (event: SpritePointerEvent) => void
   onPointerMove?: (event: SpritePointerEvent) => void
   onPointerUp?: (event: SpritePointerEvent) => void
   onPointerEnter?: (event: SpritePointerEvent) => void
   onPointerLeave?: (event: SpritePointerEvent) => void
+  /** A wheel notch over the sprite; bubbles like down/move/up. */
+  onWheel?: (event: SpriteWheelEvent) => void
+  /** A press that released on this sprite without dragging (see
+   * SpriteTapEvent); bubbles like down/move/up. */
+  onTap?: (event: SpriteTapEvent) => void
   /** A declared transition (setSpriteTransition) settled naturally on
    * one component; a cancel or snap never fires. */
   onTransitionEnd?: (event: TransitionEndEvent) => void
 }
 
+/** The layer-internal mutable view of a Sprite: the readonly on the
+ * underscore fields is for the public surface; internal write sites
+ * annotate with this (readonly does not affect assignability, so the two
+ * types flow into each other freely). */
+export type SpriteState = { -readonly [K in keyof Sprite]: Sprite[K] }
+
 /** The settled component of a node transition: `position` is x/y,
  * `scale` w/h (a group's uniform scale). */
 export type TransitionEndEvent = {
@@ -148,17 +187,35 @@ export type SpriteOptions = {
   rotation?: number
   /** RGBA multiplier 0..1 each; default opaque white (the texture as-is). */
   tint?: [number, number, number, number]
+  /**
+   * Explicit draw-order key, read only by a layer created with `orderBy:
+   * "renderOrder"` (default 0; ties keep slot order, so untouched sprites draw
+   * as without one). The raise idiom: `setSprite(hit, { renderOrder: ++top })`
+   * on interaction, back to 0 to restore. Node layer only - a record
+   * layer's 13-float record has no key field (order it by one of its own
+   * fields with `orderBy: { field }`); setting this there throws.
+   */
+  renderOrder?: number
+  /**
+   * Show or hide the sprite (default true), @solidrt/3d's setVisible in
+   * the setSprite bag: hidden, its pose slot zeroes (nothing drawn) and
+   * pick/pickRect skip it; the handle, slot, style records and any
+   * running transition state stay, so showing again restores the sprite
+   * as it was. Node layer only - a record sprite has no node (hide it by
+   * zeroing w or h); setting this there throws.
+   */
+  visible?: boolean
 }
 
 export type AddSpriteOptions = SpriteOptions & {
-  /** Mount under this group (node layer only); pose fields are then local
-   * to it. Reparent later with setSpriteParent. */
-  parent?: SpriteGroup
+  /** Mount under this group (node layer only; null = the layer root, the
+   * default); pose fields are then local to it. Reparent later with
+   * setSpriteParent. */
+  parent?: SpriteGroup | null
 }
 
-export type SpritePointerEvent = {
-  /** The sprite hit (the topmost at the point), constant while captured. */
-  sprite: Sprite
+/** What every layer pointer event carries, whichever handler sees it. */
+export type LayerEventBase = {
   /** Pointer position in LAYER pixels (the camera mapping undone). */
   x: number
   y: number
@@ -169,6 +226,74 @@ export type SpritePointerEvent = {
   ctrlKey: boolean
   altKey: boolean
   metaKey: boolean
+  /**
+   * The element event the layer's leaf received, in the leaf's own frame
+   * (localX/localY, clientX/clientY, movementX/Y): what core's
+   * recognizers consume, so a sprite drags itself through `createPan` and
+   * a camera rides `createTransform` on the same events the walk carries.
+   */
+  native: ElementPointerEvent
+  /**
+   * Stops the walk after the current handler: no enclosing group and none
+   * of the layer's listeners see the event. Stopping a DOWN claims the
+   * whole press - that pointer's move, up and tap never reach the layer
+   * either, so a sprite that drags itself stops its down once and a
+   * camera attached at the root never pans it.
+   */
+  stopPropagation(): void
+}
+
+/** The event as a sprite's or group's handler sees it. */
+export type SpritePointerEvent = LayerEventBase & {
+  /** The sprite the event is about (the topmost hit at the point, or the
+   * captured sprite during a drag) - constant while the event bubbles. */
+  sprite: Sprite
+  /** The sprite or group whose handler is running; changes as the event
+   * bubbles from the hit sprite through its enclosing groups. */
+  currentTarget: Sprite | SpriteGroup
+}
+
+/**
+ * The event as the LAYER's listeners see it (LayerBase.listen), the last
+ * stop of the walk: `sprite` is the hit sprite it bubbled from, or null
+ * over empty space, where the layer is the only target.
+ */
+export type LayerPointerEvent = LayerEventBase & {
+  sprite: Sprite | null
+  currentTarget: SpriteLayer | RecordLayer
+}
+
+type WheelFields = {
+  /** The wheel delta as the element event reports it. */
+  deltaX: number
+  deltaY: number
+  native: ElementWheelEvent
+}
+type TapFields = {
+  /** 1 for a tap, 2 for the second of a double tap (the same target,
+   * within the repeat interval and distance), and so on - DOM's `detail`,
+   * Unity's `clickCount`. */
+  tapCount: number
+}
+
+export type SpriteWheelEvent = SpritePointerEvent & WheelFields
+export type LayerWheelEvent = LayerPointerEvent & WheelFields
+/**
+ * A press that released on the target it pressed without travelling past
+ * the slop, the only pointer down for its whole press (a pinch never taps).
+ * Dispatched after the up, bubbling the same way; `x`/`y` are the release
+ * point.
+ */
+export type SpriteTapEvent = SpritePointerEvent & TapFields
+export type LayerTapEvent = LayerPointerEvent & TapFields
+
+/** A listener at the layer root; see LayerBase.listen. */
+export type LayerPointerListener = {
+  onPointerDown?: (event: LayerPointerEvent) => void
+  onPointerMove?: (event: LayerPointerEvent) => void
+  onPointerUp?: (event: LayerPointerEvent) => void
+  onWheel?: (event: LayerWheelEvent) => void
+  onTap?: (event: LayerTapEvent) => void
 }
 
 export type SpriteHandlers = {
@@ -176,14 +301,15 @@ export type SpriteHandlers = {
   onPointerMove: (event: ElementPointerEvent) => void
   onPointerUp: (event: ElementPointerEvent) => void
   onPointerLeave: (event: ElementPointerEvent) => void
+  onWheel: (event: ElementWheelEvent) => void
 }
 
-export type CameraUpdate = {
-  /** World pixel at the viewport's top-left corner. */
-  x?: number
-  y?: number
-  /** World-to-screen scale; 1 is pixel-for-pixel. */
-  zoom?: number
+/** Validate an [r, g, b, a] tint (throws - the dev validation policy).
+ * Internal - every layer kind (sprite, record, tile) calls it. */
+export function checkTint(verb: string, tint: [number, number, number, number]): void {
+  if (!(Array.isArray(tint) && tint.length === 4 && tint.every(Number.isFinite))) {
+    throw new Error(`${verb}: tint must be [r, g, b, a], got ${JSON.stringify(tint)}`)
+  }
 }
 
 export type SpriteLayerOptions = {
@@ -194,6 +320,9 @@ export type SpriteLayerOptions = {
    */
   capacity?: number
   clearColor?: [number, number, number, number]
+  /** Layer tint, [r, g, b, a] in 0..1, multiplied over every sprite's own
+   * tint; default opaque white (sprites as-is). See setTint. */
+  tint?: [number, number, number, number]
   label?: string
   /**
    * Target texels per layer pixel (positive integer, default 1). The layer
@@ -206,6 +335,30 @@ export type SpriteLayerOptions = {
   oversample?: number
   /** Skip the owner-scoped auto-dispose (see createSpriteLayer). */
   autoFree?: boolean
+  /**
+   * Draw sprites in KEY order instead of slot order, produced by core at
+   * every publish (the gpu `instanceOrder` primitive across the pose/style
+   * buffer pair - no per-sprite JS anywhere): `"y"` keys on the sprite's
+   * WORLD y, the pose the core itself writes, so a perspective crowd
+   * paints back to front (smaller y = further up the screen = drawn
+   * first) - and because the key is core-owned, sprites moved by native
+   * transitions or any other core producer re-sort with zero JS per
+   * frame. Slots stay fixed - handles, picking and the style records are
+   * untouched, only the draw order changes - and ties keep slot order, so
+   * sprites at equal y draw exactly as without it.
+   *
+   * `"renderOrder"` keys on the app-owned per-sprite `renderOrder` field instead
+   * (setSprite, default 0): explicit layering for painter-order scenes -
+   * raise a dragged piece, click-to-front, hover emphasis - with stable
+   * handles and no record churn.
+   *
+   * Known limitation for both keys: pick() resolves overlapping sprites by
+   * slot order, not visual order, when a key is set. (The record layer's
+   * RecordLayerOptions instead takes `"y"` or a raw `{ field }` offset
+   * into its own records; pose records are core-owned, so the node layer
+   * names its keys.)
+   */
+  orderBy?: "y" | "renderOrder"
 }
 
 /**
@@ -213,21 +366,44 @@ export type SpriteLayerOptions = {
  * uniform scale - never a sprite size) that sprites and other groups
  * parent under, so a ship with turrets or a dragged stack moves as one
  * subtree recomputed in native code. Groups render nothing and cannot be
- * picked; sprites are always the leaves.
+ * picked - sprites are always the leaves - but down/move/up events bubble
+ * from a hit child sprite through its enclosing groups (enter/leave pair
+ * on the sprite alone), so one group handler covers a whole assembly.
  */
 export type SpriteGroup = {
-  /** The owning layer, null after removeGroup. */
-  layer: SpriteLayer | null
+  /** The owning layer, null after removeGroup (which owns the write). */
+  readonly layer: SpriteLayer | null
   /** The group's spatial arena node. */
-  node: NodeId
-  _x: number
-  _y: number
-  _rot: number
-  _scale: number
+  readonly node: NodeId
+  /** Pose mirror (readonly, like Sprite's underscore fields: cheap reads);
+   * writes go through setGroup. */
+  readonly _x: number
+  readonly _y: number
+  readonly _rot: number
+  readonly _scale: number
+  /** Visibility mirror; writes go through setGroup. */
+  readonly _visible: boolean
+  /** See Sprite._parent. */
+  readonly _parent: SpriteGroup | null
+  /** The handles parented here (removeGroup removes them with it);
+   * internal -
+   * membership writes go through addSprite/addGroup/setSpriteParent/
+   * setGroup. */
+  readonly _children: Set<SpriteState | GroupState>
+  /** Bubbled from a hit child sprite; see SpritePointerEvent. A group
+   * never receives enter/leave (hover pairs on the sprite alone). */
+  onPointerDown?: (event: SpritePointerEvent) => void
+  onPointerMove?: (event: SpritePointerEvent) => void
+  onPointerUp?: (event: SpritePointerEvent) => void
+  onWheel?: (event: SpriteWheelEvent) => void
+  onTap?: (event: SpriteTapEvent) => void
   /** See Sprite.onTransitionEnd. */
   onTransitionEnd?: (event: TransitionEndEvent) => void
 }
 
+/** The layer-internal mutable view of a SpriteGroup (see SpriteState). */
+export type GroupState = { -readonly [K in keyof SpriteGroup]: SpriteGroup[K] }
+
 /** Group fields, all optional: absent keys keep values. */
 export type GroupOptions = {
   /** Position in the parent frame (layer pixels at the root). */
@@ -238,6 +414,10 @@ export type GroupOptions = {
   /** Uniform scale on the whole subtree (this one scales child sprites -
    * a group is a frame, not a sprite size). */
   scale?: number
+  /** Show or hide the group's WHOLE subtree (default true); each child
+   * keeps its own `visible`, so showing the group again restores the
+   * subtree as it was. See SpriteOptions.visible. */
+  visible?: boolean
   /** Reparent (null = make the group a root). */
   parent?: SpriteGroup | null
 }
@@ -246,11 +426,27 @@ export type GroupOptions = {
 export type LayerBase = {
   /** The layer's output: an ordinary texture id (`<texture src>`). */
   texture: TextureId
-  /** Element handlers wiring sprite pointer events; see handlersFor. */
+  /** Element handlers wiring the layer's pointer events (sprites, groups
+   * and the root listeners); see handlersFor. */
   handlers: SpriteHandlers
   /** Live sprite count. */
   readonly count: number
+  /** Layer pixels, as created or last set by setSize. */
+  readonly width: number
+  readonly height: number
   setSize(width: number, height: number): void
+  /**
+   * Listen at the root of the event walk. Every down, move, up, wheel and
+   * tap arrives here after the hit sprite and its enclosing groups
+   * (`sprite` set) or as the walk's only stop over empty space (`sprite`
+   * null), unless a handler stopped it on the way. Listeners run in
+   * registration order and all of them run - the root is the last stop,
+   * there is nothing left to claim. Returns the remover. The app's own
+   * root handling (deselect on a miss, a marquee) and controls
+   * (createCamera2d's attach) meet here, which is why the root is a list
+   * where a sprite has plain fields.
+   */
+  listen(listener: LayerPointerListener): () => void
   /** Target texels per layer pixel; see setOversample. */
   readonly oversample: number
   /**
@@ -262,118 +458,54 @@ export type LayerBase = {
    */
   setOversample(n: number): void
   setCamera(update: CameraUpdate): void
-  /** Topmost sprite whose rotated rect contains the layer-pixel point. */
-  pick(x: number, y: number): Sprite | null
+  /** The camera as last set (a fresh object per call, every field
+   * present): the argument for projectCamera/unprojectCamera -
+   * @solidrt/3d's scene.camera(). */
+  camera(): CameraState
+  /** World (layer) pixels -> viewport pixels under the current camera:
+   * projectCamera over camera(). */
+  project(x: number, y: number): [number, number]
+  /** Viewport pixels -> world (layer) pixels, the inverse: what pointer
+   * dispatch applies to every event. */
+  unproject(x: number, y: number): [number, number]
+  /**
+   * Tint the whole layer, [r, g, b, a] in 0..1: a uniform multiplied over
+   * every sprite's own tint (day/night, a dimmed parallax plane, a
+   * fade-in). One shared-params write - no record touches, cheap to
+   * animate - and the same contract as TileLayer.setTint, so one signal
+   * drives a whole scene across layer kinds.
+   */
+  setTint(tint: [number, number, number, number]): void
+  /** Every shown sprite whose rotated rect contains the layer-pixel point
+   * (a hidden sprite or subtree is never hit), topmost first - the
+   * all-hits shape of @solidrt/3d's pick; `pick(x, y)[0]` is the topmost.
+   * Topmost means draw order (highest slot on the node layer, last added
+   * on a record layer); an `orderBy` key is not consulted (see
+   * SpriteLayerOptions.orderBy's known limitation). */
+  pick(x: number, y: number): Sprite[]
   /**
-   * Handlers for a leaf whose LAYOUT size differs from the layer size
-   * (events scale by layer/layout; null layout means "already layer pixels",
-   * which is what the built-in leaf uses).
+   * handlers for a leaf whose LAYOUT size differs from the layer size
+   * (events scale by layer/layout; a leaf laid out AT layer size just uses
+   * `handlers`). `layout` is read per event, so a resize-reactive layout
+   * just works - @solidrt/3d's handlersFor, one dimension down.
    */
-  handlersFor(layout: (() => { width: number; height: number } | null) | null): SpriteHandlers
+  handlersFor(layout: () => { width: number; height: number }): SpriteHandlers
   dispose(): void
   _add(opts?: AddSpriteOptions): Sprite
-  _write(sprite: Sprite, opts: SpriteOptions): void
+  _write(sprite: SpriteState, opts: SpriteOptions): void
   _read(sprite: Sprite): Required<SpriteOptions>
-  _remove(sprite: Sprite): void
+  _remove(sprite: SpriteState): void
   _schedule(): void
 }
 
 export type SpriteLayer = LayerBase & {
   /**
-   * Every sprite whose rotated rect overlaps the layer-pixel rect (the
-   * core BVH overlap query, exact for rotated sprites), unordered - the
-   * marquee query. Node layer only.
+   * Every shown sprite whose rotated rect overlaps the layer-pixel rect
+   * (the core BVH overlap query, exact for rotated sprites), unordered -
+   * the marquee query. Node layer only.
    */
-  pickRect(x: number, y: number, w: number, h: number): Sprite[]
-  _groups: Set<SpriteGroup>
-}
-
-/**
- * Pointer dispatch shared by both layer kinds: capture per pointer, hover
- * pairing, no bubbling (the sprite list is flat). Layout null = the leaf is
- * laid out at layer size, so localX/localY are layer pixels already (the
- * element hit test undid every ancestor transform - never getBoundingBox
- * here). Internal - layers expose the result as handlers/handlersFor.
- */
-export function spriteDispatch(state: {
-  size: () => [number, number]
-  camera: () => [number, number, number]
-  pick: (x: number, y: number) => Sprite | null
-}): (layout: (() => { width: number; height: number } | null) | null) => SpriteHandlers {
-  let capture = new Map<number, Sprite>()
-  let hover = new Map<number, Sprite>()
-  return layout => {
-    let toLayer = (e: ElementPointerEvent): [number, number] => {
-      let x = e.localX
-      let y = e.localY
-      let l = layout?.()
-      let [width, height] = state.size()
-      if (l && l.width > 0 && l.height > 0) {
-        x *= width / l.width
-        y *= height / l.height
-      }
-      // Undo the camera: screen -> world.
-      let [camX, camY, camZoom] = state.camera()
-      return [x / camZoom + camX, y / camZoom + camY]
-    }
-    let makeEvent = (sprite: Sprite, x: number, y: number, e: ElementPointerEvent): SpritePointerEvent => ({
-      sprite,
-      x,
-      y,
-      pointerId: e.pointerId,
-      pointerType: e.pointerType,
-      button: e.button,
-      shiftKey: e.shiftKey,
-      ctrlKey: e.ctrlKey,
-      altKey: e.altKey,
-      metaKey: e.metaKey,
-    })
-    return {
-      onPointerDown(e) {
-        let [x, y] = toLayer(e)
-        let hit = state.pick(x, y)
-        if (!hit) return
-        capture.set(e.pointerId, hit)
-        hit.onPointerDown?.(makeEvent(hit, x, y, e))
-      },
-      onPointerMove(e) {
-        let [x, y] = toLayer(e)
-        let captured = capture.get(e.pointerId)
-        if (captured) {
-          if (captured.layer) captured.onPointerMove?.(makeEvent(captured, x, y, e))
-          return
-        }
-        let hit = state.pick(x, y)
-        let prev = hover.get(e.pointerId) ?? null
-        if (prev !== hit) {
-          if (prev && prev.layer) prev.onPointerLeave?.(makeEvent(prev, x, y, e))
-          if (hit) hit.onPointerEnter?.(makeEvent(hit, x, y, e))
-          if (hit) hover.set(e.pointerId, hit)
-          else hover.delete(e.pointerId)
-        }
-        hit?.onPointerMove?.(makeEvent(hit, x, y, e))
-      },
-      onPointerUp(e) {
-        let [x, y] = toLayer(e)
-        let captured = capture.get(e.pointerId)
-        if (captured) {
-          capture.delete(e.pointerId)
-          if (captured.layer) captured.onPointerUp?.(makeEvent(captured, x, y, e))
-          return
-        }
-        let hit = state.pick(x, y)
-        hit?.onPointerUp?.(makeEvent(hit, x, y, e))
-      },
-      onPointerLeave(e) {
-        let [x, y] = toLayer(e)
-        let prev = hover.get(e.pointerId)
-        if (prev) {
-          hover.delete(e.pointerId)
-          if (prev.layer) prev.onPointerLeave?.(makeEvent(prev, x, y, e))
-        }
-      },
-    }
-  }
+  pickRect(x: number, y: number, width: number, height: number): Sprite[]
+  _groups: Set<GroupState>
 }
 
 /** The stored UVs at `at` un-mirrored by the sprite's flags: the frame as
@@ -428,6 +560,9 @@ export function createSpriteLayer(
   let label = opts?.label ?? "sprites"
   let oversample = opts?.oversample ?? 1
   checkOversample("createSpriteLayer", oversample, width, height)
+  let tint = opts?.tint ?? [1, 1, 1, 1]
+  checkTint("createSpriteLayer", tint)
+  let thrash = thrashSentinel(`sprite layer "${label}"`)
   // One unit quad (triangle strip), reused by every instance.
   let quad = createBuffer(new Float32Array([-0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, 0.5]), {
     label: `${label}-quad`,
@@ -440,7 +575,7 @@ export function createSpriteLayer(
     FRAGMENT,
     width * oversample,
     height * oversample,
-    { uViewport: [width, height], uCamera: [0, 0, 1, 1] },
+    { uViewport: [width, height], uCamera: [0, 0, 1, 1], uCameraRot: [1, 0, 0, 0], uTint: tint },
     {
       label,
       topology: "triangle-strip",
@@ -449,6 +584,16 @@ export function createSpriteLayer(
       buffer: quad,
       instanceAttributes: INSTANCE_ATTRIBUTES_SPLIT,
       instanceBuffers: [pose, style],
+      // "y" keys on world y in the pose record (slot 0), "renderOrder" on the
+      // app-owned key in the style record (slot 1); either way the core
+      // gathers BOTH buffers under the one permutation at every publish
+      // and republishes the sibling itself when the key buffer re-orders.
+      instanceOrder:
+        opts?.orderBy === "y"
+          ? { field: POSE_Y_FIELD }
+          : opts?.orderBy === "renderOrder"
+            ? { field: STYLE_KEY_FIELD, slot: 1 }
+            : undefined,
       instanceCount: 0,
       blend: "alpha",
       textures: { uAtlas: atlas },
@@ -461,6 +606,9 @@ export function createSpriteLayer(
   let camX = 0
   let camY = 0
   let camZoom = 1
+  let camRot = 0
+  let camPivotX = 0
+  let camPivotY = 0
   let disposed = false
   let scheduled = false
   let styleDirty = false
@@ -473,7 +621,7 @@ export function createSpriteLayer(
   let freeSlots: number[] = []
   let gpuCapacity = capacity
   let styleData = new Float32Array(capacity * STYLE_FLOATS)
-  let byNode = new Map<NodeId, Sprite>()
+  let byNode = new Map<NodeId, SpriteState>()
 
   let flush = () => {
     scheduled = false
@@ -514,7 +662,7 @@ export function createSpriteLayer(
     styleDirty = true
   }
 
-  let writeStyle = (sprite: Sprite, opts: SpriteOptions) => {
+  let writeStyle = (sprite: SpriteState, opts: SpriteOptions) => {
     let at = sprite._slot * STYLE_FLOATS
     let flipX = opts.flipX !== undefined && opts.flipX !== sprite._flipX
     let flipY = opts.flipY !== undefined && opts.flipY !== sprite._flipY
@@ -536,13 +684,13 @@ export function createSpriteLayer(
       styleData[at + 7] = opts.tint[3]
       styleDirty = true
     }
+    if (opts.renderOrder !== undefined) {
+      styleData[at + STYLE_KEY_FIELD] = opts.renderOrder
+      styleDirty = true
+    }
   }
 
-  let dispatch = spriteDispatch({
-    size: () => [width, height],
-    camera: () => [camX, camY, camZoom],
-    pick: (x, y) => layer.pick(x, y),
-  })
+  let listeners = new Set<LayerPointerListener>()
 
   let layer: SpriteLayer = {
     texture,
@@ -550,6 +698,12 @@ export function createSpriteLayer(
     get count() {
       return byNode.size
     },
+    get width() {
+      return width
+    },
+    get height() {
+      return height
+    },
     setSize(w, h) {
       if (disposed || (w === width && h === height)) return
       checkOversample("setSize", oversample, w, h)
@@ -558,24 +712,49 @@ export function createSpriteLayer(
       setTargetSize(texture, w * oversample, h * oversample)
       setTargetParams(texture, { uViewport: [w, h] })
     },
+    listen(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
     get oversample() {
       return oversample
     },
     setOversample(n) {
       if (disposed || n === oversample) return
       checkOversample("setOversample", n, width, height)
+      thrash()
       oversample = n
       setTargetSize(texture, width * n, height * n)
     },
     setCamera(update) {
       if (disposed) return
+      checkCamera(update)
       if (update.x !== undefined) camX = update.x
       if (update.y !== undefined) camY = update.y
-      if (update.zoom !== undefined) {
-        if (!(update.zoom > 0)) throw new Error(`setCamera: zoom must be positive, got ${update.zoom}`)
-        camZoom = update.zoom
-      }
-      setTargetParams(texture, { uCamera: [camX, camY, camZoom, camZoom] })
+      if (update.zoom !== undefined) camZoom = update.zoom
+      if (update.rotation !== undefined) camRot = update.rotation
+      if (update.pivotX !== undefined) camPivotX = update.pivotX
+      if (update.pivotY !== undefined) camPivotY = update.pivotY
+      setTargetParams(texture, {
+        uCamera: [camX, camY, camZoom, camZoom],
+        uCameraRot: [Math.cos(camRot), Math.sin(camRot), camPivotX, camPivotY],
+      })
+    },
+    camera() {
+      return { x: camX, y: camY, zoom: camZoom, rotation: camRot, pivotX: camPivotX, pivotY: camPivotY }
+    },
+    project(x, y) {
+      return projectCamera(layer.camera(), x, y)
+    },
+    unproject(x, y) {
+      return unprojectCamera(layer.camera(), x, y)
+    },
+    setTint(next) {
+      if (disposed) return
+      checkTint("setTint", next)
+      setTargetParams(texture, { uTint: next })
     },
     pick(x, y) {
       // The index reads as of the last core flush; run any pending batch
@@ -584,26 +763,29 @@ export function createSpriteLayer(
       RAY_ORIGIN[0] = x
       RAY_ORIGIN[1] = y
       RAY_ORIGIN[2] = -1
-      let best: Sprite | null = null
+      let out: Sprite[] = []
       for (let hit of spatial.raycast(RAY_ORIGIN, RAY_DIR)) {
         // The arena is shared (a 3d scene lives in the same index): only
-        // this layer's nodes count. Topmost = highest slot (draw order).
+        // this layer's nodes count.
         let sprite = byNode.get(hit.node)
-        if (sprite && (best === null || sprite._slot > best._slot)) best = sprite
+        if (sprite) out.push(sprite)
       }
-      return best
+      // Topmost first: higher slot = drawn later = on top.
+      return out.sort((a, b) => b._slot - a._slot)
     },
-    pickRect(x, y, w, h) {
+    pickRect(x, y, width, height) {
       if (scheduled) flush()
-      BOX[0] = x
-      BOX[1] = y
-      BOX[2] = -1
-      BOX[3] = x + w
-      BOX[4] = y + h
+      // The marquee as a "box" volume: center, half extents, no rotation,
+      // a unit deep so every sprite plane (z = 0) lies inside it.
+      BOX[0] = x + width / 2
+      BOX[1] = y + height / 2
+      BOX[2] = 0
+      BOX[3] = width / 2
+      BOX[4] = height / 2
       BOX[5] = 1
       let out: Sprite[] = []
-      for (let node of spatial.overlap(BOX)) {
-        let sprite = byNode.get(node)
+      for (let hit of spatial.overlap("box", BOX)) {
+        let sprite = byNode.get(hit.node)
         if (sprite) out.push(sprite)
       }
       return out
@@ -614,6 +796,7 @@ export function createSpriteLayer(
     dispose() {
       if (disposed) return
       disposed = true
+      listeners.clear()
       for (let sprite of byNode.values()) {
         sprite.layer = null
         declared.delete(sprite.node!)
@@ -638,7 +821,7 @@ export function createSpriteLayer(
       if (disposed) throw new Error("addSprite: layer is disposed")
       let slot = freeSlots.pop() ?? highWater++
       if (slot >= gpuCapacity) grow(gpuCapacity * 2)
-      let sprite: Sprite = {
+      let sprite: SpriteState = {
         layer,
         node: null,
         _slot: slot,
@@ -649,18 +832,23 @@ export function createSpriteLayer(
         _rot: opts?.rotation ?? 0,
         _flipX: false,
         _flipY: false,
+        _visible: opts?.visible ?? true,
+        _parent: opts?.parent ?? null,
       }
       fillTransform(sprite._x, sprite._y, sprite._rot, sprite._w, sprite._h)
-      let node = spatial.createNode(TRANSFORM, true)
+      let node = spatial.createNode(TRANSFORM, sprite._visible)
       sprite.node = node
       if (opts?.parent) {
         if (opts.parent.layer !== layer) throw new Error("addSprite: parent group belongs to another layer")
         spatial.setParent(node, opts.parent.node)
+        opts.parent._children.add(sprite)
       }
       spatial.setBounds(node, FLAT_BOUNDS)
       spatial.bindPoseRecord(node, pose, slot)
       byNode.set(node, sprite)
-      writeStyle(sprite, { frame: FULL_FRAME, tint: [1, 1, 1, 1], ...opts })
+      // renderOrder defaults to 0 explicitly: a recycled slot holds the
+      // previous occupant's key otherwise.
+      writeStyle(sprite, { frame: FULL_FRAME, tint: [1, 1, 1, 1], renderOrder: 0, ...opts })
       layer._schedule()
       return sprite
     },
@@ -672,7 +860,18 @@ export function createSpriteLayer(
       if (opts.h !== undefined && opts.h !== sprite._h) (sprite._h = opts.h), (moved = true)
       if (opts.rotation !== undefined && opts.rotation !== sprite._rot) (sprite._rot = opts.rotation), (moved = true)
       if (moved) writeTransform(sprite)
-      if (opts.frame !== undefined || opts.tint !== undefined || opts.flipX !== undefined || opts.flipY !== undefined) {
+      if (opts.visible !== undefined && opts.visible !== sprite._visible) {
+        sprite._visible = opts.visible
+        spatial.setVisible(sprite.node!, opts.visible)
+        moved = true
+      }
+      if (
+        opts.frame !== undefined ||
+        opts.tint !== undefined ||
+        opts.flipX !== undefined ||
+        opts.flipY !== undefined ||
+        opts.renderOrder !== undefined
+      ) {
         writeStyle(sprite, opts)
       }
       if (moved || styleDirty) layer._schedule()
@@ -689,10 +888,16 @@ export function createSpriteLayer(
         flipY: sprite._flipY,
         rotation: sprite._rot,
         tint: [styleData[at + 4]!, styleData[at + 5]!, styleData[at + 6]!, styleData[at + 7]!],
+        renderOrder: styleData[at + STYLE_KEY_FIELD]!,
+        visible: sprite._visible,
       }
     },
     _remove(sprite) {
       sprite.layer = null
+      if (sprite._parent) {
+        sprite._parent._children.delete(sprite)
+        sprite._parent = null
+      }
       // Destroying the node zeroes its pose slot at the next core flush
       // (zero scale = nothing drawn); the slot then recycles.
       byNode.delete(sprite.node!)
@@ -708,6 +913,13 @@ export function createSpriteLayer(
     },
     _groups: new Set(),
   }
+  let dispatch = spriteDispatch({
+    size: () => [width, height],
+    camera: () => layer.camera(),
+    pick: (x, y) => layer.pick(x, y),
+    root: layer,
+    listeners,
+  })
   layer.handlers = dispatch(null)
 
   if (opts?.autoFree !== false && getOwner()) onCleanup(() => layer.dispose())
@@ -719,7 +931,8 @@ export function createSpriteLayer(
  * order, and a removed sprite's slot recycles to the next add - so unlike
  * the record layer there is no painter's-insertion-order guarantee across
  * removals. Opaque-or-transparent pixel art (the overwhelming case) never
- * notices; z-ordered translucency is the sort-key backlog item. Past the
+ * notices; a scene that needs depth order sorts by world y with the
+ * layer's `orderBy: "y"` (core-produced, zero JS per frame). Past the
  * layer's reservation both instance buffers double (pose sinks move in one
  * core retarget); reserve with `capacity` to avoid the copies.
  */
@@ -745,10 +958,33 @@ export function removeSprite(sprite: Sprite): void {
   sprite.layer?._remove(sprite)
 }
 
+/**
+ * A sprite's or group's position in LAYER pixels: its local x/y composed
+ * through every enclosing group (@solidrt/3d's worldPosition, Three's
+ * getWorldPosition), read from the core's world matrix as the tree stands
+ * now, pending writes included. Under a transition this is the
+ * mid-flight pose - what picking and the screen show - where the handle's
+ * own fields hold the target. A record layer's sprite has no groups, so
+ * its world position is its own, read as getSprite reads it (the records
+ * array). A fresh pair per call; null once the handle is inert.
+ */
+export function worldPosition(target: Sprite | SpriteGroup): [number, number] | null {
+  if (target.layer === null) return null
+  // The set only groups carry tells the two handle kinds apart (as in
+  // removeGroup); a node-less sprite is a record layer's.
+  if (!("_children" in target) && target.node === null) {
+    let s = target.layer._read(target)
+    return [s.x, s.y]
+  }
+  spatial.worldMatrix(target.node!, WORLD)
+  return [WORLD[12]!, WORLD[13]!]
+}
+
 /**
  * Re-parent a sprite under a group (null = back to the layer root); its
  * pose fields then read in the new parent's frame, where the sprite keeps
- * them (it holds its local pose, not its world pose). Node layer only.
+ * them (it holds its local pose, not its world pose; worldPosition reads
+ * the composed one). Node layer only.
  */
 export function setSpriteParent(sprite: Sprite, parent: SpriteGroup | null): void {
   let layer = sprite.layer
@@ -756,6 +992,10 @@ export function setSpriteParent(sprite: Sprite, parent: SpriteGroup | null): voi
   if (sprite.node === null) throw new Error("setSpriteParent: record layers have no groups")
   if (parent && parent.layer !== layer) throw new Error("setSpriteParent: group belongs to another layer")
   spatial.setParent(sprite.node, parent ? parent.node : null)
+  let s: SpriteState = sprite
+  if (s._parent) s._parent._children.delete(s)
+  s._parent = parent
+  if (parent) parent._children.add(s)
   layer._schedule()
 }
 
@@ -796,12 +1036,16 @@ export function addGroup(layer: SpriteLayer, opts?: GroupOptions): SpriteGroup {
     _y: opts?.y ?? 0,
     _rot: opts?.rotation ?? 0,
     _scale: opts?.scale ?? 1,
-  } as SpriteGroup
+    _visible: opts?.visible ?? true,
+    _parent: opts?.parent ?? null,
+    _children: new Set(),
+  } as GroupState
   writeGroupTransform(group)
-  group.node = spatial.createNode(TRANSFORM, true)
+  group.node = spatial.createNode(TRANSFORM, group._visible)
   if (opts?.parent) {
     if (opts.parent.layer !== layer) throw new Error("addGroup: parent group belongs to another layer")
     spatial.setParent(group.node, opts.parent.node)
+    opts.parent._children.add(group)
   }
   layer._groups.add(group)
   layer._schedule()
@@ -816,33 +1060,57 @@ function writeGroupTransform(group: SpriteGroup): void {
 export function setGroup(group: SpriteGroup, opts: GroupOptions): void {
   let layer = group.layer
   if (!layer) return
+  let g: GroupState = group
   let moved = false
-  if (opts.x !== undefined && opts.x !== group._x) (group._x = opts.x), (moved = true)
-  if (opts.y !== undefined && opts.y !== group._y) (group._y = opts.y), (moved = true)
-  if (opts.rotation !== undefined && opts.rotation !== group._rot) (group._rot = opts.rotation), (moved = true)
-  if (opts.scale !== undefined && opts.scale !== group._scale) (group._scale = opts.scale), (moved = true)
+  if (opts.x !== undefined && opts.x !== g._x) (g._x = opts.x), (moved = true)
+  if (opts.y !== undefined && opts.y !== g._y) (g._y = opts.y), (moved = true)
+  if (opts.rotation !== undefined && opts.rotation !== g._rot) (g._rot = opts.rotation), (moved = true)
+  if (opts.scale !== undefined && opts.scale !== g._scale) (g._scale = opts.scale), (moved = true)
   if (moved) {
     writeGroupTransform(group)
     spatial.writeTransform(group.node, TRANSFORM)
   }
+  if (opts.visible !== undefined && opts.visible !== g._visible) {
+    g._visible = opts.visible
+    spatial.setVisible(group.node, opts.visible)
+    moved = true
+  }
   if (opts.parent !== undefined) {
     if (opts.parent && opts.parent.layer !== layer) throw new Error("setGroup: parent group belongs to another layer")
     spatial.setParent(group.node, opts.parent ? opts.parent.node : null)
+    if (g._parent) g._parent._children.delete(g)
+    g._parent = opts.parent
+    if (opts.parent) opts.parent._children.add(g)
     moved = true
   }
   if (moved) layer._schedule()
 }
 
 /**
- * Remove a group: its children (sprites and groups) become layer roots and
- * KEEP THEIR LOCAL POSE, so they jump to root frame unless the caller
- * removes or re-parents them too (a component tree unmounts children first
- * and never sees this). The handle goes inert.
+ * Remove a group AND everything under it: child sprites and groups are
+ * removed with it - Unity's Destroy, Godot's free, the subtree form of
+ * removeSprite. To keep a child, re-parent it out first (setSpriteParent /
+ * setGroup's `parent`). Every removed handle goes inert. A component tree
+ * unmounts children first and never sees the recursion. (@solidrt/3d's
+ * `remove` DETACHES a re-addable subtree instead - its nodes exist outside
+ * a scene; a sprite cannot exist outside its layer, so here remove means
+ * destroy, exactly as it does for removeSprite.)
  */
 export function removeGroup(group: SpriteGroup): void {
   let layer = group.layer
   if (!layer) return
-  group.layer = null
+  let g: GroupState = group
+  // Children first, over a snapshot (each removal edits _children); the
+  // set only groups carry tells the two handle kinds apart.
+  for (let child of [...g._children]) {
+    if ("_children" in child) removeGroup(child)
+    else removeSprite(child)
+  }
+  g.layer = null
+  if (g._parent) {
+    g._parent._children.delete(g)
+    g._parent = null
+  }
   layer._groups.delete(group)
   declared.delete(group.node)
   spatial.destroyNode(group.node)