feat: reflection — wave-2 port (agent); CameraControls autoRotate

reflector() floor with normal-mapped UV offset, recursive instanced-box
tree with effector-driven nodes, depth blur + vignette pipeline. TWEEN
dependency replaced with a hand-rolled ramp in useFrame.

CameraControls gains autoRotate/autoRotateSpeed (OrbitControls-parity
azimuth increment; third wrapper gap flagged by ports) - reflection now
auto-orbits like its original. UPSTREAM B11 broadened: fogNode/
backgroundNode/emissiveNode are one family of undeclared duck-typed
properties; AGENTS.md pattern note + instancedBufferAttribute type-arg note.

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

Author: DennisSmolek

AGENTS.md

@@ -87,6 +87,15 @@ 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).
+- Duck-typed `*Node` properties beyond a subclass's declared types are a PATTERN, not
+  one-offs: `scene.backgroundNode`, `scene.fogNode`, `material.emissiveNode` on
+  non-Standard node materials — the runtime reads them generically
+  (`NodeMaterial.setupOutgoingLight`, `NodeManager`) but `@types/three` declares them
+  narrowly. Cast with a comment; verify against the runtime source in
+  `reference/three.js/src/renderers/common/` first (UPSTREAM.md B11).
+- `instancedBufferAttribute<T>(array, itemSize)` needs its explicit type argument
+  under strict tsc (infers `unknown` otherwise) — same "typed TSL surface doesn't
+  infer" family as the Fn-param cast.
 - 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

docs/UPSTREAM.md

@@ -148,16 +148,21 @@ commit** (AGENTS.md points agents at this file).
   chars) or throw early from `useUniforms` with a clear message naming the offending
   scope/key. Silent pass-through into codegen is the worst of the options.
 
-### B11 · @types/three: `Scene.fogNode` missing
-
-- **What**: `Scene.fogNode` is a real webgpu runtime property (read by
-  `renderers/common/nodes/NodeManager.js` and `NodeMaterial`) — the TSL replacement
-  for legacy `Fog`/`FogExp2` — but `@types/three` doesn't declare it.
-- **Evidence**: hit porting `webgpu_sprites` (scene-level `fog(color, rangeFogFactor)`).
-- **Local workaround**: `(scene as unknown as { fogNode: Node | null }).fogNode = …`
-  with a comment (src/examples/sprites.tsx).
-- **Suggested fix**: add `fogNode: Node | null` to the `Scene` declaration in
-  @types/three (or three's own types if that's where Scene now lives).
+### B11 · @types/three: duck-typed `*Node` properties undeclared (fogNode, backgroundNode, emissiveNode…)
+
+- **What**: the WebGPU renderer reads several `*Node` properties generically at
+  runtime that `@types/three` declares narrowly or not at all:
+  `Scene.fogNode`, `Scene.backgroundNode` (read by
+  `renderers/common/nodes/NodeManager.js`), and `emissiveNode` on ALL NodeMaterial
+  subclasses (`NodeMaterial.setupOutgoingLight()` reads it generically; @types only
+  declares it on `MeshStandardNodeMaterial`).
+- **Evidence**: hit three times across ports — `sprites` (fogNode), `reflection`
+  (backgroundNode + emissiveNode on MeshPhongNodeMaterial).
+- **Local workaround**: documented casts (see src/examples/sprites.tsx,
+  src/examples/reflection/).
+- **Suggested fix**: declare `fogNode`/`backgroundNode` on `Scene` and move
+  `emissiveNode` (and friends read by `setupOutgoingLight`) up to the shared
+  `NodeMaterial` declaration.
 
 ### B8 · drei (minor, docs-level): `useProgress` subscription can setState during render
 

src/examples.json

@@ -81,5 +81,12 @@
     "title": "Procedural Texture",
     "tags": ["tsl", "render-to-texture", "gaussian-blur", "leva"],
     "original": "https://threejs.org/examples/#webgpu_procedural_texture"
+  },
+  {
+    "slug": "reflection",
+    "title": "Reflection + Recursive Tree Cubes",
+    "tags": ["tsl", "reflection", "instancing", "post-processing", "shadows", "fog", "leva"],
+    "original": "https://threejs.org/examples/#webgpu_reflection",
+    "credits": "Recursive Tree Cubes concept by oosmoxiecode; floor checkerboard textures from the three.js examples"
   }
 ]

src/examples/reflection/PostFX.tsx

