WebGPU pixel look: GPU colours the world, CPU only rare cells (t88 phase 2a)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/PROJECT_MAP.md

@@ -162,6 +162,13 @@ The frame loop applies speed and queued steps while keeping the per-frame tick l
   - On software GL it falls back to pixels, unless `window.__allowSoftwareGL` is set (the test
     tools set it).
 
+The pixel look can use WebGPU (`src/render/gpu/`): whole-world textures receive visible
+strided uploads, `colour.js` colours plain grains, and `draw.js` selects rare CPU override
+blocks and submits colour, bloom and drawing. `cell.js` shares the original CPU cell rules
+between Legacy/Smooth and those overrides; `objects.js` adds bars, flyers and blueprint ghosts.
+The GPU canvas sits behind the transparent game canvas, which draws all existing overlays.
+CPU lighting stays in `light.js`. `SET.renderer` selects WebGPU or Legacy; Smooth uses WebGL2.
+
 ## The browser shell
 
 - `GAME` (`src/ui/state.js`) holds the UI state: tool, selected piece, build tab, drag,
@@ -406,7 +413,37 @@ Screw casing geometry shared by both looks, ghosts and placement previews. smoot
 - functions: diagonalScrewJoins, straightScrewJoins, diagonalScrewShape, diagonalScrewBlock
 - variables: SCREW_CLASS, diagonalJoins, diagonalAcross, diagonalAlong, diagonalCap
 
-### src/render/world.js (419 lines)
+### src/render/cell.js (272 lines)
+Shared CPU colour rules, used by legacy and the rare-cell WebGPU override.
+- functions: cellPixel
+
+### src/render/objects.js (80 lines)
+Loose bars, flying grains and queued blueprint blocks in the grain buffer.
+- functions: worldObjects
+
+### src/render/gpu/colour.js (82 lines)
+The plain-cell rules mirror cellPixel; built geometry stays in the CPU override.
+- variables: GPU_COLOUR
+
+### src/render/gpu/shaders.js (42 lines)
+Half-resolution separable Gaussian bloom, then nearest colour + linear light.
+- variables: GPU_BLUR, GPU_DRAW
+
+### src/render/gpu/device.js (43 lines)
+Async startup shares the title screen's adapter; failures leave a usable legacy renderer.
+- functions: gpuInit, gpuFail, worldPixelContext
+- variables: GPU
+
+### src/render/gpu/textures.js (84 lines)
+Whole-world allocation, direct strided uploads; no cell packing or dirty tracking.
+- functions: gpuTexture, gpuWrite, gpuBuffer, gpuWorldTextures, gpuViewTextures, gpuBindings, gpuUpload
+
+### src/render/gpu/draw.js (69 lines)
+Only exceptional blocks and their geometric neighbours run the CPU colour rules.
+- functions: gpuOverrides, gpuDraw, gpuPresent
+- variables: GPU_PATTERN
+
+### src/render/world.js (83 lines)
 Scale colour without changing the smooth-look class.
 - functions: fogColor, drawWorld
 
@@ -442,7 +479,7 @@ Game shell (src/ui/): browser only. This file: settings, the GAME state object,
 - functions: loadSettings, saveSettings, el, esc, rgbOf, fmtT, toast, setStatus
 - variables: SET_DEFAULT, SET, TOOLS, ICONS, BAG_ORDER, GAME, keys, hudDirty, $
 
-### src/ui/title.js (74 lines)
+### src/ui/title.js (76 lines)
 Startup capabilities and title art.
 - functions: checkCapabilities, renderCapabilityNotice, canStartGame, buildTitleCells, drawTitle
 - variables: REQUIRE_GPU_AND_THREADS, CAPS, CAPS_CHECK, FONT5, TITLE
@@ -461,7 +498,7 @@ Shared player state; the world save remains a complete standalone fallback.
 Starting, loading and quitting a game; modal dialogs; the pause menu.
 - functions: showLoading, enterGame, setupNewWorld, startNewWorld, startFromSave, loadSavedWorld, quitToTitle, refreshContinue, anyModal, openModal, closeModal, closeAllModals, topModal, dialog, openPause, renderWorlds
 
-### src/ui/settings.js (125 lines)
+### src/ui/settings.js (126 lines)
 The settings screen.
 - functions: openSettings, renderSettings, applySettings, toggleFullscreen, confirmWipe
 - variables: SET_TABS, setTab
@@ -585,6 +622,7 @@ The frame loop and boot.
 - `test/t_flow.js`: Throughput overlay (t49): grains per second per transport block, counted only while the overlay is on, never changing what the simulation does.
 - `test/t_fog.js`: Fog: surface, sight, range, saves and simulation independence.
 - `test/t_furnace_repeat.js`: The starter furnaces keep working when fired again and again without cleaning, however the charge goes in: mixed, ore first with coal on top, or blown in through the vent. Each case plays furnace_play.js, which builds the design and fires it like a player.
+- `test/t_gpu.py`: WebGPU pixel parity, rare-cell selection, world replacement, resize and device loss.
 - `test/t_joins.js`: The oracle states the geometric rule independently of the precomputed neighbour tables.
 - `test/t_light.js`: Run the renderer's lighting against real simulation data, with only canvas storage stubbed.
 - `test/t_load.js`: Reload wakes nearby areas first, without losing distant water, fire or saved state.
@@ -641,3 +679,4 @@ The frame loop and boot.
 - `tools/scenes/t35-joins.js`: Run after clear-sky.js. Paused, empty pipes make casing, flights and mouths easy to inspect.
 - `tools/scenes/t36-funnel.js`: A twelve-block funnel, one block open at the bottom, draining 400 grains of sand.
 - `tools/scenes/t40-sloped-belt.js`: Self-contained: a flat feed climbs, crosses the top, and runs downhill; a filter sorts below.
+- `tools/scenes/t88-renderer.js`: Paused comparison scene: ordinary grains, fog, heat, trees and exceptional geometry.