Added xyla shader

SHADER_CONTRACT.md

@@ -57,6 +57,31 @@ float4 shadeVideo(ShaderContext context)
 
 With `autoReload` enabled in `config/runtime-host.json`, edits to shader source, manifests, and declared texture assets are picked up automatically.
 
+## Guidance For Shaders
+
+When generating a new shader package, prefer matching the existing runtime contract over copying code verbatim from Shadertoy, GLSL sandbox sites, or WebGL demos.
+
+Important rules:
+
+- Generate a complete package: `shaders/<id>/shader.json` and `shaders/<id>/shader.slang`.
+- Use `float4 shadeVideo(ShaderContext context)` unless the manifest explicitly sets a different `entryPoint`.
+- Do not create `mainImage`, `main`, `fragColor`, `iResolution`, `iTime`, `iChannel0`, or a fragment shader attribute layout. The runtime wrapper provides the real fragment entry point.
+- Replace Shadertoy `fragCoord` with `context.uv * context.outputResolution`.
+- Replace `iResolution.xy` with `context.outputResolution`.
+- Replace `iTime` with `context.time`.
+- Replace `iFrame` with `context.frameCount`.
+- Replace source-video `iChannel0` sampling with `sampleVideo(uv)` or `context.sourceColor`.
+- Use Slang/HLSL names and syntax: `float2`, `float3`, `float4`, `float2x2`, `lerp`, `frac`, `saturate`, and `mul(matrix, vector)`.
+- Do not use GLSL-only types/functions such as `vec2`, `vec3`, `vec4`, `mat2`, `mix`, `fract`, `mod`, `texture`, or `mainImage`.
+- Keep parameter IDs, texture IDs, font IDs, and function entry points as valid shader identifiers: letters, numbers, and underscores only, starting with a letter or underscore.
+- Add only controls that are actually used by the shader.
+- Prefer a small number of clear controls with conservative defaults.
+- Keep shaders deterministic unless randomness is an explicit feature. For stable pseudo-randomness, hash from `uv`, pixel coordinates, `frameCount`, or trigger values rather than using unavailable global state.
+- If adapting third-party code, include attribution and source URL in the manifest description when the license allows adaptation.
+- If the source license is unclear or incompatible, do not add the shader package.
+
+Before finishing, compile-check the shader through the runtime wrapper or launch the app and verify the shader appears without an error in the selector.
+
 ## Manifest Fields
 
 `shader.json` is the runtime-facing description of the shader.
@@ -460,6 +485,19 @@ See `shaders/temporal-ghost-trail/` and `shaders/temporal-low-fps/` for examples
 - Use `context.inputResolution` when sampling source video by input pixel size.
 - `sourceColor` and `sampleVideo` return RGBA values in normalized `0..1` range.
 - Prefer `saturate(color)` or explicit `clamp` before returning if your math can overshoot.
+- For generated calibration charts, test patterns, gradients, and exposure ramps, state whether patch values are linear-light, display-referred gamma encoded, Rec.709 encoded, or intentionally artistic.
+- For one-stop exposure patches, each patch should normally be `baseLevel * 2^patchIndex` before any display/tone encoding.
+- For Rec.709 OETF encoding, use:
+
+```slang
+float rec709Oetf(float linearLevel)
+{
+    float value = saturate(linearLevel);
+    if (value < 0.018)
+        return 4.5 * value;
+    return 1.099 * pow(value, 0.45) - 0.099;
+}
+```
 
 Pixel-size example:
 
@@ -468,6 +506,28 @@ float2 pixel = 1.0 / max(context.outputResolution, float2(1.0));
 float4 right = sampleVideo(context.uv + float2(pixel.x, 0.0));
 ```
 
+## Animation And Timing Notes
+
+- `context.time` is elapsed runtime time in seconds and is the default animation source for generative shaders.
+- `context.frameCount` increments once per rendered output frame and is useful when an effect must be frame-locked.
+- Avoid expensive CPU-like timing logic in the shader; animation should usually be a simple function of `context.time`, `context.frameCount`, trigger uniforms, or parameters.
+- If a shader appears to judder only while animated, first test whether freezing its time removes the issue. That usually separates animation cadence issues from rendering or transfer issues.
+- Do not add custom timer uniforms to the wrapper. Use the fields already in `ShaderContext`.
+
+## Performance Notes
+
+The app has to meet a fixed video frame cadence, so avoid shader code that only looks good in unconstrained browser demos.
+
+Guidelines:
+
+- Keep loops bounded with compile-time constants where possible.
+- Avoid very high per-pixel raymarch counts by default. If a heavy loop is needed, expose a quality/steps control with a safe default.
+- Prefer early exits only when they are simple; highly divergent branches can be expensive across a full frame.
+- Avoid repeated texture sampling in large loops unless the effect really needs it.
+- Use `context.outputResolution` carefully. A 1080p frame is over 2 million fragments; a tiny extra loop can become expensive.
+- The UI render time may measure CPU command submission rather than true GPU execution time, so visual frame issues can still be GPU-related even when reported render time is small.
+- Do not write debug files, allocate resources, or assume CPU-side work can happen from `shader.slang`. Shader code is GPU-only.
+
 ## Reload And Generated Files
 
 When a shader compiles, the runtime writes generated files under `runtime/shader_cache/`: