illutions 0.31.0 → 0.33.0

package/CHANGELOG.md

@@ -1,233 +1,284 @@
-# Changelog
-
-## 0.31.0
-
-### Added
-
-- Added the optional `recursive` parameter to `Engine.setMaterialProps()` and `Mesh3D.setMaterialProps()` to include all descendant meshes.
-- Added `Coll3D` and `Coll3DParams` for persistent mesh-based raycast colliders with `hidden`, `pickable`, and `occluder` roles and an optional `target` that maps raycast events to another `Mesh3D`.
-- Added `Obj3DParams` and the persistent `Obj3D.hidden` state, which hides the rendered object without disabling raycasting and is included in combined visibility events.
-- Added optional `{ class, params }` entries through `SceneEntry` and `WebEntry`; `WebParams` values are assigned to matching custom-element instances during app initialization.
-- Added `CompsInsts` to map Scene Component and Web Component definitions to their runtime instances.
-- Added `EnvLoadedEvent` with `Env_Loaded` after the initial environment is applied and all progressive background loading attempts complete; failed background maps may be skipped, and canceled or superseded loads do not emit the event.
-- Added `cfg.render.adaptiveGfx`, `cfg.render.ecoMode`, and `cfg.render.fpsMin` for adaptive graphics quality and Eco mode configuration.
-- Added the exported `AaMode`, `WebGlAaMode`, `WebGpuAaMode`, `WebGlSslMode`, `WebGpuSslMode`, `DebugLog`, and `MsaaMode` configuration types.
-- Added WebGPU SSGI with AO and GI output, adaptive warm-up, configuration, and Inspector controls.
-
-### Renamed
-
-- `Engine.setMaterialProperties()` → `Engine.setMaterialProps()` and `Mesh3D.setMaterialProperties()` → `Mesh3D.setMaterialProps()`
-
-- `Classes` → `Comps`
-- `Comp` → `Web`
-- `CompEvent` → `WebEvent`
-- `CompOverlapEvent` → `WebOverlapEvent`
-- `CompVisibleEvent` → `WebVisibleEvent`
-- `Comp_Overlap_Changed` → `Web_Overlap_Changed`
-- `Comp_Visible_Changed` → `Web_Visible_Changed`
-- `CompOverlapEvent.comp` → `WebOverlapEvent.web`
-- `CompVisibleEvent.comp` → `WebVisibleEvent.web`
-- `CompClass` → `WebClass`
-- `Obj3DClass` → `SceneClass`
-- `CompInsts` → `WebInsts`
-- `Obj3DInsts` → `SceneInsts`
-- `Comp.comps` → `Web.webs`
-
-### Changed
-
-- Replaced the `objs3D` and `comps` registry groups with `comps.scene` and `comps.web`; initialized instances are now exposed through `app.comps.scene` and `app.comps.web`.
-- Changed `Raycast.setColliders()` and `Raycast.clearColliders()` to accept arrays of registered `Coll3D` instances and use or reset their persistent collider roles; removed the exported `Collider` interface.
-- Replaced the individual post-processing enable settings with typed `cfg.render.profile.webgl` and `cfg.render.profile.webgpu` settings for MSAA, AA, SSL, and SSR.
-- Renamed `cfg.post.ssao` to `cfg.post.ssl` and simplified the exported post-processing config type names to `SslCfg`, `SsaoCfg`, `GtaoCfg`, `SsgiCfg`, `WebGlSsrCfg`, and `WebGpuSsrCfg`.
-- Renamed `cfg.post.webgpu.ssao` to `cfg.post.webgpu.gtao` and removed the obsolete `distanceExponent` and `distanceFallOff` settings.
-- Replaced `cfg.render.params.antialias` with renderer-specific `profile.msaa` settings, supporting `'none'`, `'render'`, and `'post'`.
-- Replaced `cfg.render.fpsLimiter` and `cfg.render.fpsMax` with `cfg.render.adaptiveGfx`, `cfg.render.ecoMode`, and `cfg.render.fpsMin`.
+# Changelog
+
+## 0.33.0
+
+### Added
+
+- Added `Scene.setMaterialsProps()` and `Scene.animMaterialsTo()` with `obj` and optional `recursive` to update or animate all assigned material slots once per material; `Mesh3D` provides object-bound counterparts. Animation events remain per material.
+
+### Renamed
+
+- `Scene.animMaterialNumeric()` → `Scene.animMaterialTo()`
+- `AnimFadeEvent` → `AnimMaterialEvent`, `Anim_Fade_Start` → `Anim_Material_Start`, `Anim_Fade_Complete` → `Anim_Material_Complete`, and `objName` → `materialName` for material animation events.
+- `Scene.stopAnimClip()` → `Scene.stopClip()`; `fadeOut` → `speedTime` and `ease` → `speedEase`.
+- Renamed parameters in `Scene.playClip()` and `Scene.playClipCam()`: `blendMode` → `modeBlend`, `loopMode` → `modeLoop`, `stopMode` → `modeStop`, `fadeDuration` → `fadeTime`, `startSpeed` → `speedStart`, `endSpeed` → `speedEnd`, `duration` → `speedTime`, and `ease` → `speedEase`. For `Scene.playClip()`, also renamed `finishMode` → `modeFinish` and `fadeDurationFinish` → `fadeTimeFinish`.
+- `duration` → `time` in `Scene.animCamTo()`, `Scene.animCamCurveTo()`, and `Scene.animTransformTo()`; material animation methods now also use `time`.
+- `fade` → `time` in `Audio.loadAndPlay()`, `Audio.play()`, `Audio.pause()`, and `Audio.stop()`.
+
+### Changed
+
+- Removed the optional `startValue` parameter from `Scene.animMaterialTo()`; it always animates from the current material value to the target value.
+- Changed `Scene.animMaterialTo()` to accept only a material name through `name` instead of `mesh`; assigned materials are resolved by name, including material slots.
+- Changed `Scene.setMaterialProps()` to accept `name` instead of `obj` and removed its `recursive` option; use `Scene.setMaterialsProps()` for object-wide updates. Renamed `Mesh3D.setMaterialProps()` to `Mesh3D.setMaterialsProps()`.
+- Merged numeric and color material animation into `Scene.animMaterialTo()` and removed the singular material animation methods from `Mesh3D`; components use `this.scene.animMaterialTo()` for one named material. Multiple properties share one tween, duration, easing, and repeat setting.
+- Material animations now emit one `AnimMaterialEvent` per start, completion, or cancellation with a `values` snapshot instead of individual `property` and `value` fields; colors are hex strings.
+- Added `Anim_Material_Cancel`: a new valid material animation cancels the entire previous animation of the same material. Unknown materials, unknown easing functions, and empty property lists leave the current tween unchanged; property names and target values are the caller's responsibility; zero duration applies values immediately, and infinite repeats do not emit completion.
+
+## 0.32.0
+
+### Added
+
+- Added `Scene.animTransformTo({ obj, pos?, rot?, scale?, duration?, ease? })` for local transformations with rotation in degrees; new calls replace the previous transformation of the same object.
+- Added `Audio.pause({ name, fade?, ease? })` to pause a sound while preserving its playback position; `Audio.play()` resumes it, while `Audio.stop()` resets playing or paused sounds to the beginning.
+- Added the exported `AudioEvent` with `Audio_Start`, `Audio_Complete`, and `Audio_Stop`, each carrying `soundName`; completion indicates a natural playback end, and stopping emits its event immediately or after fade-out finishes.
+- Added the exported `SoundParamsPos` and optional per-sound distance attenuation and directional cone overrides in `SoundParams`; omitted settings inherit the shared audio defaults.
+- Added `Audio.setSoundParams()` to update a loaded sound's volume and positional overrides; volume changes during a fade are stored for subsequent playback without interrupting the fade.
+
+### Renamed
+
+- `cfg.audio.delayPlaySound` → `cfg.audio.delayLoadSound`
+- `SoundParams.object` → `SoundParams.obj`
+- `Audio.setListener({ object })` → `Audio.setListener({ obj })`
+
+### Changed
+
+- Added `Anim_Cancel` to `AnimEvent` for transformations replaced by `Scene.animTransformTo()`.
+- Merged `AudioLoadedEvent` into `AudioEvent`, which now also includes `Audio_Loaded`; removed the separate `AudioLoadedEvent` interface.
+- Extended `SoundParams.obj` to accept a scene object name or an `Obj3D` instance; an empty string still selects global audio. Positional settings are rejected for global sounds during loading and ignored when updating them.
+- Removed `fade` from `SoundParams` and `Audio.load()`; `Audio.loadAndPlay()`, `Audio.play()`, and `Audio.stop()` now accept per-call `fade` and GSAP `ease` options. Fades default to `0` (no fade), with linear easing (`'none'`), instead of a stored two-second fade.
+- Changed `Audio.get()` to return `SoundParamsPos` and `Audio.set()` to accept `Partial<SoundParamsPos>`; loading delay is no longer exposed through these methods, and shared default updates preserve per-sound overrides.
+
+### Fixed
+
+- Fixed `Audio.play()` and `Audio.resume()` to resume interrupted audio contexts in addition to suspended contexts.
+
+## 0.31.0
+
+### Added
+
+- Added the optional `recursive` parameter to `Engine.setMaterialProps()` and `Mesh3D.setMaterialProps()` to include all descendant meshes.
+- Added `Coll3D` and `Coll3DParams` for persistent mesh-based raycast colliders with `hidden`, `pickable`, and `occluder` roles and an optional `target` that maps raycast events to another `Mesh3D`.
+- Added `Obj3DParams` and the persistent `Obj3D.hidden` state, which hides the rendered object without disabling raycasting and is included in combined visibility events.
+- Added optional `{ class, params }` entries through `SceneEntry` and `WebEntry`; `WebParams` values are assigned to matching custom-element instances during app initialization.
+- Added `CompsInsts` to map Scene Component and Web Component definitions to their runtime instances.
+- Added `EnvLoadedEvent` with `Env_Loaded` after the initial environment is applied and all progressive background loading attempts complete; failed background maps may be skipped, and canceled or superseded loads do not emit the event.
+- Added `cfg.render.adaptiveGfx`, `cfg.render.ecoMode`, and `cfg.render.fpsMin` for adaptive graphics quality and Eco mode configuration.
+- Added the exported `AaMode`, `WebGlAaMode`, `WebGpuAaMode`, `WebGlSslMode`, `WebGpuSslMode`, `DebugLog`, and `MsaaMode` configuration types.
+- Added WebGPU SSGI with AO and GI output, adaptive warm-up, configuration, and Inspector controls.
+
+### Renamed
+
+- `Engine.setMaterialProperties()` → `Engine.setMaterialProps()` and `Mesh3D.setMaterialProperties()` → `Mesh3D.setMaterialProps()`
+
+- `Classes` → `Comps`
+- `Comp` → `Web`
+- `CompEvent` → `WebEvent`
+- `CompOverlapEvent` → `WebOverlapEvent`
+- `CompVisibleEvent` → `WebVisibleEvent`
+- `Comp_Overlap_Changed` → `Web_Overlap_Changed`
+- `Comp_Visible_Changed` → `Web_Visible_Changed`
+- `CompOverlapEvent.comp` → `WebOverlapEvent.web`
+- `CompVisibleEvent.comp` → `WebVisibleEvent.web`
+- `CompClass` → `WebClass`
+- `Obj3DClass` → `SceneClass`
+- `CompInsts` → `WebInsts`
+- `Obj3DInsts` → `SceneInsts`
+- `Comp.comps` → `Web.webs`
+
+### Changed
+
+- Replaced the `objs3D` and `comps` registry groups with `comps.scene` and `comps.web`; initialized instances are now exposed through `app.comps.scene` and `app.comps.web`.
+- Changed `Raycast.setColliders()` and `Raycast.clearColliders()` to accept arrays of registered `Coll3D` instances and use or reset their persistent collider roles; removed the exported `Collider` interface.
+- Replaced the individual post-processing enable settings with typed `cfg.render.profile.webgl` and `cfg.render.profile.webgpu` settings for MSAA, AA, SSL, and SSR.
+- Renamed `cfg.post.ssao` to `cfg.post.ssl` and simplified the exported post-processing config type names to `SslCfg`, `SsaoCfg`, `GtaoCfg`, `SsgiCfg`, `WebGlSsrCfg`, and `WebGpuSsrCfg`.
+- Renamed `cfg.post.webgpu.ssao` to `cfg.post.webgpu.gtao` and removed the obsolete `distanceExponent` and `distanceFallOff` settings.
+- Replaced `cfg.render.params.antialias` with renderer-specific `profile.msaa` settings, supporting `'none'`, `'render'`, and `'post'`.
+- Replaced `cfg.render.fpsLimiter` and `cfg.render.fpsMax` with `cfg.render.adaptiveGfx`, `cfg.render.ecoMode`, and `cfg.render.fpsMin`.
 - Changed the default value of `cfg.render.deltaTimesMax` from `10` to `20`.
 - Updated the peer dependencies to Three.js r186 (`~0.186.0`) and XState 5.33 (`~5.33.2`).
