@genex-ai/cli-demo 0.6.1 → 0.7.0

package/dist/index.js

@@ -788,32 +788,71 @@ async function deployGame(sshUrl, opts, log) {
     return false;
   }
   const gitDir = await fs6.mkdtemp(path7.join(os2.tmpdir(), "genex-deploy-"));
-  const gitEnv = { GIT_DIR: gitDir, GIT_WORK_TREE: siteDir };
+  const base = { GIT_DIR: gitDir };
+  const ident = {
+    GIT_AUTHOR_NAME: "genex",
+    GIT_AUTHOR_EMAIL: "agent@genex.local",
+    GIT_COMMITTER_NAME: "genex",
+    GIT_COMMITTER_EMAIL: "agent@genex.local"
+  };
+  const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
   try {
-    if ((await run("git", ["init", "-q"], gitEnv)).code !== 0) {
+    if ((await run("git", ["init", "-q"], base)).code !== 0) {
       log.warn("git init failed \u2014 the game was not pushed.");
       return false;
     }
-    await run("git", ["add", "-A"], gitEnv);
-    const tracked = await run("git", ["ls-files"], gitEnv);
-    if (/(^|\/)genex_key(\.pub)?$/m.test(tracked.out)) {
+    await fs6.writeFile(
+      path7.join(gitDir, "info", "exclude"),
+      ["node_modules/", "dist/", ".git/", KEY_NAME, `${KEY_NAME}.pub`, ".genex/", ""].join("\n")
+    );
+    const stage = async (workTree, indexName) => {
+      const env = { ...base, GIT_WORK_TREE: workTree, GIT_INDEX_FILE: path7.join(gitDir, indexName) };
+      await run("git", ["add", "-A"], env);
+      const tracked = await run("git", ["ls-files"], env);
+      if (/(^|\/)genex_key(\.pub)?$/m.test(tracked.out)) throw new Error("KEY_STAGED");
+      if (!tracked.out.trim()) return null;
+      const tree = (await run("git", ["write-tree"], env)).out.trim();
+      return tree || null;
+    };
+    const commitTree = async (tree, message) => (await run("git", ["commit-tree", tree, "-m", message], { ...base, ...ident })).out.trim();
+    let mainTree;
+    try {
+      mainTree = await stage(siteDir, "index-main");
+    } catch {
       log.error(`Refusing to deploy: ${KEY_NAME} is staged. Add it to .gitignore and retry.`);
       return false;
     }
-    const commit = await run(
-      "git",
-      ["-c", "user.email=agent@genex.local", "-c", "user.name=genex", "commit", "-q", "-m", "build"],
-      gitEnv
-    );
-    if (commit.code !== 0 && !/nothing to commit/i.test(commit.out + commit.err)) {
+    if (!mainTree || mainTree === EMPTY_TREE) {
       log.warn("Nothing to commit \u2014 the build produced no files.");
       return false;
     }
+    await run("git", ["update-ref", "refs/heads/main", await commitTree(mainTree, "build")], base);
+    let pushSource = false;
+    if (siteDir !== cwd) {
+      try {
+        const srcTree = await stage(cwd, "index-source");
+        if (srcTree && srcTree !== EMPTY_TREE) {
+          await run("git", ["update-ref", "refs/heads/source", await commitTree(srcTree, "source")], base);
+          pushSource = true;
+        }
+      } catch {
+        log.dim("  (Couldn't publish source for remixing \u2014 the deploy key was in the way.)");
+      }
+    }
     log.step("Pushing your game over SSH\u2026");
-    const push = await run("git", ["push", "-q", sshUrl, "+HEAD:main"], {
-      ...gitEnv,
-      GIT_SSH_COMMAND: `ssh -i ${keyPath} -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new`
-    });
+    const refspecs = ["+refs/heads/main:main"];
+    if (pushSource) refspecs.push("+refs/heads/source:source");
+    const push = await run(
+      "git",
+      ["push", "-q", ...pushSource ? ["--atomic"] : [], sshUrl, ...refspecs],
+      {
+        ...base,
+        // Quote the key path: git splits GIT_SSH_COMMAND with shell-like rules, so a
+        // project folder with a space (e.g. "fly drone") otherwise breaks the `-i`
+        // argument and ssh fails with "Could not resolve hostname …".
+        GIT_SSH_COMMAND: `ssh -i "${keyPath}" -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new`
+      }
+    );
     if (push.code === 0) {
       log.success("Pushed.");
       if (opts.playUrl) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/skills/genex-threejs-atmosphere-aerial-perspective/SKILL.md

@@ -5,26 +5,38 @@ description: Implement sky and aerial perspective for Genex Three.js games. Use
 
 # Genex Three.js Atmosphere And Aerial Perspective
 
-Atmosphere should explain scale and lighting without hiding gameplay. Add it
-after the base scene reads.
+Treat sky rendering and aerial perspective as two views of the same scattering model. They must share radii, density profiles, coefficients, sun direction, exposure scale, and coordinate transforms.
 
-Read [references/atmosphere.md](references/atmosphere.md) for sky, haze,
-lighting handoff, and transition checks.
+## Choose the implementation tier
 
-## Build order
+- Small scene with no orbital camera: analytic height/distance approximation.
+- Planetary ground-to-space camera: ray integration or precomputed LUTs.
+- Large geospatial world: LUTs plus world-to-planet transform, altitude correction, and depth-aware aerial perspective.
 
-1. Define world scale, camera altitude range, sun direction, horizon behavior,
-   and target devices.
-2. Build the sky model or sky gradient first.
-3. Add depth-based aerial perspective for terrain, buildings, and distant props.
-4. Connect sun color, ambient color, fog, and material response coherently.
-5. Add planetary shell or LUT paths only when the scale needs them.
-6. Expose debug views for transmittance, inscattering, depth, and no-atmosphere.
+Read [references/atmosphere.md](references/atmosphere.md)
+before implementation. It separates the LUT/ellipsoid architecture from
+dynamic integration and the shell/post handoff.
 
-## Rules
+## Required outputs
 
-- Keep gameplay silhouettes readable through haze.
-- Use one owner for sky color and sun direction.
-- Avoid stacking multiple fog systems with different assumptions.
-- Keep atmosphere quality adjustable for lower-end browsers.
-- Validate ground, mid-altitude, and high-altitude views.
+- sky radiance;
+- sun transmittance/color;
+- segment transmittance from camera to visible surface;
+- segment inscattering;
+- optional sky irradiance for materials;
+- explicit scale conversion between world units and atmosphere units.
+
+## Failure conditions
+
+- sky and terrain haze use different sun directions or coefficients;
+- the atmosphere is a uniformly transparent sphere;
+- camera altitude is measured in a local flat frame during orbital motion;
+- scene depth is treated as linear when it is not;
+- exposure is used to hide incorrect radiance scale;
+- atmosphere fades abruptly at shell entry.
+
+## Routing boundary
+
+This skill owns molecular/aerosol sky scattering and surface-segment aerial
+perspective. Use `$genex-threejs-volumetric-clouds` for weather-shaped cloud density,
+temporal cloud reconstruction, and cloud shadows.

package/templates/skills/genex-threejs-atmosphere-aerial-perspective/references/atmosphere.md

@@ -1,29 +1,213 @@
-# Atmosphere And Aerial Perspective
+# Atmosphere system contract
 
-Use this reference for outdoor scale and sky rendering.
+Use this contract to choose between a precomputed LUT/ellipsoid atmosphere and bounded dynamic integration while keeping sky, aerial perspective, surface lighting, and coordinate transforms coherent.
 
-## Sky
+## Contents
 
-- Keep sun direction explicit and shared with lighting.
-- Match sky color, ambient color, and direct light temperature.
-- Include sun or moon discs only when they help composition.
-- Keep stars or space backgrounds separated from atmospheric haze.
+- Shared parameter model
+- LUT atmosphere implementation LUT contract
+- Ellipsoid and depth ownership
+- planet-space implementation body profiles
+- planet-space implementation integration
+- Shell/post handoff
+- Implementation limits
+- Diagnostics
 
-## Aerial perspective
 
-- Apply haze by depth or world distance.
-- Preserve contrast for interactable objects and traversal edges.
-- Let distant terrain shift color before it loses all form.
-- Provide a debug toggle to remove atmosphere.
+## Shared parameter model
 
-## Planetary scale
+`LUT atmosphere implementation` keeps one atmosphere object for sky and aerial perspective.
+Earth-like defaults:
 
-- Use altitude-aware behavior for ground-to-space transitions.
-- Keep horizon curvature and shell radius consistent with planet radius.
-- Validate camera positions near ground, high altitude, and orbit.
+```text
+solar irradiance = (1.474, 1.8504, 1.91198)
+sun angular radius = 0.004675 rad
+bottom radius = 6,360,000 m
+top radius = 6,420,000 m
+Rayleigh scattering = (0.005802, 0.013558, 0.0331)
+Mie scattering = (0.003996, 0.003996, 0.003996)
+Mie extinction = (0.00444, 0.00444, 0.00444)
+Mie phase g = 0.8
+absorption extinction = (0.00065, 0.001881, 0.000085)
+ground albedo = 0.1
+```
 
-## Performance
+Density profiles are two-layer functions:
 
-- Prefer simple depth haze for small scenes.
-- Use precomputed or lower-resolution paths for expensive scattering.
-- Expose quality tiers and render-target costs.
+```text
+density(h) =
+  clamp(
+    expTerm * exp(expScale * h)
+    + linearTerm * h
+    + constantTerm,
+    0,
+    1
+  )
+```
+
+The default Rayleigh exponential scale is `-0.125`, Mie `-0.833333`.
+Absorption uses two linear layers centered around the ozone region rather than
+another ground-heavy exponential.
+
+One explicit meter-to-render-unit conversion is applied when parameters become
+uniforms. Preserve this single conversion boundary.
+
+## LUT atmosphere implementation LUT contract
+
+The sky material and aerial-perspective effect consume the same:
+
+```text
+transmittance texture
+scattering 3D texture
+irradiance texture
+optional single-Mie and higher-order scattering textures
+atmosphere parameters
+sun direction
+```
+
+The sky material reconstructs rays from inverse projection and inverse view
+matrices. It can render sun, moon, ground, and shadow-length integration.
+
+The aerial-perspective effect owns:
+
+```text
+camera projection/view and inverses
+camera world position
+depth
+optional normal buffer
+ellipsoid radii
+world-to-ECEF transform
+altitude correction
+geometric-error correction
+overlay/cloud shadow/light-mask inputs
+```
+
+Default composition enables segment transmittance and inscatter. Direct sun
+light and sky-light relighting are separate switches. Do not collapse these
+signals into one fog color.
+
+## Ellipsoid and depth ownership
+
+The geospatial path defaults to `Ellipsoid.WGS84` and can correct both
+camera altitude and geometry error. Atmosphere altitude is therefore not
+`worldPosition.y`.
+
+Required coordinate contract:
+
+```text
+world position
+  -> world-to-ECEF
+  -> ellipsoid-relative position
+  -> corrected altitude
+  -> LUT coordinates / segment scattering
+```
+
+The aerial effect declares depth ownership through its post-processing effect
+attribute. It also supports octahedral normals or normal reconstruction when
+lighting terms require orientation.
+
+## planet-space implementation body profiles
+
+planet-space implementation derives profiles by body kind and density. Terrestrial baseline:
+
+```text
+Rayleigh = (0.0058, 0.0135, 0.0331)
+Mie scattering = (0.0022, 0.0022, 0.0022)
+Mie extinction = (0.0032, 0.0032, 0.0032)
+Rayleigh scale height = lerp(7.2, 10.8, normalized density) km
+Mie scale height = lerp(0.9, 1.7, normalized density) km
+Mie g = 0.76
+ozone extinction = (0.00065, 0.001881, 0.000085)
+solar intensity = 13.8
+```
+
+Rocky bodies reduce scattering and remove ozone. Gas/ice giants use much
+larger scale heights and `g` around `0.80–0.82`.
+
+The implementation enforces:
+
+```text
+mieExtinction[channel] >= mieScattering[channel] + 0.0001
+g <= 0.92
+```
+
+This prevents negative absorption and unstable phase behavior.
+
+## planet-space implementation integration
+
+For each camera ray, planet-space implementation:
+
+1. intersects the top atmosphere sphere;
+2. clamps the segment against the surface sphere;
+3. marches `ATMOSPHERE_VIEW_SAMPLES`;
+4. accumulates Rayleigh, Mie, and triangular ozone depth;
+5. at every view sample, marches a sun segment with
+   `ATMOSPHERE_LIGHT_SAMPLES`;
+6. tests planet occlusion of the sun;
+7. evaluates Rayleigh and anisotropic Mie phase;
+8. returns in-scattered radiance and view transmittance.
+
+It adds an upper-Rayleigh exponential term and fades density over the final
+`24%` of atmosphere thickness to soften the shell edge.
+
+The compact path includes a small multiple-scattering approximation derived
+from `1 - transmittance`; it is not equivalent to the precomputed higher-order
+scattering available in `LUT atmosphere implementation`.
+
+## Shell/post handoff
+
+planet-space implementation renders a double-sided shell and a depth-aware post path from one
+profile. Runtime face-opacity weights avoid a hard front/back cull switch.
+
+The post blend is based on altitude above the atmosphere top:
+
+```text
+entry blend near = 140 km
+entry blend far = max(448 km, visual atmosphere height * 0.58)
+post blend = 1 - smoothstep(near, far, altitudeFromTop)
+```
+
+The post path applies only where scene depth represents a surface. The shell
+continues to own sky pixels and limb appearance.
+
+Preserve:
+
+```text
+one body center and radius
+one atmosphere profile
+one sun direction
+one unit conversion
+surface-depth classification
+continuous shell/post blend
+```
+
+## Implementation limits
+
+- planet-space implementation performs nested dynamic integration and is expensive compared with
+  LUT lookup.
+- Its atmosphere uses spheres, while `LUT atmosphere implementation` supports an ellipsoid
+  and ECEF correction.
+- planet-space implementation’s multiple-scattering term is an artistic approximation.
+- `LUT atmosphere implementation` is version-sensitive and built around its own
+  post-processing/coordinate utilities; adapt the architecture, not imports
+  blindly.
+- Do not combine LUT radiance and dynamic integrated radiance at full weight.
+  Choose ownership or a validated transition.
+
+## Diagnostics
+
+Expose:
+
+```text
+planet/ECEF coordinates and corrected altitude
+top and bottom intersections
+Rayleigh, Mie, and absorption density
+view and sun optical depth
+sun visibility
+segment transmittance
+single and multiple scattering
+sky versus surface depth classification
+shell front/back opacity
+post blend
+LUT coordinates and texture slices
+```

package/templates/skills/genex-threejs-bloom/SKILL.md

@@ -5,26 +5,37 @@ description: Implement controlled HDR bloom for Genex Three.js games. Use for se
 
 # Genex Three.js Bloom
 
-Bloom should reveal strong light and energy. It should not be the only reason an
-object reads.
+Bloom is a camera/display response to bright HDR signal. Establish scene exposure and emissive luminance before tuning blur.
 
-Read [references/bloom.md](references/bloom.md) for HDR signal setup,
-selective contribution, blur hierarchy, and diagnostics.
+## Workflow
 
-## Build order
+1. Inspect pre-tone-map luminance.
+2. Choose which scene values should bloom.
+3. Choose a single-node or dual selective-render ownership model.
+4. Calibrate threshold, radius, smooth width, and strength in HDR.
+5. Restore all substituted materials transactionally for selective passes.
+6. Composite before exposure/tone mapping.
+7. Validate base, contribution, and final views.
 
-1. Confirm the scene uses a consistent HDR signal and tone-mapping path.
-2. Define what is allowed to bloom and why.
-3. Extract bright or selected contribution.
-4. Blur at multiple scales.
-5. Composite with exposure-aware strength.
-6. Expose debug views for source, threshold mask, blur levels, final bloom, and
-   no-bloom baseline.
+Read [references/bloom.md](references/bloom.md) for the
+HDR ordering, dual selective-bloom transaction, compact emissive hierarchy,
+and the costs and limits of each ownership model.
 
-## Rules
+Apply the material substitution/restoration ownership pattern in the
+reference before adding selective bloom to a composed scene.
 
-- Keep emissive intensities scene-relative.
-- Avoid global bloom that washes out gameplay silhouettes.
-- Restore materials if using selective render passes.
-- Tune bloom with exposure and grading visible.
-- Validate readability with bloom disabled.
+## Failure conditions
+
+- bloom creates the only visible form of an effect;
+- all bright materials share one arbitrary emission multiplier;
+- threshold is tuned after tone mapping;
+- selective bloom requires mutating scene materials every frame without restoration guarantees;
+- transparent particles disappear from extraction because pass ownership is unclear;
+- bloom radius changes wildly with resolution;
+- highlights become gray because energy is clamped too early.
+
+## Routing boundary
+
+Use `$genex-threejs-exposure-color-grading` for metering, adaptation, tone mapping,
+and LUTs. Load `$genex-threejs-image-pipeline` only when bloom must be composed with
+several shared image-space systems.

package/templates/skills/genex-threejs-bloom/references/bloom.md

@@ -1,29 +1,185 @@
-# Bloom
+# HDR bloom systems
 
-Use this reference for controlled glow in Genex games.
+Use this reference to choose bloom ownership, signal order, selective contribution, and scene-relative emissive ranges without making bloom responsible for the underlying form.
 
-## Signal ownership
+## Contents
 
-- Establish whether bloom comes from HDR thresholding, selection layers, or both.
-- Keep tone mapping after bloom composition.
-- Keep exposure changes from unpredictably destroying bloom intent.
+- production WebGPU pipeline signal order
+- production WebGPU pipeline bloom controls
+- selective gallery pipeline selective ownership
+- Material substitution invariant
+- atlas-based renderer baseline
+- pooled VFX system HDR hierarchy
+- Implementation limits
+- Diagnostics
 
-## Selective bloom
 
-- Use layers, masks, or a separate render pass.
-- Restore material state after rendering a selected pass.
-- Avoid duplicate contribution from the same object.
-- Keep selected objects documented.
+## production WebGPU pipeline signal order
 
-## Blur levels
+The WebGPU pipeline owns bloom before exposure and render output:
 
-- Small radius: sharp energy and UI-like highlights.
-- Medium radius: glow around light sources.
-- Large radius: atmosphere or spectacle.
-- Keep each level inspectable.
+```text
+scene pass
+  -> optional GTAO composite
+  -> optional atmosphere
+  -> bloom node
+  -> sampled scene + bloom
+  -> eye-adaptation exposure
+  -> renderOutput / tone map
+  -> optional 3D LUT
+  -> optional FXAA
+```
 
-## Failure checks
+The render pipeline disables its automatic output color transform and assigns
+one final output node. Preserve this one-owner rule when adapting to current
+Three.js `RenderPipeline`.
 
-- Bloom cannot carry the silhouette alone.
-- White UI or text should not bloom unless intentionally emissive.
-- Dark scenes should not become foggy because bloom strength is too high.
+## production WebGPU pipeline bloom controls
+
+Bloom defaults:
+
+```text
+enabled = false
+strength = 0
+radius = 0.35
+threshold = 0.72
+smooth width = 0.08
+```
+
+The Three.js bloom node reads the HDR texture produced after atmosphere. Its
+strength becomes zero when disabled; radius, threshold, and smooth width remain
+independently updateable.
+
+This path does not implement a custom pyramid. Its contract is signal placement
+and parameter ownership around the renderer’s bloom node.
+Verify the installed Three.js node API before using the exact constructor or
+property names.
+
+## selective gallery pipeline selective ownership
+
+The gallery uses two separate selective bloom pipelines:
+
+```text
+neon layer -> neon UnrealBloomPass
+chandelier layer -> chandelier UnrealBloomPass
+base scene -> final composer
+
+final = base + neon bloom + chandelier bloom
+```
+
+Each bloom composer renders off-screen. A final shader adds both bloom textures
+to the base render, then an `OutputPass` performs display output.
+
+Separate ownership lets neon animation change strength/radius without forcing
+the chandelier glow to share the same threshold or spread.
+
+Chandelier bulbs, filaments, and glow meshes use unlit materials; bulb and
+filament materials set `toneMapped = false`. The pipeline therefore combines
+explicit layer membership with material-level HDR/display behavior.
+
+## Material substitution invariant
+
+For each selective pass, selective gallery pipeline traverses visible meshes and replaces every
+non-member material with one shared black material.
+
+Required transaction:
+
+```text
+set active bloom layer
+traverse visible meshes
+record { mesh, original material }
+replace non-members with shared black material
+try:
+  render bloom composer
+finally:
+  restore every recorded material
+  clear restoration list
+```
+
+Support material arrays by storing the complete original `mesh.material`
+value. Also toggle the high-detail and simplified
+chandelier representations so only the intended version contributes.
+
+The `finally` block is non-negotiable. Without it, a render error permanently
+blackens scene meshes.
+
+## atlas-based renderer baseline
+
+atlas-based renderer wraps `UnrealBloomPass` with:
+
+```text
+strength = 0.30
+radius = 0.50
+threshold = 0.05
+```
+
+Composer order:
+
+```text
+scene -> SSAO -> volumetrics -> bloom -> lens flare -> fog/color
+```
+
+This is a useful comparison, not the quality target. The threshold is very low
+and can bloom ordinary bright surfaces. The wrapper exposes only enabled,
+strength, and threshold, while radius stays at its constructor value.
+
+## pooled VFX system HDR hierarchy
+
+pooled VFX system assigns compact effect luminance before bloom:
+
+```text
+spark initial RGB multiplier = 80
+homing projectile = 30
+laser = 10
+```
+
+These values establish a material-level contribution hierarchy, but they do
+not define the bloom pass. Validate them against actual renderer exposure
+before reuse.
+
+Use the relationship, not the raw numbers:
+
+```text
+short spark flash
+  > projectile core
+  > persistent laser
+  > ordinary lit surface
+```
+
+## Implementation limits
+
+- selective gallery pipeline renders the scene multiple times for selective bloom. This is
+  acceptable for its bounded gallery but expensive for large scenes.
+- Temporary material substitution can trigger shader/program changes and must
+  account for newly added meshes.
+- The final selective gallery pipeline composite adds bloom textures directly; energy is
+  artistic, not physically conserved.
+- atlas-based renderer’s low threshold is not evidence for a general HDR calibration.
+- production WebGPU pipeline depends on version-sensitive Three.js bloom-node behavior.
+- pooled VFX system material multipliers are scene-relative and cannot be treated as
+  exposure-independent units.
+
+Prefer a dedicated contribution target when MRT/backend architecture supports
+it and the scene cannot afford multiple full renders. Validate that decision
+against the target scene’s measured cost and contribution masks.
+
+## Diagnostics
+
+Expose:
+
+```text
+HDR scene before bloom
+false-color luminance
+neon contribution
+chandelier contribution
+each bloom result
+base without bloom
+final composite
+active layer membership
+material restoration count and leak assertion
+transparent-emitter contribution
+bloom GPU time per render
+```
+
+Acceptance requires the base frame to retain form and material hierarchy with
+both bloom textures disabled.