@genex-ai/cli-demo 0.6.0 → 0.6.2

package/templates/skills/genex-threejs-shadow-systems/references/shadow-systems.md

@@ -1,30 +1,429 @@
-# Shadow Systems
+# Cached clipmap shadow system
 
-Use this reference for stable shadows in Genex games.
+Use this reference for stable directional shadows across a large procedural scene using committed light-space centers, texel snapping, bounded refresh budgets, cross-level blending, and targeted invalidation.
 
-## Cascades
+## Contents
 
-- Split camera depth into near, mid, and far ranges.
-- Allocate more resolution to gameplay-near shadows.
-- Stabilize cascade projections to shadow texels.
-- Show cascade boundaries in debug mode.
+1. Representation and defaults
+2. Light-space stabilization
+3. Committed centers and containment
+4. Sampling and cross-level blending
+5. Cache scheduling and invalidation
+6. Bias, defects, adaptation, and diagnostics
 
-## Cached clipmaps
+## 1. Identify the representation correctly
 
-- Use clipmaps for large terrains or cities with slow-changing lighting.
-- Update only dirty regions.
-- Track invalidation from moving objects, time of day, or geometry edits.
-- Keep cache memory visible in diagnostics.
+The system is a set of concentric square shadow maps centered around
+the camera in light space.
 
-## Bias and filtering
+It is **not** a virtual shadow map:
 
-- Tune normal bias and depth bias separately.
-- Inspect acne, peter-panning, and contact loss.
-- Filter only after the map coverage is correct.
-- Keep tiny decorative casters from ruining the budget.
+```text
+no page table
+no physical page cache
+no page-granular caster submission
+one ordinary shadow texture per level
+```
 
-## Quality tiers
+Every level consumes a sampled shadow texture in the material stage. Check the
+target device's sampled-texture limit before increasing level count.
 
