@woosh/meep-engine 3.55.0 → 3.57.0

package/src/shade/renderer/fluid/mac/shader_fluid_mac_advect_correct.js

@@ -1,245 +1,282 @@
-import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
-import { GRID_TILE_SIZE } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { chunk_grid3d_to_index } from "../../shader/chunk/grid/chunk_grid3d_to_index.js";
-import { FLUID_CASCADE_PARENT_STRUCT } from "../coupling/FLUID_CASCADE_PARENT_STRUCT.js";
-import { chunk_fluid_forcing_flags } from "../forcing/FLUID_FORCING.js";
-import { chunk_fluid_cascade_epilogue } from "../coupling/chunk_fluid_cascade_epilogue.js";
-import { chunk_v3_mac_face_pinned } from "./chunk_v3_mac_face_pinned.js";
-import {
-    chunk_fluid_mac_seam_forward,
-    chunk_fluid_mac_seam_solid,
-    chunk_fluid_mac_seam_source
-} from "./chunk_fluid_mac_seams.js";
-import { chunk_v3_mac_advect_correct } from "./chunk_v3_mac_advect_maccormack.js";
-import { FLUID_MAC_STEP_STRUCT } from "./FLUID_MAC_STEP_STRUCT.js";
-
-const resources = new ShaderResourceSetDescriptor();
-
-resources.createGroup()
-    .addUniform("step", FLUID_MAC_STEP_STRUCT)
-    .addUniform("parent", FLUID_CASCADE_PARENT_STRUCT)
-    .addTexture("source_u", "unfilterable-float", "3d")
-    .addTexture("source_v", "unfilterable-float", "3d")
-    .addTexture("source_w", "unfilterable-float", "3d")
-    .addTexture("forward_u", "unfilterable-float", "3d")
-    .addTexture("forward_v", "unfilterable-float", "3d")
-    .addTexture("forward_w", "unfilterable-float", "3d")
-    .addTexture("parent_u", "unfilterable-float", "3d")
-    .addTexture("parent_v", "unfilterable-float", "3d")
-    .addTexture("parent_w", "unfilterable-float", "3d")
-    .addTexture("ghost_u", "unfilterable-float", "3d")
-    .addTexture("ghost_v", "unfilterable-float", "3d")
-    .addTexture("ghost_w", "unfilterable-float", "3d")
-    .addStorageBuffer("solid", WebGPUArray.from(u32), false)
-    .addStorageBuffer("forcing", WebGPUArray.from(f32), false)
-    // the step's confinement force per cell (shader_fluid_mac_curl); read only with step.confinement_dt
-    .addStorageBuffer("confinement", WebGPUArray.from(f32), false)
-    .addStorageTexture("out_u", "r32float", "3d", "write-only")
-    .addStorageTexture("out_v", "r32float", "3d", "write-only")
-    .addStorageTexture("out_w", "r32float", "3d", "write-only");
-
-/*
- Each component's store is where a face's value is final. The per-face terms that follow the limiter
- (§8 pass 3) go between the correction and the store, in these three functions: the atmosphere
- identity, the vorticity confinement, the relaxation band and the deviation clamp
- (chunk_fluid_cascade_epilogue), then the tick's forcing, on every face that is not pinned; a pinned
- face keeps the wall's velocity, which the forcing wrote into the persistent faces before the step.
-
- The confinement of a face is half of each of its two cells' force, which the curl pass wrote
- (shader_fluid_mac_curl) with the half already taken: the CPU's scatter of a cell's force to its six
- faces, gathered. Without confinement step.confinement_dt is 0, no curl pass ran, and the uniform
- branch reads nothing.
-
- The forcing (shader_fluid_forcing_apply) is dense over the face lattices and written only on the
- bricks it ran: a face reads it only under FLUID_FORCED_FLAG of the cell that owns it, its own cell,
- or the window's last cell for a +boundary face.
-*/
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-// whether the forcing was written for the faces of a window-local cell
-fn fluid_mac_cell_forced(cell: vec3<i32>) -> bool {
-    let owner = min(cell, vec3<i32>(step.cells.size) - vec3<i32>(1));
-
-    return (solid[grid3d_to_index(vec3<u32>(owner), step.cells.size.xy)] & FLUID_FORCED_FLAG) != 0u;
-}
-
-fn fluid_mac_forcing_u(face: vec3<i32>) -> f32 {
-    if (!fluid_mac_cell_forced(face)) {
-        return 0.0;
-    }
-
-    return forcing[grid3d_to_index(vec3<u32>(face), step.faces_u.size.xy)];
-}
-
-fn fluid_mac_forcing_v(face: vec3<i32>) -> f32 {
-    if (!fluid_mac_cell_forced(face)) {
-        return 0.0;
-    }
-
-    let offset = step.faces_u.size.x * step.faces_u.size.y * step.faces_u.size.z;
-
-    return forcing[offset + grid3d_to_index(vec3<u32>(face), step.faces_v.size.xy)];
-}
-
-fn fluid_mac_forcing_w(face: vec3<i32>) -> f32 {
-    if (!fluid_mac_cell_forced(face)) {
-        return 0.0;
-    }
-
-    let offset = step.faces_u.size.x * step.faces_u.size.y * step.faces_u.size.z
-        + step.faces_v.size.x * step.faces_v.size.y * step.faces_v.size.z;
-
-    return forcing[offset + grid3d_to_index(vec3<u32>(face), step.faces_w.size.xy)];
-}
-
-// a window-local cell's confinement force along one axis, 0 beyond the window
-fn fluid_mac_cell_confinement(cell: vec3<i32>, component: u32) -> f32 {
-    let size = step.cells.size;
-
-    if (any(cell < vec3<i32>(0)) || any(cell >= vec3<i32>(size))) {
-        return 0.0;
-    }
-
-    return confinement[component * size.x * size.y * size.z + grid3d_to_index(vec3<u32>(cell), size.xy)];
-}
-
-fn fluid_mac_confinement_u(face: vec3<i32>) -> f32 {
-    if (step.confinement_dt == 0.0) {
-        return 0.0;
-    }
-
-    return fluid_mac_cell_confinement(face - vec3<i32>(1, 0, 0), 0u) + fluid_mac_cell_confinement(face, 0u);
-}
-
-fn fluid_mac_confinement_v(face: vec3<i32>) -> f32 {
-    if (step.confinement_dt == 0.0) {
-        return 0.0;
-    }
-
-    return fluid_mac_cell_confinement(face - vec3<i32>(0, 1, 0), 1u) + fluid_mac_cell_confinement(face, 1u);
-}
-
-fn fluid_mac_confinement_w(face: vec3<i32>) -> f32 {
-    if (step.confinement_dt == 0.0) {
-        return 0.0;
-    }
-
-    return fluid_mac_cell_confinement(face - vec3<i32>(0, 0, 1), 2u) + fluid_mac_cell_confinement(face, 2u);
-}
-
-fn fluid_mac_correct_store_u(face: vec3<i32>) {
-    var value = v3_mac_advect_correct_u(face, step.dt_over_h);
-
-    if (!v3_mac_face_pinned_u(face)) {
-        value = fluid_mac_epilogue_u(face, value, fluid_mac_confinement_u(face)) + fluid_mac_forcing_u(face);
-    }
-
-    textureStore(out_u, vec3<u32>(face), vec4<f32>(value, 0.0, 0.0, 0.0));
-}
-
-fn fluid_mac_correct_store_v(face: vec3<i32>) {
-    var value = v3_mac_advect_correct_v(face, step.dt_over_h);
-
-    if (!v3_mac_face_pinned_v(face)) {
-        value = fluid_mac_epilogue_v(face, value, fluid_mac_confinement_v(face)) + fluid_mac_forcing_v(face);
-    }
-
-    textureStore(out_v, vec3<u32>(face), vec4<f32>(value, 0.0, 0.0, 0.0));
-}
-
-fn fluid_mac_correct_store_w(face: vec3<i32>) {
-    var value = v3_mac_advect_correct_w(face, step.dt_over_h);
-
-    if (!v3_mac_face_pinned_w(face)) {
-        value = fluid_mac_epilogue_w(face, value, fluid_mac_confinement_w(face)) + fluid_mac_forcing_w(face);
-    }
-
-    textureStore(out_w, vec3<u32>(face), vec4<f32>(value, 0.0, 0.0, 0.0));
-}
-
-@compute @workgroup_size(${GRID_TILE_SIZE.join(', ')})
-fn main(@builtin(global_invocation_id) id: vec3<u32>) {
-    let cell = vec3<i32>(id);
-    let last = vec3<i32>(step.cells.size) - vec3<i32>(1);
-
-    // each cell's -x, -y and -z faces, and the +boundary face planes on the last tile along each axis
-    let u_end = select(1, 2, cell.x == last.x);
-    for (var dx = 0; dx < u_end; dx++) {
-        fluid_mac_correct_store_u(cell + vec3<i32>(dx, 0, 0));
-    }
-
-    let v_end = select(1, 2, cell.y == last.y);
-    for (var dy = 0; dy < v_end; dy++) {
-        fluid_mac_correct_store_v(cell + vec3<i32>(0, dy, 0));
-    }
-
-    let w_end = select(1, 2, cell.z == last.z);
-    for (var dz = 0; dz < w_end; dz++) {
-        fluid_mac_correct_store_w(cell + vec3<i32>(0, 0, dz));
-    }
-}
-`, [
-        chunk_fluid_mac_seam_source,
-        chunk_fluid_mac_seam_forward,
-        chunk_fluid_mac_seam_solid,
-        chunk_v3_mac_advect_correct,
-        chunk_v3_mac_face_pinned,
-        chunk_fluid_cascade_epilogue,
-        chunk_grid3d_to_index,
-        chunk_fluid_forcing_flags,
-    ]
-);
-
-body.addExtension(WebGPUExtensionType.Subgroups);
-
-/**
- * MacCormack's correct pass over one cascade window (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8,
- * pass 3): every face takes the predicted value corrected by half the round trip's error, limited to
- * the source's corners around its back-trace end, into the transient set the projection works on.
- * Then, on a face that is not pinned, the epilogue (`chunk_fluid_cascade_epilogue`): the atmosphere
- * identity from the step's start to its end, the vorticity confinement when `step.confinement_dt` is
- * not 0 (half of each of the face's two cells' force from `shader_fluid_mac_curl`), the relaxation band
- * toward the parent on rows 2..5 with `step.band`, and the deviation clamp about `v_far` at the step's
- * end; then the tick's forcing (§8
- * pass 4: the divergence is of `velocity_mid + forcing`), on a face whose owning cell carries
- * `FLUID_FORCED_FLAG`. A pinned face is the persistent face, the wall's velocity the forcing wrote.
- *
- * Dispatch and face ownership as {@link shader_fluid_mac_advect_predict}: `(nx / 8, ny / 8, nz / 4)`
- * groups of 8 × 8 × 4, a cell's −x, −y and −z faces, and the +boundary planes from the last tile.
- *
- * Bindings:
- * - `step`: {@link FLUID_MAC_STEP_STRUCT};
- * - `parent`: {@link FLUID_CASCADE_PARENT_STRUCT}, and `parent_u`, `parent_v`, `parent_w` the parent's
- *   persistent faces: beyond the window both the source and the predicted field are the parent's
- *   identity read at the step's start, as the step's ghosts `ghost_u`, `ghost_v`, `ghost_w` hold it
- *   and past them read again; the band reads the parent itself;
- * - `source_u`, `source_v`, `source_w`: the persistent velocity the predict pass read, toroidal
- *   through `step.faces_*`;
- * - `forward_u`, `forward_v`, `forward_w`: what the predict pass wrote, window-local;
- * - `solid`: the window-local solid flags, `array<u32>`, `FLUID_SOLID_FLAG` and `FLUID_FORCED_FLAG`;
- * - `forcing`: the tick's forcing, `array<f32>`, the u faces' lattice, then v's, then w's, each x
- *   fastest; read only under `FLUID_FORCED_FLAG`, so a step with no forcing binds anything;
- * - `confinement`: the curl pass's force, `array<f32>` of 3·N, x of every cell, then y, then z, each
- *   window-local x fastest; read only when `step.confinement_dt` is not 0, so a step without
- *   confinement binds anything;
- * - `out_u`, `out_v`, `out_w`: written, `r32float` 3-D storage textures, window-local.
- *
- * Reads a face: 9 carrier and 9 source texels, 9 predicted, 2 solid flags, 2 for the two trace ends
- * and up to 8 for clips, 2 more flags for the epilogue, 1 more and a forcing word for the forcing, 2
- * confinement words with confinement, and 8 parent texels on a band row. A cell: ~81 texels, ~21
- * flags, 6 confinement words with confinement, ~24 parent texels on the band's four
- * rows.
- *
- * @type {ComputeShader}
- */
-export const shader_fluid_mac_advect_correct = ComputeShader.from({
-    label: "Fluid / MAC advect correct",
-    body,
-    resources,
-});
+import { WebGPUExtensionType } from "../../../descriptor/WebGPUExtensionType.js";
+import { GRID_TILE_SIZE } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
+import { chunk_texture3d_trilinear_interpolate } from "../../shader/chunk/texture/sample/chunk_texture3d_trilinear_corners.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { chunk_grid3d_to_index } from "../../shader/chunk/grid/chunk_grid3d_to_index.js";
+import { FLUID_CASCADE_PARENT_STRUCT } from "../coupling/FLUID_CASCADE_PARENT_STRUCT.js";
+import { chunk_fluid_forcing_flags } from "../forcing/FLUID_FORCING.js";
+import { chunk_fluid_cascade_epilogue } from "../coupling/chunk_fluid_cascade_epilogue.js";
+import { chunk_v3_mac_clip_trace } from "./chunk_v3_mac_clip_trace.js";
+import { chunk_v3_mac_face_pinned } from "./chunk_v3_mac_face_pinned.js";
+import { chunk_v3_mac_limit } from "./chunk_v3_mac_lattice_corners.js";
+import {
+    chunk_fluid_mac_seam_forward,
+    chunk_fluid_mac_seam_solid,
+    chunk_fluid_mac_seam_source
+} from "./chunk_fluid_mac_seams.js";
+import { FLUID_MAC_STEP_STRUCT } from "./FLUID_MAC_STEP_STRUCT.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("step", FLUID_MAC_STEP_STRUCT)
+    .addUniform("parent", FLUID_CASCADE_PARENT_STRUCT)
+    .addTexture("source_u", "unfilterable-float", "3d")
+    .addTexture("source_v", "unfilterable-float", "3d")
+    .addTexture("source_w", "unfilterable-float", "3d")
+    .addTexture("forward_u", "unfilterable-float", "3d")
+    .addTexture("forward_v", "unfilterable-float", "3d")
+    .addTexture("forward_w", "unfilterable-float", "3d")
+    .addTexture("parent_u", "unfilterable-float", "3d")
+    .addTexture("parent_v", "unfilterable-float", "3d")
+    .addTexture("parent_w", "unfilterable-float", "3d")
+    .addTexture("ghost_u", "unfilterable-float", "3d")
+    .addTexture("ghost_v", "unfilterable-float", "3d")
+    .addTexture("ghost_w", "unfilterable-float", "3d")
+    .addStorageBuffer("solid", WebGPUArray.from(u32), false)
+    .addStorageBuffer("forcing", WebGPUArray.from(f32), false)
+    // the step's confinement force per cell (shader_fluid_mac_curl); read only with step.confinement_dt
+    .addStorageBuffer("confinement", WebGPUArray.from(f32), false)
+    .addStorageTexture("out_u", "r32float", "3d", "write-only")
+    .addStorageTexture("out_v", "r32float", "3d", "write-only")
+    .addStorageTexture("out_w", "r32float", "3d", "write-only");
+
+/*
+ Each component's store is where a face's value is final. The per-face terms that follow the limiter
+ (§8 pass 3) go between the correction and the store, in these three functions: the atmosphere
+ identity, the vorticity confinement, the relaxation band and the deviation clamp
+ (chunk_fluid_cascade_epilogue), then the tick's forcing, on every face that is not pinned; a pinned
+ face keeps the wall's velocity, which the forcing wrote into the persistent faces before the step.
+
+ The confinement of a face is half of each of its two cells' force, which the curl pass wrote
+ (shader_fluid_mac_curl) with the half already taken: the CPU's scatter of a cell's force to its six
+ faces, gathered. Without confinement step.confinement_dt is 0, no curl pass ran, and the uniform
+ branch reads nothing.
+
+ The forcing (shader_fluid_forcing_apply) is dense over the face lattices and written only on the
+ bricks it ran: a face reads it only under FLUID_FORCED_FLAG of the cell that owns it, its own cell,
+ or the window's last cell for a +boundary face.
+*/
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+// whether the forcing was written for the faces of a window-local cell
+fn fluid_mac_cell_forced(cell: vec3<i32>) -> bool {
+    let owner = min(cell, vec3<i32>(step.cells.size) - vec3<i32>(1));
+
+    return (solid[grid3d_to_index(vec3<u32>(owner), step.cells.size.xy)] & FLUID_FORCED_FLAG) != 0u;
+}
+
+fn fluid_mac_forcing_u(face: vec3<i32>) -> f32 {
+    if (!fluid_mac_cell_forced(face)) {
+        return 0.0;
+    }
+
+    return forcing[grid3d_to_index(vec3<u32>(face), step.faces_u.size.xy)];
+}
+
+fn fluid_mac_forcing_v(face: vec3<i32>) -> f32 {
+    if (!fluid_mac_cell_forced(face)) {
+        return 0.0;
+    }
+
+    let offset = step.faces_u.size.x * step.faces_u.size.y * step.faces_u.size.z;
+
+    return forcing[offset + grid3d_to_index(vec3<u32>(face), step.faces_v.size.xy)];
+}
+
+fn fluid_mac_forcing_w(face: vec3<i32>) -> f32 {
+    if (!fluid_mac_cell_forced(face)) {
+        return 0.0;
+    }
+
+    let offset = step.faces_u.size.x * step.faces_u.size.y * step.faces_u.size.z
+        + step.faces_v.size.x * step.faces_v.size.y * step.faces_v.size.z;
+
+    return forcing[offset + grid3d_to_index(vec3<u32>(face), step.faces_w.size.xy)];
+}
+
+// a window-local cell's confinement force along one axis, 0 beyond the window
+fn fluid_mac_cell_confinement(cell: vec3<i32>, component: u32) -> f32 {
+    let size = step.cells.size;
+
+    if (any(cell < vec3<i32>(0)) || any(cell >= vec3<i32>(size))) {
+        return 0.0;
+    }
+
+    return confinement[component * size.x * size.y * size.z + grid3d_to_index(vec3<u32>(cell), size.xy)];
+}
+
+fn fluid_mac_confinement_u(face: vec3<i32>) -> f32 {
+    if (step.confinement_dt == 0.0) {
+        return 0.0;
+    }
+
+    return fluid_mac_cell_confinement(face - vec3<i32>(1, 0, 0), 0u) + fluid_mac_cell_confinement(face, 0u);
+}
+
+fn fluid_mac_confinement_v(face: vec3<i32>) -> f32 {
+    if (step.confinement_dt == 0.0) {
+        return 0.0;
+    }
+
+    return fluid_mac_cell_confinement(face - vec3<i32>(0, 1, 0), 1u) + fluid_mac_cell_confinement(face, 1u);
+}
+
+fn fluid_mac_confinement_w(face: vec3<i32>) -> f32 {
+    if (step.confinement_dt == 0.0) {
+        return 0.0;
+    }
+
+    return fluid_mac_cell_confinement(face - vec3<i32>(0, 0, 1), 2u) + fluid_mac_cell_confinement(face, 2u);
+}
+
+fn fluid_mac_correct_store_u(face: vec3<i32>) {
+    let source = textureLoad(source_u, grid_tile_window_storage(face, step.faces_u.corner_storage, step.faces_u.period), 0).r;
+
+    if (v3_mac_face_pinned_u(face)) {
+        textureStore(out_u, vec3<u32>(face), vec4<f32>(source, 0.0, 0.0, 0.0));
+        return;
+    }
+
+    let start = vec3<f32>(face) - vec3<f32>(0.5, 0.0, 0.0);
+    let travel = fluid_mac_face_carrier_u(face, source) * step.dt_over_h;
+    let back = v3_mac_clip_trace(start, start - travel);
+    let ahead = v3_mac_clip_trace(start, start + travel);
+
+    let backward = texture3d_trilinear_interpolate(fluid_mac_forward_corners_u(ahead + vec3<f32>(0.5, 0.0, 0.0)));
+    let corrected = textureLoad(forward_u, vec3<u32>(face), 0).r + 0.5 * (source - backward);
+    let limited = v3_mac_limit(corrected, fluid_mac_source_corners_u(back + vec3<f32>(0.5, 0.0, 0.0)));
+    let value = fluid_mac_epilogue_u(face, limited, fluid_mac_confinement_u(face)) + fluid_mac_forcing_u(face);
+
+    textureStore(out_u, vec3<u32>(face), vec4<f32>(value, 0.0, 0.0, 0.0));
+}
+
+fn fluid_mac_correct_store_v(face: vec3<i32>) {
+    let source = textureLoad(source_v, grid_tile_window_storage(face, step.faces_v.corner_storage, step.faces_v.period), 0).r;
+
+    if (v3_mac_face_pinned_v(face)) {
+        textureStore(out_v, vec3<u32>(face), vec4<f32>(source, 0.0, 0.0, 0.0));
+        return;
+    }
+
+    let start = vec3<f32>(face) - vec3<f32>(0.0, 0.5, 0.0);
+    let travel = fluid_mac_face_carrier_v(face, source) * step.dt_over_h;
+    let back = v3_mac_clip_trace(start, start - travel);
+    let ahead = v3_mac_clip_trace(start, start + travel);
+
+    let backward = texture3d_trilinear_interpolate(fluid_mac_forward_corners_v(ahead + vec3<f32>(0.0, 0.5, 0.0)));
+    let corrected = textureLoad(forward_v, vec3<u32>(face), 0).r + 0.5 * (source - backward);
+    let limited = v3_mac_limit(corrected, fluid_mac_source_corners_v(back + vec3<f32>(0.0, 0.5, 0.0)));
+    let value = fluid_mac_epilogue_v(face, limited, fluid_mac_confinement_v(face)) + fluid_mac_forcing_v(face);
+
+    textureStore(out_v, vec3<u32>(face), vec4<f32>(value, 0.0, 0.0, 0.0));
+}
+
+fn fluid_mac_correct_store_w(face: vec3<i32>) {
+    let source = textureLoad(source_w, grid_tile_window_storage(face, step.faces_w.corner_storage, step.faces_w.period), 0).r;
+
+    if (v3_mac_face_pinned_w(face)) {
+        textureStore(out_w, vec3<u32>(face), vec4<f32>(source, 0.0, 0.0, 0.0));
+        return;
+    }
+
+    let start = vec3<f32>(face) - vec3<f32>(0.0, 0.0, 0.5);
+    let travel = fluid_mac_face_carrier_w(face, source) * step.dt_over_h;
+    let back = v3_mac_clip_trace(start, start - travel);
+    let ahead = v3_mac_clip_trace(start, start + travel);
+
+    let backward = texture3d_trilinear_interpolate(fluid_mac_forward_corners_w(ahead + vec3<f32>(0.0, 0.0, 0.5)));
+    let corrected = textureLoad(forward_w, vec3<u32>(face), 0).r + 0.5 * (source - backward);
+    let limited = v3_mac_limit(corrected, fluid_mac_source_corners_w(back + vec3<f32>(0.0, 0.0, 0.5)));
+    let value = fluid_mac_epilogue_w(face, limited, fluid_mac_confinement_w(face)) + fluid_mac_forcing_w(face);
+
+    textureStore(out_w, vec3<u32>(face), vec4<f32>(value, 0.0, 0.0, 0.0));
+}
+
+@compute @workgroup_size(${GRID_TILE_SIZE.join(', ')})
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    let cell = vec3<i32>(id);
+    let last = vec3<i32>(step.cells.size) - vec3<i32>(1);
+
+    // each cell's -x, -y and -z faces
+    fluid_mac_correct_store_u(cell);
+    fluid_mac_correct_store_v(cell);
+    fluid_mac_correct_store_w(cell);
+
+    // the +boundary face planes, owned by the last tile along each axis
+    if (cell.x == last.x) {
+        fluid_mac_correct_store_u(cell + vec3<i32>(1, 0, 0));
+    }
+    if (cell.y == last.y) {
+        fluid_mac_correct_store_v(cell + vec3<i32>(0, 1, 0));
+    }
+    if (cell.z == last.z) {
+        fluid_mac_correct_store_w(cell + vec3<i32>(0, 0, 1));
+    }
+}
+`, [
+        chunk_fluid_mac_seam_source,
+        chunk_fluid_mac_seam_forward,
+        chunk_fluid_mac_seam_solid,
+        chunk_v3_mac_face_pinned,
+        chunk_v3_mac_clip_trace,
+        chunk_v3_mac_limit,
+        chunk_texture3d_trilinear_interpolate,
+        chunk_fluid_cascade_epilogue,
+        chunk_grid3d_to_index,
+        chunk_fluid_forcing_flags,
+    ]
+);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * MacCormack's correct pass over one cascade window (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8,
+ * pass 3): every face takes the predicted value corrected by half the round trip's error, limited to
+ * the source's corners around its back-trace end, into the transient set the projection works on.
+ * Then, on a face that is not pinned, the epilogue (`chunk_fluid_cascade_epilogue`): the atmosphere
+ * identity from the step's start to its end, the vorticity confinement when `step.confinement_dt` is
+ * not 0 (half of each of the face's two cells' force from `shader_fluid_mac_curl`), the relaxation band
+ * toward the parent on rows 2..5 with `step.band`, and the deviation clamp about `v_far` at the step's
+ * end; then the tick's forcing (§8
+ * pass 4: the divergence is of `velocity_mid + forcing`), on a face whose owning cell carries
+ * `FLUID_FORCED_FLAG`. A pinned face is the persistent face, the wall's velocity the forcing wrote.
+ *
+ * Dispatch and face ownership as {@link shader_fluid_mac_advect_predict}: `(nx / 8, ny / 8, nz / 4)`
+ * groups of 8 × 8 × 4, a cell's −x, −y and −z faces, and the +boundary planes from the last tile.
+ *
+ * Bindings:
+ * - `step`: {@link FLUID_MAC_STEP_STRUCT};
+ * - `parent`: {@link FLUID_CASCADE_PARENT_STRUCT}, and `parent_u`, `parent_v`, `parent_w` the parent's
+ *   persistent faces: beyond the window both the source and the predicted field are the parent's
+ *   identity read at the step's start, as the step's ghosts `ghost_u`, `ghost_v`, `ghost_w` hold it;
+ *   the band reads the parent itself;
+ * - `source_u`, `source_v`, `source_w`: the persistent velocity the predict pass read, toroidal
+ *   through `step.faces_*`;
+ * - `forward_u`, `forward_v`, `forward_w`: what the predict pass wrote, window-local;
+ * - `solid`: the window-local solid flags, `array<u32>`, `FLUID_SOLID_FLAG` and `FLUID_FORCED_FLAG`;
+ * - `forcing`: the tick's forcing, `array<f32>`, the u faces' lattice, then v's, then w's, each x
+ *   fastest; read only under `FLUID_FORCED_FLAG`, so a step with no forcing binds anything;
+ * - `confinement`: the curl pass's force, `array<f32>` of 3·N, x of every cell, then y, then z, each
+ *   window-local x fastest; read only when `step.confinement_dt` is not 0, so a step without
+ *   confinement binds anything;
+ * - `out_u`, `out_v`, `out_w`: written, `r32float` 3-D storage textures, window-local.
+ *
+ * Reads a face: 9 carrier and 9 source texels, 9 predicted, 2 solid flags, 2 for the two trace ends
+ * and up to 8 for clips, 2 more flags for the epilogue, 1 more and a forcing word for the forcing, 2
+ * confinement words with confinement, and 8 parent texels on a band row. A cell: ~81 texels, ~21
+ * flags, 6 confinement words with confinement, ~24 parent texels on the band's four
+ * rows.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_mac_advect_correct = ComputeShader.from({
+    label: "Fluid / MAC advect correct",
+    body,
+    resources,
+});

