@solidrt/3d 0.0.47 → 0.0.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.47",
+  "version": "0.0.49",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -16,7 +16,7 @@
     "AGENTS.md"
   ],
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-beta.31",
-    "@solidrt/core": "0.0.47"
+    "@solidjs/signals": "2.0.0-rc.0",
+    "@solidrt/core": "0.0.49"
   }
 }

package/src/bvh.ts

@@ -0,0 +1,258 @@
+// A dynamic bounding-volume hierarchy - the physics-broadphase AABB tree
+// (Box2D/Bullet lineage): a binary tree over the items' world boxes, NOT a
+// subdivision of space. Leaves store FAT boxes (a margin around the tight
+// bounds) so an item moving a little refits nothing; an item escaping its
+// fat box is removed and re-inserted along the cheapest path (least area
+// growth). A ray query walks O(log n) nodes instead of testing every item,
+// which is what keeps per-pointer-move picking off the O(meshes) path.
+//
+// The scene keeps the tree current from its own sync walk: transforms that
+// changed are exactly the leaves to update, so maintenance is O(changed)
+// per frame - the same delta discipline as rendering, and a static scene
+// pays nothing. Storage is flat parallel arrays indexed by node id (no
+// per-node objects, no allocation at steady state past tree growth).
+//
+// Pure module by design: no engine imports, so the differential check rig
+// (checks/pick-check.ts) runs it under plain bun against a linear oracle.
+
+/** Fat-margin fraction of a leaf's largest extent. Bigger = fewer
+ * re-inserts while moving, worse query pruning; 5% is the usual trade. */
+const MARGIN = 0.05
+
+type Visit<T> = (item: T) => void
+
+export type Bvh<T> = {
+  /** Insert an item with its tight world box; returns the leaf handle. */
+  insert(item: T, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): number
+  /** Update a leaf's tight box. Free while it stays inside the fat box;
+   * otherwise the leaf re-inserts. Returns true when it moved. */
+  update(leaf: number, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): boolean
+  /** Remove a leaf (the handle is dead afterwards). */
+  remove(leaf: number): void
+  /** Visit every item whose FAT box the ray hits (t >= 0). Broadphase
+   * only: the caller narrowphases against its own tight volumes. */
+  raycast(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, visit: Visit<T>): void
+}
+
+/**
+ * Entry distance of a ray against a box: the smallest t >= 0 with
+ * origin + t * direction inside [min, max] (0 when the origin starts
+ * inside), or -1 for a miss. The direction need not be normalized - t is
+ * in units of its length, which is what keeps a ray transformed into a
+ * mesh's local space reporting world distances. Shared by the tree's
+ * broadphase and the scene's narrowphase.
+ */
+export function rayBoxDistance(
+  ox: number, oy: number, oz: number,
+  dx: number, dy: number, dz: number,
+  minX: number, minY: number, minZ: number,
+  maxX: number, maxY: number, maxZ: number,
+): number {
+  let tNear = 0
+  let tFar = Infinity
+  // Per axis: a zero direction component never crosses the slab, so the
+  // origin must already be inside it (the multiply-by-inverse shortcut
+  // turns that case into NaN, hence the explicit branch).
+  if (dx === 0) {
+    if (ox < minX || ox > maxX) return -1
+  } else {
+    let inv = 1 / dx
+    let t1 = (minX - ox) * inv
+    let t2 = (maxX - ox) * inv
+    if (t1 > t2) { let t = t1; t1 = t2; t2 = t }
+    if (t1 > tNear) tNear = t1
+    if (t2 < tFar) tFar = t2
+  }
+  if (dy === 0) {
+    if (oy < minY || oy > maxY) return -1
+  } else {
+    let inv = 1 / dy
+    let t1 = (minY - oy) * inv
+    let t2 = (maxY - oy) * inv
+    if (t1 > t2) { let t = t1; t1 = t2; t2 = t }
+    if (t1 > tNear) tNear = t1
+    if (t2 < tFar) tFar = t2
+  }
+  if (dz === 0) {
+    if (oz < minZ || oz > maxZ) return -1
+  } else {
+    let inv = 1 / dz
+    let t1 = (minZ - oz) * inv
+    let t2 = (maxZ - oz) * inv
+    if (t1 > t2) { let t = t1; t1 = t2; t2 = t }
+    if (t1 > tNear) tNear = t1
+    if (t2 < tFar) tFar = t2
+  }
+  return tFar >= tNear ? tNear : -1
+}
+
+export function createBvh<T>(): Bvh<T> {
+  // Node storage, 6 bounds floats per node; child1 === -1 marks a leaf.
+  let bounds: number[] = []
+  let parent: number[] = []
+  let child1: number[] = []
+  let child2: number[] = []
+  let items: (T | undefined)[] = []
+  let free: number[] = []
+  let root = -1
+  // Traversal stack, reused across queries.
+  let stack: number[] = []
+
+  let allocate = (): number => {
+    let node = free.pop()
+    if (node === undefined) {
+      node = parent.length
+      bounds.push(0, 0, 0, 0, 0, 0)
+      parent.push(-1)
+      child1.push(-1)
+      child2.push(-1)
+      items.push(undefined)
+    }
+    return node
+  }
+
+  // Half the surface area - the SAH cost of a node's box. Degenerate
+  // (flat) boxes still cost via their other faces, which is what makes
+  // the heuristic sane for planes.
+  let area = (n: number): number => {
+    let i = n * 6
+    let w = bounds[i + 3]! - bounds[i]!
+    let h = bounds[i + 4]! - bounds[i + 1]!
+    let d = bounds[i + 5]! - bounds[i + 2]!
+    return w * (h + d) + h * d
+  }
+
+  let unionArea = (n: number, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): number => {
+    let i = n * 6
+    let w = Math.max(bounds[i + 3]!, maxX) - Math.min(bounds[i]!, minX)
+    let h = Math.max(bounds[i + 4]!, maxY) - Math.min(bounds[i + 1]!, minY)
+    let d = Math.max(bounds[i + 5]!, maxZ) - Math.min(bounds[i + 2]!, minZ)
+    return w * (h + d) + h * d
+  }
+
+  // Recompute an internal node's box as the union of its children.
+  let refit = (n: number): void => {
+    let a = child1[n]! * 6
+    let b = child2[n]! * 6
+    let i = n * 6
+    bounds[i] = Math.min(bounds[a]!, bounds[b]!)
+    bounds[i + 1] = Math.min(bounds[a + 1]!, bounds[b + 1]!)
+    bounds[i + 2] = Math.min(bounds[a + 2]!, bounds[b + 2]!)
+    bounds[i + 3] = Math.max(bounds[a + 3]!, bounds[b + 3]!)
+    bounds[i + 4] = Math.max(bounds[a + 4]!, bounds[b + 4]!)
+    bounds[i + 5] = Math.max(bounds[a + 5]!, bounds[b + 5]!)
+  }
+
+  let insertLeaf = (leaf: number): void => {
+    if (root === -1) {
+      root = leaf
+      parent[leaf] = -1
+      return
+    }
+    let i = leaf * 6
+    let minX = bounds[i]!, minY = bounds[i + 1]!, minZ = bounds[i + 2]!
+    let maxX = bounds[i + 3]!, maxY = bounds[i + 4]!, maxZ = bounds[i + 5]!
+    // Descend toward the sibling that grows the least (the classic
+    // incremental surface-area heuristic).
+    let sibling = root
+    while (child1[sibling] !== -1) {
+      let a = child1[sibling]!
+      let b = child2[sibling]!
+      let costA = unionArea(a, minX, minY, minZ, maxX, maxY, maxZ) - area(a)
+      let costB = unionArea(b, minX, minY, minZ, maxX, maxY, maxZ) - area(b)
+      sibling = costA < costB ? a : b
+    }
+    let oldParent = parent[sibling]!
+    let newParent = allocate()
+    parent[newParent] = oldParent
+    child1[newParent] = sibling
+    child2[newParent] = leaf
+    items[newParent] = undefined
+    parent[sibling] = newParent
+    parent[leaf] = newParent
+    if (oldParent === -1) {
+      root = newParent
+    } else if (child1[oldParent] === sibling) {
+      child1[oldParent] = newParent
+    } else {
+      child2[oldParent] = newParent
+    }
+    for (let n = newParent; n !== -1; n = parent[n]!) refit(n)
+  }
+
+  let removeLeaf = (leaf: number): void => {
+    if (leaf === root) {
+      root = -1
+      return
+    }
+    let p = parent[leaf]!
+    let sibling = child1[p] === leaf ? child2[p]! : child1[p]!
+    let grand = parent[p]!
+    parent[sibling] = grand
+    if (grand === -1) {
+      root = sibling
+    } else {
+      if (child1[grand] === p) child1[grand] = sibling
+      else child2[grand] = sibling
+      for (let n = grand; n !== -1; n = parent[n]!) refit(n)
+    }
+    child1[p] = -1
+    items[p] = undefined
+    free.push(p)
+  }
+
+  let setFat = (leaf: number, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): void => {
+    let m = MARGIN * Math.max(maxX - minX, maxY - minY, maxZ - minZ)
+    let i = leaf * 6
+    bounds[i] = minX - m
+    bounds[i + 1] = minY - m
+    bounds[i + 2] = minZ - m
+    bounds[i + 3] = maxX + m
+    bounds[i + 4] = maxY + m
+    bounds[i + 5] = maxZ + m
+  }
+
+  return {
+    insert(item, minX, minY, minZ, maxX, maxY, maxZ) {
+      let leaf = allocate()
+      items[leaf] = item
+      setFat(leaf, minX, minY, minZ, maxX, maxY, maxZ)
+      insertLeaf(leaf)
+      return leaf
+    },
+    update(leaf, minX, minY, minZ, maxX, maxY, maxZ) {
+      let i = leaf * 6
+      if (
+        bounds[i]! <= minX && bounds[i + 1]! <= minY && bounds[i + 2]! <= minZ &&
+        bounds[i + 3]! >= maxX && bounds[i + 4]! >= maxY && bounds[i + 5]! >= maxZ
+      ) {
+        return false
+      }
+      removeLeaf(leaf)
+      setFat(leaf, minX, minY, minZ, maxX, maxY, maxZ)
+      insertLeaf(leaf)
+      return true
+    },
+    remove(leaf) {
+      removeLeaf(leaf)
+      items[leaf] = undefined
+      free.push(leaf)
+    },
+    raycast(ox, oy, oz, dx, dy, dz, visit) {
+      if (root === -1) return
+      stack.length = 0
+      stack.push(root)
+      while (stack.length > 0) {
+        let n = stack.pop()!
+        let i = n * 6
+        let t = rayBoxDistance(ox, oy, oz, dx, dy, dz, bounds[i]!, bounds[i + 1]!, bounds[i + 2]!, bounds[i + 3]!, bounds[i + 4]!, bounds[i + 5]!)
+        if (t < 0) continue
+        if (child1[n] === -1) {
+          visit(items[n] as T)
+        } else {
+          stack.push(child1[n]!, child2[n]!)
+        }
+      }
+    },
+  }
+}

