feat: shadowmap — wave-2 port (agent); fog rule corrected

maskNode discard casting, receivedShadowPositionNode shadow distortion,
animated spot/directional pair. Port verified that plain Fog objects are
auto-wrapped by NodeManager under WebGPU — AGENTS.md fog rule narrowed
(declarative <fog attach> preferred; scene.fogNode only for custom TSL fog).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: DennisSmolek

AGENTS.md

@@ -87,9 +87,11 @@ end up as an example fix OR an amendment here (with a changelog entry) — never
   typed TSL math (`rotate` etc.) may not resolve through them; cast to
   `Node<'float'|'vec3'|…>` with a comment (three-side typing gap, UPSTREAM.md B10 —
   same cast family as the fiber UniformNode gap).
-- Scene-level TSL fog is `scene.fogNode = fog(color, rangeFogFactor(near, far))` (the
-  legacy `Fog`/`FogExp2` objects are not the WebGPU path) — needs a documented cast,
-  `@types/three` doesn't declare `fogNode` (UPSTREAM.md B11; pattern in
+- Fog, two paths (verified against `NodeManager.updateFog()`): plain `Fog`/`FogExp2`
+  set declaratively (`<fog attach="fog" args={…} />`) IS auto-wrapped into a fog node
+  by the WebGPU renderer — prefer it. Only a CUSTOM TSL fog graph needs
+  `scene.fogNode = fog(color, rangeFogFactor(near, far))`, which needs a documented
+  cast — `@types/three` doesn't declare `fogNode` (UPSTREAM.md B11; pattern in
   src/examples/sprites.tsx).
 - Node materials are auto-extended by the `/webgpu` entry: `<meshStandardNodeMaterial>`
   etc. just work in JSX.

src/examples.json

@@ -69,5 +69,11 @@
     "tags": ["tsl", "node-material", "planet", "leva"],
     "original": "https://threejs.org/examples/#webgpu_tsl_earth",
     "credits": "Earth textures from Solar System Scope (resized and merged), via the three.js examples"
+  },
+  {
+    "slug": "shadowmap",
+    "title": "Shadow Map",
+    "tags": ["tsl", "shadow", "node-material", "leva"],
+    "original": "https://threejs.org/examples/#webgpu_shadowmap"
   }
 ]

src/examples/shadowmap/Ground.tsx

@@ -0,0 +1,35 @@
+// Ground plane: `receivedShadowPositionNode` perturbs the position used to sample
+// incoming shadow maps (wavy shadow edges), independent of `colorNode`'s own noise
+// pattern — see the file header DIVERGENCE re: the original's dead perturbation calc
+// in colorNode.
+import { useMemo } from 'react'
+import { Fn, mx_fractal_noise_vec3, positionWorld } from 'three/tsl'
+
+const BASE_COLOR = '#999999'
+
+export function Ground() {
+  const receivedShadowPositionNode = useMemo(
+    () =>
+      Fn(() => {
+        const pos = positionWorld.toVar()
+        pos.xz.addAssign(mx_fractal_noise_vec3(positionWorld.mul(2)).saturate().xz)
+        return pos
+      })(),
+    [],
+  )
+
+  const colorNode = useMemo(() => mx_fractal_noise_vec3(positionWorld.mul(2)).saturate().zzz.mul(0.2).add(0.5), [])
+
+  return (
+    <mesh rotation-x={-Math.PI / 2} scale={3} castShadow receiveShadow>
+      <planeGeometry args={[200, 200]} />
+      <meshPhongNodeMaterial
+        color={BASE_COLOR}
+        shininess={0}
+        specular="#111111"
+        colorNode={colorNode}
+        receivedShadowPositionNode={receivedShadowPositionNode}
+      />
+    </mesh>
+  )
+}

src/examples/shadowmap/Lights.tsx

@@ -0,0 +1,62 @@
+// SpotLight + DirectionalLight, both shadow casters, configured via fiber's dash-path
+// props (`shadow-camera-*`, `shadow-mapSize-*`, `shadow-radius`). The directional light
+// orbits inside `dirGroup` and bobs along z — the same two independent animations the
+// original drives from its bare `animate()` function, now a `useFrame` job.
+import { useRef } from 'react'
+import { useFrame } from '@react-three/fiber/webgpu'
+import type { DirectionalLight, Group } from 'three/webgpu'
+
+export interface LightsProps {
+  shadowRadius: number
+  spinSpeed: number
+}
+
+export function Lights({ shadowRadius, spinSpeed }: LightsProps) {
+  const dirGroupRef = useRef<Group>(null)
+  const dirLightRef = useRef<DirectionalLight>(null)
+
+  useFrame((state, delta) => {
+    const group = dirGroupRef.current
+    const light = dirLightRef.current
+    if (!group || !light) return
+    group.rotation.y += 0.7 * spinSpeed * delta
+    light.position.z = 17 + Math.sin(state.time * 0.001 * spinSpeed) * 5
+  })
+
+  return (
+    <>
+      <ambientLight color="#444444" intensity={2} />
+      <spotLight
+        color="#ff8888"
+        intensity={400}
+        position={[8, 10, 5]}
+        angle={Math.PI / 5}
+        penumbra={0.3}
+        castShadow
+        shadow-camera-near={8}
+        shadow-camera-far={200}
+        shadow-mapSize-width={2048}
+        shadow-mapSize-height={2048}
+        shadow-radius={shadowRadius}
+      />
+      <group ref={dirGroupRef}>
+        <directionalLight
+          ref={dirLightRef}
+          color="#8888ff"
+          intensity={3}
+          position={[3, 12, 17]}
+          castShadow
+          shadow-camera-near={0.1}
+          shadow-camera-far={500}
+          shadow-camera-left={-17}
+          shadow-camera-right={17}
+          shadow-camera-top={17}
+          shadow-camera-bottom={-17}
+          shadow-mapSize-width={2048}
+          shadow-mapSize-height={2048}
+          shadow-radius={shadowRadius}
+        />
+      </group>
+    </>
+  )
+}

