# Metaverse WebGL Engine Integration

This document describes the unified WebGL engine adapter that now powers the
metaverse surfaces. The adapter abstracts Three.js and Babylon.js initialization
while guaranteeing WebGL 2.0 capability negotiation and graceful fallbacks for
older hardware.

## Engine Adapter Overview

`web/src/lib/webgl-engine-adapter.ts` centralises all canvas bootstrapping
logic. It:

- Detects WebGL 2.0 support with automatic downgrade to WebGL 1.0 if required.
- Creates a configured Three.js renderer and scene when
  `engineType === 'three'`.
- Lazily loads Babylon.js when requested, returning an engine + scene handle for
  future Babylon-based experiences.
- Normalises teardown through a shared `dispose()` method so UI surfaces can
  release GPU resources reliably.

### Usage

```ts
import { initialize3DEngine } from '../lib/webgl-engine-adapter';

const handle = await initialize3DEngine(canvas, {
  preferredEngine: 'auto',
  preferredWebGLVersion: 2,
  antialias: true,
  alpha: false,
  powerPreference: 'high-performance',
});

if (handle.engineType === 'three') {
  const { scene, renderer } = handle;
  // customise scene, attach cameras, etc.
} else {
  const { engine, scene } = handle;
  // experimental Babylon.js pathway.
}
```

The adapter always records the negotiated WebGL version (`handle.webglVersion`)
for diagnostics and debug overlays.

## MetaverseCanvas Integration

`web/src/components/MetaverseCanvas.tsx` now boots through the adapter:

- New props `enginePreference` and `preferredWebGLVersion` allow runtime
  selection between Three.js, Babylon.js, or automatic detection.
- Engine diagnostics (engine type + WebGL version) surface in debug mode to aid
  QA and hardware validation.
- Cleanup delegates to the adapter’s `dispose()` routine which in turn releases
  renderer, scene materials, and Babylon engines when in use.
- Spatial audio, accessibility, content browser, and avatar subsystems continue
  to initialise once the Three.js handle is ready; Babylon initialisation
  currently stops after providing the engine handle while we build out
  Babylon-native scenes.

## Babylon.js Dependency

The web client now ships with `@babylonjs/core` as a production dependency.
Local development requires running `npm install` inside `web/` to ensure the
Babylon modules are available for dynamic import.

> **Tip:** If you prefer to keep bundle sizes minimal during experimentation,
> set `enginePreference="three"` to skip Babylon runtime loading.

## Testing

Dedicated Vitest coverage (`web/src/lib/__tests__/webgl-engine-adapter.test.ts`)
verifies:

- WebGL 2.0 detection and manual fallback to WebGL 1.0 contexts.
- Adapter orchestration for Three.js renderer creation with expected options.
- Babylon.js initialisation and disposal contracts when explicitly requested.

Component tests (`web/src/components/__tests__/MetaverseCanvas.test.tsx`) mock
the adapter to confirm UI wiring without requiring actual WebGL contexts.

## Next Steps

- Flesh out Babylon.js scene scaffolding that mirrors existing Three.js sacred
  environments.
- Extend automated QA flows to collect adapter diagnostics across supported
  browsers/GPUs.
- Consider promoting `detectWebGLSupport` into a shared platform utility for
  other surfaces (e.g., meditation visualisers, audio visualisations).
