hilo3d 2.0.0-alpha.3 → 2.0.0-alpha.4

package/CHANGELOG.md

@@ -1,3 +1,313 @@
+# Unreleased
+
+### Breaking changes
+
+- Integrate typed particle parameters into emission and spawn initialization across CPU, stateless,
+  and stateful WebGPU command generation; runtime value changes no longer require recompilation.
+  Apply `ParticleBudgetManager` decisions directly to live capacity, spawn rate, sorting, soft
+  particles, collision, and ribbon work. Connect the bounded stateless WebGPU generator to Render
+  Graph compute, indirect storage raster, and device-loss regeneration, with explicit CPU fallback
+  for unsupported definitions and manual emission. Explicit stateful GPU emitters now reject
+  `replace-oldest`; unsupported module/backend pairs fail compilation instead of doing nothing.
+- Replace the mutable `Material` monolith with immutable `MaterialDefinition` plus
+  `MaterialInstance`. Remove legacy topology mutation, WebGL-style blend/side fields, material-owned
+  render order and shadow participation, material display transforms, shared UV matrices, shadow
+  proxy materials, `onBeforeCompile`, and `shaderCacheId`. Move object ordering and shadow flags to
+  `Mesh`; require construction-time topology, explicit coverage/compositing, typed
+  `MaterialAttributeSemantic`/`MaterialUniformSemantic`/`MaterialTextureSemantic` bindings, and
+  explicit pass pipeline state. This is a direct migration with no compatibility adapter.
+- Split per-texture-slot std140 metadata out of `MaterialBlock` into the fixed
+  `MaterialTextureBlock`. The material scalar block is now 448 bytes and includes
+  `u_temporalReactiveFactor`; the texture-slot block is 1,920 bytes, WebGPU material textures begin
+  at binding 2, and custom uniform block registrations begin after ten built-in WebGL2 binding
+  points.
+- Advance the shared GPU PBR material record to `builtin-pbr-storage-v3`. The byte length is
+  unchanged, but the third surface vector's formerly reserved W component now stores authored
+  temporal reactivity for the fused GPU Scene depth/motion pass.
+- Expand the fixed Camera/Model/Skinning/Morph/Instance std140 ABI with current/previous transforms,
+  stable and jittered camera projections, render origins, and per-domain history/depth flags. Custom
+  shaders that redeclare built-in blocks must use the updated field order and capacities.
+- Make forward feature color encoding explicit. `replaceColor()` now requires `linear` or `srgb`,
+  and the default Forward pipeline always routes surface presentation through the Render Graph so
+  the final output transfer is owned by the output stage rather than individual materials.
+- Replace the Forward-specific color-encoding type with the shared `RenderColorEncoding`. Manual
+  RenderTarget presentation now accepts an explicit `colorEncoding`; linear inputs receive the final
+  sRGB transfer, while display-transformed `srgb` inputs are preserved without a second conversion.
+
+### Changes
+
+- Update the standalone `hilo3d-game` skill for immutable material topology, Mesh-owned ordering and
+  shadow participation, and the completed portable/WebGPU particle authoring workflow.
+- Normalize managed particle textures through the shared top-left UV boundary for CPU and WebGPU
+  sprite, mesh, motion-vector, ribbon, and trail shaders. Fix WebGPU 2D Sprite orientation when
+  `Texture.flipY` is false, and extend the asymmetric row-direction fixture across WebGL 2/WebGPU
+  render targets, ordinary materials, 2D Sprites, particles, and cube textures.
+
+- Add the versioned public `ParticleSystemDefinition`/`ParticleSystem` API through P0-P3. Compile
+  immutable fixed modules into liveness-based SoA layouts with deterministic counter RNG and shared
+  curve/gradient LUTs; provide portable CPU fixed-step simulation with one interleaved instanced
+  sprite draw on WebGL 2/WebGPU; and add renderer-owned stateful WebGPU simulation, alive/dead
+  compaction, spawn commands, indirect arguments, Bitonic/distance-bucket sorting, recovery-aware
+  commit/rollback, and constrained storage-aware sprite raster through the default Forward Render
+  Graph. Keep the existing specialized compute-particle showcase unchanged until the remaining
+  particle phases are complete. Add stateless eligibility metadata and asset-level diagnostics,
+  absolute-time CPU reconstruction, a no-state Naga-validated WebGPU renderer-data generator,
+  deterministic live budget/quality application, and reusable short-effect system pooling.
+- Extend the particle runtime through P4 with analytic collision and triggers, WebGPU scene-depth
+  collision, sampled-depth soft sprites with fragment depth comparison, compact bounded CPU events,
+  typed `ParticleEventChannel`, asynchronous aggregate reads, and GPU-resident event
+  capture/sub-emitter routing without count or state readback. Allow constrained storage graphics
+  shaders to specialize ordinary GLSL numeric depth samplers into WGSL depth textures.
+- Complete particle P5 with portable mesh instancing and per-mesh buckets, ribbon/trail topology and
+  dense segment streams, WebGPU mesh scatter plus per-asset indirect draws, per-view GPU ribbon
+  topology sorting/segment compaction/indirect raster, ambient plus bounded directional Lambert
+  lighting, soft ribbons, explicit Bloom/TAA composition semantics, and opt-in motion vectors for
+  supported portable opaque/masked mesh output. Add fail-closed advanced quality gates instead of
+  silently degrading unsupported tiers. Allow the built-in opaque GPU particle boundary to request
+  opaque/transparent Forward splitting only on frames that actually draw eligible particles.
+- Add the first particle P6 authoring slice with normalized versioned JSON serialization, strict
+  parsing and compiler validation, sequential application-owned upgrades, document-local shared
+  parameter identities, and stable application-resolved Texture/Geometry references. Reject future
+  versions, missing or skipped upgrades, unknown schema fields/tags, and unresolved or wrong-kind
+  resources before runtime construction.
+- Add versioned reusable in-memory particle simulation checkpoints. Capture and restore CPU SoA,
+  fixed-step scheduler, pending manual emission, bounded events, playback/budget/culling state, and
+  stateless GPU absolute time without production-loop readback. Bind checkpoints to definition,
+  compiled plan, seed, parameter identity/revision, and event capacity; reject stateful GPU capture
+  until an explicit asynchronous device-state transfer contract exists.
+- Add bounded deterministic particle baking APIs. Export stable-ID/generation-sorted frame-major
+  mesh instance caches with motion/orientation inputs and bounds, and pack application-rendered,
+  tightly packed render-target readbacks into native-format flipbook atlases. Restore the caller's
+  simulation checkpoint after success or failure, bound frame/particle/atlas work, and reject
+  stateful GPU baking rather than introducing synchronous device-state readback.
+- Complete particle P6 external authoring with a published fixed-module graph JSON Schema,
+  deterministic definition-to-graph conversion, strict ownership/compiler validation,
+  node-addressable diagnostics, normalized inspector IR, and a versioned preview controller for
+  compile/play/pause/restart/seek/step/inspect/dispose without GPU particle readback.
+- Allow a Forward feature runtime to request sampled single-sample scene depth per frame before
+  attachment allocation, so scene-dependent effects do not force unrelated RenderTarget frames
+  through an intermediate depth path.
+- Add an integrated WebGPU physical atmosphere and weather chain to Clustered Forward+: cached
+  Rayleigh/Mie/ozone transmittance and multiple-scattering LUTs, a per-frame sky-view LUT, aerial
+  perspective, physical sun disc, procedural weather map, quality-tier Perlin/Worley volumetric
+  cloud ray marching, blue-noise sampling, representative-depth temporal reprojection, cloud shadows
+  for registered PBR directional light and froxel scattering, and storm lightning/sun-shaft
+  lighting. Add GPU histogram percentile exposure with asymmetric eye adaptation, on-demand
+  diagnostics, and submission-aware `rgba16float` exposure history; add configurable filmic Color
+  Uber and Clustered display transforms. Add the interactive Stormfront Observatory WebGPU example
+  with solar time, cloud, wind, storm, quality, debug, and camera controls.
+- Add production dynamic resolution and authored reactive masks to `TemporalAA` and the integrated
+  Clustered Forward+ temporal path. Dynamic resolution is explicitly gated by WebGPU
+  `timestamp-query`, consumes asynchronous Render Graph GPU pass durations without stalling the
+  frame, and applies EWMA smoothing, hysteresis, quantized steps, warmup, settling, min/max bounds,
+  duplicate-sample rejection, and fail-closed handling for unavailable, failed, or saturated
+  timings. Resolution changes synchronously resize scene color/depth/motion/reactive, Hi-Z,
+  clusters, GTAO/SSGI/SSR, volumetric, atmosphere and cloud resources while invalidating
+  size-dependent history; color/depth history, transparent/UI composition and presentation remain
+  output resolution. Add `MaterialInstance.temporalReactiveFactor`, write it through a second
+  `r8unorm` motion MRT in ordinary Forward and the fused GPU Scene prepass, conservatively dilate it
+  3×3, and combine it with luminance reactivity during TAA/TAAU rejection. Expose single-runtime
+  Forward diagnostics and Clustered scale/GPU-time diagnostics, with tests for controller stability,
+  ABI validation, material revisions, shared GPU packing, fallback and resource requirements.
+- Complete the native GPU Scene/Clustered Forward+ coverage slice for alpha-masked PBR, shared
+  shadows, and area lights. Alpha coverage now uses base-color/opacity slot transforms, channels,
+  encodings, factors, and cutoff consistently in indirect depth, motion, material-attribute, and
+  color passes. Directional, spot, and point lights keep GPU Scene objects on the clustered path
+  while sampling the renderer's exact shared shadow-atlas graph texture with standard/reversed-depth
+  3×3 PCF, cascades, slope bias, shadow strength, and per-mesh `receiveShadows`. Area lights use the
+  ordinary Forward LTC LUTs as global storage-light records with explicit-LOD WebGPU sampling rather
+  than point-light approximation or whole-camera fallback. `RenderPipelineContext.recordShadows()`
+  now returns frame-scoped atlas, light order, bias, cascade, and matrix data for custom pipelines;
+  the atlas remains renderer-owned, recovery-aware, and submission-tracked.
+- Add production screen-space diffuse global illumination to ordinary Forward on WebGPU/WebGL 2 and
+  to the WebGPU Clustered Forward+ profile. The opt-in path reuses GTAO/GPU Scene material
+  attributes and motion/log-depth when available, traces configurable stochastic view-space
+  hemisphere rays against opaque depth, transports bounded linear HDR scene radiance, applies
+  motion/depth/normal history rejection with YCoCg variance clipping, runs one to three
+  depth/normal/luminance-aware a-trous filters, performs bilateral full-resolution upsampling, and
+  composites before transparent, Bloom, and display. Keep per-camera history submission-aware across
+  cuts, resize, discarded frames and recovery; use explicit-LOD sampling so translated WGSL remains
+  valid in non-uniform ray/filter control flow; and keep the disabled path resource- and pass-free.
+  Add the dual-backend Prismatic Vespers procedural chapel with cyan, vermilion, violet, and warm
+  emissive architecture, same-view on/off controls, responsive editorial UI, and WebGL 2/WebGPU
+  render-health and GPU-validation coverage.
+- Add production WebGPU high-end froxel volumetric lighting to
+  `ClusteredForwardPlusPipelineFactory`. The opt-in path expands the bounded local-light allocator
+  from surface depth ranges to the complete camera cluster volume, tiles logarithmic Z slices into a
+  dimension-validated `rgba16float` atlas, injects directional/point/spot radiance plus exponential
+  height and sphere/box local fog, cumulatively integrates each froxel column once, reconstructs
+  depth-bounded radiance/transmittance in constant texture-fetch cost, and performs previous-view
+  reprojection, depth/reactive temporal rejection, neighborhood clamping, and linear HDR
+  transmittance/scattering composition before TAA/TAAU, transparent fallback, Bloom, and display.
+  Add bounded screen-space light visibility, low/medium/high/ultra budgets, radiance/transmittance
+  debug views, submission-aware diagnostics, camera-cut/resize/failure/device-recovery history, and
+  fail-closed storage/format/texture-dimension requirements. Keep explicit shadow-atlas and
+  transparent-volume participation as documented future ABIs rather than silently approximating
+  either contract. Add Neon Reliquary around the repository-bundled Khronos Sponza with a cinematic
+  40px surface grid, 0.375-scale froxel XY/20-slice volume, 0.72-scale TAAU, animated chromatic
+  spotlights, seven local fog fields, camera/debug controls, and a physical-WebGPU
+  stability/on-off/GPU-validation gate.
+- Add production ground-truth ambient occlusion to ordinary Forward on WebGPU/WebGL 2 and to the
+  WebGPU Clustered Forward+ profile. The opt-in path records shared depth/material-attribute/motion
+  producers, configurable rotated horizon search, bent-normal visibility, submission-aware temporal
+  rejection, two edge-aware filters, and bounded depth/normal upsampling before applying the result
+  only to PBR ambient/IBL. Keep direct lights and emission unoccluded, reset or roll back per-camera
+  history across cuts, resize, discarded frames and recovery, and keep the disabled path resource-
+  and pass-free. Add The Silent Dragon museum study around the repository-bundled 1.2 MB Stanford
+  Dragon, with same-page GTAO A/B switching, responsive art direction, and real WebGPU/WebGL 2
+  non-black and on/off pixel coverage. Keep the deployed glTF beside its external binary payload,
+  and make the site link gate validate nested glTF buffer, image, and extension URIs before publish.
+- Add production WebGPU high-end screen-space reflections to `ClusteredForwardPlusPipelineFactory`.
+  The opt-in path adds a strict built-in `material-attributes` `rgba16float` ABI, GPU Scene MRT and
+  ordinary Forward fallback coverage, RG32F min/max Hi-Z, hierarchical coarse-to-fine tracing,
+  roughness radiance cones, edge/distance/roughness confidence, motion/log-depth temporal rejection
+  and confidence-aware depth/normal à-trous filtering before HDR composition and TAA/TAAU. Keep the
+  disabled path allocation- and pass-free, fail closed without Hi-Z or TemporalAA, and reset history
+  across camera cuts/identity changes, resize, discarded frames and device recovery. Feed ordinary
+  Forward opaque through a `depth-only` fallback prepass before current Hi-Z construction so layered
+  PBR objects are present in both the radiance source and hierarchical depth trace. Add `rg32float`
+  to the public compute storage-texture formats, add the repository-bundled Khronos Car Concept to
+  the dedicated Afterimage SSR showcase, and cover real WebGPU on/off pixels plus GPU validation.
+  The existing Temporal Observatory remains focused on TAA/TAAU.
+- Add the `TemporalAA` Forward feature with native-resolution TAA and fixed-scale TAAU. Built-in
+  opaque/masked materials now expose a strict single-sample `rgba16float` motion pass containing
+  current-to-previous UV velocity, expected previous logarithmic view depth, and current logarithmic
+  view depth. Camera, model, instance, skin, morph, visibility, and failed-frame history are
+  submission-aware. TAA runs after opaque and before transparent/Bloom with `rgba16float` color
+  history, `r32float` logarithmic-depth history, conservative depth rejection, YCoCg variance
+  clipping, motion/luminance-reactive history weight, resolve-only sharpening,
+  projection-cut/resize/device-loss invalidation, and deterministic jitter rollback. Clustered
+  Forward+ can opt into the same resolve; GPU Scene fuses motion output into its existing depth
+  prepass, double-buffers visibility, and composes ordinary Forward fallback opaque before TAA and
+  fallback transparent afterward. Add the WebGPU Temporal Observatory example and real-pixel
+  convergence/camera-cut/GPU-validation coverage. `TemporalAAOptions.renderScale` accepts 0.5–1;
+  sub-native modes render opaque color, depth, motion, Clustered Forward+ Hi-Z, and cluster sizing
+  at the fixed internal scale, then reconstruct Catmull-Rom current color into output-resolution
+  color/depth history and a full-resolution depth attachment before transparent composition. Dynamic
+  resolution, authored reactive masks, and transparent history remain deferred.
+
+- Add canonical built-in material definitions, stable material IDs and revisions, explicit
+  forward/depth-only/shadow-caster/picking roles, role-aware shader variants, per-slot texture/UV
+  transform/encoding/channel data, and deterministic coverage/transmission/compositing ownership.
+  Shadow rendering now requests the original material's shadow role, glTF constructs layered PBR
+  topology and all texture transforms before instantiation, and display conversion remains solely in
+  post-processing/output.
+- Add the renderer-local shared GPU Material Database. Deduplicate material identities into stable
+  family/layout handles, coalesce revision-driven dirty record uploads, commit texture slot state
+  only after valid submission, retry discarded frames, and retain recovery through the
+  renderer-owned CPU shadow. Migrate Clustered Forward+ from its private per-bucket PBR table so GPU
+  Scene objects keep independent geometry-bucket and shared-material indices.
+- Complete the Forward+/Clustered/Hi-Z/batching remediation audit. Preserve one global direct/batch
+  draw order, pack per-slot PBR texture metadata, use a single compact visible table with aligned
+  per-bucket storage offsets and zero indirect `firstInstance`, make overflow membership
+  deterministic, keep directional lights global, route AreaLight and shadow-enabled lights through
+  exact Forward fallback, restrict previous-frame Hi-Z to stable conservative LOD bounds, compose
+  fallback in linear HDR before separable Bloom/display, elide Bloom resources and passes at zero
+  strength, cache static batch normal matrices, and separate CPU record timing from GPU completion
+  in the 110k-object scale fixture.
+- Add a repository-bundled Khronos Sponza Clustered Forward+ lighting lab with 202 animated local
+  lights, including 10 slow chromatic runners that curve through a wall-height central volume, GPU
+  Scene diagnostics, HDR bloom, a multi-region OrbitControls camera tour, responsive controls, and
+  an offline-friendly asset path with native WebGPU release coverage.
+- Avoid repeated scene traversal, camera refresh, LightManager packing, and built-in semantic-block
+  activation while preparing resource-only compute, GPU-driven, and fullscreen passes. Their shared
+  buffer/texture/resource-use transaction remains submission-aware; scene passes activate semantics
+  only when an actual renderer list or mesh draw needs them. Clustered Forward+ now also batches all
+  fixed-bucket depth draws and all color draws into one native render pass each while retaining
+  independent indirect arguments, pipelines, bindings, and graph-declared dependencies.
+- Make previous-frame Hi-Z occlusion conservative for moving and stationary cameras. Disable it for
+  the first frame after a view-projection or depth change, project bounds from the sphere's nearest
+  depth and all eight corners of its view-space bounding cube, select a mip covering the full
+  projected extent, and cover the full configured viewport with a specialized pyramid of up to
+  thirteen levels. Only transform- and bounds-stable objects consume previous history. The current
+  pyramid is still retained so culling resumes immediately on the next stable frame without temporal
+  disocclusion holes, off-axis under-bounds, or large-geometry false positives. GPU Scene frustum
+  culling now tests the exact view-space side-plane radius instead of underestimating large spheres
+  near a screen edge, and honors each mesh's `frustumTest` opt-out.
+- Keep GPU Scene depth-prepass and color-pass clip-space transforms byte-identical so reversed-depth
+  testing remains stable while the camera moves instead of exposing stippled, checkerboard, or large
+  missing regions from cross-program floating-point rounding.
+- Keep default Forward lighting, clear colors, transparent blending, and intermediate effects in
+  linear space, then apply one exact linear-to-sRGB transfer at the browser surface. Multi-camera
+  load/blend stays in a renderer-owned linear composition target, while already transformed Color
+  Uber output is presented without a second conversion. Single-camera MSAA resolves into the
+  persistent single-sample composition target; multi-camera stacks use one single-sample
+  color/depth/stencil composition contract so later cameras can load prior contents exactly.
+- Keep ShaderMaterial scene output linear and make custom pipeline presentation encoding explicit.
+  ShaderToy now relies on the shared Forward output transfer, while the compute particle field and
+  crystal path tracer declare their display-referred output so their authored grading is not
+  transferred twice.
+- Advance the RHI benchmark manifest to schema 4 and model fixed surface-output draws separately
+  from primary scene and post-process draws; immutable snapshots from earlier schemas remain
+  historical evidence and are not rewritten.
+- Route opaque-composited transmission surfaces through the after-opaque forward queue so their
+  scene-color dependency is satisfied without conflating transmission with alpha blending. Apply
+  texture-slot encoding consistently to 2D, cube, and environment samples, including explicit sRGB
+  decoding for the LDR studio IBL. WebGPU shader lowering now retains the managed material sampler
+  for single-UV shaders instead of bypassing texture transforms, decoding, and channel remapping,
+  restoring WebGL2/WebGPU material parity.
+- Add the `high-end` rendering profile, per-camera standard/reversed depth modes, finite/infinite
+  reversed-Z projection, depth-convention-aware surfaces, render targets, shadows, storage graphics,
+  and GPU picking. Add optional camera-relative GPU transforms while preserving CPU world identity,
+  plus submission-transactional current/previous camera, mesh, instance, skinning, and morph state.
+  `Node.invalidateTransformHistory()` resets discontinuous motion deterministically.
+- Add the WebGPU-only `ClusteredForwardPlusPipelineFactory` high-end opaque-scene slice. Registered
+  ordinary Mesh buckets now use stable dirty GPU Scene records, full-viewport previous-frame Hi-Z
+  occlusion, projected-size LOD compaction, fixed indexed-indirect draws, depth-driven logarithmic
+  3D clusters, a bounded count/prefix/write light allocator, storage GGX PBR, HDR Bloom, ACES
+  display, and on-demand visibility/overflow diagnostics. Add real WebGPU renderer coverage for the
+  compute/dispatch/indirect-draw path. Make Hi-Z conservative for both standard and reversed depth,
+  use the committed previous view/projection/depth convention for temporal occlusion, preserve the
+  depth prepass during color shading, and use inverse-transpose object normal matrices. Registered
+  buckets now migrate at runtime between the GPU path and a shared Forward compatibility path for
+  material/geometry replacement, alpha, transparency, skinning, morphing, unregistered meshes, and
+  object-capacity overflow; the fallback preserves normal opaque/transparent sorting, shadows, and
+  transmission scene-color input without double-drawing GPU-managed meshes. Device limit
+  requirements cover every configured geometry/cluster buffer and dispatch dimension. Add a real
+  WebGPU 100k-static + 10k-dynamic + 256-light scale/recovery acceptance fixture and deterministic
+  cluster-overflow coverage. Share metallic/roughness surface evaluation and the BRDF between
+  ordinary Forward and clustered storage shaders so Forward+ replaces only light-list iteration. Add
+  native GPU Scene base-color, metallic, roughness, combined metallic-roughness, occlusion,
+  emission, and normal maps with UV0/UV1, UV matrices, tangent streams, sampler mutation, runtime
+  texture replacement, and device-recovery coverage; incompatible alpha/layered/deformed inputs
+  continue to use the Forward fallback.
+- Let scriptable pipeline factories create persistent renderer-owned storage buffers, stage dirty
+  writes before graph import, and commit or discard CPU temporal state at the actual submission
+  boundary through `frameSubmitted()` and `frameDiscarded()`. Pipeline-owned buffers retain normal
+  device-loss recipes and submission-aware destruction. Frame completion still runs when a
+  post-submission pipeline callback throws, so presentation, events, diagnostics, and temporal
+  cleanup are not skipped after GPU work has already been submitted.
+- Let scriptable render graphs import engine-managed `Texture` objects as sampled persistent
+  resources while preserving renderer upload/recovery/submission ownership. Expose the public
+  per-stage sampler limit alongside the existing sampled-texture limit.
+
+- Add modern WebGPU capability discovery for `subgroups`, adapter subgroup-size limits,
+  `shader-f16`, and `timestamp-query`; expose renderer feature queries for explicit f32/workgroup
+  fallback selection. Direct WGSL f16 now preserves the exact native artifact while completing Naga
+  validation through an equivalent f32 specialization. Compute buffer `minBindingSize` is derived
+  from WGSL store types, including the required one-element runtime-array minimum.
+- Add submission-aware timestamp QuerySets, pass timestamp writes, explicit resolves, and validated
+  debug groups/markers to the portable RHI. Opt-in renderer diagnostics now publish Render Graph
+  record/compile/prepare/execute CPU timing, per-pass asynchronous GPU timing, and compiled resource
+  lifetime intervals through a non-blocking three-slot readback ring; the default diagnostics-off
+  path creates no query resources.
+- Add explicit Render Graph texture views for mip, array-layer, dimension, compatible-format, and
+  depth/stencil-aspect access across sampled, storage, attachment, and copy paths. Add
+  renderer-owned double/triple-buffer history textures whose recipes survive device recovery, whose
+  contents invalidate on descriptor or device-generation changes, and whose current/history rotation
+  commits only after a successful submitted writer frame. History recipes initially accept one
+  single-sample 2D color mip/layer so slot validity always means complete initialization.
+- Add camera-relative cascaded shadows for directional lights on the shared WebGL 2/WebGPU shadow
+  atlas path. `DirectionalLight.shadow` now supports one to four cascades, practical split
+  weighting, a maximum shadow distance, cross-cascade blending, and texel stabilization while
+  preserving the existing single-shadow default. Filtered directional shadow contrast is
+  art-directable through `shadowStrength`. Add an interactive pastel sunset geometry-garden example
+  with live cascade count, stabilization, orbit controls, split, blend, strength, distance, and 4×
+  MSAA.
+- Promote `OrbitControls` from an example helper to the public `src/controls` API, add constrained
+  `setView()` support for scripted tours, and make maintained examples reuse the engine control
+  instead of carrying local camera gesture implementations.
+
 # 2.0.0-alpha.2 (2026-07-26)
 
 ### Breaking changes
