@solidrt/3d 0.0.58 → 0.0.60

package/examples/normals.tsx

@@ -0,0 +1,118 @@
+// Normals as data. Three cylinders from ONE triangle soup (a cylinder
+// split by toNonIndexed, every face its own vertices - the shape an STL
+// or a hand-written face list arrives in) shaded by withNormals at three
+// crease angles: 0 is flat, the default 60 finds the rims and smooths the
+// side, 180 blends the rims away. The result is indexed again -
+// mergeVertices welds the corners back wherever a crease or a seam does
+// not need them apart - so each costs what the generator's own cylinder
+// costs. The sphere is the CPU deformation loop: fillAttribute moves its
+// positions, computeVertexNormals recomputes its normals in place (the
+// math runs in the core, one call), updateVertices re-uploads. Its normal
+// lines are refreshed the same way, in place, from the sphere's data. The
+// loop is here to be seen; a ripple like this one belongs in a vertex
+// shader in a real app, where the CPU touches no vertex at all - the loop
+// is for data that genuinely changes on the CPU.
+// normalsHelper draws every vertex normal as a line: a crease is a fan of
+// lines from one position, a smooth vertex one line. Space or the
+// `helpers` debug command ({ on?: boolean }) toggles them.
+
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { registerDebug } from "srt:dev"
+import { computeVertexNormals, cylinder, DirectionalLight, fillAttribute, geometryAttribute, geometryVertexCount, Group, HemisphereLight, phong, Mesh, normalsHelper, PerspectiveCamera, Scene, sphere, toNonIndexed, unlit, updateVertices, withNormals } from "@solidrt/3d"
+
+// The crease angles in degrees: flat, the default, everything smoothed.
+const ANGLES = [0, 60, 180] as const
+// Spacing between the three cylinders along x.
+const SPACING = 2.4
+// Tilt of the cylinders toward the camera, so their top rims show.
+const TILT = 0.5
+// Normal line length, a fraction of the unit shapes.
+const HELPER_SIZE = 0.2
+// Facets around the cylinders: few enough that flat shading reads as facets.
+const RADIAL_SEGMENTS = 16
+// The sphere ripple: radial amplitude, waves along y, radians per second.
+const RIPPLE_AMPLITUDE = 0.12
+const RIPPLE_WAVES = 5
+const RIPPLE_SPEED = 2
+const SHADE_COLOR: [number, number, number] = [0.85, 0.55, 0.3]
+const SPHERE_COLOR: [number, number, number] = [0.35, 0.6, 0.85]
+
+function App() {
+  let [t, setT] = createSignal(0)
+  let [helpers, setHelpers] = createSignal(true)
+  let toggle = (): void => {
+    setHelpers(v => !v)
+  }
+  registerDebug("helpers", (args?: Record<string, unknown>) => {
+    if (typeof args?.on === "boolean") setHelpers(args.on)
+    else toggle()
+  })
+
+  let soup = toNonIndexed(cylinder({ radialSegments: RADIAL_SEGMENTS }), "soup")
+  let shaded = ANGLES.map(angle => withNormals(soup, angle, "cylinder-" + angle))
+  let shade = phong({ color: SHADE_COLOR, specular: 0.5, shininess: 40 })
+  let lines = unlit({ vertexColors: true })
+
+  // The rippling sphere. Base positions are kept aside: fillAttribute's
+  // callback sees the CURRENT position, and the ripple is a function of
+  // the rest shape.
+  let ball = sphere({ label: "ripple" })
+  let count = geometryVertexCount(ball, "normals example")
+  let pos = geometryAttribute(ball, "aPos")!
+  let nrm = geometryAttribute(ball, "aNormal")!
+  let base = new Float32Array(count * 3)
+  for (let i = 0; i < count; i++) {
+    base[i * 3] = pos.get(i, 0)
+    base[i * 3 + 1] = pos.get(i, 1)
+    base[i * 3 + 2] = pos.get(i, 2)
+  }
+  let ballLines = normalsHelper(ball, { size: HELPER_SIZE })
+  onFrame(tick => {
+    setT(tick / 1000)
+    let phase = (tick / 1000) * RIPPLE_SPEED
+    fillAttribute(ball, "aPos", i => {
+      let x = base[i * 3]!, y = base[i * 3 + 1]!, z = base[i * 3 + 2]!
+      let r = 1 + RIPPLE_AMPLITUDE * Math.sin(y * RIPPLE_WAVES * Math.PI + phase)
+      return [x * r, y * r, z * r]
+    })
+    computeVertexNormals(ball)
+    updateVertices(ball)
+    // The helper's line ends follow: vertex 2v is the sphere's vertex v,
+    // 2v + 1 its tip along the recomputed normal.
+    fillAttribute(ballLines, "aPos", i => {
+      let v = i >> 1
+      let x = pos.get(v, 0), y = pos.get(v, 1), z = pos.get(v, 2)
+      if ((i & 1) === 0) return [x, y, z]
+      return [x + nrm.get(v, 0) * HELPER_SIZE, y + nrm.get(v, 1) * HELPER_SIZE, z + nrm.get(v, 2) * HELPER_SIZE]
+    })
+    updateVertices(ballLines)
+  })
+
+  return (
+    <window
+      onKeyDown={e => {
+        if (e.key === " ") toggle()
+      }}
+    >
+      <view width={pct(100)} height={pct(100)}>
+        <Scene clearColor={[0.1, 0.11, 0.14, 1]} samples={4} label="normals">
+          <PerspectiveCamera fov={40} position={[0, 1.6, 8.5]} lookAt={[0, 0, 0]} />
+          <HemisphereLight sky={[0.35, 0.38, 0.45]} ground={[0.12, 0.1, 0.08]} />
+          <DirectionalLight direction={[0.4, -0.7, -0.6]} color={[1, 0.95, 0.85]} intensity={0.9} />
+          {shaded.map((geometry, i) => (
+            <Group position={[(i - 1) * SPACING, 1.1, 0]} rotation={[TILT, t() / 3, 0]}>
+              <Mesh geometry={geometry} material={shade} />
+              <Mesh geometry={normalsHelper(geometry, { size: HELPER_SIZE })} material={lines} visible={helpers()} />
+            </Group>
+          ))}
+          <Group position={[0, -1.3, 0]}>
+            <Mesh geometry={ball} material={phong({ color: SPHERE_COLOR, specular: 0.4, shininess: 30 })} />
+            <Mesh geometry={ballLines} material={lines} visible={helpers()} />
+          </Group>
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/{lit.tsx → phong.tsx}

@@ -1,4 +1,4 @@
-// The lit material and the scene's lights. lit() is the standard look -
+// The Blinn-Phong material and the scene's lights. phong() is the stock lit 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
@@ -8,11 +8,11 @@
 // 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.
+// size - the reason triplanar is an option on phong.
 
 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"
+import { box, DirectionalLight, Group, HemisphereLight, phong, Mesh, PerspectiveCamera, Scene, sphere, torusKnot, plane } from "@solidrt/3d"
 
 function checker(): ReturnType<typeof createTexture> {
   let n = 64
@@ -31,16 +31,16 @@ function App() {
   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 })
+  let uvMapped = phong({ map })
+  let tiled = phong({ map, triplanar: 2 })
+  let glossy = phong({ color: [0.85, 0.3, 0.25], specular: 0.6, shininess: 60 })
+  let matte = phong({ color: [0.3, 0.55, 0.85] })
+  let glass = phong({ color: [0.9, 0.95, 1, 0.35], specular: 1, shininess: 120, transparent: true })
 
   return (
     <window>
       <view width={pct(100)} height={pct(100)}>
-        <Scene clearColor={[0.07, 0.07, 0.1, 1]} samples={4} label="lit">
+        <Scene clearColor={[0.07, 0.07, 0.1, 1]} samples={4} label="phong">
           <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]}>

package/examples/polyhedra.tsx

@@ -0,0 +1,61 @@
+// The polyhedron family beside the lat/long sphere. Back row, flat-shaded
+// (detail 0 keeps face normals): tetrahedron, octahedron, dodecahedron and
+// icosahedron turning under the lights, so the facets catch the key one
+// after another. Middle row, the icosahedron at detail 1, 2 and 3: the
+// same builder, now a sphere of uniform triangles with radial normals -
+// the icosphere. Front row, the two triangulations as wireframes at a
+// matching triangle count: sphere({ widthSegments: 12, heightSegments: 8 })
+// bunches slivers at its poles where icosahedron({ detail: 2 }) spreads
+// its triangles evenly, which is what makes the icosphere the better
+// sphere for flat shading and displacement. The textured sphere stays
+// sphere(): the polyhedra's spherical UVs stretch toward the poles.
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { DirectionalLight, dodecahedron, Group, HemisphereLight, icosahedron, phong, Mesh, octahedron, PerspectiveCamera, plane, Scene, sphere, tetrahedron, unlit, wireframeGeometry } from "@solidrt/3d"
+
+// One circumsphere radius for every solid, so the rows read at one scale.
+const RADIUS = 0.45
+// Row depths, back to front, and the column pitch.
+const BACK = -2.1
+const MIDDLE = 0
+const FRONT = 2
+const PITCH = 1.6
+
+function App() {
+  let [t, setT] = createSignal(0)
+  onFrame(tick => setT(tick / 1000))
+
+  let red = phong({ color: [0.85, 0.3, 0.25] })
+  let amber = phong({ color: [0.9, 0.7, 0.3] })
+  let green = phong({ color: [0.4, 0.75, 0.4] })
+  let blue = phong({ color: [0.35, 0.55, 0.9] })
+  let ivory = phong({ color: [0.85, 0.82, 0.75], specular: 0.4, shininess: 40 })
+  let wire = unlit({ color: [0.9, 0.9, 0.95] })
+  let floor = phong({ color: [0.16, 0.17, 0.22] })
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)}>
+        <Scene clearColor={[0.07, 0.07, 0.1, 1]} samples={4} label="polyhedra">
+          <PerspectiveCamera fov={45} position={[0, 4.6, 6.8]} lookAt={[0, 0.1, 0]} />
+          <HemisphereLight sky={[0.35, 0.38, 0.45]} ground={[0.12, 0.1, 0.08]} />
+          <Group rotation={[0, t() / 3, 0]}>
+            <DirectionalLight direction={[0.7, -0.8, 0.2]} 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: 10, height: 8 })} material={floor} rotation={[-Math.PI / 2, 0, 0]} />
+          <Mesh geometry={tetrahedron({ radius: RADIUS })} material={red} position={[-1.5 * PITCH, RADIUS, BACK]} rotation={[0, t(), 0]} />
+          <Mesh geometry={octahedron({ radius: RADIUS })} material={amber} position={[-0.5 * PITCH, RADIUS, BACK]} rotation={[0, t(), 0]} />
+          <Mesh geometry={dodecahedron({ radius: RADIUS })} material={green} position={[0.5 * PITCH, RADIUS, BACK]} rotation={[0, t(), 0]} />
+          <Mesh geometry={icosahedron({ radius: RADIUS })} material={blue} position={[1.5 * PITCH, RADIUS, BACK]} rotation={[0, t(), 0]} />
+          <Mesh geometry={icosahedron({ radius: RADIUS, detail: 1 })} material={ivory} position={[-PITCH, RADIUS, MIDDLE]} />
+          <Mesh geometry={icosahedron({ radius: RADIUS, detail: 2 })} material={ivory} position={[0, RADIUS, MIDDLE]} />
+          <Mesh geometry={icosahedron({ radius: RADIUS, detail: 3 })} material={ivory} position={[PITCH, RADIUS, MIDDLE]} />
+          <Mesh geometry={wireframeGeometry(sphere({ radius: RADIUS, widthSegments: 12, heightSegments: 8 }))} material={wire} position={[-0.5 * PITCH, RADIUS, FRONT]} rotation={[0, t() / 2, 0]} />
+          <Mesh geometry={wireframeGeometry(icosahedron({ radius: RADIUS, detail: 2 }))} material={wire} position={[0.5 * PITCH, RADIUS, FRONT]} rotation={[0, t() / 2, 0]} />
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/scene-atlas.tsx

