feat(webgl): detect GPU out-of-memory and emit an outOfMemory event

[chiefcll]

Problem

On image-heavy pages, some devices log a flood of Could not create WebGL Texture (one device at a time). The root cause isn't createTexture running out of memory — createTexture only allocates a handle. It's a lost context: a texImage2D GPU out-of-memory escalates to context loss, after which every gl.createTexture() returns null, producing the flood.

The renderer had no way to detect the originating GPU out-of-memory. WebGL only exposes it via gl.getError() (GL_OUT_OF_MEMORY), which this engine deliberately checks only in dev builds because getError() forces a CPU/GPU sync. So in production the OOM was invisible until it had already become a dead context.

What this adds

A GPU out-of-memory probe surfaced as an application event, so the app can recover (e.g. reload with a lower criticalThreshold).

• WebGlRenderer.checkForOutOfMemory() — drains the GL error queue (bounded to keep the sync cost fixed) and returns whether GL_OUT_OF_MEMORY was seen. checkForOutOfMemory is now a required CoreRenderer method; CanvasRenderer returns false (no GPU OOM signal on Canvas2D).
• Runs at the idle transition, not every frame. GL errors accumulate and persist until drained, so a single check when the render burst settles still catches any OOM raised during the active frames — without paying the getError() sync per frame. (Tradeoff: an app that never goes idle won't fire the probe until it settles; the error stays queued until then.)
• TextureMemoryManager.handleOutOfMemory() queues an outOfMemory frame event ({ memUsed, criticalThreshold }) and requests a best-effort cleanup of non-renderable textures.

Policy lives in the app, not the renderer

The renderer only detects and reports. Persisting/lowering the threshold and reloading is application policy. RendererMainOutOfMemoryEvent carries a full recommended-integration snippet in its docs:

• Read a calibrated criticalThreshold from localStorage on startup, namespaced per app (important for file:// TV deployments where the origin is null/opaque and a bare key collides across apps).
• On outOfMemory, lower to 90% of the measured ceiling (min(memUsed, criticalThreshold)) with a floor, persist, and location.reload().

memUsed at the time of the failure is a measured ceiling — the real GPU budget is at or below it — which is why it's a good basis for the next threshold.

Reviewer notes

• emit invokes listeners as (target, data); the new event docs and examples use that signature.
• No persistence/localStorage code in the renderer itself — intentionally pushed to the app.
• checkForOutOfMemory being abstract means a future backend that forgets to implement it is a build error, not a silent skip.

Tests

• TextureMemoryManager.test.ts — outOfMemory event payload, cleanup request, threshold left unchanged, fresh estimate per fire.
• WebPlatform.outOfMemory.test.ts — probe fires once at the idle transition, handles OOM when reported, and does not probe on an active frame.
• Full suite: 262 passing. Build, prettier, eslint clean.

🤖 Generated with Claude Code