@solidrt/3d 0.0.47 → 0.0.49

package/AGENTS.md

@@ -11,7 +11,8 @@ blendMode and pointer events like any element. Design rationale:
 
 - Two layers. The imperative core is Solid-free: `createScene`,
   `createMesh(geometry, material)`, `add`/`remove`, `setTransform`,
-  `setVisible` - plain objects with dirty flags, batched to a microtask,
+  `lookAt`, `getRotation`, `setVisible` - plain objects with dirty flags, batched to a
+  microtask,
   one `setDrawParams` (uModel, plus uNormal for materials declaring it)
   per changed mesh and ONE `setTargetParams` (the shared uViewProj +
   uCamPos) per camera change, however many meshes. The component
@@ -48,9 +49,9 @@ blendMode and pointer events like any element. Design rationale:
 
 | Component | Props |
 | --- | --- |
-| `Scene` | `width`, `height` (target pixels), `clearColor?`, `label?`, `ref?(scene)`, `output?(texture)` |
-| `Group` | `position?`, `rotation?` (Euler radians, x-y-z order), `scale?` (number = uniform), `visible?`, `ref?(node)` |
-| `Mesh` | `geometry`, `material`, transforms as Group, `ref?(mesh)` |
+| `Scene` | `width`, `height` (target pixels), `clearColor?`, `background?` (fragment GLSL), `label?`, `ref?(scene)`, `output?(texture)`, `events?` (mesh pointer events, default on) |
+| `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), pointer events (below), `ref?(mesh)` |
 | `PerspectiveCamera` | `fov?` (vertical DEGREES, default 60), `near?`, `far?`, `position?`, `lookAt?`, `up?` |
 
 Output composition: without `output`, `Scene` emits a minimal
@@ -101,6 +102,40 @@ immediately, so set-then-project in one tick is exact. `scene.viewProj(out?)`
 copies the view-projection matrix for batch work. Never rebuild the
 camera matrices by hand for a HUD.
 
+Picking: `scene.pick(x, y)` is project()'s inverse - the camera ray
+through a scene pixel, returning `Hit[]` (`{ mesh, distance, point }`,
+world units, nearest first; every hit along the ray, not just the front
+one). `scene.raycast(origin, direction)` is the world-space primitive
+under it. The volume tier: hits test each mesh's local bounding box,
+transformed exactly under any node transform (non-uniform scale
+included), so results are conservative - a ray through a knot's hole
+still hits (no `face`/`uv` fields until a triangle tier exists).
+Broadphase is a dynamic AABB tree (BVH) the sync walk keeps current from
+its own dirty set - maintenance is O(changed), a query O(log meshes) -
+so per-pointer-move picking puts no ceiling on scene size. Both methods
+flush pending writes first (the lookAt/project immediacy contract), and
+both skip invisible meshes.
+
+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 viewBox 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.
+
 Geometry: `box(w?, h?, d?)`; `plane(w?, h?)`, `circle(radius?, seg?)` and
 `ring(inner?, outer?, seg?)` (XY, facing +z - rotate `[-Math.PI/2, 0, 0]`
 for a floor); `sphere(radius?, wSeg?, hSeg?)`;
@@ -129,10 +164,21 @@ Winding is normalized, so either authoring direction works.
 with a quarter-round bevel at both rims; `lathe(profile, segs?, angle?,
 start?)` revolves a CLOSED (x = radius, y = height) profile about the y
 axis - watertight by construction, flat caps on partial sweeps;
-`shape(profile)` fills one flat (facing +z, like circle);
-`triangulate(points)` is the ear-clipping core (fan fallback, never drops
-a cap), exported for custom flat work. These pick uint16/uint32 indices
-by vertex count automatically.
+`sweep(profile, path)` runs the profile along an open 3D polyline with
+MITRED joints (each cross-section sits on its bend's bisector plane, so
+bends never gape or overlap) and flat caps at both ends. The path
+mirrors the profile convention: bare `[x, y, z]` points crease (a strap
+folding over an edge), `{ p, smooth }` points shade continuous (tag a
+sampled curve's points); the profile's y starts as close to world up as
+the first segment allows, then parallel-transports without spinning.
+Closed loops are NOT supported yet - overlap the ends by a segment to
+fake one. `tube(path, radius?, radialSegs?)` is the round-profile
+shorthand (wire, rope, pipe), and `pathFrames(path)` exports the
+per-segment frames (tangents, cross-section axes, arc lengths) for
+custom work along a path. `shape(profile)` fills one flat (facing +z,
+like circle); `triangulate(points)` is the ear-clipping core (fan
+fallback, never drops a cap), exported for custom flat work. These pick
+uint16/uint32 indices by vertex count automatically.
 
 Materials:
 
@@ -158,7 +204,25 @@ Materials:
   pipeline preamble. App-driven uniforms beyond the standard set: seed
   via `params`, then write per mesh with
   `setMeshParams(mesh, { name: value })` (validated names; values persist
-  across entry rebuilds; frame-rate-safe like setTransform).
+  across entry rebuilds; frame-rate-safe like setTransform) or declaratively
+  with the `Mesh` `params` prop (same merge semantics - a key that
+  disappears from the object keeps its old value; for per-frame values
+  prefer `ref` + setMeshParams from onFrame, the setTransform split).
+
+Background: `scene.setBackground(source | null)`, the `background` option
+on createScene, and the reactive `Scene` prop. Fragment GLSL drawn as the
+FIRST entry of the scene's own pass (attributeless fullscreen triangle,
+depth off) - one target instead of a backdrop texture stacked under the
+scene, with no separate resize plumbing. The source gets the
+shader-target fragment contract exactly (vUV 0..1 top-left origin,
+iResolution, fragColor; no `#version` line = the standard preamble), so
+a `createShaderTexture` backdrop ports verbatim. Three's
+`scene.background = color` is `clearColor` here; a texture-id form can
+widen the signature later (a branded TextureId is a number, so
+`string | TextureId` disambiguates at runtime). No app-driven uniforms:
+a background is static art - anything animated is a mesh's own
+shaderMaterial (or, until blend factors land, a separate shader texture
+underneath, which translucent grounds also still need).
 
 Lighting GLSL (`@solidrt/3d/glsl`): exported string constants composed
 into shaderMaterial sources with plain template literals - `LIT_VERTEX`
