docs: make guide cross-platform and improve error handling resilience

docs/TROUBLESHOOTING.md

@@ -41,38 +41,77 @@ simple_logger = "5"
 view_formats: vec![format.add_srgb_suffix()],
 ```
 
-## 4. Panic: "No adapter found"
+## 4. "No adapter found"
 
-**Symptom:** Program crashes immediately with `No GPU adapter found`.
+**Symptom:** Program crashes or logs "No GPU adapter found" during startup.
 
-**Cause:** No Vulkan driver installed. wgpu on Linux requires Vulkan.
+**Cause:** wgpu cannot find a compatible graphics adapter. This can happen
+across all platforms for different reasons.
 
 **Fix:**
-```bash
-sudo apt install libvulkan1 mesa-vulkan-drivers
-vulkaninfo  # verify installation
-```
 
-## 5. Panic: "Surface lost"
+- **Windows:** Ensure your GPU supports DirectX 12 (WDDM 2.0+). Update GPU
+  drivers from the manufacturer's website (NVIDIA, AMD, or Intel). Some
+  integrated GPUs may require a Windows 10+ build. If DX12 is unavailable,
+  install the LunarG Vulkan Runtime.
+- **macOS:** Metal is required. Ensure your GPU supports Metal (all Macs
+  from 2012 onward). Update macOS to the latest version. If you're on
+  Apple Silicon, wgpu will automatically use the Metal backend.
+- **Linux:** Install Vulkan drivers and tools:
+  ```bash
+  # Ubuntu/Debian
+  sudo apt install vulkan-tools mesa-vulkan-drivers
+  # Arch
+  sudo pacman -S vulkan-tools vulkan-radeon  # or vulkan-intel / nvidia-utils
+  vulkaninfo  # verify installation
+  ```
 
-**Symptom:** Program crashes with a surface lost error during rendering.
+## 5. "Adapter not compatible" (macOS / Metal)
 
-**Cause:** Display server restarted or GPU context was reset. The [Surface](concepts/GLOSSARY.md#surface) is permanently invalidated.
+**Symptom:** wgpu reports that no adapter is compatible with the surface.
 
-**Fix:** In the tutorial, this means the window needs to be reopened. In production code, handle the `Lost` variant of `CurrentSurfaceTexture` by recreating the surface via `Instance::create_surface()`.
+**Cause:** On macOS, wgpu uses Metal exclusively. If the GPU does not support
+Metal (e.g., very old Mac hardware or a GPU below Metal 2.0), no adapter will
+be found.
 
-## 6. Wayland surface crashes or doesn't render
+**Fix:** Verify your Mac supports Metal. Check `System Information > Graphics`
+in macOS. If Metal is not supported, the GPU cannot be used with wgpu.
 
-**Symptom:** Program crashes or shows blank window on Wayland.
+## 6. "Surface lost"
 
-**Cause:** winit's Wayland backend may have compatibility issues with certain compositors.
+**Symptom:** Program crashes with a surface lost error during rendering, or the
+window renders blanks after being minimized/restored.
 
-**Fix:** Force X11 backend:
+**Cause:** The display server or GPU context was reset. The
+[Surface](concepts/GLOSSARY.md#surface) is permanently invalidated. Common
+triggers include:
+- Window minimized and restored (some display servers)
+- Display configuration changed (hotplug, external monitor connected/disconnected)
+- GPU driver reset
+- Compositor restart (Linux/Wayland)
+
+**Fix:** Handle the `CurrentSurfaceTexture::Lost` variant gracefully. In the
+tutorial, this means the window may need to be reopened. In production code,
+set `self.state = None`, then on the next redraw event, re-run the full
+`State::new()` initialization chain to recreate all GPU resources.
+
+## 7. Wayland surface crashes or doesn't render (Linux only)
+
+**Symptom:** Program crashes or shows blank window on Wayland compositors
+(Sway, GNOME Shell, KDE Plasma, etc.).
+
+**Cause:** winit's Wayland backend may have compatibility issues with certain
+compositors or Vulkan/Wayland interop layers.
+
+**Fix:** Temporarily force the X11 backend:
 ```bash
 WINIT_UNIX_BACKEND=x11 cargo run
 ```
 
-## 7. Window won't close
+If X11 works but Wayland does not, check your compositor version and winit
+version. This is a Linux-specific issue and does not affect Windows or macOS.
+
+## 8. Window won't close
 
 **Symptom:** Clicking the X button or pressing Escape doesn't close the window.
 
@@ -85,7 +124,7 @@ fn exiting(&mut self, event_loop_ctl: &ActiveEventLoop) {
 }
 ```
 
-## 8. CPU at 100%
+## 9. CPU at 100%
 
 **Symptom:** One CPU core at 100% usage.
 
@@ -93,7 +132,7 @@ fn exiting(&mut self, event_loop_ctl: &ActiveEventLoop) {
 
 **Fix:** No fix needed — this is expected for a continuous redraw demo. For production, switch to `ControlFlow::Wait` and call `request_redraw()` only when state changes.
 
-## 9. Shader compilation or pipeline creation error
+## 10. Shader compilation or pipeline creation error
 
 **Symptom:** Program panics during `create_render_pipeline` with a shader validation error.
 
@@ -104,7 +143,7 @@ fn exiting(&mut self, event_loop_ctl: &ActiveEventLoop) {
 - WGSL `@location(1)` matches Rust `shader_location: 1`
 - Vertex shader outputs `@builtin(position) clip_position: vec4<f32>`
 
-## 10. Triangle shows one solid color instead of gradient
+## 11. Triangle shows one solid color instead of gradient
 
 **Symptom:** Triangle renders but is a single uniform color instead of smoothly blending.
 
@@ -123,7 +162,7 @@ Not this (which returns a solid color):
 return vec4<f32>(1.0, 1.0, 1.0, 1.0);  // wrong: solid white
 ```
 
-## 11. WGSL shader compilation errors
+## 12. WGSL shader compilation errors
 
 **Symptom:** Program panics or logs errors during `device.create_shader_module()` or `create_render_pipeline()` with messages referencing WGSL validation failures.
 
@@ -140,13 +179,13 @@ return vec4<f32>(1.0, 1.0, 1.0, 1.0);  // wrong: solid white
 - Confirm the function name in your `@vertex`/`@fragment` declaration matches the string you pass to `ProgrammableStage::entry_point`
 - If the error message is unclear, try compiling the shader in isolation to isolate syntax vs. pipeline-binding issues
 
-## 12. GPU debugging with RenderDoc
+## 13. GPU debugging with RenderDoc
 
 **Symptom:** Rendering issues that are difficult to diagnose (artifacts, wrong output, silent failures).
 
 **Cause:** GPU debugging is hard with standard tools. Graphics pipeline state, shader execution, and buffer contents are not easily inspectable at runtime.
 
-**Fix:** Use [RenderDoc](https://renderdoc.org/) — a standalone GPU debugging tool supporting frame capture, pipeline state inspection, and shader debugging. It works with Vulkan (Linux), DX12 (Windows), and OpenGL. Launch RenderDoc, attach to your wgpu process, and capture frames to inspect the full graphics pipeline step by step.
+**Fix:** Use [RenderDoc](https://renderdoc.org/) — a standalone GPU debugging tool supporting frame capture, pipeline state inspection, and shader debugging. It works with Vulkan (Linux), DX12/DX11 (Windows), and Metal (macOS). Launch RenderDoc, attach to your wgpu process, and capture frames to inspect the full graphics pipeline step by step. On macOS, RenderDoc supports Metal 2.0+ devices.
 
 ## Additional Resources