Render on demand instead of every frame

[sophiedeziel]

Closes #354

What

SceneManager used to re-arm a requestAnimationFrame loop from its constructor and redraw the scene on every display frame, whether or not anything changed. On the 3.5 MB 3DBenchy that cost ~0.9 ms CPU per frame, 804k triangles and 34 draw calls — roughly 54 ms/second of main-thread time and ~48M triangles/second to redraw a still image for as long as the tab stayed open.

This replaces the perpetual loop with on-demand rendering:

• A public requestRender() schedules a single frame on the next animation frame and coalesces any burst of changes into one draw. An idle scene now draws zero frames.
• Camera movement requests frames through the OrbitControls change event, so dragging still renders at full rate. The listener is re-bound when the orthographic swap replaces the controls instance.
• Every code path that changes the picture in place now requests a frame: background / extrusion / travel / bounding-box colors, build volume, start/end layer, single-layer mode, extrusion/travel visibility, ambient/directional light, brightness, resize(), clear(), and renderProgressive() while a stream is being read.
• Changes that rebuild geometry (line width/height, extrusion width, tubes/lines swap, top-layer and last-segment highlights, gradient toggle) keep drawing synchronously through the existing render() path, unchanged.
• The camera is aimed at its target with a single controls.update() at construction. enableDamping and autoRotate are both off in this project, so nothing needs a per-frame update() and nothing self-animates.
• renderAnimated() / renderFrameLoop keep their own legitimate frame loop while geometry streams in; it still terminates when the last path is drawn.

Behavior notes

• requestRender() is the new supported way to present externally-made scene changes. The public animate() stays for compatibility as a @deprecated alias: it delegates to requestRender(), so one call schedules (at most) one coalesced frame and it no longer re-arms a continuous loop.
• onFrameRendered — and the dev-mode stats FPS panel it feeds — now counts renders per second: it reads 0 while the scene is idle instead of the display refresh rate. Documented on both hooks.

Tests

• New on-demand rendering suite: constructor schedules exactly one initial frame, idle draws nothing, controls change triggers a frame, bursts coalesce into a single draw, every visual setter requests a frame, the orthographic swap keeps camera movement rendering, renderProgressive/clear present their results, and a geometry rebuild with no job presents the emptied scene.
• Mock-based tests cover coalescing, going idle after one frame, and dispose() cancelling a pending frame.
• Full suite: 825 tests passing, 100% statements/branches/functions/lines coverage, typecheck and lint clean.

Measurements

Demo app with 3DBenchy.gcode (3.7 MB), fresh rollup builds of both branches, Chrome 152 on Apple Silicon. DevTools performance traces over a strictly idle 10 s window after the load fully settled, with the dev GUI panels hidden.

Metric (10 s idle)	develop @ 91a063a	PR @ 43598fc
renderer frames	596–600 (~60 fps)	0
main-thread busy	908 ms (9.1%)	190 ms (1.9%)
— of which FireAnimationFrame	797 ms	147 ms
triangles per rendered frame	753,448	753,448
draw calls per rendered frame	38–48	38
total frames, load → steady state	1,249+	69–71

Caveats, in the interest of honesty:

• The residual 190 ms on the PR build is the demo's devMode lil-gui rAF polling, which is identical in both versions — the renderer itself contributes 0 frames.
• Draw calls varied 38↔48 across develop loads at a constant triangle count because streamed progressive loading batches meshes nondeterministically. Triangles per frame are bit-identical, so what is drawn is unchanged — only how often.

Sanity checks: a 30-event orbit drag rendered exactly 30 coalesced frames and then returned to 0 idle; a forced requestRender() advanced the frame counter by exactly 1; before/after screenshots are visually identical.

Out of scope

The draw-call consolidation noted under "Related" in #354 (progressive rendering fragmenting the scene into ~61 chunk groups) is deliberately not part of this PR.

Assisted by Claude Code - Fable 5