MapLibre Black Screen on Mobile App Resume: Debugging WebGL Context Loss

[BenOnTrack]

Hi,

I'm building a Progressive Web App (PWA) using maplibre-svelte, and I've run into a strange issue on mobile devices. When I switch away from my app to another app and then return, the map sometimes shows a completely black screen — but only at the zoom level I was on before switching. If I zoom in or out, the map renders correctly again.

The map itself is still interactive (I can pan and zoom), so it seems like the WebGL context is partially lost or corrupted. I initially thought this might be related to Svelte's onDestroy lifecycle hook, but since the component isn't being unmounted, that doesn't seem to be the case.

I'm now considering using the visibilitychange event to detect when the app becomes active again and trigger a map refresh or reinitialization. Has anyone dealt with similar issues in MapLibre or Svelte PWAs? Is there a cleaner way to handle WebGL context loss on mobile?

[dimfeld]

Not that I know of but I haven't used it extensively on mobile so this is a bit outside my experience. Something around the visibilitychange event seems to make sense as a first try. If you find something that works well I'm happy to integrate this into the package.

[BenOnTrack]

As you may have seen in other discussions, I'm building a Progressive Web App (PWA) using Svelte 5. To extend the functionality of the original map instance, I created a class (technically a Rune), where I integrate directly:

• the map
• the loaded state
• a new parameter webGLContextLost

export class MapRune {
  current = $state<{
    map: maplibregl.Map | undefined
    loaded:boolean
    webGLContextLost: boolean | undefined
  }>({
    map: undefined,
    loaded:false,
    webGLContextLost: false,
  })

Following my usual coding style (...with my new friend Claude), I ended up with a working solution using this function within my class:

setupWebGLContextLostDetection() {
    const canvas = this.current.map.getCanvas()
    
    canvas.addEventListener('webglcontextlost', (e) => {
      e.preventDefault()  // Recommended for context loss events
      this.current.webGLContextLost = true
      debugLogger("WebGL context lost detected", e)
    })
    
    canvas.addEventListener('webglcontextrestored', (e) => {
      this.current.webGLContextLost = false
      debugLogger("WebGL context restored", e)
    })
  }

In my main component (App.svelte), I added a visibility change handler:

async function handleVisibilityChange() {
  try {
    document.addEventListener("visibilitychange", async () => {
      if (document.visibilityState === "visible") {
        // Check if we have a map and if the WebGL context was lost
        if (map && map.isWebGLContextLost()) {
          console.log("WebGL context was lost, reloading application")
          location.reload()
        } 
    })
  } catch (error) {
    console.error("Failed to handle visibility change:", error)
  }
}

Here, map refers to the Rune instance.

From my tests, this seems to work well. If the WebGL context is lost, the app reloads itself via location.reload(). I've seen similar behavior in other apps, so I assume this approach is acceptable (nevertheless I have no idea if software developers are using location.reload() (https://developer.mozilla.org/en-US/docs/Web/API/Location/reload))

If anyone reading those lines has a better proposal, please feel free to share!

[dimfeld]

Nice, thanks for sharing! I may integrate something similar to this directly into the package in the future, or at least call a callback so you can optionally reload or do something else.