@solidrt/3d 0.0.55 → 0.0.57

package/src/camera.ts

@@ -0,0 +1,148 @@
+// The camera record: one per scene target and one per view (the shadow
+// views included), the same state and the same one-shared-write contract
+// everywhere. Split out of scene.ts so the shadow system can place its
+// map cameras through the exact code the scene uses for its own.
+
+import { invert, lookAt as lookAtMatrix, mat4, multiply, orthographic, perspective } from "./math.ts"
+import type { Mat4, Vec3 } from "./math.ts"
+import type { ShaderParams } from "@solidrt/core/gpu"
+
+/** An orthographic projection's view-space extents, in world units (the
+ * same box at every depth). */
+export type OrthoExtent = { left: number; right: number; top: number; bottom: number }
+
+/** A camera snapshot (Scene/View `camera()`): CameraUpdate's fields, all
+ * present. Arrays are copies of the internal state. */
+export type CameraState = {
+  fov: number
+  near: number
+  far: number
+  position: Vec3
+  target: Vec3
+  up: Vec3
+  ortho: OrthoExtent | null
+}
+
+export type CameraUpdate = {
+  /** Vertical field of view in DEGREES (default 60). */
+  fov?: number
+  near?: number
+  far?: number
+  position?: Vec3
+  target?: Vec3
+  up?: Vec3
+  /** An orthographic projection with these extents (`fov` is then
+   * ignored); null returns to perspective. Three's OrthographicCamera as
+   * a camera option: a top-down map, an isometric view, a shadow-map
+   * light. */
+  ortho?: OrthoExtent | null
+}
+
+// `dirty` = the matrices need recomputing (a setCamera or a resize),
+// `pending` = the GPU write is owed to the next sync. The recompute is
+// split from the sync so project()/viewProj() see a fresh matrix right
+// after setCamera, before the microtask runs.
+export type Camera = {
+  fov: number
+  near: number
+  far: number
+  eye: Vec3
+  target: Vec3
+  up: Vec3
+  ortho: OrthoExtent | null
+  /** Mirror the projection's x: the image comes out flipped left to
+   * right. A reflection probe's face cameras set it - a GL cube face is
+   * seen from outside, the x mirror of what a camera sees - and the cube
+   * draw target's pass inverts the winding to match. */
+  mirror: boolean
+  dirty: boolean
+  pending: boolean
+  proj: Mat4
+  view: Mat4
+  viewProj: Mat4
+  invViewProj: Mat4
+}
+
+export function makeCamera(): Camera {
+  return {
+    fov: 60,
+    near: 0.1,
+    far: 100,
+    eye: [0, 0, 3],
+    target: [0, 0, 0],
+    up: [0, 1, 0],
+    ortho: null,
+    mirror: false,
+    dirty: true,
+    pending: false,
+    proj: mat4(),
+    view: mat4(),
+    viewProj: mat4(),
+    invViewProj: mat4(),
+  }
+}
+
+export function cameraState(cam: Camera): CameraState {
+  return {
+    fov: cam.fov,
+    near: cam.near,
+    far: cam.far,
+    position: [cam.eye[0], cam.eye[1], cam.eye[2]],
+    target: [cam.target[0], cam.target[1], cam.target[2]],
+    up: [cam.up[0], cam.up[1], cam.up[2]],
+    ortho: cam.ortho === null ? null : { left: cam.ortho.left, right: cam.ortho.right, top: cam.ortho.top, bottom: cam.ortho.bottom },
+  }
+}
+
+export function updateCamera(cam: Camera, update: CameraUpdate): void {
+  if (update.fov !== undefined) cam.fov = update.fov
+  if (update.near !== undefined) cam.near = update.near
+  if (update.far !== undefined) cam.far = update.far
+  if (update.position) cam.eye = [update.position[0], update.position[1], update.position[2]]
+  if (update.target) cam.target = [update.target[0], update.target[1], update.target[2]]
+  if (update.up) cam.up = [update.up[0], update.up[1], update.up[2]]
+  if (update.ortho !== undefined) {
+    let o = update.ortho
+    cam.ortho = o === null ? null : { left: o.left, right: o.right, top: o.top, bottom: o.bottom }
+  }
+  cam.dirty = true
+}
+
+export function ensureCamera(cam: Camera, width: number, height: number): void {
+  if (!cam.dirty) return
+  cam.dirty = false
+  cam.pending = true
+  let o = cam.ortho
+  if (o === null) perspective(cam.proj, (cam.fov * Math.PI) / 180, width / height, cam.near, cam.far)
+  else orthographic(cam.proj, o.left, o.right, o.top, o.bottom, cam.near, cam.far)
+  if (cam.mirror) {
+    // Negate the clip x row (column-major: elements 0, 4, 8, 12).
+    cam.proj[0] = -cam.proj[0]!
+    cam.proj[4] = -cam.proj[4]!
+    cam.proj[8] = -cam.proj[8]!
+    cam.proj[12] = -cam.proj[12]!
+  }
+  lookAtMatrix(cam.view, cam.eye, cam.target, cam.up)
+  multiply(cam.viewProj, cam.proj, cam.view)
+  invert(cam.invViewProj, cam.viewProj)
+}
+
+// The camera is target state: one shared write, whatever the target holds.
+// Entries are untouched - uModel is camera-independent, and uCamPos is
+// stored even when no current material declares it. The camera basis rides
+// along: the view matrix's first two rows are the camera's world-space
+// right and up (no clip flip - that lives in the projection), so a
+// billboard needs no reconstruction from uViewProj. The inverse rides too:
+// uInvViewProj carries a clip position back to world, which is how the
+// background slot (and any shader declaring it) gets a world-space ray
+// per pixel without knowing the projection.
+export function cameraParams(cam: Camera): ShaderParams {
+  let v = cam.view
+  return {
+    uViewProj: cam.viewProj,
+    uInvViewProj: cam.invViewProj,
+    uCamPos: cam.eye,
+    uCamRight: [v[0], v[4], v[8]],
+    uCamUp: [v[1], v[5], v[9]],
+  }
+}

