fix: corpus-wide B17 repair — 14 more frozen examples un-frozen

Full-corpus pixel-diff + frameCount audit after flames find: every ungated
suspending hook froze its example (loop alive, pixels dead on the old
root). Explicit Suspense gates added to rtt, skinning-instancing,
tsl-halftone, instance-mesh, lights-phong, lights-spotlight,
materials-basic, materials-envmaps, tonemapping, and 5 loader-gltf-*
ports; all probe-verified animating. All four SwiftShader CI stall
examples were B17 cases — the stall matrix is plausibly this bug (watch
next advisory CI run; ciSkips may be removable). B17 brief expanded,
AGENTS v0.13, HANDOFF audit section. 59/59 smoke green.

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

Author: DennisSmolek

AGENTS.md

@@ -332,6 +332,16 @@ override lands with an UPSTREAM.md entry in the same commit.** Highlights:
 
 ## Changelog
 
+- 2026-07-27 — v0.13: corpus-wide B17 audit + repair (wave-8 interlude). A
+  full-corpus pixel-diff + frameCount sweep found 14 more B17-frozen examples
+  beyond flames' original three — every ungated suspending hook in the corpus,
+  including all four SwiftShader-stall examples (that CI mystery is plausibly
+  THIS bug; try dropping ciSkips). All repaired with explicit Suspense gates and
+  probe-verified. Fingerprint for the future: `__frameCount` advances while
+  pixels freeze = dual-root, check for the createRoot warning. Probe windows
+  must exceed stop-go animation periods (postprocessing-pixel false-alarmed at
+  1.5s; clean at 4s). Statics-by-design confirmed: morphtargets, depth-texture,
+  tonemapping, postprocessing-ao, compute-texture family.
 - 2026-07-27 — v0.12 amendments from wave-7 pair 4 (tsl-vfx-flames +
   tsl-vfx-tornado — wave 7 closes at 57 examples): **the explicit-Suspense rule**
   (Canvas-boundary suspension re-runs createRoot on alpha.3 and freezes all TSL

docs/HANDOFF.md

@@ -1,5 +1,26 @@
 # Session Handoff — 2026-07-27 (overnight, continued: repo live + M2 waves 1–2)
 
+## Wave 8 interlude: corpus-wide B17 audit (same night)
+
+Flames' B17 find (wave 7) triggered a full-corpus animation audit: two-frame
+pixel-diff + `__frameCount` probes over all examples. Result: **14 more frozen
+examples repaired** (every ungated suspending hook in the corpus — rtt,
+skinning-instancing, tsl-halftone, instance-mesh, lights-phong, lights-spotlight,
+materials-basic, materials-envmaps, tonemapping, five loader-gltf-* ports), all
+verified animating post-fix. Fingerprint: loop alive (`__frameCount` advances) +
+pixels frozen + `R3F.createRoot should only be called once!` warning.
+
+**Big thread: all four SwiftShader CI stall examples were B17 cases.** The stall
+mystery is plausibly this bug — next CI pass, watch the advisory smoke job; if
+the four now pass on SwiftShader, drop their `ciSkip`s and consider flipping
+smoke back to blocking.
+
+Statics-by-design confirmed (0px, clean console, full-rate loop): morphtargets,
+depth-texture, tonemapping, geometry-loft*(see B17 open anomaly: warning with no
+suspending hook), postprocessing-ao, loader-gltf-sheen/-compressed.
+Follow-up still queued: the pixel-diff "animates" smoke assertion with a
+`static: true` manifest flag (probe windows must exceed stop-go periods — 4s).
+
 ## Wave 7 (same night)
 
 8 ports, 4 pairs — postprocessing cluster (6) + TSL VFX pair (2). **57 examples

docs/UPSTREAM.md

@@ -254,6 +254,23 @@ commit** (AGENTS.md points agents at this file).
   createRoot warning, all three had suspending `useTexture` with no explicit
   boundary. Adding `<Suspense fallback={null}>` inside Canvas fixes all of them
   (post-fix: 12k–75k px/s changing, zero warnings).
+- **Full-corpus audit (wave 8)**: a systematic sweep found 14 MORE affected
+  examples (every ungated suspending hook in the corpus): rtt,
+  skinning-instancing, tsl-halftone, instance-mesh, lights-phong,
+  lights-spotlight, materials-basic, materials-envmaps, tonemapping, and the five
+  loader-gltf-* single-model ports. All repaired the same way and verified
+  animating (or legitimately static with clean consoles + full-rate loops) by
+  pixel-diff + `__frameCount` probes. Mechanism note: the frame loop KEEPS
+  RUNNING (`__frameCount` advances) while the displayed canvas stays on the dead
+  root's last frame — "loop alive, pixels frozen" is the fingerprint.
+- **Likely explains the SwiftShader CI stall matrix**: all four stall examples
+  (skinning-instancing, rtt, tsl-halftone, sprites) were B17 cases — on
+  software raster the dual-root race plausibly lands so the readiness signal
+  never fires at all. Try removing the `ciSkip`s after this repair lands.
+- **Open anomaly**: `geometry-loft` logs the same createRoot warning with NO
+  suspending hook anywhere in the example (17 heavy LoftGeometry exhibits, slow
+  first render) — still animates, but the loop degraded to ~5fps under probe
+  conditions. Different trigger for the same re-entry?
 - **Workaround in repo**: Layer 1 rule — every suspending subtree inside Canvas
   gets an explicit Suspense boundary.
 - **Suggested fix**: guard the root-creation path against the re-entry that

src/examples/instance-mesh.tsx

@@ -29,7 +29,7 @@
  * - DemoHelpers baseline (grid + camera controls) added; original had a fixed camera
  *   with no user interaction.
  */
-import { useEffect, useMemo, useRef } from 'react'
+import { Suspense, useEffect, useMemo, useRef } from 'react'
 import { Canvas, useFrame, useLoader } from '@react-three/fiber/webgpu'
 import { useControls } from 'leva'
 import { mix, normalWorld, oscSine, range, time } from 'three/tsl'
@@ -134,7 +134,11 @@ export default function InstanceMesh() {
       background="#000000"
       camera={{ position: [amount * 0.9, amount * 0.9, amount * 0.9], fov: 60, near: 0.1, far: 100 }}
     >
-      <InstancedSuzanne key={amount} amount={amount} visible={Math.min(visible, count)} />
+      {/* B17 gate: ungated suspension reaching Canvas's boundary re-runs createRoot
+          and freezes the displayed scene (AGENTS.md; corpus-wide repair, wave 8). */}
+      <Suspense fallback={null}>
+        <InstancedSuzanne key={amount} amount={amount} visible={Math.min(visible, count)} />
+      </Suspense>
       <DemoHelpers grid={false} />
     </Canvas>
   )

src/examples/lights-phong.tsx

@@ -41,7 +41,7 @@
  *   declare `fogNode` even though the WebGPU renderer's `NodeManager` reads it directly
  *   off the live scene instance (same documented gap as `sprites.tsx`, AGENTS.md B11)
  */
-import { useEffect, useMemo } from 'react'
+import { Suspense, useEffect, useMemo } from 'react'
 import { Canvas, useFrame, useThree } from '@react-three/fiber/webgpu'
 import { useTexture } from '@react-three/drei/webgpu'
 import { folder, useControls } from 'leva'
@@ -214,12 +214,16 @@ export default function LightsPhong() {
   return (
     <Canvas renderer background="#000000" camera={{ position: [0, 0, 7], fov: 50, near: 0.01, far: 100 }}>
       <SceneFog fogColor={fogColor} near={fogNear} far={fogFar} />
-      <Teapots
-        leftLightKey={leftLightKey as LightKey}
-        rightLightKey={rightLightKey as LightKey}
-        centerShininess={centerShininess}
-        rightShininess={rightShininess}
-      />
+      {/* B17 gate: ungated suspension reaching Canvas's boundary re-runs createRoot
+          and freezes the displayed scene (AGENTS.md; corpus-wide repair, wave 8). */}
+      <Suspense fallback={null}>
+        <Teapots
+          leftLightKey={leftLightKey as LightKey}
+          rightLightKey={rightLightKey as LightKey}
+          centerShininess={centerShininess}
+          rightShininess={rightShininess}
+        />
+      </Suspense>
       <DemoHelpers grid={false} minDistance={3} maxDistance={25} />
     </Canvas>
   )

src/examples/lights-spotlight.tsx

@@ -43,7 +43,7 @@
  *   IS the shadow receiver this example is about; an infinite grid at y=0.002 would
  *   render through/under it, competing with the shadow for visual attention
  */
-import { useEffect, useMemo, useRef } from 'react'
+import { Suspense, useEffect, useMemo, useRef } from 'react'
 import { Canvas, useFrame, useLoader } from '@react-three/fiber/webgpu'
 import { useTexture } from '@react-three/drei/webgpu'
 import { folder, useControls } from 'leva'
@@ -224,20 +224,24 @@ export default function LightsSpotlight() {
   return (
     <Canvas renderer shadows background="#000000" camera={{ position: [7, 4, 1], fov: 40, near: 0.1, far: 100 }}>
       <hemisphereLight color="#ffffff" groundColor="#8d8d8d" intensity={0.25} />
-      <SpotlightRig
-        mapKey={map as MapKey}
-        color={color}
-        intensity={intensity}
-        distance={distance}
-        angle={angle}
-        penumbra={penumbra}
-        decay={decay}
-        focus={focus}
-        shadowIntensity={shadowIntensity}
-        helpers={helpers}
-      />
-      <Floor />
-      <Lucy />
+      {/* B17 gate: ungated suspension reaching Canvas's boundary re-runs createRoot
+          and freezes the displayed scene (AGENTS.md; corpus-wide repair, wave 8). */}
+      <Suspense fallback={null}>
+        <SpotlightRig
+          mapKey={map as MapKey}
+          color={color}
+          intensity={intensity}
+          distance={distance}
+          angle={angle}
+          penumbra={penumbra}
+          decay={decay}
+          focus={focus}
+          shadowIntensity={shadowIntensity}
+          helpers={helpers}
+        />
+        <Floor />
+        <Lucy />
+      </Suspense>
       <DemoHelpers
         grid={false}
         target={[0, 1, 0]}

src/examples/loader-gltf-anisotropy.tsx

@@ -40,6 +40,7 @@
  *   y = -0.08) so the world-origin grid plane would slice straight through the subject
  *   of a macro shot (same call as the other loader-gltf-* ports).
  */
+import { Suspense } from 'react'
 import { Canvas } from '@react-three/fiber/webgpu'
 import { Environment, useGLTF } from '@react-three/drei/webgpu'
 import { useControls } from 'leva'
@@ -70,8 +71,12 @@ export default function LoaderGltfAnisotropy() {
       renderer={{ toneMapping: ACESFilmicToneMapping, toneMappingExposure: 1.35 }}
       camera={{ position: [-0.35, -0.2, 0.35], fov: 40, near: 0.01, far: 10 }}
     >
-      <Environment files={HDR_URL} background backgroundBlurriness={blurriness} />
-      <BarnLamp />
+      {/* B17 gate: ungated suspension reaching Canvas's boundary re-runs createRoot
+          and freezes the displayed scene (AGENTS.md; corpus-wide repair, wave 8). */}
+      <Suspense fallback={null}>
+        <Environment files={HDR_URL} background backgroundBlurriness={blurriness} />
+        <BarnLamp />
+      </Suspense>
       <DemoHelpers
         grid={false}
         target={[0, -0.08, 0.11]}

src/examples/loader-gltf-compressed.tsx

@@ -32,7 +32,7 @@
  *   backdrop, and the mat's base sits at y = -0.8, so a ground grid at y ≈ 0 would
  *   slice through the middle of the model
  */
-import { useRef } from 'react'
+import { Suspense, useRef } from 'react'
 import { Canvas, useFrame, useThree } from '@react-three/fiber/webgpu'
 import { useGLTF } from '@react-three/drei/webgpu'
 import { useControls } from 'leva'
@@ -78,7 +78,11 @@ export default function LoaderGltfCompressed() {
       background="#eeeeee"
       camera={{ position: [2, 2, 2], fov: 50, near: 1, far: 20 }}
     >
-      <CoffeeMat />
+      {/* B17 gate: ungated suspension reaching Canvas's boundary re-runs createRoot
+          and freezes the displayed scene (AGENTS.md; corpus-wide repair, wave 8). */}
+      <Suspense fallback={null}>
+        <CoffeeMat />
+      </Suspense>
       <Headlight power={power} />
       <DemoHelpers grid={false} minDistance={3} maxDistance={6} />
     </Canvas>

src/examples/loader-gltf-iridescence.tsx

@@ -35,6 +35,7 @@
  *   ground grid at the default 0.5 unit cell size (same call as
  *   `loader-gltf-transmission`)
  */
+import { Suspense } from 'react'
 import { Canvas } from '@react-three/fiber/webgpu'
 import { Environment, useGLTF } from '@react-three/drei/webgpu'
 import { useControls } from 'leva'
@@ -65,8 +66,12 @@ export default function LoaderGltfIridescence() {
       renderer={{ toneMapping: ACESFilmicToneMapping }}
       camera={{ position: [0.35, 0.05, 0.35], fov: 50, near: 0.05, far: 20 }}
     >
-      <Environment files={HDR_URL} background backgroundBlurriness={blurriness} />
-      <IridescenceLamp />
+      {/* B17 gate: ungated suspension reaching Canvas's boundary re-runs createRoot
+          and freezes the displayed scene (AGENTS.md; corpus-wide repair, wave 8). */}
+      <Suspense fallback={null}>
+        <Environment files={HDR_URL} background backgroundBlurriness={blurriness} />
+        <IridescenceLamp />
+      </Suspense>
       <DemoHelpers
         grid={false}
         target={[0, 0.2, 0]}

src/examples/loader-gltf-sheen.tsx

@@ -33,7 +33,7 @@
  *   plane, and the infinite grid moiré-aliases across it, competing with the fabric study
  *   (same call as the other two loader-gltf-* ports).
  */
-import { useEffect } from 'react'
+import { Suspense, useEffect } from 'react'
 import { Canvas } from '@react-three/fiber/webgpu'
 import { Environment, useGLTF } from '@react-three/drei/webgpu'
 import { useControls } from 'leva'
@@ -72,8 +72,12 @@ export default function LoaderGltfSheen() {
       renderer={{ toneMapping: ACESFilmicToneMapping }}
       camera={{ position: [-0.75, 0.7, 1.25], fov: 45, near: 0.1, far: 20 }}
     >
-      <Environment files={HDR_URL} background />
-      <SheenChair sheen={sheen} />
+      {/* B17 gate: ungated suspension reaching Canvas's boundary re-runs createRoot
+          and freezes the displayed scene (AGENTS.md; corpus-wide repair, wave 8). */}
+      <Suspense fallback={null}>
+        <Environment files={HDR_URL} background />
+        <SheenChair sheen={sheen} />
+      </Suspense>
       <DemoHelpers grid={false} target={[0, 0.35, 0]} minDistance={1} maxDistance={10} />
     </Canvas>
   )