@solidrt/3d 0.0.51 → 0.0.53

package/README.md

@@ -77,18 +77,22 @@ blinn, fresnel, a standard vertex stage) to compose your own lit looks
 from plain template literals.
 
 v1 scope: unlit color/textured materials plus `shaderMaterial` (your own
-GLSL as a first-class material), geometry generators (box, plane, circle,
+GLSL as a first-class material), sprites (`<Sprite>` with a `sprite()`
+material: a quad facing the camera in the vertex stage, full or fixed-y
+billboarding), geometry generators (box, plane, circle,
 ring, sphere, cylinder, cone, torus, torus knot), a profile kit for custom
 solids (`extrude` with bevels, `lathe`, polyline `sweep`/`tube` with
 mitred joints, flat `shape`, with `fillet`/`roundRect`/`triangulate`
 helpers), geometry as data (`transformGeometry` bakes a placement into
 vertices and `mergeGeometries` concatenates parts, so a static scene is
-one mesh per material), a per-vertex data channel
-(`withColors` adds an `aColor` vec4 - tint, baked AO, any four scalars -
-to any geometry, for materials that read it), one perspective camera
+one mesh per material), open vertex layouts (`withAttribute` appends any
+named channel to a geometry's interleave, `withColors` is the `aColor`
+vec4 case - tint, baked AO, any four scalars - and materials read channels
+by name), one perspective camera
 with an orbit control (`createOrbitCamera`: drag, pinch/wheel zoom, auto-orbit),
-mesh picking with pointer events, and scene backgrounds.
-Lights, transparency and model loading are
-staged next - see `okf/research/scene-graph-3d.md` for the roadmap. Full
-usage notes and traps: [AGENTS.md](AGENTS.md); runnable examples:
-[examples/](examples/).
+mesh picking with pointer events, scene backgrounds, transparency, and
+lights (`lit` material with hemisphere ambient, up to four directional
+light nodes, Blinn-Phong highlight and triplanar mapping).
+Model loading and shadows are staged next - see `okf/notes/3d-roadmap.md`
+for the ranked list. Full usage notes and traps: [AGENTS.md](AGENTS.md);
+runnable examples: [examples/](examples/).

package/examples/README.md

@@ -9,8 +9,14 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   and pipeline sharing, and the one-signal onFrame drive.
 - `sweep-paths.tsx` - swept solids along polylines: a flat strap folding
   over a crate (bare path points crease on the mitred bends) and a coiled
-  tube (smooth-tagged helix, one continuous mesh), lit via the exported
-  GLSL so the creased-vs-smooth normals actually show.
+  tube (smooth-tagged helix, one continuous mesh), lit so the
+  creased-vs-smooth normals actually show.
+- `lit.tsx` - the lit material and light nodes: `<HemisphereLight>` plus
+  a warm key `<DirectionalLight>` turning inside a spinning `<Group>` and
+  a fixed cool fill,
+  a glossy sphere (specular/shininess), a transparent glass sphere, and
+  one checker map shared by a UV-mapped cube (stretched per face) and
+  two triplanar meshes tiling it at one world density.
 - `aim.tsx` - the rotation verbs, one pointer each tracking an orbiting
   target: `lookAt` for a +z solid, `quatFromTo` for aiming a y-axis cone,
   and a `quatSlerp` damped follow that visibly lags; all driven from
@@ -23,8 +29,37 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   scene's own pass (`<Scene background>`): one target, no stacked
   backdrop texture, no resize plumbing; the source is shader-target
   compatible verbatim.
+- `sprites.tsx` - sprites: a ring of `"full"` billboard glows that stay
+  flat to the screen and `"fixed-y"` cutout trees that only yaw toward
+  the camera and stay upright as it climbs, both turned in the vertex
+  stage while the camera circles - no per-sprite JS per frame.
 - `instanced.tsx` - instanced meshes: one material class declaring
   `instanceAttributes`, two `<InstancedMesh>` fleets (400 scattered
   rocks, a ring of pines) each ONE draw entry and ONE uModel, a spinning
   group moving both with two matrix writes, and `setInstanceCount` from
   onFrame breathing the pine population.
