@meimu/mutracer 0.0.0-stage → 0.1.1

package/docs/materials.md

@@ -0,0 +1,281 @@
+# Materials
+
+`OpenPBRMaterial` implements the
+[OpenPBR 1.1](https://academysoftwarefoundation.github.io/OpenPBR/) surface.
+Property names use camelCase OpenPBR inputs plus compatibility names. Colors are
+linear RGB. Pass optional properties to `new OpenPBRMaterial(params)`; omitted
+properties use the defaults below and in TSDoc.
+
+```ts
+import { OpenPBRMaterial } from '@meimu/mutracer';
+
+const glass = new OpenPBRMaterial();
+glass.transmissionWeight = 1;
+glass.specularRoughness = 0;
+glass.transmissionColor = [0.72, 0.9, 1];
+glass.transmissionDepth = 0.5;
+
+const gold = new OpenPBRMaterial({
+  baseColor: [1.0, 0.78, 0.34],
+  baseMetalness: 1,
+  specularRoughness: 0.2
+});
+```
+
+Edit a material that is already rendering in place; the next `engine.update()`
+detects the change (see [scene updates](./updates.md#materials-textures-and-lights)
+for costs):
+
+```ts
+gold.specularRoughness = 0.4;
+gold.baseColor[1] = 0.7;
+```
+
+Materials occupy GPU slots by object identity: share one material object to
+share its slot. Separate objects with equal values take separate slots, but
+the textures they reference still share atlas space.
+
+## Inputs
+
+| Layer | Inputs (default) |
+| --- | --- |
+| Base | `baseWeight` (1), `baseColor` (0.8), `baseDiffuseRoughness` (0), `baseMetalness` (0) |
+| Specular | `specularWeight` (1), `specularColor` (1), `specularRoughness` (0.3), `specularIor` (1.5), `specularRoughnessAnisotropy` (0) |
+| Transmission | `transmissionWeight` (0), `transmissionColor` (1), `transmissionDepth` (0), `transmissionScatter` (0), `transmissionScatterAnisotropy` (0), `transmissionDispersionScale` (0), `transmissionDispersionAbbeNumber` (20) |
+| Subsurface | `subsurfaceWeight` (0), `subsurfaceColor` (0.8), `subsurfaceRadius` (1), `subsurfaceRadiusScale` ([1, 0.5, 0.25]), `subsurfaceScatterAnisotropy` (0) |
+| Fuzz | `fuzzWeight` (0), `fuzzColor` (1), `fuzzRoughness` (0.5) |
+| Coat | `coatWeight` (0), `coatColor` (1), `coatRoughness` (0), `coatRoughnessAnisotropy` (0), `coatIor` (1.6), `coatDarkening` (1) |
+| Thin film | `thinFilmWeight` (0), `thinFilmThickness` (0.5 µm), `thinFilmIor` (1.4), `thinFilmThicknessMinimum` (0 µm), `thinFilmMapChannel` (`r`) |
+| Emission | `emissionColor` (1), `emissionLuminance` (0) |
+| Geometry | `geometryOpacity` (1), `geometryThinWalled` (false), `doubleSided` (false) |
+
+Units: `transmissionDepth` and `subsurfaceRadius` are in scene units;
+`thinFilmThickness` is in micrometres (`0.45` = 450 nm).
+
+`baseWeight` scales diffuse reflection and the metallic normal-incidence color
+(`baseWeight * baseColor`). Dielectric specular, transmission and subsurface
+retain their own strengths. For metals, `specularColor` tints the F82 Fresnel
+curve near grazing angles and `specularWeight` scales the entire reflection,
+including thin-film reflection. At their default values, F82 reduces to Schlick.
+
+Native `specularRoughnessAnisotropy` and `coatRoughnessAnisotropy` use the OpenPBR GGX mapping:
+`alphaT = roughness² * sqrt(2 / (1 + (1 - anisotropy)²))` and
+`alphaB = (1 - anisotropy) * alphaT`, with the renderer's minimum alpha.
+Both layers use the geometry tangent; a separate coat tangent is not available.
+A rough coat broadens the underlying metal, dielectric reflection and transmission
+using `mix(rB, min(1, rB^4 + 2*rC^4)^0.25, coatWeight)` before the GGX mapping.
+
+`coatColor` is the squared transmittance at normal incidence. Each passage
+through the coat applies `sqrt(coatColor)` raised to the inverse refracted
+cosine. Coat reflection stays uncolored; reflection from the base crosses the
+coat twice, and transmission crosses it once. `coatDarkening` controls the
+extra darkening from internal reflections, while absorption remains active at
+zero. The base is attenuated by the coat directional albedo on the view side
+and by an internal-reflection factor estimated from the base slab albedos.
+Partial coat coverage is mixed independently for each passage.
+Thin film lies below the coat: its exterior IOR is `mix(1, coatIor, coatWeight)`
+and its dielectric substrate uses the adjusted absolute base IOR. A solid
+inside hit exchanges these media; uncoated films retain their existing behavior.
+Emission uses a normal-incidence single passage: it is multiplied by
+`mix(1, sqrt(coatColor), coatWeight)`. Without `coatWeightMap`, the same attenuated emission determines
+emissive-light selection and hit MIS weights. This approximation has no angular
+dependence and does not apply coat darkening or fuzz attenuation to emission.
+Unlit and shadow-catching materials keep their existing emission behavior.
+
+The base reflection beneath a coat uses the surrounding IOR
+`mix(1, coatIor, coatWeight)`. `specularWeight` adjusts the base IOR relative
+to that medium; refraction uses the resulting absolute base IOR relative to air.
+Solid back-face exits ignore the coat IOR; thin walls use the exterior rule
+on either side. Reflection inverts a coat-to-base ratio below one when the
+base IOR is at least one, avoiding false total internal reflection caused by
+the approximate coat model. Dispersion adjusts the base IOR before these rules.
+
+`fuzzColor` colors the fuzz reflection only. Fuzz attenuates the underlying
+material using its white directional albedo, so colored fuzz does not tint
+the substrate through the attenuation term.
+
+**Interior media.** Transmission describes a homogeneous volume:
+`transmissionColor` is the color that survives one `transmissionDepth`, and
+`transmissionScatter` is the scattering albedo. With `transmissionDepth = 0`
+the tint is applied at the surface. Subsurface is a separate layer driven by its
+color and per-channel radius. When both are active, their coefficients combine
+into one volume. Dispersion (`transmissionDispersionScale > 0`) samples
+wavelengths spectrally.
+
+## Compatibility names
+
+The canonical names below share storage with the deprecated names. Both work in
+constructor parameters, property reads/writes and Three.js metadata. If both
+are supplied together, equal values are accepted and conflicting values throw.
+Edits through either spelling are detected by the next `engine.update()`; see [scene updates](./updates.md).
+
+| Canonical name | Deprecated compatibility name | Default |
+| --- | --- | --- |
+| `specularRoughnessAnisotropy` | `specularAnisotropy` | `0` |
+| `coatRoughnessAnisotropy` | `coatAnisotropy` | `0` |
+| `subsurfaceScatterAnisotropy` | `subsurfaceAnisotropy` | `0` |
+| `geometryOpacity` | `opacity` | `1` |
+| `geometryThinWalled` | `thinWalled` | `false` |
+
+`materialKeys`, `materialParamKeys`, hashes and snapshots keep the compatibility
+storage names and order; aliases add no GPU fields. `Object.keys()` and JSON
+include the stored compatibility names only. The canonical accessors are not
+an alternate serialization format.
+
+## Textures
+
+| Property | Channel | Notes |
+| --- | --- | --- |
+| `map` | RGB (sRGB), A | Multiplies `baseColor`; alpha use set by `mapAlphaUsage` |
+| `alphaMap` | G | Opacity, as in Three.js |
+| `normalMap`, `normalScale` | RGB | Tangent space; tangents are generated when missing |
+| `metallicRoughnessMap` | G = roughness, B = metalness | glTF convention |
+| `roughnessMap` | G | |
+| `metalnessMap` | B | |
+| `emissiveMap` | RGB | Multiplies `emissionColor` |
+| `transmissionMap` | R | Multiplies `transmissionWeight` |
+| `thinFilmMap` | R by default; selectable R/G/B/A | Linear thickness range |
+| `displacementMap` | R | See [displacement](#displacement) |
+| `coatWeightMap` | Linear R | Multiplies `coatWeight`, including emission absorption |
+| `coatRoughnessMap` | Linear G | Multiplies `coatRoughness` before base roughening |
+| `coatNormalMap`, `coatNormalScale` | Linear RGB | Independent tangent-space coat normal; see [coat normals](#coat-normals) |
+| `fuzzColorMap` | sRGB RGB | Decoded color multiplies `fuzzColor` |
+| `fuzzRoughnessMap` | Linear A | Multiplies `fuzzRoughness` |
+| `specularWeightMap` | Linear A | Multiplies `specularWeight`, for dielectric and metal |
+| `specularColorMap` | sRGB RGB | Decoded color multiplies `specularColor`, for dielectric and metal |
+
+All six layer maps default to `undefined`. They resolve before coat roughening
+and BSDF preparation. Images may be shared between color and data slots;
+sRGB decoding happens only at color sample sites. See [anisotropy directions](#anisotropy-directions)
+for the RG/B slot and [coat normals](#coat-normals) for the independent normal input.
+
+With `coatWeightMap`, emission absorption uses the sampled coverage at each
+surface/mesh-light point. Light selection and emissive-hit MIS use raw constant
+emission luminance as a conservative proposal; absorption is applied once to
+the contribution. Black texture points can retain a positive sampling PDF.
+Removing the map restores the constant-coat packing path.
+
+`Texture.uvScale`, `uvOffset` and `uvChannel` (0 or 1) transform UVs per
+texture. For geometry without usable UVs, set `uvProjection` to
+`'triplanar'`, `'spherical'` or `'cylindrical'` with `uvProjectionScale` (default `[1, 1]`).
+
+With `thinFilmMap`, thickness interpolates from `thinFilmThicknessMinimum` to
+`thinFilmThickness` using the linear `thinFilmMapChannel`. The default minimum
+0 and channel `r` keep the original R-times-thickness behavior. Without a map,
+only `thinFilmThickness` is used. Endpoints are nonnegative and may be reversed,
+including a positive minimum and zero maximum. Nonfinite endpoints use their
+defaults; invalid channels throw during construction or packing.
+
+Call `texture.markUpdated()` after editing pixels or UV-array elements;
+assigning a new texture, image or UV array is detected automatically.
+
+## Alpha
+
+`alphaMode` is `'auto'` (default; derived from the alpha inputs), `'opaque'`,
+`'mask'` (alpha test against `alphaCutoff`) or `'blend'`. `mapAlphaUsage`
+selects how `map`'s alpha channel is used:
+`'opaque'` (default), `'alpha'` or `'transmission'`. Blended primary rays follow
+`render.alphaBlendStrategy`. Both WebGPU and WebGL 2 apply these modes to
+surface hits and shadow rays: `opaque` ignores opacity and alpha textures;
+`mask` resolves coverage to 0 below `alphaCutoff` and 1 at or above it;
+`blend` retains fractional coverage. In `auto`, a positive cutoff selects
+`mask`; otherwise opacity below 1, alpha use of `map`, or an `alphaMap`
+selects `blend`. With none of these inputs, `auto` selects `opaque`.
+
+## Renderer extensions
+
+| Property | Description |
+| --- | --- |
+| `shadowCatcher` | Invisible ground that only receives shadows; composite over a transparent background |
+| `unlit` | Shows emission without scattering or lighting other surfaces |
+| `bevelSize` | Rounded-edge shading radius in scene units; `0` disables (see below) |
+
+**Shader bevel.** `bevelSize > 0` rounds hard edges in shading only, without
+changing geometry or silhouettes. It samples nearby surface normals of the same
+instance, similar to Blender Cycles' Bevel node. `render.bevelSamples`
+trades noise for speed. A radius of 0.5–2% of the model size is a reasonable
+start.
+
+## Displacement
+
+`displacementMap` (red channel) with `displacementScale` (local units)
+ray-marches the height field in the shader. `displacementStepSize` controls the
+ray-marching step (default `0.01`). No extra triangles are generated.
+`displacementUvProjection` (default `'none'`) and `displacementUvProjectionScale`
+(default `1`) control height-map coordinates.
+
+The remaining `displacement*` properties are documented in the type declarations.
+
+## Known limitations
+
+Data-backed material atlases require RGBA8 `Uint8Array` sources. WebGL 2 can
+currently resolve zero for data-backed material maps; use DOM image or canvas
+sources on that backend. Float data remains supported for environments.
+
+Rough thin-wall glass can appear too dark because its reflection/transmission
+model includes only single microfacet scattering. Adobe's reference has no
+thin-wall transmission multiple-scattering compensation; this approximation
+is exact for smooth windows but loses energy as roughness increases.
+
+## Implementation notes
+
+The BSDF evaluates fuzz, coat, metal, dielectric specular, transmission,
+diffuse and subsurface as separate lobes, with energy compensation tables and
+thin-film interference adapted from
+[Adobe's OpenPBR BSDF](https://github.com/adobe/openpbr-bsdf). Small
+differences from offline references remain, from finite path depth, RGB
+thin-film evaluation and texture filtering.
+
+Metal reflection includes the reference's additional microfacet multiple
+scattering, scaled by the square of the average F82 reflectance. Its energy
+tables use the original isotropic roughness, also for anisotropic materials,
+so strong anisotropy can retain a small energy error. Solid transmission also
+includes the reference dielectric multiple-scattering lobe, using its
+refraction IOR for both reflected and transmitted compensation. It uses the
+original isotropic alpha and turns off below roughness 0.04. Its transmission
+scale follows the reference; single refraction retains the renderer's existing
+radiance IOR scaling. The combined model can retain an energy error, including
+with coat, and the finite path-event budget can truncate deep glass paths.
+
+## Coat normals
+
+Set `coatNormalMap` to give the coat a tangent-space normal independently of
+`normalMap`. The renderer decodes linear RGB as `2 * RGB - 1`, multiplies XY
+by `coatNormalScale`, then normalizes. The scale defaults to `[1, 1]` and can
+be negative or zero. A missing map (the default), zero coat weight or zero sampled coat coverage retains the existing shared
+shading normal, including the base normal map.
+
+The coat TBN starts from the interpolated geometry normal before base normal
+mapping. It uses the coat texture's UV0/UV1 selection and geometric
+tangent handedness; generated tangents use UV1 differentials when that set is
+selected. Degenerate frames and zero decoded vectors use stable fallbacks.
+The texture's scale, offset and `flipY` follow the ordinary atlas sampling
+rules. As with other slots, sharing an image never changes its color space.
+
+Base lobes keep their base frame. Coat reflection, its sampling PDF, directional
+albedo and passage absorption use the coat frame; the renderer combines their
+responses and densities for the same world direction. Each frame is corrected
+against the geometric/view hemisphere independently. Triangle normals still
+control reflection versus transmission, medium boundaries and ray offsets.
+A coat reflection can contribute below the base shading hemisphere when it
+remains above the coat and geometric hemispheres. As before, solid interior
+hits omit coat reflection; thin surfaces are treated as exterior hits.
+
+Strongly tilted shading normals lose some lobe support when clipped to the
+geometric hemisphere. A unit white environment can therefore render below
+unit radiance; the renderer does not renormalize the clipped lobes.
+
+Replacing the map or editing its scale is detected by `engine.update()`. Call
+`texture.markUpdated()` after pixel or UV-array element edits; see [scene updates](./updates.md).
+These edits update material parameters/textures without rebuilding geometry. Normal maps do not alter
+emission's existing normal-incidence absorption or light-selection proposals.
+
+## Anisotropy directions
+
+Set `specularAnisotropyRotation` or provide `anisotropyMap` to orient the base specular lobe. The map reads linear `2 * RG - 1`, normalizes the direction, multiplies strength by B, and then applies the rotation. A decoded squared length at or below `1e-4` falls back to `(1, 0)` before rotation (including the two central RGBA8 codes). Without a map the direction is `(1, 0)` and the strength multiplier is one. The rotation defaults to zero; the map defaults to undefined.
+
+`coatAnisotropyRotation` defaults to zero and uses the geometry tangent independently of the base map. Base and coat evaluation, sampling and PDF use their respective directions. The coat uses the shared shading normal unless `coatNormalMap` selects an [independent normal](#coat-normals). Zero strength ignores the new direction and retains the original isotropic path.
+
+Provided tangent XYZ and optional W handedness are preserved. For XYZ tangents the sign comes from triangle UV derivatives. Missing or degenerate tangents use UV derivatives and then a stable orthonormal fallback; missing tangents produce one diagnostic per geometry. The direction texture's selected UV set is used for derivative fallback, including UV1. A provided XYZW tangent remains authoritative. Directions are reorthogonalized against the final shading normal, including normal maps and back faces, and instance transforms preserve mirrored handedness. UV scale, offset and flipY affect texel lookup; they do not rotate the encoded direction.
+
+The direction and strength inputs use native OpenPBR semantics by default. For imported glTF/Three.js strength, select `specularAnisotropyModel: 'gltf'`; the same roughness and strength properties then retain source values. Source scalar inputs are clamped to [0, 1] before texture factors; non-finite source roughness/strength fall back to 0.3/0. Native scalar handling is unchanged. Zero source strength preserves the original roughness path. The conversion matches the GGX alpha axes before existing minimum-alpha clamping; Fresnel, masking, multiple scattering and OpenPBR coating remain the library's model. See [the conversion rules](./threejs.md#anisotropy-source-conversion).

package/docs/performance.md

@@ -0,0 +1,85 @@
+# Performance
+
+A tuning checklist. Each item links to the page with the details.
+
+## Resolution and samples
+
+- Rays per sample scale with pixel count. Cap the device pixel ratio
+  (`Math.min(devicePixelRatio, 2)`, or lower on mobile).
+- Set `maxSamples` for the quality you need. With a denoiser, 64–256 spp is
+  usually enough; without one, 1000+ for clean results.
+- Start with `bounces` 3–5. Raise it for glass, subsurface scattering or
+  interiors lit indirectly, not everywhere.
+- `clamping` removes fireflies at the cost of bias; use the smallest value
+  that works.
+
+## Responsiveness
+
+- Use a preview Render with cheaper quality and optional adaptiveResolution:
+  `{targetFrameMs: 20, minScale: .25}`, plus resolutionScale .5. Choose it during
+  motion and configure final.fallback once; see [progressive rendering](./progressive-rendering.md).
+- timeBudgetMs (default 21) bounds each render's tile cost. Raise it for exports.
+- allowMultipleSamplesPerFrame adds several samples per refine when time permits.
+- For exports, `render.converge` with `targetBatchTimeMs` adapts batch sizes
+  to the GPU; omit `previewIntervalMs` for maximum throughput.
+
+## Scene setup
+
+- Share `Geometry`, `OpenPBRMaterial` and `Texture` objects. Shared geometry
+  shares its BLAS and GPU buffers.
+- For large scenes, try `engine.bvhBuilder = 'tinybvh'` and build BVHs up
+  front with optional `await engine.prepare(nextScene)`. Tune `bvhWorkerCount` for
+  parallel construction across geometries; see [BVH](./bvh.md).
+- With Three.js, keep one `THREESync(engine, {scene, camera, controls})` for the whole session rather than
+  converting again with `fromTHREEScene`.
+- Textures share an atlas bounded by `textureAtlasBudgetBytes`; larger textures
+  are downscaled. Check `engine.getDiagnostics()?.textureAtlas`.
+
+## Animation and editing
+
+See [scene updates](./updates.md) for the cost of each kind of edit.
+
+- Edit `mesh.transform` in place: transform changes only refit instances.
+- For vertex animation, keep the arrays, set `geometry.dynamic = true` and call
+  `geometry.markVerticesUpdated()`, not `markUpdated()`.
+- Avoid [full mesh updates](./updates.md#full-mesh-updates) per frame:
+  replacing arrays, changing displacement, or adding new geometry.
+- Three.js skinning and morph targets run on the CPU; cost grows with
+  vertices, bone influences and material groups. An unchanged pose is free.
+- Each `InstancedMesh` instance adds one top-level BVH instance per material
+  group. Native instance colors share the same materials.
+
+## Lighting
+
+- Prefer `RectLight` and `SphereLight` to small emissive meshes: analytic
+  lights are sampled directly and converge faster.
+- Scenes with many lights benefit from more `directLightCandidates` (WebGPU).
+- A bright, small sun in an environment map is importance sampled, but a
+  `DirectionalLight` is cleaner when the sun is the key light.
+
+## Shader compilation
+
+The path-tracing shaders are large. The first frame can take several seconds
+to compile on some platforms (`'compiling'`). Materials
+with displacement or alpha, and some renderer options, select shader variants
+that compile on first use. Show a status while compiling, as the examples do.
+
+## Diagnostics
+
+`engine.getDiagnostics()` reports the backend and adapter, shader
+compilation times, BVH statistics, light sampling setup and GPU trace timing.
+`presentedTarget` is the presented render label after the first complete image
+(`undefined` beforehand); `presentedComplete` is initially `false`.
+`targets` lists each resident accumulation's `label`, `width`, `height` and
+allocated GPU payload `bytes`, including its retained outputs. It excludes shared scene data and temporary image passes, shader/driver overhead,
+and resources queued for release. Each render retains accumulation buffers,
+resolved outputs, its last complete composition and its valid denoised result.
+Post-processing, readback and denoising scratch resources are shared by the engine;
+their allocated capacity grows to the largest required dimensions.
+
+Preview and final keep independent outputs. Switching uses their complete
+images without reallocating them; final's first tiled sample keeps preview on
+screen until it completes. Adaptive resolution may rebuild only the preview
+target; its previous complete image remains available through the rebuild.
+Targets are created lazily and remain resident until disposed. Resolution,
+quality and interaction exceptions are explicit application choices.

package/docs/post-processing.md

@@ -0,0 +1,87 @@
+# GPU output and display passes
+
+After a render has a complete sample, borrow its WebGPU textures with
+`render.getOutputTexture('hdr')` or `render.getOutputTexture('display')`.
+To add an overlay or another display effect, register a synchronous pass:
+
+```ts
+const remove = engine.display.addPostProcess(ctx => {
+  // Record a render or compute pass on ctx.encoder.
+  // Read ctx.input and fully write ctx.output, including alpha.
+  // Use ctx.output.format when creating the pipeline.
+  drawOverlay(ctx);
+});
+engine.display.present(final);
+const png = await engine.display.toBlob(final);
+remove(); // Safe to call again.
+```
+
+Passes run in registration order on every `present()` and `toBlob()`, after
+composition and denoising. They receive the selected complete render, including
+fallbacks, at its actual dimensions. Export uses the same chain without resizing
+or changing the display canvas. `readPixels()` never runs these passes.
+
+For a complete overlay implementation, see
+[`createCrosshairPass`](../examples/shared/crosshairPass.ts). It loads the input
+with `textureLoad`, draws a white crosshair in display space and writes every
+output pixel. The [basic example](../examples/basic.ts) enables it with `?overlay`:
+
+```ts
+import { createCrosshairPass } from './shared/crosshairPass';
+const removeCrosshair = engine.display.addPostProcess(createCrosshairPass());
+```
+
+A changing overlay can read application state in its callback. `RenderLoop`
+stops presenting after convergence, so explicitly call `display.present(final)`
+when that state changes. This refreshes the overlay without tracing more samples.
+
+## Options and image semantics
+
+`getOutputTexture(kind)` requires `'hdr'` or `'display'`; both return undefined
+on WebGL, before a complete sample or after disposal. There are no passes by
+default. `addPostProcess(pass)` returns an idempotent unregister function.
+`PostProcess` and `PostProcessContext` are exported types.
+
+| Image | Meaning |
+| --- | --- |
+| HDR | Native resolved linear ray RGB, before denoising, exposure, grading, tone mapping, vignette, bloom or display background/catcher composition. Same normalization and raw path-coverage alpha as `DenoiseInput.color` |
+| Display | Latest composed display channel, including denoising and the display pass chain; encoded display RGB and straight alpha (diagnostic channels retain their native values) |
+
+Images have their first row at the top. HDR currently uses `rgba16float`;
+ordinary display uses `rgba8unorm`, extended-range output uses `rgba16float`,
+and diagnostic channels may use their native format. Inspect `texture.format`
+and dimensions rather than assuming a format. Extended-range display RGB is
+still encoded for presentation; it is not the original HDR ray color.
+
+HDR RGB divides by primary hits when there are hits, otherwise by sample count.
+For an opaque flat background, `readPixels('hdr')` additionally multiplies RGB
+by primary-hit coverage for partially hit pixels, restoring the per-sample
+average. Thus that CPU readback can differ from the borrowed native HDR texture.
+See [custom denoiser image semantics](./denoising.md#custom-denoisers).
+
+## Caveats
+
+Textures are borrowed and read-only. Do not retain, write or destroy returned
+textures. Their validity ends at the render's next `refine()`/`converge()`, or
+the display's next `present()`/`setSize()`; restart, disposal and device loss
+also invalidate them. Fully transparent PNG pixels have no preserved RGB
+value after the browser canvas encoding/decoding round trip. Submit your reads before that boundary. Callback images
+and encoder are borrowed only during the synchronous callback; record all work
+there and let MuTracer finish and submit the encoder. Do not submit separate
+work, mutate input or retain the output. Device recovery may replace the device,
+so cache pipelines by both device and output format.
+
+The output supports `RENDER_ATTACHMENT`, `STORAGE_BINDING`, `TEXTURE_BINDING`
+and copy usage. Each pass must fully write it; previous contents are unspecified.
+The input and output never alias. WebGL skips all registered passes and warns
+once per display. A synchronous callback exception skips the remaining passes,
+discards the chain's recorded commands, displays the original composed image
+and emits the engine `error` event. GPU validation errors remain WebGPU errors;
+the callback must record valid commands.
+
+## Implementation notes
+
+The composed image is kept separately, so a thrown callback cannot leave a
+partly processed result.
+Display passes do not enter denoiser inputs, change samples or invalidate cached
+filter results. HDR-stage callbacks are outside this API.

package/docs/progressive-rendering.md

@@ -0,0 +1,160 @@
+# Progressive rendering
+
+Use RenderLoop for interactive preview and final rendering; use the first layer
+when your application needs explicit selection and frame budgets.
+
+```ts
+const sync = new THREESync(engine, {scene: threeScene, camera: threeCamera, controls});
+const loop = new RenderLoop(engine, {sync});
+loop.start();
+```
+
+## Loop policy
+
+Each tick updates syncs and commits engine inputs, then calls select, refines the
+selected render and presents it. Active syncs select preview by default. Isolated
+edits start final immediately; consecutive changes without explicit sync activity
+hold preview for idleMs (default 150 ms). When interaction ends, final starts after
+the current preview completes; its fallback remains visible until final completes a sample.
+With intermediate denoising enabled, it stays visible until the first filtered final image is ready.
+
+```ts
+loop.select = ({changing}) => changing || slider.dragging ? 'preview' : 'final';
+loop.on('status', ({status, previous}) => updateStatus(status));
+loop.on('sample', ({samples, frameTimeMs}) => updateSamples(samples));
+```
+
+Loop status is previewing when the displayed target is preview, including fallback
+presentation and the wait for the first complete final image. Starting to trace
+final tiles does not change that status until final is actually presented.
+Preview samples never emit loop sample events or count toward loop
+samples. Intermediate final filtering reports converging; only terminal filtering
+reports denoising. After finishing, unchanged ticks update syncs and the engine
+without GPU submissions. Display or render settings edits resume necessary work.
+
+During interaction, the loop finishes the current preview sample before applying
+the latest scene/camera edits, keeping previews responsive during continuous input.
+
+start pauses on hidden pages; stop preserves images. Use tick with your own frame
+loop, or start, which ignores manual tick calls with one warning. loop.converge
+pauses interactive ticks, converges/presents final and resumes if still started.
+
+coalesceSceneUpdates defaults to false. When enabled, preview inference defers
+engine commits while syncs keep collecting edits. The last presented image stays
+visible until the next filtered preview is ready. Completed inference is presented
+before the latest camera/scene is committed together. Interaction ending during
+inference waits for that result before final starts. With it disabled, changes
+immediately invalidate old inference. Once final is available, unused fallback
+inference does not delay it or switch presentation back to preview.
+Render.denoising includes intermediate
+inference without changing status semantics. Denoising does not enable preview;
+preview: false always disables it.
+
+## Explicit frame control
+
+Create one `Engine` for a scene and camera, then one `Render` per output. The
+engine owns shared GPU scene data; a render owns its image and complete sample
+count. `Display` owns canvas presentation and display settings.
+
+```ts
+import { Engine, Render } from '@meimu/mutracer';
+const engine = new Engine({ canvas });
+engine.scene = scene;
+engine.camera = camera;
+const preview = new Render(engine, {
+  resolutionScale: .5,
+  timeBudgetMs: 80,
+  adaptiveResolution: { targetFrameMs: 80, minScale: .125 },
+  bounces: 2, bevel: false, dispersionWavelengths: 1,
+  directLightCandidates: 2,
+});
+const final = new Render(engine, { fallback: preview });
+function frame() {
+  engine.update();
+  const current = dragging ? preview : final;
+  current.refine();
+  engine.display.present(current);
+  requestAnimationFrame(frame);
+}
+frame();
+```
+
+`engine.update()` is the only external edit detection and commit point. Until
+it runs, object edits and scene/camera replacement have no effect on tracing.
+Call it once after updating your scene and controls, even when several renders
+are refined that frame. See [scene updates](updates.md) for notifications.
+
+## Reading and exporting
+
+A fixed-size render does not need to be displayed. Its camera defaults to the
+committed engine camera, with automatic aspect based on its target dimensions.
+An explicitly supplied camera aspect is preserved.
+
+```ts
+const image = new Render(engine, { width: 256, height: 256 });
+engine.update();
+await image.converge({ samples: 64, sampleSequenceOffset: 0 });
+const hdr = await image.readPixels('hdr'); // this image, regardless of other activity
+const blob = await engine.display.toBlob(image);
+image.dispose();
+```
+
+`toBlob` uses the specified render's actual dimensions and the display's
+settings. It does not resize or change the display canvas. `converge` accepts a
+camera override, copied on entry, without replacing `engine.camera`. If engine
+input revisions change during a convergence task, the task rejects. Only that
+render rejects `refine()` while convergence is running; other renders remain
+usable.
+
+## Options and ownership
+
+- RenderLoop: preview/final selection, syncs, idleMs and coalesceSceneUpdates.
+- Engine: backend, scene/camera, BVH preparation and texture atlas budget.
+- Display: size, tone mapping, color grading, bloom, HDR output, channel and
+  shadow-catcher color/opacity. Editing these does not restart accumulation.
+- Render: resolution, samples, path quality, alpha handling, execution budget,
+  fallback and denoiser. `transmissiveOutputAlphaMin` belongs to Render because
+  it is evaluated along individual paths, so changing it restarts that render.
+
+RenderLoop creates a half-resolution preview with adaptive scale .125–.5,
+80 ms budget, 2 bounces, no bevel, one wavelength and two light candidates;
+other settings use Render defaults. Pass preview settings, a Render or false.
+Preview resolution drops when interaction is slow and recovers gradually when
+performance improves. Final resolution stays independent of preview adaptation.
+Pass final settings or a Render; newly created finals use preview as fallback.
+Supplied Render/Sync objects must belong to this engine. loop.dispose releases
+only renders it created; dispose supplied renders, syncs and controls yourself.
+
+The default render scale is 1 and adaptive resolution is disabled. Alternatively,
+provide both fixed width and height at construction; fixed dimensions cannot be
+changed through `resolutionScale`. `width` and `height` report the actual GPU
+image, including WebGPU's 16-pixel alignment. See [API options](api.md).
+
+Keep the display canvas at the viewport's drawing-buffer size and set
+`resolutionScale` on each render independently. Lowering final's scale does not
+lower preview's scale; resizing the display canvas affects both.
+
+Call `render.setDenoiser({ type: 'jnlm', schedule: 'converged' })` with JNLM or an OIDN
+configuration. The schedules are `converged` (default), `progressive` (first
+sample, then 4, 8, 16, … with a ten-second limit), and `every-sample`. Same-engine
+renders share equal filter configurations and OIDN weight downloads. The engine
+releases a network when its last render lease is released. OIDN is ignored with
+a warning on WebGL; JNLM works on both backends.
+
+## Caveats
+
+A fallback has only one level and must belong to the same engine. If the first
+full sample is predicted to exceed the frame budget, `refine` supplies a sample
+to a stale fallback before continuing. A current fallback is reused; a fast
+final sample does not render the fallback. `present` selects the requested
+complete image, then its complete fallback, and otherwise leaves the canvas
+unchanged. It never traces.
+
+`prepare(nextScene)` performs optional CPU BVH preparation without disturbing
+the current GPU scene. Setting `engine.scene` and calling `update` commits a
+scene switch for every render. Only one GPU scene resides in an engine.
+
+Dispose renders when no longer needed; `engine.dispose()` releases every render
+and shared resource. Initialization and asynchronous filter failures use the
+engine's `error` event. `Render.status` is independent for each output; the
+first-layer API leaves frame selection and application UI status to the caller.

package/docs/sampling.md

@@ -0,0 +1,40 @@
+# Sampling patterns
+
+`render.samplingPattern` selects the sample sequence. Changing it restarts
+accumulation. The denoiser never changes it.
+
+| Pattern | Use |
+| --- | --- |
+| `'sobol'` (default) | General use, and with any denoiser. Owen-scrambled Sobol; converges well per pixel with spatially decorrelated error |
+| `'zsobol'` | Low sample counts **without** a denoiser. Morton-ordered Sobol with blue-noise error |
+| `'random'` | PCG white noise; an independent Monte Carlo reference |
+
+```ts
+render.samplingPattern = 'zsobol';
+```
+
+## Caveats
+
+- **ZSobol budget**: ZSobol sizes its pattern from `maxSamples`, rounded up to
+  a power of two and capped at 65536 (unlimited rendering uses the cap).
+  Changing the rounded budget restarts accumulation. The first sample always
+  has blue-noise error; later prefixes of a large budget cannot all keep it.
+- **Determinism**: offline sequences are deterministic, including
+  `sampleSequenceOffset`. Use disjoint offset ranges for animation frames.
+- **Backends**: WebGPU and WebGL 2 can differ in floating-point rounding even
+  with identical sequence points.
+- **Fireflies**: very narrow specular lobes under directional lights can
+  produce rare, large contributions with any pattern. Sampling does not clamp
+  them; use `render.clamping` if needed.
+
+## Implementation notes
+
+- `sobol` uses Burley's Owen-scrambled 2D Sobol sequences, scrambled
+  independently per pixel and domain.
+- ZSobol is blue-noise-first: sample zero uses a one-sample ZSobol pattern,
+  and later samples use an independent scramble for the remaining budget.
+- On WebGPU each pixel follows its own sequence, so adaptive sampling and
+  preview tiles do not skip sequence points.
+- Camera, aperture, light, BSDF and phase sampling use separate dimensions;
+  spectral wavelengths reuse them to reduce colored noise. Interactive resets
+  keep seed zero for stable screen-relative noise.