@solidrt/3d 0.0.58 → 0.0.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.58",
+  "version": "0.0.60",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -18,7 +18,7 @@
     "AGENTS.md"
   ],
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.6",
-    "@solidrt/core": "0.0.58"
+    "@solidjs/signals": "2.0.0-rc.8",
+    "@solidrt/core": "0.0.60"
   }
 }

package/src/clip.ts

@@ -6,18 +6,31 @@ import { quatNormalize, quatSlerp } from "./math.ts"
 import type { Quat } from "./math.ts"
 import type { ModelChannel } from "./gltf.ts"
 
+/**
+ * Floats per key value of a channel: 3 for position and scale, 4 for a
+ * rotation, and for a weights channel one per morph target - read off
+ * the data, since the key count and the cubic triple fix it.
+ */
+export function channelElements(channel: ModelChannel): number {
+  if (channel.path === "rotation") return 4
+  if (channel.path !== "weights") return 3
+  let perKey = channel.interpolation === "cubic" ? 3 : 1
+  return channel.times.length === 0 ? 0 : channel.values.length / (channel.times.length * perKey)
+}
+
 /**
  * Sample one channel at `time` (seconds, clamped to the key range) into
- * `out` - 3 floats for position/scale, 4 for rotation. Pure array math:
- * step holds the earlier key, linear lerps (rotation slerps the shortest
- * path), cubic evaluates the glTF CUBICSPLINE Hermite (rotation
- * renormalized, per spec).
+ * `out` - 3 floats for position/scale, 4 for rotation, one per target
+ * for weights (`channelElements`). Pure array math: step holds the
+ * earlier key, linear lerps (rotation slerps the shortest path), cubic
+ * evaluates the glTF CUBICSPLINE Hermite (rotation renormalized, per
+ * spec).
  */
 export function sampleChannel(channel: ModelChannel, time: number, out: number[]): void {
   let times = channel.times
   let values = channel.values
   let keys = times.length
-  let elements = channel.path === "rotation" ? 4 : 3
+  let elements = channelElements(channel)
   let stride = channel.interpolation === "cubic" ? elements * 3 : elements
   // The value element offset within a key: cubic keys are [in, value, out].
   let mid = channel.interpolation === "cubic" ? elements : 0

package/src/color.ts

@@ -4,8 +4,8 @@
 // is sRGB-encoded, what a color picker shows, and the library decodes it to
 // linear light when it writes the uniform (Three's ColorManagement,
 // Godot's inspector colors, Unity's linear color space all do the same).
-// Shading then runs in linear light and the fragment's output stage
-// (OUTPUT in ./glsl) encodes the result back. Values written straight to
+// Shading then runs in linear light into the scene's buffer, and the
+// target's resolve pass (RESOLVE in ./glsl) encodes the result back. Values written straight to
 // a uniform (scene.setParams, setMeshParams) and vertex colors are linear,
 // as in every engine; encode or decode them here when they come from a
 // picker.
@@ -30,3 +30,12 @@ export function linearColor(color: readonly number[]): number[] {
   for (let i = 0; i < 3 && i < out.length; i++) out[i] = srgbToLinear(out[i]!)
   return out
 }
+
+/** An [r, g, b] or [r, g, b, a] sRGB color as the premultiplied linear
+ * vec4 the shaders take (uColor, aColor, iColor): rgb decoded to linear
+ * light and multiplied by the alpha, which is 1 when absent. */
+export function premultipliedColor(color: readonly number[]): number[] {
+  let a = color.length === 4 ? color[3]! : 1
+  let c = linearColor(color)
+  return [c[0]! * a, c[1]! * a, c[2]! * a, a]
+}

package/src/components/context.tsx

@@ -5,8 +5,8 @@ import type { Scene as SceneHandle } from "../scene.ts"
 import type { CameraState, CameraUpdate } from "../camera.ts"
 
 /** The camera state a camera control drives: the scene, or a view (both
- * expose setCamera and camera()). */
-export type CameraTarget = { setCamera(update: CameraUpdate): void; camera(): CameraState }
+ * expose setCamera, camera() and size()). */
+export type CameraTarget = { setCamera(update: CameraUpdate): void; camera(): CameraState; size(): { width: number; height: number } }
 
 export type SceneCtx = { scene: SceneHandle; parent: SceneNode; viewport: CameraTarget; pointer: PointerFeed | null }
 export let SceneContext = createContext<SceneCtx>()