+- `scene-views.tsx` - scene views: one scene rendered three times, the
+  built-in perspective leaf plus two `scene.createView` targets - a
+  top-down ORTHOGRAPHIC map (`ortho` on setCamera) and a side silhouette
+  drawn with an `overrideMaterial`; one spinning group, one signal, every
+  target fed by the core's one flush.
+- `shadows.tsx` - directional shadow maps from three casting lights: a
+  `castShadow` sun swinging through its arc (one setTransform per frame
+  on the light node), a fixed cool fill and a low rim light, `castShadow`
+  meshes turning in a group throwing three crossing shadows each, the
+  ground and the casters receiving through plain `lit` (the default);
+  each shadow camera follows its light's world matrix, each map is
+  rendered by an internal view.
+- `cascades.tsx` - cascaded shadow maps: a sun with `shadow: { cascades:
+  3 }` over a field of pillars to the horizon under a slowly flying
+  camera; three maps fitted to slices of the camera frustum, sampled
+  tightest-first, so the shadows are sharp at the camera's feet and still
+  there at the far edge of the ground. A click cycles 1..4 cascades (1 is
+  the plain box widened to cover the field: one map's texels spread over
+  it, blocky everywhere) and the `cascades`/`fly` debug commands set the
+  count and the shadow distance and park the flight.
+- `model.tsx` - a model from a file: `model.glb` (a small rover with
+  nested node transforms, a mirrored node, a textured material, a
+  transparent dome and a mesh without normals) parsed with `parseGltf`
+  from a binary import and built by `createModel` into a Group of named
+  parts; clicking a part hides it, clicking the body restores all.

package/examples/aim.tsx

@@ -74,16 +74,16 @@ function App() {
     setTransform(lazy, { quaternion: aimQ })
   })
 
-  let ball = sphere(0.22)
-  let pointer = cone(0.3, 0.9)
+  let ball = sphere({ radius: 0.22 })
+  let pointer = cone({ radius: 0.3, height: 0.9 })
 
   return (
     <window>
-      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
         <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.07, 0.1, 1]} label="aim">
           <PerspectiveCamera fov={55} position={[0, 2.6, 4.6]} lookAt={[0, 0.7, 0]} />
           <Mesh
-            geometry={plane(7, 7, "floor")}
+            geometry={plane({ width: 7, height: 7, label: "floor" })}
             material={unlit({ color: [0.16, 0.17, 0.22] })}
             rotation={[-Math.PI / 2, 0, 0]}
           />