-- Low: shorter distance, fewer cascades, lower resolution.
-- Medium: stable near shadows and simplified far coverage.
-- High: more cascades or cached large-world coverage.
+## 2. Preserve the exact default envelope
+
+Default construction:
+
+```text
+first half-width       12 m
+scale factor           2.5
+maximum distance       2000 m
+light margin           100 m
+shadow near            1 m
+shadow far cap         3000 m
+guard band             0.15
+cross-fade ratio       0.15
+dynamic near levels    2
+cached update budget   2 per frame
+maximum cache age      64 frames
+direction epsilon      0.002 radians
+```
+
+Level count:
+
+```text
+ceil(log(maxDistance / firstRadius) / log(scaleFactor)) + 1
+```
+
+Each half-width is:
+
+```text
+min(firstRadius * scaleFactor^level, maxDistance)
+```
+
+The last level is forced to `maxDistance` exactly.
+
+Clamp adaptation controls to safe ranges:
+
+```text
+firstRadius >= 1
+scaleFactor >= 1.5
+guardBand in [0.02, 0.5]
+blendRatio in [0.01, 0.9]
+dynamicLevels in [0, levelCount]
+updateBudget >= 1
+maxCacheAge >= 0
+```
+
+Per-level map sizes may differ. Missing entries use the directional light's
+current shadow-map width.
+
+## 3. Store committed map state
+
+Each level owns:
+
+```ts
+type LevelState = {
+  halfWidth: number
+  centerX: number
+  centerY: number
+  centerZ: number
+  valid: boolean
+  forceDirty: boolean
+  age: number
+}
+```
+
+The shader-facing vector stores:
+
+```text
+x = committed light-space center X
+y = committed light-space center Y
+z = sampled half-width = halfWidth * (1 - guardBand)
+w = unused
+```
+
+Publish the center from the last completed map render. Do not publish the
+camera's desired center while a cached level waits for its budget slot.
+
+That distinction prevents the shader containment box from drifting away from
+the map content and causing rhythmic boundary flicker.
+
+Before a level renders once, park it at:
+
+```text
+center = (1e9, 1e9)
+sample half-width = 1e-6
+```
+
+An invalid level must never win selection.
+
+## 4. Stabilize X/Y by the actual texel footprint
+
+Per level:
+
+```text
+texelWidth =
+  (orthographicRight - orthographicLeft)
+  / mapWidth
+
+desiredX = round(cameraLightX / texelWidth) * texelWidth
+desiredY = round(cameraLightY / texelWidth) * texelWidth
+```
+
+This aligns the orthographic projection to a fixed world-space texel grid.
+
+Quantize Z more coarsely:
+
+```text
+zQuantum = halfWidth * 0.5
+desiredZ = round(cameraLightZ / zQuantum) * zQuantum
+```
+
+Z changes depth coverage and update cadence but does not define the projected
+texel grid, so a coarser quantum is intentional.
+
+Do not snap by a fraction of total level extent. At coarse levels that produces
+tens-of-meters jumps.
+
+## 5. Derive the light-space frame once
+
+Each frame:
+
+```text
+lightDirection = normalize(light.target.position - light.position)
+lightOrientation = lookAt(origin, lightDirection, worldUp)
+worldToLight = inverse(lightOrientation)
+cameraLight = worldToLight * cameraWorld
+```
+
+The direction is considered changed when:
+
+```text
+dot(currentDirection, lastCommittedDirection)
+  < cos(directionEpsilon)
+```
+
+A direction change gives the frame enough budget to refresh all levels.
+
+This gates a continuously moving sun into occasional coherent refreshes. If
+the art direction requires per-frame sun motion, reduce levels or accept the
+cost rather than allowing mismatched cached directions.
+
+## 6. Use a two-class update policy
+
+A level is dirty when:
+
+```text
+it is in the dynamic near set
+or it has never rendered
+or forceDirty is set
+or snapped X/Y/Z changed
+or cache age expired
+or light direction changed
+```
+
+Policy:
+
+```text
+dynamic near levels:
+  render every frame
+  do not consume cached update budget
+
+ordinary cached levels:
+  render only while budget remains
+
+explicitly invalidated levels:
+  bypass the cached budget
+```
+
+Although invalidation may be described as “rate-limited”, `forceDirty` renders
+without consuming or checking the ordinary budget. Preserve that exception
+intentionally or change both behavior and documentation together.
+
+On first update or light-direction change:
+
+```text
+budget = levelCount
+```
+
+Otherwise:
+
+```text
+budget = updateBudget
+```
+
+Age increments every frame and resets after render. Initial ages are staggered:
+
+```text
+age(level) = floor(-level * maxCacheAge / levelCount)
+```
+
+This prevents all coarse levels expiring together.
+
+## 7. Commit camera and map atomically
+
+When a level renders:
+
+1. commit snapped X/Y/Z to `LevelState`;
+2. clear `forceDirty`;
+3. reset age;
+4. place the light at:
+
+```text
+(centerX, centerY, centerZ + halfWidth + lightMargin)
+```
+
+5. transform that position back from light space;
+6. aim the target one light-direction unit away;
+7. force light and target matrices current;
+8. render the shadow map immediately from that committed transform.
+
+The level's orthographic depth range is:
+
+```text
+near = configuredNear
+far = max(
+  near + 1,
+  min(configuredFarCap, lightMargin + 2 * halfWidth)
+)
+```
+
+Every cloned shadow has:
+
+```text
+autoUpdate = false
+needsUpdate = false
+```
+
+The clipmap owner drives updates manually. Allowing Three.js to update the
+clone independently can render from a transform different from the one later
+sampled.
+
+## 8. Cross-fade levels without divergent shadow samples
+
+Transform `shadowPositionWorld` to the shared light-space XY plane.
+
+For each level:
+
+```text
+distance = max(
+  abs(lightX - levelCenterX),
+  abs(lightY - levelCenterY)
+)
+
+fade =
+  1 - smoothstep(
+    sampledHalfWidth * (1 - blendRatio),
+    sampledHalfWidth,
+    distance
+  )
+
+weight = fade * remaining
+remaining *= 1 - fade
+```
+
+Accumulate from finest to coarsest. Leftover weight resolves to unshadowed,
+creating a smooth fade outside the outer level.
+
+Critical GPU contract:
+
+```text
+sample every level's depth-comparison texture unconditionally
+multiply the result by its weight afterward
+```
+
+Do not put comparison sampling behind a per-pixel conditional. Doing so can
+produce view-dependent flicker and undefined derivatives.
+
+`BoundedShadowNode` still evaluates the filter function, then selects `1`
+outside the level's projected XYZ range. This keeps the comparison sample in
+uniform control flow while preventing out-of-bounds projection from shadowing.
+
+## 9. Scale normal bias by texel size
+
+Capture the original directional-light bias values before cloning.
+
+Per level:
+
+```text
+texelScale = levelTexelWidth / finestTexelWidth
+shadow.bias = baseBias
+shadow.normalBias = baseNormalBias * texelScale
+```
+
+The implementation keeps depth bias unchanged and scales only world-space normal bias.
+
+Inspect acne and peter-panning separately per level. A single normal bias
+across 12 m and 2000 m levels is not coherent.
+
+## 10. Target invalidation spatially
+
+`invalidate()` with no bounds sets `forceDirty` on every level.
+
+With a world-space bounding sphere:
+
+1. transform its center to light space;
+2. for each level compute:
+
+```text
+reach = halfWidth + sphereRadius
+```
+
+3. invalidate when both projected X and Y distances are below `reach`.
+
+Use this for:
+
+- streamed terrain arrival;
+- regenerated buildings;
+- moving hero casters;
+- vegetation chunks whose deformed silhouettes matter.
+
+Observed limitation: the test is a conservative square intersection in XY. It
+does not test Z or the exact projected sphere-square distance. This is cheap
+and safe but may refresh extra levels.
+
+## 11. Attach and dispose ownership explicitly
+
+The node attaches through:
+
+```text
+light.shadow.shadowNode = clipmapNode
+```
+
+Detaching removes that property only if it still points to the node.
+
+Disposal must:
+
+- detach from the directional light;
+- dispose every level shadow node;
+- dispose every cloned shadow;
+- remove level lights and targets from their parent;
+- invoke base disposal.
+
+Cached shadow maps are persistent GPU resources. Treat missing disposal as a
+real leak.
+
+## 12. Adaptation workflow
+
+1. Verify target Three.js WebGPU/TSL shadow-node APIs.
+2. Start with two or three equal-resolution levels and no caching.
+3. add X/Y texel snapping;
+4. add guard-band selection and cross-fade;
+5. verify unconditional comparison sampling;
+6. separate dynamic and cached level updates;
+7. publish committed centers only;
+8. add cache-age staggering;
+9. add targeted invalidation;
+10. tune per-level map sizes and normal bias.
+
+Do not add caching before stable selection and committed-state tracking work.
+Caching makes a spatial mismatch persist longer.
+
+## 13. Required diagnostics
+
+Expose:
+
+```text
+level count and texture count
+rendered half-width and sampled half-width
+map size and world texel width per level
+desired versus committed X/Y/Z
+selected level and cross-fade weights
+remaining unshadowed weight
+dynamic/cached classification
+dirty reason bits
+valid/forceDirty/age
+budget before and after updates
+direction delta versus epsilon
+base and scaled normal bias
+shadow-map preview per level
+invalidation sphere in light space
+level render count and GPU time
+```
+
+Failure diagnosis:
+
+```text
+shadows crawl under slow camera motion:
+  X/Y center is not snapped to the level's texel width
+
+level boundaries flicker every other frame:
+  desired center was published while the cached map retained its old center
+
+shadows disappear by view angle:
+  comparison samplers were evaluated in divergent control flow
+
+coarse moving casters freeze:
+  max age and targeted invalidation are both absent
+
+all levels spike together:
+  cache ages were not staggered
+
+important streamed geometry remains unshadowed:
+  explicit invalidation was incorrectly blocked by the coarse update budget
+
+coarse levels show acne:
+  normal bias was not scaled by world texel width
+
+memory grows after scene replacement:
+  cloned shadows, level nodes, lights, or targets were not disposed
+```