src/examples/shadowmap/Shapes.tsx

@@ -0,0 +1,62 @@
+// The rotating torus knot (its own maskNode-punched shadow caster, see the file header
+// DEMONSTRATES) plus the four static pillars around it.
+import { useMemo, useRef } from 'react'
+import { useFrame, useUniforms } from '@react-three/fiber/webgpu'
+import { mx_fractal_noise_float, positionLocal } from 'three/tsl'
+import type { Mesh, Node } from 'three/webgpu'
+
+const BASE_COLOR = '#999999'
+const PILLAR_POSITIONS: [number, number, number][] = [
+  [8, 3.5, 8],
+  [8, 3.5, -8],
+  [-8, 3.5, 8],
+  [-8, 3.5, -8],
+]
+
+export interface TorusKnotProps {
+  maskThreshold: number
+  spinSpeed: number
+}
+
+// The torus knot's material doubles as its own shadow-caster material: `maskNode`
+// discards fragments below the noise threshold, and that discard applies to the shadow
+// depth pass too, punching matching holes in the shadow (header DEMONSTRATES).
+export function TorusKnot({ maskThreshold, spinSpeed }: TorusKnotProps) {
+  const meshRef = useRef<Mesh>(null)
+  const { threshold } = useUniforms({ threshold: maskThreshold }, 'shadowmapMask')
+
+  // Cast: fiber's `UniformNode<T>` pins the value type to `unknown` (documented fiber
+  // typing gap, see tsl-halftone/skinning-instancing) — this uniform really is a float.
+  const maskNode = useMemo(
+    () => mx_fractal_noise_float(positionLocal.mul(0.1)).x.greaterThan(threshold as unknown as Node<'float'>),
+    [threshold],
+  )
+
+  useFrame((_, delta) => {
+    const mesh = meshRef.current
+    if (!mesh) return
+    mesh.rotation.x += 0.25 * spinSpeed * delta
+    mesh.rotation.y += 0.5 * spinSpeed * delta
+    mesh.rotation.z += 1 * spinSpeed * delta
+  })
+
+  return (
+    <mesh ref={meshRef} scale={1 / 18} position={[0, 3, 0]} castShadow receiveShadow>
+      <torusKnotGeometry args={[25, 8, 75, 80]} />
+      <meshPhongNodeMaterial color={BASE_COLOR} shininess={0} specular="#222222" transparent maskNode={maskNode} />
+    </mesh>
+  )
+}
+
+export function Pillars() {
+  return (
+    <>
+      {PILLAR_POSITIONS.map((position, i) => (
+        <mesh key={i} position={position} castShadow>
+          <cylinderGeometry args={[0.75, 0.75, 7, 32]} />
+          <meshPhongNodeMaterial color={BASE_COLOR} shininess={0} specular="#222222" />
+        </mesh>
+      ))}
+    </>
+  )
+}

src/examples/shadowmap/shadowmap.tsx