@@ -93,7 +93,7 @@ function App() {
             ref={n => (target = n)}
           />
           <Mesh
-            geometry={tube([[0, 0, 0], [0, 0, 1.1]], 0.09, 10, "rod")}
+            geometry={tube([[0, 0, 0], [0, 0, 1.1]], { radius: 0.09, radialSegments: 10, label: "rod" })}
             material={unlit({ color: [0.85, 0.3, 0.3] })}
             position={[-1.4, 0.5, 0]}
             ref={n => (rod = n)}

package/examples/cascades.tsx

@@ -0,0 +1,121 @@
+// Cascaded shadow maps: a field of pillars to the horizon under a slowly
+// flying camera, lit by one casting sun with `shadow: { cascades: 3 }`.
+// A box shadow (`shadow.camera`) is one map over a fixed area: widened to
+// cover this field its 1024 texels spread over 260 world units and every
+// shadow is blocky, kept tight the far field is unshadowed. With cascades
+// the light renders one map per slice of the SCENE camera's frustum
+// (near..far, tightest first), re-fitted every time the camera or the
+// light moves, and a receiver samples the tightest map that has the
+// point: sharp contact shadows at the camera's feet, coarser ones toward
+// the horizon, at the cost of N times the shadow fill. Every map is a
+// tile of the scene's one atlas, so the pass count is unchanged.
+//
+// A click cycles 1..4 cascades (1 = the box, widened over the field).
+// The `cascades` debug command sets the count and the shadow distance
+// (`{ count, distance }`; the range the cascades split, the camera's far
+// by default - pulling it in sharpens every cascade) and `fly` parks the
+// flight (`{ t: seconds }`), so a capture repeats.
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { registerDebug } from "srt:dev"
+import { box, DirectionalLight, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, Scene, sphere } from "@solidrt/3d"
+import type { Geometry, Vec3 } from "@solidrt/3d"
+
+const SIZE = 720
+const FIELD = 260
+const FAR = 200
+// The flight: a circle over the field, looking ahead along it.
+const RADIUS = 50
+const HEIGHT = 5
+const PERIOD = 90
+
+let [cascades, setCascades] = createSignal(3)
+let [distance, setDistance] = createSignal<number | null>(null)
+// The flight clock, in seconds; `parked` holds it.
+let [time, setTime] = createSignal(0)
+let parked: number | null = null
+
+registerDebug("cascades", (args?: Record<string, unknown>) => {
+  if (typeof args?.count === "number") setCascades(args.count)
+  if (typeof args?.distance === "number" || args?.distance === null) setDistance(args.distance)
+  return { cascades: cascades(), distance: distance() }
+})
+registerDebug("fly", (args?: Record<string, unknown>) => {
+  if (typeof args?.t === "number") {
+    parked = args.t
+    setTime(args.t)
+  } else if (args?.t === null) {
+    parked = null
+  }
+  return { t: time(), parked: parked !== null }
+})
+
+// A grid of pillars with a sphere on every third one, heights varying so
+// the shadows differ in length; one geometry per height, shared.
+let pillars: { position: Vec3; height: number; ball: boolean }[] = []
+let step = 16
+for (let i = -7; i <= 7; i++) {
+  for (let j = -7; j <= 7; j++) {
+    let h = 2 + ((i * 7 + j * 3 + 100) % 5)
+    pillars.push({ position: [i * step + (j % 2) * 4, h / 2, j * step + (i % 2) * 5], height: h, ball: (i + j) % 3 === 0 })
+  }
+}
+let boxes = new Map<number, Geometry>()
+let pillar = (height: number): Geometry => {
+  let g = boxes.get(height)
+  if (g === undefined) boxes.set(height, (g = box({ width: 1.2, height, depth: 1.2 })))
+  return g
+}
+let orb = sphere({ radius: 0.9 })
+
+function App() {
+  onFrame(tick => {
+    if (parked === null) setTime(tick / 1000)
+  })
+  let eye = (): Vec3 => {
+    let a = (time() / PERIOD) * Math.PI * 2
+    return [Math.sin(a) * RADIUS, HEIGHT, Math.cos(a) * RADIUS]
+  }
+  let ahead = (): Vec3 => {
+    let a = (time() / PERIOD) * Math.PI * 2 + 0.5
+    return [Math.sin(a) * RADIUS, 1.5, Math.cos(a) * RADIUS]
+  }
+
+  let ground = lit({ color: [0.5, 0.55, 0.45] })
+  let stone = lit({ color: [0.75, 0.7, 0.62] })
+  let ball = lit({ color: [0.85, 0.35, 0.3], specular: 0.4, shininess: 30 })
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]} onPointerDown={() => setCascades(c => (c % 4) + 1)}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.6, 0.72, 0.88, 1]} samples={4} label="cascades">
+          <PerspectiveCamera fov={50} near={0.5} far={FAR} position={eye()} lookAt={ahead()} />
+          <HemisphereLight sky={[0.5, 0.58, 0.7]} ground={[0.25, 0.22, 0.18]} />
+          <DirectionalLight
+            color={[1, 0.95, 0.85]}
+            intensity={0.9}
+            position={[40, 90, 30]}
+            direction={[-1, -0.55, -0.4]}
+            castShadow
+            shadow={{
+              mapSize: 1024,
+              normalBias: 0.08,
+              cascades: cascades(),
+              distance: distance(),
+              // The box tier's frustum, when cascades is 1: the whole field.
+              camera: { left: -FIELD / 2, right: FIELD / 2, top: FIELD / 2, bottom: -FIELD / 2, near: 1, far: 400 },
+            }}
+          />
+          <Mesh geometry={plane({ width: FIELD, height: FIELD })} material={ground} rotation={[-Math.PI / 2, 0, 0]} />
+          {pillars.map(p => (
+            <>
+              <Mesh geometry={pillar(p.height)} material={stone} position={p.position} castShadow />
+              {p.ball ? <Mesh geometry={orb} material={ball} position={[p.position[0], p.height + 0.9, p.position[2]]} castShadow /> : null}
+            </>
+          ))}
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/instanced.tsx

