@woosh/meep-engine 3.63.3 → 3.64.1

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_project.d.ts

@@ -6,9 +6,10 @@ export const PROBE_PROJECT_SETTINGS: WebGPUStruct;
  * Projection, rows (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.8): a thread a row of each listed probe's
  * radiance map, dispatched through `PROBE_DISPATCH_ROWS`. It sums the row's texels, new and kept, as
  * RGB radiance SH3, `L·Y(ω)·dω` over each texel's solid angle, so that `sh3_color_get_irradiance_at` gives
- * E; the row's rays this update, resolved and back faces; and how far the update's
- * samples fell from their means, with that sum's variance. One row of the probe's projection each, which
- * the probe's pass sums.
+ * E; the row's rays this update, resolved and back faces; and the row's part of L0 as the texels'
+ * estimators hold it, each texel by its solid angle: their short means less their means, their deviations
+ * squared (by the solid angle squared) and their short means, luminance. One row of the probe's projection
+ * each, which the probe's pass sums.
  *
  * @type {ComputeShader}
  */
@@ -25,21 +26,20 @@ export const shader_probe_clipmap_project_rows: ComputeShader;
  * radiance is nothing, so their share would read a probe inside a solid as alive. Such an update keeps
  * the probe's kind and its back-face share.
  *
