rayzee 10.0.0 → 11.1.0

package/README.md

@@ -21,6 +21,8 @@ A real-time WebGPU path tracing engine built on Three.js. Framework-agnostic —
 - [API Reference](#api-reference)
   - [Configuring Assets (CDN URLs & cache namespace)](#configuring-assets-cdn-urls--cache-namespace)
   - [PathTracerApp](#pathtracerapp)
+  - [Renderer core (`rayzee/core`)](#renderer-core-rayzeecore)
+    - [Add-ons](#add-ons)
   - [engine.cameraManager](#enginecameramanager)
   - [Camera Projection (Orthographic, 360° Panorama)](#camera-projection-orthographic-360-panorama)
   - [engine.lightManager](#enginelightmanager)
@@ -39,6 +41,9 @@ A real-time WebGPU path tracing engine built on Three.js. Framework-agnostic —
   - [Memory Monitoring](#memory-monitoring)
   - [Logging](#logging)
   - [Deterministic & Headless Rendering](#deterministic--headless-rendering)
+  - [On-disk Storage (OPFS)](#on-disk-storage-opfs)
+  - [Saving Scene State](#saving-scene-state)
+  - [Render Checkpoints](#render-checkpoints)
   - [Events](#events)
   - [Advanced: Custom Pipeline Stages](#advanced-custom-pipeline-stages)
   - [All Exports](#all-exports)
@@ -55,7 +60,7 @@ A real-time WebGPU path tracing engine built on Three.js. Framework-agnostic —
 npm install rayzee three
 ```
 
-`three` (>=0.185.0) is a required peer dependency.
+`three` (>=0.186.0) is a required peer dependency.
 
 ## Getting Started
 
@@ -137,10 +142,10 @@ A single HTML file — no Node.js, no build step. Uses [ES module import maps](h
   <script type="importmap">
   {
     "imports": {
-      "three": "https://cdn.jsdelivr.net/npm/three@0.185.0/build/three.webgpu.js",
-      "three/tsl": "https://cdn.jsdelivr.net/npm/three@0.185.0/build/three.tsl.js",
-      "three/webgpu": "https://cdn.jsdelivr.net/npm/three@0.185.0/build/three.webgpu.js",
-      "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.185.0/examples/jsm/",
+      "three": "https://cdn.jsdelivr.net/npm/three@0.186.0/build/three.webgpu.js",
+      "three/tsl": "https://cdn.jsdelivr.net/npm/three@0.186.0/build/three.tsl.js",
+      "three/webgpu": "https://cdn.jsdelivr.net/npm/three@0.186.0/build/three.webgpu.js",
+      "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.186.0/examples/jsm/",
       "oidn-web": "https://cdn.jsdelivr.net/npm/oidn-web@0.4.0/dist/oidn.js",
       "rayzee": "https://cdn.jsdelivr.net/npm/rayzee/dist/rayzee.es.js"
     }
@@ -306,7 +311,7 @@ All keys are optional — only what you pass is overridden. Call `getAssetConfig
 
 ### PathTracerApp
 
-The main engine class. Extends Three.js `EventDispatcher`. Related functionality is grouped into **namespaced managers** accessed via `engine.cameraManager`, `engine.lightManager`, etc., or as direct methods on the engine instance.
+The main engine class. Extends `RayzeeRenderer`, the [renderer core](#renderer-core-rayzeecore), which extends three.js's `EventDispatcher`. Related functionality is grouped into **namespaced managers** accessed via `engine.cameraManager`, `engine.lightManager`, etc., or as direct methods on the engine instance.
 
 ```js
 const engine = new PathTracerApp(canvas, options?)
@@ -320,7 +325,6 @@ const engine = new PathTracerApp(canvas, options?)
 | `options.autoResize` | `boolean` | Auto-resize on window resize (default: `true`; always off headless) |
 | `options.container` | `HTMLElement` | Single DOM parent the engine mounts auxiliary elements into — HUD overlay (tile borders, helpers) and denoiser canvas. Defaults to `canvas.parentNode`. |
 | `options.strict` | `boolean` | Throw an `EngineIssueError` where the engine would otherwise degrade and carry on (default: `false`). See [Degradation contract](#degradation-contract). |
-| `options.profile` | `string` | `'viewer'` (default) or `'physical'` — product tuning that is not a physical constant: area-light scale, environment rotation, tone mapping, saturation. An unknown name throws. |
 | `options.maxSceneBytes` | `number` | Raise or lower the CPU memory ceiling a scene may need before the engine refuses it (default 9,216 MB). See [Memory monitoring](#memory-monitoring). |
 | `options.hostMemoryGB` | `number` | The host's memory, for runtimes without Chrome's `navigator.deviceMemory` (which then read as 4 GB and cap the render reserve at 2048). Sizes the reserve and the path pool. |
 | `options.storage` | `false \| 'auto' \| StorageManager` | On-disk storage (default: `configureAssets( { storage } )`; off under `strict` unless you set it there or here). A manager you pass stays yours to dispose. See [On-disk storage](#on-disk-storage-opfs). |
@@ -346,12 +350,15 @@ Constructing a new `PathTracerApp` on a canvas that already has an active instan
 #### Loading Assets
 
 ```js
-await engine.loadModel(url)                  // Load GLB/GLTF/FBX/OBJ/STL/PLY/DAE/3MF/USDZ/ZIP
+await engine.loadModel(url)                  // Load a GLB/GLTF by URL
+await engine.loadFile(fileOrUrl)              // Any supported file: GLB/GLTF/FBX/OBJ/STL/PLY/DAE/3MF/USD/USDZ, archives, HDR/EXR
 await engine.loadObject3D(object3d, name?)    // Load a Three.js Object3D directly (name is optional, defaults to 'object3d')
 await engine.loadEnvironment(url)             // Load HDR/EXR environment map
 engine.cancelLoad()                           // Abort an in-flight download (network phase only; no-op once processing starts)
 ```
 
+On `rayzee/core`, formats other than glTF and `.hdr` need the `rayzee/addons/formats` add-on — see [Add-ons](#add-ons).
+
 `loadModel` / `loadObject3D` **replace** the current scene. To add or remove objects from a live scene without a full reload (and without reframing the camera):
 
 ```js
@@ -368,6 +375,8 @@ engine.setSceneObjectVisibility(id, visible)                      // Toggle visi
 
 ##### Loading part of a scene archive
 
+On `rayzee/core`, archives and pbrt need the `rayzee/addons/archives` add-on — see [Renderer core](#renderer-core-rayzeecore).
+
 A pbrt-v4 scene archive (`.tar`, `.tar.gz`, `.zip`) is usually a root `.pbrt` file that includes one
 subtree per element, and the whole thing rarely fits in a browser tab — Moana is 29 GB unpacked.
 The archive can be inspected without retaining any of it, then loaded one element at a time:
@@ -435,15 +444,19 @@ Key settings:
 | `enableEnvironment` | `boolean` | true | Use environment lighting |
 | `environmentIntensity` | `number` | 1.0 | Environment light strength |
 | `environmentRotation` | `number` | 0 | Environment Y-rotation (degrees); 0 shows the HDRI as authored, as Blender's unmapped world does |
+| `areaLightIntensityScale` | `number` | 0.1 | Power of a glTF model's placeholder area lights (RectAreaLight extras), read when the model loads, so set it first; 1 is the authored power |
+| `maxTextureSize` | `number` | 4096 | Longest edge of a material texture, read when a model loads (clamped to the hardware ceiling); `setMaxTextureSize()` applies it to the current scene too |
+| `wavefrontSortMaterials` | `boolean` | true | Sort rays by material before shading, above 8 materials; read when the shaders next build |
 | `showBackground` | `boolean` | true | Show the environment as a visible backdrop for camera-miss rays (vs. a solid/transparent background) |
 | `samplingTechnique` | `number` | 2 | Sampler: `0` PCG, `1` scrambled Halton, `2` Owen-scrambled Sobol |
+| `integrator` | `string` | 'path' | `'path'` \| `'bidirectional'` \| `'vcm'` (on the core, needs the bidirectional add-on). Bidirectional also traces light subpaths from every light — emissive surfaces, rect/disk, point, spot and directional lights, the sun and the environment — far faster for caustics and light through small openings, about 2× the cost per sample. On a lamp-lit interior with an HDRI it is ~20 % less noisy at equal time; a room lit only through a window stays better path traced. `'vcm'` adds photon merging, for caustics seen in mirrors and through glass. Switching rebuilds the kernels |
 | `fireflyThreshold` | `number` | 3.0 | Firefly clamping threshold |
 | `shadowTerminatorOffset` | `number` | 0.1 | Cycles' Shadow Terminator → Geometry Offset: near the light's terminator on a smooth-shaded low-poly mesh, light and environment shadow rays start on the smooth surface the vertex normals describe, not the flat facet. Blender's default; `0` disables |
 | `transmissiveBounces` | `number` | 5 | Max bounces for transmissive materials |
 | `maxSubsurfaceSteps` | `number` | 8 | Max random-walk steps for subsurface scattering (raised to 64 by `configureForMode('production')`) |
 | `enableAlphaShadows` | `boolean` | false | Alpha-tested shadow rays (enabled by `configureForMode('production')`) |
 | `enableDOF` | `boolean` | false | Enable depth of field |
-| `dofMode` | `string` | 'look' | `'look'`: the blur is set by `dofBlur`, the same at any scene scale; `'physical'`: a real lens set by `aperture`, `focalLength` and `unitsPerMetre`. The `physical` render profile defaults to `'physical'` |
+| `dofMode` | `string` | 'look' | `'look'`: the blur is set by `dofBlur`, the same at any scene scale; `'physical'`: a real lens set by `aperture`, `focalLength` and `unitsPerMetre`. |
 | `dofBlur` | `number` | 0.05 | Look mode: how far a distant background blurs, as a fraction of the image height |
 | `focusDistance` | `number` | 0.8 | DOF focus distance in scene units — depth along the view axis (the focal plane is flat) |
 | `aperture` | `number` | 5.6 | Physical mode: f-stop |
@@ -451,23 +464,23 @@ Key settings:
 | `unitsPerMetre` | `number` | 1 | Physical mode: scene units per real metre, for files whose units are not metres. It carries over between model loads — reset it when the new file's units differ |
 | `transparentBackground` | `boolean` | false | Transparent canvas background |
 | `interactionModeEnabled` | `boolean` | true | Render at lower resolution while the camera moves, keeping the full bounce budget ("Fast Navigation" in the app) |
-| `interactionRenderScale` | `number` | 0.5 | Per-axis render scale while the camera moves (0.5 = a quarter of the pixels); `1` turns the drop off. Ignored while OIDN is the live denoiser |
+| `interactionRenderScale` | `number` | 0.5 | Per-axis render scale while the camera moves (0.5 = a quarter of the pixels); `1` turns the drop off. Ignored while OIDN is the live denoiser. `PathTracerApp` only |
 | `renderMode` | `number` | 0 | Internal preview(0)/production(1) flag driving accumulation & ASVGF behavior — normally set via `configureForMode()`, not written directly |
 | `visMode` | `number` | 0 | Debug visualization mode (0 = off) |
-| `environmentMode` | `string` | 'hdri' | Sky mode: `'hdri'` \| `'procedural'` \| `'gradient'` \| `'color'` — not routed through `engine.settings`; use `engine.environmentManager.setMode()` instead |
+| `environmentMode` | `string` | 'hdri' | Sky mode: `'hdri'` \| `'procedural'` \| `'color'` — not routed through `engine.settings`; use `engine.environmentManager.setMode()` instead |
 | `cameraProjection` | `string` | 'perspective' | `'perspective'` \| `'orthographic'` \| `'equirectangular'` — see [Camera Projection](#camera-projection-orthographic-360-panorama) |
 | `panoramaLonRange` | `[number, number]` | `[-180, 180]` | Panorama longitude sweep, degrees, left→right |
 | `panoramaLatRange` | `[number, number]` | `[-90, 90]` | Panorama latitude sweep, degrees, bottom→top |
 | `panoramaLevelHorizon` | `boolean` | true | Yaw-only panorama basis, so orbit pitch/roll can't tilt the horizon |
 | `useAdaptiveSampling` | `boolean` | true | Whole-frame early-stop once convergence reaches `adaptiveStopFraction` |
-| `noiseThreshold` | `number` | 0.02 | √-luminance-normalized per-pixel noise below which a pixel counts as converged |
+| `noiseThreshold` | `number` | 0.1 | √-luminance-normalized per-pixel noise below which a pixel counts as converged (the production preset uses 0.02) |
 | `adaptiveMinSamples` | `number` | 8 | Minimum samples before adaptive sampling can trigger |
-| `adaptiveStopFraction` | `number` | 0.95 | Fraction of pixels that must converge before the frame retires |
+| `adaptiveStopFraction` | `number` | 0.90 | Fraction of pixels that must converge before the frame retires (the production preset uses 0.94) |
 | `usePixelFreeze` | `boolean` | true | Per-pixel freeze (Tier-2): skip individually-converged pixels via active-list compaction |
 | `pixelFreezeThreshold` | `number` | 0.02 | Relative-error threshold for a pixel to become a freeze candidate |
 | `pixelFreezeStability` | `number` | 8 | Consecutive candidate frames required before a pixel freezes |
 
-See `ENGINE_DEFAULTS` for the full list with default values. The default look is AgX (`toneMapping: 6`) at neutral saturation; tone mapping is chosen through [Colour Management](#colour-management) (`engine.color.setActiveView( id )`), not `settings`.
+See `ENGINE_DEFAULTS` for the full list with default values — every key in it is a setting of the same name. The default look is AgX (`DEFAULT_VIEW`) at neutral saturation; tone mapping is chosen through [Colour Management](#colour-management) (`engine.color.setActiveView( id )`), not `settings`. On the core without the colour add-on, set `renderer.renderer.toneMapping`.
 
 #### Rendering Modes
 
@@ -480,6 +493,168 @@ To pause rendering for image-viewing UI, set `engine.pauseRendering = true` and
 
 ---
 
+### Renderer core (`rayzee/core`)
+
+`PathTracerApp` is built on `RayzeeRenderer`, the renderer without the viewer: a scene and camera in, path-traced samples accumulated, the image out. The denoisers, camera controls, gizmo, overlays, timeline and animation playback exist only in `PathTracerApp`; six capabilities come as add-ons — file formats beyond glTF and `.hdr`, the physical sky, scene archives, bidirectional path tracing, OpenColorIO colour and on-disk storage. Its entry point downloads about 40 % less (249 KB against 418 KB compressed). It takes the same constructor options except `container`, and renders the same pixels.
+
+```js
+import { RayzeeRenderer } from 'rayzee/core';
+
+const renderer = await new RayzeeRenderer(canvas).init();
+await renderer.loadModel('/models/scene.glb');
+renderer.camera.position.set(0, 2, 6);   // the camera it renders from; reset() after moving it
+renderer.camera.lookAt(0, 0, 0);
+renderer.reset();
+await renderer.renderFrames(256);
+const image = await renderer.renderToBuffer({ colorSpace: 'srgb' });
+renderer.dispose();
+```
+
+Two runnable examples live in the repository: `rayzee/examples/core-node.mjs` (the core alone, in Node, writing a PNG)
+and `rayzee/examples/core-browser/` (the core plus the physical sky, accumulating on a canvas).
+
+#### Add-ons
+
+Six capabilities install on the core explicitly. `PathTracerApp` installs all six itself, so nothing in this
+section applies to it.
+
+| Add-on | Import | Install | When | Without it |
+|---|---|---|---|---|
+| File formats | `fbxFormat`, `objFormat`, `stlFormat`, `plyFormat`, `colladaFormat`, `threeMFFormat`, `usdFormat`, `exrFormat` or `allFormats` from `rayzee/addons/formats` | `renderer.assetLoader.registerFormat(objFormat, exrFormat)` | after `init()` | only glTF/GLB, `.hdr` and images load; any other file's error names the add-on |
+| Physical sky | `PhysicalSky` from `rayzee/addons/physical-sky` | `renderer.environmentManager.setProceduralSky(PhysicalSky)` | after `init()` | `'procedural'` mode records `capability.missing` (throws under `strict`) |
+| Scene archives and pbrt | `ArchiveImporter` from `rayzee/addons/archives` | `renderer.assetLoader.setArchiveImporter(new ArchiveImporter(renderer.assetLoader))` | after `init()` | `.zip`, `.tar` and `.tgz` are not supported formats, and the error names the add-on |
+| Bidirectional and VCM | `BidirectionalIntegrator` from `rayzee/addons/bidirectional` | `renderer.stages.pathTracer.registerIntegrator(['bidirectional', 'vcm'], pt => new BidirectionalIntegrator(pt))` | after `init()` | choosing either integrator records `capability.missing` (throws under `strict`) and keeps the current one |
+| OpenColorIO colour | `ColorManagement` from `rayzee/addons/color` | `renderer.setColorManagement(ColorManagement)` | before or after `init()` | linear Rec.709 through three.js's own tone mappers; `loadColorConfig()` records `capability.missing` and rejects |
+| On-disk storage | `acquireSharedStorage` from `rayzee/addons/storage` | `renderer.setStorageOpener(acquireSharedStorage)` | **before** `init()` | downloads land in memory and nothing is cached between visits |
+
+`init()` creates the asset loader, the environment manager and the path tracer stage, which is why four of them come
+after it. Storage is opened during `init()`, so its opener has to be set first.
+
+All six, in that order:
+
+```js
+import { RayzeeRenderer, configureAssets } from 'rayzee/core';
+import { acquireSharedStorage } from 'rayzee/addons/storage';
+import { ColorManagement } from 'rayzee/addons/color';
+import { ArchiveImporter } from 'rayzee/addons/archives';
+import { PhysicalSky } from 'rayzee/addons/physical-sky';
+import { BidirectionalIntegrator } from 'rayzee/addons/bidirectional';
+import { allFormats } from 'rayzee/addons/formats';
+
+configureAssets({ ocioRuntimeFactory: () => import('@bb-studio/ocio') });
+
+const renderer = new RayzeeRenderer(canvas);
+renderer.setStorageOpener(acquireSharedStorage);             // before init()
+renderer.setColorManagement(ColorManagement);
+await renderer.init();
+renderer.assetLoader.registerFormat(...allFormats);
+renderer.assetLoader.setArchiveImporter(new ArchiveImporter(renderer.assetLoader));
+renderer.environmentManager.setProceduralSky(PhysicalSky);
+renderer.stages.pathTracer.registerIntegrator(['bidirectional', 'vcm'], pt => new BidirectionalIntegrator(pt));
+```
+
+**Loading on first use.** The physical sky and the archive importer can be installed as loaders instead, so their code
+is fetched only the first time the sky is baked or an archive is read — `PathTracerApp` does this. The archive loader
+takes the formats it reads, which `rayzee/core` exports, so the loader recognises an archive before its code exists:
+
+```js
+import { ARCHIVE_FORMATS } from 'rayzee/core';
+
+renderer.environmentManager.setProceduralSkyLoader(() => import('rayzee/addons/physical-sky').then((m) => m.PhysicalSky));
+renderer.assetLoader.setArchiveImporterLoader(
+  () => import('rayzee/addons/archives').then((m) => new m.ArchiveImporter(renderer.assetLoader)),
+  ARCHIVE_FORMATS,
+);
+```
+
+Colour, storage and the integrators have no loader: colour and storage are used at startup, and an integrator applies
+the moment it is chosen (a lazy one would trace plain frames meanwhile and break reproducible renders).
+
+**File formats.** The core reads glTF/GLB (Draco, KTX2 and meshopt decoders are fetched only for a file that uses
+them), `.hdr` and LDR images. FBX, OBJ, STL, PLY, Collada, 3MF, USD/USDZ and EXR are formats to register — import only
+those you read and a bundler leaves the rest out; each three.js loader is downloaded the first time its format is read:
+
+```js
+import { objFormat, usdFormat, exrFormat } from 'rayzee/addons/formats';
+
+renderer.assetLoader.registerFormat(objFormat, usdFormat, exrFormat);
+await renderer.loadFile(objFile);
+```
+
+A format of your own registers the same way. A model format's `parse` gets the file and resolves to the model; an
+environment format's `createLoader` returns a three.js loader whose `loadAsync` resolves to a texture:
+
+```js
+renderer.assetLoader.registerFormat({
+  name: 'Point cloud (XYZ)', label: 'XYZ', type: 'model', extensions: ['xyz'],
+  async parse(file, { filename }) {
+    return { model: buildPoints(await file.text(), filename) };
+  },
+});
+```
+
+**Physical sky**, for `environmentMode: 'procedural'`:
+
+```js
+renderer.environmentManager.setProceduralSky(PhysicalSky);
+await renderer.environmentManager.setMode('procedural');
+```
+
+**Bidirectional path tracing and vertex merging**, for `integrator: 'bidirectional' | 'vcm'`:
+
+```js
+renderer.stages.pathTracer.registerIntegrator(['bidirectional', 'vcm'], pt => new BidirectionalIntegrator(pt));
+renderer.settings.set('integrator', 'bidirectional');
+```
+
+Its controls are on the active integrator (the same on `PathTracerApp`):
+
+```js
+const integrator = renderer.stages.pathTracer.activeIntegrator;
+integrator.setMergeRadius(1);                        // 'vcm': gather radius in pixels
+integrator.setMergeTrust(0.25);                      // 'vcm': how far merging is trusted against the other strategies
+integrator.setLightGuiding(true);                    // learn where light paths from the sky and sun start
+integrator.setBidirectionalStrategy('connect', { alone: true });  // keep one strategy, for verification
+```
+
+**Scene archives** (`.zip`, `.tar`, `.tar.gz`) and the pbrt scenes in them:
+
+```js
+renderer.assetLoader.setArchiveImporter(new ArchiveImporter(renderer.assetLoader));
+await renderer.loadFile(archiveFile);
+```
+
+**OpenColorIO colour management** — configs, their views and looks, working spaces and export spaces. The host supplies
+the OCIO runtime (the engine never names the package). Without the add-on, pick a tone mapper on the three.js renderer
+instead (`renderer.renderer.toneMapping = AgXToneMapping`):
+
+```js
+configureAssets({ ocioRuntimeFactory: () => import('@bb-studio/ocio') });
+renderer.setColorManagement(ColorManagement);
+await renderer.loadColorConfig({ builtin: 'ocio://cg-config-v4.0.0_aces-v2.0_ocio-v2.5' });
+```
+
+**On-disk storage** (the browser's origin private file system), for the download, environment and scene caches and
+the `memorySpill` option. Asking for it without the add-on (`storage: 'auto'`) records a `capability.missing` warning;
+`storage: false` turns it off either way:
+
+```js
+const renderer = new RayzeeRenderer(canvas);
+renderer.setStorageOpener(acquireSharedStorage);
+await renderer.init();
+```
+
+Several renderers, core or full, can live in one page; they share only the colour management and the on-disk storage,
+which are page-wide.
+
+Code of your own that adds a setting declares it on the renderer's settings, with its default, so it gets the same
+provenance, change events and session saving as the built-in ones:
+
+```js
+renderer.settings.define('myGlowStrength', { default: 1, apply: (value) => glow.setStrength(value), reset: true });
+renderer.settings.set('myGlowStrength', 2);
+```
+
 ### engine.cameraManager
 
 Camera switching, auto-focus, DOF, and direct Three.js access.
@@ -617,7 +792,8 @@ engine.stages.pathTracer.materialData.updateMaterial(index, mat)  // Replace a m
 await engine.rebuildMaterials(scene)  // Full rebuild (after texture changes)
 
 // Cap the longest edge of processed material textures (clamped to the hardware max).
-// Larger = sharper textures, ~quadratic VRAM. Reprocesses the current scene by default.
+// Larger = sharper textures, ~quadratic VRAM. Reprocesses the current scene by default;
+// settings.set('maxTextureSize', n) stores it for the next load instead.
 await engine.setMaxTextureSize(2048)
 await engine.setMaxTextureSize(4096, { reprocess: false })
 
@@ -641,6 +817,8 @@ A property a three.js material lacks falls back to `MATERIAL_DEFAULTS` (exported
 
 ### Colour Management
 
+On `rayzee/core` this is the `rayzee/addons/color` add-on — see [Renderer core](#renderer-core-rayzeecore).
+
 `engine.color` is an OpenColorIO pipeline: what textures and lights mean, what the render happens in, and what it is shown and saved as. **It is inert until a config is loaded** — the render stays linear Rec.709 and the view transforms are three.js's own seven, so a host that never loads one sees no change. The host supplies the runtime (`ocioRuntimeFactory` or `ocioRuntimeUrl` in [`configureAssets`](#configuring-assets-cdn-urls--cache-namespace)).
 
 ```js
@@ -678,9 +856,8 @@ engine.environmentManager.params             // Current environment parameters
 engine.environmentManager.texture            // The loaded environment texture
 await engine.loadEnvironment(url)            // Load HDR/EXR environment map (method on engine)
 await engine.environmentManager.setEnvironmentMap(tex) // Set a custom environment texture
-await engine.environmentManager.setMode(mode)   // 'hdri' | 'procedural' | 'gradient' | 'color'
-await engine.environmentManager.generateProcedural() // Physical sky: spectral, multiple scattering, analytic sun
-await engine.environmentManager.generateGradient()   // Gradient sky
+await engine.environmentManager.setMode(mode)   // 'hdri' | 'procedural' | 'color'
+await engine.environmentManager.generateProcedural() // Physical sky: spectral, multiple scattering, analytic sun (core: needs rayzee/addons/physical-sky)
 await engine.environmentManager.generateSolid()      // Solid color sky
 engine.environmentManager.markDirty()        // Flag environment for GPU re-upload
 ```
@@ -708,15 +885,15 @@ Denoiser strategy, ASVGF, OIDN, upscaler, and auto-exposure.
 
 ```js
 // Strategy
-engine.denoisingManager.setStrategy('asvgf', 'medium')  // 'none' | 'asvgf' | 'edgeaware'
+engine.denoisingManager.setStrategy('asvgf', 'medium')  // 'none' | 'asvgf' | 'nrd' | 'edgeaware' | 'oidn'
 engine.denoisingManager.denoiserStrategy                 // read back the active strategy (derived from stage state)
 engine.denoisingManager.setASVGFEnabled(true, 'medium')
 engine.denoisingManager.applyASVGFPreset('high')         // 'low' | 'medium' | 'high'
 engine.denoisingManager.setAutoExposure(true)
 
 // Fine-grained parameters
-engine.denoisingManager.setASVGFParams({ temporalAlpha: 0.1, phiColor: 10 })
-engine.denoisingManager.setEdgeAwareParams({ pixelEdgeSharpness: 1.0 })
+engine.denoisingManager.setASVGFParams({ temporalAlpha: 0.1, maxAccumFrames: 16 })
+engine.denoisingManager.setEdgeAwareParams({ phiLuminance: 4.0, atrousIterations: 5 })
 engine.denoisingManager.setAutoExposureParams({ keyValue: 0.18 })
 
 // OIDN & Upscaler
@@ -727,7 +904,7 @@ engine.denoisingManager.setTemporalHistory(false)        // live OIDN without th
 engine.denoisingManager.continuousDenoiseInterval = 250   // cap refreshes at 4/sec (default 8 = uncapped)
 engine.denoisingManager.setUpscalerEnabled(true)
 engine.denoisingManager.setUpscalerScaleFactor(2)         // 2 or 4
-engine.denoisingManager.setUpscalerQuality('high')        // ESRGAN only
+engine.denoisingManager.setUpscalerQuality('quality')     // 'fast' | 'balanced' | 'quality'
 ```
 
 ### engine.interactionManager
@@ -831,7 +1008,11 @@ surface** — pin a version and branch on the strings; they are never renamed or
 | `refit.shared_geometry` | a deform was asked for on a mesh that shares its triangles, and was skipped |
 | `denoiser.unavailable` | a requested denoise or upscale produced nothing — the denoiser was not built, OIDN was off while accumulating, or the pass needs a canvas in a document |
 | `output.source_fallback` | `renderToBuffer( { source: 'display' } )` found no denoised picture and returned the raw accumulation |
+| `output.tonemap_fallback` | `renderToBuffer`'s `'srgb'` bytes were tone-mapped on the CPU, not the GPU — the picture is the same within a level, only slower (a warning: strict does not throw) |
 | `light.placeholder_skipped` | a `RectAreaLightPlaceholder` node lacked `userData.name` or `userData.type: 'RectAreaLight'`, so no light was made for it |
+| `capability.missing` | a feature was asked for whose add-on is not installed on the core (procedural sky, an unregistered integrator, a colour config, storage) — names the add-on |
+| `color.config_load_failed` / `viewTransform.bake_failed` / `viewTransform.display_mismatch` | a colour config failed to load (the previous one stays), a view could not be rebaked, or a view targets a display the canvas cannot show (a saved buffer is still right) — warnings |
+| `storage.unavailable` / `storage.quota_exceeded` / `storage.write_failed` / `storage.read_failed` / `storage.entry_corrupt` / `storage.cache_mismatch` | on-disk storage is off or failed; the engine carries on in memory — warnings |
 
 `asset.unreachable` also covers what the engine fetches for itself: OIDN weights, IES profiles and
 gobos (`detail.asset` says which).
@@ -1021,7 +1202,7 @@ auto-exposure, if you turn it on.
 #### Batch rendering
 
 The supported entry point for a render farm is `rayzee/src/Headless.js`, exported from the package.
-Its defaults are a batch renderer's — `strict`, `profile: 'physical'`, deterministic, storage off —
+Its defaults are a batch renderer's — `strict`, deterministic, storage off —
 so a degraded render throws instead of shipping:
 
 ```js
@@ -1045,19 +1226,26 @@ it back with `renderToBuffer( { source: 'display' } )`. Driving it yourself is t
 `'display'` was asked for, a denoiser is in use, and nothing had published — so a strict host cannot
 ship a noisy image by mistake. Its `'srgb'` bytes are tone-mapped on the GPU — 9 ms at 4096×2160,
 where the CPU pass it replaced took 1.4 s on an M-series Mac and 10 s on a cloud host — and match the
-canvas to within one level (it rounds half a level up); `'linear'` is exact.
+canvas to within one level (it rounds half a level up); `'linear'` is exact. When the GPU pass is
+unavailable or fails, the CPU does it instead: the result's `toneMappedOn` says `'cpu'` rather than
+`'gpu'`, and `output.tonemap_fallback` is recorded with the reason.
 
 Constructing `PathTracerApp` yourself instead: pass `strict: true`; storage is then off unless you
 set it. Outside Chrome, pass `hostMemoryGB`.
 
+The engine has one set of defaults, the viewer's. For lens-accurate depth of field and glTF placeholder area
+lights at their authored power, set `dofMode: 'physical'` and `areaLightIntensityScale: 1` — through `settings`
+here, or `engine.settings` before loading the model.
+
 **Provenance.** `engine.getProvenance()` — also `frame.provenance` from `captureHeadless` — is plain
-JSON naming what produced the image: engine and three.js versions, the profile by name *and* by
-value, the adapter, every live setting with its source, the colour pipeline, the render size and
-samples, and whether it ran headless, strict, deterministic or lockstepped. Store it beside each
-render and "what made this?" has an answer without rendering again.
+JSON naming what produced the image: engine and three.js versions, the adapter, every live setting with its source, the colour pipeline, the render size and
+samples, and whether it ran headless, strict, deterministic or lockstepped. `mode.lockstep` says
+whether the current image was traced in lockstep, so it stays true after `renderUntilComplete` turns
+lockstep back off. Store it beside each render and "what made this?" has an answer without rendering
+again.
 
 **Pinning a look.** A change to what a render looks like when a host sets nothing — a default
-setting, a mode preset, a profile's values, light units — is released as a **major**, with the
+setting, a mode preset, light units — is released as a **major**, with the
 change described under BREAKING CHANGES in the release notes. Pin a major to pin a look; read the
 notes before moving to the next one.
 
@@ -1097,7 +1285,9 @@ app.dispose();
   JPEG or WebP to RGBA8, straight alpha, top row first — since the engine carries no decoder. It decodes
   every glTF image, embedded or not, and JPEG/PNG skies. PNGs with bytes after `IEND`, which browsers
   accept and strict decoders refuse, are trimmed first; a texture that still fails is recorded as
-  `texture.build_failed` rather than dropped. Measured on a 91-texture model: `sharp` and
+  `texture.build_failed` rather than dropped. Without `decodeImage`, each glTF image is recorded that way with what to
+  configure (a strict host's load throws), and the model loads untextured. KTX2 (Basis) textures need no
+  `decodeImage`: three's KTX2 loader decodes them, in a `NodeWorker` the engine lends it. Measured on a 91-texture model: `sharp` and
   `@napi-rs/canvas` (`await loadImage()`, then a 2D canvas) both decode in parallel, ~0.3 s against
   pngjs's 2.5 s serial. The canvas route premultiplies, which zeroes colour under alpha 0 and loses
   it under low alpha; `sharp` is exact. `jpeg-js` differs from libjpeg-turbo by up to 63 levels.
@@ -1111,12 +1301,13 @@ app.dispose();
   memory): on the main thread it held up the BVH workers, and a 1.9M-triangle, 91-texture model
   loaded in 4.1–4.9 s. It now loads in 2.1 s, against Chrome's 2.9 s on the same machine.
 - `nodePlatform()` also defines `ProgressEvent`, which three.js's `FileLoader` constructs while
-  streaming; that is the only global it sets. three.js's own Draco and KTX2 workers call the global
-  `Worker`, so a model using either also needs `globalThis.Worker = NodeWorker`.
+  streaming; that is the only global it sets. three.js's own Draco and KTX2 loaders call the global
+  `Worker`; the engine lends them `NodeWorker` for the length of each glTF parse, so a Draco or KTX2
+  model loads with nothing set by the host.
 
 Measured on this bench's corpus: all 29 scenes match the Chrome goldens (`npm run bench:node`, RMSE
 ≤ 0.0036, no pixel over 0.02 — the readback's tone map accounts for most of it), and a textured glTF with an
-HDR, a PNG sky or a gradient matches Chrome block for block within 0.05 of a level. Not available
+HDR or a PNG sky matches Chrome block for block within 0.05 of a level. Not available
 without a browser: on-disk storage (OPFS), gobo libraries (they draw on a 2D canvas), and the AI
 upscaler.
 
@@ -1147,6 +1338,8 @@ list. Both need `timestamp-query`, and `getDenoiseProfile()` returns `null` when
 
 ### On-disk Storage (OPFS)
 
+On `rayzee/core`, storage needs the `rayzee/addons/storage` add-on (`setStorageOpener`) — see [Renderer core](#renderer-core-rayzeecore).
+
 `engine.storage` is a `StorageManager` over the browser's origin private file system, or `null` where
 there is none (a private window, Node) — everything works without it, only slower. The engine keeps
 its caches there: downloads (models, skies, OIDN weights — revalidated at most daily with a 1-byte `Range` request, and served from the cache meanwhile),
@@ -1243,6 +1436,7 @@ engine.addEventListener(EngineEvents.RENDER_COMPLETE, (e) => {
 | Event | Fired when |
 |---|---|
 | `RENDER_COMPLETE` | Rendering has converged |
+| `SHADERS_COMPILING` | The path tracer compiles its shaders in the background (`event.compiling` true, then false) — after a model load, a new material layer, a light transport switch. The page stays responsive; the canvas keeps its last frame until they are ready, and `renderFrames()` waits for them |
 | `RENDER_RESET` | Accumulation buffer is reset |
 | `FRAME` | Fires once per `animate()` tick — hook external instrumentation (stats panels, telemetry) here |
 | `DENOISING_START` / `DENOISING_END` | Denoiser runs. `event.continuous` is `true` for a cadence denoise of the still-accumulating image, `false` for the one that ends a render |
@@ -1296,12 +1490,30 @@ class MyCustomStage extends RenderStage {
 }
 ```
 
+To run between the path tracer and the compositor, subclass the renderer and return the stage from
+`_createExtraStages()` (call the parent's and add yours); for the compositor to show its picture, list
+`'my-stage:output'` in `_displaySources()`. `pipeline.addStage()` after `init()` appends after the
+compositor. A stage that needs an extra path-tracer output asks for it with
+`stages.pathTracer.requestOutput( name, options )` — `'gBuffer'` (the normal/depth and albedo a denoiser reads; the
+viewer asks for it itself) or `'hitDistance'`. Each is compiled into the path tracer only while asked for.
+
 ### All Exports
 
 ```js
-// Core
+// The full engine (it also exports RayzeeRenderer)
 import { PathTracerApp, EngineEvents, LEGACY_EVENT_NAMES } from 'rayzee';
 
+// The renderer core and its add-ons (see Renderer core)
+import { RayzeeRenderer } from 'rayzee/core';
+import { PhysicalSky } from 'rayzee/addons/physical-sky';
+import { ArchiveImporter } from 'rayzee/addons/archives';
+import { BidirectionalIntegrator } from 'rayzee/addons/bidirectional';
+import { ColorManagement } from 'rayzee/addons/color';
+import { acquireSharedStorage } from 'rayzee/addons/storage';
+
+// Headless rendering (see Deterministic & Headless Rendering)
+import { renderHeadless, openHeadless, captureHeadless } from 'rayzee';
+
 // Platform services for hosts without a browser (see Running in Node)
 import { configurePlatform, getPlatform } from 'rayzee';
 import { nodePlatform, NodeWorker } from 'rayzee/node';
@@ -1309,22 +1521,18 @@ import { nodePlatform, NodeWorker } from 'rayzee/node';
 // Configuration & presets
 import {
   ENGINE_DEFAULTS,
+  DENOISER_DEFAULTS,
+  AUTO_EXPOSURE_DEFAULTS,
+  AUTO_FOCUS_DEFAULTS,
   ASVGF_QUALITY_PRESETS,
-  CAMERA_PRESETS,
-  CAMERA_RANGES,
-  SKY_PRESETS,
+  SKY_DEFAULTS,
   DEFAULT_SUN_PATH,
-  AUTO_FOCUS_MODES,
-  AF_DEFAULTS,
+  DEFAULT_VIEW,
   TRIANGLE_DATA_LAYOUT,
   BVH_LEAF_MARKERS,
-  TEXTURE_CONSTANTS,
-  DEFAULT_TEXTURE_MATRIX,
-  MEMORY_CONSTANTS,
   PRODUCTION_RENDER_CONFIG,
   INTERACTIVE_RENDER_CONFIG,
   MAX_RESERVABLE_RENDER_SIZE,
-  RENDER_PROFILES,
   MATERIAL_DEFAULTS,
 } from 'rayzee';
 
@@ -1426,7 +1634,7 @@ import { setBindingAudit, getBindingAuditFindings, clearBindingAuditFindings } f
 OIDN provides high-quality AI denoising. It runs automatically once the render converges (reaches
 `maxSamples`), and — in `'interactive'` mode — also on a cadence while the image is still
 accumulating, so a preview shows a clean picture as it refines instead of only at the end. See
-[Continuous denoising](#continuous-denoising).
+[When the denoiser runs](#when-the-denoiser-runs).
 
 1. **Install the package**
 

package/dist/ActiveColor-YvuQq44O.js

@@ -0,0 +1,13 @@
+//#region src/Color/ActiveColor.js
+var e = "Linear Rec.709 (sRGB)", t = null;
+function n() {
+	return t;
+}
+function r(e) {
+	t = e, e?._publishWorkingMatrix?.();
+}
+function i(e) {
+	t === null && (t = e);
+}
+//#endregion
+export { r as i, i as n, n as r, e as t };