@@ -33,3 +33,12 @@ export function provide(ctx: SceneCtx, parent: SceneNode, props: { children?: El
   if (!("children" in props)) return undefined
   return <SceneContext value={{ scene: ctx.scene, parent, viewport: ctx.viewport, pointer: ctx.pointer }}>{props.children}</SceneContext>
 }
+
+/** What a `<Lod>` hands its children: a direct child with `lodSize`
+ * registers itself as a level. */
+export type LodRegistry = {
+  group: SceneNode
+  register(node: SceneNode, size: number): void
+  unregister(node: SceneNode): void
+}
+export let LodContext = createContext<LodRegistry | undefined>(undefined)

package/src/components/directional-light.tsx

@@ -3,7 +3,7 @@ import type { VoidComponent } from "@solidrt/core"
 import { SceneContext } from "./context.tsx"
 import { syncNode } from "./node-props.ts"
 import type { TransformProps } from "./node-props.ts"
-import { add, remove } from "../node.ts"
+import { add, destroy } from "../node.ts"
 import { createDirectionalLight, setLight } from "../light.ts"
 import type { DirectionalLight as DirectionalLightNode, ShadowOptions } from "../light.ts"
 import type { Vec3 } from "../math.ts"
@@ -43,6 +43,6 @@ export let DirectionalLight: VoidComponent<DirectionalLightProps> = props => {
     ([direction, color, intensity, castShadow, shadow]) => setLight(light, { direction, color, intensity, castShadow, shadow }),
   )
   untrack(() => props.ref)?.(light)
-  onCleanup(() => remove(light))
+  onCleanup(() => destroy(light))
   return null
 }

package/src/components/first-person-camera.tsx

@@ -15,8 +15,8 @@ export type FirstPersonCameraProps = FirstPersonCameraOptions & {
   input?: InputMap<any>
   /** Action names per axis when the map's differ (null skips an axis). */
   actions?: Partial<Record<keyof FirstPersonAxes, string | null>>
-  /** The control's handle (pose()/set()/eye()/forward()/active(), the
-   * verbs, `axes` - also the debug command shape). */
+  /** The control's handle (pose()/set()/glideTo()/eye()/forward()/
+   * active(), the verbs, `axes` - also the debug command shape). */
   ref?: (camera: FirstPersonCameraHandle) => void
 }
 
