@genex-ai/cli-demo 0.93.0-dev.247 → 0.94.0-dev.249

package/templates/skills/genex-threejs-raymarched-space-effects/references/space-effects.md

@@ -1,194 +0,0 @@
-# Curved-ray numerical integrators
-
-Use this reference for an RK4 wormhole integrator and an artistic inverse-square curved-ray accretion volume, including state reduction, disk accumulation, background lensing, and numerical diagnostics.
-
-## Contents
-
-- Wormhole state reduction
-- Wormhole RK4 integration
-- Universe selection
-- accretion volume screen-volume integration
-- Disk density and color
-- Background lensing
-- Observed defects and boundaries
-- Diagnostics
-
-
-## Wormhole state reduction
-
-The wormhole renderer uses a spherically symmetric throat model. It reduces
-each 3D ray to a two-dimensional integration state:
-
-```text
-y.x = signed radial coordinate l
-y.y = radial momentum pL
-impact parameter b = length(cross(rayOrigin, rayDirection))
-throat radius Rth = 1.2
-```
-
-It constructs an orbital plane:
-
-```text
-normal = normalize(cross(origin, direction))
-u = normalize(origin)
-v = cross(normal, u)
-```
-
-Near-radial rays use fallback axes to avoid a zero cross product.
-
-Initial signed coordinate:
-
-```text
-l = sqrt(max(length(origin)^2 - Rth^2, 0.001))
-pL = dot(normalize(origin), direction)
-```
-
-## Wormhole RK4 integration
-
-The derivative is:
-
-```text
-r2 = l^2 + Rth^2
-dl/ds = r2 * pL
-dpL/ds = b^2 * l / r2
-```
-
-The shader runs fourth-order Runge–Kutta with:
-
-```text
-maximum iterations = 920
-base step = 0.0042
-per-ray step jitter = +/- 0.00045
-escape distance = abs(l) > 40
-azimuth accumulation = step * b
-```
-
-On escape:
-
-```text
-finalDirection =
-  normalize(u * cos(phi) + v * sin(phi))
-```
-
-The sign of final `l` selects which exterior universe is visible. Failure to
-escape renders a bright fallback color, making iteration-cap pixels observable.
-
-This is materially stronger than a UV swirl because the final environment
-direction comes from numerical integration.
-
-## Universe selection
-
-The two exterior universes are independent procedural directional fields. Both
-use five-octave FBM, animated coordinate drift, broad/fine structure, and
-different plane orientation.
-
-Sample those fields only after integration. Lensing must change the lookup
-direction rather than distort an already rendered screen image.
-
-A small direction-hashed grain of amplitude `0.01` reduces visible gradient
-banding.
-
-## accretion volume screen-volume integration
-
-The black-hole effect is evaluated on a sphere surrounding the effect. Defaults:
-
-```text
-iterations = 128
-step = 0.0071
-ray jitter = 0.01
-bending power = 0.3
-core radius = 0.13
-disk half-width = 0.03
-```
-
-Per step:
-
-```text
-r = length(rayPosition)
-steerMagnitude = step * power / r^2
-steerRange = remapClamped(r, 1 -> 0.5, 0 -> 1)
-newDirection = normalize(direction - radial * steerMagnitude * steerRange)
-```
-
-The ray direction is bent toward the center only inside the configured range.
-Unlike the wormhole, this is an artistic inverse-square steering field, not a
-validated metric geodesic.
-
-## Disk density and color
-
-Disk coordinates rotate around the local Z axis with radius and time:
-
-```text
-rotation phase = radialDistance * 4.27 - time * 0.1
-noise UV = rotatedPosition * 2
-```
-
-A repeated deep-noise texture is multiplied by a quadratic band across
-`[-width, 0, +width]`. Radial distance, noise value, and a nearby noise sample
-produce a ramp coordinate.
-
-The three-point color ramp is:
-
-```text
-white-hot at 0.06
-gold at 0.33
-dark amber at 1.0
-emission scale 1.95
-additional emission color (1.0, 0.72, 0.26)
-```
-
-The central sphere below `originRadius` is black. Disk opacity accumulates
-front-to-back into `alphaAcc`; color accumulates using remaining transmittance.
-
-## Background lensing
-
-After the fixed loop, the final bent direction samples a deterministic
-equirectangular star texture generated from `5200` seeded stars on a sphere.
-
-```text
-final = accumulated disk color
-      + remaining transmittance * star environment
-```
-
-The deterministic star field is important: lensing motion can be compared
-without random stars moving between runs.
-
-## Observed defects and boundaries
-
-- The demonstrated accretion-volume loop advances `rayPosition` twice per
-  iteration while its steering magnitude uses a single `step`. Treat the
-  effective distance step as `2 * step`, or remove the duplicate advance and
-  retune the complete density-and-bending system explicitly.
-- accretion volume has no early exit and no termination IDs; every pixel pays the full
-  iteration count.
-- Its disk is detected by local band density at samples, not by a continuous
-  plane-crossing test. A large step can skip a thin disk.
-- The artistic inverse-square steering must not be described as general
-  relativity.
-- The wormhole uses a fixed high iteration cap and per-ray step jitter but has
-  no CPU reference-ray tests.
-- Both effects render on bounded proxy geometry; coordinate transforms must be
-  verified if the proxy is nonuniformly scaled or moved far from the origin.
-- The star texture is finite-resolution and can alias under extreme
-  magnification.
-
-## Diagnostics
-
-Expose:
-
-```text
-wormhole l and pL
-impact parameter and orbital-plane basis
-RK4 step count and escaped/capped state
-final exterior side and environment direction
-accretion volume radius and steering magnitude
-effective traveled distance
-disk band, noise, ramp coordinate, and local alpha
-accumulated alpha and remaining transmittance
-core-hit mask
-final bent background direction
-NaN/invalid-state mask
-```
-
-Add CPU reference rays for the wormhole before claiming physical parity, and a
-continuous disk-crossing variant before increasing accretion volume’s step size.

