From 0a59d89d7b5bb2ffbf8ee2710136171fd5ccefe0 Mon Sep 17 00:00:00 2001
From: Alex Yang <himself65@outlook.com>
Date: Wed, 18 Mar 2026 16:41:20 -0700
Subject: [PATCH] Add console warnings when WebGL is not available or context
 is lost

Previously, COBE silently returned no-op objects when WebGL was
unavailable or shaders failed to compile, making it hard to debug.
This adds console.warn messages for three failure scenarios:
- WebGL not supported by browser/device
- Shader program compilation failure
- Runtime WebGL context loss/restoration
---
 src/index.js | 33 +++++++++++++++++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)

diff --git a/src/index.js b/src/index.js
index e182bc9..8092b14 100644
--- a/src/index.js
+++ b/src/index.js
@@ -50,7 +50,12 @@ export default (canvas, opts) => {
   const webgl2 = !!gl
   if (!gl) gl = canvas.getContext('webgl', contextOpts)
 
-  if (!gl) return { destroy: () => {}, update: () => {} }
+  if (!gl) {
+    console.warn(
+      'COBE: WebGL is not supported in this browser or device. The globe will not be rendered.',
+    )
+    return { destroy: () => {}, update: () => {} }
+  }
 
   const instExt = webgl2 ? null : gl.getExtension('ANGLE_instanced_arrays')
 
@@ -87,7 +92,12 @@ export default (canvas, opts) => {
   const markerProgram = createProgram(gl, MARKER_VERT, MARKER_FRAG)
   const arcProgram = createProgram(gl, ARC_VERT, ARC_FRAG)
 
-  if (!globeProgram) return { destroy: () => {}, update: () => {} }
+  if (!globeProgram) {
+    console.warn(
+      'COBE: Failed to compile WebGL shaders. The globe will not be rendered.',
+    )
+    return { destroy: () => {}, update: () => {} }
+  }
 
   // Buffers
   const quadBuffer = gl.createBuffer()
@@ -591,10 +601,29 @@ export default (canvas, opts) => {
   // Initialize
   update({ markers, arcs })
 
+  // Handle WebGL context loss
+  const onContextLost = (e) => {
+    e.preventDefault()
+    console.warn(
+      'COBE: WebGL context lost. The globe will stop rendering. This can happen due to GPU resource limits or device sleep.',
+    )
+  }
+  const onContextRestored = () => {
+    console.warn(
+      'COBE: WebGL context restored. Please re-create the globe instance to resume rendering.',
+    )
+  }
+  canvas.addEventListener('webglcontextlost', onContextLost)
+  canvas.addEventListener('webglcontextrestored', onContextRestored)
+
   // Return public API
   return {
     update,
     destroy: () => {
+      // Clean up event listeners
+      canvas.removeEventListener('webglcontextlost', onContextLost)
+      canvas.removeEventListener('webglcontextrestored', onContextRestored)
+
       // Clean up WebGL resources
       gl.deleteBuffer(quadBuffer)
       gl.deleteBuffer(arcSegmentBuffer)