@@ -35,8 +35,8 @@ export type FirstPersonCameraProps = FirstPersonCameraOptions & {
  * `fly={flying()}` swaps walk and fly on the running control (pose
  * carries over, no remount), `moveSpeed`, `lookSpeed` and
  * `clampPosition` follow their props, and a pitch clamp change re-clamps
- * at once. A frame loop runs only while `active()` - a rate driving - so
- * a still scene stays demand-driven idle.
+ * at once. A frame loop runs only while `active()` - a rate driving, or
+ * a glide in flight - so a still scene stays demand-driven idle.
  */
 export let FirstPersonCamera: VoidComponent<FirstPersonCameraProps> = props => {
   let ctx = useContext(SceneContext)

package/src/components/group.tsx

@@ -2,17 +2,21 @@ import { onCleanup, untrack, useContext } from "@solidrt/core"
 import type { ParentComponent } from "@solidrt/core"
 import { SceneContext, provide } from "./context.tsx"
 import { syncNode } from "./node-props.ts"
-import type { TransformProps, PointerEventProps } from "./node-props.ts"
-import { add, createGroup, remove } from "../node.ts"
+import type { TransformProps, BubblingPointerEventProps } from "./node-props.ts"
+import { add, createGroup, destroy } from "../node.ts"
 import type { SceneNode } from "../node.ts"
 
-/** A transform node: children inherit its position/rotation/scale. */
-export let Group: ParentComponent<TransformProps & PointerEventProps & { ref?: (node: SceneNode) => void }> = props => {
+export type GroupProps = TransformProps & BubblingPointerEventProps & { ref?: (node: SceneNode) => void }
+
+/** A transform node: children inherit its position/rotation/scale. Its
+ * pointer events are the ones bubbling up from a hit descendant; a group
+ * is never the struck node, so it takes no enter/leave. */
+export let Group: ParentComponent<GroupProps> = props => {
   let ctx = useContext(SceneContext)
   let node = createGroup()
   add(ctx.parent, node)
   syncNode(node, props)
   untrack(() => props.ref)?.(node)
-  onCleanup(() => remove(node))
+  onCleanup(() => destroy(node))
   return provide(ctx, node, props)
 }

package/src/components/hemisphere-light.tsx

@@ -1,7 +1,7 @@
 import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
 import type { VoidComponent } from "@solidrt/core"
 import { SceneContext } from "./context.tsx"
-import { add, remove } from "../node.ts"
+import { add, destroy } from "../node.ts"
 import { createHemisphereLight, setLight } from "../light.ts"
 import type { HemisphereLight as HemisphereLightNode } from "../light.ts"
 import type { Vec3 } from "../math.ts"
@@ -19,6 +19,6 @@ export let HemisphereLight: VoidComponent<HemisphereLightProps> = props => {
     ([sky, ground, intensity]) => setLight(light, { sky, ground, intensity }),
   )
   untrack(() => props.ref)?.(light)
-  onCleanup(() => remove(light))
+  onCleanup(() => destroy(light))
   return null
 }

package/src/components/index.ts

@@ -16,18 +16,21 @@
 
 export { useScene } from "./context.tsx"
 export type { CameraTarget } from "./context.tsx"
-export type { PointerEventProps, TransformProps } from "./node-props.ts"
+export type { BubblingPointerEventProps, PointerEventProps, TransformProps } from "./node-props.ts"
 export { Scene } from "./scene.tsx"
 export type { ScenePointerProps, SceneProps } from "./scene.tsx"
 export { View3d } from "./view3d.tsx"
 export type { View3dProps } from "./view3d.tsx"
 export { Group } from "./group.tsx"
+export type { GroupProps } from "./group.tsx"
 export { Mesh } from "./mesh.tsx"
 export type { MeshProps } from "./mesh.tsx"
 export { Sprite } from "./sprite.tsx"
 export type { SpriteProps } from "./sprite.tsx"
 export { Instance, InstancedMesh } from "./instanced-mesh.tsx"
 export type { InstancedMeshProps, InstanceProps } from "./instanced-mesh.tsx"
+export { InstancedLod, Lod } from "./lod.tsx"
+export type { InstancedLodProps, LodProps } from "./lod.tsx"
 export { RecordMesh } from "./record-mesh.tsx"
 export type { RecordMeshProps } from "./record-mesh.tsx"
 export { PerspectiveCamera } from "./perspective-camera.tsx"

package/src/components/instanced-mesh.tsx

@@ -5,8 +5,9 @@ import { syncNode } from "./node-props.ts"
 import type { TransformProps, PointerEventProps } from "./node-props.ts"
 import { syncMesh } from "./mesh.tsx"
 import type { PopulatedMeshProps } from "./mesh.tsx"
-import { add } from "../node.ts"
-import { addInstance, createInstancedMesh, disposeInstances, removeInstance, setCastShadow, setGeometry, setInstanceStyle } from "../mesh.ts"
+import { add, destroy, setMorphWeights } from "../node.ts"
+import type { MorphWeights } from "../node.ts"
+import { addInstance, createInstancedMesh, disposeInstances, setCastShadow, setGeometry, setInstanceStyle } from "../mesh.ts"
 import type { InstancedMesh as InstancedMeshNode, InstanceNode } from "../mesh.ts"
 import type { Geometry } from "../geometry.ts"
 import type { Material } from "../material.ts"
@@ -15,7 +16,7 @@ export type InstancedMeshProps = PopulatedMeshProps & {
   geometry: Geometry
   /** An instanced material: a stock one with `instanced` (or
    * `instanceColors`, for a per-instance tint), or a class declaring
-   * INSTANCE_MATRIX_ATTRIBUTES in slot 0 and any style layout in slot 1. */
+   * INSTANCE_MATRIX_ATTRIBUTES first and any style layout second. */
   material: Material
   /** Instance slots reserved up front (default 64; fixed at creation).
    * Past it the buffers double into replacements - amortized, but size it
@@ -35,7 +36,9 @@ export type InstancedMeshProps = PopulatedMeshProps & {
   ref?: (mesh: InstancedMeshNode) => void
 }
 
-let InstancedMeshContext = createContext<InstancedMeshNode | null>(null)
+/** The enclosing population, what `<Instance>` adds itself to: an
+ * `<InstancedMesh>`, or an `<InstancedLod>`'s first level. */
+export let InstancedMeshContext = createContext<InstancedMeshNode | null>(null)
 
 /**
  * One draw entry covering N instance NODES (createInstancedMesh as a
@@ -63,7 +66,10 @@ export let InstancedMesh: ParentComponent<InstancedMeshProps> = props => {
   )
   syncMesh(mesh, props)
   untrack(() => props.ref)?.(mesh)
-  onCleanup(() => disposeInstances(mesh))
+  onCleanup(() => {
+    destroy(mesh)
+    disposeInstances(mesh)
+  })
   return (
     <SceneContext value={{ scene: ctx.scene, parent: mesh, viewport: ctx.viewport, pointer: ctx.pointer }}>
       <InstancedMeshContext value={mesh}>{props.children}</InstancedMeshContext>
@@ -72,11 +78,17 @@ export let InstancedMesh: ParentComponent<InstancedMeshProps> = props => {
 }
 
 export type InstanceProps = TransformProps & PointerEventProps & {
-  /** The instance's style record (setInstanceStyle as a prop): the
-   * floats of the material's slot-1 instance attributes - `[r, g, b, a]`
-   * under a stock material's `instanceColors`. Reactive; absent, the
-   * instance keeps the material's instanceStyle (white for a tint). */
+  /** The instance's style record (setInstanceStyle as a prop): one value
+   * per component of the material's second instance buffer, in order -
+   * `[r, g, b, a]` under a stock material's `instanceColors`. Reactive;
+   * absent, the instance keeps the material's instanceStyle (white for
+   * a tint). */
   style?: ArrayLike<number>
+  /** The instance's morph target weights (setMorphWeights as a prop),
+   * for a population over geometry with `morphs` under a `morph: true`
+   * material: by name (keys merge) or every weight in target order; a
+   * `weights` entry in `transition` animates each change. */
+  morphWeights?: MorphWeights
   ref?: (instance: InstanceNode) => void
 }
 
@@ -99,7 +111,13 @@ export let Instance: ParentComponent<InstanceProps> = props => {
       if (s !== undefined) setInstanceStyle(instance, s)
     },
   )
+  createEffect(
+    () => props.morphWeights,
+    w => {
+      if (w !== undefined) setMorphWeights(instance, w)
+    },
+  )
   untrack(() => props.ref)?.(instance)
-  onCleanup(() => removeInstance(instance))
+  onCleanup(() => destroy(instance))
   return provide(ctx, instance, props)
 }

