@solidrt/3d 0.0.56 → 0.0.57

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

package/src/components/record-mesh.tsx

@@ -0,0 +1,68 @@
+import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+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 { createRecordMesh, disposeInstances, setCastShadow, setGeometry, setRecordCount, setRecords } from "../mesh.ts"
+import type { RecordMesh as RecordMeshNode } from "../mesh.ts"
+import type { Geometry } from "../geometry.ts"
+import type { Material } from "../material.ts"
+
+export type RecordMeshProps = PopulatedMeshProps & {
+  geometry: Geometry
+  /** Must declare instanceAttributes (shaderMaterialClass), slot 0 only. */
+  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
+  /** How many records draw; default all of the latest `records`. */
+  count?: number
+  /** LOCAL bounds covering every instance ([minX..maxZ]), fixed at
+   * creation. Without them the mesh has no picking leaf, so pointer events
+   * never target it. */
+  bounds?: ArrayLike<number>
+  /** Draw into the scene's shadow map (setCastShadow as a prop); default
+   * false. Needs a `castShadow` light AND a material class declaring
+   * `shadowVertex` (the depth pass with the instance placement) - the
+   * shadow views skip a populated mesh without one. */
+  castShadow?: boolean
+  ref?: (mesh: RecordMeshNode) => void
+}
+
+/** One draw entry covering N records: geometry repeated per record of
+ * `records` (createRecordMesh as a component, the JS-written population).
+ * The record buffer is component-owned and freed on unmount. */
+export let RecordMesh: VoidComponent<RecordMeshProps> = props => {
+  let ctx = useContext(SceneContext)
+  let mesh = untrack(() =>
+    createRecordMesh(props.geometry, props.material, props.records, props.count, { bounds: props.bounds }),
+  )
+  add(ctx.parent, mesh)
+  createEffect(
+    () => props.records,
+    r => setRecords(mesh, r, untrack(() => props.count)),
+    { defer: true },
+  )
+  createEffect(
+    () => props.count,
+    c => {
+      if (c !== undefined) setRecordCount(mesh, c)
+    },
+    { defer: true },
+  )
+  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 null
+}

package/src/components/scene.tsx