@@ -46,6 +356,8 @@
 
 ### Fixes
 
+- Preserve GLSL comparison shadow samplers during storage-graphics WGSL lowering instead of
+  incorrectly sending already translated depth textures through numeric-depth specialization.
 - Keep float scene-color variants linear by suppressing material-local gamma encoding and legacy
   per-material tone mapping until the final display transform. Preserve HDR Bloom energy with
   normalized Karis weights, remove the non-physical far-distance light floor, and use refracted
@@ -58,6 +370,9 @@
   storage rows, pointer input, and readback. Apply it to Bloom, Color Uber, graph present,
   transmission, ShaderToy, Life Game, the compute particle field, the compute path tracer, and
   built-in material/environment sampling so WebGL 2 and WebGPU retain the same Y orientation.
+- Keep shared Shadow Atlas rectangles in positive top-left coordinates and convert light-space UVs
+  through the portable render-target helper. WebGL 2 no longer samples a vertically mirrored depth
+  atlas that made moving shadows appear to rotate opposite their casters.
 - Correct `SpriteFrame`'s top-left atlas-row offset for `flipY` textures on both backends. Full
   textures were unaffected, but subframes previously selected the vertically opposite source row,
   swapping nine-slice top/bottom pieces and requiring reversed character-direction maps. Use a