@@ -0,0 +1,70 @@
+// Tiled views into one atlas, resolved once by the app. Four `<View3d>`
+// render `into` an app-owned draw target (one pass for all four, the
+// atlas carrying depth and the buffer format), each from its own camera.
+// A tile holds LINEAR light like every buffer, so the atlas is displayed
+// through a resolve pass of the app's own: `resolveFragment()` (the
+// stock resolve source with `uScene` and the RESOLVE set declared) over a
+// `createShaderTexture` sampling the atlas, `resolveParams` writing its
+// exposure and tone mapping. The scene's own target draws nothing here
+// (layer mask 0, no leaf): the tiles are the picture. Godot's SubViewport
+// atlas and Unity's camera stacking into one render texture, resolved
+// where the runtime displays it.
+
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { createDrawTarget, createShaderTexture } from "@solidrt/core/gpu"
+import { box, bufferFormat, cone, DirectionalLight, Group, HemisphereLight, phong, Mesh, plane, resolveParams, Scene, sphere, View3d } from "@solidrt/3d"
+import { resolveFragment } from "@solidrt/3d/glsl"
+
+// The atlas: two by two tiles.
+const TILE_W = 480
+const TILE_H = 270
+const ATLAS_W = TILE_W * 2
+const ATLAS_H = TILE_H * 2
+// Each tile's backdrop: a view clears its own rectangle, so the color
+// goes on the views (an sRGB color like a scene's clearColor, decoded by
+// the library), not on the atlas.
+const CLEAR: [number, number, number, number] = [0.12, 0.14, 0.2, 1]
+// Where the four cameras stand: a quarter turn apart around the group.
+const ORBIT_RADIUS = 6
+const ORBIT_HEIGHT = 2.5
+
+function App() {
+  let [spin, setSpin] = createSignal(0)
+  onFrame(tick => setSpin(tick / 2000))
+  let atlas = createDrawTarget(ATLAS_W, ATLAS_H, null, { depth: true, format: bufferFormat(), label: "atlas" })
+  // The app's resolve: the whole atlas in one pass, the display pixels.
+  let resolved = createShaderTexture(resolveFragment(), ATLAS_W, ATLAS_H, resolveParams({ toneMapping: "aces" }), {
+    textures: { uScene: atlas },
+    label: "atlas-resolve",
+  })
+  let floor = plane({ width: 8, height: 8 })
+  let tiles = [0, 1, 2, 3].map(i => {
+    let angle = (i * Math.PI) / 2
+    return {
+      x: (i % 2) * TILE_W,
+      y: Math.floor(i / 2) * TILE_H,
+      camera: { position: [Math.sin(angle) * ORBIT_RADIUS, ORBIT_HEIGHT, Math.cos(angle) * ORBIT_RADIUS] as [number, number, number], target: [0, 0.5, 0] as [number, number, number] },
+    }
+  })
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} designSize={[ATLAS_W, ATLAS_H]}>
+        <Scene width={TILE_W} height={TILE_H} layers={0} label="atlas-scene" output={() => <texture src={resolved} width={ATLAS_W} height={ATLAS_H} />}>
+          <HemisphereLight sky={[0.6, 0.7, 0.9]} ground={[0.25, 0.2, 0.15]} intensity={0.7} />
+          <DirectionalLight direction={[-1, -2, -1]} intensity={1.2} />
+          <Mesh geometry={floor} material={phong({ color: [0.55, 0.55, 0.5] })} rotation={[-Math.PI / 2, 0, 0]} />
+          <Group rotation={[0, spin(), 0]}>
+            <Mesh geometry={box()} material={phong({ color: [0.85, 0.3, 0.3] })} position={[1.2, 0.5, 0]} />
+            <Mesh geometry={sphere({ radius: 0.5 })} material={phong({ color: [0.3, 0.6, 0.9], specular: 0.5, shininess: 40 })} position={[-1.2, 0.5, 0]} />
+            <Mesh geometry={cone({ radius: 0.5, height: 1.2 })} material={phong({ color: [0.9, 0.8, 0.3] })} position={[0, 0.6, 1.4]} />
+          </Group>
+          {tiles.map(t => (
+            <View3d width={TILE_W} height={TILE_H} into={atlas} x={t.x} y={t.y} clearColor={CLEAR} camera={t.camera} output={() => null} />
+          ))}
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/scene-views.tsx

