Chapter 31 Web and DOM Renderers

The renderer obtains canvas.getContext(’2d’) and maps texture uploads and sprite operations onto drawImage, putImageData, and fillRect. A 2D render target is another Canvas2D surface. There is no shader stage, depth buffer, MRT, occlusion query, or 3D path; inherited effect-aware draws terminate in the explicit 3D refusal.

Only additive blending is reported among the 13 capability flags. That narrow switch is more useful than the renderer contract’s default-true policy because callers do not have to discover the 2D ceiling by constructing unsupported objects.

HTML_DOM does not rasterize every sprite into one surface. It maintains a pool of DOM elements, assigns image content, and expresses destination position, scale, rotation, origin, opacity, crop, and visibility through CSS and element properties. Reusing nodes avoids unbounded allocation as the visible sprite set changes frame to frame.

This representation makes browser layout and compositing part of the renderer contract. Ordering becomes DOM stacking order, transforms use CSS conventions, and additive blending depends on browser support for plus-lighter. The renderer therefore cannot promise one identical native blend implementation across browser versions.

Its off-screen target is DOM-backed, not a GPU framebuffer. MRT and queries are absent. The inherited 3D route reaches a local unconditional throw and bypasses the common WarnAndStub policy, so diagnostic configuration cannot turn that refusal into a warning-only placeholder.

SVG_DOM creates SVG image nodes and uses SVG transforms for sprite placement. Tinting is expressed through a real feColorMatrix filter rather than by rewriting texture pixels. Additive sprites set mix-blend-mode: plus-lighter; the capability query returns the running browser’s CSS.supports answer, just as HTML_DOM does. The retained tree is inspectable and naturally matches vector composition, but it inherits SVG’s filter, sampling, blending, and browser-layout semantics.

Like HTML DOM, it owns a DOM off-screen target, has no MRT or queries, and its 3D refusal bypasses WarnAndStub. Its browser smoke page checks raw CSS support, the public capability answer and the emitted sprite style together, and separate screenshot fixtures cover pixels and scissor order. Its verification tier nevertheless remains weaker: the native host target is behind an off-by-default CNA_BUILD_SVG_DOM_HOST_TESTS option, and no CI workflow drives either it or the browser pages. A runnable browser script is a real test route, not evidence that the route currently gates changes.

PIXIJS is Emscripten-only and resolves a pinned PixiJS 7.4.2 UMD artifact with a recorded SHA-256; automatic download is on unless CNA_PIXIJS_ROOT supplies the file. It maps textures, SpriteBatch/SpriteFont draws, transforms, scissor, blend state and one active RenderTarget2D to PixiJS objects. The browser library may use WebGL internally, but the CNA identity remains PIXIJS and its contract is the 2D adapter, not CNA’s WEBGL2 family.

MRT, mip levels above zero, 3D, custom/compiled effects, cube and volume textures, cube targets and occlusion queries are explicit refusals. Render textures make its off-screen route stronger than NanoVG’s, while more than one simultaneous target still throws. Browser execution must prove the resolved library, object lifetime and final pixels; a successful Emscripten link alone does not.

Older editions paired Canvas with an ASCII renderer. That public identity and its selector are gone. The reusable quantization logic now lives in CNA::Graphics::AsciiPostProcessEffect; Appendix E records the current CNAEXT surface. Historical architecture is not a fourth row in the live renderer registry.

The four families can display an identical sprite scene while failing in different places:

• •

  Canvas failures cluster around pixel upload, context state, clipping, and immediate compositing;

• •

  HTML DOM failures cluster around pooling, CSS transforms, stacking, and browser blend support;

• •

  SVG DOM failures cluster around retained-node lifetime, SVG transforms, filters, and sampling.

• •

  PixiJS failures cluster around UMD artifact resolution, Pixi object/render-texture lifetime, batching, and the browser driver selected below the library.

A useful cross-renderer scene therefore includes crop, origin-centred rotation, alpha and additive overlap, clipping, target bind/unbind, and node-count stability over several frames. Inspect both structure and final pixels: the DOM can look mechanically correct while the browser composites a different color, and a correct screenshot can hide unbounded node growth.

Record the CNA identity, Emscripten version, browser and browser version, device-pixel ratio, canvas/SVG dimensions, and whether execution was visible or headless. Confirm that the page reaches multiple animation frames and that the observable is meaningful for the feature under test. Browser compilation is only the first gate; these renderers exist in the DOM that runs after it.