create-xani-agentic-app 1.0.0

package/template/.claude/skills/webgpu-threejs-tsl/docs/device-loss.md

@@ -0,0 +1,359 @@
+# WebGPU Device Loss Handling
+
+## What Is Device Loss?
+
+Device loss occurs when the GPU driver cannot continue processing commands. Causes include:
+
+- Driver crashes
+- Extreme resource pressure
+- Long-running shaders (GPU watchdog triggers after ~10 seconds)
+- Driver updates
+- Significant device configuration changes
+
+When a device is lost, the `GPUDevice` object and **all objects created with it become unusable**. All buffers, textures, pipelines, and GPU memory are discarded.
+
+## Listening for Device Loss
+
+Detect loss by attaching a callback to the device's `lost` promise:
+
+```javascript
+const adapter = await navigator.gpu.requestAdapter();
+if (!adapter) { return; }
+const device = await adapter.requestDevice();
+
+device.lost.then((info) => {
+  console.error('WebGPU device lost:', info.message);
+  // Handle recovery
+});
+```
+
+**Important:** Don't `await` this promise directly - it will block indefinitely if loss never occurs.
+
+### Device Loss Information
+
+The `GPUDeviceLostInfo` object provides:
+
+| Property | Description |
+|----------|-------------|
+| `reason` | `'destroyed'` (intentional via `destroy()`) or `'unknown'` (unexpected) |
+| `message` | Human-readable debugging info (don't parse programmatically) |
+
+```javascript
+device.lost.then((info) => {
+  if (info.reason === 'unknown') {
+    // Unexpected loss - attempt recovery
+    handleUnexpectedDeviceLoss();
+  } else {
+    // Intentional destruction - expected behavior
+  }
+});
+```
+
+### Devices Starting Lost
+
+`adapter.requestDevice()` always returns a `GPUDevice`, but it may already be lost if creation failed. This occurs when the adapter was "consumed" (used previously) or "expired."
+
+**Best practice:** Always get a new adapter right before requesting a device.
+
+## Recovery Strategies
+
+### Minimal Recovery (Page Reload)
+
+For simple applications:
+
+```javascript
+device.lost.then((info) => {
+  if (info.reason === 'unknown') {
+    // Warn user before reload
+    alert('Graphics error occurred. The page will reload.');
+    location.reload();
+  }
+});
+```
+
+### Restart GPU Content Only (Recommended for Three.js)
+
+Recreate the device and reconfigure the canvas without full page reload:
+
+```javascript
+import * as THREE from 'three/webgpu';
+
+let renderer;
+let scene, camera;
+
+async function initWebGPU() {
+  renderer = new THREE.WebGPURenderer();
+  await renderer.init();
+
+  // Access the underlying WebGPU device
+  const device = renderer.backend.device;
+
+  device.lost.then((info) => {
+    console.error('Device lost:', info.message);
+    if (info.reason === 'unknown') {
+      // Dispose current renderer
+      renderer.dispose();
+      // Reinitialize
+      initWebGPU();
+    }
+  });
+
+  // Configure canvas
+  renderer.setSize(window.innerWidth, window.innerHeight);
+  document.body.appendChild(renderer.domElement);
+
+  // Recreate scene content
+  setupScene();
+}
+
+function setupScene() {
+  scene = new THREE.Scene();
+  camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
+  // ... add meshes, lights, etc.
+}
+
+initWebGPU();
+```
+
+### Restore with Application State
+
+For applications with user progress or configuration:
+
+```javascript
+let appState = {
+  cameraPosition: { x: 0, y: 5, z: 10 },
+  settings: {},
+  // Don't save transient data like particle positions
+};
+
+// Save state periodically
+function saveState() {
+  appState.cameraPosition = {
+    x: camera.position.x,
+    y: camera.position.y,
+    z: camera.position.z
+  };
+  localStorage.setItem('appState', JSON.stringify(appState));
+}
+
+// Restore on recovery
+async function initWebGPU() {
+  renderer = new THREE.WebGPURenderer();
+  await renderer.init();
+
+  const savedState = localStorage.getItem('appState');
+  if (savedState) {
+    appState = JSON.parse(savedState);
+  }
+
+  setupScene();
+
+  // Restore camera position
+  camera.position.set(
+    appState.cameraPosition.x,
+    appState.cameraPosition.y,
+    appState.cameraPosition.z
+  );
+
+  renderer.backend.device.lost.then((info) => {
+    if (info.reason === 'unknown') {
+      saveState();
+      renderer.dispose();
+      initWebGPU();
+    }
+  });
+}
+```
+
+## When Recovery Fails
+
+If `requestAdapter()` returns `null` after device loss, the OS or browser has blocked GPU access:
+
+```javascript
+async function initWebGPU() {
+  const adapter = await navigator.gpu.requestAdapter();
+
+  if (!adapter) {
+    // Check if this is initial failure or post-loss failure
+    if (hadPreviousDevice) {
+      showMessage('GPU access lost. Please restart your browser.');
+    } else {
+      showMessage('WebGPU is not supported on this device.');
+    }
+    return;
+  }
+
+  // Continue with device creation...
+}
+```
+
+## Testing Device Loss
+
+### Using destroy()
+
+Call `device.destroy()` to simulate loss:
+
+```javascript
+let simulatedLoss = false;
+
+function simulateDeviceLoss() {
+  simulatedLoss = true;
+  renderer.backend.device.destroy();
+}
+
+// In your device.lost handler:
+device.lost.then((info) => {
+  if (info.reason === 'unknown' || simulatedLoss) {
+    simulatedLoss = false;
+    // Treat as unexpected loss for testing
+    handleDeviceLoss();
+  }
+});
+
+// Add debug keybinding
+window.addEventListener('keydown', (e) => {
+  if (e.key === 'L' && e.ctrlKey && e.shiftKey) {
+    simulateDeviceLoss();
+  }
+});
+```
+
+**Limitations of destroy():**
+- Unmaps buffers immediately (real loss doesn't)
+- Always allows device recovery (real loss may not)
+
+### Chrome GPU Process Crash Testing
+
+Navigate to `about:gpucrash` in a **separate tab** to crash the GPU process.
+
+Chrome enforces escalating restrictions:
+
+| Crash | Effect |
+|-------|--------|
+| 1st | New adapters allowed |
+| 2nd within 2 min | Adapter requests fail (resets on page refresh) |
+| 3rd within 2 min | All pages blocked (reset after 2 min or browser restart) |
+| 3-6 within 5 min | GPU process stops restarting; browser restart required |
+
+### Chrome Testing Flags
+
+Bypass crash limits for development:
+
+```bash
+# macOS
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --disable-domain-blocking-for-3d-apis \
+  --disable-gpu-process-crash-limit
+
+# Windows
+chrome.exe --disable-domain-blocking-for-3d-apis --disable-gpu-process-crash-limit
+
+# Linux
+google-chrome --disable-domain-blocking-for-3d-apis --disable-gpu-process-crash-limit
+```
+
+## Complete Example
+
+```javascript
+import * as THREE from 'three/webgpu';
+import { color, time, oscSine } from 'three/tsl';
+
+let renderer, scene, camera, mesh;
+let hadPreviousDevice = false;
+
+async function init() {
+  // Check WebGPU support
+  if (!navigator.gpu) {
+    showError('WebGPU not supported');
+    return;
+  }
+
+  // Create renderer
+  renderer = new THREE.WebGPURenderer({ antialias: true });
+
+  try {
+    await renderer.init();
+  } catch (e) {
+    if (hadPreviousDevice) {
+      showError('GPU recovery failed. Please restart browser.');
+    } else {
+      showError('Failed to initialize WebGPU.');
+    }
+    return;
+  }
+
+  hadPreviousDevice = true;
+
+  // Setup device loss handler
+  const device = renderer.backend.device;
+  device.lost.then(handleDeviceLoss);
+
+  // Setup scene
+  renderer.setSize(window.innerWidth, window.innerHeight);
+  document.body.appendChild(renderer.domElement);
+
+  scene = new THREE.Scene();
+  camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
+  camera.position.z = 5;
+
+  const geometry = new THREE.BoxGeometry();
+  const material = new THREE.MeshStandardNodeMaterial();
+  material.colorNode = color(0x00ff00).mul(oscSine(time));
+
+  mesh = new THREE.Mesh(geometry, material);
+  scene.add(mesh);
+
+  const light = new THREE.DirectionalLight(0xffffff, 1);
+  light.position.set(5, 5, 5);
+  scene.add(light);
+  scene.add(new THREE.AmbientLight(0x404040));
+
+  animate();
+}
+
+function handleDeviceLoss(info) {
+  console.error('Device lost:', info.reason, info.message);
+
+  if (info.reason === 'unknown') {
+    // Cleanup
+    if (renderer) {
+      renderer.domElement.remove();
+      renderer.dispose();
+    }
+
+    // Attempt recovery after short delay
+    setTimeout(() => {
+      init();
+    }, 100);
+  }
+}
+
+function animate() {
+  if (!renderer) return;
+
+  requestAnimationFrame(animate);
+  mesh.rotation.x += 0.01;
+  mesh.rotation.y += 0.01;
+  renderer.render(scene, camera);
+}
+
+function showError(message) {
+  const div = document.createElement('div');
+  div.textContent = message;
+  div.style.cssText = 'position:fixed;top:50%;left:50%;transform:translate(-50%,-50%);padding:20px;background:#f44;color:#fff;border-radius:8px;';
+  document.body.appendChild(div);
+}
+
+init();
+```
+
+## Best Practices
+
+1. **Always listen for device loss** - Even if you just show an error message
+2. **Get a fresh adapter before each device request** - The GPU hardware may have changed
+3. **Don't parse the message field** - It's implementation-specific and changes between browsers
+4. **Save critical application state** - Restore user progress after recovery
+5. **Don't save transient state** - Particle positions, physics state can be reset
+6. **Test your recovery path** - Use `destroy()` and Chrome's `about:gpucrash`
+7. **Handle adapter failure gracefully** - Distinguish between initial failure and post-loss failure
+8. **Add a short delay before recovery** - Give the system time to stabilize

package/template/.claude/skills/webgpu-threejs-tsl/docs/limits-and-features.md

@@ -0,0 +1,133 @@
+# WebGPU Limits and Features
+
+## Why This Matters
+
+WebGPU devices have **default limits** (guaranteed minimums) that may be lower than what your application needs. For example, the default `maxBufferSize` is 256 MiB — if you create a large compute buffer, you'll silently get errors unless you request a higher limit. Similarly, optional **features** like `float32-filterable` must be explicitly enabled.
+
+## Limits
+
+Limits define numeric constraints on resources. Every WebGPU implementation guarantees a set of minimum values, but most GPUs support much higher limits.
+
+Common limits you may need to increase:
+
+| Limit | Default | When to Increase |
+|-------|---------|------------------|
+| `maxBufferSize` | 268435456 (256 MiB) | Large storage/vertex buffers |
+| `maxStorageBufferBindingSize` | 134217728 (128 MiB) | Large compute storage buffers |
+| `maxStorageBuffersPerShaderStage` | 8 | Many storage buffers in one shader |
+| `maxComputeWorkgroupSizeX` | 128 | Large workgroup dimensions |
+| `maxComputeInvocationsPerWorkgroup` | 128 | Dense compute workgroups |
+| `maxColorAttachments` | 8 | Many render targets |
+
+### Querying Adapter Limits
+
+```javascript
+const adapter = await navigator.gpu?.requestAdapter();
+console.log(adapter.limits.maxBufferSize);
+console.log(adapter.limits.maxStorageBufferBindingSize);
+```
+
+### Requesting Increased Limits
+
+You must request higher limits when creating the device — otherwise you get the defaults, not the adapter's maximums.
+
+**Raw WebGPU:**
+```javascript
+const adapter = await navigator.gpu?.requestAdapter();
+const device = await adapter.requestDevice({
+  requiredLimits: {
+    maxBufferSize: 1024 * 1024 * 1024,            // 1 GiB
+    maxStorageBufferBindingSize: 1024 * 1024 * 512, // 512 MiB
+  },
+});
+```
+
+**Three.js WebGPURenderer:**
+
+Three.js accepts `requiredLimits` as a renderer constructor option, which gets passed through to `requestDevice()`:
+
+```javascript
+const renderer = new THREE.WebGPURenderer({
+  requiredLimits: {
+    maxBufferSize: 1024 * 1024 * 1024,            // 1 GiB
+    maxStorageBufferBindingSize: 1024 * 1024 * 512, // 512 MiB
+  },
+});
+await renderer.init();
+```
+
+If the adapter doesn't support the requested limit, `requestDevice()` (or `renderer.init()`) will fail.
+
+### Safe Pattern: Check Before Requesting
+
+```javascript
+const adapter = await navigator.gpu?.requestAdapter();
+
+const desiredBufferSize = 1024 * 1024 * 1024; // 1 GiB
+const requiredLimits = {};
+
+if (adapter.limits.maxBufferSize >= desiredBufferSize) {
+  requiredLimits.maxBufferSize = desiredBufferSize;
+} else {
+  console.warn('Adapter does not support 1 GiB buffers, using default');
+}
+
+const renderer = new THREE.WebGPURenderer({ requiredLimits });
+await renderer.init();
+```
+
+## Features
+
+Features are optional capabilities that vary by GPU. Unlike limits, features are either present or absent — there's no numeric value to adjust.
+
+### How Three.js Handles Features
+
+Three.js automatically requests **all features supported by the adapter**. You generally don't need to manage features manually when using Three.js.
+
+### Querying Available Features (Raw WebGPU)
+
+```javascript
+const adapter = await navigator.gpu?.requestAdapter();
+// adapter.features is a Set
+console.log(adapter.features.has('float32-filterable'));
+console.log(adapter.features.has('shader-f16'));
+```
+
+### Common Optional Features
+
+| Feature | Purpose |
+|---------|---------|
+| `float32-filterable` | Linear filtering on float32 textures |
+| `float32-blendable` | Blending on float32 render targets |
+| `shader-f16` | 16-bit floats in shaders |
+| `texture-compression-bc` | BC (desktop) texture compression |
+| `texture-compression-etc2` | ETC2 (mobile) texture compression |
+| `texture-compression-astc` | ASTC (mobile) texture compression |
+| `timestamp-query` | GPU timing measurements |
+| `depth-clip-control` | Disable depth clipping |
+| `dual-source-blending` | Two blend sources from one shader |
+| `subgroups` | Subgroup operations in compute |
+| `clip-distances` | Custom clip planes in vertex shader |
+
+## Best Practices
+
+1. **Only request limits you actually need** — requesting maximums hides portability issues where your app works on your GPU but fails on weaker ones
+2. **Check adapter limits before requesting** — gracefully degrade when limits aren't available
+3. **Don't forget storage buffer binding size** — `maxStorageBufferBindingSize` is often the bottleneck, not `maxBufferSize`
+4. **Use [webgpureport.org](https://webgpureport.org)** to check what limits/features different GPUs support
+
+## Debugging
+
+If you're hitting buffer size errors or validation failures:
+
+```javascript
+// Log all adapter limits
+const adapter = await navigator.gpu?.requestAdapter();
+for (const [key, value] of Object.entries(Object.getPrototypeOf(adapter.limits))) {
+  if (typeof value !== 'function') {
+    console.log(`${key}: ${adapter.limits[key]}`);
+  }
+}
+```
+
+Check Chrome DevTools console for WebGPU validation errors — they often mention which limit was exceeded.