@@ -15,7 +15,7 @@
 // map keeps the top-down view clear (its fog names are view-owned, so
 // scene-wide fog writes never clobber them).
 import { createSignal, onFrame, pct, render } from "@solidrt/core"
-import { box, circle, DirectionalLight, Group, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, Scene, sphere, unlit, View3d } from "@solidrt/3d"
+import { box, circle, DirectionalLight, Group, HemisphereLight, phong, Mesh, PerspectiveCamera, plane, Scene, sphere, unlit, View3d } from "@solidrt/3d"
 
 // Layer bits: the world everything defaults to, and the map-only markers.
 const WORLD_LAYER = 1
@@ -46,16 +46,16 @@ function App() {
           <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]} />
+          <Mesh geometry={floor} material={phong({ 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={phong({ color: [0.85, 0.3, 0.3] })} position={[0, 0.5, 0]} />
             <Mesh
               geometry={cube}
-              material={lit({ color: [0.9, 0.8, 0.35] })}
+              material={phong({ 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]} />
+            <Mesh geometry={ball} material={phong({ color: [0.35, 0.65, 0.9] })} position={[1.1, 0.35, 0]} />
             {/* The ball's map marker: drawn by the map view alone. */}
             <Mesh
               geometry={marker}

package/examples/shadows.tsx

@@ -1,15 +1,15 @@
 // Directional shadow maps: three `castShadow` lights, `castShadow` meshes
-// and `lit` materials, which receive shadows by default. The warm sun
+// and `phong` 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
+// as the sun moves (each casting light claims its tiles of the scene's
+// atlas from the MAX_SHADOW_MAPS budget). 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
+// option (`phong({ 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
@@ -18,7 +18,7 @@
 // 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 { box, cylinder, DirectionalLight, Group, HemisphereLight, phong, Mesh, PerspectiveCamera, plane, Scene, setTransform, sphere, torusKnot } from "@solidrt/3d"
 import type { DirectionalLightNode } from "@solidrt/3d"
 
 function App() {
@@ -34,10 +34,10 @@ function App() {
     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 })
+  let ground = phong({ color: [0.55, 0.58, 0.6] })
+  let red = phong({ color: [0.85, 0.3, 0.25] })
+  let blue = phong({ color: [0.3, 0.55, 0.85] })
+  let gold = phong({ color: [0.9, 0.75, 0.3], specular: 0.5, shininess: 40 })
 
   return (
     <window>

package/examples/sky-lit.tsx

@@ -30,8 +30,8 @@ const SUN: Vec3 = normalize([0.6, 0.5, 0.6])
 const BAKE_SIZE = 128
 
 // Horizon gradient (zenith blue to a pale horizon, a dark ground), a sun
-// disc with a glow. Linear colors in, the output stage encodes for the
-// screen and leaves them linear for the bake.
+// disc with a glow, written as linear light: the scene's resolve exposes,
+// tone maps and encodes it for the screen, and the bake stores it as is.
 const SKY = glsl`
   uniform vec3 uSunDir;
   // Cosine of the disc's angular radius (about 2 degrees), the glow's
@@ -50,7 +50,7 @@ const SKY = glsl`
     float s = max(dot(d, uSunDir), 0.0);
     col += vec3(1.0, 0.85, 0.6) * pow(s, SUN_GLOW) * 0.6;
     if (s > SUN_DISC) col = vec3(1.0, 0.87, 0.67) * SUN_RADIANCE;
-    fragColor = outputColor(col, 1.0);
+    fragColor = vec4(col, 1.0);
   }
 `
 

package/examples/skybox.tsx

@@ -13,7 +13,7 @@
 // place, no recompile. Drag to look around, wheel to zoom.
 import { createInputMap, createPointerFeed, createSignal, gamepad, onFrame, pct, render } from "@solidrt/core"
 import { createCubeTexture } from "@solidrt/core/gpu"
-import { box, DirectionalLight, HemisphereLight, lit, Mesh, OrbitCamera, orbitActions, orbitBindings, plane, Scene, sphere, torusKnot } from "@solidrt/3d"
+import { box, DirectionalLight, HemisphereLight, phong, Mesh, OrbitCamera, orbitActions, orbitBindings, plane, Scene, sphere, torusKnot } from "@solidrt/3d"
 import { normalize } from "@solidrt/3d/math"
 import type { Vec3 } from "@solidrt/3d/math"
 
@@ -107,13 +107,13 @@ function App() {
   })
   let sun = () => turnedSun(turn())
 
-  let ground = lit({ color: [0.36, 0.4, 0.3] })
+  let ground = phong({ color: [0.36, 0.4, 0.3] })
   // Glossy: a blurred reflection (shininess 48) at a dielectric's face-on
   // weight, rising toward the silhouette.
-  let brass = lit({ color: [0.85, 0.6, 0.3], specular: 0.6, shininess: 48, reflectivity: 0.15 })
-  let stone = lit({ color: [0.6, 0.6, 0.62] })
+  let brass = phong({ color: [0.85, 0.6, 0.3], specular: 0.6, shininess: 48, reflectivity: 0.15 })
+  let stone = phong({ color: [0.6, 0.6, 0.62] })
   // Chrome: the environment itself, sharp.
-  let chrome = lit({ color: [1, 1, 1], specular: 1, shininess: 400, reflectivity: 1 })
+  let chrome = phong({ color: [1, 1, 1], specular: 1, shininess: 400, reflectivity: 1 })
   return (
     <window>
       <view width={pct(100)} height={pct(100)}>

package/examples/standard.tsx

@@ -6,10 +6,10 @@
 // the base color and dark wherever the sky is; the dielectric row keeps
 // its diffuse color and shows the sky as a faint gloss, a mirror highlight
 // at the left that widens to the right and brightens toward every
-// silhouette; the rows between blend the two. standard takes lit's base,
+// silhouette; the rows between blend the two. standard takes phong's base,
 // maps, cutout, shadow, emissive and fog options - only the Blinn-Phong
 // knobs are gone, replaced by metalness/roughness and their packed maps.
-// Light intensities read as lit's: 1 lights a white matte surface to 1.
+// Light intensities read as phong's: 1 lights a white matte surface to 1.
 // Drag to look around.
 
 import { createInputMap, createPointerFeed, gamepad, pct, render } from "@solidrt/core"

package/examples/streams.tsx

@@ -0,0 +1,122 @@
+// Vertex streams and the draw range: a sphere whose surface heaves every
+// frame without its positions, normals or uvs ever re-uploading. The
+// displacement rides in a stream of its own - `withAttribute(..., {
+// stream: 1 })` opens a second vertex buffer holding one float per vertex
+// - and each frame writes that stream through the attribute accessor and
+// re-uploads it alone with updateVertices, Three's `needsUpdate` for one
+// BufferAttribute. The static channels stay in the buffer they were
+// uploaded to once; the pipeline reads both buffers.
+//
+// The wireframe over the same geometry shares every stream (and every GPU
+// upload) with the surface, so the one update moves both meshes.
+//
+// setDrawRange reveals the sphere: the mesh draws a growing slice of its
+// index list over the first seconds, then the whole of it - the same
+// buffers, only the range moving.
+import { onFrame, pct, render } from "@solidrt/core"
+import { glsl } from "@solidrt/core/gpu"
+import {
+  DirectionalLight,
+  geometryAttribute,
+  geometryVertexCount,
+  HemisphereLight,
+  Mesh,
+  PerspectiveCamera,
+  Scene,
+  setDrawRange,
+  shaderMaterialClass,
+  sphere,
+  updateVertices,
+  wireframeGeometry,
+  withAttribute,
+} from "@solidrt/3d"
+import type { MeshNode } from "@solidrt/3d"
+import { phongFragment } from "@solidrt/3d/glsl"
+
+// The lit varyings from a position pushed along its normal by the
+// per-vertex aWave, which the pipeline fetches from the second stream.
+const WAVE_VERTEX = glsl`
+  in vec3 aPos;
+  in vec3 aNormal;
+  in vec2 aUV;
+  in float aWave;
+  out vec3 vWorldPos;
+  out vec3 vNormal;
+  out vec2 vUv;
+  uniform mat4 uModel;
+  uniform mat4 uViewProj;
+  uniform mat4 uNormal;
+
+  void main() {
+    vec4 world = uModel * vec4(aPos + aNormal * aWave, 1.0);
+    gl_Position = uViewProj * world;
+    vWorldPos = world.xyz;
+    vNormal = mat3(uNormal) * aNormal;
+    vUv = aUV;
+  }
+`
+
+// The same displacement for the wireframe, drawn flat.
+const WAVE_LINE_VERTEX = glsl`
+  in vec3 aPos;
+  in vec3 aNormal;
+  in float aWave;
+  uniform mat4 uModel;
+  uniform mat4 uViewProj;
+
+  void main() {
+    gl_Position = uViewProj * uModel * vec4(aPos + aNormal * (aWave + 0.004), 1.0);
+  }
+`
+
+const LINE_FRAGMENT = glsl`
+  void main() {
+    fragColor = vec4(0.12, 0.16, 0.2, 1.0);
+  }
+`
+
+// Displacement amplitude in model units, and the seconds the reveal takes.
+const WAVE_HEIGHT = 0.06
+const REVEAL_SECONDS = 3
+
+let surfaceLook = shaderMaterialClass({ vertex: WAVE_VERTEX, fragment: phongFragment(), label: "wave-surface" })
+let lineLook = shaderMaterialClass({ vertex: WAVE_LINE_VERTEX, fragment: LINE_FRAGMENT, label: "wave-lines" })
+
+function App() {
+  // The sphere with its wave channel in stream 1: stream 0 keeps the
+  // generator's positions, normals and uvs untouched.
+  let ball = withAttribute(sphere({ radius: 1, widthSegments: 64, heightSegments: 40, label: "ball" }), { name: "aWave", format: "float32" }, () => [0], { stream: 1 })
+  let wave = geometryAttribute(ball, "aWave")!
+  let pos = geometryAttribute(ball, "aPos")!
+  let count = geometryVertexCount(ball, "streams")
+  let triangles = ball.indices.length / 3
+  let surface!: MeshNode
+  onFrame(tick => {
+    let t = tick / 1000
+    for (let i = 0; i < count; i++) {
+      let y = pos.get(i, 1)
+      let x = pos.get(i, 0)
+      wave.set(i, 0, WAVE_HEIGHT * Math.sin(y * 6 + t * 3) * Math.cos(x * 5 - t * 2))
+    }
+    // One write of the wave stream; the other buffers never move.
+    updateVertices(ball, { stream: 1 })
+    let shown = Math.min(triangles, Math.floor(triangles * Math.min(1, t / REVEAL_SECONDS)))
+    if (surface) setDrawRange(surface, 0, shown * 3)
+  })
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)}>
+        <Scene clearColor={[0.85, 0.87, 0.9, 1]} label="streams">
+          <PerspectiveCamera fov={45} position={[0, 1.4, 3.4]} lookAt={[0, 0, 0]} />
+          <HemisphereLight sky={[0.55, 0.58, 0.62]} ground={[0.25, 0.22, 0.2]} />
+          <DirectionalLight color={[1, 0.96, 0.9]} intensity={0.8} position={[3, 4, 2]} direction={[-3, -4, -2]} />
+          <Mesh geometry={ball} material={surfaceLook.instance({ params: { uColor: [0.9, 0.55, 0.3, 1], uSpecular: 0.3, uShininess: 40 } })} ref={m => (surface = m)} />
+          <Mesh geometry={wireframeGeometry(ball)} material={lineLook.instance()} />
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/sweep-paths.tsx

@@ -3,11 +3,11 @@
 // over the crate's edges like real webbing - while smooth-tagged points
 // share averaged normals, so the helix sweeps into ONE continuous coil
 // (per-segment boxes with unmitred gaps are exactly what this replaces).
-// tube() is the round-profile shorthand. lit() materials on purpose:
+// tube() is the round-profile shorthand. phong() materials on purpose:
 // creased vs smooth joints differ only in normals, which unlit color
 // would hide.
 import { createSignal, onFrame, pct, render } from "@solidrt/core"
-import { box, DirectionalLight, Group, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, roundRect, Scene, sweep, tube, unlit } from "@solidrt/3d"
+import { box, DirectionalLight, Group, HemisphereLight, phong, Mesh, PerspectiveCamera, plane, roundRect, Scene, sweep, tube, unlit } from "@solidrt/3d"
 import type { SweepPath } from "@solidrt/3d"
 
 function App() {
@@ -48,9 +48,9 @@ function App() {
             rotation={[-Math.PI / 2, 0, 0]}
           />
           <Group rotation={[0, spin(), 0]}>
-            <Mesh geometry={box({ width: 1, height: 0.6, depth: 0.8 })} material={lit({ color: [0.55, 0.42, 0.28] })} position={[-0.8, 0.3, 0]} />
-            <Mesh geometry={strap} material={lit({ color: [0.9, 0.55, 0.2] })} />
-            <Mesh geometry={coil} material={lit({ color: [0.45, 0.6, 0.8] })} />
+            <Mesh geometry={box({ width: 1, height: 0.6, depth: 0.8 })} material={phong({ color: [0.55, 0.42, 0.28] })} position={[-0.8, 0.3, 0]} />
+            <Mesh geometry={strap} material={phong({ color: [0.9, 0.55, 0.2] })} />
+            <Mesh geometry={coil} material={phong({ color: [0.45, 0.6, 0.8] })} />
           </Group>
         </Scene>
       </view>

package/examples/wireframe.tsx

@@ -8,12 +8,18 @@
 // The swap is setGeometry + setMaterial on the live mesh: the node, its
 // transform and its pointer handlers are untouched. Space, a tap on the
 // rover or the `wire` debug command ({ mode }) cycles the modes.
+//
+// Under the rover, the debug helpers: gridHelper on its floor and
+// axesHelper at the origin (world space, so they stand still while the
+// rover turns) and box3Helper around its bounds, turning with it. Lines
+// geometry too; the two colored ones draw through one
+// unlit({ vertexColors: true }) material.
 
 import { createSignal, onFrame, pct, render } from "@solidrt/core"
 import { createTexture } from "@solidrt/core/gpu"
 import type { TextureId } from "@solidrt/core/gpu"
 import { registerDebug } from "srt:dev"
-import { add, createModel, DirectionalLight, edgesGeometry, equirectToCube, Group, parseGltf, PerspectiveCamera, Scene, setGeometry, setMaterial, unlit, wireframeGeometry } from "@solidrt/3d"
+import { add, axesHelper, box3Helper, createModel, DirectionalLight, edgesGeometry, equirectToCube, gridHelper, Group, Mesh, parseGltf, PerspectiveCamera, Scene, setGeometry, setMaterial, unlit, wireframeGeometry } from "@solidrt/3d"
 import type { SceneNode } from "@solidrt/3d"
 import modelBytes from "./model.glb" with { type: "binary" }
 
@@ -23,6 +29,13 @@ type Mode = (typeof MODES)[number]
 // rounded parts, so their seams stay hidden and only rims and creases draw.
 const EDGE_ANGLE = 20
 const LINE_COLOR: [number, number, number] = [0.85, 0.95, 1]
+// The grid's subdivision lines and its two center lines, and the bounds
+// box (Three's Box3Helper yellow), against the dark clear color.
+const GRID_COLOR: [number, number, number] = [0.3, 0.33, 0.4]
+const GRID_CENTER_COLOR: [number, number, number] = [0.6, 0.66, 0.8]
+const BOUNDS_COLOR: [number, number, number] = [1, 1, 0]
+// Grid cells across the rover's floor.
+const GRID_DIVISIONS = 20
 // Face edge of the gradient environment cube: a gradient needs no detail.
 const ENV_FACE = 16
 // The gradient, zenith to nadir, sRGB bytes: sky, horizon, ground, below.
@@ -54,6 +67,11 @@ function App() {
   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
 
+  let helperLines = unlit({ vertexColors: true })
+  let grid = gridHelper({ size: radius * 4, divisions: GRID_DIVISIONS, color: GRID_COLOR, centerColor: GRID_CENTER_COLOR })
+  let axes = axesHelper({ size: radius })
+  let bounds = box3Helper(b)
+
   // One line material for every part and both line modes. Per part, what
   // each mode swaps in: the line geometries share the solid's vertices,
   // so building both up front costs their index buffers only.
@@ -97,7 +115,11 @@ function App() {
         <Scene clearColor={[0.1, 0.11, 0.14, 1]} environment={{ cube }} samples={4} label="wireframe">
           <PerspectiveCamera fov={40} position={[center[0] + radius * 1.4, center[1] + radius * 1.1, center[2] + radius * 2.2]} lookAt={center} />
           <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)} />
+          <Mesh geometry={grid} material={helperLines} position={[0, b[1]!, 0]} />
+          <Mesh geometry={axes} material={helperLines} />
+          <Group rotation={[0, t() / 3, 0]} ref={(g: SceneNode) => add(g, model)}>
+            <Mesh geometry={bounds} material={unlit({ color: BOUNDS_COLOR })} />
+          </Group>
         </Scene>
       </view>
     </window>