package/src/components/lod.tsx

@@ -0,0 +1,102 @@
+import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+import type { ParentComponent } from "@solidrt/core"
+import { LodContext, SceneContext, provide } from "./context.tsx"
+import type { LodRegistry } from "./context.tsx"
+import { syncNode } from "./node-props.ts"
+import type { TransformProps, BubblingPointerEventProps } from "./node-props.ts"
+import { syncMesh } from "./mesh.tsx"
+import type { PopulatedMeshProps } from "./mesh.tsx"
+import { InstancedMeshContext } from "./instanced-mesh.tsx"
+import { add, createGroup, destroy } from "../node.ts"
+import type { SceneNode } from "../node.ts"
+import { createInstancedLod, setLod } from "../lod.ts"
+import type { InstancedLodLevel } from "../lod.ts"
+import { disposeInstances, setCastShadow } from "../mesh.ts"
+import type { InstancedMesh as InstancedMeshNode } from "../mesh.ts"
+
+export type LodProps = TransformProps &
+  BubblingPointerEventProps & {
+    /** The cross-fade band fraction (createLod's `fade`); default 0. */
+    fade?: number
+    ref?: (node: SceneNode) => void
+  }
+
+/**
+ * A LOD group (createLod as a component): its levels are the direct
+ * children carrying `lodSize` - the projected size below which each hands
+ * over - in any JSX order (levels sort by size, never by position, since
+ * attach order is not JSX order); a child without one is drawn always.
+ * Levels may come and go (`<Show>`): the group re-declares itself.
+ */
+export let Lod: ParentComponent<LodProps> = props => {
+  let ctx = useContext(SceneContext)
+  let node = createGroup()
+  add(ctx.parent, node)
+  syncNode(node, props)
+  let sizes = new Map<SceneNode, number>()
+  let declare = () => {
+    let levels = [...sizes.entries()].sort((a, b) => b[1] - a[1]).map(([n, size]) => ({ node: n, size }))
+    setLod(node, levels, { fade: untrack(() => props.fade) })
+  }
+  let registry: LodRegistry = {
+    group: node,
+    register(child, size) {
+      if (child.parent !== node) throw new Error("lodSize goes on a direct child of <Lod>")
+      sizes.set(child, size)
+      declare()
+    },
+    unregister(child) {
+      if (sizes.delete(child)) declare()
+    },
+  }
+  createEffect(
+    () => props.fade,
+    () => declare(),
+    { defer: true },
+  )
+  untrack(() => props.ref)?.(node)
+  onCleanup(() => destroy(node))
+  return <LodContext value={registry}>{provide(ctx, node, props)}</LodContext>
+}
+
+export type InstancedLodProps = PopulatedMeshProps & {
+  /** The levels nearest first, each what the population draws at it and
+   * the per-instance projected size below which it hands over (see
+   * createInstancedLod); fixed at creation. */
+  levels: InstancedLodLevel[]
+  /** Instance slots reserved up front (default 64; fixed at creation). */
+  capacity?: number
+  /** LOCAL bounds covering the population, fixed at creation (see
+   * InstancedMesh). */
+  bounds?: ArrayLike<number>
+  label?: string
+  /** Every level draws into the scene's shadow map; default false. */
+  castShadow?: boolean
+  ref?: (mesh: InstancedMeshNode) => void
+}
+
+/**
+ * An instanced LOD (createInstancedLod as a component): `<Instance>`
+ * children populate it exactly as under `<InstancedMesh>`, and each
+ * instance draws the level its own projected size picks.
+ */
+export let InstancedLod: ParentComponent<InstancedLodProps> = props => {
+  let ctx = useContext(SceneContext)
+  let mesh = untrack(() => createInstancedLod(props.levels, { capacity: props.capacity, bounds: props.bounds, label: props.label }))
+  add(ctx.parent, mesh)
+  createEffect(
+    () => props.castShadow,
+    c => setCastShadow(mesh, c === true),
+  )
+  syncMesh(mesh, props)
+  untrack(() => props.ref)?.(mesh)
+  onCleanup(() => {
+    destroy(mesh)
+    disposeInstances(mesh)
+  })
+  return (
+    <SceneContext value={{ scene: ctx.scene, parent: mesh, viewport: ctx.viewport, pointer: ctx.pointer }}>
+      <InstancedMeshContext value={mesh}>{props.children}</InstancedMeshContext>
+    </SceneContext>
+  )
+}