package/src/clip.ts

@@ -0,0 +1,96 @@
+// Pure clip sampling - the mixer's core, split out so it runs with no
+// scene or engine (checks under flux, custom drivers, a future bake-side
+// resample). Everything here is plain array math over ModelChannel data.
+
+import { quatNormalize, quatSlerp } from "./math.ts"
+import type { Quat } from "./math.ts"
+import type { ModelChannel } from "./gltf.ts"
+
+/**
+ * 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).
+ */
+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 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
+  if (keys === 0) return
+  if (time <= times[0]! || keys === 1) {
+    for (let e = 0; e < elements; e++) out[e] = values[mid + e]!
+    return
+  }
+  if (time >= times[keys - 1]!) {
+    let at = (keys - 1) * stride + mid
+    for (let e = 0; e < elements; e++) out[e] = values[at + e]!
+    return
+  }
+  // The key pair around `time`: binary search for the last key at or
+  // before it.
+  let lo = 0
+  let hi = keys - 1
+  while (hi - lo > 1) {
+    let m = (lo + hi) >> 1
+    if (times[m]! <= time) lo = m
+    else hi = m
+  }
+  let t0 = times[lo]!
+  let t1 = times[hi]!
+  let span = t1 - t0
+  let s = span > 0 ? (time - t0) / span : 0
+  let a = lo * stride + mid
+  let b = hi * stride + mid
+  switch (channel.interpolation) {
+    case "step":
+      for (let e = 0; e < elements; e++) out[e] = values[a + e]!
+      return
+    case "linear":
+      if (channel.path === "rotation") {
+        readQuat(SAMPLE_A, values, a)
+        readQuat(SAMPLE_B, values, b)
+        quatSlerp(SAMPLE_A, SAMPLE_A, SAMPLE_B, s)
+        for (let e = 0; e < 4; e++) out[e] = SAMPLE_A[e]!
+      } else {
+        for (let e = 0; e < elements; e++) out[e] = values[a + e]! + (values[b + e]! - values[a + e]!) * s
+      }
+      return
+    case "cubic": {
+      // glTF's Hermite: p(s) = h00 v0 + h10 d b0 + h01 v1 + h11 d a1,
+      // where b0 is key lo's OUT-tangent and a1 key hi's IN-tangent
+      // (per-second, so they scale by the span d).
+      let s2 = s * s
+      let s3 = s2 * s
+      let h00 = 2 * s3 - 3 * s2 + 1
+      let h10 = s3 - 2 * s2 + s
+      let h01 = -2 * s3 + 3 * s2
+      let h11 = s3 - s2
+      let outTan = lo * stride + elements * 2
+      let inTan = hi * stride
+      for (let e = 0; e < elements; e++) {
+        out[e] = h00 * values[a + e]! + h10 * span * values[outTan + e]! + h01 * values[b + e]! + h11 * span * values[inTan + e]!
+      }
+      if (channel.path === "rotation") {
+        readQuat(SAMPLE_A, out, 0)
+        quatNormalize(SAMPLE_A, SAMPLE_A)
+        for (let e = 0; e < 4; e++) out[e] = SAMPLE_A[e]!
+      }
+      return
+    }
+  }
+}
+
+const SAMPLE_A: Quat = [0, 0, 0, 1]
+const SAMPLE_B: Quat = [0, 0, 0, 1]
+
+function readQuat(out: Quat, values: ArrayLike<number>, at: number): void {
+  out[0] = values[at]!
+  out[1] = values[at + 1]!
+  out[2] = values[at + 2]!
+  out[3] = values[at + 3]!
+}