package/src/shade/renderer/fluid/mac/shader_fluid_mac_advect_predict.d.ts

@@ -9,8 +9,6 @@
  *
  * Bindings:
  * - `step`: {@link FLUID_MAC_STEP_STRUCT};
- * - `parent`: {@link FLUID_CASCADE_PARENT_STRUCT}, and `parent_u`, `parent_v`, `parent_w` the parent's
- *   persistent faces, read beyond the step's ghosts;
  * - `ghost_u`, `ghost_v`, `ghost_w`: the step's velocity ghosts, the parent's read past the window;
  * - `source_u`, `source_v`, `source_w`: the persistent velocity, `r32float` 3-D textures read with
  *   `textureLoad`, toroidal through `step.faces_*`. It is both the field advected and the carrier;
@@ -18,7 +16,7 @@
  * - `forward_u`, `forward_v`, `forward_w`: written, `r32float` 3-D storage textures, window-local.
  *
  * Beyond the window, velocity is the parent's identity read at the step's start (the far field's for
- * the coarsest cascade) and cells are fluid.
+ * the coarsest cascade), held by the ghost shell, and cells are fluid.
  *
  * Reads a face: 9 carrier and 8 source texels (a manual trilinear tap in f32), 2 solid flags, 1 more
  * for the trace's end and up to 4 for a clip; a pinned face reads 2 flags and its own texel. A cell:

package/src/shade/renderer/fluid/mac/shader_fluid_mac_advect_predict.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_fluid_mac_advect_predict.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/mac/shader_fluid_mac_advect_predict.js"],"names":[],"mappings":"AA4EA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,8CAFU,aAAa,CAMpB;8BA1G2B,+BAA+B"}
+{"version":3,"file":"shader_fluid_mac_advect_predict.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/mac/shader_fluid_mac_advect_predict.js"],"names":[],"mappings":"AA4GA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,8CAFU,aAAa,CAMpB;8BAvI2B,+BAA+B"}