@genex-ai/cli-demo 0.6.1 → 0.7.0

package/templates/skills/genex-threejs-exposure-color-grading/references/exposure-grading.md

@@ -1,30 +1,205 @@
-# Exposure And Color Grading
+# Scene-referred exposure and color pipeline
 
-Use this reference for final image response.
+Use this reference for a measured HDR-to-display path with encoded luminance readback, asymmetric adaptation, one tone-map owner, and a generated display-domain 3D LUT.
 
-## Metering
+## Contents
 
-- Downsample luminance or sample a stable set of pixels.
-- Use log-average luminance for robust exposure.
-- Ignore or reduce weighting for UI and transient VFX when they should not drive
-  exposure.
-- Clamp exposure range.
+- Exact pipeline order
+- Luminance meter
+- Exposure target and adaptation
+- 3D LUT construction
+- LUT placement
+- Tone mapping ownership
+- Observed limitations
+- Diagnostics
 
-## Adaptation
 
-- Use different speeds for brightening and darkening when useful.
-- Smooth by `deltaTime`.
-- Reset or seed exposure intentionally on scene transitions.
+## Exact pipeline order
 
-## Tone mapping
+The pipeline computes:
 
-- Choose one tone mapping stage.
-- Place bloom before tone mapping.
-- Place display grading after tone mapping unless the project has a specific
-  scene-referred grading path.
+```text
+HDR scene after AO/atmosphere
+  -> bloom added in HDR
+  -> multiply by adapted exposure
+  -> renderOutput using renderer tone mapping
+  -> saturate to LUT domain
+  -> sample 3D LUT
+  -> blend LUT intensity
+  -> optional FXAA
+```
 
-## Grading
+`RenderPipeline.outputColorTransform` is disabled and one output node owns the
+final conversion. Renderer tone-mapping mode and renderer exposure are still
+configuration inputs to `renderOutput`.
 