package/src/components/mesh.tsx

@@ -3,7 +3,8 @@ import type { VoidComponent } from "@solidrt/core"
 import { SceneContext } from "./context.tsx"
 import { syncNode } from "./node-props.ts"
 import type { TransformProps, PointerEventProps } from "./node-props.ts"
-import { add, remove } from "../node.ts"
+import { add, destroy, setMorphWeights } from "../node.ts"
+import type { MorphWeights } from "../node.ts"
 import { createMesh, setCastShadow, setCulling, setGeometry, setLayers, setMaterial, setMeshParams, setRenderOrder } from "../mesh.ts"
 import type { Mesh as MeshNode } from "../mesh.ts"
 import type { ShaderParams } from "@solidrt/core/gpu"
@@ -32,6 +33,13 @@ export type MeshProps = TransformProps & PointerEventProps & {
   frustumCulled?: boolean
   /** World units the culled box grows by (setCulling as a prop; default 0). */
   cullMargin?: number
+  /** Morph target weights (setMorphWeights as a prop) for geometry that
+   * carries `morphs` under a `morph: true` material: by name (keys merge,
+   * a key that disappears keeps its weight) or every weight in target
+   * order. A `weights` entry in `transition` animates each change. For
+   * weights changing every frame prefer `ref` + setMorphWeights from
+   * onFrame, the same split as setTransform. */
+  morphWeights?: MorphWeights
   ref?: (mesh: MeshNode) => void
 }
 
