@genex-ai/cli-demo 0.6.0 → 0.6.2

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.