package/templates/skills/genex-threejs-skill-router/SKILL.md

@@ -15,27 +15,27 @@ map, execution order, and acceptance gate.
 
 | Work needed | Load |
 | --- | --- |
-| camera rigs, authored shots, chase/orbit/side views, pointer look | `$genex-threejs-camera-direction` |
-| game-object timelines, springs, docking, staging, debris, loops | `$genex-threejs-procedural-animation` |
-| shared scalar/vector fields, masks, domain warping, procedural normals | `$genex-threejs-procedural-fields` |
-| PBR identity, atlas filtering, terrain wetness, dissolves, procedural normals | `$genex-threejs-procedural-materials` |
-| mesh writers, profile sweeps, semantic geometry, UVs, normals, material slots | `$genex-threejs-procedural-geometry` |
-| trees, foliage, roots, branching organisms, wind | `$genex-threejs-procedural-vegetation` |
-| buildings, modular kits, facade grammars, city assets | `$genex-threejs-procedural-architecture` |
-| planets, spherical terrain, craters, biomes, orbit-to-surface detail | `$genex-threejs-procedural-planets` |
-| sky, scattering, aerial perspective, atmosphere-aware lighting | `$genex-threejs-atmosphere-aerial-perspective` |
-| volumetric clouds, weather maps, raymarch budgets, cloud shadows | `$genex-threejs-volumetric-clouds` |
-| large FFT oceans, choppy waves, foam, spectral cascades | `$genex-threejs-spectral-ocean` |
-| analytic water, refraction, absorption, waves, crest foam | `$genex-threejs-water-optics` |
-| black holes, accretion disks, wormholes, curved-ray GPU effects | `$genex-threejs-raymarched-space-effects` |
-| particles, trails, plasma, shockwaves, timed event VFX | `$genex-threejs-procedural-vfx` |
-| accumulated frost, touch history, screen-space temporal masks | `$genex-threejs-temporal-surfaces` |
-| cascades, clipmaps, stable large-world shadows | `$genex-threejs-shadow-systems` |
-| GTAO, bent normals, contact grounding, AO diagnostics | `$genex-threejs-screen-space-ambient-occlusion` |
-| HDR bloom, selective emission, glow diagnostics | `$genex-threejs-bloom` |
-| exposure, tone mapping, color grading, LUTs | `$genex-threejs-exposure-color-grading` |
-| render-target ownership, pass ordering, depth/normal/history signals | `$genex-threejs-image-pipeline` |
-| fixed-view captures, seed sweeps, browser and GPU evidence | `$genex-threejs-visual-validation` |
+| shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, floating origins | `$genex-threejs-camera-direction` |
+| launch and docking timelines, procedural transform phases, springs, staging, rotating-frame alignment, debris motion | `$genex-threejs-procedural-animation` |
+| reusable scalar/vector fields, domain warping, causal masks, procedural normals | `$genex-threejs-procedural-fields` |
+| atlas-filtered blocks, planetary surfaces, terrain wetness, lava/emissive procedural surfaces, authored frame PBR, specular AA | `$genex-threejs-procedural-materials` |
+| sculpted rails/frames, branch rings, semantic mesh writers, material groups | `$genex-threejs-procedural-geometry` |
+| trees, stylized grass, branching organisms, roots, foliage, rooted wind deformation | `$genex-threejs-procedural-vegetation` |
+| buildings, façade grammars, profiles, ornaments, modular mesh writers | `$genex-threejs-procedural-architecture` |
+| planets, terrain, craters, biome fields, coastlines, spherical detail | `$genex-threejs-procedural-planets` |
+| sky scattering, planetary shells, depth-based aerial perspective | `$genex-threejs-atmosphere-aerial-perspective` |
+| weather-driven raymarched clouds and cloud shadows | `$genex-threejs-volumetric-clouds` |
+| FFT oceans, hybrid FFT/Gerstner clear water, stylized above/below ocean optics, spectral cascades, choppy derivatives, Jacobian whitecaps | `$genex-threejs-spectral-ocean` |
+| authored analytic waves, bounded heightfield pools, object ripples, differential-area caustics, ray-traced pool volume optics, shared normals, heuristic refraction, fallback absorption, crest foam | `$genex-threejs-water-optics` |
+| curved-ray black holes, accretion disks, wormholes | `$genex-threejs-raymarched-space-effects` |
+| particles, trails, plasma, shockwaves, layered event effects | `$genex-threejs-procedural-vfx` |
+| accumulated screen frost, touch clearing, reduced blur, and refraction masks | `$genex-threejs-temporal-surfaces` |
+| stable large-world shadows, cascades, clipmaps, cached updates | `$genex-threejs-shadow-systems` |
+| GTAO, bent normals, bilateral reconstruction | `$genex-threejs-screen-space-ambient-occlusion` |
+| HDR bloom and selective emission contribution | `$genex-threejs-bloom` |
+| eye adaptation, tone mapping, LUT grading, output color | `$genex-threejs-exposure-color-grading` |
+| shared depth/normal/velocity ownership and multi-pass ordering | `$genex-threejs-image-pipeline` |
+| fixed-view diagnostics, seed sweeps, temporal and budget evidence | `$genex-threejs-visual-validation` |
 | realtime multiplayer: movement sync, shared state, presence, shots/emotes, persistence | `$genex-threejs-multiplayer` |
 
 **Multiplayer is mandatory routing:** if the game has 2+ players sharing a world, loading

