@genex-ai/cli-demo 0.6.0 → 0.6.2

package/templates/skills/genex-threejs-temporal-surfaces/references/temporal-surfaces.md

@@ -1,29 +1,207 @@
-# Temporal Surfaces
+# Touch-history frost accumulation
 
-Use this reference for persistent interaction effects.
+Use this reference for screen-space frost whose visible mask and refractive response depend on persistent touch history, reduced-resolution scene blur, static crystalline fields, and two-scale normals.
 
-## History buffer
+## Contents
 
-- Store history in one or more render targets.
-- Ping-pong read and write targets each update.
-- Keep UV or screen-space mapping explicit.
-- Reset on scene reload, resize, or level restart.
+- Exact pass graph
+- Render-target ownership
+- Persistent pointer state
+- Frost composite
+- Refraction output
+- Observed defects and required corrections
+- Diagnostic contract
 
-## Event writing
 
-- Convert pointer, collision, projectile, or gameplay events into stable
-  coordinates.
-- Write shape, strength, radius, and timestamp or age.
-- Avoid direct dependence on frame rate.
+## Exact pass graph
 
-## Decay and blur
+The frame graph owns these targets:
 
-- Apply decay before or after new input intentionally.
-- Use separable blur for large soft effects.
-- Keep low-resolution buffers from causing visible blockiness.
-- Expose unblurred and blurred views.
+| Target | Resolution | Lifetime | Purpose |
+| --- | --- | --- | --- |
+| root | display DPR | every frame | source scene |
+| vertical blur | `0.4` DPR | every frame | first separable blur axis |
+| horizontal blur | `0.4` DPR | every frame | broad blurred source |
+| frost composite | display DPR | every frame | scene, blur, structure, interaction |
+| pointer read/write | display DPR, half-float | persistent | touched/cleared history plus tilt |
+| frost noise | `0.4` DPR | once | coarse crystalline structure |
+| frozen noise | display DPR | once | dense frozen structure |
+| highlight noise | display DPR | once | highlight breakup |
 
-## Compositing
+Per-frame order is fixed:
 
-Temporal history can drive opacity, frost, wetness, scorch, refraction, glow, or
-normal distortion. Keep the visual role clear and provide a no-history fallback.
+```text
+root scene
+  -> vertical blur
+  -> horizontal blur
+  -> frost composite
+  -> pointer history write and swap
+  -> display output samples the new frost target
+```
+
+The frost pass therefore reads the pointer state from the previous completed
+frame. Preserve that one-frame history relationship unless changing it
+deliberately and validating the response.
+
+## Render-target ownership
+
+The single-target helper:
+
+1. stores `renderer.autoClear`;
+2. sets the requested clear mode;
+3. binds the target;
+4. renders;
+5. restores the default target;
+6. restores `autoClear`;
+7. disposes the target on owner teardown.
+
+The double-target helper writes only to `write`, exposes `read.texture` before
+the draw, swaps after the draw, and returns the new `read.texture`.
+
+```text
+read = completed state
+write = destination for this update
+render(write, sampling read)
+swap(read, write)
+```
+
+Both targets resize together. A production adaptation must also define whether
+resize preserves, resamples, or clears state. The hook resizes the
+targets but does not explicitly clear both histories.
+
+## Persistent pointer state
+
+The pointer target uses:
+
+```text
+R = accumulated interaction mask
+A = accumulated tilt-response mask
+G/B = duplicate R in the output
+```
+
+Defaults:
+
+```text
+decay per rendered frame = 0.002
+noise strength = 0.16
+frost-noise strength = 0.10
+mask strength = 0.30
+radius = 0.15 -> 0.17
+corner fade = 0.50 -> 0.60
+side fade = 0.00 -> 0.50
+```
+
+The update is:
+
+```text
+previous = max(previous - decay, 0)
+center = pointer * 0.5 + 0.5
+distance = aspect-corrected distance to center
+deposit = edge-masked noisy radial brush when touching
+Rnext = clamp(Rprevious + noisyDeposit, 0, 1)
+Anext = clamp(Aprevious + lower-noiseDeposit, 0, 1)
+```
+
+The side and corner masks keep a circular deposit from clipping abruptly at
+viewport boundaries. The alpha channel deliberately uses a less noisy brush so
+device tilt can react smoothly while the visible thaw/frost boundary stays
+irregular.
+
+## Frost composite
+
+The frost pass inverts pointer history:
+
+```text
+clearAmount = 1 - pointer.R
+```
+
+It combines three static structures:
+
+```text
+base structure = mix(frozenNoise, highlightNoise, 0.30)
+coarse frost = contrast(frostNoise * 1.70 + frostAmount, 1.60)
+mask = contrast(base structure + coarse frost * clearAmount, 1.80)
+```
+
+The scene treatment is coupled:
+
+```text
+blurMix = clamp(clearAmount * (mask + 0.30), 0, 1)
+scene = mix(sharpScene, blurredScene, blurMix)
+scene *= (0.90, 0.90, 1.03)
+saturation *= 1.20
+brightness *= 0.70
+```
+
+Frost color then mixes:
+
+```text
+thin tint  = (0.82, 0.86, 1.05)
+thick tint = (0.92, 0.96, 1.10)
+frost tint strength = 0.70
+highlight tint strength = 0.80
+```
+
+The composite alpha stores the structural frost mask before the pointer is
+applied. The output pass uses that alpha to gate normal-map refraction.
+
+## Refraction output
+
+The final pass samples two mirrored-repeat normal maps in screen coordinates:
+
+```text
+main scale size = 1200, strength = 0.30
+sub scale size = 350, strength = 2.0
+IOR = 1.31
+thickness = 1.0
+source inset = 0.17
+Fresnel strength = 0.80
+```
+
+The main map also produces a grayscale height weight for the sub-map. Device
+tilt rotates the view vector, with pointer alpha contributing up to `0.8`.
+Refraction is mixed only where both frost alpha and the inverse pointer mask
+permit it.
+
+## Observed defects and required corrections
+
+Do not preserve these weaknesses silently:
+
+- Pointer decay is per frame, not per second. Convert it to
+  `1 - exp(-rate * deltaSeconds)` or an equivalent time-based update.
+- The alpha-aware blur divides RGB and alpha by `sumW`. Fully transparent
+  neighborhoods can make `sumW == 0`; guard with an epsilon and define the
+  transparent result.
+- Blur alpha is accumulated with unmodified kernel weights but divided by the
+  alpha-weighted RGB denominator. Treat RGB normalization and alpha
+  normalization separately.
+- Pointer aspect is assigned from the low-resolution target although pointer
+  state is high resolution. The ratio is normally equal, but ownership should
+  use the actual pointer target.
+- Static targets opt out of auto-resize. A resize policy must regenerate or
+  remap them.
+- Screen-space state follows the viewport, not the depicted surface. Do not use
+  this representation for world footprints or object-bound paint.
+
+## Diagnostic contract
+
+Expose:
+
+```text
+root scene
+vertical blur
+horizontal blur
+each static noise target
+previous pointer R/A
+current deposit R/A
+next pointer R/A
+frost mask before pointer
+frost mask after pointer
+sharp/blur mix
+main and sub refraction offsets
+final without refraction
+final
+```
+
+Add pause and single-step controls. Verify decay at 30, 60, and 120 FPS after
+correcting it to time-based behavior.

