@solidrt/3d 0.0.56 → 0.0.57

package/AGENTS.md

@@ -21,7 +21,7 @@ blendMode and pointer events like any element.
   change, however many meshes. World matrices live in the core only:
   `worldPosition`/`lookAt`/picking read them back (`worldMatrix`, pending
   writes included). See okf/backlog/spatial-core.md for what still runs
-  in JS and why. The component face (`Scene`/`Group`/`Mesh`/
+  in JS and why. The component face (`Scene`/`View3d`/`Group`/`Mesh`/
   `PerspectiveCamera`) syncs props into that core over context and renders
   nothing itself.
 - Node lifecycle: `add(parent, child)` attaches (re-parenting detaches
@@ -42,8 +42,9 @@ blendMode and pointer events like any element.
   structure, per-frame motion goes straight to the scene).
 - VIEWS: `scene.createView({ width, height, overrideMaterial?, depth?,
   clearColor?, ... })` renders the same scene into a second target from
-  its own camera (`view.setCamera`, the scene's CameraUpdate shape). Each
-  mesh gets one entry in the view's target bound as one more draw sink of
+  its own camera (`view.setCamera`, the scene's CameraUpdate shape; in a
+  component tree `<View3d>` is the same as a Scene child, see Components).
+  Each mesh gets one entry in the view's target bound as one more draw sink of
   its CORE node, so the one flush writes every target - the app writes
   nothing per view. Geometry buffers and (without an override) materials
   are shared; the light set and `scene.setParams` names fan out to every
@@ -228,8 +229,8 @@ blendMode and pointer events like any element.
   GPU-free BY DESIGN so they can be checked headless (and, for the two
   model modules, run under bun in `tools/model.ts`); keep them that way.
   The rigs under `checks/`
-  (`geometry-check`, `sweep-check`, `pick-check`, `order-check`,
-  `gltf-check`) run on
+  (`geometry-check`, `sweep-check`, `pick-check`, `dispatch-check`,
+  `order-check`, `gltf-check`) run on
   flux from the repo root: `bunx srt bundle -f --stdout
   packages/3d/checks/<name>.ts | target/release/flux -`. Run the ones
   touching what you changed. `raycast-check.tsx` and
@@ -247,7 +248,8 @@ blendMode and pointer events like any element.
 
 | Component | Props |
 | --- | --- |
-| `Scene` | `width?`, `height?` (target pixels - both, or neither = FILL, below), `clearColor?`, `camera?` (partial CameraUpdate, `ortho` included - the declarative scene.setCamera; same state as `PerspectiveCamera`, use one form), `background?` (fragment GLSL, or a skybox `{ cube, intensity?, rotation? }`), `environment?` (`{ cube, intensity?, rotation? }`, the cube reflective materials mirror), `fog?` (`{ color, near, far }`, linear by camera distance), `toneMapping?` (`"none"` default or `"aces"`), `exposure?` (default 1), `layers?` (target mask, default 1), `depth?` (`"texture"` exposes scene.depthTexture; not with samples), `samples?` (1/2/4/8 MSAA), `label?`, `ref?(scene)`, `output?(texture)`, `events?` (mesh pointer events, default on) |
+| `Scene` | `width?`, `height?` (target pixels - both, or neither = FILL, below), `clearColor?`, `camera?` (partial CameraUpdate, `ortho` included - the declarative scene.setCamera; same state as `PerspectiveCamera`, use one form), `background?` (fragment GLSL, or a skybox `{ cube, intensity?, rotation? }`), `environment?` (`{ cube, intensity?, rotation? }`, the cube reflective materials mirror), `fog?` (`{ color, near, far }`, linear by camera distance), `toneMapping?` (`"none"` default or `"aces"`), `exposure?` (default 1), `layers?` (target mask, default 1), `depth?` (`"texture"` exposes scene.depthTexture; not with samples), `samples?` (1/2/4/8 MSAA), `label?`, `ref?(scene)`, `output?(texture)`, `events?` (pointer events, default on), `pointer?` (the leaf's pointer feed, fed from the scene's root), `onPointerDown/Move/Up?`, `onWheel?`, `onTap?` (the scene's own handlers, the last stop of the walk - `event.mesh` null over empty space) |
+| `View3d` | a Scene child rendering the scene again from a camera of its own (scene.createView as a component): `width`, `height` (target pixels, live; fixed-size only for now), `x?`, `y?` (the tile's top-left in `into`, live), `into?` (tile an app-owned draw target - one pass for every view into it; fixed at creation), `camera?` (partial CameraUpdate on the view's camera, live; same state as a `PerspectiveCamera` child), `layers?` (the view's mask, live), `clearColor?`, `label?`, `overrideMaterial?`, `fog?` (FogOptions, or null for none), `depth?`, `samples?`, `filter?`, `wrap?` (createView's, fixed), `ref?(view)`, `output?(texture)` (else a built-in `<texture>` leaf at the target size, a tile shown through srcX/srcY), `events?`, `pointer?` (the view leaf's feed, fed from the view's root), `onPointerDown/Move/Up?`, `onWheel?`, `onTap?` (the view's own handlers); camera-control children drive the VIEW (inside, `useScene()` reports the view as `viewport` and the view's feed as `pointer`); node children mount to the scene as outside, and under the view's leaf get their ordinary pointer handlers, picked through the view's camera (`view.pick`), the view as the root of that walk |
 | `Group` | `position?`, `rotation?` (Euler radians, XYZ order), `quaternion?` (either, not both), `scale?` (number = uniform), `visible?`, pointer events (below), `ref?(node)` |
 | `Mesh` | `geometry`, `material`, transforms as Group, `params?` (per-mesh uniforms, merge semantics - no unset), `renderOrder?`, `castShadow?`, `layers?` (membership bitmask, default 1), pointer events (below), `ref?(mesh)` |
 | `Sprite` | as Mesh minus `geometry`: a camera-facing unit quad, `scale` is its world size, rotation is ignored; pair with a `sprite()` material |
@@ -276,9 +278,10 @@ while the target follows the leaf's on-screen size in DEVICE pixels -
 display scale, `designSize` fits and ancestor transforms included
 (getBoundingBoxViewport x displayScale, applied from onLayout, so no
 frame draws at a stale size). A bare `<Scene>` in a pane renders at
-native density on any display, mesh events and `<OrbitCamera>` input are
-wired automatically (event scaling reads the leaf's untransformed box
-back with `getLayoutBox`), and the camera aspect follows the box. Fill
+native density on any display, mesh events are wired automatically
+(event scaling reads the leaf's untransformed box back with
+`getLayoutBox`), the `pointer` feed you hand in is spread on the leaf,
+and the camera aspect follows the box. Fill
 or fixed is decided at mount; `output` requires explicit sizes (the
 target cannot follow a leaf it does not own), and giving exactly one of
 width/height throws.
@@ -293,98 +296,139 @@ examples fill; scene-views and scene-post-effect keep fixed sizes to
 show multi-view composition and supersampling). A custom `output` leaf
 whose layout differs from the target
 takes `handlersFor` (below), not `handlers`; `useScene()` works inside
-`output` because it runs in the scene context. With an `<OrbitCamera>`
-(or any SceneInput listener) in the scene, also spread
-`{...useScene().input.handlersFor(layout)}` on the leaf - the mesh-event
-and control-input channels are separate spreads with the same layout.
+`output` because it runs in the scene context. One spread carries
+everything: the `pointer` feed listens at the scene's root, so
+`{...useScene().scene.handlers}` feeds the nodes, the scene's own
+handlers and the feed alike (a detached leaf gives its feed a `layout`,
+it has no layout box to normalize by).
+
+Input, the rule (ARCHITECTURE.md): a camera control consumes a
+device-free abstraction and never handles events or reads a device
+itself. The controls expose `axes` (core's createAxes contract - rates
+sampled per frame, immediate deltas in device-free units) and pose verbs;
+an input map (`createInputMap`, core AGENTS.md) drives the axes by action
+name, and the APP binds devices to the map: the scene leaf's pointer feed
+(`createPointerFeed()`, handed to `<Scene pointer>` / `<View3d pointer>`,
+where it listens at the root of the pointer walk, so a mesh that claims
+its press keeps the control out of that drag; an imperative scene or
+view feeds it with `feedPointer(scene, feed)`), a pad (`gamepad(0)`, or `gamepad.next()`
+for the next pad to press a button), the keyboard (`keyboard`, its key
+events through `input.handlers` on the window).
+Nothing binds by default: `<OrbitCamera />` without `input` moves only
+through its handle. The standard wiring is a preset, plain bindings the
+app applies and edits:
+
+```tsx
+let pointer = createPointerFeed()
+let input = createInputMap(orbitActions)
+input.bind(orbitBindings({ pointer, gamepad: gamepad() }))
+<Scene pointer={pointer}>
+  <OrbitCamera input={input} distance={7} />
+```
+
+The vocabulary is shared with @solidrt/2d, one kind and unit per word:
+`rotate` vec2 (orbit turns), `zoom` axis (octaves, positive in), `pan`
+vec2 (element heights), `look` vec2 (turns), `move` vec2 ([right,
+forward], forward = -y in the screen convention), `rise` axis. Keys and
+sticks move the CAMERA where a drag moves the content, so the presets
+bind them to `rotate`/`pan` through `invert()`; `look` is the exception,
+a drag and a stick both turn the eye.
 
 Camera control: `createOrbitCamera(scene, { target?, azimuth?, elevation?,
 distance?, min/maxDistance?, min/maxElevation?, orbitSpeed?, rotateSpeed?,
-zoomSpeed?, zoomAnchor?, rotateAnchor?, panSpeed?, viewport?, clampTarget? })`
-- drag-to-rotate, pinch- and wheel-to-zoom, two-finger pan, optional
-auto-orbit. The first argument is anything with the scene's `setCamera`: a
-Scene, or a View to drive one view's camera independently (one orbit per
-view, each handed the handlers of its own viewport element). Input runs on
-core's `createTransform` recognizer, so drag and pinch arbitrate in the
-app-wide gesture arena (a viewport inside a scroller
-does not double-handle) and rotation starts after the recognizer's slop;
-`zoomSpeed` weights both wheel and pinch. Two-finger translation pans (the
-scene tracks the fingers 1:1 at target depth, weighted by `panSpeed`) when
-`viewport()` supplies `{ height, fov }` for the pixel-to-world mapping -
-without it, it rotates like one finger; `clampTarget(target)` bounds where
-a pan may put the pivot. Zoom aims
-at the target unless `zoomAnchor(x, y, {eye, target})` maps the pinch focal
-/ wheel cursor to a world point (ground hit, target-depth plane, ...) - then
-that point stays pinned under the pointer and the target slides toward it;
-only the app can build that mapping, since fov and aspect are app state
-(the point arrives in the input element's own pixels). Pair it with `rotateAnchor({eye, target})`: called at gesture
-start, its point is projected onto the view axis and re-seats the pivot
-without moving the picture, so a drag after an anchored zoom orbits what the
-camera looks at, not wherever the zoom left the target. Spread
-`orbit.handlers` onto the input-owning element, call `orbit.update(dt)`
-from your onFrame (no frame loop of its own), and use its return - true
-when the pose changed - to gate per-frame dependents like reprojecting
-HUD overlays. `orbiting()` (the auto-orbit switch) and `active()` (the
-frame-loop gate: orbiting with a non-zero rate - the predicate the 2d
-camera and the first-person camera share) are reactive (HUD-safe); the
-pose is plain state via `pose()`/`set()` (also the debug-command shape). It drives position and
-target only; fov/near/far stay on scene.setCamera (or the Scene `camera`
-prop).
+zoomSpeed?, panSpeed?, clampTarget?, zoomAnchor?, rotateAnchor? })` -
+azimuth/elevation/distance around a target with optional auto-orbit. The
+first argument is anything with the scene's `setCamera` and `camera()`
+(the fov maps pan travel to world): a Scene, or a View to drive one view's
+camera independently. Its `axes` are `rotate` (a delta of one element
+height sweeps one full turn, Three's OrbitControls convention, so a drag
+feels the same on a phone and a 4k window; a rate turns at 0.5 turn/s at
+full deflection), `zoom` (octaves: a delta of 1 halves the distance, a
+rate of 1 halves it per second) and `pan` (the target slides so the scene
+tracks the fingers 1:1 at the target's depth, three.js DOLLY_PAN, weighted
+by `panSpeed`; `clampTarget(target)` bounds where a pan may put the
+pivot). The verbs: `rotateBy(azimuth, elevation)` radians, `zoomBy(factor,
+anchor?)` (factor > 1 in, as the 2d camera's zoomAt), `panBy(right, up)`
+world units, `setPivot(point)`, `set(pose)`; every one pushes the pose at
+once. Zoom aims at the target unless `zoomAnchor(focal, {eye, target})`
+maps the gesture's focal point - a FRACTION of the element, [0..1, 0..1] -
+to a world point (ground hit, target-depth plane, ...): then that point
+stays pinned under the pointer and the target slides toward it; only the
+app can build that mapping, since it needs the projection
+(scene.unproject over the scene's size). A pinch holds one anchor for its
+whole gesture (the fingers' interleaved events make the span oscillate,
+and re-anchoring per delta turns that into a crawl); the wheel, arriving
+unbracketed, anchors per notch. Pair it with `rotateAnchor({eye, target})`:
+called when a rotate gesture begins, its point is projected onto the
+view axis and re-seats the pivot without moving the picture, so a drag
+after an anchored zoom orbits what the camera looks at, not wherever the
+zoom left the target. Call `orbit.update(dt)` from your onFrame to
+integrate the rates and the auto-orbit (no frame loop of its own), and
+use its return - true when the pose changed since the previous update,
+nudges included - to gate per-frame dependents like reprojecting HUD
+overlays. `orbiting()` (the auto-orbit switch) and `active()` (the
+frame-loop gate: orbiting with a non-zero rate, or any rate driving - the
+predicate every camera control shares) are reactive (HUD-safe); the pose
+is plain state via `pose()`/`set()` (also the debug-command shape). It
+drives position and target only; fov/near/far stay on scene.setCamera
+(or the Scene `camera` prop). The auto-orbit pauses while a gesture is
+open.
 
-In a component tree, skip the wiring: `<OrbitCamera azimuth={1.2}
-distance={7} />` as a Scene child reaches the scene through context,
-receives input from the scene's leaf (the built-in one automatically; a
-custom `output` leaf spreads `{...useScene().input.handlersFor(layout)}`
-beside its scene.handlersFor spread, same `layout`), defaults `viewport`
-to the leaf's laid-out size plus the scene camera's fov, and pushes input
-poses synchronously - no ref plumbing, no onFrame. Auto-orbit runs a
-frame loop only while `active()`, so a paused camera keeps the app
-demand-driven idle. The pose props are
-initial values: runtime pose changes (and the debug-command hookup) go
-through `ref`'s handle, whose set() also pushes the pose. Every other
-prop is live - forwarded to the control as a getter and read where it
-applies, never snapshotted - so clamps, rates, anchors and `viewport`
-follow their props without a remount, and a clamp change re-clamps the
-pose at once.
+In a component tree, skip the wiring: `<OrbitCamera input={input}
+azimuth={1.2} distance={7} />` as a Scene child reaches the scene through
+context (as a `<View3d>` child, that view: the context's `viewport` is
+the nearest owner's), drives from the map in `input` (its `rotate`,
+`zoom`, `pan` actions, or the names in `actions`; live - a new map
+reconnects) and nothing else, and runs a frame loop only while
+`active()`, so a camera moved by drags alone keeps the app demand-driven
+idle. The pose props are initial values: runtime pose changes (and the
+debug-command hookup) go through `ref`'s handle, whose set() and verbs
+push the pose. Every other prop is live - forwarded to the control as a
+getter and read where it applies, never snapshotted - so clamps, rates
+and anchors follow their props without a remount, and a clamp change
+re-clamps the pose at once.
 
 First-person control: `createFirstPersonCamera(scene, { position?, yaw?,
-pitch?, min/maxPitch?, moveSpeed?, lookSpeed?, fly?, viewport?,
-clampPosition? })` - a position plus yaw/pitch (yaw 0 faces -z, positive
-turns left; pitch positive looks up), Unity's FirstPersonController shape
-(look AND move in one control) where Three splits PointerLockControls
-from a hand-written key loop. Look comes from pointer-move
-movementX/movementY while `pointerLocked()`, from a one-finger drag
-(arena-arbitrated through createTransform, viewport-relative with
-`viewport`) while not, and from the right stick; move from WASD/arrows
-(physical codes and logical keys both), the left stick, and Q/E for
-down/up - bound always, inert unless `fly` is on. Walking (the default)
-flattens the heading onto the ground plane at fixed height. Every option
-but the initial pose is read where it applies (`fly` per update,
-`clampPosition` per move, the rates and pitch clamps per input), so a
-field changed on the options object takes effect on the next move: walk
-and fly are one control. The control NEVER calls `lockPointer`
-- click-to-lock and Escape-to-release are the app's window-level
-decisions (see `examples/first-person.tsx`) - and has no collision of
-its own: `clampPosition(next, current)` is the whole hook - bounds, a
-floor height, or `moveAndSlide` over `next - current` against the
-collision layer (see `examples/collision.tsx`). Spread `handlers` (pointer + key +
-onBlur; keys reach only the FOCUSED node, so that element must hold
-focus or be the window), call `update(dt)` from onFrame; `active()` is
-reactive - a key held or a stick deflected - and gates the loop. Keys
-cannot be polled (core has no key-state accessor), so held keys are
-tracked from the down/up pair and `onBlur` drops them.
+pitch?, min/maxPitch?, moveSpeed?, lookSpeed?, fly?, clampPosition? })` -
+a position plus yaw/pitch (yaw 0 faces -z, positive turns left; pitch
+positive looks up), Unity's FirstPersonController shape (look AND move in
+one control) where Three splits PointerLockControls from a hand-written
+key loop. Its `axes`: `look` (a delta of one element height sweeps half a
+turn - a drag across the screen turns the walker around - and the
+pointer feed's `mouseDelta` delivers mouse motion under pointer lock in
+the same unit; a rate turns at 0.4 turn/s), `move` ([right, forward],
+forward = -y: a stick pushed up or W reads [0, -1]; a rate walks at
+`moveSpeed`, a delta is a step in world units, diagonals clamped to unit
+length so they walk no faster) and `rise` (world up at `moveSpeed`, fly
+mode only). Walking (the default) flattens the heading onto the ground
+plane at fixed height; `fly` moves along the view. The verbs:
+`lookBy(yaw, pitch)` radians, `moveBy(right, forward, up?)` in the
+walker's frame, `set(pose)`. Every option but the initial pose is read
+where it applies (`fly` per step, `clampPosition` per move, the rates and
+pitch clamps per input), so a field changed on the options object takes
+effect on the next move: walk and fly are one control. The control NEVER
+calls `lockPointer` - click-to-lock and Escape-to-release are the app's
+window-level decisions (see `examples/first-person.tsx`) - and has no
+collision of its own: `clampPosition(next, current)` is the whole hook -
+bounds, a floor height, or `moveAndSlide` over `next - current` against
+the collision layer (see `examples/collision.tsx`, whose `jump` is one
+more action on the same map: Space or the pad's south button, read by
+name). Call `update(dt)` from onFrame; `active()` is reactive - a rate
+driving (a held key, a deflected stick) - and gates the loop. The map
+tracks held keys from the down/up pair through `input.handlers`; spread
+its `onBlur` too, since the up never arrives once focus has left.
 
