@solidrt/3d 0.0.56 → 0.0.58

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

package/src/components/mesh.tsx

@@ -0,0 +1,92 @@
+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, PointerEventProps } from "./node-props.ts"
+import { add, remove } 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"
+import type { Geometry } from "../geometry.ts"
+import type { Material } from "../material.ts"
+
+export type MeshProps = TransformProps & PointerEventProps & {
+  geometry: Geometry
+  material: Material
+  /** Per-mesh uniforms for a custom material (setMeshParams as a prop).
+   * Keys merge - a key that disappears keeps its old value; there is no
+   * unset. Names must be declared by the material's shaders. For values
+   * changing every frame prefer `ref` + setMeshParams from onFrame, the
+   * same split as setTransform. */
+  params?: ShaderParams
+  /** Explicit draw-order key (setRenderOrder as a prop); default 0. */
+  renderOrder?: number
+  /** Draw into the scene's shadow map (setCastShadow as a prop); default
+   * false. Needs a `castShadow` light to show. */
+  castShadow?: boolean
+  /** Layer membership bitmask (setLayers as a prop; default 1): a target
+   * draws the mesh when its mask intersects this. Not inherited from
+   * ancestor Groups. */
+  layers?: number
+  /** Frustum culling switch (setCulling as a prop; default true). */
+  frustumCulled?: boolean
+  /** World units the culled box grows by (setCulling as a prop; default 0). */
+  cullMargin?: number
+  ref?: (mesh: MeshNode) => void
+}
+
+// The mesh-side props every mesh component shares (Sprite has no
+// geometry and casts no shadow, so those stay with the components that
+// 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 {
+  createEffect(
+    () => props.material,
+    m => setMaterial(mesh, m),
+    { defer: true },
+  )
+  createEffect(
+    () => props.params,
+    p => {
+      if (p !== undefined) setMeshParams(mesh, p)
+    },
+  )
+  createEffect(
+    () => props.renderOrder,
+    o => setRenderOrder(mesh, o ?? 0),
+  )
+  createEffect(
+    () => props.layers,
+    l => setLayers(mesh, l ?? 1),
+  )
+  createEffect(
+    () => [props.frustumCulled, props.cullMargin] as const,
+    ([culled, margin]) => setCulling(mesh, { frustumCulled: culled !== false, cullMargin: margin ?? 0 }),
+  )
+  syncNode(mesh, props)
+}
+
+/** One draw entry: geometry drawn with a material at a transform. */
+export let Mesh: VoidComponent<MeshProps> = props => {
+  let ctx = useContext(SceneContext)
+  let mesh = untrack(() => createMesh(props.geometry, props.material))
+  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(() => remove(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">

package/src/components/node-props.ts

@@ -0,0 +1,90 @@
+import { createEffect } from "@solidrt/core"
+import { setTransform, setTransition, setVisible } from "../node.ts"
+import type { NodePointerEvent, NodeTapEvent, NodeWheelEvent, SceneNode, TransitionEndEvent } from "../node.ts"
+import type { NodeTransition } from "flux:spatial"
+import type { Quat, Vec3 } from "../math.ts"
+
+export type TransformProps = {
+  position?: Vec3
+  /** Euler radians in XYZ order (x first), Three's `Euler` default. */
+  rotation?: Vec3
+  /** The rotation as a quaternion - what the node stores. Pass this or
+   * `rotation`, not both. */
+  quaternion?: Quat
+  scale?: Vec3 | number
+  visible?: boolean
+  /** How transform-prop changes animate (see setTransition); the mount
+   * transform always snaps. */
+  transition?: NodeTransition | string | null
+  /** A declared transition settled on one component. */
+  onTransitionEnd?: (event: TransitionEndEvent) => void
+}
+
+/**
+ * Node pointer events, the element vocabulary one tree deeper: the nearest
+ * hit (the struck instance, else the mesh) receives the event,
+ * down/move/up/wheel/tap bubble to ancestor Groups and end at the
+ * `<Scene>`'s own handlers (stopPropagation stops the walk; a stopped
+ * down claims the whole press, so a mesh that drags itself keeps an
+ * `<OrbitCamera>` still), enter/leave pair on the struck node alone.
+ * Events flow while the element showing the scene carries scene.handlers -
+ * the built-in <Scene> leaf does (opt out with events={false}); an `output`
+ * leaf spreads them itself.
+ */
+export type PointerEventProps = {
+  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
+   * press: DOM's click, with `tapCount` for repeats. */
+  onTap?: (event: NodeTapEvent) => void
+}
+
+export function syncNode(node: SceneNode, props: TransformProps & PointerEventProps): void {
+  // One effect for the transform and the handlers: re-assigning eight
+  // handler fields on a transform write is free, an effect of its own is
+  // not (a node component's mount cost is mostly its effects and its
+  // context provider, see probes/3d-instance-mount-bench.tsx).
+  createEffect(
+    () =>
+      [
+        props.position,
+        props.rotation,
+        props.quaternion,
+        props.scale,
+        props.visible,
+        props.onPointerDown,
+        props.onPointerMove,
+        props.onPointerUp,
+        props.onPointerEnter,
+        props.onPointerLeave,
+        props.onWheel,
+        props.onTap,
+        props.onTransitionEnd,
+      ] as const,
+    ([position, rotation, quaternion, scale, visible, down, move, up, enter, leave, wheel, tap, end]) => {
+      setTransform(node, { position, rotation, quaternion, scale })
+      setVisible(node, visible !== false)
+      node.onPointerDown = down
+      node.onPointerMove = move
+      node.onPointerUp = up
+      node.onPointerEnter = enter
+      node.onPointerLeave = leave
+      node.onWheel = wheel
+      node.onTap = tap
+      node.onTransitionEnd = end
+    },
+  )
+  // After the transform effect, so the mount transform snaps before writes
+  // animate. Its own effect: merged above, every transform write would
+  // re-send the config to the core.
+  createEffect(
+    () => props.transition,
+    transition => setTransition(node, transition ?? null),
+  )
+}

package/src/components/orbit-camera.tsx

@@ -0,0 +1,75 @@
+import { createEffect, merge, onFrame, untrack, useContext } from "@solidrt/core"
+import type { InputMap, VoidComponent } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import { createOrbitCamera } from "../orbit.ts"
+import type { OrbitAxes, OrbitCamera as OrbitCameraHandle, OrbitCameraOptions } from "../orbit.ts"
+
+// Cap on the frame loop's per-frame dt in seconds, so the first tick after
+// a suspended stretch (a resumed app, a reload) cannot leap the pose.
+const MAX_ORBIT_DT = 0.1
+
+export type OrbitCameraProps = OrbitCameraOptions & {
+  /** The input map driving the control (InputMap.drive): its `rotate`,
+   * `zoom` and `pan` 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 OrbitAxes, string | null>>
+  /** The control's handle (pose()/set()/eye()/orbiting()/active(), the
+   * verbs, `axes` - also the debug command shape). */
+  ref?: (orbit: OrbitCameraHandle) => void
+}
+
+/**
+ * createOrbitCamera 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: no device wiring in a component; the app binds a
+ * pointer feed, a pad or anything else to the map). The pose props
+ * (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
+ * by drags alone leaves the app demand-driven idle.
+ */
+export let OrbitCamera: VoidComponent<OrbitCameraProps> = props => {
+  let ctx = useContext(SceneContext)
+  // The control keeps this object and reads each option where it applies,
+  // so the props go through as getters (merge), never a spread: a spread
+  // would snapshot every prop once and a change could only remount.
+  let options: OrbitCameraOptions = merge(props, {})
+  let orbit = untrack(() => createOrbitCamera(ctx.viewport, options))
+  createEffect(
+    () => props.input,
+    input => (input ? input.drive(orbit.axes, untrack(() => props.actions)) : undefined),
+  )
+  createEffect(
+    () => orbit.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_ORBIT_DT)
+        last = now
+        orbit.update(dt)
+      })
+    },
+  )
+  // 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).
+  createEffect(
+    () => [options.minDistance, options.maxDistance, options.minElevation, options.maxElevation],
+    () => untrack(() => orbit.set({})),
+    { defer: true },
+  )
+  untrack(() => props.ref)?.(orbit)
+  return null
+}

