hilo3d 2.0.0-alpha.4 → 2.0.0-alpha.5

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ### Breaking changes
 
+- Move skin history validity from the removed `SkinningBlock.u_skinHistoryParams.x` to
+  `ModelBlock.u_modelHistoryParams.y`. The two 128-joint palettes now occupy exactly 16,384 bytes,
+  fitting the WebGL2 minimum uniform-block capacity. Custom shaders and block producers must use the
+  new location; model and skin validity remain independent.
+
 - 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
@@ -26,16 +31,111 @@
   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.
+  shaders that redeclare built-in blocks must use the updated field order and capacities. Add
+  `u_modelLayerParams` to `ModelBlock` so direct and GPU Scene clustered shading share the uint32
+  receiver light-layer contract.
 - 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.
+- Make `ClusteredForwardPlusPipelineFactory.create()` asynchronous so renderer initialization can
+  finish its declared material-variant warmup before the first frame.
 
 ### Changes
 
+- Add tag-driven npm releases: the release command creates and pushes an annotated tag matching all
+  three package versions, then GitHub Actions validates the tagged commit and publishes `hilo3d`,
+  `@hilo/addon-particle`, and `@hilo/addon-physics` under one dist-tag through npm Trusted
+  Publishing. Addon peer dependencies use the exact synchronized core version, and safe workflow
+  retries skip package versions that are already present in npm.
+- Allow local Playwright release validation to select an unoccupied loopback port with
+  `HILO3D_PLAYWRIGHT_PORT`; CI retains the deterministic default port.
+- Make `site:build` own the complete public API declaration/check prerequisite for the core and both
+  addon packages. The Pages and CI preflight workflows now invoke self-contained `site:build` and
+  `lint` commands, while the Node-side repository preflight prevents clean-checkout jobs from
+  calling built-only commands without addon declarations.
+- Replace the unenrolled Linux-only RHI performance-rig contract with an auditable Apple M3 Max
+  macOS/Metal profile. Require AC power, High Power Mode, a warning-free thermal state, exact
+  Node/Playwright/Chromium identity, physical Metal, GPU timers, precise memory, and allocation
+  profiling before collection or immutable baseline freezing. Size the release benchmark for a small
+  engine with three rounds, 500 timing/GPU frames, bounded one-frame allocation profiles, and a
+  single-draw absolute-allocation sentinel while retaining stress allocation data diagnostically.
+  Add per-phase progress and abortable browser/heap-profiler waits so a lost response fails
+  explicitly instead of hanging a formal run. Keep the large-instancing workload's 640,000-byte
+  dynamic budget scoped to instance transforms instead of incorrectly requiring the dynamic-texture
+  fixture, and distinguish a persistent shadow caster from steady shadow redraws after the atlas
+  cache is warm. Keep the sole churn shadow caster identity stable while cycling all ordinary mesh
+  slots, and explicitly budget the two shadow-view redraws caused by scene-child churn. Give the
+  depthless MRT/MSAA source workload the same explicit no-depth-write state as its fullscreen
+  continuation passes. Count first-complex-frame dynamic shadow invalidation and its final
+  linear-to-sRGB surface transfer in the declared steady draw budget. Keep targeted churn smoke
+  bounded to one complete ordinary-mesh replacement cycle unless its 10,000-frame tail is explicitly
+  requested; formal enrolled-rig capture still completes the full workload.
+- Add the versioned, dependency-aware public Stage System ABI with typed services, transactional
+  asynchronous setup, synchronous frame hooks, dynamic leaf installation, and reverse-order
+  teardown. Add the separately packaged `@hilo/addon-physics` portable 2D/3D runtime with bounded
+  fixed stepping, interpolated Hilo node bindings, bodies, colliders, joints, events, filtered ray
+  and shape queries, bounded overlaps, point projection, kinematic character controllers, snapshots,
+  debug geometry, diagnostics, and independently importable Rapier 2D/3D adapters. Replace the
+  Cannon example and dependency with a Rapier 3D System example.
+- Move the authored particle runtime out of the `hilo3d` entry into the independently tree-shakable
+  `@hilo/addon-particle` ESM package. Add a Stage-owned particle runtime and frame budget service,
+  route addon rendering through a generic core render-node capability, migrate maintained particle
+  examples and package types, and add Rapier material, joint, and 2D sensor showcases.
+
+- Rebuild portable GTAO around view-relative dual horizons, projected-normal analytic visible-arc
+  integration, depth-derived or hybrid normals, a separately controlled contact lobe, integrated
+  bent normals, distance/edge fading, and explicit low/medium/high/ultra budgets. Add logarithmic-
+  depth reconstruction, per-camera pass/UBO isolation, closest-depth motion selection, depth/normal
+  confidence, variance clipping, vector-space bent-normal filtering, unblurred rejection depth, and
+  joint bilateral upsampling. Feed color-aware multi-bounce visibility and bent-cone specular
+  visibility into ordinary and Clustered PBR, retune The Silent Dragon, and add a deterministic GTAO
+  Acceptance Lab with corner, thin-card, slab, stair, normal-map, dielectric/metal, moving-occluder,
+  screen-edge, log-depth, on/off, temporal, and WebGL2/WebGPU parity gates.
+- Upgrade WebGPU high-end SSR with response-aware 8×8 tile masks, coherent prefix compaction,
+  indirect stochastic visible-GGX tracing, roughness-adaptive ray budgets, refined depth crossings,
+  hit-normal facing validation, and explicit uncertain/backface outcomes. Evaluate receiver- and
+  hit-motion-domain history candidates against real previous material/depth state, authored reactive
+  masks, YCoCg neighborhood variance and roughness-adaptive sample counts; replace four fixed
+  filters with one adaptive bilateral hole-fill and a full-resolution edge-aware resolve. Align
+  clearcoat/anisotropy trace lobes with forward IBL, keep fallback removal independent from SSR
+  intensity, replace absolute half-float hit UVs with motion/depth state, compress material
+  attributes to `rgba8unorm`, prefer `rg11b10ufloat` reflection MRTs when supported, and expose
+  mutually exclusive uncertain/backface and history diagnostics alongside active/hit/miss counters.
+  Cap compacted active-tile indirect work to a two-dimensional 65,535-wide dispatch, retain
+  reflection-response/material identity in temporal history and spatial filtering, and make ordinary
+  Forward reflection MRTs reuse the main PBR GTAO visibility and iridescence parameters.
+- Add the first S0 production shadow-cache slice. Stable atlas tiles now use exact light/caster
+  snapshots, scissored portable depth clears, per-slice invalidation, submission commit/rollback,
+  recovery invalidation, and `RendererDiagnostics.caches.shadowAtlas`; static slices issue no shadow
+  pass, while local-light changes redraw only their affected faces.
+- Extend S0 shadows with clustered GPU Scene caster culling and fixed-bucket indirect depth draws;
+  receiver-driven local/cascade resolution; deterministic slice budgets and 1/2/4/8-frame CSM
+  cadence; and submission-aware 128-pixel page residency with coalesced page-scissored updates that
+  avoid replaying the caster queue once per adjacent page. Expose page
+  request/update/defer/residency and budget-overflow counts in frame diagnostics.
+- Add opt-in WebGPU Clustered virtual directional shadows through
+  `ClusteredForwardPlusPipelineOptions.virtualShadows`: previous-Hi-Z receiver classification,
+  atomic GPU request deduplication and deterministic ordering, arbitrary logical-to-physical page
+  remapping with LRU eviction, deferred dirty-page retry, per-page GPU caster compact/indirect depth
+  draws, and camera-centered directional clipmaps. Double-buffer page tables, residency, and clipmap
+  epochs commit only after successful submission; failed frames roll back and device recovery
+  reinitializes mappings without CPU request readback. Expose on-demand virtual-shadow diagnostics
+  and retain shared CSM fallback for missing pages and non-GPU caster scenes.
+- Complete the WebGPU high-end Clustered Forward+ P0 closure. Globally sorted compatible transparent
+  PBR and direct GPU Scene skin, morph, and layered glTF PBR now consume the native storage light
+  list, while mixed Transmission/custom/particle transparent queues fail closed to the shared
+  Forward path. Add transparent/transmission and isolated GPU-particle reactive, depth-agreement,
+  history-resurrection composition; analytic Spot cookie/IES records and uint32 light-layer
+  filtering; a public material-variant manifest with asynchronous warmup, transactional runtime
+  admission, fixed budgets, and diagnostics; and real WebGPU pixel/UI coverage for rollback, device
+  loss, recovery, layered/deformed lighting, particles, and mixed-queue fallback. Fix the stateless
+  particle WGSL hash expression for strict browser parser precedence.
+
+- Resolve the `hilo3d-game` starter dependency from the npm `next` dist-tag, validate its supported
+  2.0 release shape, and pin the resolved concrete version for reproducible installs.
 - 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