@@ -0,0 +1,45 @@
+// Post-process: a depth-driven `gaussianBlur` (blur radius grows with scene depth,
+// same technique as `skinning-instancing`/`shadow-contact`) composited with a
+// `screenUV` vignette via `blendOverlay` — three TSL nodes combined into one
+// `outputNode`, no manual RenderTarget/QuadMesh plumbing (`useRenderPipeline` owns it).
+import { useEffect } from 'react'
+import { useRenderPipeline, useUniforms } from '@react-three/fiber/webgpu'
+import { gaussianBlur } from 'three/addons/tsl/display/GaussianBlurNode.js'
+import { blendOverlay, screenUV } from 'three/tsl'
+import type { Node } from 'three/webgpu'
+
+export interface PostFXProps {
+  /** Vignette darkening offset (leva `vignetteStrength`; 0.2 matches the original). */
+  vignetteStrength: number
+}
+
+export function PostFX({ vignetteStrength }: PostFXProps) {
+  const { uVignette } = useUniforms(() => ({ uVignette: vignetteStrength }))
+
+  useEffect(() => {
+    uVignette.value = vignetteStrength
+  }, [uVignette, vignetteStrength])
+
+  useRenderPipeline(({ renderPipeline, passes }) => {
+    if (!renderPipeline) return
+
+    const sceneColor = passes.scenePass.getTextureNode()
+    const sceneDepth = passes.scenePass.getLinearDepthNode().remapClamp(0.3, 0.7)
+
+    const blurredColor = gaussianBlur(sceneColor)
+    blurredColor.directionNode = sceneDepth
+
+    // Cast: fiber's `UniformNode<T>` pins the TSL node-type param to `unknown` (documented
+    // fiber typing gap, see skinning-instancing/rtt/shadow-contact/Tree.tsx).
+    const vignette = screenUV
+      .distance(0.5)
+      .mul(1.25)
+      .clamp()
+      .oneMinus()
+      .sub(uVignette as unknown as Node<'float'>)
+
+    renderPipeline.outputNode = blendOverlay(blurredColor, vignette)
+  })
+
+  return null
+}

src/examples/reflection/ReflectiveFloor.tsx

@@ -0,0 +1,67 @@
+// The reflective floor: a `reflector()` TSL node renders the scene from a mirrored
+// camera into its own render target, sampled through a normal-map-perturbed UV and
+// blended additively into `MeshPhongNodeMaterial.emissiveNode` (not `colorNode` — the
+// reflection ADDS onto the checkerboard diffuse, it doesn't replace it).
+import { useMemo } from 'react'
+import { useTexture } from '@react-three/drei/webgpu'
+import { reflector, texture, uv } from 'three/tsl'
+import { BoxGeometry, Mesh, MeshPhongNodeMaterial, RepeatWrapping, SRGBColorSpace } from 'three/webgpu'
+import type { Node } from 'three/webgpu'
+
+const FLOOR_COLOR_URL =
+  'https://cdn.jsdelivr.net/gh/mrdoob/three.js@r185/examples/textures/floors/FloorsCheckerboard_S_Diffuse.jpg'
+const FLOOR_NORMAL_URL =
+  'https://cdn.jsdelivr.net/gh/mrdoob/three.js@r185/examples/textures/floors/FloorsCheckerboard_S_Normal.jpg'
+
+// Reflector resolution scale is fixed at the original's hardcoded value: it sizes an
+// internal render target at construction time (not a reactive uniform), so it isn't
+// exposed as a leva control here — see reflection.tsx's header DIVERGENCE note.
+const REFLECTION_RESOLUTION_SCALE = 0.2
+
+export function ReflectiveFloor() {
+  const [floorColor, floorNormal] = useTexture([FLOOR_COLOR_URL, FLOOR_NORMAL_URL])
+
+  const { mesh, reflectionTarget } = useMemo(() => {
+    floorColor.wrapS = RepeatWrapping
+    floorColor.wrapT = RepeatWrapping
+    floorColor.colorSpace = SRGBColorSpace
+    floorColor.repeat.set(15, 15)
+
+    floorNormal.wrapS = RepeatWrapping
+    floorNormal.wrapT = RepeatWrapping
+    floorNormal.repeat.set(15, 15)
+
+    const floorUV = uv().mul(15)
+    const floorNormalOffset = texture(floorNormal, floorUV).xy.mul(2).sub(1).mul(0.02)
+
+    const reflection = reflector({ resolutionScale: REFLECTION_RESOLUTION_SCALE })
+    reflection.target.rotateX(-Math.PI / 2)
+    // Non-null: `reflector()` always constructs with a default `uvNode` (`screenUV.flipX()`)
+    // — @types/three declares the field nullable for the general `TextureNode` case, but
+    // this instance is never null at runtime.
+    reflection.uvNode = reflection.uvNode!.add(floorNormalOffset)
+
+    const material = new MeshPhongNodeMaterial()
+    material.colorNode = texture(floorColor, floorUV)
+    // Cast: `emissiveNode` is read generically by `NodeMaterial`'s base
+    // `setupOutgoingLight()` for every subclass (confirmed against
+    // `three/src/materials/nodes/NodeMaterial.js`), but @types/three only declares it on
+    // `MeshStandardNodeMaterial` — same class of duck-typed-property gap as
+    // `scene.fogNode`/`scene.backgroundNode` (see reflection.tsx header DIVERGENCE).
+    ;(material as unknown as { emissiveNode: Node | null }).emissiveNode = reflection.mul(0.25)
+    material.normalMap = floorNormal
+    material.normalScale.set(0.2, -0.2)
+
+    const mesh = new Mesh(new BoxGeometry(50, 0.001, 50), material)
+    mesh.receiveShadow = true
+
+    return { mesh, reflectionTarget: reflection.target }
+  }, [floorColor, floorNormal])
+
+  return (
+    <>
+      <primitive object={mesh} />
+      <primitive object={reflectionTarget} />
+    </>
+  )
+}