@solidrt/3d 0.0.56 → 0.0.57

package/src/scene.ts

@@ -1,6 +1,6 @@
 // The retained scene: plain objects, no signals - the hot path (a moved
 // node) is flat imperative code, and reactivity stays at the component
-// boundary (components.tsx). The transform hierarchy itself lives in the
+// boundary (components/). The transform hierarchy itself lives in the
 // spatial core (flux:spatial): every node in a scene has a core node, JS
 // keeps the LOCAL transform as the readable source of truth and forwards
 // each write, and the core's flush recomputes only the moved subtrees and
@@ -38,10 +38,10 @@
 
 import { addDraw, createCubeDrawTarget, createDrawTarget, depthTexture, destroyProgram, destroyRenderPipeline, destroyTexture, removeDraw, renderTarget, setDrawBuffers, setDrawOrder, setDrawParams, setDrawTextures, setTargetParams, setTargetRect, setTargetSize, setTargetTextures } from "@solidrt/core/gpu"
 import * as spatial from "flux:spatial"
-import type { NodeId } from "flux:spatial"
+import type { Impact as CoreImpact, NodeId, QueryFilter } from "flux:spatial"
 import type { DrawId, FilterMode, ProgramId, RenderPipelineId, ShaderParams, TextureId, WrapMode } from "@solidrt/core/gpu"
 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 { copy, mat4, transformPoint } from "./math.ts"
 import { linearColor } from "./color.ts"
 import type { Mat4, Quat, Vec3, Vec4 } from "./math.ts"
@@ -59,7 +59,7 @@ import type { Prefilter } from "./environment.ts"
 import type { Material } from "./material.ts"
 import { orderEntries } from "./order.ts"
 import { fillTransform, leaveScene, makeNode, worldInto } from "./node.ts"
-import type { SceneHooks, SceneNode, ScenePointerEvent } from "./node.ts"
+import type { SceneHooks, SceneNode, ScenePointerListener } from "./node.ts"
 import { checkInstancePairing, checkMask, instanceBinding, localBounds, publishInstanceStyle } from "./mesh.ts"
 import type { InstancedMesh, InstanceNode, Mesh } from "./mesh.ts"
 import type { CastingLight, Light } from "./light.ts"
