Error Boundary for TresCanvas

[alvarosabu]

Description

As a developer using TresJS, I need a way to gracefully handle and display runtime errors that occur within the TresCanvas component and its children. This would improve the development experience and make it easier to debug issues in production.

Motivation

Currently, when an error occurs within TresCanvas or any of its child components (lights, meshes, materials, etc.) or threejs, the error can cause the entire application to crash or render a blank canvas without any meaningful feedback. This makes it difficult to:

1. Identify the source of the error
2. Debug issues in development
3. Provide a fallback UI in production
4. Handle errors gracefully without affecting the rest of the application

Proposal

Add an Error Boundary feature to TresCanvas that would:

1. Catch runtime errors in:

   • Scene initialization
   • Component mounting/unmounting
   • Animation frame updates
   • Resource loading (textures, models, etc.)
   • Child component errors

2. Provide a customizable error display that shows:

   • Error message and stack trace (in development)
   • Component tree path to the error
   • Simplified error message (in production)

3. Include built-in error handling for common ThreeJS-specific errors:

   • WebGL context loss
   • Texture loading failures
   • Geometry errors
   • Material compilation errors

Suggested solution

Implementation Details

<template>
  <TresCanvas
    :error-boundary="true"
    :error-fallback="customErrorComponent"
    @error="handleError"
  >
    <!-- Scene content -->
  </TresCanvas>
</template>

The error boundary would inject necessary CSS styles automatically for the error display, eliminating the need for external CSS files. The styles would be scoped to the error boundary container to avoid conflicts.

Default Error Display

The default error display would be a styled overlay with:

• Error message
• Stack trace (in development)
• Retry button
• Option to copy error details
• Responsive design that maintains the canvas aspect ratio

// Internal styling injection
const errorStyles = `
  .tres-error-boundary {
    position: relative;
    width: 100%;
    height: 100%;
    background: rgba(30, 30, 30, 0.95);
    color: #fff;
    font-family: monospace;
    padding: 1rem;
    overflow: auto;
  }
  .tres-error-message {
    color: #ff5555;
    margin-bottom: 1rem;
  }
  .tres-error-stack {
    font-size: 0.9em;
    white-space: pre-wrap;
  }
  .tres-error-retry {
    background: #4a4a4a;
    border: none;
    color: white;
    padding: 0.5rem 1rem;
    margin-top: 1rem;
    cursor: pointer;
  }
`

Opt-in vs Opt-out Discussion

Opt-in Approach

<!-- Explicit opt-in -->
<TresCanvas :error-boundary="true">
  <!-- Scene content -->
</TresCanvas>

Pros:

• More explicit and intentional usage
• Smaller initial bundle size (code-splitting possible)
• Developers consciously choose when to use error boundaries
• Better control over error handling strategies

Cons:

• Requires additional configuration for each TresCanvas instance
• May lead to inconsistent error handling across the application
• Developers might forget to add error boundaries where needed

Opt-out Approach

<!-- Error boundaries enabled by default -->
<TresCanvas>
  <!-- Scene content -->
</TresCanvas>

<!-- Explicit opt-out -->
<TresCanvas :error-boundary="false">
  <!-- Scene content -->
</TresCanvas>

Pros:

• Better developer experience out of the box
• Consistent error handling across the application
• Safer default behavior
• Less configuration needed

Cons:

• Slightly larger initial bundle size
• May be unnecessary for simple scenes
• Less explicit about error handling behavior

Alternative

No response

Additional context

Questions for Discussion

1. Should error boundaries be opt-in or opt-out by default?
2. What additional information would be helpful in the error display?
3. Should we provide different error displays for development and production?
4. How should we handle WebGL-specific errors differently from Vue component errors?

Feel free to share your thoughts and suggestions on this proposal!

Validations

• I agree to follow this project's Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.