@solidrt/3d 0.0.57 → 0.0.59

package/examples/wireframe.tsx

@@ -0,0 +1,129 @@
+// The rover drawn solid, as a wireframe or as its feature edges. Both line
+// forms are GEOMETRY: wireframeGeometry lists every edge of a triangle
+// geometry once, edgesGeometry only the edges where two faces meet at the
+// threshold angle or more (plus the open borders), each as a "lines"
+// geometry over the source's OWN vertex array. The topology rides on the
+// geometry, so the plain unlit material draws it as lines, and the vertex
+// upload is shared, so a mode costs an index buffer, not a second model.
+// The swap is setGeometry + setMaterial on the live mesh: the node, its
+// transform and its pointer handlers are untouched. Space, a tap on the
+// rover or the `wire` debug command ({ mode }) cycles the modes.
+//
+// Under the rover, the debug helpers: gridHelper on its floor and
+// axesHelper at the origin (world space, so they stand still while the
+// rover turns) and box3Helper around its bounds, turning with it. Lines
+// geometry too; the two colored ones draw through one
+// unlit({ vertexColors: true }) material.
+
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { createTexture } from "@solidrt/core/gpu"
+import type { TextureId } from "@solidrt/core/gpu"
+import { registerDebug } from "srt:dev"
+import { add, axesHelper, box3Helper, createModel, DirectionalLight, edgesGeometry, equirectToCube, gridHelper, Group, Mesh, parseGltf, PerspectiveCamera, Scene, setGeometry, setMaterial, unlit, wireframeGeometry } from "@solidrt/3d"
+import type { SceneNode } from "@solidrt/3d"
+import modelBytes from "./model.glb" with { type: "binary" }
+
+const MODES = ["solid", "wireframe", "edges"] as const
+type Mode = (typeof MODES)[number]
+// Feature-edge threshold in degrees: above the facet angle of the rover's
+// rounded parts, so their seams stay hidden and only rims and creases draw.
+const EDGE_ANGLE = 20
+const LINE_COLOR: [number, number, number] = [0.85, 0.95, 1]
+// The grid's subdivision lines and its two center lines, and the bounds
+// box (Three's Box3Helper yellow), against the dark clear color.
+const GRID_COLOR: [number, number, number] = [0.3, 0.33, 0.4]
+const GRID_CENTER_COLOR: [number, number, number] = [0.6, 0.66, 0.8]
+const BOUNDS_COLOR: [number, number, number] = [1, 1, 0]
+// Grid cells across the rover's floor.
+const GRID_DIVISIONS = 20
+// Face edge of the gradient environment cube: a gradient needs no detail.
+const ENV_FACE = 16
+// The gradient, zenith to nadir, sRGB bytes: sky, horizon, ground, below.
+const ENV_ROWS: [number, number, number][] = [
+  [96, 122, 168],
+  [176, 190, 210],
+  [120, 105, 90],
+  [60, 52, 45],
+]
+
+// A tiny equirectangular panorama turned into the cube the solid rover's
+// standard materials light by (see model.tsx).
+function gradientEnvironment(): TextureId {
+  let px = new Uint8Array(2 * ENV_ROWS.length * 4)
+  ENV_ROWS.forEach((c, y) => {
+    for (let x = 0; x < 2; x++) px.set([c[0], c[1], c[2], 255], (y * 2 + x) * 4)
+  })
+  let panorama = createTexture(px, 2, ENV_ROWS.length, { format: "rgba8-srgb", filter: "linear" })
+  return equirectToCube(panorama, ENV_FACE, { format: "rgba8-srgb", mipmap: true, label: "gradient-env" })
+}
+
+function App() {
+  let cube = gradientEnvironment()
+  let [t, setT] = createSignal(0)
+  onFrame(tick => setT(tick / 1000))
+
+  let model = createModel(parseGltf(modelBytes), { label: "rover" })
+  let b = model.bounds
+  let center: [number, number, number] = [(b[0]! + b[3]!) / 2, (b[1]! + b[4]!) / 2, (b[2]! + b[5]!) / 2]
+  let radius = Math.hypot(b[3]! - b[0]!, b[4]! - b[1]!, b[5]! - b[2]!) / 2
+
+  let helperLines = unlit({ vertexColors: true })
+  let grid = gridHelper({ size: radius * 4, divisions: GRID_DIVISIONS, color: GRID_COLOR, centerColor: GRID_CENTER_COLOR })
+  let axes = axesHelper({ size: radius })
+  let bounds = box3Helper(b)
+
+  // One line material for every part and both line modes. Per part, what
+  // each mode swaps in: the line geometries share the solid's vertices,
+  // so building both up front costs their index buffers only.
+  let lines = unlit({ color: LINE_COLOR })
+  let looks = model.parts.map(part => ({
+    mesh: part.mesh,
+    solid: { geometry: part.mesh.geometry, material: part.mesh.material },
+    wireframe: wireframeGeometry(part.mesh.geometry),
+    edges: edgesGeometry(part.mesh.geometry, EDGE_ANGLE),
+  }))
+  let mode: Mode = "solid"
+  let apply = (next: Mode): void => {
+    mode = next
+    for (let look of looks) {
+      // Each call rebuilds the draw entry, so the intermediate state is
+      // always the line material over the solid's triangles - a pipeline
+      // unlit has anyway - never the solid material over lines.
+      if (next === "solid") {
+        setGeometry(look.mesh, look.solid.geometry)
+        setMaterial(look.mesh, look.solid.material)
+      } else {
+        setMaterial(look.mesh, lines)
+        setGeometry(look.mesh, look[next])
+      }
+    }
+  }
+  let cycle = (): void => apply(MODES[(MODES.indexOf(mode) + 1) % MODES.length]!)
+  for (let part of model.parts) part.mesh.onTap = cycle
+  registerDebug("wire", (args?: Record<string, unknown>) => {
+    if (typeof args?.mode === "string" && (MODES as readonly string[]).includes(args.mode)) apply(args.mode as Mode)
+    else cycle()
+  })
+
+  return (
+    <window
+      onKeyDown={e => {
+        if (e.key === " ") cycle()
+      }}
+    >
+      <view width={pct(100)} height={pct(100)}>
+        <Scene clearColor={[0.1, 0.11, 0.14, 1]} environment={{ cube }} samples={4} label="wireframe">
+          <PerspectiveCamera fov={40} position={[center[0] + radius * 1.4, center[1] + radius * 1.1, center[2] + radius * 2.2]} lookAt={center} />
+          <DirectionalLight direction={[0.5, -0.8, 0.3]} color={[1, 0.95, 0.85]} intensity={0.9} />
+          <Mesh geometry={grid} material={helperLines} position={[0, b[1]!, 0]} />
+          <Mesh geometry={axes} material={helperLines} />
+          <Group rotation={[0, t() / 3, 0]} ref={(g: SceneNode) => add(g, model)}>
+            <Mesh geometry={bounds} material={unlit({ color: BOUNDS_COLOR })} />
+          </Group>
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.57",
+  "version": "0.0.59",
   "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.57"
+    "@solidjs/signals": "2.0.0-rc.8",
+    "@solidrt/core": "0.0.59"
   }
 }

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))
+  }
 }