package/templates/skills/genex-threejs-visual-validation/SKILL.md

@@ -5,28 +5,44 @@ description: Validate Genex Three.js game visuals in a real browser. Use for fix
 
 # Genex Three.js Visual Validation
 
-Validate the mechanism that creates the image, not just one attractive frame.
-For Genex games, also validate that the canvas runs and responds to input.
-
-Read [references/visual-validation.md](references/visual-validation.md) for the
-evidence checklist and rejection conditions.
+Evaluate the mechanism that creates the image. A beautiful hero screenshot can hide unstable fields, broken depth, seed failures, or post-processing dependence.
 
 ## Validation sequence
 
-1. Freeze seed, camera, time, quality tier, and viewport.
-2. Capture final image and no-post baseline.
+1. Freeze deterministic inputs.
+2. Capture the no-post baseline.
 3. Capture system-specific diagnostic views.
-4. Check near, design, and far camera distances.
-5. Sweep at least one alternate seed or parameter extreme.
-6. Check motion, pause/resume, resize, and input response.
-7. Record frame timing and render-target inventory when available.
-8. Keep written invariants and known compromises.
+4. Test the intended camera-distance envelope.
+5. Sweep representative seeds and parameter extremes.
+6. Test motion and temporal stability.
+7. Record image, geometry, memory, and timing budgets.
+8. Keep a small regression set tied to visual invariants.
+
+Read [references/visual-validation.md](references/visual-validation.md)
+for visual contracts, required inspection controls, mechanism-specific
+evidence, temporal checks, budgets, and explicit rejection criteria.
+
+## Required evidence
+
+- fixed camera and seed manifest;
+- final and no-post captures;
+- field/pass diagnostic mosaic;
+- near, design, and far camera views;
+- at least one stress seed;
+- frame-time and render-target inventory;
+- written invariants and known compromises.
 
 ## Failure conditions
 
-- Approval relies on one screenshot.
-- The scene only reads with bloom, haze, or grading enabled.
-- Random seeds are not reproducible.
-- Debug views are unavailable for generated fields or passes.
-- Browser canvas is blank, off-frame, unresponsive, or broken after resize.
-- Temporal artifacts are judged only from still images.
+- approval relies on a single frame;
+- post-processing cannot be disabled per pass;
+- random seeds are not reproducible;
+- GPU time is inferred only from CPU frame time;
+- temporal artifacts are judged from still images;
+- comparison thresholds ignore intentional stochastic pixels without stabilizing them.
+
+## Routing boundary
+
+This skill evaluates an implementation; it does not supply the implementation
+mechanism. Load the subject or image-effect skill first, then use this protocol
+to decide whether the result is acceptable.