rayzee 11.7.0 → 11.9.0

package/README.md

@@ -100,8 +100,9 @@ npm install rayzee three
    // Load a 3D model (place .glb in public/ folder)
    await engine.loadModel('/scene.glb');
 
-   // Or load an environment map
-   // await engine.loadEnvironment('/environment.hdr');
+   // Light it: a model alone renders black. The physical sky needs no file;
+   // for an HDRI, await engine.loadEnvironment('/environment.hdr') instead.
+   await engine.environmentManager.setMode('procedural');
 
    // Start rendering
    engine.animate();
@@ -146,7 +147,7 @@ A single HTML file — no Node.js, no build step. Uses [ES module import maps](h
       "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",
+      "oidn-web/": "https://cdn.jsdelivr.net/npm/oidn-web@0.5.0/",
       "rayzee": "https://cdn.jsdelivr.net/npm/rayzee/dist/rayzee.es.js"
     }
   }
@@ -165,6 +166,8 @@ A single HTML file — no Node.js, no build step. Uses [ES module import maps](h
     await engine.init();
     // Replace with your own model URL
     await engine.loadModel('https://your-cdn.com/scene.glb');
+    // Light it: a model alone renders black. The physical sky needs no file.
+    await engine.environmentManager.setMode('procedural');
     engine.animate();
 
     window.addEventListener('resize', () => {
@@ -545,8 +548,16 @@ 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).
+Runnable examples live in the repository's `rayzee/examples/`, each run against the engine in that checkout:
+
+| Example | What it shows | Run (from the repository root) |
+|---|---|---|
+| `core-node.mjs` | the core alone, in Node, writing a PNG | `npm run example:node` |
+| `core-browser/` | the core plus the physical sky, accumulating on a canvas | `npm run example:browser` |
+| `viewer-browser/` | the full engine in a page: a model, an HDRI, OIDN on the finished image | `npm run example:viewer` |
+| `render.mjs` | the full engine in Node: any model and sky, any size, denoised, saved as `render.png` (options at the top of the file) | `npm run example:render -- --model scene.glb` |
+
+`npm run bench:examples` runs all four and fails if any of them throws or logs an error or warning.
 
 #### Add-ons
 
@@ -1060,6 +1071,7 @@ surface** — pin a version and branch on the strings; they are never renamed or
 | `adapter.software` | the GPU is a software rasteriser (SwiftShader, llvmpipe, lavapipe, WARP) |
 | `asset.unreachable` / `asset.ambiguous_entry` | the asset could not be fetched, or an archive held several candidate models |
 | `asset.archive_too_large` / `asset.entry_too_large` | an archive or one of its entries exceeded the byte budget |
+| `asset.parameters_ignored` | a pbrt scene sets parameters the loader ignores (`detail.unused`) or only approximates (`detail.approximated`), each `directive type: name` with how many directives set it — a warning |
 | `texture.build_failed` / `texture.processing_fallback` / `texture.limit_exceeded` | a texture could not be built, fell back to a slower path, or exceeded the per-map-type cap |
 | `environment.load_failed` | the environment map failed to load |
 | `setting.unknown_key` | a setting name reached no stage — how a typo becomes a wrong image |
@@ -1079,6 +1091,19 @@ surface** — pin a version and branch on the strings; they are never renamed or
 `asset.unreachable` also covers what the engine fetches for itself: OIDN weights, IES profiles and
 gobos (`detail.asset` says which).
 
+`init()` cannot degrade past a missing GPU, so these three always reject it with an
+`EngineIssueError`, strict or not, and are recorded too. `error.cause` is the WebGPU error, when there was one:
+
+| Code | Raised when |
+|---|---|
+| `webgpu.unavailable` | there is no `navigator.gpu`, or three.js could start only WebGL2 on the canvas |
+| `adapter.unavailable` | `requestAdapter()` returned no adapter or rejected — no GPU, or no driver for it |
+| `device.unavailable` | the adapter was found but `requestDevice()` rejected |
+
+```js
+try { await engine.init(); } catch (error) { metrics.failure = error.code ?? 'unknown'; }
+```
+
 `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.
 
@@ -1701,7 +1726,7 @@ import { setBindingAudit, getBindingAuditFindings, clearBindingAuditFindings } f
 
 | Package | Purpose | Install needed? |
 |---|---|---|
-| `oidn-web` | Intel Open Image Denoise for high-quality final renders | Yes — `npm install oidn-web` (**>=0.4.0**) |
+| `oidn-web` | Intel Open Image Denoise for high-quality final renders | Yes — `npm install oidn-web` (**>=0.5.0**) |
 | `onnxruntime-web` | AI-powered upscaling | No — loaded from CDN at runtime |
 | `@bb-studio/ocio` | OpenColorIO runtime for [Colour Management](#colour-management) (~6 MB WebAssembly) | Only to load colour configs — `npm install @bb-studio/ocio`, then pass it as `ocioRuntimeFactory` |