@@ -117,19 +117,19 @@ function App() {
 
   return (
     <window>
-      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
         <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.08, 0.1, 1]} label="instanced">
           <PerspectiveCamera fov={55} position={[0, 3.2, 5.4]} lookAt={[0, 0.2, 0]} />
-          <Mesh geometry={plane(9, 9, "meadow")} material={unlit({ color: [0.16, 0.18, 0.16] })} rotation={[-Math.PI / 2, 0, 0]} />
+          <Mesh geometry={plane({ width: 9, height: 9, label: "meadow" })} material={unlit({ color: [0.16, 0.18, 0.16] })} rotation={[-Math.PI / 2, 0, 0]} />
           <Group rotation={[0, spin(), 0]}>
             <InstancedMesh
-              geometry={box(1, 1, 1, "rock")}
+              geometry={box({ label: "rock" })}
               material={instancedLook.instance()}
               records={rocks(400)}
               bounds={[-3.9, 0, -3.9, 3.9, 0.2, 3.9]}
             />
             <InstancedMesh
-              geometry={cone(0.3, 1, 10, "pine")}
+              geometry={cone({ radius: 0.3, height: 1, radialSegments: 10, label: "pine" })}
               material={instancedLook.instance()}
               records={pines(PINE_COUNT)}
               bounds={[-2.8, 0, -2.8, 2.8, 0.8, 2.8]}

package/examples/lit.tsx

@@ -0,0 +1,66 @@
+// The lit material and the scene's lights. lit() is the standard look -
+// hemisphere ambient, the scene's directional lights, Lambert diffuse,
+// optional Blinn-Phong highlight - with the same color/map/transparent
+// options as unlit. Lights are NODES: <HemisphereLight> plus up to four
+// <DirectionalLight>s, here a warm key inside a spinning <Group> (a
+// parent's rotation turns the light, no per-frame direction math) and a
+// fixed cool fill; however many meshes, a light change is one shared
+// uniform write. The three boxes share one checker map: the
+// UV-mapped one stretches it per face (every generator emits 0..1 UVs),
+// the two triplanar ones tile it at one world density whatever their
+// size - the reason triplanar is an option on lit.
+
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { createTexture } from "@solidrt/core/gpu"
+import { box, DirectionalLight, Group, HemisphereLight, lit, Mesh, PerspectiveCamera, Scene, sphere, torusKnot, plane } from "@solidrt/3d"
+
+const SIZE = 720
+
+function checker(): ReturnType<typeof createTexture> {
+  let n = 64
+  let data = new Uint8Array(n * n * 4)
+  for (let y = 0; y < n; y++) {
+    for (let x = 0; x < n; x++) {
+      let v = ((x >> 3) + (y >> 3)) & 1 ? 235 : 120
+      data.set([v, v, v, 255], (y * n + x) * 4)
+    }
+  }
+  return createTexture(data, n, n, { wrap: "repeat", mipmap: true })
+}
+
+function App() {
+  let [t, setT] = createSignal(0)
+  onFrame(tick => setT(tick / 1000))
+
+  let map = checker()
+  let uvMapped = lit({ map })
+  let tiled = lit({ map, triplanar: 2 })
+  let glossy = lit({ color: [0.85, 0.3, 0.25], specular: 0.6, shininess: 60 })
+  let matte = lit({ color: [0.3, 0.55, 0.85] })
+  let glass = lit({ color: [0.9, 0.95, 1, 0.35], specular: 1, shininess: 120, transparent: true })
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.07, 0.1, 1]} samples={4} label="lit">
+          <PerspectiveCamera fov={50} position={[0, 2.6, 5]} lookAt={[0, 0.4, 0]} />
+          <HemisphereLight sky={[0.35, 0.38, 0.45]} ground={[0.12, 0.1, 0.08]} />
+          <Group rotation={[0, t(), 0]}>
+            <DirectionalLight direction={[0.7, -0.8, 0]} color={[1, 0.92, 0.8]} intensity={0.9} />
+          </Group>
+          <DirectionalLight direction={[0.6, -0.3, 0.5]} color={[0.4, 0.5, 0.8]} intensity={0.35} />
+          <Mesh geometry={plane({ width: 8, height: 8 })} material={tiled} rotation={[-Math.PI / 2, 0, 0]} />
+          <Group rotation={[0, t() / 4, 0]}>
+            <Mesh geometry={box({ width: 0.8, height: 0.8, depth: 0.8 })} material={uvMapped} position={[-1.6, 0.4, 0]} />
+            <Mesh geometry={box({ width: 1.6, height: 0.5, depth: 0.8 })} material={tiled} position={[0, 0.25, 1.2]} />
+            <Mesh geometry={sphere({ radius: 0.5 })} material={glossy} position={[1.5, 0.5, 0]} />
+            <Mesh geometry={torusKnot({ radius: 0.35, tube: 0.12 })} material={matte} position={[0, 0.9, -1]} />
+            <Mesh geometry={sphere({ radius: 0.45 })} material={glass} position={[0, 0.45, 0]} />
+          </Group>
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/model.tsx