- * **The probe's ray request** (§8.6): the rays its next guided update asks for, in `probe_requests`.
- * - After a probe's first update, the most: Enshrouded's new probe that asks for all it can have.
- * - When its light has moved, the most again. The update's change score sums its blended texels' falls
- *   from their means, luminance, each in its own deviation and held to `PROBE_CHANGE_SIGNIFICANCE` by
- *   accumulation, over the root of their count. A test texel by texel sees no change under a one-ray
- *   texel's own noise (measured: the estimator's inconsistency barely moves on a doubling); a sum of the
- *   falls unbounded is one bright sample's.
- * - The score is held to the probe's own: moved means past `PROBE_CHANGE_SIGNIFICANCE` of its running
- *   deviation, at least one, from its running mean, both over the estimator's variance window,
- *   `PROBE_VARIANCE_BLEND` an update however long since the last. A probe whose means sit off its samples
- *   (the estimator's own bias on texels lit by few rays) scores steadily off zero.
- * - Measured, Sponza on the 4090, the camera and the light still, 3,600 frames settled: of the probes
- *   past 64 updates, 4.2% asked for the most against a sum of the raw falls held to zero, 3.2% with each
- *   texel's fall bounded, and 1.1–1.3% held to their own statistics.
- * - Otherwise half what it asked for last, down to the fewest: a converged probe sips.
+ * **The probe's L0 estimator** (§8.6, §8.8): a multi-scale mean estimator (`chunk_multiscale_mean`) over the
+ * probe's whole light, L0, the solid-angle-weighted sum of its radiance texels. Its short and long means are
+ * L0 of the texels' short and long means, and its deviation the root of their deviations' sum, each by its
+ * solid angle squared, as the rows sum them; its inconsistency and blend reduction are the probe's own, in
+ * `probe_requests`. Its catch-up, the published estimator's, decides what the probe's next update takes:
+ * - **Blend**: every texel's long mean blends by at least the catch-up (`shader_probe_clipmap_accumulate`).
+ *   A one-ray texel's own test sees no change under its own noise; L0 pools every texel's evidence, so a
+ *   change in the probe's whole light, brighter or darker, is found where no texel can find it.
+ * - **Rays**: the next guided update asks for half what the last asked for, raised toward the most by the
+ *   catch-up, and never under the fewest: a probe whose light moved asks for more, a steady one sips.
+ * - After a probe's first update the most rays, a blend of nothing and the estimator seeded as a texel's is,
+ *   an inconsistency of one and no blend reduction: its slot's last owner's state is not its own.
+ * - An update whose texels hold no spread, L0's deviation nothing, leaves the estimator as it was and halves
+ *   the rays.
  *
  * @type {ComputeShader}
  */

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_probe_clipmap_project.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_project.js"],"names":[],"mappings":"AAmCA;;GAEG;AACH,qCAFU,YAAY,CAmBK;AAW3B;;;;;;;;;GASG;AACH,gDAFU,aAAa,CAsDpB;AAcH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,2CAFU,aAAa,CA8FpB;6BA3P0B,sCAAsC;8BAHrC,kCAAkC"}
+{"version":3,"file":"shader_probe_clipmap_project.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_project.js"],"names":[],"mappings":"AAgCA;;GAEG;AACH,qCAFU,YAAY,CAmBK;AAW3B;;;;;;;;;;GAUG;AACH,gDAFU,aAAa,CAyDpB;AAcH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,2CAFU,aAAa,CA0FpB;6BArP0B,sCAAsC;8BAHrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_project.js

@@ -1,3 +1,5 @@
+import { chunk_rgb_to_luminance } from "../../../shader/chunk/color/chunk_rgb_to_luminance.js";
+import { chunk_multiscale_mean } from "../../../shader/chunk/filter/chunk_multiscale_mean.js";
 import {
     chunk_octahedral_solid_angle
 } from "../../../shader/chunk/geometry/octahedron/chunk_octahedral_solid_angle.js";
@@ -26,12 +28,7 @@ import {
     PROBE_STATES_STORE_RESOURCE,
     PROBE_TRACE_READ_RESOURCE
 } from "./chunk_probe_clipmap.js";
-import {
-    PROBE_CHANGE_SIGNIFICANCE,
-    PROBE_RADIANCE_SAMPLES_LIMIT,
-    PROBE_THREAD_WORKGROUP_SIZE,
-    PROBE_VARIANCE_BLEND
-} from "./PROBE_CLIPMAP.js";
+import { PROBE_SHORT_BLEND, PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
 
 /**
  * @type {WebGPUStruct}
@@ -68,9 +65,10 @@ row_resources.createGroup()
  * Projection, rows (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.8): a thread a row of each listed probe's
  * radiance map, dispatched through `PROBE_DISPATCH_ROWS`. It sums the row's texels, new and kept, as
  * RGB radiance SH3, `L·Y(ω)·dω` over each texel's solid angle, so that `sh3_color_get_irradiance_at` gives
- * E; the row's rays this update, resolved and back faces; and how far the update's
- * samples fell from their means, with that sum's variance. One row of the probe's projection each, which
- * the probe's pass sums.
+ * E; the row's rays this update, resolved and back faces; and the row's part of L0 as the texels'
+ * estimators hold it, each texel by its solid angle: their short means less their means, their deviations
+ * squared (by the solid angle squared) and their short means, luminance. One row of the probe's projection
+ * each, which the probe's pass sums.
  *
  * @type {ComputeShader}
  */
@@ -106,13 +104,15 @@ fn main(
         let uv = (vec2<f32>(f32(x), f32(row)) + 0.5) * inverse;
         let solid_angle = octahedral_solid_angle(uv, inverse);
         let rays = probe_maps[maps + 2u * texels + i];
-        let change = unpack2x16float(probe_maps[maps + 3u * texels + settings.depth_resolution * settings.depth_resolution + i]);
+        // the texel's estimator: its short mean less its mean, and its deviation, luminance
+        let state = unpack2x16float(probe_maps[maps + 3u * texels + settings.depth_resolution * settings.depth_resolution + i]);
 
         sh3_color_accumulate(&row_sum.sh, light * solid_angle, sh3_basis_at(uv_octahedral_unit_decode(uv)));
         row_sum.resolved += rays & 0xFFFFu;
         row_sum.back_faces += rays >> 16u;
-        row_sum.change += change.x;
-        row_sum.blended += change.y;
+        row_sum.gap += state.x * solid_angle;
+        row_sum.variance += state.y * state.y * solid_angle * solid_angle;
+        row_sum.level += (rgb_to_luminance(light) + state.x) * solid_angle;
     }
 
     probe_projection[thread] = row_sum;
@@ -124,6 +124,7 @@ fn main(
             chunk_uv_octahedral_unit_decode,
             chunk_sh3_basis_at,
             chunk_sh3_color_accumulate,
+            chunk_rgb_to_luminance,
             PROBE_PROJECTION_ROW_STRUCT.declaration_chunk,
         ]),
 });
@@ -152,21 +153,20 @@ probe_resources.createGroup()
  * radiance is nothing, so their share would read a probe inside a solid as alive. Such an update keeps
  * the probe's kind and its back-face share.
  *