@@ -0,0 +1,281 @@
+import { createEffect, displayScale, getBoundingBoxViewport, getLayoutBox, onCleanup, onLayout, untrack } from "@solidrt/core"
+import type { Element, ParentComponent, PointerFeed, TextureId } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import { createScene } from "../scene.ts"
+import { feedPointer } from "../scene-pointer.ts"
+import type { EnvironmentOptions, FogOptions, Scene as SceneHandle, SkyboxOptions, ToneMapping } from "../scene.ts"
+import type { ScenePointerEvent, SceneTapEvent, SceneWheelEvent } from "../node.ts"
+import type { CameraUpdate } from "../camera.ts"
+
+/**
+ * The scene's own pointer events, the root of the walk: every event the
+ * nodes let through arrives here last - `event.mesh` is the hit it
+ * bubbled from, or null over empty space (a tap there with `mesh` null is
+ * "deselect"), `x`/`y` scene pixels. scene.listen as props; an
+ * `<OrbitCamera>` child's feed listens at the same root.
+ */
+export type ScenePointerProps = {
+  onPointerDown?: (event: ScenePointerEvent) => void
+  onPointerMove?: (event: ScenePointerEvent) => void
+  onPointerUp?: (event: ScenePointerEvent) => void
+  onWheel?: (event: SceneWheelEvent) => void
+  onTap?: (event: SceneTapEvent) => void
+}
+
+export type SceneProps = ScenePointerProps & {
+  /**
+   * Target pixels - give both, or neither. Omitted, the scene FILLS: the
+   * built-in leaf is laid out at 100% of its parent's box (give it a sized
+   * parent, as on the web) and the target tracks the leaf's on-screen size
+   * in device pixels - display scale, designSize fits and ancestor
+   * transforms included - so a bare `<Scene>` renders at native density on
+   * any display, and viewport-relative camera controls scale with the box.
+   * Fill or fixed is decided at mount. `output` needs explicit sizes (the
+   * target cannot follow a leaf it does not own); the leaf's own
+   * width/height are then layout, so render size and display size separate
+   * (supersampling).
+   */
+  width?: number
+  height?: number
+  clearColor?: [number, number, number, number]
+  /**
+   * Drive the scene camera declaratively (scene.setCamera as a prop): a
+   * partial CameraUpdate, absent keys keep their values - `ortho` included,
+   * which `<PerspectiveCamera>` by its name never sets. The prop and the
+   * `<PerspectiveCamera>` child write the same scene state, so use one
+   * form, not both (last write wins). The 2d layers' `camera` prop, one
+   * dimension up.
+   */
+  camera?: CameraUpdate
+  /** The background drawn behind the meshes, inside the scene's own pass
+   * (scene.setBackground): fragment GLSL (vUV/iResolution/fragColor plus
+   * the vRay view ray, so a createShaderTexture backdrop ports verbatim
+   * and a directional sky is a few lines) or a skybox `{ cube, intensity?,
+   * rotation? }`. Reactive - swapping the source replaces the background,
+   * a skybox's knobs update in place; undefined removes it. Three's
+   * `scene.background = color` is `clearColor` here. */
+  background?: string | SkyboxOptions
+  /** The cube map reflective `lit` materials mirror (scene.setEnvironment):
+   * `{ cube, intensity?, rotation? }`, typically the skybox's own cube
+   * turned with it. Reactive; undefined removes it. */
+  environment?: EnvironmentOptions
+  /** Scene-wide fog (scene.setFog): linear `{ color, near, far }` or exp2
+   * `{ color, density }`, optionally thinning above `height` by
+   * `heightFalloff`; every standard material fades toward `color` by
+   * distance from the camera. Reactive; undefined removes it. Match
+   * `color` to clearColor or the background, which is not fogged. */
+  fog?: FogOptions
+  /** Output tone mapping (scene.setToneMapping): "none" (default) or
+   * "aces". Reactive. */
+  toneMapping?: ToneMapping
+  /** Output exposure (scene.setExposure), default 1. Reactive. */
+  exposure?: number
+  /** The scene target's layer mask (scene.setLayers as a prop; default 1):
+   * the scene draws the meshes whose `layers` intersect it. Reactive. */
+  layers?: number
+  /** `"texture"` exposes the target's depth as `scene.depthTexture` (a
+   * depth-reading post effect's input). Fixed at creation; not with
+   * `samples`. */
+  depth?: true | "texture"
+  label?: string
+  /** Multisample count (1, 2, 4 or 8; default 1): anti-aliased mesh edges.
+   * Fixed at creation. */
+  samples?: 1 | 2 | 4 | 8
+  ref?: (scene: SceneHandle) => void
+  /**
+   * Compose the output yourself: called once (untracked) with the scene's
+   * texture id, and its return renders in place of the built-in `<texture>`
+   * leaf - a `<d-texture>`, a leaf carrying paint/pointer/layout props, or
+   * a post-effect chain (a shader target sampling the id; created in the
+   * callback it disposes with the Scene). Return null to render no leaf.
+   * Pointer events then need the scene's handlers on your leaf:
+   * `<texture src={texture} {...useScene().scene.handlers} />` - one
+   * spread carries the node events, the scene's own and the pointer
+   * feed, which listens at the scene's root.
+   */
+  output?: (texture: TextureId) => Element
+  /**
+   * Pointer events (default on): the built-in leaf carries scene.handlers,
+   * so nodes, the scene's own handlers and a camera control's feed
+   * receive input. `false` detaches them - the leaf then costs no pointer
+   * routing at all.
+   */
+  events?: boolean
+  /**
+   * The pointer feed of the scene's leaf (createPointerFeed), fed from
+   * the scene's root - the events the nodes let through: a mesh that
+   * claims its press (stopPropagation on its down) keeps a camera control
+   * bound to the feed out of that drag. The feed's gestures - drag,
+   * pinch, two-finger pan, wheel, mouse motion under lock - come from
+   * this scene, and an input map binds them to the camera controls
+   * inside; `useScene().pointer` is this feed. Fixed at creation. Without
+   * one the leaf feeds no gestures and the controls move only through
+   * their handles.
+   */
+  pointer?: PointerFeed
+}
+
+/**
+ * Owns a draw target and composites it as an ordinary `<texture>` leaf, so
+ * the output takes layout, transforms, blendMode, and pointer events like
+ * any element - or hand `output` the texture id and compose it yourself.
+ * Children (Mesh/Group/PerspectiveCamera) render nothing themselves - they
+ * populate the retained scene through context.
+ */
+// Creation size of a fill-mode target: the first onLayout replaces it
+// before the first paint, so it only has to be a valid texture size.
+const FILL_INITIAL_SIZE = 1
+
+export let Scene: ParentComponent<SceneProps> = props => {
+  // Fill vs fixed target is decided at mount, like `output`: both
+  // width and height (fixed pixels) or neither (fill).
+  let fill = untrack(() => {
+    if ((props.width === undefined) !== (props.height === undefined)) {
+      throw new Error("Scene: width and height come together - give both (fixed target) or neither (fill)")
+    }
+    if (props.width === undefined && props.output) {
+      throw new Error("Scene: fill needs the built-in leaf - with output, give width and height")
+    }
+    return props.width === undefined
+  })
+  // The initial props seed createScene, so `ref` (below) hands out a
+  // configured scene and the first frame draws it whole; the effects
+  // after this follow changes only (`defer`).
+  let scene = untrack(() => {
+    let s = createScene(props.width ?? FILL_INITIAL_SIZE, props.height ?? FILL_INITIAL_SIZE, {
+      clearColor: props.clearColor,
+      label: props.label,
+      samples: props.samples,
+      depth: props.depth,
+      background: props.background,
+      environment: props.environment,
+      fog: props.fog,
+      toneMapping: props.toneMapping,
+      exposure: props.exposure,
+      layers: props.layers,
+    })
+    if (props.camera) s.setCamera(props.camera)
+    return s
+  })
+  createEffect(
+    () => [props.width, props.height] as const,
+    ([w, h]) => {
+      if ((w === undefined) !== (h === undefined) || (w === undefined) !== fill) {
+        throw new Error("Scene: fill/fixed is mount-fixed - width/height cannot appear or disappear")
+      }
+      if (!fill) scene.setSize(w!, h!)
+    },
+  )
+  createEffect(
+    () => props.camera,
+    camera => {
+      if (camera) scene.setCamera(camera)
+    },
+    { defer: true },
+  )
+  createEffect(
+    () => props.background,
+    b => scene.setBackground(b ?? null),
+    { defer: true },
+  )
+  createEffect(
+    () => props.environment,
+    e => scene.setEnvironment(e ?? null),
+    { defer: true },
+  )
+  createEffect(
+    () => props.fog,
+    f => scene.setFog(f ?? null),
+    { defer: true },
+  )
+  createEffect(
+    () => props.toneMapping,
+    t => scene.setToneMapping(t ?? "none"),
+    { defer: true },
+  )
+  createEffect(
+    () => props.exposure,
+    e => scene.setExposure(e ?? 1),
+    { defer: true },
+  )
+  createEffect(
+    () => props.layers,
+    l => scene.setLayers(l ?? 1),
+    { defer: true },
+  )
+  untrack(() => props.ref)?.(scene)
+  // The pointer feed the app handed in listens at the scene's root, and
+  // children reach it through useScene().pointer. Fixed at creation, like
+  // output.
+  let pointer = untrack(() => props.pointer) ?? null
+  if (pointer) onCleanup(feedPointer(scene, pointer))
+  // The scene's own handlers at the root of the walk; the props are read
+  // per event, so a handler prop may change without re-registering.
+  onCleanup(
+    scene.listen({
+      onPointerDown: e => props.onPointerDown?.(e),
+      onPointerMove: e => props.onPointerMove?.(e),
+      onPointerUp: e => props.onPointerUp?.(e),
+      onWheel: e => props.onWheel?.(e),
+      onTap: e => props.onTap?.(e),
+    }),
+  )
+  let output = untrack(() => props.output)
+  let events = untrack(() => props.events) !== false
+  let leafNode: { id: number } | undefined
+  // The built-in leaf's laid-out box in ITS units - what pointer
+  // localX/localY report in and every handlersFor scales against. Fixed
+  // mode lays the leaf out at the target size; fill mode reads the box
+  // back (getLayoutBox, the untransformed read, so a designSize fit or
+  // ancestor transform never skews events). Zero before the first layout:
+  // no event can arrive before one, and a degenerate layout passes
+  // coordinates through unscaled. A custom output leaf registers its own
+  // layout via handlersFor.
+  let builtinLayout = fill
+    ? () => (leafNode && getLayoutBox(leafNode)) || { width: 0, height: 0 }
+    : () => ({ width: props.width!, height: props.height! })
+  if (fill) {
+    // Fill sizing: after every layout (and on display-scale changes, which
+    // lay nothing out) the target follows the leaf's on-screen box in
+    // device pixels - getBoundingBoxViewport composes designSize fits and
+    // ancestor transforms, so the scene renders at true density wherever
+    // it sits. onLayout runs before paint (no frame draws at a stale
+    // size); setSize no-ops when nothing changed. apply runs as an
+    // onLayout handler and as an effect apply, both untracked scopes, so
+    // its scale read is wrapped in an explicit untrack (the effect's
+    // compute is what tracks it).
+    let apply = () =>
+      untrack(() => {
+        if (!leafNode) return
+        let box = getBoundingBoxViewport(leafNode)
+        if (!box) return
+        let scale = displayScale()
+        scene.setSize(Math.max(1, Math.round(box.width * scale)), Math.max(1, Math.round(box.height * scale)))
+      })
+    onLayout(apply)
+    createEffect(() => displayScale(), apply)
+  }
+  // Pointer events on the built-in leaf: at target size the plain
+  // handlers, in fill mode scaled from the laid-out box.
+  let sceneHandlers = fill ? scene.handlersFor(builtinLayout) : scene.handlers
+  return (
+    <SceneContext value={{ scene, parent: scene.root, viewport: scene, pointer }}>
+      {output ? (
+        untrack(() => output(scene.texture))
+      ) : (
+        <texture
+          ref={(n: { id: number }) => (leafNode = n)}
+          src={scene.texture}
+          width={fill ? "100%" : props.width}
+          height={fill ? "100%" : props.height}
+          onPointerDown={events ? sceneHandlers.onPointerDown : undefined}
+          onPointerMove={events ? sceneHandlers.onPointerMove : undefined}
+          onPointerUp={events ? sceneHandlers.onPointerUp : undefined}
+          onPointerLeave={events ? sceneHandlers.onPointerLeave : undefined}
+          onWheel={events ? sceneHandlers.onWheel : undefined}
+        />
+      )}
+      {props.children}
+    </SceneContext>
+  )
+}

