rayzee 9.1.2 → 9.2.1

package/README.md

@@ -267,16 +267,12 @@ export default defineConfig({
 
 ### Configuring Assets (CDN URLs & cache namespace)
 
-By default, the engine loads STBN blue-noise atlases, GLTF Draco/KTX2 decoders, OIDN denoiser weights, ONNX upscaler models, and the onnxruntime-web bundle from upstream CDNs. If you're self-hosting, embedding the engine alongside a different consumer of the same caches, or operating offline, override them **once before constructing `PathTracerApp`**:
+By default, the engine loads GLTF Draco/KTX2 decoders, OIDN denoiser weights, ONNX upscaler models, and the onnxruntime-web bundle from upstream CDNs. If you're self-hosting, embedding the engine alongside a different consumer of the same caches, or operating offline, override them **once before constructing `PathTracerApp`**:
 
 ```js
 import { configureAssets } from 'rayzee';
 
 configureAssets({
-  // STBN atlases (PNG, decoded as Float textures)
-  stbnScalarAtlas: '/assets/stbn_scalar_atlas.png',
-  stbnVec2Atlas:   '/assets/stbn_vec2_atlas.png',
-
   // onnxruntime-web (loaded by AI upscaler worker via dynamic import)
   ortRuntimeUrl: '/ort/ort.webgpu.bundle.min.mjs',
   ortWasmPaths:  '/ort/',
@@ -319,12 +315,15 @@ const engine = new PathTracerApp(canvas, options?)
 | Parameter | Type | Description |
 |---|---|---|
 | `canvas` | `HTMLCanvasElement` | Rendering target |
-| `options.autoResize` | `boolean` | Auto-resize on window resize (default: `true`) |
+| `canvas` may be `null` | | Headless: the engine makes its own canvas and runs no render loop — see [Running in Node](#running-in-node) |
+| `options.headless` | `boolean` | Headless with a canvas of your own (default: `true` when `canvas` is `null`) |
+| `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.storage` | `false \| 'auto' \| StorageManager` | On-disk storage (default: `configureAssets( { storage } )`). A manager you pass stays yours to dispose. See [On-disk storage](#on-disk-storage-opfs). |
+| `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). |
 | `options.memorySpill` | `boolean` | Experimental, default `false`: build a large static scene through disk — triangle records, BLAS nodes and the three.js geometry are written out as the build finishes with them — and raise the pbrt triangle and placement caps to 60M / 8M. See [On-disk storage](#on-disk-storage-opfs). |
 
 The engine creates and mounts everything it needs (denoiser canvas, tile/HUD overlay) into a single parent on `init()`. Performance HUDs (e.g. `stats-gl`) are not bundled — listen to `EngineEvents.FRAME` and tick your own panel.
@@ -552,10 +551,16 @@ engine.lightManager.add('PointLight')       // Add a light (PointLight, SpotLigh
 engine.lightManager.remove(uuid)            // Remove by UUID
 engine.lightManager.clear()                 // Remove all lights
 engine.lightManager.getAll()                // Get all light descriptors
-engine.lightManager.sync()                  // Re-upload light data to GPU
+engine.lightManager.setIntensity(uuid, 40)  // Set one light's power and re-upload
+engine.lightManager.getLight(uuid)          // The traced three.js light, to edit other properties
+engine.lightManager.sync()                  // Re-upload light data to GPU after editing a light
 engine.lightManager.showHelpers(true)       // Toggle visual helpers
 ```
 
+The path tracer traces **copies** of a model's lights, made when the model loads. Changing a light
+inside the loaded model does nothing; change the copy — `getLight(uuid)` with a UUID from `getAll()` —
+and call `sync()`, or use `setIntensity()`.
+
 Light `intensity` follows Blender: radiant power in watts for point, spot and area lights, irradiance in W/m² for directional. Dividing power by area only means something in metres, so the engine assumes **one world unit is one metre**; scenes authored in cm or mm must carry that scale in their node transforms, as glTF exporters do. glTF `RectAreaLightPlaceholder` nodes author `intensity` as three.js radiance (their `power` field is `intensity · width · height · π`); the importer converts it to power through the light's world area so the authored radiance is reproduced exactly, then applies the profile's `areaLightIntensityScale`.
 
 ### engine.animationManager
@@ -824,6 +829,12 @@ surface** — pin a version and branch on the strings; they are never renamed or
 | `scene.memory_budget` | the scene needs more CPU memory than is safe, or more than is possible |
 | `emissive.instances_collapsed` | an emissive instanced mesh was too large to expand, so its copies light the scene as one |
 | `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 |
+| `light.placeholder_skipped` | a `RectAreaLightPlaceholder` node lacked `userData.name` or `userData.type: 'RectAreaLight'`, so no light was made for it |
+
+`asset.unreachable` also covers what the engine fetches for itself: OIDN weights, IES profiles and
+gobos (`detail.asset` says which).
 
 `settings.getEffective()` is the companion for the `setting.unknown_key` case: it returns every live
 setting as `{ value, source, routed }`, and `routed: false` means stored but reaching no stage.
@@ -868,7 +879,7 @@ engine.setReservedRenderResolution(2048, { allowLower: true })   // lower, payin
 engine.getReservedRenderResolution()              // the reserve actually in force
 ```
 
-The request is **device-capped**: a 4096 reserve pins roughly 1.5 GB of MRT textures, so it is only granted on GPUs reporting ≥ 8 GB and a ≥ 1 GB `maxStorageBufferBindingSize`; weaker devices clamp to 2048. `MAX_RESERVABLE_RENDER_SIZE` (4096) is the ceiling on any request.
+The request is **device-capped**: a 4096 reserve pins roughly 1.5 GB of MRT textures, so it is only granted on hosts reporting ≥ 8 GB and a ≥ 1 GB `maxStorageBufferBindingSize`; weaker devices clamp to 2048, recorded as `render.reserve_capped`. The memory figure is `options.hostMemoryGB`, else `navigator.deviceMemory`, else an assumed 4 — so outside Chrome, pass it. `MAX_RESERVABLE_RENDER_SIZE` (4096) is the ceiling on any request.
 
 Raises are monotonic unless you pass `allowLower` — UI-driven callers ask for whatever the current view needs, and honouring every decrease made the reserve oscillate across preview↔render switches, paying a full kernel rebuild each time.
 
@@ -877,10 +888,10 @@ Callable at any point in the lifecycle:
 - **Before `init()`** — recorded and applied during `init()`, after the device exists but before the stages are constructed, so they allocate at the raised size directly. The device gate cannot run without a device, so the return value here is the *request*, not the verdict.
 - **After `init()`** — applied immediately, re-initialising the reserved GPU storage in place.
 
-Either way the verdict arrives as a `reserved_render_size_changed` event (a plain string type, not an `EngineEvents` constant):
+Either way the verdict arrives as `EngineEvents.RESERVED_RENDER_SIZE_CHANGED`:
 
 ```js
-engine.addEventListener('reserved_render_size_changed', e => console.log('reserve:', e.size));
+engine.addEventListener(EngineEvents.RESERVED_RENDER_SIZE_CHANGED, e => console.log('reserve:', e.size));
 engine.setReservedRenderResolution(4096);
 await engine.init();
 console.log(engine.getReservedRenderResolution());   // 4096, or 2048 if the device declined
@@ -894,7 +905,7 @@ Track GPU (VRAM) usage across the whole pipeline. Sizes are measured from live G
 
 ```js
 const { current, peak, byCategory } = engine.getMemoryInfo();   // bytes
-// byCategory: { rays, queues, gbuffer, accum, geometry, materials, environment, stages }
+// byCategory: { rays, queues, gbuffer, accum, geometry, materials, environment, stages, denoiser, canvas }
 
 engine.vram.resetPeak();   // reset the high-water mark to the current value
 engine.vram.getReport();   // formatted one-line summary string
@@ -902,6 +913,12 @@ engine.vram.getReport();   // formatted one-line summary string
 
 `peak` is a high-water mark, reset when a final render begins (`configureForMode('production')`). The engine's VRAM is largely monotonic — the ray pool only grows and the per-stage storage textures are fixed-size — so `peak` equals `current` during a steady render and only exceeds it after memory is released (lower resolution, a smaller scene, or removing the HDRI). The `stages` + `accum` categories (fixed 2048² storage textures) dominate the baseline.
 
+`denoiser` is what the engine allocates for OIDN — its three float inputs, its half-float output and
+the motion history. `canvas` is one image per presented surface (a browser may keep one or two more)
+plus the buffer three.js's output pass tone-maps through. Not counted: oidn-web's own network weights
+and activations, which it reports by count, not by size; and the neural passes, which run on a
+`GPUDevice` of their own.
+
 The React app surfaces this as a `Memory: … | Peak: …` readout in the on-canvas stats overlay.
 
 #### CPU memory
@@ -974,7 +991,134 @@ The RNG is already pure — `hash(pixel, rayIndex, frame)`, no clock, no `Math.r
 
 - `engine.isDeterministic` — whether output is currently bit-reproducible.
 - `setDeterministicMode(true, { pinDispatch: false })` keeps the two readback-driven dispatch heuristics active. Output is then *not* reproducible; this exists so performance measurements reflect shipping behaviour rather than a configuration production never runs.
-- `renderFrames` awaits `engine.stages.pathTracer.blueNoiseReady` first — until the STBN atlases land the sampler reads a constant-0.5 placeholder that bakes permanently into the accumulation buffer. It raises `maxSamples` if needed, and throws if something retires the render early.
+- `renderFrames` raises `maxSamples` if needed, and throws if something retires the render early.
+
+#### Production renders, reproducibly
+
+Deterministic mode buys reproducibility by turning adaptive sampling off. To render the way the
+product does — adaptive sampling, pixel freeze and the per-bounce early exit all on — and still get
+the same image for the same input, drive the render with `renderUntilComplete`:
+
+```js
+engine.configureForMode('production');
+const { samples, retiredBy, denoised } = await engine.renderUntilComplete({ signal });
+// retiredBy: 'samples' | 'converged' | 'timeLimit'
+```
+
+It renders without `requestAnimationFrame` until the sample ceiling, convergence or the time limit —
+whichever comes first — then runs the final OIDN denoise once, and fires `RENDER_COMPLETE` as the
+loop does. Adaptive sampling decides from counts read back from the GPU; normally each is applied
+whenever it lands, so the frame that retires depends on how fast frames are submitted. For its
+duration `renderUntilComplete` runs those readbacks in **lockstep**: one issued at frame N is applied
+at frame N + 4 exactly, and the render waits if it has not landed; every reset also starts from seed
+0 and from nothing the previous render measured. It turns interaction mode off meanwhile (a
+wall-clock mode for camera drags), and keeps submissions at most 2 × `drainEvery` frames ahead of
+the GPU. A time limit is wall-clock by nature, so that one stop is not reproducible; neither is
+auto-exposure, if you turn it on.
+
+`engine.setLockstepReadbacks(true)` applies the same lockstep to the rAF loop and to `renderFrames`.
+
+#### 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 —
+so a degraded render throws instead of shipping:
+
+```js
+import { openHeadless, captureHeadless } from 'rayzee';
+
+const app = await openHeadless({ canvas, model: url, width: 1920, height: 1080 });
+try {
+  const frame = await captureHeadless(app, { samples: 256, denoise: true });
+  // frame.data: RGBA8 (colorSpace 'srgb') or Float32 (colorSpace 'linear')
+  // frame.source: what was read — 'oidn' here, 'accumulation' without denoise
+  // frame.issues: everything the engine survived, when not strict
+} finally {
+  app.dispose();
+}
+```
+
+`denoise: true` turns OIDN on before accumulating (it reads the albedo and normal buffers, which
+are written only while it is on), runs **one** final denoise with `app.runFinalDenoise()`, and reads
+it back with `renderToBuffer( { source: 'display' } )`. Driving it yourself is the same three calls.
+`renderToBuffer` reports the picture it read as `source`, and records `output.source_fallback` when
+`'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.
+
+Constructing `PathTracerApp` yourself instead: pass `strict: true`; storage is then off unless you
+set it. Outside Chrome, pass `hostMemoryGB`.
+
+**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.
+
+**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
+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.
+
+#### Running in Node
+
+The published build renders in plain Node on Dawn — the `webgpu` package, the WebGPU implementation
+inside Chrome — with no browser and no DOM shim:
+
+```js
+import { create, globals } from 'webgpu';
+import sharp from 'sharp';
+import { configurePlatform, openHeadless } from 'rayzee';
+import { nodePlatform } from 'rayzee/node';
+
+Object.assign(globalThis, globals);
+const gpu = create([]);                       // keep a reference: Dawn crashes if it is collected
+Object.defineProperty(navigator, 'gpu', { value: gpu });
+
+const decodeImage = async (bytes) => {
+  const { data, info } = await sharp(bytes).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  return { data, width: info.width, height: info.height };
+};
+configurePlatform(nodePlatform({ decodeImage }));   // after the webgpu globals, before any app
+const app = await openHeadless({ width: 1920, height: 1080, hostMemoryGB: 16 });   // no canvas: headless
+await app.loadModel('https://…/room.glb');
+const { samples } = await app.renderUntilComplete();
+const frame = await app.renderToBuffer({ source: 'display' });
+app.dispose();
+```
+
+- **No canvas means headless.** `new PathTracerApp(null)` — or `{ headless: true }` — makes its own
+  canvas (a WebGPU context over a plain texture), runs no render loop (drive it with `renderFrames` or
+  `renderUntilComplete`), and builds neither the overlay renderer nor the transform gizmo.
+- **`configurePlatform({ Worker, decodeImage })`** is where a host without a browser supplies what one
+  would. `nodePlatform()` from `rayzee/node` fills it: `NodeWorker`, the Web Worker API over
+  `worker_threads`, runs the engine's inlined workers; `decodeImage(bytes, mimeType)` is yours — PNG,
+  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
+  `@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.
+- **`nodePlatform()` wraps the `webgpu` queue**, so install its globals first. dawn.node 0.6.1
+  segfaults on `writeBuffer` / `writeTexture` from a `SharedArrayBuffer`, which WebGPU allows and the
+  engine's triangle and BVH stores are once a scene is large; those uploads are copied out, 64 MB at
+  a time.
+- **Textures are packed on the CPU** where there is no `createImageBitmap`: exact when a map fits its
+  bucket, bilinear otherwise (a browser's canvas filter differs slightly there). A bucket over 8 MB
+  packs in a worker, reading images decoded by `decodeImage` in place (they are kept in shared
+  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`.
+
+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
+without a browser: on-disk storage (OPFS), gobo libraries (they draw on a 2D canvas), and the AI
+upscaler.
 
 #### GPU timing
 
@@ -1005,7 +1149,7 @@ list. Both need `timestamp-query`, and `getDenoiseProfile()` returns `null` when
 
 `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, STBN atlases — revalidated with `HEAD`),
+its caches there: downloads (models, skies, OIDN weights — revalidated at most daily with a 1-byte `Range` request, and served from the cache meanwhile),
 unpacked `.tar.gz` archives and archive indexes, built scenes (reopened without rebuilding BVHs when
 the first build took ≥ 10 s), and environment sampling tables. Caches share a budget of 30 % of the
 quota and are evicted least-recently-used; `engine.storage.usage()` reports each area.
@@ -1103,7 +1247,7 @@ engine.addEventListener(EngineEvents.RENDER_COMPLETE, (e) => {
 | `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 |
 | `UPSCALING_START` / `UPSCALING_PROGRESS` / `UPSCALING_END` | AI upscaler runs |
-| `LOADING_UPDATE` / `LOADING_RESET` | Asset loading progress |
+| `LOADING_UPDATE` / `LOADING_RESET` | Asset loading progress. A failed load ends with `failed: true` and the error as `status`; an archive that asks which parts to load ends with `LOADING_RESET` |
 | `STATS_UPDATE` | Performance stats updated |
 | `OBJECT_SELECTED` / `OBJECT_DESELECTED` | Object selection changes |
 | `OBJECT_DOUBLE_CLICKED` | Object double-clicked |
@@ -1119,6 +1263,18 @@ engine.addEventListener(EngineEvents.RENDER_COMPLETE, (e) => {
 | `VIDEO_RENDER_PROGRESS` / `VIDEO_RENDER_COMPLETE` | Video export progress |
 | `DEVICE_LOST` | The GPU device was lost (driver crash/reset) — rendering halts instead of throwing into a dead device |
 | `DISPOSE` | Engine is being disposed (fires before teardown begins, so listeners can release their own references) |
+| `ISSUE` | An issue was recorded — see [Degradation contract](#degradation-contract) |
+| `MODEL_LOADED` / `OBJECT3D_LOADED` / `MODEL_ADDED` / `SCENE_OBJECT_REMOVED` / `SCENE_UNLOADED` | Scene content changed |
+| `SCENE_REBUILD` / `SCENE_SPILLED` / `SCENE_METADATA_APPLIED` | The scene was rebuilt, moved to disk, or had its authored environment applied |
+| `ENVIRONMENT_LOADED` / `TEXTURES_REPROCESSED` | An environment or the texture arrays were (re)built |
+| `CAMERAS_UPDATED` / `CAMERA_SWITCHED` / `FOCUS_CHANGED` | Camera list, active camera, or focus distance changed |
+| `RESOLUTION_CHANGED` / `RESERVED_RENDER_SIZE_CHANGED` | The render size or the reserve changed |
+| `STORAGE_CHANGED` / `TIMELINE_CHANGED` | On-disk storage or timeline keys changed |
+
+Several of these used to be plain strings (`'ModelLoaded'`, `'RenderComplete'`, `'resolution_changed'`, …).
+The engine still dispatches each under its old name as well, until the next major; `LEGACY_EVENT_NAMES`
+maps new to old. Listening for a name the engine never dispatches logs a warning once, since such a
+listener fails silently otherwise.
 
 ### Advanced: Custom Pipeline Stages
 
@@ -1144,7 +1300,11 @@ class MyCustomStage extends RenderStage {
 
 ```js
 // Core
-import { PathTracerApp, EngineEvents } from 'rayzee';
+import { PathTracerApp, EngineEvents, LEGACY_EVENT_NAMES } from 'rayzee';
+
+// Platform services for hosts without a browser (see Running in Node)
+import { configurePlatform, getPlatform } from 'rayzee';
+import { nodePlatform, NodeWorker } from 'rayzee/node';
 
 // Configuration & presets
 import {

package/dist/{NeuralRetouch-BRquqfmZ.js → NeuralRetouch-CYgkQY8Z.js}

@@ -1,5 +1,5 @@
 import { t as e } from "./rolldown-runtime-CAFD8bLK.js";
-import { S as t, t as n, y as r } from "./ToneMapGPU-DpUZDMbQ.js";
+import { C as t, t as n, y as r } from "./ToneMapGPU-B6XIe3DU.js";
 //#region src/neural/NeuralRetouch.js
 var i = /* @__PURE__ */ e({
 	NeuralRetouch: () => m,

package/dist/{NeuralSuperRes-CbNvQjCw.js → NeuralSuperRes-PkgDLQcD.js}

@@ -1,5 +1,5 @@
 import { t as e } from "./rolldown-runtime-CAFD8bLK.js";
-import { S as t, t as n, y as r } from "./ToneMapGPU-DpUZDMbQ.js";
+import { C as t, t as n, y as r } from "./ToneMapGPU-B6XIe3DU.js";
 //#region src/EngineEvents.js
 var i = {
 	RENDER_COMPLETE: "engine:renderComplete",
@@ -20,6 +20,9 @@ var i = {
 	OBJECT_TRANSFORM_START: "engine:objectTransformStart",
 	OBJECT_TRANSFORM_END: "engine:objectTransformEnd",
 	TRANSFORM_MODE_CHANGED: "engine:transformModeChanged",
+	CAMERA_SWITCHED: "engine:cameraSwitched",
+	CAMERAS_UPDATED: "engine:camerasUpdated",
+	FOCUS_CHANGED: "engine:focusChanged",
 	AUTO_FOCUS_UPDATED: "engine:autoFocusUpdated",
 	ORTHO_HEIGHT_UPDATED: "engine:orthoHeightUpdated",
 	AUTO_EXPOSURE_UPDATED: "engine:autoExposureUpdated",
@@ -35,21 +38,50 @@ var i = {
 	DISPOSE: "engine:dispose",
 	DEVICE_LOST: "engine:deviceLost",
 	ISSUE: "engine:issue",
+	MODEL_LOADED: "engine:modelLoaded",
+	OBJECT3D_LOADED: "engine:object3dLoaded",
+	MODEL_ADDED: "engine:modelAdded",
+	SCENE_OBJECT_REMOVED: "engine:sceneObjectRemoved",
+	SCENE_UNLOADED: "engine:sceneUnloaded",
+	SCENE_REBUILD: "engine:sceneRebuild",
+	SCENE_SPILLED: "engine:sceneSpilled",
 	SCENE_METADATA_APPLIED: "engine:sceneMetadataApplied",
+	ENVIRONMENT_LOADED: "engine:environmentLoaded",
+	TEXTURES_REPROCESSED: "engine:texturesReprocessed",
+	RESOLUTION_CHANGED: "engine:resolutionChanged",
+	RESERVED_RENDER_SIZE_CHANGED: "engine:reservedRenderSizeChanged",
 	STORAGE_CHANGED: "engine:storageChanged"
-}, a = /* @__PURE__ */ e({
-	NeuralSuperRes: () => g,
-	SR_MAX_INPUT: () => c,
+}, a = Object.freeze({
+	[i.RENDER_COMPLETE]: "RenderComplete",
+	[i.RENDER_RESET]: "RenderReset",
+	[i.CAMERA_SWITCHED]: "CameraSwitched",
+	[i.CAMERAS_UPDATED]: "CamerasUpdated",
+	[i.FOCUS_CHANGED]: "focusChanged",
+	[i.MODEL_LOADED]: "ModelLoaded",
+	[i.OBJECT3D_LOADED]: "Object3DLoaded",
+	[i.MODEL_ADDED]: "ModelAdded",
+	[i.SCENE_OBJECT_REMOVED]: "SceneObjectRemoved",
+	[i.SCENE_UNLOADED]: "SceneUnloaded",
+	[i.SCENE_REBUILD]: "SceneRebuild",
+	[i.SCENE_SPILLED]: "SceneSpilled",
+	[i.SCENE_METADATA_APPLIED]: "SceneMetadataApplied",
+	[i.ENVIRONMENT_LOADED]: "EnvironmentLoaded",
+	[i.TEXTURES_REPROCESSED]: "TexturesReprocessed",
+	[i.RESOLUTION_CHANGED]: "resolution_changed",
+	[i.RESERVED_RENDER_SIZE_CHANGED]: "reserved_render_size_changed"
+}), o = /* @__PURE__ */ e({
+	NeuralSuperRes: () => _,
+	SR_MAX_INPUT: () => l,
 	SR_SCALE: () => 2,
-	presentRGBA8: () => b,
-	readDenoisedHalf: () => h,
-	releaseDenoisedReader: () => m,
-	renderUpscaled: () => v
-}), o = 2, s = t("neural"), c = 2048, l = null;
-function u() {
-	if (l) return l;
+	presentRGBA8: () => x,
+	readDenoisedHalf: () => g,
+	releaseDenoisedReader: () => h,
+	renderUpscaled: () => y
+}), s = 2, c = t("neural"), l = 2048, u = null;
+function d() {
+	if (u) return u;
 	let { neuralRuntimeUrl: e, neuralAssetBaseUrl: t } = r();
-	return t ? (globalThis.__NEURAL_ASSET_BASE__ = t, l = new Promise((t, n) => {
+	return t ? (globalThis.__NEURAL_ASSET_BASE__ = t, u = new Promise((t, n) => {
 		if (globalThis.NeuralRuntime?.getNativeSR) return t(globalThis.NeuralRuntime.getNativeSR());
 		let r = document.createElement("script");
 		r.src = e, r.onload = () => {
@@ -57,13 +89,13 @@ function u() {
 			if (!e) return n(/* @__PURE__ */ Error("Neural runtime loaded but exposed no super-resolution entry"));
 			t(e());
 		}, r.onerror = () => n(/* @__PURE__ */ Error(`Failed to load the neural runtime from ${e}`)), document.head.appendChild(r);
-	}), l) : Promise.reject(/* @__PURE__ */ Error("No neural model location: set neuralAssetBaseUrl with configureAssets()"));
+	}), u) : Promise.reject(/* @__PURE__ */ Error("No neural model location: set neuralAssetBaseUrl with configureAssets()"));
 }
-var d = "\n@group(0) @binding(0) var src: texture_2d<f32>;\n@group(0) @binding(1) var<storage, read_write> dst: array<u32>;\n\n@compute @workgroup_size(8, 8)\nfn main( @builtin(global_invocation_id) gid: vec3<u32> ) {\n	let size = textureDimensions( src );\n	if ( gid.x >= size.x || gid.y >= size.y ) { return; }\n	let c = textureLoad( src, vec2<i32>( gid.xy ), 0 ).rgb;\n	let a = ( gid.y * size.x + gid.x ) * 2u;\n	dst[ a ] = pack2x16float( c.rg );\n	dst[ a + 1u ] = pack2x16float( vec2<f32>( c.b, 1.0 ) );\n}\n", f = null;
-function p(e, t, n) {
-	if (f && (f.device !== e || f.width !== t || f.height !== n) && m(), f) return f;
+var f = "\n@group(0) @binding(0) var src: texture_2d<f32>;\n@group(0) @binding(1) var<storage, read_write> dst: array<u32>;\n\n@compute @workgroup_size(8, 8)\nfn main( @builtin(global_invocation_id) gid: vec3<u32> ) {\n	let size = textureDimensions( src );\n	if ( gid.x >= size.x || gid.y >= size.y ) { return; }\n	let c = textureLoad( src, vec2<i32>( gid.xy ), 0 ).rgb;\n	let a = ( gid.y * size.x + gid.x ) * 2u;\n	dst[ a ] = pack2x16float( c.rg );\n	dst[ a + 1u ] = pack2x16float( vec2<f32>( c.b, 1.0 ) );\n}\n", p = null;
+function m(e, t, n) {
+	if (p && (p.device !== e || p.width !== t || p.height !== n) && h(), p) return p;
 	let r = t * n * 8;
-	return f = {
+	return p = {
 		device: e,
 		width: t,
 		height: n,
@@ -83,20 +115,20 @@ function p(e, t, n) {
 			compute: {
 				module: e.createShaderModule({
 					label: "rayzee:neural-sr-pack",
-					code: d
+					code: f
 				}),
 				entryPoint: "main"
 			}
 		})
-	}, f;
+	}, p;
 }
-function m() {
-	f?.storage.destroy(), f?.map.destroy(), f = null;
+function h() {
+	p?.storage.destroy(), p?.map.destroy(), p = null;
 }
-async function h(e) {
+async function g(e) {
 	let t = e?._outGPUTexture;
 	if (!t) throw Error("NeuralSuperRes: no denoised frame — enable OIDN and finish a render first");
-	let n = e.gpuDevice, { width: r, height: i } = e._outTexSize, a = p(n, r, i), o = n.createBindGroup({
+	let n = e.gpuDevice, { width: r, height: i } = e._outTexSize, a = m(n, r, i), o = n.createBindGroup({
 		layout: a.pipeline.getBindGroupLayout(0),
 		entries: [{
 			binding: 0,
@@ -114,7 +146,7 @@ async function h(e) {
 		height: i
 	};
 }
-var g = class e {
+var _ = class e {
 	constructor(e, t) {
 		this.sr = e, this.canvas = t, this.slot = 0, this._color = null, this._depth = null, this._motion = null, this._toneMapper = null, this.disposed = !1;
 	}
@@ -135,8 +167,8 @@ var g = class e {
 	}
 	static async create({ width: t, height: n, onProgress: r = () => {} } = {}) {
 		if (!Number.isInteger(t) || !Number.isInteger(n) || t < 1 || n < 1) throw Error("NeuralSuperRes.create: width and height must be positive integers");
-		if (t > 2048 || n > 2048) throw Error(`NeuralSuperRes.create: input capped at ${c}px per side (${c * 2}px output), got ${t}x${n}. Above that the runtime's history plane exceeds maxTextureDimension2D and it fails later with an unrelated bind-group error.`);
-		let i = await u(), a = document.createElement("canvas");
+		if (t > 2048 || n > 2048) throw Error(`NeuralSuperRes.create: input capped at ${l}px per side (${l * 2}px output), got ${t}x${n}. Above that the runtime's history plane exceeds maxTextureDimension2D and it fails later with an unrelated bind-group error.`);
+		let i = await d(), a = document.createElement("canvas");
 		a.style.cssText = "position:fixed;left:-10000px;top:0;pointer-events:none", document.body.appendChild(a);
 		let o;
 		try {
@@ -199,12 +231,12 @@ var g = class e {
 			try {
 				this.sr.destroy();
 			} catch (e) {
-				s.warn("super resolution teardown:", e);
+				c.warn("super resolution teardown:", e);
 			}
 		}
 	}
 };
-function _(e, t, n) {
+function v(e, t, n) {
 	return new Promise((r, a) => {
 		let o = !1, s = (t, n) => {
 			o || (o = !0, e.removeEventListener(i.DENOISING_END, l), clearInterval(u), clearTimeout(d), t ? r() : a(n));
@@ -217,7 +249,7 @@ function _(e, t, n) {
 		}, 200), d = setTimeout(() => s(!1, /* @__PURE__ */ Error("NeuralSuperRes: timed out waiting for the render to finish")), n);
 	});
 }
-async function v(e, { outputWidth: t, outputHeight: n, samples: r = 64, upscaler: i = null, timeoutMs: a = 6e5, present: o = !0, onProgress: s = () => {} } = {}) {
+async function y(e, { outputWidth: t, outputHeight: n, samples: r = 64, upscaler: i = null, timeoutMs: a = 6e5, present: o = !0, onProgress: s = () => {} } = {}) {
 	if (t % 2 || n % 2) throw Error(`renderUpscaled: output must be divisible by 2, got ${t}x${n}`);
 	let c = t / 2, l = n / 2, u = e.stages?.pathTracer, d = {
 		width: u?.width,
@@ -229,7 +261,7 @@ async function v(e, { outputWidth: t, outputHeight: n, samples: r = 64, upscaler
 	try {
 		if (!p) {
 			let e = performance.now();
-			s("Loading the super-resolution model"), p = await g.create({
+			s("Loading the super-resolution model"), p = await _.create({
 				width: c,
 				height: l,
 				onProgress: s
@@ -237,17 +269,17 @@ async function v(e, { outputWidth: t, outputHeight: n, samples: r = 64, upscaler
 		} else if (p.inputWidth !== c || p.inputHeight !== l) throw Error(`renderUpscaled: upscaler is ${p.inputWidth}x${p.inputHeight}, need ${c}x${l}`);
 		let i = performance.now();
 		s(`Tracing ${c}x${l} at ${r} spp`), e.pauseRendering = !1, e.setCanvasSize(c, l), await new Promise((e) => setTimeout(e, 300)), e.denoisingManager.applyOIDNEnabled(!0), e.settings.set("maxSamples", r);
-		let u = _(e, r, a);
+		let u = v(e, r, a);
 		e.reset(), await u, e.pauseRendering = !0, m.render = performance.now() - i, s("Reading the denoised frame");
-		let d = performance.now(), f = await h(e.denoisingManager?.denoiser);
+		let d = performance.now(), f = await g(e.denoisingManager?.denoiser);
 		m.read = performance.now() - d, s(`Upscaling to ${t}x${n}`);
-		let v = {
+		let h = {
 			exposure: e.renderer.toneMappingExposure,
 			toneMapping: e.renderer.toneMapping,
 			saturation: e.settings.get("saturation") ?? 1
-		}, { rgba8: b, width: x, height: S, ms: C, toneMs: w } = await p.upscaleToRGBA8(f, v);
-		return m.upscale = C, m.tonemap = w, o && y(e.denoisingManager?.upscalerCanvas, b, x, S), {
-			rgba8: b,
+		}, { rgba8: y, width: x, height: S, ms: C, toneMs: w } = await p.upscaleToRGBA8(f, h);
+		return m.upscale = C, m.tonemap = w, o && b(e.denoisingManager?.upscalerCanvas, y, x, S), {
+			rgba8: y,
 			width: x,
 			height: S,
 			timings: m,
@@ -259,11 +291,11 @@ async function v(e, { outputWidth: t, outputHeight: n, samples: r = 64, upscaler
 		d.width && d.height && e.setCanvasSize(d.width, d.height), d.maxSamples !== void 0 && e.settings?.set?.("maxSamples", d.maxSamples), d.finalDenoise !== void 0 && e.denoisingManager?.applyOIDNEnabled(d.finalDenoise), e.pauseRendering = d.paused;
 	}
 }
-function y(e, t, n, r) {
+function b(e, t, n, r) {
 	return e ? (e.width = n, e.height = r, e.getContext("2d").putImageData(new ImageData(new Uint8ClampedArray(t.buffer ?? t), n, r), 0, 0), e.style.display = "block", !0) : !1;
 }
-function b(e, t, n, r) {
-	return y(e, t, n, r);
+function x(e, t, n, r) {
+	return b(e, t, n, r);
 }
 //#endregion
-export { i as a, v as i, c as n, o as r, a as t };
+export { i as a, y as i, l as n, a as o, s as r, o as t };