@woosh/meep-engine 3.68.0 → 3.69.0

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

@@ -1,282 +1,339 @@
-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,
-});
+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, then the porous obstacles' drag, 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 drag of a face is the mean of its two cells' drag over the step, k·dt, a cell without
+ FLUID_POROUS_FLAG giving none, toward the velocity of what drags on it, the two cells' weighed by
+ their drag. It is taken implicitly, with the face's velocity relative to that, |u − v|, at the step's
+ start (the carrier): u ← v + (u − v) / (1 + k·dt·|u − v|), which slows the air toward v and never
+ past it, however strong the drag.
+
+ 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 drag over the step and the velocity it drags toward, none beyond the window
+// or where the forcing wrote none
+fn fluid_mac_cell_porous(cell: vec3<i32>) -> vec4<f32> {
+    if (any(cell < vec3<i32>(0)) || any(cell >= vec3<i32>(step.cells.size))) {
+        return vec4<f32>(0.0);
+    }
+
+    let index = grid3d_to_index(vec3<u32>(cell), step.cells.size.xy);
+
+    if ((solid[index] & FLUID_POROUS_FLAG) == 0u) {
+        return vec4<f32>(0.0);
+    }
+
+    // after the three face lattices
+    let at = 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
+        + step.faces_w.size.x * step.faces_w.size.y * step.faces_w.size.z
+        + index * FLUID_FORCING_POROUS_WORDS;
+
+    return vec4<f32>(forcing[at], forcing[at + 1u], forcing[at + 2u], forcing[at + 3u]);
+}
+
+// a face's value slowed by the drag of its two cells, the face's direction axis, its velocity at the
+// step's start carrier
+fn fluid_mac_porous(minus: vec3<i32>, plus: vec3<i32>, axis: vec3<f32>, value: f32, carrier: vec3<f32>) -> f32 {
+    let a = fluid_mac_cell_porous(minus);
+    let b = fluid_mac_cell_porous(plus);
+
+    let total = a.x + b.x;
+
+    if (total <= 0.0) {
+        return value;
+    }
+
+    let wall = (a.yzw * a.x + b.yzw * b.x) * (1.0 / total);
+    let along = dot(wall, axis);
+
+    return along + (value - along) / (1.0 + 0.5 * total * length(carrier - wall));
+}
+
+// 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 carrier = fluid_mac_face_carrier_u(face, source);
+    let travel = carrier * 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 forced = fluid_mac_epilogue_u(face, limited, fluid_mac_confinement_u(face)) + fluid_mac_forcing_u(face);
+    let value = fluid_mac_porous(face - vec3<i32>(1, 0, 0), face, vec3<f32>(1.0, 0.0, 0.0), forced, carrier);
+
+    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 carrier = fluid_mac_face_carrier_v(face, source);
+    let travel = carrier * 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 forced = fluid_mac_epilogue_v(face, limited, fluid_mac_confinement_v(face)) + fluid_mac_forcing_v(face);
+    let value = fluid_mac_porous(face - vec3<i32>(0, 1, 0), face, vec3<f32>(0.0, 1.0, 0.0), forced, carrier);
+
+    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 carrier = fluid_mac_face_carrier_w(face, source);
+    let travel = carrier * 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 forced = fluid_mac_epilogue_w(face, limited, fluid_mac_confinement_w(face)) + fluid_mac_forcing_w(face);
+    let value = fluid_mac_porous(face - vec3<i32>(0, 0, 1), face, vec3<f32>(0.0, 0.0, 1.0), forced, carrier);
+
+    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`; then the drag of the porous obstacles in the face's two cells, under
+ * `FLUID_POROUS_FLAG`, taken implicitly. 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, then the cells' drag, `FLUID_FORCING_POROUS_WORDS` a cell; a face read only under
+ *   `FLUID_FORCED_FLAG` and a cell's drag only under `FLUID_POROUS_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,
+});