package/src/components/spot-light.tsx

@@ -0,0 +1,65 @@
+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 { createSpotLight, setLight } from "../light.ts"
+import type { SpotLight as SpotLightNode, SpotShadowOptions } from "../light.ts"
+import type { Vec3 } from "../math.ts"
+
+export type SpotLightProps = TransformProps & {
+  /** Aim direction in the node's local space; default [0, -1, 0], a
+   * lamp pointing straight down. */
+  direction?: Vec3
+  color?: Vec3
+  intensity?: number
+  /** Falloff cutoff in world units (0 = no cutoff). */
+  distance?: number
+  /** Cone half-angle in DEGREES, (0, 90]; default 60 (degrees like
+   * camera fov; Three's radians convert as `angle * 180 / PI`). */
+  angle?: number
+  /** 0..1 fraction of the cone fading to the rim; default 0. */
+  penumbra?: number
+  /** Falloff exponent; default 2 (inverse square). */
+  decay?: number
+  /** Render a shadow map from this light (a perspective map of its
+   * cone; one shadow slot). */
+  castShadow?: boolean
+  /** Shadow-map options (mapSize, bias, normalBias, near), merged key
+   * by key. */
+  shadow?: SpotShadowOptions
+  ref?: (light: SpotLightNode) => void
+}
+
+/** A spot light node (createSpotLight): a cone from the node's world
+ * position along its local `direction` - give it a `position`, and aim
+ * it with `direction` or a parent's rotation. Counts against MAX_LIGHTS
+ * with the other non-ambient lights. */
+export let SpotLight: VoidComponent<SpotLightProps> = props => {
+  let ctx = useContext(SceneContext)
+  let light = untrack(() =>
+    createSpotLight({
+      direction: props.direction,
+      color: props.color,
+      intensity: props.intensity,
+      distance: props.distance,
+      angle: props.angle,
+      penumbra: props.penumbra,
+      decay: props.decay,
+      castShadow: props.castShadow,
+      shadow: props.shadow,
+    }),
+  )
+  add(ctx.parent, light)
+  syncNode(light, props)
+  createEffect(
+    () =>
+      [props.direction, props.color, props.intensity, props.distance, props.angle, props.penumbra, props.decay, props.castShadow, props.shadow] as const,
+    ([direction, color, intensity, distance, angle, penumbra, decay, castShadow, shadow]) =>
+      setLight(light, { direction, color, intensity, distance, angle, penumbra, decay, castShadow, shadow }),
+  )
+  untrack(() => props.ref)?.(light)
+  onCleanup(() => remove(light))
+  return null
+}