package/templates/skills/genex-threejs-screen-space-ambient-occlusion/SKILL.md

@@ -1,35 +0,0 @@
----
-name: genex-threejs-screen-space-ambient-occlusion
-description: Implement screen-space ambient occlusion for Genex Three.js games. Use for GTAO-style horizon sampling, bent normals, contact grounding, depth reconstruction, bilateral upsampling, halo diagnosis, and AO that supports readable form.
----
-
-# Genex Three.js Screen-Space Ambient Occlusion
-
-AO estimates missing ambient visibility. It must modulate indirect lighting, not repaint all scene color with a dark multiply.
-
-## Workflow
-
-1. Verify linear depth and view-space normals.
-2. Reconstruct view position consistently.
-3. Sample horizon visibility in a controlled radius.
-4. Estimate AO and optional bent normal.
-5. Denoise with depth/normal-aware filters.
-6. Apply to indirect diffuse and environment response.
-
-Read [references/ambient-occlusion.md](references/ambient-occlusion.md).
-
-## Failure conditions
-
-- direct light and emission are darkened;
-- radius is specified only in pixels;
-- foreground silhouettes cast thick screen-space halos;
-- depth discontinuities are blurred together;
-- AO remains strong at distances where its world radius is subpixel;
-- bent normals are treated as ordinary geometric normals;
-- the implementation claims temporal accumulation even though this path has none.
-
-## Routing boundary
-
-This skill owns GTAO gathering, bent normals, denoising, and AO application.
-Use `$genex-threejs-image-pipeline` only when its depth/normal buffers or pass order
-must be coordinated with other image-space systems.

package/templates/skills/genex-threejs-screen-space-ambient-occlusion/references/ambient-occlusion.md