-`<FirstPersonCamera>` as a Scene child wires all of it: with a
-key-driven control registered, the built-in leaf becomes `focusable`
-and takes focus on pointer down (the web canvas gesture), which routes
-the keys to the control; a pointer-only scene (`<OrbitCamera>`) never
-steals focus. A custom `output` leaf spreads
-`useScene().input.handlersFor(layout, () => node)` and declares
-`focusable` itself. The frame loop runs only while `active()`. Every prop
+`<FirstPersonCamera input={input}>` as a Scene child wires the control
+to the scene and the map, nothing else: the app spreads
+`input.handlers` on the window (keys bubble there from wherever focus
+is, so a click on the scene needs no focus dance) and hands the scene
+its `pointer` feed. The frame loop runs only while `active()`. Every prop
 but the initial pose is live: `fly={flying()}` toggles walk/fly on the
-running control (pose and held keys carry over, no remount, and
-`clampPosition` may swap with it), `moveSpeed`/`lookSpeed` follow their
-props, and a pitch clamp change re-clamps at once.
+running control (pose carries over, no remount, and `clampPosition` may
+swap with it), `moveSpeed`/`lookSpeed` follow their props, and a pitch
+clamp change re-clamps at once. checks/orbit-check.ts and
+checks/first-person-check.ts pin both controls headless (they import
+`@solidrt/core/input` only).
 
 Overlay projection: `scene.project(point)` maps a world point to scene
 pixels (top-left origin, y down - the output texture's own space; `w` is
@@ -453,12 +497,21 @@ closed mesh with no triangle in reach touches nothing - the trimesh rule
 in every engine), and a sweep from a volume already in contact reports
 time 0 only while the motion closes in; leaving or sliding along the
 contact is no hit, which is what lets a slide along a wall proceed. A