@@ -0,0 +1,51 @@
+// A model from a file: model.glb (a small authored scene - a rover with a
+// node tree of nested transforms, a mirrored node, a textured material, a
+// transparent dome and a mesh shipped without normals) parsed at runtime
+// with parseGltf and turned into a Group of meshes by createModel. The
+// glb rides in the bundle as a binary import; a model under assets/ goes
+// through loadGltf (same parser, read with flux:fs) or, baked once with
+// `srt tool 3d/model`, through loadModel (no parsing at all). Every part
+// keeps its node name and is an ordinary mesh: pointer events, transforms
+// and materials work per part.
+
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { add, createModel, DirectionalLight, Group, HemisphereLight, parseGltf, PerspectiveCamera, Scene, setVisible } from "@solidrt/3d"
+import type { SceneNode } from "@solidrt/3d"
+import modelBytes from "./model.glb" with { type: "binary" }
+
+const SIZE = 720
+
+function App() {
+  let [t, setT] = createSignal(0)
+  onFrame(tick => setT(tick / 1000))
+
+  // Parse + upload once; the model is plain scene data from here on.
+  let model = createModel(parseGltf(modelBytes), { label: "rover" })
+  let b = model.bounds
+  let center: [number, number, number] = [(b[0]! + b[3]!) / 2, (b[1]! + b[4]!) / 2, (b[2]! + b[5]!) / 2]
+  let radius = Math.hypot(b[3]! - b[0]!, b[4]! - b[1]!, b[5]! - b[2]!) / 2
+
+  // Parts are named after the glTF nodes: a click hides that part, a
+  // click on the body brings everything back.
+  for (let part of model.parts) {
+    part.mesh.onPointerDown = () => {
+      if (part.name === "body") for (let p of model.parts) setVisible(p.mesh, true)
+      else setVisible(part.mesh, false)
+    }
+  }
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.1, 0.11, 0.14, 1]} samples={4} label="model">
+          <PerspectiveCamera fov={40} position={[center[0] + radius * 1.4, center[1] + radius * 1.1, center[2] + radius * 2.2]} lookAt={center} />
+          <HemisphereLight sky={[0.45, 0.5, 0.6]} ground={[0.2, 0.17, 0.14]} />
+          <DirectionalLight direction={[0.5, -0.8, 0.3]} color={[1, 0.95, 0.85]} intensity={0.9} />
+          <Group rotation={[0, t() / 3, 0]} ref={(g: SceneNode) => add(g, model)} />
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/pick.tsx