@@ -182,14 +246,84 @@ system.
   and show mesh interiors.
 - `visible: false` keeps the entry, drawn with `instanceCount: 0` (a
   cheap off switch). Hidden meshes skip uModel writes; the fresh matrix is
-  written on unhide.
+  written on unhide. A freshly attached entry starts off the same way and
+  sync() turns it on when it writes uModel - never add one live: it has no
+  world matrix yet, and drawn before the sync microtask it flashes at the
+  world origin for a frame.
 - Alpha does not blend in v1: pipelines are opaque (`blend: "none"`), a
   translucent color overwrites. Transparency waits on blend factors +
   sorting (research note, staging step 4).
-- Rotation is Euler radians applied x, then y, then z. No quaternions in
-  v1.
-- Transforms have ONE write path: `setTransform`/`setVisible` (or the
-  props that call them). Mutating `node.position` directly does not sync.
+- Rotation is stored as a QUATERNION (`node.quaternion`, `[x, y, z, w]`,
+  always unit). There is exactly one rotation field: no `node.rotation`
+  shadowing it, because a second field is a second thing to go stale (an
+  aimed node whose Euler triple still reads as the old pose is the bug
+  this model deletes). Euler triples are a boundary format only -
+  `setTransform({ rotation })` and the `rotation` prop convert in,
+  `getRotation(node, out?)` converts out.
+- Euler triples are XYZ order (x applied first: `R = Rx * Ry * Rz`),
+  Three's `Euler` default, so a triple copied from a Three scene means the
+  same thing here. This CHANGED 2026-08-11: the old `compose()` built
+  `Rz * Ry * Rx` (Three's `'ZYX'`) while its comment claimed XYZ. Every
+  rotation triple then in the repo, examples, demos and projects was
+  single-axis, which is order-independent, so the fix moved no pixels -
+  verified, not assumed. There is ONE order and no order argument: a
+  per-call order is how one triple ends up meaning two things.
+- `getRotation` cannot recover the triple that was written, only a triple
+  meaning the same rotation (and at the poles it pins z to 0 and folds the
+  roll into x). It is for reading and debugging; anything composing or
+  interpolating rotations works with the quaternion.
+- `eulerFromQuat` extracts y with `atan2(m02, cos(y))`, NOT Three's
+  `asin(m02)`: asin's derivative blows up at the poles, turning 1e-16 of
+  matrix error into 1e-8 of angle. Same reason its pole branch starts at
+  `cos(y) < 1e-7` rather than Three's `|m02| > 0.9999999` (which is
+  `cos(y) ~ 4.5e-4` - three orders early, and inside that band Three
+  silently discards real roll). Do not "restore parity" here.
+- Aim with `lookAt(node, target, up?)`, never by extracting angles by
+  hand. Three's `Object3D.lookAt` semantics deliberately: `target` and
+  `up` are WORLD space (ancestor transforms are undone, and the ancestor
+  chain is refreshed on the spot rather than waiting for the sync), and
+  local +z ends up pointing at the target. To aim along a DIRECTION, add
+  it to `worldPosition(node)` - the same conversion Three asks for.
+  +z is the library's own sweep axis, so `extrude`/`sweep`/`tube` output
+  needs no correction. For a y-axis solid (`cylinder`, `cone`) use
+  `quatFromTo(q, [0, 1, 0], dir)` instead of correcting lookAt's +z.
+  Divergences from Three, both deliberate: `up` is an argument, NOT a
+  per-node field (Three's `object.up` is hidden state that costs a vector
+  on every node), and degenerate frames pick a stable perpendicular
+  instead of Three's epsilon nudge of the eye.
+  There is no `setTransform(node, { matrix })`, and lookAt is a MUTATOR,
+  not a rotation-returning function.
+- `quatFromTo` is Three's `setFromUnitVectors`, renamed after Unity's
+  `FromToRotation` / glam's `from_rotation_arc`: the Three name states a
+  precondition instead of the operation, and ours has no such
+  precondition (it normalizes). Check Unity/glam/Godot too before copying
+  a Three name that reads as an artifact of its class layout.
+- The composition set: `quatFromAxisAngle` (radians; normalizes the axis -
+  Three/Unity/glam all require a unit axis and silently corrupt
+  otherwise), `quatMultiply` (same order contract as the mat4 `multiply`:
+  `a * b`, b applies first; does NOT renormalize - the unit product only
+  drifts under long accumulation, and setTransform renormalizes on
+  write), `quatSlerp` (shortest path across the double cover, constant
+  angular velocity, unit output; the damped follow is
+  `quatSlerp(q, q, target, 1 - Math.exp(-k * dt))`). All aim/verb usage
+  live in `examples/aim.tsx`.
+- `setTransform` NORMALIZES an incoming quaternion, and passing `rotation`
+  and `quaternion` in one call throws. A non-unit quaternion scales
+  geometry by `|q|^2` through `compose()` - Three leaves that trap open
+  and documents it; we close it at the one write path instead of paying
+  for a check in every compose.
+- `lookAt` is exact for rotation and uniform scale up the chain. A
+  non-uniformly scaled ancestor shears the frame, so the aim is
+  approximate - Three has the identical limitation (both read the parent's
+  upper 3x3 as if it were a rotation), and the fix is not to special-case
+  it here but to not shear parents of things you aim.
+- The package root's `lookAt` is the scene verb; `@solidrt/3d/math` keeps
+  its own `lookAt` (the camera view matrix) on the SUBPATH ONLY, the same
+  collision rule the Vec3 helpers follow - and the same Object3D/Matrix4
+  split Three makes under one name. Do not re-export math's from the root.
+- Transforms have ONE write path: `setTransform`/`lookAt`/`setVisible` (or
+  the props that call them). Mutating `node.position` directly does not
+  sync. Components have no `lookAt` prop - aim through a `ref`.
 - A camera change is ONE `setTargetParams` write (uViewProj + uCamPos are
   target state), independent of mesh count - never reintroduce per-mesh
   camera writes (uEye-style per-mesh params are exactly the O(scene) cost
@@ -222,3 +356,33 @@ system.
   vertex source - a comment counts - selects the "colored" layout, and
   the material then rejects standard geometry at add(). Do not mention
   aColor you do not read.
+- Picking is the VOLUME tier: a hit means the ray crossed the mesh's
+  transformed bounding box, not its surface. Never present `point` as a
+  surface point (it is the box-entry point), and never add a
+  triangle-accurate path in JS - per-triangle rays at mesh scale are
+  interpreter-hostile; that tier is core work (BVH descent per the
+  differentiators ladder).
+- `scene.handlers` vs `handlersFor`: localX/localY arrive in the leaf's
+  LAYOUT frame (every ancestor transform and viewBox fit is already
+  undone by the element hit test). `handlers` therefore assumes leaf
+  layout == target pixels; scaling by `getBoundingBox` would be WRONG -
+  the box composes transforms, and it would double-correct the built-in
+  leaf under a viewBox. Only a leaf whose layout size deliberately
+  differs from the target (supersampling) needs `handlersFor`, fed the
+  layout size the app itself set.
+- Hover (enter/leave) reacts to pointer MOTION only: a mesh animating
+  under a still pointer fires nothing until the next move - the same
+  limit the element hit test has (hit-test-per-frame is an open platform
+  item). Do not poll pick() per frame to fake it.
+- Geometry local bounds cache on the Geometry (like its GPU buffers):
+  geometry is immutable after creation. Mutating `vertices` after a mesh
+  used them leaves stale bounds AND a stale GPU buffer - make a new
+  Geometry instead.
+- The background covers the whole target with depth off, drawn first: it
+  REPLACES the clearColor visually (the clear still runs; you just never
+  see it), and a translucent mesh does not blend over it in-pass (blend
+  is none|add today - the fade-over-backdrop look still needs the
+  two-layer composition until blend factors land).
+- The background pipeline/program are SCENE-OWNED (unlike shared
+  material pipelines): setBackground(null), replacement, and dispose()
+  destroy them. Do not hand the background's pipeline to anything else.

package/README.md

@@ -37,10 +37,34 @@ props, chain a post-effect shader target, or return null and composite
 
 There is also an imperative layer underneath (`createScene`, `createMesh`,
 `setTransform`, ...) usable without components, plus a small math module
-(`@solidrt/3d/math`: column-major mat4, perspective, lookAt). For HUD
+(`@solidrt/3d/math`: column-major mat4, perspective, lookAt). To aim a
+node, `lookAt(node, target, up?)` points its local +z at a world point,
+Three's `Object3D.lookAt`; `worldPosition(node)` is the companion for
+aiming along a direction, and `quatFromTo` aims any other axis. For HUD
 overlays, `scene.project(point)` maps a world point to scene pixels.
+
+Rotation is stored as a quaternion (`quaternion` prop, `node.quaternion`),
+so aiming and interpolation are gimbal-free and there is no second
+rotation field to fall out of step. Euler triples stay the easy way to
+author one - the `rotation` prop takes radians in XYZ order, matching
+Three's `Euler` default, and `getRotation(node)` reads one back. The
+verbs: `quatFromAxisAngle`, `quatMultiply`, and `quatSlerp` (smooth
+tracking, damped follows) round out `quatFromTo`; `examples/aim.tsx`
+shows each aiming style live.
+
+Meshes take pointer events like elements do: `onPointerDown/Move/Up/
+Enter/Leave` props on `<Mesh>` and `<Group>`, with bubbling, capture on
+drag, and hover enter/leave pairs - hit testing runs over a BVH the
+scene maintains incrementally, so events put no ceiling on scene size.
+Underneath sit `scene.pick(x, y)` (the camera ray through a pixel,
+`project()`'s inverse) and `scene.raycast(origin, direction)`; hits are
+bounding-box accurate in v1. A scene also takes a `background` - fragment
+GLSL drawn inside its own pass behind the meshes, replacing the stacked
+backdrop-texture pattern.
 Custom materials get a standard uniform set - per-mesh `uModel`/`uNormal`,
-shared `uViewProj`/`uCamPos`, each written once per change - and
+shared `uViewProj`/`uCamPos`, each written once per change - plus your own
+uniforms per mesh, declaratively via the `params` prop on `<Mesh>` or
+imperatively via `setMeshParams` - and
 `@solidrt/3d/glsl` exports the lighting pieces (hemisphere, lambert,
 blinn, fresnel, a standard vertex stage) to compose your own lit looks
 from plain template literals.
@@ -48,12 +72,14 @@ from plain template literals.
 v1 scope: unlit color/textured materials plus `shaderMaterial` (your own
 GLSL as a first-class material), geometry generators (box, plane, circle,
 ring, sphere, cylinder, cone, torus, torus knot), a profile kit for custom
-solids (`extrude` with bevels, `lathe`, flat `shape`, with `fillet`/
-`roundRect`/`triangulate` helpers), a per-vertex data channel
+solids (`extrude` with bevels, `lathe`, polyline `sweep`/`tube` with
+mitred joints, flat `shape`, with `fillet`/`roundRect`/`triangulate`
+helpers), a per-vertex data channel
 (`withColors` adds an `aColor` vec4 - tint, baked AO, any four scalars -
 to any geometry, for materials that read it), one perspective camera
-with an orbit control (`createOrbitCamera`: drag, pinch/wheel zoom, auto-orbit).
-Lights, transparency, model loading and picking are
+with an orbit control (`createOrbitCamera`: drag, pinch/wheel zoom, auto-orbit),
+mesh picking with pointer events, and scene backgrounds.
+Lights, transparency and model loading are
 staged next - see `okf/research/scene-graph-3d.md` for the roadmap. Full
 usage notes and traps: [AGENTS.md](AGENTS.md); runnable examples:
 [examples/](examples/).

package/examples/README.md

@@ -7,3 +7,19 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   texture leaf, `<PerspectiveCamera>`, a ground plane, a spinning
   `<Group>` of unlit meshes with real depth-buffer occlusion, geometry
   and pipeline sharing, and the one-signal onFrame drive.
+- `sweep-paths.tsx` - swept solids along polylines: a flat strap folding
+  over a crate (bare path points crease on the mitred bends) and a coiled
+  tube (smooth-tagged helix, one continuous mesh), lit via the exported
+  GLSL so the creased-vs-smooth normals actually show.
+- `aim.tsx` - the rotation verbs, one pointer each tracking an orbiting
+  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.
+- `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
+  compatible verbatim.

package/examples/aim.tsx

@@ -0,0 +1,119 @@
+// Aiming and rotation: a target orbits, and three fixed pointers track it,
+// each through a different rotation verb.
+//   - lookAt(node, target)      the z-axis rod: one call, world semantics
+//   - quatFromTo(y, direction)  the cone: aiming an axis other than +z
+//   - quatSlerp damped follow   the lazy cone: visibly lags, then catches up
+// All three drive their nodes from onFrame through refs - the frame-rate
+// escape hatch - so no per-frame signals exist; the one signal-free scene
+// re-renders because setTransform marks the moved nodes dirty.
+import { onFrame, pct, render } from "@solidrt/core"
+import {
+  cone,
+  lookAt,
+  Mesh,
+  PerspectiveCamera,
+  plane,
+  quat,
+  quatFromTo,
+  quatSlerp,
+  Scene,
+  setTransform,
+  sphere,
+  tube,
+  unlit,
+  worldPosition,
+} from "@solidrt/3d"
+import type { MeshNode, Vec3 } from "@solidrt/3d"
+
+const SIZE = 720
+const Y_AXIS: Vec3 = [0, 1, 0]
+
+function App() {
+  let target!: MeshNode
+  let rod!: MeshNode
+  let cannon!: MeshNode
+  let lazy!: MeshNode
+
+  // Allocated once; every per-frame write reuses them.
+  let targetPos: Vec3 = [0, 0, 0]
+  let dir: Vec3 = [0, 0, 0]
+  let aimQ = quat()
+
+  // A world-space direction from a node to the target: the documented
+  // recipe, worldPosition + subtract (exact here - the pointers have no
+  // transformed ancestors - and correct even if they get some).
+  let aimFrom = (node: MeshNode) => {
+    let p = worldPosition(node, dir)
+    dir[0] = targetPos[0] - p[0]
+    dir[1] = targetPos[1] - p[1]
+    dir[2] = targetPos[2] - p[2]
+    return dir
+  }
+
+  onFrame(tick => {
+    let t = tick / 1500
+    targetPos[0] = Math.cos(t) * 1.9
+    targetPos[1] = 1.1 + Math.sin(t * 0.7) * 0.7
+    targetPos[2] = Math.sin(t) * 1.9
+    setTransform(target, { position: targetPos })
+
+    // The rod is a +z solid (tube paths run along z): lookAt is the whole
+    // aiming story, a world-space point in, done.
+    lookAt(rod, targetPos)
+
+    // The cone points along +y, not +z, so lookAt would aim its side.
+    // quatFromTo rotates the axis you name onto the direction you want.
+    quatFromTo(aimQ, Y_AXIS, aimFrom(cannon))
+    setTransform(cannon, { quaternion: aimQ })
+
+    // Damped follow: slerp the CURRENT rotation a fixed fraction of the
+    // way toward the aimed one each frame. The 0.04 makes the lag obvious;
+    // a real app uses 1 - Math.exp(-k * dt) to stay frame-rate independent.
+    quatFromTo(aimQ, Y_AXIS, aimFrom(lazy))
+    quatSlerp(aimQ, lazy.quaternion, aimQ, 0.04)
+    setTransform(lazy, { quaternion: aimQ })
+  })
+
+  let ball = sphere(0.22)
+  let pointer = cone(0.3, 0.9)
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.07, 0.1, 1]} label="aim">
+          <PerspectiveCamera fov={55} position={[0, 2.6, 4.6]} lookAt={[0, 0.7, 0]} />
+          <Mesh
+            geometry={plane(7, 7, "floor")}
+            material={unlit({ color: [0.16, 0.17, 0.22] })}
+            rotation={[-Math.PI / 2, 0, 0]}
+          />
+          <Mesh
+            geometry={ball}
+            material={unlit({ color: [0.95, 0.85, 0.4] })}
+            ref={n => (target = n)}
+          />
+          <Mesh
+            geometry={tube([[0, 0, 0], [0, 0, 1.1]], 0.09, 10, "rod")}
+            material={unlit({ color: [0.85, 0.3, 0.3] })}
+            position={[-1.4, 0.5, 0]}
+            ref={n => (rod = n)}
+          />
+          <Mesh
+            geometry={pointer}
+            material={unlit({ color: [0.35, 0.65, 0.9] })}
+            position={[1.4, 0.5, 0]}
+            ref={n => (cannon = n)}
+          />
+          <Mesh
+            geometry={pointer}
+            material={unlit({ color: [0.45, 0.8, 0.5] })}
+            position={[0, 0.5, -1.4]}
+            ref={n => (lazy = n)}
+          />
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/pick.tsx

@@ -0,0 +1,98 @@
+// Mesh pointer events: hover to tint (enter/leave), click to pop (down),
+// with a Group seeing its children's clicks through bubbling and one mesh
+// stopping the walk. The scene is STATIC - no onFrame - so it renders only
+// when an event changes something: picking is demand-driven like
+// everything else. Events flow because the built-in <Scene> leaf carries
+// scene.handlers (default on); hit testing runs over the scene's BVH, so a
+// pointer move costs O(log meshes).
+//
+// The volume tier is honest about its shape: hits test each mesh's
+// bounding box, so hovering just outside the ball's silhouette (inside its
+// box corners) still counts. Triangle-accurate hits are a later tier.
+
+import { createSignal, pct, render } from "@solidrt/core"
+import { box, cone, Group, Mesh, PerspectiveCamera, plane, Scene, setMeshParams, setTransform, sphere, torus, unlit } from "@solidrt/3d"
+import type { Geometry, ScenePointerEvent, Vec3 } from "@solidrt/3d"
+
+const SIZE = 720
+
+type Color = [number, number, number]
+
+let [hovered, setHovered] = createSignal("nothing")
+let popped = new Set<object>()
+
+/** A pickable mesh: unlit color that brightens on hover, scale-pop on
+ * click. setMeshParams writes raw uniform values, so the tint premultiplies
+ * here (alpha 1: the rgb passes through). */
+function Pickable(p: { name: string; color: Color; geometry: Geometry; position: Vec3; scale?: number; stop?: boolean }) {
+  let lift = (up: number): [number, number, number, number] => [
+    Math.min(p.color[0] + up, 1),
+    Math.min(p.color[1] + up, 1),
+    Math.min(p.color[2] + up, 1),
+    1,
+  ]
+  return (
+    <Mesh
+      geometry={p.geometry}
+      material={unlit({ color: p.color })}
+      position={p.position}
+      scale={p.scale}
+      onPointerEnter={(e: ScenePointerEvent) => {
+        setHovered(p.name)
+        setMeshParams(e.mesh, { uColor: lift(0.25) })
+        console.log(`enter ${p.name}`)
+      }}
+      onPointerLeave={(e: ScenePointerEvent) => {
+        setHovered("nothing")
+        setMeshParams(e.mesh, { uColor: lift(0) })
+        console.log(`leave ${p.name}`)
+      }}
+      onPointerDown={(e: ScenePointerEvent) => {
+        let pop = !popped.has(e.mesh)
+        if (pop) popped.add(e.mesh)
+        else popped.delete(e.mesh)
+        setTransform(e.mesh, { scale: pop ? (p.scale ?? 1) * 1.25 : (p.scale ?? 1) })
+        let pt = e.point!
+        console.log(`down ${p.name} at ${pt[0].toFixed(2)},${pt[1].toFixed(2)},${pt[2].toFixed(2)} d=${e.distance!.toFixed(2)}`)
+        // The cone demonstrates stopping the bubble: its group never hears it.
+        if (p.stop) e.stopPropagation()
+      }}
+    />
+  )
+}
+
+function App() {
+  let floor = plane(8, 8, "floor")
+  let crate = box()
+  let ball = sphere(0.45)
+  let spike = cone(0.45, 1)
+  let ring = torus(0.4, 0.14)
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.07, 0.1, 1]} label="pick">
+          <PerspectiveCamera fov={55} position={[0, 2.6, 5]} lookAt={[0, 0.4, 0]} />
+          <Mesh geometry={floor} material={unlit({ color: [0.15, 0.16, 0.2] })} rotation={[-Math.PI / 2, 0, 0]} />
+          {/* The group hears every child click that is not stopped. */}
+          <Group onPointerDown={() => console.log("group saw down")}>
+            <Pickable name="crate" color={[0.85, 0.3, 0.3]} geometry={crate} position={[-1.6, 0.4, 0]} scale={0.8} />
+            <Pickable name="cone" color={[0.35, 0.65, 0.9]} geometry={spike} position={[1.6, 0.5, 0]} stop />
+          </Group>
+          <Pickable name="ball" color={[0.9, 0.8, 0.35]} geometry={ball} position={[0, 0.45, 0]} />
+          <Pickable name="ring" color={[0.5, 0.85, 0.5]} geometry={ring} position={[0.9, 0.35, -1.6]} />
+        </Scene>
+        <view position="absolute" x={0} y={0} padding={16} gap={4}>
+          <text color="#eef4ff" fontSize={22} fontWeight={700}>
+            {`hover: ${hovered()}`}
+          </text>
+          <text color="#8fa6c8" fontSize={13}>
+            hover tints, click pops - a static scene, rendered only on change
+          </text>
+        </view>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/scene-background.tsx

@@ -0,0 +1,43 @@
+// A scene background: fragment GLSL drawn as the first entry of the
+// scene's own pass - no second target, no stacked texture layers, no
+// resize plumbing. The source below uses only the shader-target contract
+// (vUV, iResolution, fragColor), so it would work unchanged in
+// createShaderTexture; here it costs nothing extra - the one scene pass
+// paints backdrop and meshes together, and a static scene still renders
+// zero passes when idle.
+
+import { pct, render } from "@solidrt/core"
+import { glsl } from "@solidrt/core/gpu"
+import { box, Mesh, PerspectiveCamera, Scene, sphere, torusKnot, unlit } from "@solidrt/3d"
+
+const SIZE = 720
+
+// A radial night-sky gradient with hash grain so the ramp does not band.
+let BACKDROP = glsl`
+  void main() {
+    float d = distance(vUV, vec2(0.5, 0.35));
+    vec3 near = vec3(0.10, 0.13, 0.22);
+    vec3 far = vec3(0.02, 0.03, 0.06);
+    vec3 col = mix(near, far, smoothstep(0.05, 0.9, d));
+    float n = fract(sin(dot(vUV * iResolution, vec2(12.9898, 78.233))) * 43758.5453);
+    col += (n - 0.5) * 0.012;
+    fragColor = vec4(col, 1.0);
+  }
+`
+
+function App() {
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+        <Scene width={SIZE} height={SIZE} background={BACKDROP} label="backdrop-demo">
+          <PerspectiveCamera fov={55} position={[0, 1.8, 4.4]} lookAt={[0, 0.4, 0]} />
+          <Mesh geometry={torusKnot(0.7, 0.2, 128, 16)} material={unlit({ color: [0.85, 0.55, 0.25] })} position={[0, 0.9, 0]} />
+          <Mesh geometry={box()} material={unlit({ color: [0.3, 0.5, 0.8] })} position={[-1.5, 0.4, -0.5]} scale={0.8} />
+          <Mesh geometry={sphere(0.4)} material={unlit({ color: [0.4, 0.75, 0.45] })} position={[1.5, 0.4, -0.5]} />
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/sweep-paths.tsx

@@ -0,0 +1,79 @@
+// Swept solids along 3D polylines. sweep() runs a 2D profile along a
+// path with mitred joints: bare path points crease - the strap folds
+// over the crate's edges like real webbing - while smooth-tagged points
+// share averaged normals, so the helix sweeps into ONE continuous coil
+// (per-segment boxes with unmitred gaps are exactly what this replaces).
+// tube() is the round-profile shorthand. Lit materials on purpose:
+// creased vs smooth joints differ only in normals, which unlit color
+// would hide.
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { box, Group, Mesh, PerspectiveCamera, plane, roundRect, Scene, shaderMaterial, sweep, tube, unlit } from "@solidrt/3d"
+import type { SweepPath } from "@solidrt/3d"
+import { HEMISPHERE, LAMBERT, LIT_VERTEX } from "@solidrt/3d/glsl"
+
+const SIZE = 720
+
+function App() {
+  let [spin, setSpin] = createSignal(0)
+  onFrame(tick => setSpin(tick / 4000))
+
+  // One hemisphere + lambert look per color (a material instance is the
+  // pipeline handle, so each look is created once and shared).
+  let lit = (r: number, g: number, b: number) =>
+    shaderMaterial({
+      vertex: LIT_VERTEX,
+      fragment: `
+        in vec3 vNormal;
+        ${HEMISPHERE}
+        ${LAMBERT}
+        void main() {
+          vec3 n = normalize(vNormal);
+          vec3 l = normalize(vec3(0.5, 0.8, 0.4));
+          vec3 base = vec3(${r}, ${g}, ${b});
+          fragColor = vec4(base * (hemisphere(n, vec3(0.45), vec3(0.22)) + 0.8 * lambert(n, l)), 1.0);
+        }`,
+    })
+
+  // The strap hugs the crate at half its thickness; every bend is a bare
+  // (sharp) point, so each fold creases exactly on a crate edge.
+  let o = 0.013
+  let strapPath: SweepPath = [
+    [-1.75, o, 0],
+    [-1.3 - o, o, 0],
+    [-1.3 - o, 0.6 + o, 0],
+    [-0.3 + o, 0.6 + o, 0],
+    [-0.3 + o, o, 0],
+    [0.15, o, 0],
+  ]
+  let strap = sweep(roundRect(0.3, 0.026, 0.008), strapPath, "strap")
+
+  // A smooth-tagged helix: one continuous tube, not a stack of segments.
+  let coilPath: SweepPath = []
+  for (let i = 0; i <= 60; i++) {
+    let a = (i / 60) * Math.PI * 5
+    coilPath.push({ p: [0.85 + Math.cos(a) * 0.35, 0.055 + i * 0.0095, Math.sin(a) * 0.35], smooth: true })
+  }
+  let coil = tube(coilPath, 0.05, 12, "coil")
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.07, 0.1, 1]} label="sweep-paths">
+          <PerspectiveCamera fov={55} position={[0, 1.9, 3.9]} lookAt={[0, 0.35, 0]} />
+          <Mesh
+            geometry={plane(6, 6, "floor")}
+            material={unlit({ color: [0.16, 0.17, 0.22] })}
+            rotation={[-Math.PI / 2, 0, 0]}
+          />
+          <Group rotation={[0, spin(), 0]}>
+            <Mesh geometry={box(1, 0.6, 0.8)} material={lit(0.55, 0.42, 0.28)} position={[-0.8, 0.3, 0]} />
+            <Mesh geometry={strap} material={lit(0.9, 0.55, 0.2)} />
+            <Mesh geometry={coil} material={lit(0.45, 0.6, 0.8)} />
+          </Group>
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)