-zero motion touches nothing.
-`moveAndSlide(scene, volume, motion, opts?)` is the controller over
-them: Godot's CharacterBody3D.move_and_slide and Unity's
-CharacterController.Move as one PURE function - no node, no velocity;
-the first-person camera composes it in `clampPosition`, a node-driven
-body applies `result.motion` with setTransform. It pushes the body out
+zero motion touches nothing. The filters run in the core: every query
+hands `flux:spatial` a `{ root, layers, nodes }` filter (the scene root,
+the mask, the `meshes` include-list as node ids - an instanced mesh
+contributing every instance node), and a mesh's `layers` is written to
+its core node (`setLayers`), so a query never sees another scene's or a
+2d layer's nodes and JS only maps hits back to meshes.
+`scene.moveAndSlide(volume, motion, opts?)` (and the free
+`moveAndSlide(scene, ...)` spelling of it) is the controller over them:
+Godot's CharacterBody3D.move_and_slide and Unity's
+CharacterController.Move as one PURE call - no node, no velocity; the
+first-person camera composes it in `clampPosition`, a node-driven body
+applies `result.motion` with setTransform. The loop runs in the spatial
+core (`alloy/src/spatial/mover.rs`, one FFI call per body per frame; the
+2d layer's mover is the same loop), the JS side only packs the volume
+and maps hits back to meshes. It pushes the body out
 of anything it starts inside, sweeps, stops a skin short, slides the
 rest along the contact plane up to `maxSlides` times, then snaps down
 onto a floor within `floorSnap` unless the motion rises - and the
@@ -478,25 +531,54 @@ one overlap per move. Deliberately absent and additive when asked: a
 step offset (Unity's stepOffset; Godot has none either) and a cylinder
 volume (Godot only).
 
-Mesh pointer events - the element vocabulary one tree deeper:
-`onPointerDown/Move/Up/Enter/Leave` as plain fields on any node (and as
-Mesh/Group props). The nearest hit mesh is the target; down/move/up
-bubble mesh -> ancestor groups (`stopPropagation()` stops the walk);
-enter/leave fire on the mesh alone, pairing on hover changes. A
-pointer-down CAPTURES its mesh until the up: moves and the up keep
-dispatching to it off-mesh (the platform's captured-drag rule), with
-`point`/`distance` null while the ray misses it. The event carries the
-element fields (pointerId, pointerType, button, modifiers) plus `mesh`,
-`currentTarget`, `point`, `distance`, and `x`/`y` in scene pixels.
-Wiring: the built-in `<Scene>` leaf carries `scene.handlers`
-automatically (opt out: `events={false}`); an `output` leaf or
-imperative composition spreads `{...scene.handlers}` onto the element
-showing the texture. `scene.handlers` assumes that leaf is LAID OUT at
-the target size - true for the built-in leaf and a d-texture at natural
-size, under any ancestor transforms or design-size fits (the hit test
-undoes them; localX/localY arrive in the leaf's layout frame). A leaf
-laid out at a different size (the supersampling pattern) uses
+Pointer events (scene-pointer.ts): the element event model one tree
+deeper, with the SCENE as the root of the walk (under a `<View3d>` leaf:
+the view). `onPointerDown/Move/Up/Enter/Leave/Wheel/Tap` are plain
+fields on any node (and Mesh/Group/Instance props); the nearest hit is
+the target - the struck instance of an instanced mesh, else the mesh -
+and down/move/up/wheel dispatch there, bubble through the ancestors and
+END AT THE SCENE's listeners (`scene.listen({...})`, the `<Scene>`
+`onPointer*`/`onWheel`/`onTap` props); over empty space the walk is the
+scene alone, with `event.mesh` null (a tap there is the deselect idiom).
+`event.mesh` stays the hit (`NodePointerEvent` in the chain,
+`ScenePointerEvent` at the root with `mesh` nullable), `currentTarget`
+the node whose handler runs (the scene 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 scene either (the chain still
+bubbles). That one rule is how a mesh drags itself under an
+`<OrbitCamera>` without the view turning: stop the down, own the
+captured moves - the control's pointer feed listens at the root
+(`<Scene pointer>` does it, `feedPointer(scene, feed)` by hand) and sees
+only what the nodes let through. Capture is per pointerId to the press
+target, the scene included (a drag from empty space keeps delivering to
+the root as it crosses meshes; a drag from a mesh keeps naming it, with
+`point`/`distance` null while the ray misses it). Enter/leave fire on
+the struck node alone - a group never receives them - while the root
+sees every move, so "hovering empty space" is a root move with `mesh`
+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 drag), 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`); a release on another instance of the same mesh is no
+tap. Wheel walks like a move with `deltaX/deltaY` (a node stopping it
+keeps the zoom out). Every event carries `native`, the leaf's element
+event, for core's recognizers, and the element fields (pointerId,
+pointerType, button, modifiers) plus `x`/`y` in scene pixels
+(screenRay's input - a drag plane is one intersection away). Root
+listeners all run, in registration order (the root is the last stop,
+nothing is left to claim). Wiring: the built-in `<Scene>` leaf carries
+`scene.handlers` automatically (opt out: `events={false}`); an `output`
+leaf or imperative composition spreads `{...scene.handlers}` onto the
+element showing the texture. `scene.handlers` assumes that leaf is LAID
+OUT at the target size - true for the built-in leaf and a d-texture at
+natural size, under any ancestor transforms or design-size fits (the hit
+test undoes them; localX/localY arrive in the leaf's layout frame). A
+leaf laid out at a different size (the supersampling pattern) uses
 `scene.handlersFor(() => ({ width, height }))` with its layout size.
+checks/dispatch-check.ts pins the walk, claiming, capture, hover, wheel
+and tap rules headless; examples/pick.tsx is the live guard.
 
 Geometry generators take ONE options object, every field optional with
 a default, named as Three names them: `box({ width, height, depth })`

package/README.md

@@ -97,7 +97,8 @@ named channel to a geometry's interleave, `withColors` is the `aColor`
 vec4 case - tint, baked AO, any four scalars - and materials read channels
 by name), one perspective camera
 with an orbit control (`<OrbitCamera>` as a Scene child, or
-`createOrbitCamera` imperatively: drag, pinch/wheel zoom, auto-orbit),
+`createOrbitCamera` imperatively; drag, pinch/wheel zoom and a pad reach
+it through an input map the app binds, auto-orbit),
 mesh picking with pointer events, scene backgrounds, transparency, and
 lights (`lit` material with hemisphere ambient, up to four directional
 light nodes, Blinn-Phong highlight and triplanar mapping).

package/examples/README.md

@@ -21,10 +21,14 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   target: `lookAt` for a +z solid, `quatFromTo` for aiming a y-axis cone,
   and a `quatSlerp` damped follow that visibly lags; all driven from
   onFrame through refs, no per-frame signals.
-- `pick.tsx` - mesh pointer events: hover tints (enter/leave), click
-  pops (down), a Group hearing its children's clicks through bubbling
-  and one mesh stopping the walk; a STATIC scene rendered only when an
-  event changes something, with hit testing over the scene's BVH.
+- `pick.tsx` - mesh pointer events under an `<OrbitCamera>`, the scene
+  as the root of the walk: hover tints (enter/leave), a tap pops, a drag
+  on the crate slides it over the floor without orbiting (its down claims
+  the press), a drag elsewhere orbits and a wheel zooms through the feed
+  listening at the root, the ring claims the wheel to spin, a tap on
+  nothing un-pops (the scene's own `onTap` with `mesh` null), and a
+  Group hears its children's downs through bubbling; a STATIC scene
+  rendered only when an event changes something.
 - `scene-background.tsx` - a fragment-GLSL background drawn inside the
   scene's own pass (`<Scene background>`): one target, no stacked
   backdrop texture, no resize plumbing; the source is shader-target
@@ -85,10 +89,11 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   Drag to orbit; the `formation` and `state` debug commands drive it
   headlessly.
 - `first-person.tsx` - a first-person walk: `<FirstPersonCamera>` over
-  a walled courtyard of shadow-casting pillars, WASD/arrows and the pad
-  sticks to walk, mouse look under pointer lock (click locks, Escape
-  releases - the app's calls, not the control's), a drag to look on
-  touch; `clampPosition` keeps the walker inside the walls, the whole of
+  a walled courtyard of shadow-casting pillars, driven by an input map
+  the app binds (`firstPersonBindings`: WASD/arrows and the pad sticks
+  to walk, the scene's drag to look on touch, mouse motion while the
+  pointer is locked - click locks, Escape releases, the app's calls, not
+  the control's); `clampPosition` keeps the walker inside the walls, the whole of
   the collision a camera control offers; the `pose` debug command reads
   and sets the pose headlessly.
 - `collision.tsx` - collision without a physics engine: the same walker

package/examples/collision.tsx

@@ -11,13 +11,15 @@
 // click locks the pointer, Escape releases it. Debug commands: `pose`
 // (read/set), `walk` ({ dx, dz } through the collision), `jump`, `fall`
 // ({ dt }: one airborne step by hand, for headless checks), `state`.
-import { createSignal, lockPointer, onFrame, pct, pointerLocked, render } from "@solidrt/core"
+import { createInputMap, createPointerFeed, createSignal, gamepad, keyboard, lockPointer, onFrame, pct, pointerLocked, render } from "@solidrt/core"
 import type { PointerEvent } from "@solidrt/core"
 import {
   box,
   cylinder,
   DirectionalLight,
   FirstPersonCamera,
+  firstPersonActions,
+  firstPersonBindings,
   HemisphereLight,
   lit,
   Mesh,
@@ -68,6 +70,14 @@ let feetOf = (eye: Vec3): Vec3 => [eye[0], eye[1] - EYE, eye[2]]
 function App() {
   let scene!: SceneHandle
   let camera!: FirstPersonCameraHandle
+  // The walker's input plus the game's own `jump` action: the standard
+  // first-person bindings, and Space or the pad's south button for the
+  // jump - one map, read by name (ARCHITECTURE.md).
+  let pointer = createPointerFeed()
+  let pad = gamepad()
+  let input = createInputMap({ ...firstPersonActions, jump: "button" })
+  input.bind(firstPersonBindings({ pointer, gamepad: pad, keyboard }))
+  input.bind("jump", keyboard.key("Space"), pad.button("south"))
   let [hud, setHud] = createSignal("")
   let [near, setNear] = createSignal<Set<number>>(new Set())
   // The same set, readable synchronously (a signal read right after its
@@ -135,6 +145,7 @@ function App() {
     grounded = false
     fall()
   }
+  input.onPress("jump", jump)
 
   let lastHud = 0
   onFrame(tick => {
@@ -204,9 +215,11 @@ function App() {
   return (
     <window
       onKeyDown={e => {
+        input.handlers.onKeyDown(e)
         if (e.key === "Escape") lockPointer(false)
-        if (e.key === " " || e.code === "Space") jump()
       }}
+      onKeyUp={input.handlers.onKeyUp}
+      onBlur={input.handlers.onBlur}
     >
       <view
         width={pct(100)}
@@ -215,9 +228,9 @@ function App() {
           if (e.pointerType === "mouse") lockPointer(true)
         }}
       >
-        <Scene ref={s => (scene = s)} clearColor={[0.6, 0.72, 0.88, 1]} samples={4} label="collision">
+        <Scene ref={s => (scene = s)} clearColor={[0.6, 0.72, 0.88, 1]} samples={4} label="collision" pointer={pointer}>
           <PerspectiveCamera fov={70} near={0.1} far={80} />
-          <FirstPersonCamera ref={c => (camera = c)} position={[0, EYE, 10]} clampPosition={clamp} />
+          <FirstPersonCamera input={input} ref={c => (camera = c)} position={[0, EYE, 10]} clampPosition={clamp} />
           <HemisphereLight sky={[0.5, 0.56, 0.68]} ground={[0.25, 0.22, 0.18]} />
           <DirectionalLight color={[1, 0.95, 0.85]} intensity={0.9} position={[8, 14, 6]} direction={[-8, -14, -6]} castShadow shadow={{ mapSize: 2048, normalBias: 0.02, cascades: 3, distance: 40 }} />
           <Mesh geometry={plane({ width: FLOOR * 2 + 2, height: FLOOR * 2 + 2 })} material={ground} rotation={[-Math.PI / 2, 0, 0]} layers={1 | COLLIDER} />

package/examples/first-person.tsx

@@ -1,16 +1,17 @@
 // A first-person walk: `<FirstPersonCamera>` driving the scene camera from
-// WASD/arrows and the gamepad sticks, mouse look under pointer lock and
-// drag-to-look without it. Click the scene to lock the pointer (the scene
-// leaf takes focus on the same click, which routes the keys to the
-// control), Escape releases it; on a touch screen a drag looks around and
-// the left stick of a pad walks. Movement runs a frame loop only while a
-// key is held or a stick deflected - a still scene renders nothing new.
+// an input map the app wires - WASD/arrows and the sticks through the
+// standard bindings, the scene leaf's drag to look around on touch, and
+// mouse motion while the pointer is locked. Click the scene to lock the
+// pointer, Escape releases it; the keys reach the map through the window
+// (`input.handlers`), so nothing needs focus. Movement runs a frame loop
+// only while a key is held or a stick deflected - a still scene renders
+// nothing new.
 // `clampPosition` keeps the walker inside the courtyard walls, the whole
 // of the collision an app gets from a camera control. The `pose` debug
 // command reads and sets the pose for headless checks.
-import { createSignal, lockPointer, onFrame, pct, pointerLocked, render } from "@solidrt/core"
+import { createInputMap, createPointerFeed, createSignal, gamepad, keyboard, lockPointer, onFrame, pct, pointerLocked, render } from "@solidrt/core"
 import type { PointerEvent } from "@solidrt/core"
-import { box, cylinder, DirectionalLight, FirstPersonCamera, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, Scene } from "@solidrt/3d"
+import { box, cylinder, DirectionalLight, FirstPersonCamera, firstPersonActions, firstPersonBindings, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, Scene } from "@solidrt/3d"
 import type { FirstPersonCameraHandle, Vec3 } from "@solidrt/3d"
 import { registerDebug } from "srt:dev"
 
@@ -43,6 +44,12 @@ let inside = (p: Vec3): Vec3 => [clampNum(p[0], -COURT + WALL_GAP, COURT - WALL_
 
 function App() {
   let camera!: FirstPersonCameraHandle
+  // The walker's input: the scene leaf's gestures, the keyboard and any
+  // pad, bound to the control's actions (ARCHITECTURE.md: the app wires
+  // devices, the component takes the map).
+  let pointer = createPointerFeed()
+  let input = createInputMap(firstPersonActions)
+  input.bind(firstPersonBindings({ pointer, gamepad: gamepad(), keyboard }))
   let [hud, setHud] = createSignal("")
   let lastHud = 0
   onFrame(tick => {
@@ -77,8 +84,11 @@ function App() {
   return (
     <window
       onKeyDown={e => {
+        input.handlers.onKeyDown(e)
         if (e.key === "Escape") lockPointer(false)
       }}
+      onKeyUp={input.handlers.onKeyUp}
+      onBlur={input.handlers.onBlur}
     >
       <view
         width={pct(100)}
@@ -87,9 +97,9 @@ function App() {
           if (e.pointerType === "mouse") lockPointer(true)
         }}
       >
-        <Scene clearColor={[0.6, 0.72, 0.88, 1]} samples={4} label="first-person">
+        <Scene clearColor={[0.6, 0.72, 0.88, 1]} samples={4} label="first-person" pointer={pointer}>
           <PerspectiveCamera fov={70} near={0.1} far={60} />
-          <FirstPersonCamera ref={c => (camera = c)} position={[0, EYE, 7]} clampPosition={inside} />
+          <FirstPersonCamera input={input} ref={c => (camera = c)} position={[0, EYE, 7]} clampPosition={inside} />
           <HemisphereLight sky={[0.5, 0.56, 0.68]} ground={[0.25, 0.22, 0.18]} />
           <DirectionalLight
             color={[1, 0.95, 0.85]}