-- Keep gameplay-critical colors distinguishable.
-- Provide a neutral grade toggle.
-- Validate captures on multiple scene lighting states.
+## Luminance meter
+
+The implementation renders a `64 x 36` meter target using unsigned bytes. It encodes
+unbounded luminance:
+
+```text
+encoded = luminance / (luminance + 1)
+decoded = encoded / max(0.0001, 1 - encoded)
+```
+
+Readback occurs asynchronously every `12` frames by default. While one readback
+is pending, another is not started.
+
+CPU reduction uses weighted log average:
+
+```text
+weight = 1.0 when luminance > 0.002
+weight = 0.15 otherwise
+
+average =
+  exp(sum(log(max(luminance, 0.0001)) * weight) / sum(weight))
+```
+
+This suppresses black-pixel dominance without requiring a histogram.
+
+## Exposure target and adaptation
+
+Defaults:
+
+```text
+minimum exposure = 0.45
+maximum exposure = 1.85
+middle gray = 0.18
+compensation = 0 EV
+speed up = 3.2
+speed down = 1.1
+```
+
+Target:
+
+```text
+target =
+  clamp(
+    middleGray / averageLuminance
+    * 2^exposureCompensation,
+    minExposure,
+    maxExposure
+  )
+```
+
+Frame-rate-independent adaptation:
+
+```text
+speed = target > current ? speedUp : speedDown
+amount = 1 - exp(-max(deltaSeconds, 0) * speed)
+current += (target - current) * amount
+```
+
+When disabled, current and target reset to `1`.
+
+## 3D LUT construction
+
+Build a `32^3` RGBA `Data3DTexture` with linear filtering, clamp wrapping, no
+mipmaps, and unsigned-byte storage.
+
+Each preset recipe owns:
+
+```text
+contrast
+saturation
+vibrance
+black/white point
+per-channel gamma
+shadow/midtone/highlight tint
+strength for each tonal range
+```
+
+Recipe order:
+
+```text
+normalize black/white range
+S-curve blend, fixed amount 0.44
+contrast around 0.5
+shadow tint
+midtone tint
+highlight tint
+per-channel gamma
+saturation
+vibrance
+small highlight glow bias
+clamp to [0, 1]
+```
+
+Tonal weights are calculated from pre-grade luminance:
+
+```text
+shadow = 1 - smoothstep(0.12, 0.54, luma)
+highlight = smoothstep(0.48, 0.92, luma)
+midtone = max(0, 1 - abs(luma - 0.5) * 2)
+```
+
+## LUT placement
+
+The LUT samples tone-mapped display-linear RGB after saturation:
+
+```text
+uv = saturate(displayColor.rgb) * ((32 - 1) / 32) + 0.5 / 32
+graded = texture3D(lut, uv)
+final = mix(displayColor, graded, lutIntensity)
+```
+
+This means the included recipes are authored for a bounded post-tone-map
+domain. Do not move them before tone mapping without rebuilding the recipes and
+documenting a scene-linear or log domain.
+
+## Tone mapping ownership
+
+Available renderer modes include:
+
+```text
+None, Linear, Reinhard, Cineon, ACES, AgX, Neutral
+```
+
+Color defaults:
+
+```text
+tone mapping = ACES
+renderer exposure = 0.72
+LUT = Real Daylight
+LUT intensity = 1
+```
+
+The feature factory initially disables LUT intensity and eye adaptation until
+enabled through settings. Distinguish configuration defaults from active
+feature state.
+
+## Observed limitations
+
+- The meter has no center weighting, percentile clipping, sky mask, or UI mask.
+- Unsigned-byte encoding loses precision near extreme luminance.
+- Readback cadence is frame-count based, so wall-clock cadence changes with
+  frame rate.
+- A failed readback resets target exposure to `1`, which can cause a visible
+  adaptation shift.
+- LUT generation clamps every entry to `[0,1]`; it is display-domain grading,
+  not HDR scene-referred grading.
+- The pipeline exposes both renderer `toneMappingExposure` and a separate
+  adapted exposure multiplier. Their combined ownership must be documented to
+  avoid accidental double exposure.
+- FXAA is applied after grading, but dithering/gamut compression are absent.
+
+## Diagnostics
+
+Expose:
+
+```text
+meter source
+encoded meter target
+decoded luminance
+weight mask
+measured average
+target/current exposure over time
+readback pending and cadence
+HDR before exposure
+tone-mapped before LUT
+neutral versus selected LUT
+per-recipe tonal weights
+clipped/out-of-domain mask
+final with one exposure stage disabled at a time
+```

package/templates/skills/genex-threejs-image-pipeline/SKILL.md

@@ -5,26 +5,47 @@ description: Design the final image pipeline for Genex Three.js games. Use for r
 
 # Genex Three.js Image Pipeline
 
-Own the frame deliberately. Advanced effects fail when every pass invents its
-own depth, color, history, or tone mapping path.
+Use this skill only when composing several image-space systems or defining shared buffers. For one effect, load its atomic skill instead.
 
-Read [references/image-pipeline.md](references/image-pipeline.md) for pass
-ordering, signal ownership, diagnostics, and cleanup.
+Load:
 
-## Build order
+- `$genex-threejs-screen-space-ambient-occlusion` for GTAO, bent normals, denoising, or AO application;
+- `$genex-threejs-bloom` for HDR extraction and bloom;
+- `$genex-threejs-exposure-color-grading` for metering, adaptation, tone mapping, LUTs, and output conversion.
 
