0002: A small software renderer instead of WebGL / three.js

• Status: accepted
• Date: 2026-10-23

Context

The harness is meant to be browser-first, with a sandbox for watching progress, and agents (Codex, Claude) must be able to run the same pipeline headless in CI. The main dev machine is a 2012 iMac on the nouveau driver, where WebGL pages have frozen the whole machine before.

Decision

src/core/render.js is a plain-JS z-buffered rasterizer with flat shading and a light-space shadow map. It is used in the browser and in Node.

Consequences

• Output is byte-identical in the browser, in Node and in CI, so gates and gallery diffs mean something.
• No GPU is involved, which is safe on the dev box and works in any CI runner.
• No dependencies: three.js isn't needed to render.
• It's slower than a GPU. Sprites are tiny, so a 2 × 2 asset with all four views builds in about 0.4 s. Larger tiles or model import may need a Web Worker (M6).
• Features like textures, interior outlines and animation are ours to write (M7, M8). Parsing GLB files can still borrow a loader without rendering through WebGL.