# Factorizing the light

FMVisual starts with an original procedural scene and Three.js r186 VXGI. The goal is to expose and eventually replace each rendering stage independently, with measured evidence that its replacement works. The current renderer is an integration baseline; it is not an independently implemented voxel renderer.

## Contracts and order

| Stage | Input → output | Current implementation | Replacement gate |
| --- | --- | --- | --- |
| Geometry | meshes, materials, lights → world bounds and triangles | FMVisual procedural worlds | Stable triangle counts, transforms and material fixtures |
| Occupancy | triangles + bounds → voxel coverage and surface attributes | Three.js VXGI | Conservative coverage, thin-wall and boundary fixtures |
| Radiance | occupied surfaces + lights → lit voxel values | Three.js VXGI | Neutral, coloured, emissive and shadow fixtures |
| Hierarchy | radiance + opacity → directional filtered levels | Three.js VXGI | Energy and directional continuity across levels |
| Tracing | depth, normals + hierarchy → irradiance and visibility | Three.js VXGI | Analytic occlusion and diffuse comparisons |
| Resolve | irradiance, material, motion → stable displayed pixels | Three.js + TRAA | No stale history after camera, scene or lighting changes |

The first engineering milestone is an explicit backend interface around the upstream implementation. Then implement occupancy, injection, hierarchy and tracing behind the same interface. Keep the baseline selectable until each replacement passes its isolated fixtures and scene comparisons. Resolve and lifecycle changes follow the relevant inputs; avoid changing all stages in one patch.

## Work graph

The central Tracker Desk project is the authoritative work graph. Its task IDs cover:

- FMV-1–3: runnable baseline, this decomposition, and browser commissioning.
- FMV-4–7: backend contracts, geometry extraction, conservative occupancy and voxel inspection.
- FMV-8–11: radiance injection, directional hierarchy, cone integration and temporal history.
- FMV-12–16: resource lifecycle, GPU measurements, comparison fixtures, backend integration and replay.
- FMV-17–18: optional imported assets and browser/release qualification.

Geometry fixtures and benchmark design can advance separately once the contracts are established. Injection depends on occupancy; hierarchy depends on injection; tracing depends on hierarchy. Resource cleanup and browser qualification are gates throughout. Autopilot is off; readiness of a task does not authorize starting paid infrastructure.

## Measurement protocol

Use all three deterministic scenes at 48, 80 and 128 grid resolution, with fixed camera, sun, exposure and indirect strength. Record browser, adapter, viewport, device pixel ratio, backend and settings alongside captures. Compare direct, combined, indirect, visibility and voxel debug outputs. Treat debug images as upstream visualizations until explicit world-space slices are implemented.

Collect GPU timestamps only when the adapter exposes timestamp-query. Label wall-clock frame intervals separately; the initial FPS readout is not GPU timing. Record warm-up, sample count, median and p95 plus memory estimates by grid and mip level. Look for light leakage, incorrect colour transfer, missing thin surfaces, temporal smearing and discontinuities when moving across voxel boundaries. Performance targets must follow a measured adapter baseline, rather than inventing universal FPS guarantees.

## Completion gates

A replacement requires deterministic unit fixtures, a real WebGPU scene comparison, a documented quality/performance tradeoff, and repeated create/switch/dispose checks. A WebGL direct-light preview does not qualify voxel GI. External GLTF import is optional and follows the controlled procedural tests. Settings export exists in the baseline; import and versioned replay remain planned.

## Framework seam now implemented

The local `src/framework/index.js` entry point accepts scene factories, quality presets and settings independently of the lab UI. Direct and upstream VXGI adapters share a versioned lifecycle contract. See [FRAMEWORK.md](FRAMEWORK.md). Individual transport algorithms still belong to Three.js and remain future replacement work.

## Architectural priority

FMV-19 adds the original Woven atrium, procedural PBR surfaces, interior camera studies, stable slow passage and upstream temporal/bounce/bloom controls. FMV-20–22 track shadow-aware volumetric shafts, measured specular reflections and dedicated architectural-motion quality evaluation. The current visual study is the testbed for these techniques; their dedicated acceptance gates remain open.

## First radius

FMV-24 adds one connected lantern passage and sun court. The original atrium's geometry is retained as a deterministic fixture, while voxel and shadow coverage grow at preserved spatial density. Further substantial growth requires lighting zones; see [EXPANSION-01.md](EXPANSION-01.md).