fix(webgl): degrade gracefully when the browser has no WebGL (#282)

The MiniTV renders from the root layout, so its three.js canvas mounts on
every route. On a browser with hardware acceleration off (also: sandboxed
contexts, blocklisted drivers, embedded webviews) getContext returns null,
WebGLRenderer throws, and with nothing catching it React unwound the whole
tree into Next.js' "This page couldn't load" screen. A decorative 120px
television was taking the site down for those users.

Adds a cached support probe and a guard component pairing that probe with
an error boundary — the probe catches the common case before three.js/ogl
construct anything, the boundary catches context loss, driver crashes,
exhausted context slots and shaders that won't compile on a given machine.
Applied to all four WebGL mount points. The fallback is silent: the scene
does not render, everything around it does.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: sktbrd

src/components/lootbox/AnimatedChest3D.tsx

@@ -6,12 +6,12 @@
    the particle buffers, useFrame mutates those buffers + reads refs each RAF frame
    (outside React render), and loaded textures get their wrap/colorSpace set once.
    None of this runs in React's render path. */
-
 import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Environment, OrbitControls, PerspectiveCamera, useGLTF } from "@react-three/drei";
 import { Canvas, useFrame, useLoader } from "@react-three/fiber";
 import { Group, PointLight, TextureLoader } from "three";
 import * as THREE from "three";
