К основному содержанию
правило CX Codex

error-handling-recovery — правило для Claude Code: WebGL, установка

Правило error-handling-recovery для Claude Code обрабатывает потерю WebGL-контекста, пересоздаёт ресурсы и показывает запасной интерфейс в Three.js-сценах.

MIT ★ 4 719 обновлён 2026-10-24

Установить в Claude Code · Вручную: положить файлы Все способы и платформы ↓
.claude/rules/error-handling-recovery.md
Открыть на GitHub

Что делает error-handling-recovery

Правило задаёт обработку событий webglcontextlost и webglcontextrestored: останавливает цикл рендера, показывает сообщение о восстановлении, затем заново инициализирует сцену, материалы и текстуры. Ресурсы можно регистрировать в SceneManager, помечать для пересоздания и восстанавливать после возврата контекста.

Внутри также есть шаблон React Error Boundary для перехвата ошибок Three.js, логирование параметров GPU и WebGL, контроль числа геометрий и текстур. Для тестов используется расширение WEBGL_lose_context; предусмотрен переход от WebGPU к WebGL2, WebGL1 и статическому изображению.

Правило советует хранить состояние сцены, иначе ресурсы после восстановления не из чего пересоздавать. В обработчиках учитываются утечки памяти, перегрузка GPU, переключение вкладок и сбои драйвера.

Какие задачи решает

  • обработать потерю WebGL-контекста
  • пересоздать материалы и текстуры после восстановления
  • показать пользователю сообщение об ошибке 3D-сцены
  • проверить утечки по числу геометрий и текстур
  • добавить запасной рендерер или статичное изображение

Примеры запросов агенту

  • Добавь обработку потери WebGL-контекста в Three.js-сцену.
  • Сделай восстановление ресурсов после события webglcontextrestored.
  • Проверь обработку сбоя 3D-сцены через WEBGL_lose_context.

Как установить error-handling-recovery

Вручную: положить файлы

.claude/rules/error-handling-recovery.md

Поле paths во frontmatter ограничивает файлы

По шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать

Вопросы об error-handling-recovery

Как установить error-handling-recovery в Claude Code?

Поместите файл правила в .claude/rules/error-handling-recovery.md.

Что делает error-handling-recovery?

Правило помогает обнаруживать потерю WebGL-контекста, останавливать рендеринг, восстанавливать ресурсы и возвращать цикл анимации. Оно также описывает React Error Boundary, логирование WebGL и запасные варианты рендера.

Как проверить восстановление WebGL-контекста?

Получите расширение WEBGL_lose_context, вызовите loseContext(), а затем восстановите контекст через restoreContext() после задержки.

Исходный текст

error-handling-recovery.md · MIT
# Error Handling & Context Recovery

Handling WebGL errors and context loss gracefully.

## WebGL Context Lost

```javascript
const canvas = renderer.domElement;

canvas.addEventListener('webglcontextlost', (event) => {
  event.preventDefault(); // Indicates we'll handle recovery
  console.warn('WebGL context lost');

  // Stop render loop
  cancelAnimationFrame(animationId);

  // Show error UI
  showErrorOverlay('Graphics context lost. Recovering...');
});

canvas.addEventListener('webglcontextrestored', () => {
  console.log('WebGL context restored');

  // Recreate resources
  initScene();
  initMaterials();
  initTextures();

  // Restart render loop
  animate();

  hideErrorOverlay();
});
```

## Common Causes of Context Loss

1. **Memory Leaks**: Not disposing resources
2. **GPU Overload**: Too many draw calls
3. **Browser Tab Switch**: Mobile browsers free memory
4. **Driver Issues**: Especially on Windows
5. **GPU Crash**: Hardware/driver failure

## Simulating Context Loss (Testing)

```javascript
const ext = renderer.getContext().getExtension('WEBGL_lose_context');

// Lose context
ext.loseContext();

// Restore after delay
setTimeout(() => ext.restoreContext(), 1000);
```

## Resource Recreation Pattern