package/templates/skills/genex-threejs-spectral-ocean/SKILL.md

@@ -5,26 +5,36 @@ description: Build large procedural oceans for Genex Three.js games. Use for FFT
 
 # Genex Three.js Spectral Ocean
 
-Use spectral oceans when the game needs large water bodies with convincing
-scale, directionality, and far-distance motion.
-
-Read [references/spectral-ocean.md](references/spectral-ocean.md) for wave
-cascades, foam, shading, and budget controls.
+Treat an ocean as a sampled stochastic wave field with explicit frequency-space ownership. Do not approximate this target with a pile of Gerstner waves, scrolling normal maps, or unrelated foam noise.
 
 ## Build order
 
-1. Define wind direction, fetch, sea state, camera height range, and frame budget.
-2. Split wavelengths into cascades for far swell, mid waves, and near detail.
-3. Generate displacement, slope, curvature, and choppy derivatives from the
-   same wave state.
-4. Derive whitecaps and foam from slope, compression, and lifetime.
-5. Shade with sky reflection, Fresnel, absorption, and crest response.
-6. Expose no-post, normal, slope, foam, and cascade debug views.
-
-## Rules
-
-- Keep wave state deterministic for a seed and time value.
-- Do not fake large oceans with only scrolling normal maps.
-- Use quality tiers for cascade count, resolution, and update cadence.
-- Keep horizon and camera-relative origin stable.
-- Validate motion, not only still frames.
+1. Define the sea-state spectrum and deterministic Gaussian seed.
+2. Partition wavelengths into disjoint cascades.
+3. Validate the inverse FFT independently with analytic inputs.
+4. Generate and conjugate-pack the initial spectrum.
+5. Evolve packed displacement and derivative fields in frequency space.
+6. Inverse-transform every packed field with explicit inter-step barriers.
+7. Assemble displacement, derivatives, and persistent Jacobian foam maps.
+8. Shade from summed cascade displacement and derivatives.
+9. Add sub-grid detail only below the resolved simulation bands.
+10. Expose spectrum, height, slopes, Jacobian, and foam-history diagnostics.
+
+Read [references/spectral-ocean.md](references/spectral-ocean.md) before implementing or auditing a spectral ocean.
+
+## Non-negotiable gates
+
+- Require a power-of-two grid and a passing FFT impulse/frequency test.
+- Keep cascade wavenumber intervals disjoint.
+- Derive normals from transformed derivatives, not a detached normal texture.
+- Detect breaking from the horizontal-displacement Jacobian.
+- Persist foam in simulation state; do not infer all foam anew per frame.
+- Submit FFT stages with the synchronization required by the active backend.
+- Share sun and sky parameters between the visible sky and ocean reflection.
+- Keep a deterministic seed and fixed-camera capture for comparisons.
+
+## Route elsewhere
+
+- Use `$genex-threejs-water-optics` for bounded water, screen-space refraction, depth thickness, shoreline absorption, and analytic wave surfaces.
+- Add `$genex-threejs-procedural-vfx` only when crest spray or interaction splashes are required.
+- Add `$genex-threejs-visual-validation` for cross-seed, temporal, and GPU evidence.