+import { WebGLGuard } from "@/components/webgl/WebGLGuard";
 
 interface ChestProps {
   onClick: () => void;
@@ -249,7 +249,7 @@ const FuturisticCrate = memo(({ onClick, isOpening, isPending, tier = "bronze" }
   const floatingLogoRef = useRef<Group>(null);
   const interiorGlowRef = useRef<THREE.MeshBasicMaterial>(null);
   const logoGlowRef = useRef<THREE.MeshBasicMaterial>(null);
-  
+
   // Get tier colors
   const tierColors = TIER_COLORS[tier];
 
@@ -259,7 +259,7 @@ const FuturisticCrate = memo(({ onClick, isOpening, isPending, tier = "bronze" }
 
   // Load Gnars logo 3D model for button
   const gnarsLogoModel = useGLTF("/models/gnars-logo.glb");
-  
+
   // Clone the model scene to allow multiple instances
   const clonedLogoScene = useMemo(() => {
     return gnarsLogoModel.scene.clone();
@@ -1445,51 +1445,65 @@ export default function AnimatedChest3D({
 
   return (
     <div className="relative w-full h-full rounded-lg overflow-hidden">
-      <Canvas
-        shadows
-        dpr={[1, 2]}
-        performance={{ min: 0.5 }}
-        gl={{ alpha: true, antialias: true }}
-        style={{ background: "transparent" }}
-      >
-        <PerspectiveCamera makeDefault position={[0, 1.5, 6]} fov={45} />
-        <OrbitControls
-          enableZoom={true}
-          enablePan={false}
-          minDistance={3}
-          maxDistance={8}
-          minPolarAngle={Math.PI / 6}
-          maxPolarAngle={Math.PI / 2}
-          enableDamping
-          dampingFactor={0.05}
-        />
+      {/* No context, no crate — but the panel around it keeps working. */}
+      <WebGLGuard label="lootbox-chest">
+        <Canvas
+          shadows
+          dpr={[1, 2]}
+          performance={{ min: 0.5 }}
+          gl={{ alpha: true, antialias: true }}
+          style={{ background: "transparent" }}
+        >
+          <PerspectiveCamera makeDefault position={[0, 1.5, 6]} fov={45} />
+          <OrbitControls
+            enableZoom={true}
+            enablePan={false}
+            minDistance={3}
+            maxDistance={8}
+            minPolarAngle={Math.PI / 6}
+            maxPolarAngle={Math.PI / 2}
+            enableDamping
+            dampingFactor={0.05}
+          />
 
-        {/* Lighting */}
-        <ambientLight intensity={0.4} />
-        <directionalLight
-          position={[5, 8, 5]}
-          intensity={1.5}
-          castShadow
-          shadow-mapSize-width={1024}
-          shadow-mapSize-height={1024}
-        />
-        <directionalLight position={[-3, 5, -3]} intensity={0.6} color="#88aaff" />
-        <spotLight
-          position={[0, 3, 4]}
-          angle={0.5}
-          penumbra={1}
-          intensity={1.2}
-          color="#ffffff"
-          castShadow
-        />
-        <spotLight position={[-4, 2, 2]} angle={0.4} penumbra={1} intensity={0.4} color="#6699ff" />
+          {/* Lighting */}
+          <ambientLight intensity={0.4} />
+          <directionalLight
+            position={[5, 8, 5]}
+            intensity={1.5}
+            castShadow
+            shadow-mapSize-width={1024}
+            shadow-mapSize-height={1024}
+          />
+          <directionalLight position={[-3, 5, -3]} intensity={0.6} color="#88aaff" />
+          <spotLight
+            position={[0, 3, 4]}
+            angle={0.5}
+            penumbra={1}
+            intensity={1.2}
+            color="#ffffff"
+            castShadow
+          />
+          <spotLight
+            position={[-4, 2, 2]}
+            angle={0.4}
+            penumbra={1}
+            intensity={0.4}
+            color="#6699ff"
+          />
 
-        {/* Environment for reflections */}
-        <Environment preset="warehouse" background={false} />
+          {/* Environment for reflections */}
+          <Environment preset="warehouse" background={false} />
 
-        {/* The Futuristic Crate */}
-        <FuturisticCrate onClick={handleChestClick} isOpening={isOpening} isPending={isPending} tier={tier} />
-      </Canvas>
+          {/* The Futuristic Crate */}
+          <FuturisticCrate
+            onClick={handleChestClick}
+            isOpening={isOpening}
+            isPending={isPending}
+            tier={tier}
+          />
+        </Canvas>
+      </WebGLGuard>
 
       {/* Sci-fi corner decorations — status is shown by the surrounding panel's
           stepper (translated), so no text overlay here. */}

src/components/nogglesrails/NogglesRailsGlobe.tsx

@@ -3,6 +3,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import dynamic from "next/dynamic";
 import { MapLocationDrawer, type LocationData } from "@/components/map-location-drawer";
+import { WebGLGuard } from "@/components/webgl/WebGLGuard";
 import { NOGGLES_RAILS, type NogglesRailLocation } from "@/content/nogglesrails";
 import { toLocationData } from "./NogglesRailsMap";
 
@@ -156,22 +157,26 @@ export function NogglesRailsGlobe({
         className={className ?? "h-[60vh] min-h-[350px] overflow-hidden rounded-lg"}
       >
         {dimensions.width > 0 && (
-          <Globe
-            ref={globeRef}
-            width={dimensions.width}
-            height={dimensions.height}
-            globeImageUrl="https://unpkg.com/three-globe/example/img/earth-blue-marble.jpg"
-            bumpImageUrl="https://unpkg.com/three-globe/example/img/earth-topology.png"
-            onGlobeReady={() => setReady(true)}
-            backgroundColor="rgba(0,0,0,0)"
-            atmosphereColor="#6699cc"
-            atmosphereAltitude={0.15}
-            htmlElementsData={points}
-            htmlLat="lat"
-            htmlLng="lng"
-            htmlAltitude={0.01}
-            htmlElement={markerHtmlElement}
-          />
+          // three-globe builds a WebGLRenderer on mount; without a context that
+          // throws through React and takes the whole page down with it.
+          <WebGLGuard label="noggles-rails-globe">
+            <Globe
+              ref={globeRef}
+              width={dimensions.width}
+              height={dimensions.height}
+              globeImageUrl="https://unpkg.com/three-globe/example/img/earth-blue-marble.jpg"
+              bumpImageUrl="https://unpkg.com/three-globe/example/img/earth-topology.png"
+              onGlobeReady={() => setReady(true)}
+              backgroundColor="rgba(0,0,0,0)"
+              atmosphereColor="#6699cc"
+              atmosphereAltitude={0.15}
+              htmlElementsData={points}
+              htmlLat="lat"
+              htmlLng="lng"
+              htmlAltitude={0.01}
+              htmlElement={markerHtmlElement}
+            />
+          </WebGLGuard>
         )}
       </div>
       <MapLocationDrawer location={selected} open={drawerOpen} onOpenChange={setDrawerOpen} />

src/components/tv/FaultyTerminal.tsx

@@ -3,6 +3,7 @@
 /* eslint-disable react-hooks/purity -- OGL WebGL imperative API requires render-time allocation */
 import { useCallback, useEffect, useMemo, useRef } from "react";
 import { Color, Mesh, Program, Renderer, Triangle } from "ogl";
+import { hasWebGLSupport } from "@/lib/webgl";
 
 const vertexShader = `
 attribute vec2 position;
@@ -295,6 +296,10 @@ export function FaultyTerminal({
   useEffect(() => {
     const ctn = containerRef.current;
     if (!ctn) return;
+    // ogl's Renderer throws when it cannot get a context (GPU disabled,
+    // sandboxed, blocklisted driver). This is a decorative background, so a
+    // machine without WebGL simply gets the empty container.
+    if (!hasWebGLSupport()) return;
 
     const renderer = new Renderer({ dpr });
     rendererRef.current = renderer;

src/components/tv/Gnar3DTVScene.tsx

@@ -4,6 +4,7 @@ import { Suspense, useCallback, useEffect, useRef, useState } from "react";
 import { OrbitControls } from "@react-three/drei";
 import { Canvas } from "@react-three/fiber";
 import type { WebGLRenderer } from "three";
+import { WebGLGuard } from "@/components/webgl/WebGLGuard";
 import { TV3DModel } from "./TV3DModel";
 import { useTVTextureControls } from "./TVTextureControls";
 import type { CreatorCoinImage } from "./useTVFeed";
@@ -60,54 +61,59 @@ export function Gnar3DTVScene({
 
   return (
     <div ref={containerRef} className="relative h-full w-full">
-      <Canvas
-        camera={{ position: [0, 0.5, 4], fov: 60 }}
-        frameloop="demand"
-        gl={{
-          antialias: false,
-          alpha: true,
-          powerPreference: "low-power",
-          failIfMajorPerformanceCaveat: false,
-          // Don't preserve drawing buffer - allows GPU to discard after compositing
-          preserveDrawingBuffer: false,
-          // Prefer low power GPU on multi-GPU systems
-          precision: "lowp",
-          // Limit pixel ratio for memory savings
-          depth: true,
-          stencil: false,
-        }}
-        onCreated={handleCreated}
-        style={{ background: "transparent" }}
-        dpr={dpr}
-      >
-        {/* Lighting - simplified for better performance */}
-        <ambientLight intensity={3.5} />
-        <directionalLight position={[5, 5, 5]} intensity={2.5} />
-        <directionalLight position={[-3, 3, -3]} intensity={1.5} />
+      {/* The MiniTV that renders this scene sits in the root layout, so a
+          machine without WebGL used to lose every page to the global error
+          screen rather than just the television. */}
+      <WebGLGuard label="gnars-tv">
+        <Canvas
+          camera={{ position: [0, 0.5, 4], fov: 60 }}
+          frameloop="demand"
+          gl={{
+            antialias: false,
+            alpha: true,
+            powerPreference: "low-power",
+            failIfMajorPerformanceCaveat: false,
+            // Don't preserve drawing buffer - allows GPU to discard after compositing
+            preserveDrawingBuffer: false,
+            // Prefer low power GPU on multi-GPU systems
+            precision: "lowp",
+            // Limit pixel ratio for memory savings
+            depth: true,
+            stencil: false,
+          }}
+          onCreated={handleCreated}
+          style={{ background: "transparent" }}
+          dpr={dpr}
+        >
+          {/* Lighting - simplified for better performance */}
+          <ambientLight intensity={3.5} />
+          <directionalLight position={[5, 5, 5]} intensity={2.5} />
+          <directionalLight position={[-3, 3, -3]} intensity={1.5} />
 
-        {/* TV Model */}
-        <Suspense fallback={null}>
-          <TV3DModel
-            videoUrl={videoUrl}
-            autoRotate={autoRotate}
-            onNextVideo={onNextVideo}
-            textureConfig={config}
-            creatorCoinImages={creatorCoinImages}
-            isVisible={isVisible}
-          />
-        </Suspense>
+          {/* TV Model */}
+          <Suspense fallback={null}>
+            <TV3DModel
+              videoUrl={videoUrl}
+              autoRotate={autoRotate}
+              onNextVideo={onNextVideo}
+              textureConfig={config}
+              creatorCoinImages={creatorCoinImages}
+              isVisible={isVisible}
+            />
+          </Suspense>
 
-        {/* Controls */}
-        {enableOrbitControls && (
-          <OrbitControls
-            enableDamping={false}
-            minDistance={2}
-            maxDistance={8}
-            enablePan={false}
-            enableZoom={false}
-          />
-        )}
-      </Canvas>
+          {/* Controls */}
+          {enableOrbitControls && (
+            <OrbitControls
+              enableDamping={false}
+              minDistance={2}
+              maxDistance={8}
+              enablePan={false}
+              enableZoom={false}
+            />
+          )}
+        </Canvas>
+      </WebGLGuard>
     </div>
   );
 }

src/components/webgl/WebGLGuard.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+import { Component, useEffect, useState, type ReactNode } from "react";
+import { hasWebGLSupport } from "@/lib/webgl";
+
+interface WebGLGuardProps {
+  children: ReactNode;
+  /** Rendered instead of `children` when WebGL is unavailable or the scene throws. */
+  fallback?: ReactNode;
+  /** Label used in the console warning so a report names the scene that fell back. */
+  label?: string;
+}
+
+interface BoundaryState {
+  failed: boolean;
+}
+
+class WebGLErrorBoundary extends Component<
+  { children: ReactNode; fallback: ReactNode; label: string },
+  BoundaryState
+> {
+  state: BoundaryState = { failed: false };
+
+  static getDerivedStateFromError(): BoundaryState {
+    return { failed: true };
+  }
+
+  componentDidCatch(error: unknown) {
+    // Not a crash we want reported as one: the page is expected to keep working
+    // without the scene. Log it so a support report still carries the reason.
+    console.warn(`[webgl] ${this.props.label} scene failed, falling back`, error);
+  }
+
+  render() {
+    return this.state.failed ? this.props.fallback : this.props.children;
+  }
+}
+
+/**
+ * Renders a WebGL scene only where WebGL actually works.
+ *
+ * Two layers, because the failure has two shapes:
+ *  - support probe — the common case (GPU disabled, sandboxed, blocklisted
+ *    driver). Caught before three.js/ogl ever construct a renderer.
+ *  - error boundary — everything else: context creation that fails despite a
+ *    passing probe, a driver crash, too many live contexts, a shader that will
+ *    not compile on that machine.
+ *
+ * Without this, `new WebGLRenderer()` throws through React and, since the
+ * MiniTV lives in the root layout, replaces every page with the global error
+ * screen. See `src/lib/webgl.ts`.
+ */
+export function WebGLGuard({ children, fallback = null, label = "webgl" }: WebGLGuardProps) {
+  // Probing needs a DOM, so the answer is only known after mount. `null` keeps
+  // the server markup and the first client render identical.
+  const [supported, setSupported] = useState<boolean | null>(null);
+
+  useEffect(() => {
+    setSupported(hasWebGLSupport());
+  }, []);
+
+  if (supported === null) return <>{fallback}</>;
+  if (!supported) return <>{fallback}</>;
+
+  return (
+    <WebGLErrorBoundary fallback={fallback} label={label}>
+      {children}
+    </WebGLErrorBoundary>
+  );
+}