-- Removed the `detect-gpu` runtime dependency.
-- `Model_Loading` and numbered progressive loading events now fire only when the rounded percentage changes within each model load.
-
-## 0.30.0
-
-### Changed
-
-- Replaced `Mesh3D.setTexture()` and `TextureSlot` with `requestImageTexture()` and `getImageTexture()` to separate requesting unused GLTF images from accessing their initialized Three.js textures and assigning them directly to material slots.
-- Textures created from unused GLTF images now remain stable across progressive model levels while their image and mipmap data is updated.
-
-### Fixed
-
-- Fixed the `Obj3D.onStart()` lifecycle so it is called before GLTF model loading begins, as documented.
-
-## 0.29.1
-
-### Fixed
-
-- Fixed progressive model loading so textures belonging to materials not currently assigned to a mesh are updated through all model quality levels.
-
-## 0.29.0
-
-### Added
-
-- Added protected `Mesh3D.setTexture()` to assign unused GLTF images by name to the `ColorMap`, `LightMap`, or `AlphaMap` material slot, with optional UV channel and light map intensity settings; registered textures are updated across progressive model levels.
-- Added the exported `TextureSlot` union for the supported material slots.
-
-## 0.28.0
-
-### Added
-
-- Added `Mesh3D.animMaterialColor()`, `Mesh3D.animMaterialNumeric()`, and `Mesh3D.setMaterialProperties()` as object-bound counterparts to the existing `Engine` material methods.
-- Added the optional `needsUpdate` parameter to `Engine.animMaterialNumeric()`, `Engine.setMaterialProperties()`, `Mesh3D.animMaterialNumeric()`, and `Mesh3D.setMaterialProperties()` to request material recompilation.
-- Added degree-based horizontal orbit constraints through `orbitCtrls.minAzimuthAngle` and `orbitCtrls.maxAzimuthAngle`.
-- Added `ModelLoadedEvent` with `Model_Loaded` for a single model and numbered `Model1_Loaded`, `Model2_Loaded`, etc. events for progressive models.
-- Added the `Model_Ready` event after the final progressive model variant has been applied and rendered.
-- Added the exported `Collider` configuration and `Raycast.setColliders()` and `Raycast.clearColliders()` to configure named scene objects or `Obj3D` instances as occluders, pickables, or hidden colliders.
-
-### Changed
-
-- Replaced `Raycast.setOccluders()`, `Raycast.resetOccluders()`, `Raycast.trackPickables()`, and `Raycast.untrackPickables()` with the unified collider API.
-- Renamed `Raycast.enable()` and `Raycast.disable()` to `Raycast.enablePickables()` and `Raycast.disablePickables()`.
-- Renamed `raycast.occlInterval` to `raycast.occludeeInterval` and `raycast.occlMoveFactor` to `raycast.occlusionMoveFactor`.
-- Changed progressive `ModelLoadingEvent` and `SceneRenderedEvent` types to numbered `Model1_Loading`, `Scene1_Rendered`, etc. events; unnumbered events remain available for a single model.
-- Removed the `level` property from `ModelLoadingEvent`; the progressive model level is now identified by the event type.
-- Removed the obsolete `fct` property from `ClipEvent`.
-- Changed pointer raycasts so that registered occluders block pickables behind them.
-
-### Fixed
-
-- Corrected `CanvasPointerEvent` to expose `Canvas_Click`, `Canvas_Pointer_Enter`, and `Canvas_Pointer_Leave`.
-- Added the already emitted `FpvCtrls_Disposed` event to `FpvCtrlsEvent`.
-- Delayed the postprocessing noise check until `Model_Ready` so that postprocessing is not disabled before the final progressive model variant is rendered.
-
-## 0.27.0
-
-### Added
-
-- Added progressive model loading through ordered model levels in `ModelCfg.file`.
-
-### Changed
-
-- Changed `ModelCfg.file` from `string | null` to `string[]`; use an empty array when no model should be loaded.
-- Added the one-based `level` parameter to `ModelLoadingEvent` to identify the model level currently loading.
-- Changed state names to `snake_case` and event names to `Pascal_Snake_Case`.
-- Updated debug console output to use `State:` and `Event:` labels and the new naming conventions.
-
-## 0.26.0
-
-### Added
-
-- Added TRAA as a WebGPU anti-aliasing mode through `cfg.post.aa.mode = 'traa'`.
-- Added the `raycast.occlInterval` configuration to distribute pending marker occlusion checks evenly over a configurable time interval.
-- Added the `raycast.occlMoveFactor` configuration to trigger new occlusion checks only after the object or camera exceeds a distance-relative movement threshold.
-- Added `Raycast.setOccluders()` and `Raycast.resetOccluders()` to optionally restrict occlusion checks to selected scene objects.
-- Added `Comp.trackOverlap()` and `Comp.untrackOverlap()` to manage component overlaps in screen space through the internal `CompCtrls`.
-- Added `cfg.light.rectArea` to lazily load and initialize renderer-specific LTC data for `RectAreaLight` support.
-
-### Changed
-
-- Moved the shared SSR settings `maxDistance`, `thickness`, and `resolutionScale` from `cfg.post.webgl.ssr` and `cfg.post.webgpu.ssr` to `cfg.post.ssr`.
-- Renamed the public `Raycast.trackSelectables()` and `Raycast.untrackSelectable()` methods to `Raycast.trackPickables()` and `Raycast.untrackPickables()`.
-
-### Fixed
-
-- Fixed the Inspector showing TRAA or an empty anti-aliasing mode for WebGL by falling back to FXAA when `cfg.post.aa.mode` is set to `'traa'`.
-
-## 0.25.0
-
-### Added
-
-- Added `CanvasPointerLeave` handling to the `Obj3D_Pointer_Leave` event.
-- Added `ActionCtrls` for centralized animation action lifecycle, layer grouping, and interruptible fades.
-- Extended `ClipEvent` with `Clip_Cancel`, `Clip_Fade_Start`, `Clip_Fade_Complete`, `Clip_Speed_Start`, and `Clip_Speed_Complete` events.
-
-### Fixed
-
-- Fixed `Obj3D_Pointer_Leave` being emitted during pointer movement with a pressed mouse button and ensured touch pointers emit it after `Obj3D_Pointer_Up` when contact ends.
-
-## 0.24.1
-
-### Added
-
-- Added the `ProgressBar_Hidden` event.
-
-### Changed
-
-- Renamed the `aaCfg` interface to `AaCfg`.
-
-### Fixed
-
-- Fixed an incorrect `objTarget.position` when enabling orbit or FPV controls after setting it in `Cam3D.onReady()`.
-
-## 0.24.0
-
-### Added
-
-- Added animation modes `BlendMode`, `FinishMode`, `LoopMode`, `StopMode`
-- Added `fadeDuration` to `playClip()` and `playClipCam()`.
-- Added `Audio.load()` to load audio without starting playback.
-- Added the `AudioLoadedEvent` (`Audio_Loaded`) event for handling completed audio loading.
-
-### Changed
-
-- Replaced `pauseActions` with `stopMode` and `infinite` with `loop` in animation clip playback.
-- Renamed `Raycast.trackSelectable()` to `Raycast.trackSelectables()`.
-- Changed the `LightCfg` shadow defaults to match the corresponding Three.js defaults, while keeping `castShadow` enabled by default.
-
-### Fixed
-
-- Fixed visual stuttering when transitioning from orbit rotation to panning with damping enabled by keeping `OrbitCtrls` in `lookMode = 'target'` for all OrbitControls interactions.
-
-## 0.23.1
-
-### FIXED
-
-- Convert absolute path to the Draco folder to a relative path.
-
-## 0.23.0
-
-### Added
-
-- Added progressive environment map loading.
-- Added `Cam3D` support to `Audio.setListener()` targets.
-- Added support for using the base `Cam3D` class in the `classes.objs3D` registry.
-
-### Fixed
-
-- Fixed WebGL environment maps so PMREM-generated textures are not used for `THREE.Scene.background`.
-
-## 0.22.1
-
-### Added
-
-- Added `cfg.render.params` for renderer-specific runtime parameters.
-- Added `render.api` output to the infobox.
-- Added `.blend` source files to the public example apps.
-
-### Changed
-
-- Renamed `cfg.webgl` and `cfg.webgpu` parameter groups to `params`.
-
-## 0.22.0
-
-### Changed
-
-- Updated the framework to Three.js r185.
-- Changed the default renderer selection to `render.api = 'auto'`.
-- Added `envCtrls.dataType` to configure environment texture data handling.
-- Replaced `SsrWebGpuCfg.opacity` with `SsrWebGpuCfg.intensity`.
-
-### Fixed
-
-- Clarified the WebGL/WebGPU renderer switch behavior.
-- Enabled WebGPU renderer loading even when post-processing is disabled.
-
-## 0.21.9
-
-### Changed
-
-- Removed the `CfgCtrl` class and the related `app.cfgCtrl` access point. Runtime parameters are now updated through the responsible feature APIs, such as `app.audio.set(...)`.
-
-## 0.21.8
-
-### Changed
-
-- Added `cfg.audio.enable` to the configuration.
+- Removed the `detect-gpu` runtime dependency.
+- `Model_Loading` and numbered progressive loading events now fire only when the rounded percentage changes within each model load.
+
+## 0.30.0
+
+### Changed
+
+- Replaced `Mesh3D.setTexture()` and `TextureSlot` with `requestImageTexture()` and `getImageTexture()` to separate requesting unused GLTF images from accessing their initialized Three.js textures and assigning them directly to material slots.
+- Textures created from unused GLTF images now remain stable across progressive model levels while their image and mipmap data is updated.
+
+### Fixed
+
+- Fixed the `Obj3D.onStart()` lifecycle so it is called before GLTF model loading begins, as documented.
+
+## 0.29.1
+
+### Fixed
+
+- Fixed progressive model loading so textures belonging to materials not currently assigned to a mesh are updated through all model quality levels.
+
+## 0.29.0
+
+### Added
+
+- Added protected `Mesh3D.setTexture()` to assign unused GLTF images by name to the `ColorMap`, `LightMap`, or `AlphaMap` material slot, with optional UV channel and light map intensity settings; registered textures are updated across progressive model levels.
+- Added the exported `TextureSlot` union for the supported material slots.
+
+## 0.28.0
+
+### Added
+
+- Added `Mesh3D.animMaterialColor()`, `Mesh3D.animMaterialNumeric()`, and `Mesh3D.setMaterialProperties()` as object-bound counterparts to the existing `Engine` material methods.
+- Added the optional `needsUpdate` parameter to `Engine.animMaterialNumeric()`, `Engine.setMaterialProperties()`, `Mesh3D.animMaterialNumeric()`, and `Mesh3D.setMaterialProperties()` to request material recompilation.
+- Added degree-based horizontal orbit constraints through `orbitCtrls.minAzimuthAngle` and `orbitCtrls.maxAzimuthAngle`.
+- Added `ModelLoadedEvent` with `Model_Loaded` for a single model and numbered `Model1_Loaded`, `Model2_Loaded`, etc. events for progressive models.
+- Added the `Model_Ready` event after the final progressive model variant has been applied and rendered.
+- Added the exported `Collider` configuration and `Raycast.setColliders()` and `Raycast.clearColliders()` to configure named scene objects or `Obj3D` instances as occluders, pickables, or hidden colliders.
+
+### Changed
+
+- Replaced `Raycast.setOccluders()`, `Raycast.resetOccluders()`, `Raycast.trackPickables()`, and `Raycast.untrackPickables()` with the unified collider API.
+- Renamed `Raycast.enable()` and `Raycast.disable()` to `Raycast.enablePickables()` and `Raycast.disablePickables()`.
+- Renamed `raycast.occlInterval` to `raycast.occludeeInterval` and `raycast.occlMoveFactor` to `raycast.occlusionMoveFactor`.
+- Changed progressive `ModelLoadingEvent` and `SceneRenderedEvent` types to numbered `Model1_Loading`, `Scene1_Rendered`, etc. events; unnumbered events remain available for a single model.
+- Removed the `level` property from `ModelLoadingEvent`; the progressive model level is now identified by the event type.
+- Removed the obsolete `fct` property from `ClipEvent`.
+- Changed pointer raycasts so that registered occluders block pickables behind them.
+
+### Fixed
+
+- Corrected `CanvasPointerEvent` to expose `Canvas_Click`, `Canvas_Pointer_Enter`, and `Canvas_Pointer_Leave`.
+- Added the already emitted `FpvCtrls_Disposed` event to `FpvCtrlsEvent`.
+- Delayed the postprocessing noise check until `Model_Ready` so that postprocessing is not disabled before the final progressive model variant is rendered.
+
+## 0.27.0
+
+### Added
+
+- Added progressive model loading through ordered model levels in `ModelCfg.file`.
+
+### Changed
+
+- Changed `ModelCfg.file` from `string | null` to `string[]`; use an empty array when no model should be loaded.
+- Added the one-based `level` parameter to `ModelLoadingEvent` to identify the model level currently loading.
+- Changed state names to `snake_case` and event names to `Pascal_Snake_Case`.
+- Updated debug console output to use `State:` and `Event:` labels and the new naming conventions.
+
+## 0.26.0
+
+### Added
+
+- Added TRAA as a WebGPU anti-aliasing mode through `cfg.post.aa.mode = 'traa'`.
+- Added the `raycast.occlInterval` configuration to distribute pending marker occlusion checks evenly over a configurable time interval.
+- Added the `raycast.occlMoveFactor` configuration to trigger new occlusion checks only after the object or camera exceeds a distance-relative movement threshold.
+- Added `Raycast.setOccluders()` and `Raycast.resetOccluders()` to optionally restrict occlusion checks to selected scene objects.
+- Added `Comp.trackOverlap()` and `Comp.untrackOverlap()` to manage component overlaps in screen space through the internal `CompCtrls`.
+- Added `cfg.light.rectArea` to lazily load and initialize renderer-specific LTC data for `RectAreaLight` support.
+
+### Changed
+
+- Moved the shared SSR settings `maxDistance`, `thickness`, and `resolutionScale` from `cfg.post.webgl.ssr` and `cfg.post.webgpu.ssr` to `cfg.post.ssr`.
+- Renamed the public `Raycast.trackSelectables()` and `Raycast.untrackSelectable()` methods to `Raycast.trackPickables()` and `Raycast.untrackPickables()`.
+
+### Fixed
+
+- Fixed the Inspector showing TRAA or an empty anti-aliasing mode for WebGL by falling back to FXAA when `cfg.post.aa.mode` is set to `'traa'`.
+
+## 0.25.0
+
+### Added
+
+- Added `CanvasPointerLeave` handling to the `Obj3D_Pointer_Leave` event.
+- Extended `ClipEvent` with `Clip_Cancel`, `Clip_Fade_Start`, `Clip_Fade_Complete`, `Clip_Speed_Start`, and `Clip_Speed_Complete` events.
+
+### Fixed
+
+- Fixed `Obj3D_Pointer_Leave` being emitted during pointer movement with a pressed mouse button and ensured touch pointers emit it after `Obj3D_Pointer_Up` when contact ends.
+
+## 0.24.1
+
+### Added
+
+- Added the `ProgressBar_Hidden` event.
+
+### Changed
+
+- Renamed the `aaCfg` interface to `AaCfg`.
+
+### Fixed
+
+- Fixed an incorrect `objTarget.position` when enabling orbit or FPV controls after setting it in `Cam3D.onReady()`.
+
+## 0.24.0
+
+### Added
+
+- Added animation modes `BlendMode`, `FinishMode`, `LoopMode`, `StopMode`
+- Added `fadeDuration` to `playClip()` and `playClipCam()`.
+- Added `Audio.load()` to load audio without starting playback.
+- Added the `AudioLoadedEvent` (`Audio_Loaded`) event for handling completed audio loading.
+
+### Changed
+
+- Replaced `pauseActions` with `stopMode` and `infinite` with `loop` in animation clip playback.
+- Renamed `Raycast.trackSelectable()` to `Raycast.trackSelectables()`.
+- Changed the `LightCfg` shadow defaults to match the corresponding Three.js defaults, while keeping `castShadow` enabled by default.
+
+### Fixed
+
+- Fixed visual stuttering when transitioning from orbit rotation to panning with damping enabled by keeping `OrbitCtrls` in `lookMode = 'target'` for all OrbitControls interactions.
+
+## 0.23.1
+
+### FIXED
+
+- Convert absolute path to the Draco folder to a relative path.
+
+## 0.23.0
+
+### Added
+
+- Added progressive environment map loading.
+- Added `Cam3D` support to `Audio.setListener()` targets.
+- Added support for using the base `Cam3D` class in the `classes.objs3D` registry.
+
+### Fixed
+
+- Fixed WebGL environment maps so PMREM-generated textures are not used for `THREE.Scene.background`.
+
+## 0.22.1
+
+### Added
+
+- Added `cfg.render.params` for renderer-specific runtime parameters.
+- Added `render.api` output to the infobox.
+- Added `.blend` source files to the public example apps.
+
+### Changed
+
+- Renamed `cfg.webgl` and `cfg.webgpu` parameter groups to `params`.
+
+## 0.22.0
+
+### Changed
+
+- Updated the framework to Three.js r185.
+- Changed the default renderer selection to `render.api = 'auto'`.
+- Added `envCtrls.dataType` to configure environment texture data handling.
+- Replaced `SsrWebGpuCfg.opacity` with `SsrWebGpuCfg.intensity`.
+
+### Fixed
+
+- Clarified the WebGL/WebGPU renderer switch behavior.
+- Enabled WebGPU renderer loading even when post-processing is disabled.
+
+## 0.21.9
+
+### Changed
+
+- Removed the `CfgCtrl` class and the related `app.cfgCtrl` access point. Runtime parameters are now updated through the responsible feature APIs, such as `app.audio.set(...)`.
+
+## 0.21.8
+
+### Changed
+
+- Added `cfg.audio.enable` to the configuration.