@@ -86,9 +401,10 @@
 
 ### Changes
 
-- Add a portable `build-hilo3d-games` Agent Skill with strict TypeScript/Vite starters for 2D, 3D,
-  and hybrid games, stable-first `2.0.0` dependency resolution, focused public-API references, and
-  repository checks that keep bundled examples and version-selection behavior valid.
+- Add a portable `hilo3d-game` Agent Skill under `skills/` with strict TypeScript/Vite starters for
+  2D, 3D, and hybrid games, stable-first `2.0.0` dependency resolution, focused public-API
+  references, and repository checks that keep bundled examples and version-selection behavior valid
+  without treating the skill as repository-scoped Codex guidance.
 - Separate the full release gate from npm's publish lifecycle: `npm run release:check` retains the
   complete validation matrix, while `prepublishOnly` performs only fast deterministic checks before
   `prepack` builds the tarball, avoiding repeated browser suites and expired publish OTPs.
@@ -149,19 +465,21 @@
   forces, boundary physics, GPU-authored indirect arguments, and three particle raster layers stay
   on the public Render Graph/RHI path. Its deterministic test mode drives real pointer input without
   reading particle state back to the CPU.
-- Keep first-release compute textures limited to complete 2D graph resources, with transient
-  write-only storage textures and no persistent storage-texture or layer/mip-view API. Persistent
-  state uses externally owned renderer `StorageBuffer` objects imported per frame; each Renderer
-  accepts one pending storage-buffer readback. `cpu-shadow` recovery restores CPU bytes rather than
-  later GPU mutations, and Direct WGSL `f16` remains fail-closed until the Naga validation path can
-  validate it end to end. Storage-aware graphics retains broader Material/Scene texture reflection,
-  while `GPUDrivenRenderPass` rejects non-2D graph texture bindings before backend execution.
+- Keep storage texture writes write-only and complete for the selected single-mip view; overlapping
+  sampled/write feedback remains invalid. Persistent texture state uses renderer-owned history
+  recipes, while persistent buffer state uses externally owned renderer `StorageBuffer` objects
+  imported per frame; each Renderer accepts one pending storage-buffer readback. `cpu-shadow`
+  recovery restores CPU bytes rather than later GPU mutations, and Direct WGSL `f16` remains
+  fail-closed until the Naga validation path can validate it end to end. Storage-aware graphics
+  retains broader Material/Scene texture reflection, while `GPUDrivenRenderPass` validates explicit
+  graph view dimension, format, and sample type before backend execution.
 - Expose the built-in forward culling results to features, reject feature runtimes shared across
   Renderers, and preserve selected RenderTarget color/depth/stencil clear/load/store operations
   across feature-enabled scene, intermediate-color, and output passes.
-- Reject pre-opaque scene-color sampling and keep the built-in forward feature's `sampledDepth`
-  option fail-closed; a custom SRP can explicitly compose depth prepass, compute culling, and a
-  storage-aware Scene pass for Forward+.
+- Reject pre-opaque scene-color sampling and support built-in Forward `sampledDepth` through
+  single-sample sampleable depth plus portable non-filtering fullscreen bindings. A custom SRP can
+  still explicitly compose depth prepass, compute culling, and a storage-aware Scene pass for
+  Forward+.
 - Add backend-neutral `Renderer.waitForIdle()` for application completion fences. Native WebGL 2 or
   WebGPU interoperability is opt-in through `Renderer.getExtension()` instead of public `gl` or
   `gpuDevice` fields.