- * **The probe's ray request** (§8.6): the rays its next guided update asks for, in `probe_requests`.
- * - After a probe's first update, the most: Enshrouded's new probe that asks for all it can have.
- * - When its light has moved, the most again. The update's change score sums its blended texels' falls
- *   from their means, luminance, each in its own deviation and held to `PROBE_CHANGE_SIGNIFICANCE` by
- *   accumulation, over the root of their count. A test texel by texel sees no change under a one-ray
- *   texel's own noise (measured: the estimator's inconsistency barely moves on a doubling); a sum of the
- *   falls unbounded is one bright sample's.
- * - The score is held to the probe's own: moved means past `PROBE_CHANGE_SIGNIFICANCE` of its running
- *   deviation, at least one, from its running mean, both over the estimator's variance window,
- *   `PROBE_VARIANCE_BLEND` an update however long since the last. A probe whose means sit off its samples
- *   (the estimator's own bias on texels lit by few rays) scores steadily off zero.
- * - Measured, Sponza on the 4090, the camera and the light still, 3,600 frames settled: of the probes
- *   past 64 updates, 4.2% asked for the most against a sum of the raw falls held to zero, 3.2% with each
- *   texel's fall bounded, and 1.1–1.3% held to their own statistics.
- * - Otherwise half what it asked for last, down to the fewest: a converged probe sips.
+ * **The probe's L0 estimator** (§8.6, §8.8): a multi-scale mean estimator (`chunk_multiscale_mean`) over the
+ * probe's whole light, L0, the solid-angle-weighted sum of its radiance texels. Its short and long means are
+ * L0 of the texels' short and long means, and its deviation the root of their deviations' sum, each by its
+ * solid angle squared, as the rows sum them; its inconsistency and blend reduction are the probe's own, in
+ * `probe_requests`. Its catch-up, the published estimator's, decides what the probe's next update takes:
+ * - **Blend**: every texel's long mean blends by at least the catch-up (`shader_probe_clipmap_accumulate`).
+ *   A one-ray texel's own test sees no change under its own noise; L0 pools every texel's evidence, so a
+ *   change in the probe's whole light, brighter or darker, is found where no texel can find it.
+ * - **Rays**: the next guided update asks for half what the last asked for, raised toward the most by the
+ *   catch-up, and never under the fewest: a probe whose light moved asks for more, a steady one sips.
+ * - After a probe's first update the most rays, a blend of nothing and the estimator seeded as a texel's is,
+ *   an inconsistency of one and no blend reduction: its slot's last owner's state is not its own.
+ * - An update whose texels hold no spread, L0's deviation nothing, leaves the estimator as it was and halves
+ *   the rays.
  *
  * @type {ComputeShader}
  */
@@ -201,8 +201,9 @@ fn main(
 
         sum.resolved += part.resolved;
         sum.back_faces += part.back_faces;
-        sum.change += part.change;
-        sum.blended += part.blended;
+        sum.gap += part.gap;
+        sum.variance += part.variance;
+        sum.level += part.level;
     }
 
     let state = probe_states[slot].x;
@@ -227,28 +228,22 @@ fn main(
     probe_records[slot].sh = probe_record_sh_encode(sum.sh);
     probe_records[slot].traced_frame = settings.frame;
 
-    // the next guided update's rays: the most after the first update and whenever the light moved, else half
+    // the L0 estimator: the next update's blend and rays
     var request = probe_requests[slot];
 
     if (updates == 0u) {
-        // its slot's last owner's statistics are not its own
-        request = ${PROBE_REQUEST_STRUCT.make({ rays: "settings.rays_max", change_mean: "0.0", change_variance: "0.0", changes: "0u" })};
-    } else if (sum.blended > 0.0) {
-        let score = sum.change / sqrt(sum.blended);
-        let reach = ${PROBE_CHANGE_SIGNIFICANCE} * max(sqrt(request.change_variance), 1.0);
-        let moved = abs(score - request.change_mean) > reach;
-
-        // the score's running statistics, a running mean while young, then over the estimator's variance
-        // window; a score past their reach counts at it, so a change in the light does not become the probe's
-        // own spread, while a lasting shift of its own still does within a few windows
-        let held = clamp(score, request.change_mean - reach, request.change_mean + reach);
-        let blend = max(1.0 / f32(request.changes + 1u), ${PROBE_VARIANCE_BLEND});
-        let mean = mix(request.change_mean, held, blend);
-
-        request.change_variance = mix(request.change_variance, (held - request.change_mean) * (held - mean), blend);
-        request.change_mean = mean;
-        request.changes = min(request.changes + 1u, ${PROBE_RADIANCE_SAMPLES_LIMIT}u);
-        request.rays = select(max(settings.rays_min, request.rays >> 1u), settings.rays_max, moved);
+        // seeded: its slot's last owner's state is not its own
+        request = ${PROBE_REQUEST_STRUCT.make({ rays: "settings.rays_max", blend: "0.0", inconsistency: "1.0", reduction: "0.0" })};
+    } else if (sum.variance > 0.0) {
+        let deviation = sqrt(sum.variance);
+        let relative = abs(sum.gap) / deviation;
+        let inconsistency = mix(request.inconsistency, relative, ${PROBE_SHORT_BLEND});
+        let blend = saturate(multiscale_mean_catch_up(relative, inconsistency, request.reduction));
+
+        request.reduction = mix(request.reduction, multiscale_mean_blend_reduction(sum.level / deviation), MULTISCALE_MEAN_REDUCTION_BLEND);
+        request.inconsistency = inconsistency;
+        request.blend = blend;
+        request.rays = max(settings.rays_min, u32(round(mix(f32(request.rays >> 1u), f32(settings.rays_max), blend))));
     } else {
         request.rays = max(settings.rays_min, request.rays >> 1u);
     }
@@ -259,6 +254,7 @@ fn main(
             chunk_probe_clipmap,
             chunk_probe_clipmap_guide,
             chunk_folded_workgroup_index,
+            chunk_multiscale_mean,
             PROBE_PROJECTION_ROW_STRUCT.declaration_chunk,
             PROBE_REQUEST_STRUCT.declaration_chunk,
         ]),

package/src/shade/renderer/loader/gltf/tiny-gltf.d.ts

@@ -13,7 +13,7 @@ export class TinyGltf {
      * @readonly
      * @type {TextureFormat}
      */
-    static readonly "__#309@#UNCOMPRESSED_TARGET": TextureFormat;
+    static readonly "__#312@#UNCOMPRESSED_TARGET": TextureFormat;
     /**
      * @param {AssetManager} assetManager
      * @param {AssetRequestScope} [scope]

package/src/shade/renderer/postprocess/nss/NSS.d.ts

@@ -51,7 +51,7 @@ export class NSS {
      * @returns {number}
      */
     static recommended_jitter_sequence_size(upscale_ratio: number): number;
-    static "__#217@#preprocess_tensor_descriptor"(render_w: any, render_h: any): TextureResourceDescriptor;
+    static "__#220@#preprocess_tensor_descriptor"(render_w: any, render_h: any): TextureResourceDescriptor;
     /**
      * @param {GraphicsContext} graphics
      */

package/src/shade/renderer/shader/chunk/color/conversion/chunk_CRM_REC709_AP1.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Linear Rec.709 (D65) to AP1 (ACES white), Bradford-adapted, as Unreal's `WorkingColorSpace.ToAP1` for an sRGB
+ * working space. Row-major.
+ * @type {Float64Array}
+ */
+export const M3_REC709_TO_AP1: Float64Array;
+/**
+ * The inverse of {@link M3_REC709_TO_AP1}. Row-major.
+ * @type {Float64Array}
+ */
+export const M3_AP1_TO_REC709: Float64Array;
+/**
+ * - `CRM_FROM_REC709_TO_AP1` and `CRM_FROM_AP1_TO_REC709`: {@link M3_REC709_TO_AP1} and its inverse.
+ * - `AP1_LUMINANCE`: AP1's contribution of each channel to Y, the row Unreal calls `AP1_RGB2Y`.
+ *
+ * Derived from the two spaces' chromaticities, so neither matrix is a rounded transcription of the other.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_CRM_REC709_AP1: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_CRM_REC709_AP1.d.ts.map

package/src/shade/renderer/shader/chunk/color/conversion/chunk_CRM_REC709_AP1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_CRM_REC709_AP1.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/color/conversion/chunk_CRM_REC709_AP1.js"],"names":[],"mappings":"AAqBA;;;;GAIG;AACH,+BAFU,YAAY,CAE8B;AAIpD;;;GAGG;AACH,+BAFU,YAAY,CAE8B;AAYpD;;;;;;;GAOG;AACH,mCAFU,SAAS,CASjB;0BAzDwB,gCAAgC"}

package/src/shade/renderer/shader/chunk/color/conversion/chunk_CRM_REC709_AP1.js

@@ -0,0 +1,62 @@
+import { m3_chromatic_adaptation_bradford } from "../../../../../../core/color/xyz/m3_chromatic_adaptation_bradford.js";
+import { m3_rgb_to_xyz_from_primaries } from "../../../../../../core/color/xyz/m3_rgb_to_xyz_from_primaries.js";
+import { m3_invert } from "../../../../../../core/geom/mat3/m3_invert.js";
+import { m3_multiply } from "../../../../../../core/geom/mat3/m3_multiply.js";
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+const REC709_TO_XYZ = new Float64Array(9);
+m3_rgb_to_xyz_from_primaries(REC709_TO_XYZ, [0.640, 0.330, 0.300, 0.600, 0.150, 0.060], 0.3127, 0.3290);
+
+// ACES AP1 (ACEScg) primaries and the ACES white, S-2014-004
+const AP1_WHITE_X = 0.32168;
+const AP1_WHITE_Y = 0.33767;
+const AP1_TO_XYZ = new Float64Array(9);
+m3_rgb_to_xyz_from_primaries(AP1_TO_XYZ, [0.713, 0.293, 0.165, 0.830, 0.128, 0.044], AP1_WHITE_X, AP1_WHITE_Y);
+
+const XYZ_TO_AP1 = new Float64Array(9);
+m3_invert(XYZ_TO_AP1, AP1_TO_XYZ);
+
+const D65_TO_ACES_WHITE = new Float64Array(9);
+m3_chromatic_adaptation_bradford(D65_TO_ACES_WHITE, 0.3127, 0.3290, AP1_WHITE_X, AP1_WHITE_Y);
+
+/**
+ * Linear Rec.709 (D65) to AP1 (ACES white), Bradford-adapted, as Unreal's `WorkingColorSpace.ToAP1` for an sRGB
+ * working space. Row-major.
+ * @type {Float64Array}
+ */
+export const M3_REC709_TO_AP1 = new Float64Array(9);
+m3_multiply(M3_REC709_TO_AP1, D65_TO_ACES_WHITE, REC709_TO_XYZ);
+m3_multiply(M3_REC709_TO_AP1, XYZ_TO_AP1, M3_REC709_TO_AP1);
+
+/**
+ * The inverse of {@link M3_REC709_TO_AP1}. Row-major.
+ * @type {Float64Array}
+ */
+export const M3_AP1_TO_REC709 = new Float64Array(9);
+m3_invert(M3_AP1_TO_REC709, M3_REC709_TO_AP1);
+
+/**
+ * @param {Float64Array} m row-major
+ * @returns {string} a WGSL `mat3x3<f32>` constructor, column by column
+ */
+function wgsl_mat3(m) {
+    const column = c => `vec3<f32>(${m[c]}, ${m[3 + c]}, ${m[6 + c]})`;
+    return `mat3x3<f32>(${column(0)}, ${column(1)}, ${column(2)})`;
+}
+
+/**
+ * - `CRM_FROM_REC709_TO_AP1` and `CRM_FROM_AP1_TO_REC709`: {@link M3_REC709_TO_AP1} and its inverse.
+ * - `AP1_LUMINANCE`: AP1's contribution of each channel to Y, the row Unreal calls `AP1_RGB2Y`.
+ *
+ * Derived from the two spaces' chromaticities, so neither matrix is a rounded transcription of the other.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_CRM_REC709_AP1 = CodeChunk.from(
+    //language=WGSL
+    `
+const CRM_FROM_REC709_TO_AP1 = ${wgsl_mat3(M3_REC709_TO_AP1)};
+const CRM_FROM_AP1_TO_REC709 = ${wgsl_mat3(M3_AP1_TO_REC709)};
+const AP1_LUMINANCE = vec3<f32>(${AP1_TO_XYZ[3]}, ${AP1_TO_XYZ[4]}, ${AP1_TO_XYZ[5]});
+    `
+);

package/src/shade/renderer/shader/chunk/color/grade/chunk_color_grade.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `color_grade(scene, grade, keys)`: exposed scene-linear Rec.709 through a {@link ColorGrade}, white balance, then
+ * primaries, then hue curves, to Rec.709 again, not negative. `grade` is the grade's {@link COLOR_GRADE_STRUCT} and
+ * `keys` the curves' keyframes. See `ColorGrade` for what each stage does.
+ *
+ * Also defines each stage on its own: `color_grade_primaries(ap1, grade)` and
+ * `color_grade_hue_curves(color, counts, keys)`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_color_grade: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_color_grade.d.ts.map

package/src/shade/renderer/shader/chunk/color/grade/chunk_color_grade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_color_grade.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/color/grade/chunk_color_grade.js"],"names":[],"mappings":"AASA;;;;;;;;;GASG;AACH,gCAFU,SAAS,CA0HjB;0BAxIwB,gCAAgC"}

package/src/shade/renderer/shader/chunk/color/grade/chunk_color_grade.js

@@ -0,0 +1,140 @@
+import { ANIMATION_CURVE_KEYFRAME_STRUCT } from "../../../../animation/ANIMATION_CURVE_KEYFRAME_STRUCT.js";
+import { chunk_animation_curve_evaluate_keys } from "../../../../animation/chunk_animation_curve_evaluate_keys.js";
+import { COLOR_GRADE_STRUCT } from "../../../../deferred/tonemap/ColorGrade.js";
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { chunk_CRM_REC709_AP1 } from "../conversion/chunk_CRM_REC709_AP1.js";
+import { chunk_linear_srgb_to_oklab } from "../oklab/chunk_linear_srgb_to_oklab.js";
+import { chunk_oklab_compute_max_saturation } from "../oklab/chunk_oklab_compute_max_saturation.js";
+import { chunk_oklab_to_linear_srgb } from "../oklab/chunk_oklab_to_linear_srgb.js";
+
+/**
+ * `color_grade(scene, grade, keys)`: exposed scene-linear Rec.709 through a {@link ColorGrade}, white balance, then
+ * primaries, then hue curves, to Rec.709 again, not negative. `grade` is the grade's {@link COLOR_GRADE_STRUCT} and
+ * `keys` the curves' keyframes. See `ColorGrade` for what each stage does.
+ *
+ * Also defines each stage on its own: `color_grade_primaries(ap1, grade)` and
+ * `color_grade_hue_curves(color, counts, keys)`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_color_grade = CodeChunk.from(
+    //language=WGSL
+    `
+// Unreal's ColorCorrect: one zone's grade, in AP1
+fn color_grade_correct(
+    color: vec3<f32>,
+    saturation: vec3<f32>,
+    contrast: vec3<f32>,
+    gamma: vec3<f32>,
+    gain: vec3<f32>,
+    offset: vec3<f32>,
+) -> vec3<f32> {
+    let luma = dot(color, AP1_LUMINANCE);
+
+    var c = max(vec3<f32>(0.0), mix(vec3<f32>(luma), color, saturation));
+    c = pow(c * (1.0 / 0.18), contrast) * 0.18;
+    c = pow(c, 1.0 / gamma);
+
+    return c * gain + offset;
+}
+
+// Unreal's ColorCorrectAll: the three zones, blended by luma
+fn color_grade_primaries(ap1: vec3<f32>, grade: ${COLOR_GRADE_STRUCT.wgsl_ref}) -> vec3<f32> {
+    let luma = dot(ap1, AP1_LUMINANCE);
+
+    let shadows = color_grade_correct(
+        ap1,
+        grade.shadows_saturation.xyz, grade.shadows_contrast.xyz, grade.shadows_gamma.xyz,
+        grade.shadows_gain.xyz, grade.shadows_offset.xyz,
+    );
+    let midtones = color_grade_correct(
+        ap1,
+        grade.midtones_saturation.xyz, grade.midtones_contrast.xyz, grade.midtones_gamma.xyz,
+        grade.midtones_gain.xyz, grade.midtones_offset.xyz,
+    );
+    let highlights = color_grade_correct(
+        ap1,
+        grade.highlights_saturation.xyz, grade.highlights_contrast.xyz, grade.highlights_gamma.xyz,
+        grade.highlights_gain.xyz, grade.highlights_offset.xyz,
+    );
+
+    let weight_shadows = 1.0 - smoothstep(0.0, grade.zone_bounds.x, luma);
+    let weight_highlights = smoothstep(grade.zone_bounds.y, grade.zone_bounds.z, luma);
+    let weight_midtones = 1.0 - weight_shadows - weight_highlights;
+
+    return shadows * weight_shadows + midtones * weight_midtones + highlights * weight_highlights;
+}
+
+// hue shift, chroma scale and lightness against OkLCh hue; counts.xyz are the three curves' keys, in that order
+fn color_grade_hue_curves(
+    color: vec3<f32>,
+    counts: vec4<u32>,
+    keys: ptr<storage, array<${ANIMATION_CURVE_KEYFRAME_STRUCT.wgsl_ref}>, read>,
+) -> vec3<f32> {
+    if (all(counts.xyz == vec3<u32>(0u))) {
+        return color;
+    }
+
+    let lab = linear_srgb_to_oklab(color);
+    let chroma = length(lab.yz);
+
+    // a grey has no hue, and every edit below leaves it where it is
+    if (chroma <= 0.0 || lab.x <= 0.0) {
+        return color;
+    }
+
+    let direction = lab.yz / chroma;
+    let hue_signed = degrees(atan2(direction.y, direction.x));
+    let hue = select(hue_signed, hue_signed + 360.0, hue_signed < 0.0);
+
+    var shift = 0.0;
+    var scale = 1.0;
+    var stops = 0.0;
+
+    if (counts.x > 0u) {
+        shift = animation_curve_evaluate_keys(keys, 0u, counts.x, hue);
+    }
+    if (counts.y > 0u) {
+        scale = animation_curve_evaluate_keys(keys, counts.x, counts.y, hue);
+    }
+    if (counts.z > 0u) {
+        stops = animation_curve_evaluate_keys(keys, counts.x + counts.y, counts.z, hue);
+    }
+
+    // saturation relative to the Rec.709 gamut's edge at this hue: 0 for a grey, 1 on the edge
+    let relative = min(chroma / lab.x / oklab_compute_max_saturation(direction.x, direction.y), 1.0);
+
+    let angle = radians(shift);
+    let rotated = vec2<f32>(
+        direction.x * cos(angle) - direction.y * sin(angle),
+        direction.x * sin(angle) + direction.y * cos(angle),
+    );
+
+    // Oklab is the cube root of a linear map, so scaling L, a and b by cbrt(2^k) scales the light by exactly 2^k
+    let exposure = exp2(stops * relative / 3.0);
+
+    return oklab_to_linear_srgb(vec3<f32>(lab.x, rotated * (chroma * scale)) * exposure);
+}
+
+fn color_grade(
+    scene: vec3<f32>,
+    grade: ${COLOR_GRADE_STRUCT.wgsl_ref},
+    keys: ptr<storage, array<${ANIMATION_CURVE_KEYFRAME_STRUCT.wgsl_ref}>, read>,
+) -> vec3<f32> {
+    let white_balance = mat3x3<f32>(grade.white_balance_c0.xyz, grade.white_balance_c1.xyz, grade.white_balance_c2.xyz);
+
+    let ap1 = color_grade_primaries(CRM_FROM_REC709_TO_AP1 * (white_balance * scene), grade);
+
+    let graded = max(CRM_FROM_AP1_TO_REC709 * ap1, vec3<f32>(0.0));
+
+    return max(color_grade_hue_curves(graded, grade.curve_counts, keys), vec3<f32>(0.0));
+}
+    `, [
+        COLOR_GRADE_STRUCT.declaration_chunk,
+        chunk_animation_curve_evaluate_keys,
+        chunk_CRM_REC709_AP1,
+        chunk_linear_srgb_to_oklab,
+        chunk_oklab_to_linear_srgb,
+        chunk_oklab_compute_max_saturation,
+    ]
+);

package/src/shade/renderer/shader/chunk/color/oklab/chunk_oklab_compute_max_saturation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `oklab_compute_max_saturation(a, b)`: the largest saturation S = C / L in linear sRGB (Rec.709) at the hue of the
+ * unit Oklab direction (a, b), where the first channel reaches zero. Ottosson's polynomial and one Halley step; the
+ * WGSL twin of `core/color/oklab/compute_max_saturation.js`.
+ *
+ * @see https://bottosson.github.io/posts/gamutclipping/
+ * @type {CodeChunk}
+ */
+export const chunk_oklab_compute_max_saturation: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_oklab_compute_max_saturation.d.ts.map

package/src/shade/renderer/shader/chunk/color/oklab/chunk_oklab_compute_max_saturation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_oklab_compute_max_saturation.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/color/oklab/chunk_oklab_compute_max_saturation.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,iDAFU,SAAS,CAwDjB;0BAhEwB,gCAAgC"}

package/src/shade/renderer/shader/chunk/color/oklab/chunk_oklab_compute_max_saturation.js

@@ -0,0 +1,65 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * `oklab_compute_max_saturation(a, b)`: the largest saturation S = C / L in linear sRGB (Rec.709) at the hue of the
+ * unit Oklab direction (a, b), where the first channel reaches zero. Ottosson's polynomial and one Halley step; the
+ * WGSL twin of `core/color/oklab/compute_max_saturation.js`.
+ *
+ * @see https://bottosson.github.io/posts/gamutclipping/
+ * @type {CodeChunk}
+ */
+export const chunk_oklab_compute_max_saturation = CodeChunk.from(
+    //language=WGSL
+    `
+fn oklab_compute_max_saturation(a: f32, b: f32) -> f32 {
+    // the channel that reaches zero first selects the coefficients
+    var k0: f32; var k1: f32; var k2: f32; var k3: f32; var k4: f32;
+    var wl: f32; var wm: f32; var ws: f32;
+
+    if (-1.88170328 * a - 0.80936493 * b > 1.0) {
+        // red
+        k0 = 1.19086277; k1 = 1.76576728; k2 = 0.59662641; k3 = 0.75515197; k4 = 0.56771245;
+        wl = 4.0767416621; wm = -3.3077115913; ws = 0.2309699292;
+    } else if (1.81444104 * a - 1.19445276 * b > 1.0) {
+        // green
+        k0 = 0.73956515; k1 = -0.45954404; k2 = 0.08285427; k3 = 0.12541070; k4 = 0.14503204;
+        wl = -1.2684380046; wm = 2.6097574011; ws = -0.3413193965;
+    } else {
+        // blue
+        k0 = 1.35733652; k1 = -0.00915799; k2 = -1.15130210; k3 = -0.50559606; k4 = 0.00692167;
+        wl = -0.0041960863; wm = -0.7034186147; ws = 1.7076147010;
+    }
+
+    var s = k0 + k1 * a + k2 * b + k3 * a * a + k4 * a * b;
+
+    let k_l = 0.3963377774 * a + 0.2158037573 * b;
+    let k_m = -0.1055613458 * a - 0.0638541728 * b;
+    let k_s = -0.0894841775 * a - 1.2914855480 * b;
+
+    let l_ = 1.0 + s * k_l;
+    let m_ = 1.0 + s * k_m;
+    let s_ = 1.0 + s * k_s;
+
+    let l = l_ * l_ * l_;
+    let m = m_ * m_ * m_;
+    let s3 = s_ * s_ * s_;
+
+    let l_ds = 3.0 * k_l * l_ * l_;
+    let m_ds = 3.0 * k_m * m_ * m_;
+    let s_ds = 3.0 * k_s * s_ * s_;
+
+    let l_ds2 = 6.0 * k_l * k_l * l_;
+    let m_ds2 = 6.0 * k_m * k_m * m_;
+    let s_ds2 = 6.0 * k_s * k_s * s_;
+
+    let f = wl * l + wm * m + ws * s3;
+    let f1 = wl * l_ds + wm * m_ds + ws * s_ds;
+    let f2 = wl * l_ds2 + wm * m_ds2 + ws * s_ds2;
+
+    // one Halley step
+    s = s - f * f1 / (f1 * f1 - 0.5 * f * f2);
+
+    return s;
+}
+    `
+);

package/src/shade/renderer/shader/chunk/color/tonemap/chunk_bt2390_eetf.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The EETF of ITU-R BT.2390 (§5.4.1): maps a PQ signal mastered for a display reaching `source_peak` onto one
+ * reaching `target_peak`, all three PQ signals, with black at zero on both.
+ *
+ * The signal is first normalised to the source's range. Up to the knee, KS = 1.5 × maxLum − 0.5, it passes
+ * through; past it, a Hermite spline carries it to maxLum, the target's peak in the same normalisation, which the
+ * source's peak reaches with zero slope. The spline meets the identity at the knee with slope 1. A signal past
+ * `source_peak` is held at it. A target at or above the source passes every signal through.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bt2390_eetf: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_bt2390_eetf.d.ts.map

package/src/shade/renderer/shader/chunk/color/tonemap/chunk_bt2390_eetf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_bt2390_eetf.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/color/tonemap/chunk_bt2390_eetf.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,gCAFU,SAAS,CA0BjB;0BArCwB,gCAAgC"}

package/src/shade/renderer/shader/chunk/color/tonemap/chunk_bt2390_eetf.js

@@ -0,0 +1,38 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * The EETF of ITU-R BT.2390 (§5.4.1): maps a PQ signal mastered for a display reaching `source_peak` onto one
+ * reaching `target_peak`, all three PQ signals, with black at zero on both.
+ *
+ * The signal is first normalised to the source's range. Up to the knee, KS = 1.5 × maxLum − 0.5, it passes
+ * through; past it, a Hermite spline carries it to maxLum, the target's peak in the same normalisation, which the
+ * source's peak reaches with zero slope. The spline meets the identity at the knee with slope 1. A signal past
+ * `source_peak` is held at it. A target at or above the source passes every signal through.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bt2390_eetf = CodeChunk.from(
+    //language=WGSL
+    `
+fn bt2390_eetf(signal: f32, source_peak: f32, target_peak: f32) -> f32 {
+    let e1 = clamp(signal / source_peak, 0.0, 1.0);
+
+    let max_lum = target_peak / source_peak;
+    let ks = 1.5 * max_lum - 0.5;
+
+    if (e1 < ks || ks >= 1.0) {
+        return e1 * source_peak;
+    }
+
+    let t = (e1 - ks) / (1.0 - ks);
+    let t2 = t * t;
+    let t3 = t2 * t;
+
+    let e2 = (2.0 * t3 - 3.0 * t2 + 1.0) * ks
+        + (t3 - 2.0 * t2 + t) * (1.0 - ks)
+        + (-2.0 * t3 + 3.0 * t2) * max_lum;
+
+    return e2 * source_peak;
+}
+    `
+);