package/src/components/perspective-camera.tsx

@@ -0,0 +1,32 @@
+import { createEffect, useContext } from "@solidrt/core"
+import type { VoidComponent } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import type { Vec3 } from "../math.ts"
+
+export type PerspectiveCameraProps = {
+  /** Vertical field of view in DEGREES (default 60). */
+  fov?: number
+  near?: number
+  far?: number
+  position?: Vec3
+  lookAt?: Vec3
+  up?: Vec3
+}
+
+/**
+ * Drives the enclosing camera from props - the scene's, or inside a
+ * `<View3d>` that view's (both have a default camera, so this component is
+ * optional). The camera is target state, not a tree node: to orbit it,
+ * update `position`/`lookAt`. The Scene and View3d `camera` props drive the
+ * same state (a partial CameraUpdate, ortho included) - use one form, not
+ * both.
+ */
+export let PerspectiveCamera: VoidComponent<PerspectiveCameraProps> = props => {
+  let ctx = useContext(SceneContext)
+  createEffect(
+    () => [props.fov, props.near, props.far, props.position, props.lookAt, props.up] as const,
+    ([fov, near, far, position, lookAt, up]) =>
+      ctx.viewport.setCamera({ fov, near, far, position, target: lookAt, up }),
+  )
+  return null
+}

package/src/components/point-light.tsx

@@ -0,0 +1,52 @@
+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 { createPointLight, setLight } from "../light.ts"
+import type { PointLight as PointLightNode, SpotShadowOptions } from "../light.ts"
+import type { Vec3 } from "../math.ts"
+
+export type PointLightProps = TransformProps & {
+  color?: Vec3
+  intensity?: number
+  /** Falloff cutoff in world units (0 = no cutoff). */
+  distance?: number
+  /** Falloff exponent; default 2 (inverse square). */
+  decay?: number
+  /** Render shadow maps from this light (six 90-degree face maps, one
+   * per cube face; six shadow slots). Far = `distance`, so give a
+   * casting bulb one. */
+  castShadow?: boolean
+  /** Shadow-map options (mapSize, bias, normalBias, near), merged key
+   * by key. */
+  shadow?: SpotShadowOptions
+  ref?: (light: PointLightNode) => void
+}
+
+/** A point light node (createPointLight): light in every direction from
+ * the node's world position - give it a `position`; rotation does not
+ * matter. Counts against MAX_LIGHTS with the other non-ambient lights. */
+export let PointLight: VoidComponent<PointLightProps> = props => {
+  let ctx = useContext(SceneContext)
+  let light = untrack(() =>
+    createPointLight({
+      color: props.color,
+      intensity: props.intensity,
+      distance: props.distance,
+      decay: props.decay,
+      castShadow: props.castShadow,
+      shadow: props.shadow,
+    }),
+  )
+  add(ctx.parent, light)
+  syncNode(light, props)
+  createEffect(
+    () => [props.color, props.intensity, props.distance, props.decay, props.castShadow, props.shadow] as const,
+    ([color, intensity, distance, decay, castShadow, shadow]) => setLight(light, { color, intensity, distance, decay, castShadow, shadow }),
+  )
+  untrack(() => props.ref)?.(light)
+  onCleanup(() => remove(light))
+  return null
+}