package/src/components.tsx

@@ -16,13 +16,15 @@ import {
   remove,
   setGeometry,
   setMaterial,
+  setMeshParams,
   setTransform,
   setVisible,
 } from "./scene.ts"
-import type { Mesh as MeshNode, Scene as SceneHandle, SceneNode } from "./scene.ts"
+import type { ShaderParams } from "@solidrt/core/gpu"
+import type { Mesh as MeshNode, Scene as SceneHandle, SceneNode, ScenePointerEvent } from "./scene.ts"
 import type { Geometry } from "./geometry.ts"
 import type { Material } from "./material.ts"
-import type { Vec3 } from "./math.ts"
+import type { Quat, Vec3 } from "./math.ts"
 
 type SceneCtx = { scene: SceneHandle; parent: SceneNode }
 let SceneContext = createContext<SceneCtx>()
@@ -37,20 +39,50 @@ export function useScene(): SceneCtx {
 
 export type TransformProps = {
   position?: Vec3
-  /** Euler radians, applied x then y then z. */
+  /** 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
 }
 
-function syncNode(node: SceneNode, props: TransformProps): void {
+/**
+ * Mesh pointer events, the element vocabulary one tree deeper: the nearest
+ * hit mesh receives the event, down/move/up bubble to ancestor Groups
+ * (stopPropagation stops the walk), enter/leave pair on the mesh 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: ScenePointerEvent) => void
+  onPointerMove?: (event: ScenePointerEvent) => void
+  onPointerUp?: (event: ScenePointerEvent) => void
+  /** Meshes only: a Group never receives enter/leave. */
+  onPointerEnter?: (event: ScenePointerEvent) => void
+  onPointerLeave?: (event: ScenePointerEvent) => void
+}
+
+function syncNode(node: SceneNode, props: TransformProps & PointerEventProps): void {
   createEffect(
-    () => [props.position, props.rotation, props.scale, props.visible] as const,
-    ([position, rotation, scale, visible]) => {
-      setTransform(node, { position, rotation, scale })
+    () => [props.position, props.rotation, props.quaternion, props.scale, props.visible] as const,
+    ([position, rotation, quaternion, scale, visible]) => {
+      setTransform(node, { position, rotation, quaternion, scale })
       setVisible(node, visible !== false)
     },
   )
+  createEffect(
+    () => [props.onPointerDown, props.onPointerMove, props.onPointerUp, props.onPointerEnter, props.onPointerLeave] as const,
+    ([down, move, up, enter, leave]) => {
+      node.onPointerDown = down
+      node.onPointerMove = move
+      node.onPointerUp = up
+      node.onPointerEnter = enter
+      node.onPointerLeave = leave
+    },
+  )
 }
 
 export type SceneProps = {
@@ -59,6 +91,12 @@ export type SceneProps = {
   width: number
   height: number
   clearColor?: [number, number, number, number]
+  /** Fragment GLSL drawn behind the meshes, inside the scene's own pass
+   * (scene.setBackground): vUV/iResolution/fragColor contract, so a
+   * createShaderTexture backdrop ports verbatim. Reactive - swapping the
+   * source replaces the background; undefined removes it. Three's
+   * `scene.background = color` is `clearColor` here. */
+  background?: string
   label?: string
   ref?: (scene: SceneHandle) => void
   /**
@@ -67,8 +105,16 @@ export type SceneProps = {
    * 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.
+   * Mesh pointer events then need the scene's handlers on your leaf:
+   * `<texture src={texture} {...useScene().scene.handlers} />`.
    */
   output?: (texture: TextureId) => Element
+  /**
+   * Mesh pointer events (default on): the built-in leaf carries
+   * scene.handlers, so Mesh/Group onPointer* props receive events. `false`
+   * detaches them - the leaf then costs no pointer routing at all.
+   */
+  events?: boolean
 }
 
 /**
@@ -86,14 +132,27 @@ export let Scene: ParentComponent<SceneProps> = props => {
     () => [props.width, props.height] as const,
     ([w, h]) => scene.setSize(w, h),
   )
+  createEffect(
+    () => props.background,
+    b => scene.setBackground(b ?? null),
+  )
   untrack(() => props.ref)?.(scene)
   let output = untrack(() => props.output)
+  let events = untrack(() => props.events) !== false
   return (
     <SceneContext value={{ scene, parent: scene.root }}>
       {output ? (
         untrack(() => output(scene.texture))
       ) : (
-        <texture src={scene.texture} width={props.width} height={props.height} />
+        <texture
+          src={scene.texture}
+          width={props.width}
+          height={props.height}
+          onPointerDown={events ? scene.handlers.onPointerDown : undefined}
+          onPointerMove={events ? scene.handlers.onPointerMove : undefined}
+          onPointerUp={events ? scene.handlers.onPointerUp : undefined}
+          onPointerLeave={events ? scene.handlers.onPointerLeave : undefined}
+        />
       )}
       {props.children}
     </SceneContext>
@@ -101,7 +160,7 @@ export let Scene: ParentComponent<SceneProps> = props => {
 }
 
 /** A transform node: children inherit its position/rotation/scale. */
-export let Group: ParentComponent<TransformProps & { ref?: (node: SceneNode) => void }> = props => {
+export let Group: ParentComponent<TransformProps & PointerEventProps & { ref?: (node: SceneNode) => void }> = props => {
   let ctx = useContext(SceneContext)
   let node = createGroup()
   add(ctx.parent, node)
@@ -111,9 +170,15 @@ export let Group: ParentComponent<TransformProps & { ref?: (node: SceneNode) =>
   return <SceneContext value={{ scene: ctx.scene, parent: node }}>{props.children}</SceneContext>
 }
 
-export type MeshProps = TransformProps & {
+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
   ref?: (mesh: MeshNode) => void
 }
 
@@ -132,6 +197,12 @@ export let Mesh: VoidComponent<MeshProps> = props => {
     m => setMaterial(mesh, m),
     { defer: true },
   )
+  createEffect(
+    () => props.params,
+    p => {
+      if (p !== undefined) setMeshParams(mesh, p)
+    },
+  )
   syncNode(mesh, props)
   untrack(() => props.ref)?.(mesh)
   onCleanup(() => remove(mesh))

package/src/geometry.ts

@@ -43,6 +43,12 @@ export const VERTEX_LAYOUTS: Record<VertexLayout, VertexAttribute[]> = {
 export const FLOATS_PER_VERTEX = 8
 const COLORED_FLOATS = 12
 
+/** Uint16 indices when they fit, Uint32Array past 64k vertices - the draw
+ * entry follows the array type. The tail of every unbounded generator. */
+export function packIndices(indices: number[], vertexCount: number): Uint16Array | Uint32Array {
+  return vertexCount > 65535 ? new Uint32Array(indices) : new Uint16Array(indices)
+}
+
 export type Geometry = {
   /** Interleaved [pos.xyz, normal.xyz, uv.xy] per vertex, plus color.rgba
    * in the "colored" layout. */
@@ -57,6 +63,35 @@ export type Geometry = {
   label?: string
   _buffer?: BufferId
   _index?: BufferId
+  _bounds?: Float32Array
+}
+
+/**
+ * The geometry's LOCAL axis-aligned bounds as [minX, minY, minZ, maxX,
+ * maxY, maxZ], computed from the vertices on first use and cached (like
+ * the GPU buffers, geometry is treated as immutable after creation).
+ * Picking's narrowphase volume; a flat geometry legitimately has zero
+ * extent on an axis. An empty geometry yields a zero box at the origin.
+ */
+export function geometryBounds(geometry: Geometry): Float32Array {
+  let bounds = geometry._bounds
+  if (bounds === undefined) {
+    bounds = new Float32Array([Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity])
+    let v = geometry.vertices
+    let stride = geometry.layout === "colored" ? COLORED_FLOATS : FLOATS_PER_VERTEX
+    for (let i = 0; i + 2 < v.length; i += stride) {
+      let x = v[i]!, y = v[i + 1]!, z = v[i + 2]!
+      if (x < bounds[0]!) bounds[0] = x
+      if (y < bounds[1]!) bounds[1] = y
+      if (z < bounds[2]!) bounds[2] = z
+      if (x > bounds[3]!) bounds[3] = x
+      if (y > bounds[4]!) bounds[4] = y
+      if (z > bounds[5]!) bounds[5] = z
+    }
+    if (bounds[0]! > bounds[3]!) bounds.fill(0)
+    geometry._bounds = bounds
+  }
+  return bounds
 }
 
 /** The geometry's GPU buffers, created on first use and cached on it,

package/src/index.ts

@@ -5,17 +5,21 @@
 // without Solid components) and the component face (Scene/Mesh/Group/
 // PerspectiveCamera) on top. See AGENTS.md for the model and the traps.
 
-export { add, createGroup, createMesh, createScene, remove, setGeometry, setMaterial, setMeshParams, setTransform, setVisible } from "./scene.ts"
-export type { CameraUpdate, Mesh as MeshNode, Scene as SceneHandle, SceneNode, SceneOptions, TransformUpdate } from "./scene.ts"
+export { add, createGroup, createMesh, createScene, getRotation, lookAt, remove, setGeometry, setMaterial, setMeshParams, setTransform, setVisible, worldPosition } from "./scene.ts"
+export type { CameraUpdate, Hit, Mesh as MeshNode, Scene as SceneHandle, SceneHandlers, SceneNode, SceneOptions, ScenePointerEvent, TransformUpdate } from "./scene.ts"
 export { box, circle, cone, cylinder, disposeGeometry, fillColors, plane, ring, sphere, torus, torusKnot, withColors, FLOATS_PER_VERTEX, VERTEX_LAYOUTS } from "./geometry.ts"
 export type { ColorFill, Geometry, VertexLayout } from "./geometry.ts"
-export { extrude, fillet, lathe, roundRect, shape, triangulate } from "./profile.ts"
+export { fillet, roundRect, shape, triangulate } from "./profile.ts"
 export type { Profile, ProfilePoint } from "./profile.ts"
+export { extrude, lathe, pathFrames, sweep, tube } from "./sweep.ts"
+export type { PathFrames, PathPoint, SweepPath } from "./sweep.ts"
 export { shaderMaterial, unlit } from "./material.ts"
 export type { Material, ShaderMaterialOptions, UnlitOptions } from "./material.ts"
 export { Group, Mesh, PerspectiveCamera, Scene, useScene } from "./components.tsx"
-export type { MeshProps, PerspectiveCameraProps, SceneProps, TransformProps } from "./components.tsx"
+export type { MeshProps, PerspectiveCameraProps, PointerEventProps, SceneProps, TransformProps } from "./components.tsx"
 export { createOrbitCamera } from "./orbit.ts"
 export type { OrbitCamera, OrbitCameraOptions, OrbitPose } from "./orbit.ts"
-export { compose, copy, identity, lookAt, mat4, multiply, normalMatrix, perspective } from "./math.ts"
-export type { Mat4, Vec2, Vec3 } from "./math.ts"
+// math's lookAt (the camera view matrix) stays on the /math subpath: the
+// root's lookAt is the scene verb, the same split as `add`.
+export { compose, copy, eulerFromQuat, identity, mat4, multiply, normalMatrix, perspective, quat, quatFromAxisAngle, quatFromEuler, quatFromFrame, quatFromTo, quatMultiply, quatNormalize, quatSlerp } from "./math.ts"
+export type { Mat4, Quat, Vec2, Vec3 } from "./math.ts"

package/src/material.ts

@@ -144,6 +144,43 @@ function needsHeader(source: string): boolean {
   return !source.trimStart().startsWith("#version")
 }
 
+// The scene-background pass (scene.setBackground). The vertex stage is the
+// engine's own attributeless fullscreen triangle (gl_VertexID, no vertex
+// buffer), emitting the SAME vUV the shader-target contract provides: 0..1
+// with origin at the displayed top-left - so a backdrop fragment written
+// for createShaderTexture ports verbatim.
+const BACKGROUND_VERTEX = glsl`
+  out vec2 vUV;
+  void main() {
+    vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+    vUV = p;
+    gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+  }
+`
+
+// Pipeline fragments get no vUV from the engine preamble (a pipeline's
+// varyings are its own), so the background slot injects the full
+// shader-target fragment contract itself: vUV, fragColor, iResolution.
+const BACKGROUND_FRAGMENT_PREAMBLE =
+  "#version 300 es\nprecision highp float;\nin vec2 vUV;\nout vec4 fragColor;\nuniform vec2 iResolution;\n"
+
+/** The scene's background pipeline (internal - reached via
+ * scene.setBackground): depth-free, attributeless, drawn as entry zero of
+ * the scene pass. */
+export function backgroundPipeline(fragment: string, label: string): { pipeline: RenderPipelineId; program: ProgramId } {
+  let vs = compileShader("vertex", BACKGROUND_VERTEX, { header: true })
+  let fs = compileShader(
+    "fragment",
+    needsHeader(fragment) ? BACKGROUND_FRAGMENT_PREAMBLE + fragment : fragment,
+    { header: false },
+  )
+  let program = linkProgram(vs, fs, { label })
+  destroyShader(vs)
+  destroyShader(fs)
+  let pipeline = createRenderPipeline(program, { label })
+  return { pipeline, program }
+}
+
 export type ShaderMaterialOptions = {
   /**
    * Vertex stage GLSL. MUST declare and use `uniform mat4 uModel` (the