package/src/collision.ts

@@ -0,0 +1,20 @@
+// The kinematic character move, Godot's CharacterBody3D.move_and_slide
+// and Unity's CharacterController.Move as one pure function: no node, no
+// velocity state. It takes a volume where the body IS and the motion it
+// WANTS, and returns the motion it gets plus what it touched - the
+// first-person camera (which has no node) composes it in clampPosition,
+// a node-driven body applies the result with setTransform. The loop
+// itself (depenetration, sweep, slide, floor snap) runs in the spatial
+// core as scene.moveAndSlide; this is its free-function spelling.
+
+import type { MoveOptions, MoveResult, Scene, Volume } from "./scene.ts"
+import type { Vec3 } from "./math.ts"
+
+/** What moveAndSlide needs of a scene. */
+export type MoveScene = Pick<Scene, "moveAndSlide">
+
+/** Move a body `motion` through the scene's colliders, sliding along what
+ * it hits: scene.moveAndSlide as a function (see it for the contract). */
+export function moveAndSlide(scene: MoveScene, volume: Volume, motion: Vec3, opts: MoveOptions = {}): MoveResult {
+  return scene.moveAndSlide(volume, motion, opts)
+}

package/src/color.ts

@@ -0,0 +1,32 @@
+// The sRGB transfer functions (IEC 61966-2-1) in JS, the JS half of the
+// package's color contract: every [r, g, b] color option - material
+// color and emissive, light color, hemisphere sky and ground, fog color -
+// 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
+// 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.
+
+/** Decode one sRGB-encoded component (0..1) to linear light. Above 1 the
+ * curve continues, so an intensity folded into a color survives. */
+export function srgbToLinear(c: number): number {
+  if (c <= 0.04045) return c / 12.92
+  return Math.pow((c + 0.055) / 1.055, 2.4)
+}
+
+/** Encode one linear-light component to sRGB: the inverse of srgbToLinear. */
+export function linearToSrgb(c: number): number {
+  if (c <= 0.0031308) return c * 12.92
+  return 1.055 * Math.pow(c, 1 / 2.4) - 0.055
+}
+
+/** A copy of an [r, g, b] or [r, g, b, a] color with its rgb decoded to
+ * linear light; alpha is coverage, never encoded, and passes through. */
+export function linearColor(color: readonly number[]): number[] {
+  let out = color.slice()
+  for (let i = 0; i < 3 && i < out.length; i++) out[i] = srgbToLinear(out[i]!)
+  return out
+}

package/src/components/context.tsx

@@ -0,0 +1,35 @@
+import { createContext, useContext } from "@solidrt/core"
+import type { Element, PointerFeed } from "@solidrt/core"
+import type { SceneNode } from "../node.ts"
+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 }
+
+export type SceneCtx = { scene: SceneHandle; parent: SceneNode; viewport: CameraTarget; pointer: PointerFeed | null }
+export let SceneContext = createContext<SceneCtx>()
+
+/**
+ * The enclosing scene, parent node, viewport and pointer feed - the
+ * imperative escape hatch inside a component subtree (throws outside a
+ * `<Scene>`). `viewport` and `pointer` are the nearest OWNER's: the
+ * scene, or inside a `<View3d>` that view - what the camera-control
+ * components drive, and the feed the owner's `pointer` prop handed in
+ * (null when none was: the owner's leaf then feeds no gestures). The
+ * same shape as @solidrt/2d's useSpriteLayer.
+ */
+export function useScene(): SceneCtx {
+  return useContext(SceneContext)
+}
+
+// The scene context for a node component's children. Solid's provider is
+// a root and two memos over the children, paid even when there are none,
+// so it is built only when the JSX has children: the compiler emits the
+// `children` getter only then, so the test is structural, not a read
+// (probes/3d-instance-mount-bench.tsx has the per-row cost).
+export function provide(ctx: SceneCtx, parent: SceneNode, props: { children?: Element }): Element | undefined {
+  if (!("children" in props)) return undefined
+  return <SceneContext value={{ scene: ctx.scene, parent, viewport: ctx.viewport, pointer: ctx.pointer }}>{props.children}</SceneContext>
+}

