feat(loop): add handleLoopError escape hatch; never crash the render loop

[chiefcll]

Summary

Adapts the idea behind upstream lightning-js/renderer#819 to this fork: a render loop that never crashes on client-code errors, plus an optional handleLoopError callback to observe them.

The render loop runs client-supplied code every frame — synchronous event subscribers (frameTick, idle, and the queued events drained by flushFrameEvents) and animation steps. If any of these throw, the exception would otherwise propagate out of the requestAnimationFrame callback and permanently stop the loop — the whole app freezes until reload.

What changed

• WebPlatform.startLoop — wraps the frame body in try/catch and always keeps the loop alive. A throw is routed to handleLoopError and the loop reschedules.
• RendererMainSettings — adds optional handleLoopError?: (error: unknown) => void, defaulting to a no-op. So out of the box a bad frame is swallowed and the loop survives; apps can override the handler to log/report (and optionally recover). Threaded through to StageOptions and read in the loop via stage.options.handleLoopError.

Behaviour

handleLoopError	On a frame throw
not provided (default no-op)	error swallowed, loop keeps running
provided	handler called with the error, loop keeps running

The loop never rethrows — a single bad frame can't freeze the app.

Divergence from upstream

• This fork's Platform is a thin abstract class (no settings/PlatformSettings), so upstream's settings-plumbing refactor was intentionally not ported — only the resilience feature.
• Upstream rethrows when no handler is set; here the default is a no-op so the loop is crash-proof by default.
• A scheduled flag prevents double-scheduling: the fork's idle path queues its next tick (setTimeout) before running the throwing client code, so the catch must not also queue a frame. Without this, a handler that throws every idle frame would compound into runaway frames. (Upstream's variant has this latent double-schedule.)

Notes / scope

This fork's animation-finish path is promise-based (microtask), so it surfaces as an unhandled rejection rather than an rAF crash. The real synchronous freeze vectors this guards are the frameTick/idle/flushFrameEvents emits.

Usage

const renderer = new RendererMain(
  {
    appWidth: 1920,
    appHeight: 1080,
    // optional — defaults to a no-op; the loop survives either way
    handleLoopError: (error) => {
      reportToTelemetry(error);
    },
  },
  'app',
);

Test plan

• WebPlatform.loopError.test.ts covers: handled active-frame error + reschedule, default (no handler) swallows error + loop survives, idle-path double-schedule guard, and a clean frame.
• Full unit suite: 267 passed (33 files), including existing WebPlatform context-loss/OOM tests.
• tsc --build clean; changed files lint-clean.

🤖 Generated with Claude Code