@@ -0,0 +1,103 @@
+/**
+ * shadowmap
+ * R3F port of three.js `webgpu_shadowmap`, running on WebGPU.
+ * Original: https://threejs.org/examples/#webgpu_shadowmap (~175 lines of JS)
+ *
+ * DEMONSTRATES
+ * - `NodeMaterial.maskNode` (Shapes.tsx): a fractal-noise discard mask (MaterialX's
+ *   `mx_fractal_noise_float`) punched through the torus knot's fragment shader — since
+ *   the shadow pass shares the same material graph, discarded fragments cast no shadow
+ *   either, unlike legacy alpha-test setups that need a separate depth material to keep
+ *   a caster's silhouette and its shadow in sync
+ * - `NodeMaterial.receivedShadowPositionNode` (Ground.tsx): perturbing the position the
+ *   ground material samples shadow maps at (`mx_fractal_noise_vec3`), producing a
+ *   wavy/distorted shadow edge with no extra vertex displacement
+ * - Two independent shadow-casting lights (`SpotLight` + `DirectionalLight`, Lights.tsx)
+ *   configured via fiber's dash-path props (`shadow-camera-*`, `shadow-mapSize-*`,
+ *   `shadow-radius`)
+ * - `useUniforms` feeding a leva-controlled threshold straight into the discard mask's
+ *   TSL graph (same "feed a value in, keep the graph identity stable" pattern as
+ *   tsl-halftone), tying a live control directly to the maskNode technique above
+ * - Legacy `<fog attach="fog">` (a plain `THREE.Fog`, not a TSL `fogNode`) rendering
+ *   correctly under the WebGPU node-material pipeline — three's `NodeManager.updateFog()`
+ *   auto-wraps `scene.fog` into a fog node every frame, so the declarative fiber `<fog>`
+ *   idiom (used elsewhere in this corpus for legacy WebGL-style fog) needs no cast or
+ *   TSL rewrite here; see header DIVERGENCE for why this refines an existing AGENTS.md note
+ *
+ * DIVERGENCE from original
+ * - Folder pattern: split by scene role into `Lights.tsx` (spot + directional, orbit +
+ *   bob animation), `Shapes.tsx` (torus knot + pillars), and `Ground.tsx` (the noise-
+ *   shaded/shadow-perturbed plane) — the flat file exceeded the ~200-line threshold
+ * - OrbitControls (`target`, `minDistance`, `maxDistance`, no pan lock) becomes
+ *   DemoHelpers' camera-controls v3 wrapper; grid disabled (`grid={false}`) — the
+ *   original's own 600x600 noise-shaded ground plane IS the subject of this example
+ *   (`receivedShadowPositionNode`), and an infinite world grid at the same height would
+ *   visually compete with it
+ * - `THREE.Timer` dropped; `useFrame`'s `state.delta`/`state.time` drive the per-frame
+ *   rotation/orbit/bob directly, same translation as every other port in this corpus
+ * - The four pillars are four independent JSX `meshPhongNodeMaterial` instances instead
+ *   of the original's one shared material + three `.clone()`s — declarative simplicity,
+ *   the four extra material instances are negligible next to the torus knot / ground
+ *   node graphs
+ * - The ground's `colorNode` drops the original's dead position-perturbation calc (a
+ *   `pos.xz` noise offset computed via `toVar()`/`addAssign()` but never read before the
+ *   node returns — apparent copy/paste from `receivedShadowPositionNode` just above it
+ *   in the original source); the perturbation is kept where it's actually used
+ * - `renderer.inspector`'s dat.gui-less imperative setup gains a small leva panel
+ *   (`maskThreshold`, `shadowRadius`, `spinSpeed`, `exposure`) — the original has no UI
+ *   at all; added for interactivity/pedagogy, same rationale as this corpus's other
+ *   zero-GUI ports (sky, sprites)
+ * - `spinSpeed` uniformly scales the torus knot's three rotation axes, the directional
+ *   light group's orbit, and the light's z-bob frequency together (one dial, not the
+ *   original's four independent hard-coded rates)
+ * - `renderer.toneMappingExposure` driven from leva (same escape hatch as
+ *   `sky`/`postprocessing-bloom-emissive`: a WebGPURenderer property, not a TSL uniform)
+ */
+import { useEffect } from 'react'
+import { Canvas, useThree } from '@react-three/fiber/webgpu'
+import { useControls, folder } from 'leva'
+import { ACESFilmicToneMapping } from 'three/webgpu'
+import { DemoHelpers } from '../../utils/DemoHelpers'
+import { Ground } from './Ground'
+import { Lights } from './Lights'
+import { Pillars, TorusKnot } from './Shapes'
+
+// renderer.toneMappingExposure is a WebGPURenderer property, not a TSL uniform — set
+// imperatively (same pattern as sky.tsx / postprocessing-bloom-emissive.tsx).
+function ToneMappingExposure({ exposure }: { exposure: number }) {
+  const renderer = useThree((s) => s.renderer)
+
+  useEffect(() => {
+    renderer.toneMappingExposure = exposure
+  }, [renderer, exposure])
+
+  return null
+}
+
+export default function Shadowmap() {
+  const { maskThreshold, shadowRadius, spinSpeed, exposure } = useControls('shadowmap', {
+    maskThreshold: { value: 0, min: -1, max: 1, step: 0.01 },
+    shadow: folder({
+      shadowRadius: { value: 4, min: 0, max: 10, step: 0.5 },
+    }),
+    spinSpeed: { value: 1, min: 0, max: 3, step: 0.05 },
+    exposure: { value: 1, min: 0, max: 2, step: 0.01 },
+  })
+
+  return (
+    <Canvas
+      renderer={{ toneMapping: ACESFilmicToneMapping }}
+      shadows
+      background="#222244"
+      camera={{ position: [0, 10, 20], fov: 45, near: 1, far: 1000 }}
+    >
+      <fog attach="fog" args={['#222244', 50, 100]} />
+      <Lights shadowRadius={shadowRadius} spinSpeed={spinSpeed} />
+      <TorusKnot maskThreshold={maskThreshold} spinSpeed={spinSpeed} />
+      <Pillars />
+      <Ground />
+      <ToneMappingExposure exposure={exposure} />
+      <DemoHelpers grid={false} target={[0, 2, 0]} minDistance={7} maxDistance={40} />
+    </Canvas>
+  )
+}