-1. Inventory the frame: scene color, depth, normals, velocity/history, masks,
-   transparency, UI, and output.
-2. Assign one owner for each shared signal.
-3. Order passes from geometry signals to lighting support to final image.
-4. Keep tone mapping and output color at the end.
-5. Add per-pass debug views and no-post baseline.
-6. Dispose render targets and composers on resize or scene teardown.
+The pipeline must expose its signals and ordering. Do not install a pile of effects and tune the final frame blindly.
+
+## Signal order
+
+```text
+scene HDR color + depth + normals + albedo where required
+  → lighting-related screen effects
+  → atmosphere/transparency composition
+  → bloom
+  → exposure
+  → tone mapping
+  → grading
+  → lens/presentation effects
+  → output conversion
+```
+
+Read [references/image-pipeline.md](references/image-pipeline.md)
+for four production pass graphs, their buffer/resolution contracts, and the
+ownership boundaries between whole-scene and effect-local graphs.
 
 ## Rules
 
-- Do not let each effect render its own incompatible depth or normal pass.
-- Keep UI composition separate from world post-processing unless intentional.
-- Make DPR and resize behavior explicit.
-- Track render-target count, resolution, and memory.
-- Validate pass order by toggling each effect.
+- Tone-map once.
+- Keep HDR bloom before tone mapping.
+- Meter exposure from a small luminance target, not the final 8-bit screen.
+- Separate direct and indirect light before applying bent-normal ambient tint when possible.
+- Upsample low-resolution effects with depth/normal-aware weights.
+- Build pass toggles and effect-only views before tuning.
+- UI rendered in the same target needs an explicit protection strategy.
+- Do not load all atomic post skills by default. Route only the effects actually requested.
+
+## Routing boundary
+
+Use this skill when multiple image-space systems must share buffers, ordering,
+or output ownership. For one isolated effect, use its atomic skill without
+loading this coordinator.

package/templates/skills/genex-threejs-image-pipeline/references/image-pipeline.md

@@ -1,39 +1,195 @@
-# Image Pipeline
+# Production image-pipeline contracts
 
-Use this reference when a Genex game has multiple render passes.
+Use this reference to compose shared scene buffers, lighting effects, atmosphere, bloom, exposure, tone mapping, grading, and feature-local render targets with explicit ownership.
 
-## Typical pass order
+## Contents
 
-1. Main scene signals: color, depth, normals, masks.
-2. Lighting support: shadows, AO, reflections, volumetrics.
-3. Screen-space effects: refraction, temporal masks, distortion.
-4. HDR effects: bloom and other emission-based contributions.
-5. Exposure and tone mapping.
-6. Color grading.
-7. UI and presentation overlays.
+- production WebGPU pipeline WebGPU graph
+- selective gallery pipeline selective gallery graph
+- atlas-based renderer composer graph
+- Temporal-surface effect-local graph
+- Buffer and ownership rules
+- Resolution policies
+- Failure analysis
+- Diagnostics
 
-## Shared signals
 
-- Depth: document projection and encoding.
-- Normals: document space and packing.
-- Color: document linear/HDR/display state.
-- History: document reset and reprojection rules.
-- Masks: document semantic meaning and lifetime.
+## production WebGPU pipeline WebGPU graph
 