package/src/components/directional-light.tsx

@@ -0,0 +1,48 @@
+import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+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 { createDirectionalLight, setLight } from "../light.ts"
+import type { DirectionalLight as DirectionalLightNode, ShadowOptions } from "../light.ts"
+import type { Vec3 } from "../math.ts"
+
+export type DirectionalLightProps = TransformProps & {
+  /** Travel direction in the node's local space; default [0, -1, 0]. */
+  direction?: Vec3
+  color?: Vec3
+  intensity?: number
+  /** Render a shadow map from this light (any directional light may;
+   * each is a pass). Its shadow camera sits at the light's WORLD
+   * position, so give a casting light a `position` above the scene. */
+  castShadow?: boolean
+  /** Shadow-map options (mapSize, bias, normalBias, camera frustum,
+   * cascades, distance), merged key by key. */
+  shadow?: ShadowOptions
+  ref?: (light: DirectionalLightNode) => void
+}
+
+/** A directional light node (createDirectionalLight): a parent Group's
+ * rotation turns it; up to MAX_LIGHTS per scene, in mount order. */
+export let DirectionalLight: VoidComponent<DirectionalLightProps> = props => {
+  let ctx = useContext(SceneContext)
+  let light = untrack(() =>
+    createDirectionalLight({
+      direction: props.direction,
+      color: props.color,
+      intensity: props.intensity,
+      castShadow: props.castShadow,
+      shadow: props.shadow,
+    }),
+  )
+  add(ctx.parent, light)
+  syncNode(light, props)
+  createEffect(
+    () => [props.direction, props.color, props.intensity, props.castShadow, props.shadow] as const,
+    ([direction, color, intensity, castShadow, shadow]) => setLight(light, { direction, color, intensity, castShadow, shadow }),
+  )
+  untrack(() => props.ref)?.(light)
+  onCleanup(() => remove(light))
+  return null
+}

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

@@ -0,0 +1,72 @@
+import { createEffect, merge, onFrame, untrack, useContext } from "@solidrt/core"
+import type { InputMap, VoidComponent } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import { createFirstPersonCamera } from "../first-person.ts"
+import type { FirstPersonAxes, FirstPersonCamera as FirstPersonCameraHandle, FirstPersonCameraOptions } from "../first-person.ts"
+
+// Cap on the frame loop's per-frame dt in seconds, the same guard as the
+// orbit's: a resumed app must not teleport the walker.
+const MAX_WALK_DT = 0.1
+
+export type FirstPersonCameraProps = FirstPersonCameraOptions & {
+  /** The input map driving the control (InputMap.drive): its `look`,
+   * `move` and `rise` actions, or the ones `actions` names. Live: a new
+   * map reconnects. Without one the control moves only through `ref`. */
+  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). */
+  ref?: (camera: FirstPersonCameraHandle) => void
+}
+
+/**
+ * createFirstPersonCamera as a Scene (or View3d) child: drives the
+ * enclosing camera - the scene's, or inside a `<View3d>` that view's -
+ * through context, and takes its input from the map in `input`, nothing
+ * else (ARCHITECTURE.md: the app binds keys, a pointer feed, a pad or
+ * anything else to the map, and spreads the map's key handlers where the
+ * keys should be caught). Pointer lock stays the app's: call
+ * `lockPointer(true)` from a click and `lockPointer(false)` from Escape;
+ * the pointer feed's `mouseDelta` source looks around while locked. The
+ * pose props (position, yaw, pitch) 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:
+ * `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.
+ */
+export let FirstPersonCamera: VoidComponent<FirstPersonCameraProps> = props => {
+  let ctx = useContext(SceneContext)
+  // Getters, not a spread: see OrbitCamera.
+  let options: FirstPersonCameraOptions = merge(props, {})
+  let camera = untrack(() => createFirstPersonCamera(ctx.viewport, options))
+  createEffect(
+    () => props.input,
+    input => (input ? input.drive(camera.axes, untrack(() => props.actions)) : undefined),
+  )
+  createEffect(
+    () => camera.active(),
+    on => {
+      if (!on) return
+      let last: number | null = null
+      return onFrame(tick => {
+        let now = tick / 1000
+        let dt = last === null ? 0 : Math.min(now - last, MAX_WALK_DT)
+        last = now
+        camera.update(dt)
+      })
+    },
+  )
+  // A pitch clamp change re-clamps the pose at once; deferred and
+  // untracked as OrbitCamera's.
+  createEffect(
+    () => [options.minPitch, options.maxPitch],
+    () => untrack(() => camera.set({})),
+    { defer: true },
+  )
+  untrack(() => props.ref)?.(camera)
+  return null
+}