@@ -158,17 +258,17 @@
   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.
+  The opt-in path adds a strict built-in `material-attributes` `rgba8unorm` ABI, matching HDR 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

package/README.md

@@ -127,6 +127,7 @@ path and compose into the same linear HDR frame.
 | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
 | GPU Scene               | Dirty object/material databases, previous-frame Hi-Z occlusion, projected-radius LOD, compact visible ranges, and fixed indirect buckets  |
 | Clustered Forward+      | Depth-driven 3D clusters, bounded deterministic light allocation, storage PBR, shared directional/spot/point shadows, and LTC area lights |
+| Shadow caching          | Stable atlas tiles, exact per-slice invalidation, scissored depth clears, transactional reuse, and recovery-aware diagnostics             |
 | Temporal rendering      | Motion vectors, authored reactive masks, native TAA, 0.5–1.0 TAAU, and timestamp-driven dynamic resolution                                |
 | Screen-space lighting   | Portable GTAO and SSGI on WebGPU/WebGL 2, plus WebGPU Clustered hierarchical SSR                                                          |
 | Volumetrics and weather | Froxel height/local fog, directional/point/spot injection, physical atmosphere LUTs, temporal clouds, and cloud shadows                   |

package/README_ZH.md

@@ -123,6 +123,7 @@ Scene 覆盖范围内的兼容 Mesh 会继续走共享 Forward 路径，并合
 | ------------------ | ----------------------------------------------------------------------------------------------------- |
 | GPU Scene          | 脏对象/材质数据库、previous-frame Hi-Z 遮挡、projected-radius LOD、紧凑可见区间与固定 indirect bucket |
 | Clustered Forward+ | depth-driven 3D cluster、有界且确定性的灯光分配、storage PBR、共享方向光/聚光/点光阴影与 LTC 面光     |
+| 阴影缓存           | 稳定 atlas tile、逐 slice 精确失效、局部深度清理、事务式复用与 recovery-aware 诊断                    |
 | 时域渲染           | Motion Vector、authored reactive mask、原生 TAA、0.5–1.0 TAAU 与 timestamp 驱动的动态分辨率           |
 | 屏幕空间光照       | WebGPU/WebGL 2 可移植 GTAO 与 SSGI，以及 WebGPU Clustered hierarchical SSR                            |
 | 体积与天气         | Froxel 高度雾/局部雾、方向光/点光/聚光注入、物理大气 LUT、时域云与云影                                |