-## Diagnostics
+When GTAO is enabled, the scene pass writes MRT:
+
+```text
+output HDR color
+view-space normal
+diffuse albedo
+depth
+```
+
+Graph:
+
+```text
+scene MRT
+  -> reduced GTAO + bent normal
+  -> full-resolution bilateral/lighting composite
+  -> atmosphere
+  -> bloom
+  -> adapted exposure
+  -> renderOutput / tone map
+  -> 3D LUT
+  -> FXAA
+```
+
+Near/far values, environment intensity, and environment texture remain
+updateable inputs. AO is applied through its dedicated composite rather than
+blindly multiplying the final image.
+
+The atmosphere pass reconstructs view/world position from depth,
+classifies sky, and owns aerial haze, height fog, sun disc/shaft, lens flare,
+and distance grading. Its optional post-process cloud shadow is explicitly
+disabled in its configuration, avoiding duplicate ownership with material
+lighting.
+
+## selective gallery pipeline selective gallery graph
+
+The gallery owns three composers:
+
+```text
+neon selective bloom
+chandelier selective bloom
+base + final additive composite + OutputPass
+```
+
+Selective renders use layer membership plus temporary black material
+substitution with `try/finally` restoration. CSS3D content is rendered by a
+separate renderer after WebGL when invalidated.
+
+Shadows use VSM and manual invalidation:
+
+```text
+shadowMap.autoUpdate = false
+shadowMap.needsUpdate = true only after relevant scene/light changes
+```
+
+This is a bounded-scene optimization. It depends on every moving caster and
+light correctly invalidating the cache.
+
+## atlas-based renderer composer graph
+
+atlas-based renderer performs a separate depth prepass into a depth-stencil target before
+the composer:
+
+```text
+depth prepass target
+main render
+SSAO
+volumetric lighting
+bloom
+lens flare
+fog/color grading
+```
+
+The depth target uses nearest filtering and a
+`DepthStencilFormat`/`UnsignedInt248Type` depth texture. Every depth consumer
+receives that same texture.
+
+The composer recalculates effective pixel dimensions from renderer pixel ratio
+and resizes the depth target and all passes together.
+
+The composer can exist alongside another application post path. Verify the
+actual render-loop call path before claiming that this graph owns runtime
+output.
 
-Provide a pass inspector or simple toggles for:
+## Temporal-surface effect-local graph
+
+The temporal frost graph is not a whole-scene post stack. It is a
+self-contained material effect:
+
+```text
+scene at full resolution
+  -> vertical blur at 0.4 DPR
+  -> horizontal blur at 0.4 DPR
+  -> frost composite at full resolution
+  -> pointer history write/swap at full resolution
+  -> final normal/refraction output
+```
+
+Three static procedural texture targets render once. This is a feature-local
+example of mixing persistent, static, low-resolution, and full-resolution
+signals in one feature.
+
+## Buffer and ownership rules
+
+Before implementation, write:
+
+| Signal | Producer | Consumers | Space/format | Resolution | History |
+| --- | --- | --- | --- | --- | --- |
+| HDR scene | scene pass | AO/atmosphere/bloom | linear HDR | full | no |
+| depth | scene or prepass | AO/fog/flare | renderer-defined | full | no |
+| normal | MRT/geometry | AO composite | view space | full | no |
+| albedo | MRT | indirect composite | linear | full | no |
+| bloom contributions | selective passes | final composite | HDR | full/pyramid | no |
+| exposure | meter | final color | scalar | 64x36 source | adapted |
+| interaction | ping-pong pass | frost/output | half-float | full | yes |
+
+Every signal has one producer. If a scene pass already owns depth and normal,
+do not add an uncoordinated duplicate prepass without measuring the reason.
+
+## Resolution policies
+
+selective gallery pipeline caps DPR from both device and pixel budget:
+
+```text
+mobile budget = 1,000,000 pixels, max DPR 1.25
+desktop budget = 1,650,000 pixels, max DPR 1.5
+minimum DPR = 1
+budget DPR = sqrt(pixelBudget / CSS pixel count)
+```
+
+All composers receive the same selected DPR and CSS size.
+
+The temporal frost graph instead gives individual passes fixed roles:
+
+```text
+blur and coarse noise = 0.4 DPR
+composite, history, output = display DPR
+```
+
+Choose global DPR budgeting for scene cost and per-pass scaling for effect
+bandwidth. They solve different problems.
+
+## Failure analysis
+
+- production WebGPU pipeline API names are version-sensitive; `PostProcessing` was renamed
+  and deprecated in favor of `RenderPipeline` in current Three.js history.
+- selective gallery pipeline selective bloom renders the scene multiple times.
+- selective gallery pipeline manual shadow invalidation can freeze unregistered motion.
+- atlas-based renderer depth prepass renders regular scene materials, not an explicit depth
+  override; verify transparent and alpha-tested behavior.
+- atlas-based renderer composer may not be the active runtime path.
+- The frost blur has a zero-weight division risk and pointer decay is frame
+  based.
+- None of these graphs provides a complete velocity/motion-vector
+  contract for general temporal effects.
+- Do not advertise velocity ownership or TAA merely because a generic pipeline
+  could include them.
+
+## Diagnostics
 