package/src/components/group.tsx

@@ -0,0 +1,18 @@
+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 { SceneNode } from "../node.ts"
+
+/** A transform node: children inherit its position/rotation/scale. */
+export let Group: ParentComponent<TransformProps & PointerEventProps & { ref?: (node: SceneNode) => void }> = props => {
+  let ctx = useContext(SceneContext)
+  let node = createGroup()
+  add(ctx.parent, node)
+  syncNode(node, props)
+  untrack(() => props.ref)?.(node)
+  onCleanup(() => remove(node))
+  return provide(ctx, node, props)
+}

package/src/components/hemisphere-light.tsx

@@ -0,0 +1,24 @@
+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 { createHemisphereLight, setLight } from "../light.ts"
+import type { HemisphereLight as HemisphereLightNode } from "../light.ts"
+import type { Vec3 } from "../math.ts"
+
+export type HemisphereLightProps = { sky?: Vec3; ground?: Vec3; intensity?: number; ref?: (light: HemisphereLightNode) => void }
+
+/** The scene's ambient term as a node (createHemisphereLight); one per
+ * scene, the last mounted wins. */
+export let HemisphereLight: VoidComponent<HemisphereLightProps> = props => {
+  let ctx = useContext(SceneContext)
+  let light = untrack(() => createHemisphereLight({ sky: props.sky, ground: props.ground, intensity: props.intensity }))
+  add(ctx.parent, light)
+  createEffect(
+    () => [props.sky, props.ground, props.intensity] as const,
+    ([sky, ground, intensity]) => setLight(light, { sky, ground, intensity }),
+  )
+  untrack(() => props.ref)?.(light)
+  onCleanup(() => remove(light))
+  return null
+}

package/src/components/index.ts