```javascript
class SceneManager {
  constructor() {
    this.resources = [];
    this.setupContextHandlers();
  }

  setupContextHandlers() {
    const canvas = this.renderer.domElement;

    canvas.addEventListener('webglcontextlost', (e) => {
      e.preventDefault();
      this.onContextLost();
    });

    canvas.addEventListener('webglcontextrestored', () => {
      this.onContextRestored();
    });
  }

  registerResource(resource) {
    this.resources.push(resource);
  }

  onContextLost() {
    // Mark all resources as needing recreation
    this.resources.forEach(r => r.needsRecreation = true);
  }

  onContextRestored() {
    // Recreate all resources
    this.resources.forEach(r => {
      if (r.needsRecreation) {
        r.recreate();
        r.needsRecreation = false;
      }
    });
  }
}
```

## React Error Boundary

```jsx
class ThreeErrorBoundary extends React.Component {
  state = { hasError: false, error: null };

  static getDerivedStateFromError(error) {
    return { hasError: true, error };
  }

  componentDidCatch(error, info) {
    console.error('Three.js error:', error);
    // Report to error tracking service
    reportError(error, info);
  }

  retry = () => {
    this.setState({ hasError: false, error: null });
  };

  render() {
    if (this.state.hasError) {
      return (
        <div className="error-fallback">
          <p>3D scene failed to load.</p>
          <button onClick={this.retry}>Retry</button>
        </div>
      );
    }
    return this.props.children;
  }
}

// Usage
<ThreeErrorBoundary>
  <Canvas>
    <Scene />
  </Canvas>
</ThreeErrorBoundary>
```

## Production Logging

```javascript
function logRendererInfo() {
  const gl = renderer.getContext();
  const debugInfo = gl.getExtension('WEBGL_debug_renderer_info');

  const info = {
    vendor: gl.getParameter(debugInfo.UNMASKED_VENDOR_WEBGL),
    renderer: gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL),
    maxTextureSize: gl.getParameter(gl.MAX_TEXTURE_SIZE),
    maxViewportDims: gl.getParameter(gl.MAX_VIEWPORT_DIMS),
    memory: renderer.info.memory,
    render: renderer.info.render
  };

  console.log('Renderer Info:', info);
  return info;
}

// Log on errors
window.addEventListener('error', (e) => {
  if (e.message.includes('WebGL') || e.message.includes('THREE')) {
    logRendererInfo();
  }
});
```

## Memory Monitoring

```javascript
function checkMemory() {
  const { geometries, textures } = renderer.info.memory;

  console.log(`Geometries: ${geometries}, Textures: ${textures}`);

  // Warning thresholds
  if (textures > 100) {
    console.warn('High texture count - check for leaks');
  }
  if (geometries > 500) {
    console.warn('High geometry count - check for leaks');
  }
}

// Check periodically
setInterval(checkMemory, 30000);
```

## Graceful Degradation

```javascript
function initRenderer() {
  // Try WebGPU first
  if (navigator.gpu) {
    try {
      return new THREE.WebGPURenderer({ antialias: true });
    } catch (e) {
      console.warn('WebGPU failed, falling back to WebGL');
    }
  }

  // Try WebGL2
  try {
    const canvas = document.createElement('canvas');
    if (canvas.getContext('webgl2')) {
      return new THREE.WebGLRenderer({ antialias: true });
    }
  } catch (e) {
    console.warn('WebGL2 failed, trying WebGL1');
  }

  // WebGL1 fallback
  try {
    return new THREE.WebGLRenderer({
      antialias: false,
      precision: 'mediump'
    });
  } catch (e) {
    // Show static image fallback
    showStaticFallback();
    return null;
  }
}
```

## Recovery Strategies

| Strategy | When to Use |
|----------|-------------|
| **Prevent** | Dispose aggressively, monitor memory |
| **Detect** | Listen for context lost events |
| **Recover** | Recreate resources from saved state |
| **Fallback** | Show static image or message |

## Best Practices

1. **Always Handle Context Loss**: Don't assume WebGL is always available

2. **Save State**: Keep track of scene state for recreation

3. **Dispose Properly**: Prevent context loss by managing memory