-- no-post scene;
-- depth;
-- normals;
-- masks;
-- AO;
-- bloom source and result;
-- exposure;
-- final output.
+Expose a graph inspector or equivalent stable views:
 
-## Cleanup
+```text
+scene HDR
+depth raw and reconstructed
+normal/albedo MRT
+GTAO and bent normal
+atmosphere only
+each selective bloom contribution
+exposure meter and current exposure
+pre/post tone map and LUT
+frost static/history/composite targets
+pass resolution, format, memory, and GPU time
+manual invalidation state
+```
 
-Resize render targets on canvas changes. Dispose render targets, materials,
-geometries, and composers when leaving the scene.
+The pipeline is accepted only when every enabled pass has a named input,
+output, owner, resolution, and disable path.

package/templates/skills/genex-threejs-procedural-animation/SKILL.md

@@ -5,27 +5,40 @@ description: Build procedural animation systems for Genex Three.js games. Use fo
 
 # Genex Three.js Procedural Animation
 
-Use deterministic motion systems that can be replayed, tuned, and synchronized.
-Animation should support gameplay clarity before it adds spectacle.
-
-Read [references/procedural-motion.md](references/procedural-motion.md) for
-timeline, spring, rotating-frame, and debris patterns.
+Animate semantic state, not unrelated transform curves. Define phases,
+coordinate frames, velocities, and ownership before writing per-frame updates.
 
 ## Build order
 
-1. Define the motion contract: start/end state, duration, loop policy, gameplay
-   meaning, and interrupt behavior.
-2. Use analytic time or explicit simulation state; avoid hidden wall-clock
-   dependencies.
-3. Split position, orientation, scale, and material animation into named phases.
-4. Use quaternion alignment for moving frames and docking-style orientation.
-5. Use damped springs only where inertia is intended.
-6. Expose debug controls for pause, time scale, phase, seed, and loop reset.
-
-## Rules
-
-- Advance animation with `deltaTime`; never assume a fixed frame rate.
-- Keep random variation seeded and reproducible.
-- Prefer one clear motion cause over several unrelated noise offsets.
-- Make restart, pause, scene disposal, and replay deterministic.
-- Keep gameplay-critical state separate from purely visual offsets.
+1. Define the timeline phases and event boundaries.
+2. Choose the frame for each motion: world, subject local, orbital radial,
+   docking axis, or camera shot.
+3. Derive target position/orientation from that frame.
+4. Use analytic kinematics for authored travel and springs for responsive
+   convergence.
+5. Preserve world transforms when detaching children from a hierarchy.
+6. Separate translation, alignment, spin, and secondary debris state.
+7. Clamp integration delta and reset every state variable on replay/disposal.
+
+Read [references/procedural-motion.md](references/procedural-motion.md)
+for the launch, staging, docking, debris, spring, quaternion, and
+frame-rate-independent response implementations.
+
+## Non-negotiable rules
+
+- Use elapsed seconds and `deltaSeconds`; do not make motion frame-count based.
+- Derive orientation from direction/frame, then apply roll or spin as a
+  separate quaternion.
+- Decompose docking error into axial and radial components.
+- Switch from spring convergence to an exact terminal pose at the end of a
+  sequence.
+- When reparenting an animated object, capture world position, quaternion, and
+  scale before removal.
+- Use seeded randomness when motion must be reproducible.
+- Keep visual shake in a bounded envelope and separate it from trajectory.
+
+## Routing boundary
+
+Use `$genex-threejs-camera-direction` for shot composition and camera handoffs.
+Use `$genex-threejs-procedural-vfx` when the deliverable is primarily plasma, sparks,
+or effect pooling rather than object transform motion.