@@ -0,0 +1,46 @@
+// The Solid face: PascalCase components over context, syncing the retained
+// scene (node/mesh/light/scene.ts) - no new intrinsic elements, no
+// renderer changes. Props
+// follow the Solid 2.0 model (reactive values, no destructuring); effects
+// write into the retained nodes and the runtime's dirty flush renders.
+// Anything moving at frame rate can bypass the declarative layer: grab the
+// node with `ref` and call setTransform from onFrame - signals carry
+// structure and slow state, per-frame motion goes straight to the scene.
+//
+// One file per component (the lights, cameras and meshes each their own),
+// with the shared pieces beside them: context.tsx (the scene context and
+// useScene), node-props.ts (the transform and pointer
+// props every node component syncs) and mesh.tsx (the mesh-side props the
+// populated meshes share). This index is the package's face: index.ts at
+// the root re-exports it, nothing outside imports the files directly.
+
+export { useScene } from "./context.tsx"
+export type { CameraTarget } from "./context.tsx"
+export type { 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 { 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 { RecordMesh } from "./record-mesh.tsx"
+export type { RecordMeshProps } from "./record-mesh.tsx"
+export { PerspectiveCamera } from "./perspective-camera.tsx"
+export type { PerspectiveCameraProps } from "./perspective-camera.tsx"
+export { OrbitCamera } from "./orbit-camera.tsx"
+export type { OrbitCameraProps } from "./orbit-camera.tsx"
+export { FirstPersonCamera } from "./first-person-camera.tsx"
+export type { FirstPersonCameraProps } from "./first-person-camera.tsx"
+export { HemisphereLight } from "./hemisphere-light.tsx"
+export type { HemisphereLightProps } from "./hemisphere-light.tsx"
+export { DirectionalLight } from "./directional-light.tsx"
+export type { DirectionalLightProps } from "./directional-light.tsx"
+export { SpotLight } from "./spot-light.tsx"
+export type { SpotLightProps } from "./spot-light.tsx"
+export { PointLight } from "./point-light.tsx"
+export type { PointLightProps } from "./point-light.tsx"

package/src/components/instanced-mesh.tsx

@@ -0,0 +1,105 @@
+import { createContext, createEffect, 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 { 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 type { InstancedMesh as InstancedMeshNode, InstanceNode } from "../mesh.ts"
+import type { Geometry } from "../geometry.ts"
+import type { Material } from "../material.ts"
+
+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. */
+  material: Material
+  /** Instance slots reserved up front (default 64; fixed at creation).
+   * Past it the buffers double into replacements - amortized, but size it
+   * realistically to skip the copies. */
+  capacity?: number
+  /** LOCAL bounds covering the population ([minX..maxZ]), fixed at
+   * creation: the mesh node's own box for the frustum test and the
+   * transparent sort. Optional here - instances pick by themselves, and
+   * without it the mesh culls by the union of their boxes. */
+  bounds?: ArrayLike<number>
+  /** Debug label for the record buffers. */
+  label?: string
+  /** Draw into the scene's shadow map (setCastShadow as a prop); default
+   * false. The stock instanced materials cast; a custom class needs a
+   * `shadowVertex`. */
+  castShadow?: boolean
+  ref?: (mesh: InstancedMeshNode) => void
+}
+
+let InstancedMeshContext = createContext<InstancedMeshNode | null>(null)
+
+/**
+ * One draw entry covering N instance NODES (createInstancedMesh as a
+ * component): `<Instance>` children populate it - each a scene node the
+ * core places, so their `transition` props spring with zero per-frame
+ * JS, and picking, pointer events, overlap and sweep name the instance
+ * struck. `<Group>` children between the mesh and its instances are
+ * squads (the records stay mesh-relative through them). The record
+ * buffers are component-owned and freed on unmount.
+ */
+export let InstancedMesh: ParentComponent<InstancedMeshProps> = props => {
+  let ctx = useContext(SceneContext)
+  let mesh = untrack(() =>
+    createInstancedMesh(props.geometry, props.material, { capacity: props.capacity, bounds: props.bounds, label: props.label }),
+  )
+  add(ctx.parent, mesh)
+  createEffect(
+    () => props.geometry,
+    g => setGeometry(mesh, g),
+    { defer: true },
+  )
+  createEffect(
+    () => props.castShadow,
+    c => setCastShadow(mesh, c === true),
+  )
+  syncMesh(mesh, props)
+  untrack(() => props.ref)?.(mesh)
+  onCleanup(() => disposeInstances(mesh))
+  return (
+    <SceneContext value={{ scene: ctx.scene, parent: mesh, viewport: ctx.viewport, pointer: ctx.pointer }}>
+      <InstancedMeshContext value={mesh}>{props.children}</InstancedMeshContext>
+    </SceneContext>
+  )
+}
+
+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). */
+  style?: ArrayLike<number>
+  ref?: (instance: InstanceNode) => void
+}
+
+/**
+ * One instance of the enclosing `<InstancedMesh>` (addInstance as a
+ * component): a node placed under the nearest `<Group>` or `<Instance>`
+ * inside the mesh, with the transform, transition and pointer props of
+ * a `<Group>` plus `style`. Children (a `<Mesh>` headlight under a car
+ * instance) mount under it. Throws outside an `<InstancedMesh>`.
+ */
+export let Instance: ParentComponent<InstanceProps> = props => {
+  let ctx = useContext(SceneContext)
+  let mesh = useContext(InstancedMeshContext)
+  if (mesh === null) throw new Error("<Instance> must be inside an <InstancedMesh>")
+  let instance = addInstance(mesh, undefined, ctx.parent)
+  syncNode(instance, props)
+  createEffect(
+    () => props.style,
+    s => {
+      if (s !== undefined) setInstanceStyle(instance, s)
+    },
+  )
+  untrack(() => props.ref)?.(instance)
+  onCleanup(() => removeInstance(instance))
+  return provide(ctx, instance, props)
+}