4. **User Feedback**: Show clear messages during recovery

5. **Logging**: Capture device info for debugging

6. **Fallbacks**: Have static fallback for critical content

## References

- [WebGL Context Lost](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/webglcontextlost_event)
- [Three.js dispose()](https://threejs.org/docs/#manual/en/introduction/How-to-dispose-of-objects)

© zebbern · MIT · zebbern/claude-code-guide

Похожие правила IDE

Все правила IDE по теме «Фронтенд и UI» →
correctness-and-error-handling cognitedata Скилл correctness-and-error-handling находит и устраняет сбои в React-коде Cognite Flows: монтирует Error Boundary, обрабатывает промисы и закрывает пустые состояния интерфейса. CX Codex +1 1 900установок langgraph-error-handling soba-labs Скилл langgraph-error-handling для Claude Code помогает настраивать обработку ошибок в LangGraph. Подключается, когда нужно добавить повторы, восстановление через LLM или передачу решения человеку. CX Codex +1 ★ 106звёзд репо react-error-handling oakoss Скилл react-error-handling помогает проектировать предохранители и запасные интерфейсы в React, чтобы сбой в дочернем компоненте не ломал всё приложение. CX Codex +1 134установок golang-error-handling samber Скилл golang-error-handling помогает идиоматично обрабатывать ошибки в Go. Включается при создании, оборачивании, проверке цепочек и логировании ошибок. CX Codex +1 46 400установок error-handling-ux Owl-Listener Скилл error-handling-ux для Claude Code, который помогает проектировать обработку ошибок: предотвращать сбои, показывать их пользователю и предлагать выход. Работает, когда ошибки встречаются в нескольких сценариях одновременно. CX Codex +1 2 600установок error-recovery-reviewer ShuaiMXu Скилл error-recovery-reviewer для Claude Code проверяет сценарии ошибок, пути восстановления и сохранность данных пользователя. Включается при разборе отказов в критических пользовательских задачах. CX Codex +1 ★ 529звёзд репо

Из того же набора86

Весь набор →
physics-integration Правило physics-integration задаёт правила связки Three.js с физическими движками Rapier и Cannon-es: настройка Vite, коллайдеры и синхронизация позиций. CX Codex +1 ★ 4 719звёзд репо raycasting-optimization Правило raycasting-optimization для Claude Code описывает, как ускорить поиск пересечений и выбор объектов в Three.js. Сокращает проверки Raycaster в интерактивных сценах и на сложных мешах. CX Codex +1 ★ 4 719звёзд репо mobile-optimization Правило mobile-optimization с готовыми паттернами для ускорения Three.js-сцен на смартфонах и планшетах. Снижает нагрузку на GPU, уменьшает потребление памяти и помогает держать стабильный FPS. CX Codex +1 ★ 4 719звёзд репо webxr-setup Правило webxr-setup для Claude Code задаёт настройку VR- и AR-сцен на Three.js через WebXR. Помогает агенту настроить рендерер, контроллеры и отслеживание рук. CX Codex +1 ★ 4 719звёзд репо vc-industry-research Скилл vc-industry-research собирает отраслевое исследование в стиле PE/VC: глубокий разбор сектора, инвестиционный меморандум или обзор рынка. На китайском или английском, по умолчанию в PDF. CX Codex +1 ★ 4 719звёзд репо tsl-complete-reference Правило tsl-complete-reference для Claude Code даёт справочник по TSL и помогает писать нодовые шейдеры без ошибок в типах и вызовах. CX Codex +1 ★ 4 719звёзд репо test-suite-architect Скилл test-suite-architect разворачивает QA-процессы по стандартам Google и OWASP: шаблоны тест-кейсов AAA, трекинг дефектов P0–P4, расчёт метрик и прогон тестов через LLM. CX Codex +1 ★ 4 719звёзд репо ssh-penetration-testing Скилл ssh-penetration-testing для Claude Code помогает проверять SSH-сервисы: собирать сведения о конфигурации, тестировать учётные данные и настраивать туннели. Проводит аудит SSH в разрешённой среде. CX Codex +1 ★ 4 719звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой