@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/renderer/fluid/coupling/chunk_fluid_cascade_parent.js

@@ -0,0 +1,238 @@
+import { chunk_grid3d_to_index } from "../../shader/chunk/grid/chunk_grid3d_to_index.js";
+import { chunk_grid_tile_window } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
+import { chunk_is_finite } from "../../shader/chunk/math/chunk_is_finite.js";
+import { chunk_texture3d_trilinear_interpolate } from "../../shader/chunk/texture/sample/chunk_texture3d_trilinear_corners.js";
+import { TEXTURE3D_TRILINEAR_CORNERS_STRUCT } from "../../shader/chunk/texture/TEXTURE3D_TRILINEAR_CORNERS_STRUCT.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/*
+ What a cascade reads of its parent (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7, §9), through the
+ uniform `parent` (FLUID_CASCADE_PARENT_STRUCT), which every shader including one of these chunks
+ declares under that name.
+
+ A child addresses its parent by `offset = step.cells.corner − parent.origin` (or its pass's own copy
+ of the child's corner): child-lattice cells from the parent's window start to the child's, a
+ multiple of 4. With it, child window-local lattice points become parent window-local coordinates
+ by halving, so nothing here sees a world coordinate.
+
+ Both reads are trilinear with weights of 0, ¼, ½ or ¾, which f32 holds exactly. The velocity read
+ blends the parent's DEVIATIONS from the far field and adds the far field after, so air the far field
+ alone moves (a deviation of exactly 0 at every corner) reads as the far field exactly.
+*/
+
+/**
+ * The parent's identity read at a face of the child, one concrete function per component:
+ * `fluid_parent_face_u(face, offset)`, `_v`, `_w`, `face` a window-local face of the child's lattice
+ * for that component (u face `(i, j, k)` at cell coordinate `(i − ½, j, k)`).
+ *
+ * Child u face `i` lies on parent u lattice coordinate `(i + offset)/2` along x and
+ * `(j + offset − ½)/2` across it; likewise v along y and w along z. The tap's eight parent faces are
+ * read as deviations, `v − parent.far_velocity`, and one beyond the parent's window as 0; the read is
+ * `parent.read_far_velocity + parent.keep · trilinear(deviations)`.
+ *
+ * Binds `parent_u`, `parent_v`, `parent_w`: the parent's persistent faces, `texture_3d<f32>`
+ * (`r32float`), toroidal through `parent.faces_*`. A far-field parent binds stand-ins it never reads.
+ *
+ * Reads 8 texels a call; beside the far field (a window of size 0) none, and it answers
+ * `parent.read_far_velocity` before any window test. That early answer is measured: a lone 64×32×64
+ * cascade's predict went from 56.3 to 27.6 µs and its correct from 84.0 to 44.0 on an RTX 4090
+ * (pipelines swapped in one run, per-dispatch medians), the seams' empty-window tests and blend being
+ * most of what a beyond-window read cost there.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_cascade_parent_velocity = CodeChunk.from(
+    //language=WGSL
+    `
+fn fluid_parent_deviation_u(lattice: vec3<i32>) -> f32 {
+    if (!grid_tile_window_contains(lattice, parent.faces_u.size)) {
+        return 0.0;
+    }
+
+    let storage = grid_tile_window_storage(lattice, parent.faces_u.corner_storage, parent.faces_u.period);
+
+    return textureLoad(parent_u, storage, 0).r - parent.far_velocity.x;
+}
+
+fn fluid_parent_deviation_v(lattice: vec3<i32>) -> f32 {
+    if (!grid_tile_window_contains(lattice, parent.faces_v.size)) {
+        return 0.0;
+    }
+
+    let storage = grid_tile_window_storage(lattice, parent.faces_v.corner_storage, parent.faces_v.period);
+
+    return textureLoad(parent_v, storage, 0).r - parent.far_velocity.y;
+}
+
+fn fluid_parent_deviation_w(lattice: vec3<i32>) -> f32 {
+    if (!grid_tile_window_contains(lattice, parent.faces_w.size)) {
+        return 0.0;
+    }
+
+    let storage = grid_tile_window_storage(lattice, parent.faces_w.corner_storage, parent.faces_w.period);
+
+    return textureLoad(parent_w, storage, 0).r - parent.far_velocity.z;
+}
+
+fn fluid_parent_face_u(face: vec3<i32>, offset: vec3<i32>) -> f32 {
+    // the far field: nothing to read, every corner would count 0
+    if (parent.faces_u.size.x == 0u) {
+        return parent.read_far_velocity.x;
+    }
+
+    let lattice = (vec3<f32>(face + offset) - vec3<f32>(0.0, 0.5, 0.5)) * 0.5;
+    let base = floor(lattice);
+    let lo = vec3<i32>(base);
+    let hi = lo + vec3<i32>(1);
+
+    let corners = ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref}(
+        vec4<f32>(
+            fluid_parent_deviation_u(lo),
+            fluid_parent_deviation_u(vec3<i32>(hi.x, lo.y, lo.z)),
+            fluid_parent_deviation_u(vec3<i32>(lo.x, hi.y, lo.z)),
+            fluid_parent_deviation_u(vec3<i32>(hi.x, hi.y, lo.z))
+        ),
+        vec4<f32>(
+            fluid_parent_deviation_u(vec3<i32>(lo.x, lo.y, hi.z)),
+            fluid_parent_deviation_u(vec3<i32>(hi.x, lo.y, hi.z)),
+            fluid_parent_deviation_u(vec3<i32>(lo.x, hi.y, hi.z)),
+            fluid_parent_deviation_u(hi)
+        ),
+        lattice - base
+    );
+
+    return parent.read_far_velocity.x + parent.keep * texture3d_trilinear_interpolate(corners);
+}
+
+fn fluid_parent_face_v(face: vec3<i32>, offset: vec3<i32>) -> f32 {
+    // the far field: nothing to read, every corner would count 0
+    if (parent.faces_v.size.x == 0u) {
+        return parent.read_far_velocity.y;
+    }
+
+    let lattice = (vec3<f32>(face + offset) - vec3<f32>(0.5, 0.0, 0.5)) * 0.5;
+    let base = floor(lattice);
+    let lo = vec3<i32>(base);
+    let hi = lo + vec3<i32>(1);
+
+    let corners = ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref}(
+        vec4<f32>(
+            fluid_parent_deviation_v(lo),
+            fluid_parent_deviation_v(vec3<i32>(hi.x, lo.y, lo.z)),
+            fluid_parent_deviation_v(vec3<i32>(lo.x, hi.y, lo.z)),
+            fluid_parent_deviation_v(vec3<i32>(hi.x, hi.y, lo.z))
+        ),
+        vec4<f32>(
+            fluid_parent_deviation_v(vec3<i32>(lo.x, lo.y, hi.z)),
+            fluid_parent_deviation_v(vec3<i32>(hi.x, lo.y, hi.z)),
+            fluid_parent_deviation_v(vec3<i32>(lo.x, hi.y, hi.z)),
+            fluid_parent_deviation_v(hi)
+        ),
+        lattice - base
+    );
+
+    return parent.read_far_velocity.y + parent.keep * texture3d_trilinear_interpolate(corners);
+}
+
+fn fluid_parent_face_w(face: vec3<i32>, offset: vec3<i32>) -> f32 {
+    // the far field: nothing to read, every corner would count 0
+    if (parent.faces_w.size.x == 0u) {
+        return parent.read_far_velocity.z;
+    }
+
+    let lattice = (vec3<f32>(face + offset) - vec3<f32>(0.5, 0.5, 0.0)) * 0.5;
+    let base = floor(lattice);
+    let lo = vec3<i32>(base);
+    let hi = lo + vec3<i32>(1);
+
+    let corners = ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref}(
+        vec4<f32>(
+            fluid_parent_deviation_w(lo),
+            fluid_parent_deviation_w(vec3<i32>(hi.x, lo.y, lo.z)),
+            fluid_parent_deviation_w(vec3<i32>(lo.x, hi.y, lo.z)),
+            fluid_parent_deviation_w(vec3<i32>(hi.x, hi.y, lo.z))
+        ),
+        vec4<f32>(
+            fluid_parent_deviation_w(vec3<i32>(lo.x, lo.y, hi.z)),
+            fluid_parent_deviation_w(vec3<i32>(hi.x, lo.y, hi.z)),
+            fluid_parent_deviation_w(vec3<i32>(lo.x, hi.y, hi.z)),
+            fluid_parent_deviation_w(hi)
+        ),
+        lattice - base
+    );
+
+    return parent.read_far_velocity.z + parent.keep * texture3d_trilinear_interpolate(corners);
+}
+`, [
+        TEXTURE3D_TRILINEAR_CORNERS_STRUCT.declaration_chunk,
+        chunk_texture3d_trilinear_interpolate,
+        chunk_grid_tile_window,
+    ]
+);
+
+/**
+ * `fluid_parent_pressure(q)`: the parent's kinematic pressure (m²/s², the child's units) at the
+ * centre of child-lattice cell `q`, counted from `parent.origin`: the Dirichlet value of a ghost cell
+ * beyond the child's window (§9).
+ *
+ * The centre of child cell `q` is parent cell coordinate `(q − ½)/2` (parent cell `P` centred at `P`),
+ * a quarter of a parent cell off a parent centre on every axis, so the read is trilinear over eight
+ * parent cells at weights ¾ and ¼. A parent cell beyond the parent's window reads 0, as does a value
+ * that is not finite.
+ *
+ * Binds `parent_pressure`: the parent's pressure, `array<f32>`, toroidal through `parent.cells`.
+ *
+ * Reads 8 elements a call; beside the far field, none.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_cascade_parent_pressure = CodeChunk.from(
+    //language=WGSL
+    `
+fn fluid_parent_pressure_cell(cell: vec3<i32>) -> f32 {
+    if (!grid_tile_window_contains(cell, parent.cells.size)) {
+        return 0.0;
+    }
+
+    let storage = grid_tile_window_storage(cell, parent.cells.corner_storage, parent.cells.period);
+    let value = parent_pressure[grid3d_to_index(storage, parent.cells.period.xy)];
+
+    return select(0.0, value, is_finite(value));
+}
+
+fn fluid_parent_pressure(q: vec3<i32>) -> f32 {
+    if (parent.cells.size.x == 0u) {
+        return 0.0;
+    }
+
+    let position = (vec3<f32>(q) - vec3<f32>(0.5)) * 0.5;
+    let base = floor(position);
+    let lo = vec3<i32>(base);
+    let hi = lo + vec3<i32>(1);
+
+    let corners = ${TEXTURE3D_TRILINEAR_CORNERS_STRUCT.wgsl_ref}(
+        vec4<f32>(
+            fluid_parent_pressure_cell(lo),
+            fluid_parent_pressure_cell(vec3<i32>(hi.x, lo.y, lo.z)),
+            fluid_parent_pressure_cell(vec3<i32>(lo.x, hi.y, lo.z)),
+            fluid_parent_pressure_cell(vec3<i32>(hi.x, hi.y, lo.z))
+        ),
+        vec4<f32>(
+            fluid_parent_pressure_cell(vec3<i32>(lo.x, lo.y, hi.z)),
+            fluid_parent_pressure_cell(vec3<i32>(hi.x, lo.y, hi.z)),
+            fluid_parent_pressure_cell(vec3<i32>(lo.x, hi.y, hi.z)),
+            fluid_parent_pressure_cell(hi)
+        ),
+        position - base
+    );
+
+    return texture3d_trilinear_interpolate(corners);
+}
+`, [
+        TEXTURE3D_TRILINEAR_CORNERS_STRUCT.declaration_chunk,
+        chunk_texture3d_trilinear_interpolate,
+        chunk_grid_tile_window,
+        chunk_grid3d_to_index,
+        chunk_is_finite,
+    ]
+);

package/src/shade/renderer/fluid/coupling/shader_fluid_cascade_fill.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A cascade's fill (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7, §8 pass 0): after a placement, the
+ * cells the move exposed (`window_scroll_regions`, at most three disjoint boxes) take their parent's
+ * identity read, faces and pressure, in one dispatch. A cascade's parent is the far field's when it is
+ * the coarsest, which writes `v_far` and pressure 0.
+ *
+ * One workgroup a brick of 4 × 4 × 4 cells, one invocation a cell; the boxes' corners and sizes are
+ * multiples of 4 because corners move in 4s. Dispatched over exactly `fill.box_end.z` bricks, folded
+ * onto x then y (`chunk_folded_workgroup_index`). A cell writes its −x, −y and −z faces, and a cell on
+ * the window's last plane along an axis writes the +boundary face there too: so a move up overwrites
+ * the old +boundary plane, which the window still holds, with the parent's read.
+ *
+ * The values are in the cascade's own frame, its read record: the parent's read is taken at `t_s` of
+ * the cascade (`parent.read_far_velocity`, `parent.keep`), so the filled cells and the cells that were
+ * already there are deviations from the same far field.
+ *
+ * Bindings:
+ * - `fill`: {@link FLUID_CASCADE_FILL_STRUCT};
+ * - `parent`: {@link FLUID_CASCADE_PARENT_STRUCT}, `parent_u`, `parent_v`, `parent_w` its faces and
+ *   `parent_pressure` its pressure;
+ * - `velocity_u`, `velocity_v`, `velocity_w`: written, the cascade's persistent faces, toroidal
+ *   through `fill.faces_*`;
+ * - `pressure`: written, the cascade's pressure, toroidal through `fill.cells`.
+ *
+ * Two storage buffers and three storage textures. Reads a cell: 24 parent texels and 8 parent
+ * pressures, more on a +boundary plane.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_cascade_fill: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_fluid_cascade_fill.d.ts.map

package/src/shade/renderer/fluid/coupling/shader_fluid_cascade_fill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_fluid_cascade_fill.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/coupling/shader_fluid_cascade_fill.js"],"names":[],"mappings":"AA2GA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wCAFU,aAAa,CAMpB;8BAxI2B,+BAA+B"}

package/src/shade/renderer/fluid/coupling/shader_fluid_cascade_fill.js

@@ -0,0 +1,141 @@
+import { chunk_folded_workgroup_index } from "../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_grid3d_to_index } from "../../shader/chunk/grid/chunk_grid3d_to_index.js";
+import { chunk_grid_tile_window } from "../../shader/chunk/grid/chunk_grid_tile_window.js";
+import { chunk_index_to_grid3d } from "../../shader/chunk/grid/chunk_index_to_grid3d.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { f32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { chunk_fluid_cascade_parent_pressure, chunk_fluid_cascade_parent_velocity } from "./chunk_fluid_cascade_parent.js";
+import { FLUID_CASCADE_FILL_BRICK, FLUID_CASCADE_FILL_STRUCT } from "./FLUID_CASCADE_FILL_STRUCT.js";
+import { FLUID_CASCADE_PARENT_STRUCT } from "./FLUID_CASCADE_PARENT_STRUCT.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("fill", FLUID_CASCADE_FILL_STRUCT)
+    .addUniform("parent", FLUID_CASCADE_PARENT_STRUCT)
+    .addTexture("parent_u", "unfilterable-float", "3d")
+    .addTexture("parent_v", "unfilterable-float", "3d")
+    .addTexture("parent_w", "unfilterable-float", "3d")
+    .addStorageBuffer("parent_pressure", WebGPUArray.from(f32), false)
+    .addStorageTexture("velocity_u", "r32float", "3d", "write-only")
+    .addStorageTexture("velocity_v", "r32float", "3d", "write-only")
+    .addStorageTexture("velocity_w", "r32float", "3d", "write-only")
+    .addStorageBuffer("pressure", WebGPUArray.from(f32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const FLUID_CASCADE_FILL_BRICK = ${FLUID_CASCADE_FILL_BRICK};
+
+fn fluid_cascade_fill_u(face: vec3<i32>, offset: vec3<i32>) {
+    let storage = grid_tile_window_storage(face, fill.faces_u.corner_storage, fill.faces_u.period);
+    textureStore(velocity_u, storage, vec4<f32>(fluid_parent_face_u(face, offset), 0.0, 0.0, 0.0));
+}
+
+fn fluid_cascade_fill_v(face: vec3<i32>, offset: vec3<i32>) {
+    let storage = grid_tile_window_storage(face, fill.faces_v.corner_storage, fill.faces_v.period);
+    textureStore(velocity_v, storage, vec4<f32>(fluid_parent_face_v(face, offset), 0.0, 0.0, 0.0));
+}
+
+fn fluid_cascade_fill_w(face: vec3<i32>, offset: vec3<i32>) {
+    let storage = grid_tile_window_storage(face, fill.faces_w.corner_storage, fill.faces_w.period);
+    textureStore(velocity_w, storage, vec4<f32>(fluid_parent_face_w(face, offset), 0.0, 0.0, 0.0));
+}
+
+@compute @workgroup_size(${FLUID_CASCADE_FILL_BRICK}, ${FLUID_CASCADE_FILL_BRICK}, ${FLUID_CASCADE_FILL_BRICK})
+fn main(
+    @builtin(workgroup_id) group: vec3<u32>,
+    @builtin(local_invocation_id) local: vec3<u32>,
+) {
+    let brick = folded_workgroup_index(group);
+
+    if (brick >= fill.box_end.z) {
+        return;
+    }
+
+    // which box the brick is in, each box read whole by a static name
+    var origin = fill.box2;
+    var bricks = fill.box2_bricks;
+    var index = brick - fill.box_end.y;
+
+    if (brick < fill.box_end.x) {
+        origin = fill.box0;
+        bricks = fill.box0_bricks;
+        index = brick;
+    } else if (brick < fill.box_end.y) {
+        origin = fill.box1;
+        bricks = fill.box1_bricks;
+        index = brick - fill.box_end.x;
+    }
+
+    let cell = origin + FLUID_CASCADE_FILL_BRICK * vec3<i32>(index_to_grid3d(index, bricks.xy)) + vec3<i32>(local);
+    let offset = fill.cells.corner - parent.origin;
+    let last = vec3<i32>(fill.cells.size) - vec3<i32>(1);
+
+    // each cell's -x, -y and -z faces
+    fluid_cascade_fill_u(cell, offset);
+    fluid_cascade_fill_v(cell, offset);
+    fluid_cascade_fill_w(cell, offset);
+
+    // the +boundary face planes, owned by the window's last cell along each axis
+    if (cell.x == last.x) {
+        fluid_cascade_fill_u(cell + vec3<i32>(1, 0, 0), offset);
+    }
+    if (cell.y == last.y) {
+        fluid_cascade_fill_v(cell + vec3<i32>(0, 1, 0), offset);
+    }
+    if (cell.z == last.z) {
+        fluid_cascade_fill_w(cell + vec3<i32>(0, 0, 1), offset);
+    }
+
+    let storage = grid_tile_window_storage(cell, fill.cells.corner_storage, fill.cells.period);
+
+    pressure[grid3d_to_index(storage, fill.cells.period.xy)] = fluid_parent_pressure(cell + offset);
+}
+`, [
+        chunk_folded_workgroup_index,
+        chunk_index_to_grid3d,
+        chunk_grid3d_to_index,
+        chunk_grid_tile_window,
+        chunk_fluid_cascade_parent_velocity,
+        chunk_fluid_cascade_parent_pressure,
+    ]
+);
+
+/**
+ * A cascade's fill (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7, §8 pass 0): after a placement, the
+ * cells the move exposed (`window_scroll_regions`, at most three disjoint boxes) take their parent's
+ * identity read, faces and pressure, in one dispatch. A cascade's parent is the far field's when it is
+ * the coarsest, which writes `v_far` and pressure 0.
+ *
+ * One workgroup a brick of 4 × 4 × 4 cells, one invocation a cell; the boxes' corners and sizes are
+ * multiples of 4 because corners move in 4s. Dispatched over exactly `fill.box_end.z` bricks, folded
+ * onto x then y (`chunk_folded_workgroup_index`). A cell writes its −x, −y and −z faces, and a cell on
+ * the window's last plane along an axis writes the +boundary face there too: so a move up overwrites
+ * the old +boundary plane, which the window still holds, with the parent's read.
+ *
+ * The values are in the cascade's own frame, its read record: the parent's read is taken at `t_s` of
+ * the cascade (`parent.read_far_velocity`, `parent.keep`), so the filled cells and the cells that were
+ * already there are deviations from the same far field.
+ *
+ * Bindings:
+ * - `fill`: {@link FLUID_CASCADE_FILL_STRUCT};
+ * - `parent`: {@link FLUID_CASCADE_PARENT_STRUCT}, `parent_u`, `parent_v`, `parent_w` its faces and
+ *   `parent_pressure` its pressure;
+ * - `velocity_u`, `velocity_v`, `velocity_w`: written, the cascade's persistent faces, toroidal
+ *   through `fill.faces_*`;
+ * - `pressure`: written, the cascade's pressure, toroidal through `fill.cells`.
+ *
+ * Two storage buffers and three storage textures. Reads a cell: 24 parent texels and 8 parent
+ * pressures, more on a +boundary plane.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_cascade_fill = ComputeShader.from({
+    label: "Fluid / cascade fill",
+    body,
+    resources,
+});

package/src/shade/renderer/fluid/coupling/shader_fluid_cascade_ghosts.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A step's ghosts (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7, §9, D3): the parent's identity read,
+ * evaluated once at every face of a shell `FLUID_CASCADE_GHOST_DEPTH` faces deep around the
+ * window, and the parent's pressure at the centre of every cell one past it, into transients the
+ * step's passes read with one texel or element where the parent read takes eight.
+ *
+ * Read as of the cascade's record, the step's start, as the seams read the parent. A per-step cache:
+ * the persistent textures still hold no ghost, and the toroidal windows are the window's alone.
+ *
+ * Measured on an RTX 4090 at 64×32×64 against the seams reading the parent per tap (four cascades,
+ * the stacks driven alike, their recorded ticks replayed paired and interleaved, p10 of 200; the four
+ * cascades' state after 32 ticks bit for bit the same): a tick that steps cascade 0 alone
+ * 246.8 → 144.4 µs, one with a coarse step 489.5 → 291.8. Of cascade 0's step, predict 45 → 16 µs,
+ * correct 89 → 27, the smoother 63 → 53, residual and restriction 22 → 18, the gradient 6 → 4, for
+ * this pass's 9.
+ *
+ * One invocation a texel of the largest face shell, 4 × 4 × 4 a workgroup, dispatched
+ * `ceil((N + 1 + 2·depth) / 4)` on each axis; an invocation inside the window writes nothing.
+ *
+ * Bindings:
+ * - `step`: {@link FLUID_MAC_STEP_STRUCT}, the window;
+ * - `parent`: {@link FLUID_CASCADE_PARENT_STRUCT}, `parent_u`, `parent_v`, `parent_w` and
+ *   `parent_pressure`, the parent;
+ * - `ghost_u`, `ghost_v`, `ghost_w`: written, `r32float` 3-D storage textures of the face lattices
+ *   grown by the depth on every side, window-local face `f` at texel `f + depth`;
+ * - `ghost_pressure`: written, `array<f32>` over the window grown by one cell on every side, x fastest.
+ *
+ * Two storage buffers and three storage textures.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_cascade_ghosts: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_fluid_cascade_ghosts.d.ts.map

package/src/shade/renderer/fluid/coupling/shader_fluid_cascade_ghosts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_fluid_cascade_ghosts.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/coupling/shader_fluid_cascade_ghosts.js"],"names":[],"mappings":"AAiEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,0CAFU,aAAa,CAMpB;8BAnG2B,+BAA+B"}

package/src/shade/renderer/fluid/coupling/shader_fluid_cascade_ghosts.js

@@ -0,0 +1,101 @@
+import { chunk_grid_tile_window } 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 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { FLUID_MAC_STEP_STRUCT } from "../mac/FLUID_MAC_STEP_STRUCT.js";
+import { FLUID_CASCADE_GHOST_DEPTH } from "./FLUID_CASCADE_GHOSTS.js";
+import { chunk_fluid_cascade_parent_pressure, chunk_fluid_cascade_parent_velocity } from "./chunk_fluid_cascade_parent.js";
+import { FLUID_CASCADE_PARENT_STRUCT } from "./FLUID_CASCADE_PARENT_STRUCT.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("step", FLUID_MAC_STEP_STRUCT)
+    .addUniform("parent", FLUID_CASCADE_PARENT_STRUCT)
+    .addTexture("parent_u", "unfilterable-float", "3d")
+    .addTexture("parent_v", "unfilterable-float", "3d")
+    .addTexture("parent_w", "unfilterable-float", "3d")
+    .addStorageBuffer("parent_pressure", WebGPUArray.from(f32), false)
+    .addStorageTexture("ghost_u", "r32float", "3d", "write-only")
+    .addStorageTexture("ghost_v", "r32float", "3d", "write-only")
+    .addStorageTexture("ghost_w", "r32float", "3d", "write-only")
+    .addStorageBuffer("ghost_pressure", WebGPUArray.from(f32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const FLUID_CASCADE_GHOST_DEPTH = ${FLUID_CASCADE_GHOST_DEPTH};
+
+@compute @workgroup_size(4, 4, 4)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    let offset = step.cells.corner - parent.origin;
+
+    // the velocity ghosts: shell texel t holds window-local face t - depth, of every face past the window
+    let face = vec3<i32>(id) - vec3<i32>(FLUID_CASCADE_GHOST_DEPTH);
+    let reach = vec3<u32>(2u * u32(FLUID_CASCADE_GHOST_DEPTH));
+
+    if (all(id < step.faces_u.size + reach) && !grid_tile_window_contains(face, step.faces_u.size)) {
+        textureStore(ghost_u, id, vec4<f32>(fluid_parent_face_u(face, offset), 0.0, 0.0, 0.0));
+    }
+
+    if (all(id < step.faces_v.size + reach) && !grid_tile_window_contains(face, step.faces_v.size)) {
+        textureStore(ghost_v, id, vec4<f32>(fluid_parent_face_v(face, offset), 0.0, 0.0, 0.0));
+    }
+
+    if (all(id < step.faces_w.size + reach) && !grid_tile_window_contains(face, step.faces_w.size)) {
+        textureStore(ghost_w, id, vec4<f32>(fluid_parent_face_w(face, offset), 0.0, 0.0, 0.0));
+    }
+
+    // the pressure ghosts: element t, x fastest over the window and a cell each side, of cell t - 1
+    let n = step.cells.size + vec3<u32>(2u);
+    let cell = vec3<i32>(id) - vec3<i32>(1);
+
+    if (all(id < n) && !grid_tile_window_contains(cell, step.cells.size)) {
+        ghost_pressure[id.x + n.x * (id.y + n.y * id.z)] = fluid_parent_pressure(cell + offset);
+    }
+}
+`, [
+        chunk_grid_tile_window,
+        chunk_fluid_cascade_parent_velocity,
+        chunk_fluid_cascade_parent_pressure,
+    ]
+);
+
+/**
+ * A step's ghosts (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7, §9, D3): the parent's identity read,
+ * evaluated once at every face of a shell `FLUID_CASCADE_GHOST_DEPTH` faces deep around the
+ * window, and the parent's pressure at the centre of every cell one past it, into transients the
+ * step's passes read with one texel or element where the parent read takes eight.
+ *
+ * Read as of the cascade's record, the step's start, as the seams read the parent. A per-step cache:
+ * the persistent textures still hold no ghost, and the toroidal windows are the window's alone.
+ *
+ * Measured on an RTX 4090 at 64×32×64 against the seams reading the parent per tap (four cascades,
+ * the stacks driven alike, their recorded ticks replayed paired and interleaved, p10 of 200; the four
+ * cascades' state after 32 ticks bit for bit the same): a tick that steps cascade 0 alone
+ * 246.8 → 144.4 µs, one with a coarse step 489.5 → 291.8. Of cascade 0's step, predict 45 → 16 µs,
+ * correct 89 → 27, the smoother 63 → 53, residual and restriction 22 → 18, the gradient 6 → 4, for
+ * this pass's 9.
+ *
+ * One invocation a texel of the largest face shell, 4 × 4 × 4 a workgroup, dispatched
+ * `ceil((N + 1 + 2·depth) / 4)` on each axis; an invocation inside the window writes nothing.
+ *
+ * Bindings:
+ * - `step`: {@link FLUID_MAC_STEP_STRUCT}, the window;
+ * - `parent`: {@link FLUID_CASCADE_PARENT_STRUCT}, `parent_u`, `parent_v`, `parent_w` and
+ *   `parent_pressure`, the parent;
+ * - `ghost_u`, `ghost_v`, `ghost_w`: written, `r32float` 3-D storage textures of the face lattices
+ *   grown by the depth on every side, window-local face `f` at texel `f + depth`;
+ * - `ghost_pressure`: written, `array<f32>` over the window grown by one cell on every side, x fastest.
+ *
+ * Two storage buffers and three storage textures.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_cascade_ghosts = ComputeShader.from({
+    label: "Fluid / cascade ghosts",
+    body,
+    resources,
+});

package/src/shade/renderer/fluid/coupling/shader_fluid_cascade_restrict.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Two-way feedback (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §8 pass 7, §9): before a parent steps, the
+ * parent faces over its child's interior take the mean of the four child faces each covers.
+ *
+ * On a ratio-2 MAC lattice a parent cell's six faces cover the boundary of its eight children, and
+ * the sum of the means is a quarter of the sum of the children's divergences, the children's shared
+ * faces cancelling: a divergence-free child restricts to a divergence-free parent, exactly. The
+ * parent's own projection then removes the divergence at the interface, where a parent cell has some
+ * faces from the child and some of its own.
+ *
+ * The box is the parent cells whose children lie {@link FLUID_CASCADE_FEEDBACK_MARGIN} child cells or
+ * more inside the child's window: the child's edge row and relaxation band are not fed back.
+ *
+ * Frames: the child's faces are deviations from `v_far` at its record and the parent's from `v_far`
+ * at its own, which is older (the parent is about to step); the mean deviation is carried to the
+ * parent's record by `keep`.
+ *
+ * One invocation a parent cell of the box, 8 × 8 × 4 a workgroup, dispatched over the box. A cell
+ * writes its −x, −y, −z faces, and the box's last cell on an axis its + face there. Reads 12 child
+ * texels a cell; no storage buffer, three storage textures.
+ *
+ * Bindings:
+ * - `restriction`: {@link FLUID_CASCADE_RESTRICT_STRUCT};
+ * - `child_u`, `child_v`, `child_w`: the child's persistent faces;
+ * - `out_u`, `out_v`, `out_w`: written, the parent's persistent faces.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_fluid_cascade_restrict: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_fluid_cascade_restrict.d.ts.map

package/src/shade/renderer/fluid/coupling/shader_fluid_cascade_restrict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_fluid_cascade_restrict.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/coupling/shader_fluid_cascade_restrict.js"],"names":[],"mappings":"AA6FA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,4CAFU,aAAa,CAMpB;8BA5H2B,+BAA+B"}