@@ -62,15 +62,15 @@ function Pickable(p: { name: string; color: Color; geometry: Geometry; position:
 }
 
 function App() {
-  let floor = plane(8, 8, "floor")
+  let floor = plane({ width: 8, height: 8, label: "floor" })
   let crate = box()
-  let ball = sphere(0.45)
-  let spike = cone(0.45, 1)
-  let ring = torus(0.4, 0.14)
+  let ball = sphere({ radius: 0.45 })
+  let spike = cone({ radius: 0.45, height: 1 })
+  let ring = torus({ radius: 0.4, tube: 0.14 })
 
   return (
     <window>
-      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
         <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.07, 0.1, 1]} label="pick">
           <PerspectiveCamera fov={55} position={[0, 2.6, 5]} lookAt={[0, 0.4, 0]} />
           <Mesh geometry={floor} material={unlit({ color: [0.15, 0.16, 0.2] })} rotation={[-Math.PI / 2, 0, 0]} />

package/examples/scene-background.tsx

@@ -28,12 +28,12 @@ let BACKDROP = glsl`
 function App() {
   return (
     <window>
-      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
         <Scene width={SIZE} height={SIZE} background={BACKDROP} label="backdrop-demo">
           <PerspectiveCamera fov={55} position={[0, 1.8, 4.4]} lookAt={[0, 0.4, 0]} />
-          <Mesh geometry={torusKnot(0.7, 0.2, 128, 16)} material={unlit({ color: [0.85, 0.55, 0.25] })} position={[0, 0.9, 0]} />
+          <Mesh geometry={torusKnot({ radius: 0.7, tube: 0.2, tubularSegments: 128, radialSegments: 16 })} material={unlit({ color: [0.85, 0.55, 0.25] })} position={[0, 0.9, 0]} />
           <Mesh geometry={box()} material={unlit({ color: [0.3, 0.5, 0.8] })} position={[-1.5, 0.4, -0.5]} scale={0.8} />
-          <Mesh geometry={sphere(0.4)} material={unlit({ color: [0.4, 0.75, 0.45] })} position={[1.5, 0.4, -0.5]} />
+          <Mesh geometry={sphere({ radius: 0.4 })} material={unlit({ color: [0.4, 0.75, 0.45] })} position={[1.5, 0.4, -0.5]} />
         </Scene>
       </view>
     </window>

package/examples/scene-basic.tsx

@@ -21,12 +21,12 @@ function App() {
   // use one cube geometry (one vertex/index buffer pair on the GPU), and
   // every mesh here shares the one unlit-color pipeline.
   let cube = box()
-  let floor = plane(6, 6, "floor")
-  let ball = sphere(0.35)
+  let floor = plane({ width: 6, height: 6, label: "floor" })
+  let ball = sphere({ radius: 0.35 })
 
   return (
     <window>
-      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
         <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.07, 0.1, 1]} label="scene-basic">
           <PerspectiveCamera fov={55} position={[0, 1.6, 3.6]} lookAt={[0, 0.3, 0]} />
           <Mesh

package/examples/scene-post-effect.tsx

@@ -39,12 +39,12 @@ function App() {
   onFrame(tick => setSpin(tick / 2000))
 
   let cube = box()
-  let floor = plane(6, 6, "floor")
-  let ball = sphere(0.35)
+  let floor = plane({ width: 6, height: 6, label: "floor" })
+  let ball = sphere({ radius: 0.35 })
 
   return (
     <window>
-      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
         <Scene
           width={RENDER}
           height={RENDER}

package/examples/scene-views.tsx

@@ -0,0 +1,95 @@
+// One scene, three renderings: the built-in leaf from a perspective
+// camera, plus two `scene.createView` targets - a top-down ORTHOGRAPHIC
+// map (`ortho` on setCamera) and a side silhouette drawn with an
+// `overrideMaterial`. The group spins from ONE signal: each mesh is one
+// core node whose flush writes its world matrix into every target's entry
+// at once, so the extra views cost the app nothing per frame (and the
+// light set fans out to them too - the map is lit like the main view).
+// Views die with the scene.
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { box, DirectionalLight, Group, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, Scene, sphere, unlit } from "@solidrt/3d"
+import type { SceneHandle } from "@solidrt/3d"
+
+const MAIN = 720
+const SIDE = 360
+
+function App() {
+  let [spin, setSpin] = createSignal(0)
+  onFrame(tick => setSpin(tick / 2000))
+
+  let cube = box()
+  let floor = plane({ width: 6, height: 6, label: "floor" })
+  let ball = sphere({ radius: 0.35 })
+  // `ref` runs before `output`, so the handle is set when the views are
+  // created there; both callbacks run once, untracked - no signals needed.
+  let scene!: SceneHandle
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} designSize={[MAIN + SIDE, MAIN]}>
+        <Scene
+          width={MAIN}
+          height={MAIN}
+          clearColor={[0.07, 0.07, 0.1, 1]}
+          label="scene-views"
+          ref={s => (scene = s)}
+          output={tex => {
+            // The map: straight down from y = 10, world -z toward the top of
+            // the leaf, seven world units across at any depth.
+            let map = scene.createView({ width: SIDE, height: SIDE, clearColor: [0.05, 0.08, 0.06, 1], label: "map" })
+            map.setCamera({
+              position: [0, 10, 0],
+              target: [0, 0, 0],
+              up: [0, 0, -1],
+              ortho: { left: -3.5, right: 3.5, top: 3.5, bottom: -3.5 },
+              near: 0.1,
+              far: 20,
+            })
+            // The silhouette: every mesh drawn flat amber, from the side. The
+            // floor is edge-on here, a single line at the bottom.
+            let side = scene.createView({
+              width: SIDE,
+              height: SIDE,
+              clearColor: [0.1, 0.06, 0.05, 1],
+              overrideMaterial: unlit({ color: [0.95, 0.75, 0.3] }),
+              label: "silhouette",
+            })
+            side.setCamera({
+              position: [6, 1, 0],
+              target: [0, 0.6, 0],
+              ortho: { left: -2.4, right: 2.4, top: 2.4, bottom: -2.4 },
+              near: 0.1,
+              far: 20,
+            })
+            return (
+              <view flexDirection="row" width={MAIN + SIDE} height={MAIN}>
+                <texture src={tex} width={MAIN} height={MAIN} />
+                <view flexDirection="column" width={SIDE} height={MAIN}>
+                  <texture src={map.texture} width={SIDE} height={SIDE} />
+                  <texture src={side.texture} width={SIDE} height={SIDE} />
+                </view>
+              </view>
+            )
+          }}
+        >
+          <PerspectiveCamera fov={55} position={[0, 1.6, 3.6]} lookAt={[0, 0.3, 0]} />
+          <HemisphereLight sky={[0.6, 0.7, 0.9]} ground={[0.25, 0.2, 0.15]} intensity={0.6} />
+          <DirectionalLight direction={[-0.5, -1, -0.3]} color={[1, 0.95, 0.85]} intensity={0.9} />
+          <Mesh geometry={floor} material={lit({ color: [0.3, 0.32, 0.38] })} rotation={[-Math.PI / 2, 0, 0]} />
+          <Group rotation={[0, spin(), 0]}>
+            <Mesh geometry={cube} material={lit({ color: [0.85, 0.3, 0.3] })} position={[0, 0.5, 0]} />
+            <Mesh
+              geometry={cube}
+              material={lit({ color: [0.9, 0.8, 0.35] })}
+              position={[-1.1, 0.7, 0]}
+              scale={[0.5, 1.4, 0.5]}
+            />
+            <Mesh geometry={ball} material={lit({ color: [0.35, 0.65, 0.9] })} position={[1.1, 0.35, 0]} />
+          </Group>
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/shadows.tsx

@@ -0,0 +1,86 @@
+// Directional shadow maps: three `castShadow` lights, `castShadow` meshes
+// and `lit` materials, which receive shadows by default. The warm sun
+// swings through its arc from onFrame - ONE setTransform on the light
+// node per frame; the scene re-places its shadow camera from the light's
+// world matrix, so its shadows sweep across the ground while the casters
+// turn inside their group. A cool fill from the opposite side and a low
+// rim light stand still, so every caster throws three shadows that cross
+// as the sun moves (each casting light is its own map and pass, capped
+// by MAX_LIGHTS). Three's vocabulary throughout: `castShadow` on the
+// light and on meshes, `shadow.mapSize/bias/normalBias/camera` on the
+// light; the one divergence is that opting OUT of receiving is a material
+// option (`lit({ receiveShadow: false })`, Godot's split), because the
+// material picks the program (like vertexColors and triplanar).
+//
+// Placement matters for a casting light: its shadow camera sits at the
+// light's WORLD position looking along its direction, so the sun is
+// positioned above the scene (a light at the origin would shadow nothing
+// above it). The light frustum is `shadow.camera`, +-5 world units by
+// default - anything outside it is lit.
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { box, cylinder, DirectionalLight, Group, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, Scene, setTransform, sphere, torusKnot } from "@solidrt/3d"
+import type { DirectionalLightNode } from "@solidrt/3d"
+
+const SIZE = 720
+
+function App() {
+  let [t, setT] = createSignal(0)
+  let sun!: DirectionalLightNode
+  onFrame(tick => {
+    setT(tick / 1000)
+    // The sun's arc: east to west over the scene, always pointing at the
+    // origin. The direction is the node's local -y, so aiming is a
+    // rotation about z; the position rides the same arc so the shadow
+    // camera stays above the casters.
+    let a = Math.sin(tick / 4000) * 1.0
+    setTransform(sun, { position: [Math.sin(a) * 6, Math.cos(a) * 6, 2], rotation: [0.32, 0, -a] })
+  })
+
+  let ground = lit({ color: [0.55, 0.58, 0.6] })
+  let red = lit({ color: [0.85, 0.3, 0.25] })
+  let blue = lit({ color: [0.3, 0.55, 0.85] })
+  let gold = lit({ color: [0.9, 0.75, 0.3], specular: 0.5, shininess: 40 })
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.55, 0.65, 0.8, 1]} samples={4} label="shadows">
+          <PerspectiveCamera fov={45} position={[0, 4, 7]} lookAt={[0, 0.5, 0]} />
+          <HemisphereLight sky={[0.45, 0.5, 0.6]} ground={[0.2, 0.18, 0.15]} />
+          <DirectionalLight
+            ref={l => (sun = l)}
+            color={[1, 0.95, 0.85]}
+            intensity={0.8}
+            castShadow
+            shadow={{ mapSize: 1024, normalBias: 0.02, camera: { near: 1, far: 20 } }}
+          />
+          <DirectionalLight
+            color={[0.45, 0.6, 0.9]}
+            intensity={0.5}
+            position={[-5, 5, -4]}
+            direction={[5, -5, 4]}
+            castShadow
+            shadow={{ normalBias: 0.02, camera: { near: 1, far: 20 } }}
+          />
+          <DirectionalLight
+            color={[0.9, 0.5, 0.35]}
+            intensity={0.45}
+            position={[5, 2, -5]}
+            direction={[-5, -2, 5]}
+            castShadow
+            shadow={{ mapSize: 512, normalBias: 0.03, camera: { near: 1, far: 20 } }}
+          />
+          <Mesh geometry={plane({ width: 10, height: 10 })} material={ground} rotation={[-Math.PI / 2, 0, 0]} />
+          <Group rotation={[0, t() / 3, 0]}>
+            <Mesh geometry={box({ width: 1, height: 1, depth: 1 })} material={red} position={[-1.6, 0.5, 0]} castShadow />
+            <Mesh geometry={sphere({ radius: 0.6 })} material={blue} position={[1.5, 0.6, 0]} castShadow />
+            <Mesh geometry={torusKnot({ radius: 0.4, tube: 0.14 })} material={gold} position={[0, 1.3, 0]} castShadow />
+            <Mesh geometry={cylinder({ radiusTop: 0.12, radiusBottom: 0.12, height: 1.6 })} material={gold} position={[0, 0.8, 0]} castShadow />
+          </Group>
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)