@@ -183,15 +183,52 @@ export type Overlap = { mesh: Mesh; instance?: InstanceNode; point: Vec3; normal
  * Godot's KinematicCollision3D). `instance` as on Overlap. */
 export type Impact = { mesh: Mesh; instance?: InstanceNode; time: number; point: Vec3; normal: Vec3 }
 
-/** Element handlers wiring a scene's pointer events: spread onto whatever
- * element shows `scene.texture` (the built-in `<Scene>` leaf wires them
- * automatically). `scene.handlers` expects the leaf laid out at the target
- * size; a split-resolution leaf (supersampling) uses scene.handlersFor. */
+export type MoveOptions = QueryOptions & {
+  /** The direction floors face (default [0, 1, 0]). */
+  up?: Vec3
+  /** Largest angle (radians) between a contact normal and `up` that still
+   * counts as floor (default 45 degrees). Steeper contacts are walls, and
+   * the body slides down them. */
+  floorMaxAngle?: number
+  /** Most contacts one call slides along (default 6). */
+  maxSlides?: number
+  /** Gap kept from every surface, world units (default 0.01). */
+  skin?: number
+  /** How far below the body a floor is pulled to when the motion does not
+   * rise (default 0.1; 0 disables): what keeps a walker on a ramp going
+   * down, and what decides `floor` at the end of the move - a body that
+   * ends higher than this above its floor is airborne, whatever it
+   * touched on the way. A rising motion (a jump) never snaps. */
+  floorSnap?: number
+}
+
+export type MoveResult = {
+  /** The displacement the body gets: add it to the body's position. */
+  motion: Vec3
+  /** The unit normal of the floor the body ends the move on - within
+   * `floorSnap` below it, snapped onto - else null (airborne, or on a
+   * slope too steep to stand on). With `floorSnap: 0` it is a floor met
+   * during the move instead. */
+  floor: Vec3 | null
+  /** Whether a wall (a contact steeper than a floor and flatter than a
+   * ceiling) or a ceiling was met. */
+  wall: boolean
+  ceiling: boolean
+  /** Every contact met, in order, the floor snap's last. */
+  hits: Impact[]
+}
+
+/** Element handlers wiring a scene's (or a view's) pointer events: spread
+ * onto whatever element shows its texture (the built-in `<Scene>` and
+ * `<View3d>` leaves wire them automatically). `scene.handlers` expects
+ * the leaf laid out at the target size; a split-resolution leaf
+ * (supersampling) uses scene.handlersFor. */
 export type SceneHandlers = {
   onPointerDown(event: ElementPointerEvent): void
   onPointerMove(event: ElementPointerEvent): void
   onPointerUp(event: ElementPointerEvent): void
   onPointerLeave(event: ElementPointerEvent): void
+  onWheel(event: ElementWheelEvent): void
 }
 
 /**
@@ -447,7 +484,7 @@ export type ViewOptions = {
 }
 
 /** A second rendering of a scene from its own camera; see Scene.createView. */
-export type View = {
+export type ViewHandle = {
   /** The view's output, an ordinary texture id. */
   texture: TextureId
   /** The view target's depth as a sampler-only texture id when created
@@ -469,6 +506,22 @@ export type View = {
   /** Replace the view's layer mask (bitmask): entries for newly admitted
    * meshes attach, masked-out ones detach. */
   setLayers(mask: number): void
+  /** The camera ray through one of the VIEW's pixels, hits nearest first:
+   * scene.pick through this view's camera and size, so a mesh under a
+   * minimap is picked where the minimap shows it (the scene's query
+   * filters apply: visibility, the view's own layer mask is not one). */
+  pick(x: number, y: number): Hit[]
+  /** Element pointer handlers for the element showing `texture`: the
+   * scene's dispatch with THIS VIEW as the root of the walk - nodes get
+   * their ordinary handlers, picked through the view's camera, the
+   * view's `listen` is the last stop, `x`/`y` are view pixels. The
+   * `<View3d>` leaf carries them; an `output` leaf spreads them itself. */
+  handlers: SceneHandlers
+  /** handlers for a leaf laid out at another size; exactly
+   * scene.handlersFor. */
+  handlersFor(layout: () => { width: number; height: number }): SceneHandlers
+  /** A listener at this view's root; exactly scene.listen. */
+  listen(listener: ScenePointerListener): () => void
   /** Destroy the view's target (its entries die with it). Idempotent;
    * views also die with their scene. */
   dispose(): void
@@ -708,6 +761,21 @@ export type Scene = {
    * a wall. A zero motion touches nothing. Same testing as overlap().
    */
   sweep(volume: Volume, motion: Vec3, opts?: QueryOptions): Impact[]
+  /**
+   * Move a body `motion` through the scene's colliders, sliding along
+   * what it hits (Godot's move_and_slide, Unity's CharacterController.Move):
+   * a capsule for a character, a sphere for a ball, a box for a crate.
+   * The body first pushes out of anything it starts inside, then sweeps
+   * and slides up to `maxSlides` times, then, unless the motion rises,
+   * snaps down onto a floor within `floorSnap` - the floor it reports is
+   * the one it ends on. One core call per body per frame; the loop's
+   * sweeps and overlaps never leave the core. Colliders are whatever
+   * `opts` selects (`layers`/`meshes`, as for sweep). Gravity is the
+   * caller's: fold the fall into `motion` each frame, zero it while
+   * `floor` is set (the snap keeps reporting the floor while the body
+   * stands still); a walkable floor absorbs the vertical part.
+   */
+  moveAndSlide(volume: Volume, motion: Vec3, opts?: MoveOptions): MoveResult
   /**
    * pick()'s ray half (Unity's ScreenPointToRay, Godot's
    * project_ray_origin/normal): the camera ray through a scene pixel,
@@ -719,17 +787,25 @@ export type Scene = {
    */
   screenRay(x: number, y: number): ScreenRay
   /**
-   * Element pointer handlers driving the mesh event fields
-   * (onPointerDown/Move/Up/Enter/Leave on nodes): spread onto the element
-   * that shows `scene.texture`. The `<Scene>` component's built-in leaf
-   * carries them automatically; with `output` (or imperative use), spread
-   * them yourself: `<texture src={scene.texture} {...scene.handlers} />`.
-   * Semantics mirror element pointer events: nearest hit wins, down/move/
-   * up bubble mesh -> ancestors, pointer-down captures the mesh until up
-   * (moves keep flowing to it off-mesh, the platform's captured-drag
-   * rule), enter/leave pair on hover changes. Hover reacts to pointer
-   * MOTION - a mesh animating under a still pointer fires nothing until
-   * the pointer moves (the element hit-test has the same limit).
+   * Element pointer handlers driving the node event fields
+   * (onPointerDown/Move/Up/Enter/Leave/Wheel/Tap on nodes) and the
+   * scene's listeners: spread onto the element that shows
+   * `scene.texture`. The `<Scene>` component's built-in leaf carries them
+   * automatically; with `output` (or imperative use), spread them
+   * yourself: `<texture src={scene.texture} {...scene.handlers} />`.
+   * The element event model one tree deeper, with the scene as the root
+   * of the walk: the nearest hit is the target (the struck instance of an
+   * instanced mesh, else the mesh), down/move/up/wheel bubble through its
+   * ancestors and end at the scene's listeners (`listen`); over empty
+   * space the walk is the scene alone. stopPropagation stops the walk,
+   * and a stopped down claims the whole press. Capture is per pointer to
+   * the press target, the scene included: a drag keeps delivering to what
+   * it pressed, with `point`/`distance` null while the ray misses it.
+   * Enter/leave pair on the struck node alone, on hover changes. Taps are
+   * synthesized (a same-target release within the slop, alone for the
+   * press, `tapCount` for repeats). Hover reacts to pointer MOTION - a
+   * mesh animating under a still pointer fires nothing until the pointer
+   * moves (the element hit-test has the same limit).
    *
    * Coordinates assume the leaf is LAID OUT at the target size - true for
    * the built-in leaf and a d-texture at natural size, under any ancestor
@@ -743,6 +819,19 @@ export type Scene = {
    * layout just works: `scene.handlersFor(() => ({ width: w(), height:
    * h() }))`. */
   handlersFor(layout: () => { width: number; height: number }): SceneHandlers
+  /**
+   * Add a listener at the root of the pointer walk (the `<Scene>`
+   * component's onPointerDown/Move/Up, onWheel and onTap props do this):
+   * it sees every event the node chain lets through, hit or miss -
+   * `event.mesh` is the hit it bubbled from, null over empty space - with
+   * `x`/`y` in scene pixels. Listeners all run, in registration order
+   * (the root is the last stop, nothing is left to claim); a stopped DOWN
+   * claims the whole press for the chain, so that pointer's move, up and
+   * tap never arrive. Returns the remover. A pointer feed listens here
+   * through feedPointer, so a camera control bound to the feed respects a
+   * mesh's claim.
+   */
+  listen(listener: ScenePointerListener): () => void
   /**
    * A second rendering of this scene: its own draw target and camera,
    * the same meshes and lights. Each mesh gets one entry in the view's
@@ -756,7 +845,7 @@ export type Scene = {
    * or pointer events. Views die with the scene; `view.dispose()` drops
    * one early.
    */
-  createView(opts: ViewOptions): View
+  createView(opts: ViewOptions): ViewHandle
   /**
    * A reflection probe: the scene rendered into a cube map from a point,
    * six faces at 90 degrees - Three's CubeCamera, Unity's and Godot's
@@ -849,23 +938,44 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   // map turns a hit's core node back into the mesh, or the instance of an
   // instanced mesh (each instance node is its own leaf).
   let byNode = new Map<NodeId, Mesh | InstanceNode>()
-  // The per-query filter raycast/overlap/sweep share: a hit's core node
-  // back to its mesh (and instance), or null when the query mask excludes
-  // the mesh (skipped like an invisible one; the mask defaults to the
-  // scene's, so an undrawn layer needs an explicit opts.layers to report)
-  // or the include-list leaves it out.
-  let admitted = (qopts: QueryOptions | undefined, site: string) => {
-    let mask = qopts?.layers !== undefined ? checkMask(qopts.layers, site) : sceneMask
-    let include = qopts?.meshes !== undefined ? new Set(qopts.meshes) : null
-    return (node: NodeId): { mesh: Mesh; instance: InstanceNode | null } | null => {
-      let leaf = byNode.get(node)
-      if (leaf === undefined) return null
-      let instance = leaf.kind === "instance" ? leaf : null
-      let mesh = instance !== null ? instance.mesh : (leaf as Mesh)
-      if (mesh === null || (mesh.layers & mask) === 0) return null
-      if (include !== null && !include.has(mesh)) return null
-      return { mesh, instance }
+  // The filter raycast/overlap/sweep hand the core: the scene root (the
+  // arena is shared with other scenes and 2d layers), the query mask (the
+  // scene's by default, so an undrawn layer needs an explicit opts.layers
+  // to report) and, for an include-list, the meshes' nodes - an instanced
+  // mesh's instances each being a leaf of their own.
+  // One filter object per scene, refilled per query (the bindings read it
+  // synchronously), so a query allocates nothing but its hits.
+  let filter: QueryFilter = {}
+  let queryFilter = (qopts: QueryOptions | undefined, site: string): QueryFilter => {
+    filter.root = root._node!
+    filter.layers = qopts?.layers !== undefined ? checkMask(qopts.layers, site) : sceneMask
+    if (qopts?.meshes === undefined) {
+      filter.nodes = undefined
+    } else {
+      let nodes: NodeId[] = []
+      for (let mesh of qopts.meshes) {
+        if (mesh._node !== null) nodes.push(mesh._node)
+        if (mesh._instances !== null) nodes.push(...instanceGroup(mesh as InstancedMesh))
+      }
+      filter.nodes = nodes
     }
+    return filter
+  }
+  // A hit's core node back to its mesh (and instance).
+  let leafOf = (node: NodeId): { mesh: Mesh; instance: InstanceNode | null } | null => {
+    let leaf = byNode.get(node)
+    if (leaf === undefined) return null
+    let instance = leaf.kind === "instance" ? leaf : null
+    let mesh = instance !== null ? instance.mesh : (leaf as Mesh)
+    if (mesh === null) return null
+    return { mesh, instance }
+  }
+  let impactOf = (h: CoreImpact): Impact | null => {
+    let leaf = leafOf(h.node)
+    if (leaf === null) return null
+    let impact: Impact = { mesh: leaf.mesh, time: h.time, point: h.point, normal: h.normal }
+    if (leaf.instance !== null) impact.instance = leaf.instance
+    return impact
   }
   // Nodes whose transform changed since the last sync (deduped by the
   // _moved flag): what the light and transparent-order bookkeeping
@@ -1070,44 +1180,46 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   let clip: Vec4 = [0, 0, 0, 0]
   let pickOrigin: Vec3 = [0, 0, 0]
 
-  // The camera ray through a scene pixel, into the pickOrigin/pickDir
+  // The camera ray through a pixel of `cam` over a tw x th target, into the
+  // pickOrigin/pickDir
   // scratches. The direction keeps a camera-forward component of 1
   // (perspective: (cx, cy, -1) in the camera frame; ortho: unit forward),
   // so origin + w * direction is the world point at camera-forward
   // distance w - what unproject() banks on. pick()/screenRay()/
   // unproject() all cast exactly this ray.
-  let pixelRay = (x: number, y: number): void => {
-    ensureCamera(camera, width, height)
-    let v = camera.view
-    let o = camera.ortho
+  let pixelRayOf = (cam: Camera, tw: number, th: number, x: number, y: number): void => {
+    ensureCamera(cam, tw, th)
+    let v = cam.view
+    let o = cam.ortho
     if (o === null) {
       // The camera-frame ray through the pixel, inverting project()'s
       // mapping: the baked y-down clip flip is why pixel y converts with
       // no negation there and one here.
-      let f = 1 / Math.tan(((camera.fov * Math.PI) / 180) / 2)
-      let cx = (((x / width) * 2 - 1) * (width / height)) / f
-      let cy = -((y / height) * 2 - 1) / f
+      let f = 1 / Math.tan(((cam.fov * Math.PI) / 180) / 2)
+      let cx = (((x / tw) * 2 - 1) * (tw / th)) / f
+      let cy = -((y / th) * 2 - 1) / f
       // The view's upper 3x3 rows are the camera axes, so its transpose
       // carries the camera-space direction (cx, cy, -1) to world.
       pickDir[0] = cx * v[0] + cy * v[1] - v[2]
       pickDir[1] = cx * v[4] + cy * v[5] - v[6]
       pickDir[2] = cx * v[8] + cy * v[9] - v[10]
-      pickOrigin[0] = camera.eye[0]
-      pickOrigin[1] = camera.eye[1]
-      pickOrigin[2] = camera.eye[2]
+      pickOrigin[0] = cam.eye[0]
+      pickOrigin[1] = cam.eye[1]
+      pickOrigin[2] = cam.eye[2]
       return
     }
     // Orthographic: every ray runs along the camera's forward axis; the
     // pixel picks where on the camera plane it starts (top row = top).
-    let cx = o.left + (x / width) * (o.right - o.left)
-    let cy = o.top + (y / height) * (o.bottom - o.top)
-    pickOrigin[0] = camera.eye[0] + cx * v[0] + cy * v[1]
-    pickOrigin[1] = camera.eye[1] + cx * v[4] + cy * v[5]
-    pickOrigin[2] = camera.eye[2] + cx * v[8] + cy * v[9]
+    let cx = o.left + (x / tw) * (o.right - o.left)
+    let cy = o.top + (y / th) * (o.bottom - o.top)
+    pickOrigin[0] = cam.eye[0] + cx * v[0] + cy * v[1]
+    pickOrigin[1] = cam.eye[1] + cx * v[4] + cy * v[5]
+    pickOrigin[2] = cam.eye[2] + cx * v[8] + cy * v[9]
     pickDir[0] = -v[2]
     pickDir[1] = -v[6]
     pickDir[2] = -v[10]
   }
+  let pixelRay = (x: number, y: number): void => pixelRayOf(camera, width, height, x, y)
 
   // Views (scene.createView): more targets drawing the same meshes from
   // their own cameras. A view holds one entry per mesh in its target,
@@ -1487,6 +1599,10 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     },
     _setLayers(mesh) {
       if (mesh._buffers === null || disposed) return
+      if (mesh._node !== null) spatial.setLayers(mesh._node, mesh.layers)
+      if (mesh._instances !== null) {
+        for (let n of instanceGroup(mesh as InstancedMesh)) spatial.setLayers(n, mesh.layers)
+      }
       if ((mesh.layers & sceneMask) !== 0) attachScene(mesh)
       else detachScene(mesh)
       for (let v of views) {
@@ -1598,6 +1714,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       if (mesh === null || mesh._buffers === null || mesh._node === null || instance._node === null) return
       spatial.setBounds(instance._node, geometryBounds(mesh.geometry))
       spatial.setShape(instance._node, mesh._buffers.shape)
+      spatial.setLayers(instance._node, mesh.layers)
       // The record is the instance's placement inside the mesh (the mesh
       // node is the anchor), staged by the core at the next flush.
       spatial.bindMatrixRecord(instance._node, mesh._instances.buffer, instance._slot, mesh._node)
@@ -1674,13 +1791,9 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   lightsDirty = true
   hooks._schedule()
 
-  // Pointer dispatch (scene.handlers): capture/hover bookkeeping and the
-  // bubble walk live in scene-pointer.ts; all it needs of the scene is
-  // pick() and the target size.
-  let pointer = makePointerInput({
-    pick: (x, y) => scene.pick(x, y),
-    targetSize: () => ({ width, height }),
-  })
+  // The scene's root listeners (scene.listen): the last stop of the
+  // pointer walk scene-pointer.ts runs behind scene.handlers.
+  let listeners = new Set<ScenePointerListener>()
 
   let scene: Scene = {
     texture,
@@ -1830,7 +1943,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       // microtask still runs and finds nothing dirty - harmless.)
       if (scheduled) sync()
       if (disposed) return []
-      let admit = admitted(rayOpts, "raycast")
+      let f = queryFilter(rayOpts, "raycast")
       let hits: Hit[] = []
       rayOriginScratch[0] = origin[0]
       rayOriginScratch[1] = origin[1]
@@ -1838,8 +1951,8 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       rayDirScratch[0] = direction[0]
       rayDirScratch[1] = direction[1]
       rayDirScratch[2] = direction[2]
-      for (let h of spatial.raycast(rayOriginScratch, rayDirScratch)) {
-        let leaf = admit(h.node)
+      for (let h of spatial.raycast(rayOriginScratch, rayDirScratch, f)) {
+        let leaf = leafOf(h.node)
         if (leaf === null) continue
         let hit: Hit = { mesh: leaf.mesh, distance: h.distance, point: h.point, normal: h.normal }
         if (leaf.instance !== null) hit.instance = leaf.instance
@@ -1852,11 +1965,11 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     overlap(volume, qopts) {
       if (scheduled) sync()
       if (disposed) return []
-      let admit = admitted(qopts, "overlap")
+      let f = queryFilter(qopts, "overlap")
       let kind = packVolume(volume, "overlap")
       let out: Overlap[] = []
-      for (let h of spatial.overlap(kind, kind === "box" ? boxScratch : capsuleScratch)) {
-        let leaf = admit(h.node)
+      for (let h of spatial.overlap(kind, kind === "box" ? boxScratch : capsuleScratch, f)) {
+        let leaf = leafOf(h.node)
         if (leaf === null) continue
         let contact: Overlap = { mesh: leaf.mesh, point: h.point, normal: h.normal, depth: h.depth }
         if (leaf.instance !== null) contact.instance = leaf.instance
@@ -1867,27 +1980,53 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     sweep(volume, motion, qopts) {
       if (scheduled) sync()
       if (disposed) return []
-      let admit = admitted(qopts, "sweep")
+      let f = queryFilter(qopts, "sweep")
       let kind = packVolume(volume, "sweep")
       motionScratch[0] = motion[0]
       motionScratch[1] = motion[1]
       motionScratch[2] = motion[2]
       let out: Impact[] = []
-      for (let h of spatial.sweep(kind, kind === "box" ? boxScratch : capsuleScratch, motionScratch)) {
-        let leaf = admit(h.node)
-        if (leaf === null) continue
-        let impact: Impact = { mesh: leaf.mesh, time: h.time, point: h.point, normal: h.normal }
-        if (leaf.instance !== null) impact.instance = leaf.instance
-        out.push(impact)
+      for (let h of spatial.sweep(kind, kind === "box" ? boxScratch : capsuleScratch, motionScratch, f)) {
+        let impact = impactOf(h)
+        if (impact !== null) out.push(impact)
       }
       return out
     },
-    handlers: pointer.handlers,
-    handlersFor: pointer.handlersFor,
+    moveAndSlide(volume, motion, mopts) {
+      if (scheduled) sync()
+      let kind = packVolume(volume, "moveAndSlide")
+      motionScratch[0] = motion[0]
+      motionScratch[1] = motion[1]
+      motionScratch[2] = motion[2]
+      if (disposed) return { motion: [motion[0], motion[1], motion[2]], floor: null, wall: false, ceiling: false, hits: [] }
+      let f = queryFilter(mopts, "moveAndSlide")
+      let r = spatial.moveAndSlide(kind, kind === "box" ? boxScratch : capsuleScratch, motionScratch, mopts, f)
+      let hits: Impact[] = []
+      for (let h of r.hits) {
+        let impact = impactOf(h)
+        if (impact !== null) hits.push(impact)
+      }
+      return { motion: r.motion, floor: r.floor, wall: r.wall, ceiling: r.ceiling, hits }
+    },
+    get handlers() {
+      return pointer.handlers
+    },
+    handlersFor(layout) {
+      return pointer.handlersFor(layout)
+    },
+    listen(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
     createView(vopts) {
       if (disposed) throw new Error("createView: the scene is disposed")
       let v = makeView(vopts, null)
-      return {
+      // The view's own walk: its listeners, its camera's pick, and a
+      // dispatch with its own capture and hover bookkeeping.
+      let viewListeners = new Set<ScenePointerListener>()
+      let handle: ViewHandle = {
         texture: v.texture,
         depthTexture: vopts.depth === "texture" && vopts.into === undefined ? depthTexture(v.texture) : null,
         setCamera(update) {
@@ -1927,10 +2066,35 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
           }
           hooks._schedule()
         },
+        pick(x, y) {
+          if (v.disposed) return []
+          pixelRayOf(v.camera, v.width, v.height, x, y)
+          return scene.raycast(pickOrigin, pickDir)
+        },
+        get handlers() {
+          return viewPointer.handlers
+        },
+        handlersFor(layout) {
+          return viewPointer.handlersFor(layout)
+        },
+        listen(listener) {
+          viewListeners.add(listener)
+          return () => {
+            viewListeners.delete(listener)
+          }
+        },
         dispose() {
+          viewListeners.clear()
           disposeView(v)
         },
       }
+      let viewPointer = makePointerInput({
+        pick: (x, y) => handle.pick(x, y),
+        targetSize: () => ({ width: v.width, height: v.height }),
+        root: handle,
+        listeners: viewListeners,
+      })
+      return handle
     },
     createReflectionProbe(popts) {
       if (disposed) throw new Error("createReflectionProbe: the scene is disposed")
@@ -1950,6 +2114,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     dispose() {
       if (disposed) return
       disposed = true
+      listeners.clear()
       // Full tree-side teardown, not just the target: every node leaves
       // the scene (entries' geometry-buffer references and pick leaves
       // dropped, core nodes freed), so a disposed scene leaves no
@@ -1977,6 +2142,15 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       }
     },
   }
+  // Pointer dispatch (scene.handlers): capture/hover bookkeeping, the
+  // walk and the tap tracker live in scene-pointer.ts; all it needs of
+  // the scene is pick(), the target size, and the root it ends at.
+  let pointer = makePointerInput({
+    pick: (x, y) => scene.pick(x, y),
+    targetSize: () => ({ width, height }),
+    root: scene,
+    listeners,
+  })
   // A reflection probe over layer mask `mask` (see createReflectionProbe):
   // the public object plus `finish`, which keeps the prefiltered chain and
   // drops everything else - the bake's one-shot use.