@@ -1,441 +0,0 @@
-# GTAO and bent-normal pipeline
-
-Use this reference for a bounded-cost WebGPU/TSL ambient-visibility pass with half-resolution horizon integration, bent normals, bilateral reconstruction, and directional ambient tint.
-
-> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project. Either way the effect obeys the device tier (`$genex-threejs-adaptive-quality`): expensive passes are desktop-tier, and on WebGPU the per-target MSAA sample count is a runtime knob the governor may drive.
-
-## Contents
-
-1. Gather budget and depth convention
-2. World-radius projection and horizon integration
-3. Bent-normal encoding
-4. Bilateral reconstruction
-5. Indirect-light composite
-6. Implementation defects, adaptation, and diagnostics
-
-## 1. Preserve the actual budget
-
-The gather uses:
-
-```text
-resolution scale     0.5 × 0.5
-slices               2
-steps per side       4
-sides per slice      2
-depth taps           16 per half-resolution pixel
-target               RGBA16F
-RGB                   bent direction encoded to [0, 1]
-A                     scalar visibility, 1 = open
-```
-
-Half linear resolution means one quarter of full-resolution fragments.
-
-The implementation targets an approximately `2 ms` budget by combining:
-
-- half-resolution gather;
-- few slices;
-- interleaved-gradient-noise rotation;
-- direct UV marching;
-- one view-position reconstruction per tap;
-- sky early-outs in gather and composite.
-
-Do not increase slices first. Validate whether the bilateral pass and stable
-rotation already remove directional structure.
-
-## 2. Preserve the depth convention
-
-The implementation uses reversed depth:
-
-```text
-sky threshold          0.000001
-maximum reconstruction 0.999999
-```
-
-Sky is cleared to zero. Far terrain remains above the sky threshold.
-
-Gather:
-
-```text
-if rawDepth <= 1e-6:
-  output visibility = 1
-  output encoded bent = encoded view normal
-  skip all 16 taps
-```
-
-Composite clamps depth to `[0, 0.999999]` before linearization so sky
-neighbours do not create extreme view-Z values.
-
-Do not port these thresholds to a forward-depth target unchanged.
-
-## 3. Preserve world-radius projection
-
-Default controls:
-
-```text
-radius              0.5 m
-intensity           1.0
-power               1.6
-thickness           0.35 m in view Z
-bentNormalStrength  0.6
-```
-
-The horizontal projection scale is cached from:
-
-```text
-camera.projectionMatrix.elements[0]
-```
-
-and refreshed every frame.
-
-World radius becomes UV reach:
-
-```text
-radiusUv =
-  radius
-  * projectionScaleX
-  / max(-viewPosition.z, 0.0001)
-  * 0.5
-
-radiusUv = clamp(radiusUv, 0.004, 0.08)
-```
-
-This clamp prevents near surfaces searching half the screen and stops far
-surfaces collapsing to a useless footprint.
-
-Observed adaptation issue: only the X projection term is used, then one scalar
-radius is applied to both UV axes. At unusual aspect ratios or asymmetric
-projections, derive a `vec2` reach from both projection axes.
-
-## 4. Rotate two horizon slices per pixel
-
-For slice `i`:
-
-```text
-noise = interleavedGradientNoise(screenCoordinate)
-angle = (i / 2 + noise) * PI
-sliceDirection = (cos(angle), sin(angle))
-```
-
-The axis covers both positive and negative directions, so angles only span
-`PI`, not `2 * PI`.
-
-Step spacing:
-
-```text
-t = (stepIndex + noise + 0.5) / 4
-stepUv = sliceDirection * radiusUv * t
-```
-
-The shared noise rotates slices and jitters their radial positions.
-
-The pass has no temporal accumulation. Its stability depends on the
-noise being screen-stable and the full-resolution spatial composite.
-
-## 5. Keep horizon angle and distance falloff separate
-
-For each positive and negative sample:
-
-```text
-delta = sampleViewPosition - centerViewPosition
-distance = max(length(delta), 0.0001)
-falloff = saturate(1 - distance / max(radius, 0.0001))
-```
-
-Accept the sample only when:
-
-```text
-abs(delta.z) < thickness
-```
-
-Raw horizon cosine:
-
-```text
-cosine = dot(delta, viewDirection) / distance
-```
-
-Apply distance falloff by mixing toward fully open:
-
-```text
-horizon = mix(-1, cosine, falloff)
-maxHorizon = max(maxHorizon, horizon)
-```
-
-Do not multiply the cosine directly by falloff. Mixing toward `-1` weakens a
-distant occluder without changing the angle of a nearby one.
-
-Per slice:
-
-```text
-positiveAngle = acos(clamp(positiveHorizon, -1, 1))
-negativeAngle = acos(clamp(negativeHorizon, -1, 1))
-visibility += saturate((positiveAngle + negativeAngle) / PI)
-```
-
-Final scalar:
-
-```text
-visibility = visibility / 2
-visibility = visibility ^ power
-visibility = saturate(mix(1, visibility, intensity))
-```
-
-Disabling the pass sets intensity to zero; the gather still runs unless the
-owner removes or bypasses the node. If disabled cost matters, bypass the pass
-at pipeline construction or add an update/render gate.
-
-## 6. Treat the bent direction as an observed heuristic
-
-For accepted samples, the gather accumulates:
-
-```text
-bentDirection +=
-  normalize(delta)
-  * saturate(cosine * falloff)
-```
-
-Then:
-
-```text
-bent = normalize(
-  mix(
-    viewNormal,
-    normalize(viewDirection + bentDirection),
-    bentNormalStrength
-  )
-)
-```
-
-The output stores `bent * 0.5 + 0.5`.
-
-Important objective finding: the accumulated vectors point toward accepted
-sample positions. A physically derived bent normal normally points toward
-unoccluded directions, so do not assume this sign convention is correct in an
-adaptation.
-
-Required validation:
-
-```text
-place a flat receiver beside one vertical wall
-show geometric normal
-show decoded bent direction
-show environment sample direction
-verify the direction turns away from the blocked hemisphere
-```
-
-If it turns toward the wall, negate/rederive the directional accumulator
-before using it for environment lighting.
-
-## 7. Own gather rendering state
-
-`GtaoNode.updateBefore()`:
-
-1. saves/reset renderer state through `RendererUtils`;
-2. reads drawing-buffer dimensions;
-3. resizes the half-resolution target;
-4. refreshes projection scale;
-5. renders one fullscreen `QuadMesh`;
-6. restores renderer state.
-
-Dispose both the target and node material.
-
-Do not let a post node leak render target, viewport, or material state into the
-main pipeline.
-
-## 8. Upsample with the exact kernel
-
-The full-resolution composite gathers eight neighbours:
-
-```text
-left, right, up, down
-four diagonals
-center omitted
-```
-
-Each weight is depth-only:
-
-```text
-weight = exp(-abs(sampleViewZ - centerViewZ) / 0.5)
-```
-
-If total weight is above `0.01`, normalize the eight-sample sum. Otherwise use
-the center AO texel.
-
-This is an eight-neighbour `3×3` ring with the center skipped, not a cross.
-
-The rationale is to cover the four-pixel interleaved-gradient-noise repeat
-while sampling across half-resolution AO texels.
-
-Observed limitation: `screenTexelHint()` returns only:
-
-```text
-1 / screenWidth
-```
-
-and uses that scalar for both X and Y offsets. At non-square viewports the
-vertical step is wrong. Adapt as:
-
-```text
-texel = vec2(1 / width, 1 / height)
-```
-
-Observed limitation: the filter has no normal-similarity weight despite having
-the normal buffer available later in the composite. Thin foreground/background
-contacts may need:
-
-```text
-weight *= pow(saturate(dot(centerNormal, sampleNormal)), normalPower)
-```
-
-Add this only after confirming the depth-only kernel causes cross-edge leakage;
-normal buffers can be noisy at hard edges.
-
-## 9. Apply AO only to reconstructed indirect light
-
-Do not multiply final scene color by AO.
-
-It approximates indirect light:
-
-```text
-irradiance =
-  PMREM sampled along bent direction at texture level 1
-  or fallback cavity color (0.55, 0.62, 0.78)
-
-indirectEstimate =
-  albedo
-  * environmentIntensity
-  * irradiance
-
-indirect = min(indirectEstimate, sceneColor)
-direct = sceneColor - indirect
-```
-
-The clamp ensures direct light never becomes negative.
-
-Then:
-
-```text
-occludedIndirect = indirect * visibility
-
-deviation =
-  saturate(1 - dot(decodedBentView, geometricViewNormal))
-
-tintAmount =
-  deviation
-  * (1 - visibility)
-  * bentTintStrength
-
-bentTintStrength default = 0.35
-
-tintedIndirect =
-  mix(
-    occludedIndirect,
-    occludedIndirect * irradiance,
-    saturate(tintAmount)
-  )
-
-output = direct + tintedIndirect
-```
-
-This keeps direct sun and most specular response out of the AO multiply.
-
-The indirect reconstruction is still approximate because it works from a
-forward-shaded scene color and an albedo MRT. Specular energy can leak into
-the `direct` residual. Prefer a renderer-provided indirect-diffuse signal when
-available.
-
-## 10. Verify view/world transform semantics
-
-The composite decodes the bent direction in view space and calls:
-
-```text
-transformDirection(bentView, cameraViewMatrix)
-```
-
-while describing the result as view-to-world.
-
-Matrix-direction semantics in TSL are version-sensitive. Verify the installed
-Three.js behavior with axis probes:
-
-```text
-camera facing -Z:
-  view (0, 0, 1) maps to expected world direction
-
-camera rotated 90 degrees:
-  decoded bent direction rotates with the camera exactly once
-```
-
-Do not copy the matrix expression solely from the comment.
-
-## 11. Temporal behavior
-
-This pipeline has no motion vectors, history target, reprojection,
-neighborhood clamp, or disocclusion rejection.
-
-Do not describe it as temporally accumulated GTAO.
-
-If adding temporal accumulation:
-
-1. preserve raw half-resolution visibility and bent direction;
-2. add representative depth/normal validity;
-3. reproject with velocity;
-4. clamp scalar visibility to the current neighborhood;
-5. constrain bent history by angular deviation;
-6. reset on camera cuts and resolution changes.
-
-First verify whether the current stable-noise plus bilateral pass already meets
-the target. Temporal history adds ghosting risk to moving procedural geometry.
-
-## 12. Required diagnostics
-
-Expose:
-
-```text
-raw reversed depth and linear view Z
-sky classification
-view normal
-projected radius UV/pixels
-slice angle and jitter
-positive/negative horizon cosine
-thickness acceptance
-distance falloff
-visibility before power/intensity
-raw encoded and decoded bent direction
-one-sided-wall bent-direction test
-eight bilateral sample depths and weights
-X/Y texel offsets
-upsampled visibility
-albedo and environment irradiance
-indirect estimate before/after scene-color clamp
-direct residual
-tint deviation and amount
-final direct versus indirect contribution
-GPU time for gather and composite
-```
-
-Failure diagnosis:
-
-```text
-AO radius changes with distance incorrectly:
-  world radius was replaced by a fixed pixel radius
-
-far surfaces lose all contact:
-  projected radius was not clamped to a minimum
-
-thick silhouette halos:
-  thickness or depth-only bilateral weights cross discontinuities
-
-vertical blur differs from horizontal blur:
-  width-derived scalar texel size was used for Y
-
-bent tint points into walls:
-  the observed accumulator sign was accepted without a one-sided-wall test
-
-sunlit surfaces become gray:
-  visibility multiplied final scene color instead of reconstructed indirect
-
-disabled AO still costs the full pass:
-  intensity was set to zero without bypassing gather rendering
-
-camera rotation changes tint incorrectly:
-  view-to-world direction transform semantics were not verified
-```