@@ -40,10 +48,13 @@ export type MeshProps = TransformProps & PointerEventProps & {
 // take them); the
 // ref and the cleanup are each component's own (a populated mesh frees
 // its buffers, a plain one is removed).
-export function syncMesh(mesh: MeshNode, props: Omit<MeshProps, "geometry" | "castShadow" | "ref">): void {
+export function syncMesh(mesh: MeshNode, props: Omit<MeshProps, "geometry" | "material" | "castShadow" | "ref"> & { material?: Material }): void {
+  // Absent on an <InstancedLod>, whose levels each carry their own.
   createEffect(
     () => props.material,
-    m => setMaterial(mesh, m),
+    m => {
+      if (m !== undefined) setMaterial(mesh, m)
+    },
     { defer: true },
   )
   createEffect(
@@ -81,12 +92,19 @@ export let Mesh: VoidComponent<MeshProps> = props => {
     () => props.castShadow,
     c => setCastShadow(mesh, c === true),
   )
+  createEffect(
+    () => props.morphWeights,
+    w => {
+      if (w !== undefined) setMorphWeights(mesh, w)
+    },
+  )
   syncMesh(mesh, props)
   untrack(() => props.ref)?.(mesh)
-  onCleanup(() => remove(mesh))
+  onCleanup(() => destroy(mesh))
   return null
 }
 
 // The props both populated meshes share with Mesh: everything but the
-// geometry/material pair (documented per component) and the ref.
-export type PopulatedMeshProps = Omit<MeshProps, "geometry" | "material" | "ref">
+// geometry/material pair (documented per component), the ref and the
+// morph weights (a populated mesh does not morph yet).
+export type PopulatedMeshProps = Omit<MeshProps, "geometry" | "material" | "ref" | "morphWeights">

package/src/components/node-props.ts

@@ -1,4 +1,5 @@
-import { createEffect } from "@solidrt/core"
+import { createEffect, onCleanup, useContext } from "@solidrt/core"
+import { LodContext } from "./context.tsx"
 import { setTransform, setTransition, setVisible } from "../node.ts"
 import type { NodePointerEvent, NodeTapEvent, NodeWheelEvent, SceneNode, TransitionEndEvent } from "../node.ts"
 import type { NodeTransition } from "flux:spatial"
@@ -18,6 +19,10 @@ export type TransformProps = {
   transition?: NodeTransition | string | null
   /** A declared transition settled on one component. */
   onTransitionEnd?: (event: TransitionEndEvent) => void
+  /** Under a `<Lod>`: this node is a level of it, drawn while the group's
+   * projected size is at or above this and below the next larger level's
+   * (see createLod). Only on a direct child of `<Lod>`; throws elsewhere. */
+  lodSize?: number
 }
 
 /**
@@ -31,13 +36,20 @@ export type TransformProps = {
  * the built-in <Scene> leaf does (opt out with events={false}); an `output`
  * leaf spreads them itself.
  */
-export type PointerEventProps = {
+export type PointerEventProps = BubblingPointerEventProps & {
+  /** Hover: enter/leave pair on the struck node alone, so only a hit
+   * target - a mesh or an instance - takes them; `<Group>` and `<Lod>`
+   * bubble and omit the pair. */
+  onPointerEnter?: (event: NodePointerEvent) => void
+  onPointerLeave?: (event: NodePointerEvent) => void
+}
+
+/** The pointer props every node takes: the events that bubble from the
+ * hit up through the Groups above it, without the hover pair. */
+export type BubblingPointerEventProps = {
   onPointerDown?: (event: NodePointerEvent) => void
   onPointerMove?: (event: NodePointerEvent) => void
   onPointerUp?: (event: NodePointerEvent) => void
-  /** Meshes and instances only: a Group never receives enter/leave. */
-  onPointerEnter?: (event: NodePointerEvent) => void
-  onPointerLeave?: (event: NodePointerEvent) => void
   /** The wheel over the node: `deltaX`/`deltaY`. */
   onWheel?: (event: NodeWheelEvent) => void
   /** A press released on the node within the slop, alone for its whole
@@ -87,4 +99,22 @@ export function syncNode(node: SceneNode, props: TransformProps & PointerEventPr
     () => props.transition,
     transition => setTransition(node, transition ?? null),
   )
+  // A level of the enclosing <Lod>, keyed by size; built only when the
+  // prop is present (the compiler emits the getter only then), so a plain
+  // node pays nothing.
+  if ("lodSize" in props) {
+    let lod = useContext(LodContext)
+    createEffect(
+      () => props.lodSize,
+      size => {
+        if (size === undefined) {
+          lod?.unregister(node)
+          return
+        }
+        if (lod === undefined) throw new Error("lodSize needs a <Lod> parent")
+        lod.register(node, size)
+      },
+    )
+    onCleanup(() => lod?.unregister(node))
+  }
 }

package/src/components/orbit-camera.tsx

@@ -15,8 +15,9 @@ export type OrbitCameraProps = OrbitCameraOptions & {
   input?: InputMap<any>
   /** Action names per axis when the map's differ (null skips an axis). */
   actions?: Partial<Record<keyof OrbitAxes, string | null>>
-  /** The control's handle (pose()/set()/eye()/orbiting()/active(), the
-   * verbs, `axes` - also the debug command shape). */
+  /** The control's handle (pose()/set()/glideTo()/fit()/eye()/
+   * orbiting()/active(), the verbs, `axes` - also the debug command
+   * shape). */
   ref?: (orbit: OrbitCameraHandle) => void
 }
 
@@ -29,9 +30,10 @@ export type OrbitCameraProps = OrbitCameraOptions & {
  * (target, azimuth, elevation, distance) are initial values - change the
  * pose at runtime through `ref`'s set() or the verbs; every other prop is
  * live, forwarded to the control as a getter and read where it applies,
- * so a clamp, a rate or an anchor callback follows its prop, and a clamp
- * change re-clamps the pose at once. The frame loop runs only while
- * `active()` (auto-orbit on, or an axis rate driving); a camera moved
+ * so a clamp, a rate, `damping` or an anchor callback follows its prop,
+ * and a clamp change (`clampPose` included) re-clamps the pose at once.
+ * The frame loop runs only while `active()` (auto-orbit on, a glide or
+ * damped wheel notch in flight, or an axis rate driving); a camera moved
  * by drags alone leaves the app demand-driven idle.
  */
 export let OrbitCamera: VoidComponent<OrbitCameraProps> = props => {
@@ -59,14 +61,15 @@ export let OrbitCamera: VoidComponent<OrbitCameraProps> = props => {
     },
   )
   // A clamp prop change re-clamps the pose at once (set({}) applies the
-  // clamps and pushes) - the update() call a Three OrbitControls app
-  // makes after setting minDistance, done by the prop. Deferred: the
-  // creation already clamped and pushed the initial pose. Untracked: the
-  // control reads the clamps through the getters while it applies them,
-  // and the apply wants the values of that moment (the compute above is
-  // what tracks them).
+  // clamps and pushes, and writes no pose field, so a glide in flight
+  // keeps running) - the update() call a Three OrbitControls app makes
+  // after setting minDistance, done by the prop. Deferred: the creation
+  // already clamped and pushed the initial pose. Untracked: the control
+  // reads the clamps through the getters while it applies them, and the
+  // apply wants the values of that moment (the compute above is what
+  // tracks them).
   createEffect(
-    () => [options.minDistance, options.maxDistance, options.minElevation, options.maxElevation],
+    () => [options.minDistance, options.maxDistance, options.minElevation, options.maxElevation, options.clampPose],
     () => untrack(() => orbit.set({})),
     { defer: true },
   )

package/src/components/point-light.tsx

@@ -3,7 +3,7 @@ import type { VoidComponent } from "@solidrt/core"
 import { SceneContext } from "./context.tsx"
 import { syncNode } from "./node-props.ts"
 import type { TransformProps } from "./node-props.ts"
-import { add, remove } from "../node.ts"
+import { add, destroy } from "../node.ts"
 import { createPointLight, setLight } from "../light.ts"
 import type { PointLight as PointLightNode, SpotShadowOptions } from "../light.ts"
 import type { Vec3 } from "../math.ts"
@@ -47,6 +47,6 @@ export let PointLight: VoidComponent<PointLightProps> = props => {
     ([color, intensity, distance, decay, castShadow, shadow]) => setLight(light, { color, intensity, distance, decay, castShadow, shadow }),
   )
   untrack(() => props.ref)?.(light)
-  onCleanup(() => remove(light))
+  onCleanup(() => destroy(light))
   return null
 }

package/src/components/record-mesh.tsx

@@ -3,7 +3,7 @@ import type { VoidComponent } from "@solidrt/core"
 import { SceneContext } from "./context.tsx"
 import { syncMesh } from "./mesh.tsx"
 import type { PopulatedMeshProps } from "./mesh.tsx"
-import { add } from "../node.ts"
+import { add, destroy } from "../node.ts"
 import { createRecordMesh, disposeInstances, setCastShadow, setGeometry, setRecordCount, setRecords } from "../mesh.ts"
 import type { RecordMesh as RecordMeshNode } from "../mesh.ts"
 import type { Geometry } from "../geometry.ts"
@@ -11,12 +11,14 @@ import type { Material } from "../material.ts"
 
 export type RecordMeshProps = PopulatedMeshProps & {
   geometry: Geometry
-  /** Must declare instanceAttributes (shaderMaterialClass), slot 0 only. */
+  /** Must declare instanceBuffers (shaderMaterialClass); the first is
+   * the records' layout. */
   material: Material
-  /** Interleaved per-instance records (stride = the material's instance
-   * attributes summed). Reactive; a later array larger than the buffer
-   * grows it (capacity doubles into a replacement buffer). */
-  records: Float32Array
+  /** The records, laid out in the material's first instance layout (a
+   * Float32Array over an all-float layout, bytes otherwise; see
+   * setRecords). Reactive; a later value larger than the buffer grows it
+   * (capacity doubles into a replacement buffer). */
+  records: ArrayBufferView
   /** How many records draw; default all of the latest `records`. */
   count?: number
   /** LOCAL bounds covering every instance ([minX..maxZ]), fixed at
@@ -63,6 +65,9 @@ export let RecordMesh: VoidComponent<RecordMeshProps> = props => {
   )
   syncMesh(mesh, props)
   untrack(() => props.ref)?.(mesh)
-  onCleanup(() => disposeInstances(mesh))
+  onCleanup(() => {
+    destroy(mesh)
+    disposeInstances(mesh)
+  })
   return null
 }