@woosh/meep-engine 3.49.0 → 3.50.0

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

@@ -0,0 +1,43 @@
+import { GRID_TILE_WINDOW_STRUCT } from "../../shader/chunk/grid/GRID_TILE_WINDOW_STRUCT.js";
+import { vec3i, vec3u } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * Bricks of a cascade's fill: cells 4 on a side, the unit corners move in.
+ * @type {number}
+ */
+export const FLUID_CASCADE_FILL_BRICK = 4;
+
+/**
+ * Boxes one fill writes at most: a move exposes one slab per axis it moved along
+ * (`window_scroll_regions`).
+ * @type {number}
+ */
+export const FLUID_CASCADE_FILL_BOX_LIMIT = 3;
+
+/**
+ * What a cascade's fill writes (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7), as the uniform `fill`.
+ *
+ * - `cells`, `faces_u`, `faces_v`, `faces_w`: where the cascade's pressure and faces are stored,
+ *   as `FLUID_MAC_STEP_STRUCT` has them; `cells.corner` is the cascade's corner.
+ * - `box0`, `box1`, `box2`: each box's smallest window-local cell, a multiple of
+ *   {@link FLUID_CASCADE_FILL_BRICK};
+ * - `box0_bricks`, `box1_bricks`, `box2_bricks`: bricks along each axis of each box;
+ * - `box_end`: bricks through the end of box 0, 1 and 2, so `box_end.z` is the dispatch's live count.
+ *   An unused box has no bricks.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_CASCADE_FILL_STRUCT = WebGPUStruct.from({
+    cells: GRID_TILE_WINDOW_STRUCT,
+    faces_u: GRID_TILE_WINDOW_STRUCT,
+    faces_v: GRID_TILE_WINDOW_STRUCT,
+    faces_w: GRID_TILE_WINDOW_STRUCT,
+    box0: vec3i,
+    box1: vec3i,
+    box2: vec3i,
+    box0_bricks: vec3u,
+    box1_bricks: vec3u,
+    box2_bricks: vec3u,
+    box_end: vec3u,
+}, 'FluidCascadeFill');

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

@@ -0,0 +1,31 @@
+/**
+ * The texels of a step's velocity ghost shell along each axis of a component's face lattice: the
+ * lattice grown by {@link FLUID_CASCADE_GHOST_DEPTH} on both sides.
+ *
+ * @param {ArrayLike<number>} resolution the window's cells
+ * @param {number} component 0, 1 or 2
+ * @returns {number[]}
+ */
+export function fluid_cascade_ghost_shell_size(resolution: ArrayLike<number>, component: number): number[];
+/**
+ * Elements of a step's pressure ghosts: the window grown by one cell on every side, every stencil's
+ * halo.
+ *
+ * @param {ArrayLike<number>} resolution
+ * @returns {number}
+ */
+export function fluid_cascade_pressure_ghost_count(resolution: ArrayLike<number>): number;
+/**
+ * Faces a step's velocity ghosts reach past its window on every side
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7, D3): what the advection reads beyond the window.
+ *
+ * A face's carrier reads one face past it; a trace ends `|v|·dt/h` cells away, and a step starts
+ * from a field the deviation clamp held to `|v − v_far| ≤ 4·h/dt`, so the trace is at most
+ * `|v_far|·dt/h + 4` cells; its trilinear tap takes one corner past that. A depth of
+ * `FLUID_CASCADE_DEVIATION_CELLS + 1 + 1` = 6 holds every read while the far field crosses at most one
+ * cell a step (`|v_far|·dt/h ≤ 1`: 20 m/s at h = 0.5 m and dt = 25 ms). A read past the shell, under
+ * a faster far field, takes the parent's read directly, so the depth sets the cost, never the answer.
+ * @type {number}
+ */
+export const FLUID_CASCADE_GHOST_DEPTH: number;
+//# sourceMappingURL=FLUID_CASCADE_GHOSTS.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FLUID_CASCADE_GHOSTS.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/coupling/FLUID_CASCADE_GHOSTS.js"],"names":[],"mappings":"AAgBA;;;;;;;GAOG;AACH,2DAJW,UAAU,MAAM,CAAC,aACjB,MAAM,GACJ,MAAM,EAAE,CAIpB;AAED;;;;;;GAMG;AACH,+DAHW,UAAU,MAAM,CAAC,GACf,MAAM,CAIlB;AAnCD;;;;;;;;;;;GAWG;AACH,wCAFU,MAAM,CAE2D"}

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

@@ -0,0 +1,38 @@
+import { FLUID_CASCADE_DEVIATION_CELLS } from "./chunk_fluid_cascade_epilogue.js";
+
+/**
+ * Faces a step's velocity ghosts reach past its window on every side
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7, D3): what the advection reads beyond the window.
+ *
+ * A face's carrier reads one face past it; a trace ends `|v|·dt/h` cells away, and a step starts
+ * from a field the deviation clamp held to `|v − v_far| ≤ 4·h/dt`, so the trace is at most
+ * `|v_far|·dt/h + 4` cells; its trilinear tap takes one corner past that. A depth of
+ * `FLUID_CASCADE_DEVIATION_CELLS + 1 + 1` = 6 holds every read while the far field crosses at most one
+ * cell a step (`|v_far|·dt/h ≤ 1`: 20 m/s at h = 0.5 m and dt = 25 ms). A read past the shell, under
+ * a faster far field, takes the parent's read directly, so the depth sets the cost, never the answer.
+ * @type {number}
+ */
+export const FLUID_CASCADE_GHOST_DEPTH = FLUID_CASCADE_DEVIATION_CELLS + 2;
+
+/**
+ * The texels of a step's velocity ghost shell along each axis of a component's face lattice: the
+ * lattice grown by {@link FLUID_CASCADE_GHOST_DEPTH} on both sides.
+ *
+ * @param {ArrayLike<number>} resolution the window's cells
+ * @param {number} component 0, 1 or 2
+ * @returns {number[]}
+ */
+export function fluid_cascade_ghost_shell_size(resolution, component) {
+    return [0, 1, 2].map(axis => resolution[axis] + (axis === component ? 1 : 0) + 2 * FLUID_CASCADE_GHOST_DEPTH);
+}
+
+/**
+ * Elements of a step's pressure ghosts: the window grown by one cell on every side, every stencil's
+ * halo.
+ *
+ * @param {ArrayLike<number>} resolution
+ * @returns {number}
+ */
+export function fluid_cascade_pressure_ghost_count(resolution) {
+    return (resolution[0] + 2) * (resolution[1] + 2) * (resolution[2] + 2);
+}

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

@@ -0,0 +1,46 @@
+/**
+ * A {@link FLUID_CASCADE_PARENT_STRUCT} value, to be filled in place (`GPUFluidCascade#describe_parent`).
+ *
+ * @returns {{origin: Int32Array, keep: number, cells: object, faces_u: object, faces_v: object, faces_w: object, far_velocity: Float32Array, read_far_velocity: Float32Array}}
+ */
+export function fluid_cascade_parent_value(): {
+    origin: Int32Array;
+    keep: number;
+    cells: object;
+    faces_u: object;
+    faces_v: object;
+    faces_w: object;
+    far_velocity: Float32Array;
+    read_far_velocity: Float32Array;
+};
+/**
+ * A cascade's parent as the cascade reads it beyond its own window, the uniform `parent`
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7, §9).
+ *
+ * The parent's cells are twice the child's on every axis, and both lattices share the world's
+ * origin: child world cell `g` lies in parent world cell `floor(g / 2)`. Corners are multiples of 4,
+ * so the parent's faces are faces of the child's lattice too.
+ *
+ * - `origin`: the child-lattice world cell at the parent's window-local cell 0, twice the parent's
+ *   corner. A child reads its parent through `step.cells.corner − origin`, which is small however far
+ *   from the world's origin both windows are.
+ * - `cells`: where the parent's pressure is stored ({@link GRID_TILE_WINDOW_STRUCT}, in the parent's
+ *   cells).
+ * - `faces_u`, `faces_v`, `faces_w`: where the parent's faces are stored.
+ * - `far_velocity`: `v_far(t_s,p)`, m/s, the far field at the parent's last step: what its faces are
+ *   a deviation from.
+ * - `read_far_velocity`: `v_far` at the instant the child reads at, m/s.
+ * - `keep`: `e^(−(Λ(t_read) − Λ(t_s,p)))`, how much of the parent's deviation the read keeps.
+ *
+ * So the parent's identity read of a face value `v` is `read_far_velocity + (v − far_velocity)·keep`
+ * (§6), and a read beyond the parent's window is `read_far_velocity`.
+ *
+ * **The far field is a parent with no window**: every window's size is 0, so every read lands
+ * beyond it, velocity reads `read_far_velocity` and pressure 0. The coarsest cascade, and a cascade
+ * stepped on its own, read that.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_CASCADE_PARENT_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=FLUID_CASCADE_PARENT_STRUCT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FLUID_CASCADE_PARENT_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/coupling/FLUID_CASCADE_PARENT_STRUCT.js"],"names":[],"mappings":"AA4CA;;;;GAIG;AACH,8CAFa;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,YAAY,CAAC;IAAC,iBAAiB,EAAE,YAAY,CAAA;CAAC,CAa7K;AAvDD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,0CAFU,YAAY,CAWG;6BAxCI,mCAAmC"}

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

@@ -0,0 +1,61 @@
+import { GRID_TILE_WINDOW_STRUCT } from "../../shader/chunk/grid/GRID_TILE_WINDOW_STRUCT.js";
+import { f32, vec3f, vec3i } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { fluid_cascade_window_value } from "../fluid_cascade_window.js";
+
+/**
+ * A cascade's parent as the cascade reads it beyond its own window, the uniform `parent`
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7, §9).
+ *
+ * The parent's cells are twice the child's on every axis, and both lattices share the world's
+ * origin: child world cell `g` lies in parent world cell `floor(g / 2)`. Corners are multiples of 4,
+ * so the parent's faces are faces of the child's lattice too.
+ *
+ * - `origin`: the child-lattice world cell at the parent's window-local cell 0, twice the parent's
+ *   corner. A child reads its parent through `step.cells.corner − origin`, which is small however far
+ *   from the world's origin both windows are.
+ * - `cells`: where the parent's pressure is stored ({@link GRID_TILE_WINDOW_STRUCT}, in the parent's
+ *   cells).
+ * - `faces_u`, `faces_v`, `faces_w`: where the parent's faces are stored.
+ * - `far_velocity`: `v_far(t_s,p)`, m/s, the far field at the parent's last step: what its faces are
+ *   a deviation from.
+ * - `read_far_velocity`: `v_far` at the instant the child reads at, m/s.
+ * - `keep`: `e^(−(Λ(t_read) − Λ(t_s,p)))`, how much of the parent's deviation the read keeps.
+ *
+ * So the parent's identity read of a face value `v` is `read_far_velocity + (v − far_velocity)·keep`
+ * (§6), and a read beyond the parent's window is `read_far_velocity`.
+ *
+ * **The far field is a parent with no window**: every window's size is 0, so every read lands
+ * beyond it, velocity reads `read_far_velocity` and pressure 0. The coarsest cascade, and a cascade
+ * stepped on its own, read that.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_CASCADE_PARENT_STRUCT = WebGPUStruct.from({
+    origin: vec3i,
+    keep: f32,
+    cells: GRID_TILE_WINDOW_STRUCT,
+    faces_u: GRID_TILE_WINDOW_STRUCT,
+    faces_v: GRID_TILE_WINDOW_STRUCT,
+    faces_w: GRID_TILE_WINDOW_STRUCT,
+    far_velocity: vec3f,
+    read_far_velocity: vec3f,
+}, 'FluidCascadeParent');
+
+/**
+ * A {@link FLUID_CASCADE_PARENT_STRUCT} value, to be filled in place (`GPUFluidCascade#describe_parent`).
+ *
+ * @returns {{origin: Int32Array, keep: number, cells: object, faces_u: object, faces_v: object, faces_w: object, far_velocity: Float32Array, read_far_velocity: Float32Array}}
+ */
+export function fluid_cascade_parent_value() {
+    return {
+        origin: new Int32Array(3),
+        keep: 1,
+        cells: fluid_cascade_window_value(),
+        faces_u: fluid_cascade_window_value(),
+        faces_v: fluid_cascade_window_value(),
+        faces_w: fluid_cascade_window_value(),
+        far_velocity: new Float32Array(3),
+        read_far_velocity: new Float32Array(3),
+    };
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Child cells from each face of a child's window that its feedback leaves out: the edge row and the
+ * relaxation band's rows 2..5, rounded up to whole parent cells (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md
+ * §9). Those rows are driven toward the parent; feeding them back would hand the parent its own
+ * relaxed values. A parent face restricted from child cells at row 7 or deeper is all the child's own.
+ * @type {number}
+ */
+export const FLUID_CASCADE_FEEDBACK_MARGIN: number;
+/**
+ * What a restriction of a child into its parent reads and writes, as the uniform `restriction`.
+ *
+ * - `child_u`, `child_v`, `child_w`: where the child's faces are stored;
+ * - `faces_u`, `faces_v`, `faces_w`: where the parent's are;
+ * - `box`, `box_size`: the parent window-local cells restricted, whose six faces all take the child's;
+ * - `child_offset`: the child window-local cell of the parent's window-local cell 0, so parent cell
+ *   `P` holds child cells `2P + child_offset` to `2P + child_offset + 1`;
+ * - `child_far_velocity`: `v_far` at the child's record, what its faces deviate from;
+ * - `far_velocity`: `v_far` at the parent's record;
+ * - `keep`: `e^(−(Λ(t_s,parent) − Λ(t_s,child)))`, the child's deviation as of the parent's record.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_CASCADE_RESTRICT_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=FLUID_CASCADE_RESTRICT_STRUCT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FLUID_CASCADE_RESTRICT_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/coupling/FLUID_CASCADE_RESTRICT_STRUCT.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;GAaG;AACH,4CAFU,YAAY,CAeK;6BAtCE,mCAAmC"}

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

@@ -0,0 +1,41 @@
+import { GRID_TILE_WINDOW_STRUCT } from "../../shader/chunk/grid/GRID_TILE_WINDOW_STRUCT.js";
+import { f32, vec3f, vec3i, vec3u } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * Child cells from each face of a child's window that its feedback leaves out: the edge row and the
+ * relaxation band's rows 2..5, rounded up to whole parent cells (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md
+ * §9). Those rows are driven toward the parent; feeding them back would hand the parent its own
+ * relaxed values. A parent face restricted from child cells at row 7 or deeper is all the child's own.
+ * @type {number}
+ */
+export const FLUID_CASCADE_FEEDBACK_MARGIN = 6;
+
+/**
+ * What a restriction of a child into its parent reads and writes, as the uniform `restriction`.
+ *
+ * - `child_u`, `child_v`, `child_w`: where the child's faces are stored;
+ * - `faces_u`, `faces_v`, `faces_w`: where the parent's are;
+ * - `box`, `box_size`: the parent window-local cells restricted, whose six faces all take the child's;
+ * - `child_offset`: the child window-local cell of the parent's window-local cell 0, so parent cell
+ *   `P` holds child cells `2P + child_offset` to `2P + child_offset + 1`;
+ * - `child_far_velocity`: `v_far` at the child's record, what its faces deviate from;
+ * - `far_velocity`: `v_far` at the parent's record;
+ * - `keep`: `e^(−(Λ(t_s,parent) − Λ(t_s,child)))`, the child's deviation as of the parent's record.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_CASCADE_RESTRICT_STRUCT = WebGPUStruct.from({
+    child_u: GRID_TILE_WINDOW_STRUCT,
+    child_v: GRID_TILE_WINDOW_STRUCT,
+    child_w: GRID_TILE_WINDOW_STRUCT,
+    faces_u: GRID_TILE_WINDOW_STRUCT,
+    faces_v: GRID_TILE_WINDOW_STRUCT,
+    faces_w: GRID_TILE_WINDOW_STRUCT,
+    box: vec3i,
+    keep: f32,
+    box_size: vec3u,
+    child_offset: vec3i,
+    child_far_velocity: vec3f,
+    far_velocity: vec3f,
+}, 'FluidCascadeRestrict');

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

@@ -0,0 +1,52 @@
+/**
+ * Rows of a cascade's relaxation band (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §9, WRF's Davies
+ * zone): a face `n` rows from the window's edge, the edge row being 1, relaxes toward its parent on
+ * rows {@link FLUID_CASCADE_BAND_FIRST_ROW} to {@link FLUID_CASCADE_BAND_LAST_ROW}.
+ * @type {number}
+ */
+export const FLUID_CASCADE_BAND_FIRST_ROW: number;
+/** @type {number} */
+export const FLUID_CASCADE_BAND_LAST_ROW: number;
+/**
+ * The deviation clamp's bound in cells a step: `|v − v_far| ≤ 4·h_c/dt_c` (§8 pass 3).
+ *
+ * A deviation that large crosses four cells a step, past what the advection's traces and the
+ * parent's seams are sized for; nothing the solver makes reaches it (the CFL of a stable step is
+ * about 1), so it only ever acts on a field that something broke, such as a teleport the fills did
+ * not cover. It bounds the deviation, never the wind: `v_far` itself may be any speed. And
+ * `h_c/dt_c` is the same on every cascade, since both double together.
+ * @type {number}
+ */
+export const FLUID_CASCADE_DEVIATION_CELLS: number;
+/**
+ * The terms of a cascade step that follow the MacCormack limiter on every face that is not pinned
+ * (§8 pass 3), as pure functions, and composed per component for the correct pass.
+ *
+ * - `fluid_atmosphere_identity(v, far_start, far_end, keep)`: `far_end + (v − far_start)·keep`, the
+ *   atmosphere over the step (§6): air the far field alone moves keeps `keep = e^(−ΔΛ)` of its
+ *   deviation, exactly, whatever the far field did meanwhile.
+ * - `fluid_relaxation_weight(row)`: WRF's `F1·Δt = (6 − n)/40` on rows 2..5 (`F1 = (1/10Δt)·(6 − n)/4`),
+ *   0 elsewhere: 0.1, 0.075, 0.05, 0.025.
+ * - `fluid_deviation_clamp(v, far, limit)`: `v` held to `far ± limit`.
+ * - `fluid_mac_face_row_u(face)`, `_v`, `_w`: a window-local face's row, `1 +` its distance in faces
+ *   from the window's edge along its own axis, in cells across it; the edge faces and the edge cells'
+ *   faces are row 1.
+ * - `fluid_mac_epilogue_u(face, value, push)`, `_v`, `_w`: the identity, plus `push`, the face's
+ *   vorticity confinement over the step (0 without it); then, with `step.band`, the band toward the
+ *   parent's identity read at the face carried through the same identity, then the clamp about
+ *   `v_far` at the step's end. The order is §8's pass 3: the atmosphere, confinement, the band, the
+ *   clamp, so the band relaxes and the clamp bounds the confined face like any other.
+ *
+ * Reads the uniforms `step` (`FLUID_MAC_STEP_STRUCT`) and `parent`, and the parent's faces
+ * (`chunk_fluid_cascade_parent_velocity`), whose read is at the step's start; the band reads 8 parent
+ * texels a face on its rows, nothing elsewhere.
+ *
+ * Air the far field alone moves is exact through all of it: the identity maps `v_far(t₀)` to
+ * `v_far(t₁)`, the parent reads `v_far(t₀)` there so the band's target is `v_far(t₁)` too, and the
+ * clamp holds what is already at its centre.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_cascade_epilogue: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_fluid_cascade_epilogue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_fluid_cascade_epilogue.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/coupling/chunk_fluid_cascade_epilogue.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,2CAFU,MAAM,CAE8B;AAE9C,qBAAqB;AACrB,0CADW,MAAM,CAC4B;AAE7C;;;;;;;;;GASG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,2CAFU,SAAS,CA4FjB;0BAjJwB,oCAAoC"}

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

@@ -0,0 +1,146 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_fluid_cascade_parent_velocity } from "./chunk_fluid_cascade_parent.js";
+
+/**
+ * Rows of a cascade's relaxation band (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §9, WRF's Davies
+ * zone): a face `n` rows from the window's edge, the edge row being 1, relaxes toward its parent on
+ * rows {@link FLUID_CASCADE_BAND_FIRST_ROW} to {@link FLUID_CASCADE_BAND_LAST_ROW}.
+ * @type {number}
+ */
+export const FLUID_CASCADE_BAND_FIRST_ROW = 2;
+
+/** @type {number} */
+export const FLUID_CASCADE_BAND_LAST_ROW = 5;
+
+/**
+ * The deviation clamp's bound in cells a step: `|v − v_far| ≤ 4·h_c/dt_c` (§8 pass 3).
+ *
+ * A deviation that large crosses four cells a step, past what the advection's traces and the
+ * parent's seams are sized for; nothing the solver makes reaches it (the CFL of a stable step is
+ * about 1), so it only ever acts on a field that something broke, such as a teleport the fills did
+ * not cover. It bounds the deviation, never the wind: `v_far` itself may be any speed. And
+ * `h_c/dt_c` is the same on every cascade, since both double together.
+ * @type {number}
+ */
+export const FLUID_CASCADE_DEVIATION_CELLS = 4;
+
+/**
+ * The terms of a cascade step that follow the MacCormack limiter on every face that is not pinned
+ * (§8 pass 3), as pure functions, and composed per component for the correct pass.
+ *
+ * - `fluid_atmosphere_identity(v, far_start, far_end, keep)`: `far_end + (v − far_start)·keep`, the
+ *   atmosphere over the step (§6): air the far field alone moves keeps `keep = e^(−ΔΛ)` of its
+ *   deviation, exactly, whatever the far field did meanwhile.
+ * - `fluid_relaxation_weight(row)`: WRF's `F1·Δt = (6 − n)/40` on rows 2..5 (`F1 = (1/10Δt)·(6 − n)/4`),
+ *   0 elsewhere: 0.1, 0.075, 0.05, 0.025.
+ * - `fluid_deviation_clamp(v, far, limit)`: `v` held to `far ± limit`.
+ * - `fluid_mac_face_row_u(face)`, `_v`, `_w`: a window-local face's row, `1 +` its distance in faces
+ *   from the window's edge along its own axis, in cells across it; the edge faces and the edge cells'
+ *   faces are row 1.
+ * - `fluid_mac_epilogue_u(face, value, push)`, `_v`, `_w`: the identity, plus `push`, the face's
+ *   vorticity confinement over the step (0 without it); then, with `step.band`, the band toward the
+ *   parent's identity read at the face carried through the same identity, then the clamp about
+ *   `v_far` at the step's end. The order is §8's pass 3: the atmosphere, confinement, the band, the
+ *   clamp, so the band relaxes and the clamp bounds the confined face like any other.
+ *
+ * Reads the uniforms `step` (`FLUID_MAC_STEP_STRUCT`) and `parent`, and the parent's faces
+ * (`chunk_fluid_cascade_parent_velocity`), whose read is at the step's start; the band reads 8 parent
+ * texels a face on its rows, nothing elsewhere.
+ *
+ * Air the far field alone moves is exact through all of it: the identity maps `v_far(t₀)` to
+ * `v_far(t₁)`, the parent reads `v_far(t₀)` there so the band's target is `v_far(t₁)` too, and the
+ * clamp holds what is already at its centre.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_fluid_cascade_epilogue = CodeChunk.from(
+    //language=WGSL
+    `
+const FLUID_CASCADE_BAND_FIRST_ROW = ${FLUID_CASCADE_BAND_FIRST_ROW};
+const FLUID_CASCADE_BAND_LAST_ROW = ${FLUID_CASCADE_BAND_LAST_ROW};
+
+fn fluid_atmosphere_identity(v: f32, far_start: f32, far_end: f32, keep: f32) -> f32 {
+    return far_end + (v - far_start) * keep;
+}
+
+fn fluid_relaxation_weight(row: i32) -> f32 {
+    if (row < FLUID_CASCADE_BAND_FIRST_ROW || row > FLUID_CASCADE_BAND_LAST_ROW) {
+        return 0.0;
+    }
+
+    return f32(6 - row) / 40.0;
+}
+
+fn fluid_deviation_clamp(v: f32, far: f32, limit: f32) -> f32 {
+    return clamp(v, far - limit, far + limit);
+}
+
+fn fluid_mac_face_row_u(face: vec3<i32>) -> i32 {
+    let n = vec3<i32>(step.cells.size);
+    let along = min(face.x, n.x - face.x);
+    let across = min(min(face.y, n.y - 1 - face.y), min(face.z, n.z - 1 - face.z));
+
+    return 1 + min(along, across);
+}
+
+fn fluid_mac_face_row_v(face: vec3<i32>) -> i32 {
+    let n = vec3<i32>(step.cells.size);
+    let along = min(face.y, n.y - face.y);
+    let across = min(min(face.x, n.x - 1 - face.x), min(face.z, n.z - 1 - face.z));
+
+    return 1 + min(along, across);
+}
+
+fn fluid_mac_face_row_w(face: vec3<i32>) -> i32 {
+    let n = vec3<i32>(step.cells.size);
+    let along = min(face.z, n.z - face.z);
+    let across = min(min(face.x, n.x - 1 - face.x), min(face.y, n.y - 1 - face.y));
+
+    return 1 + min(along, across);
+}
+
+fn fluid_mac_epilogue_u(face: vec3<i32>, value: f32, push: f32) -> f32 {
+    var v = fluid_atmosphere_identity(value, step.far_velocity.x, step.far_velocity_end.x, step.keep) + push;
+
+    let weight = select(0.0, fluid_relaxation_weight(fluid_mac_face_row_u(face)), step.band != 0u);
+
+    if (weight > 0.0) {
+        let toward = fluid_atmosphere_identity(fluid_parent_face_u(face, step.cells.corner - parent.origin), step.far_velocity.x, step.far_velocity_end.x, step.keep);
+
+        v += weight * (toward - v);
+    }
+
+    return fluid_deviation_clamp(v, step.far_velocity_end.x, step.deviation_limit);
+}
+
+fn fluid_mac_epilogue_v(face: vec3<i32>, value: f32, push: f32) -> f32 {
+    var v = fluid_atmosphere_identity(value, step.far_velocity.y, step.far_velocity_end.y, step.keep) + push;
+
+    let weight = select(0.0, fluid_relaxation_weight(fluid_mac_face_row_v(face)), step.band != 0u);
+
+    if (weight > 0.0) {
+        let toward = fluid_atmosphere_identity(fluid_parent_face_v(face, step.cells.corner - parent.origin), step.far_velocity.y, step.far_velocity_end.y, step.keep);
+
+        v += weight * (toward - v);
+    }
+
+    return fluid_deviation_clamp(v, step.far_velocity_end.y, step.deviation_limit);
+}
+
+fn fluid_mac_epilogue_w(face: vec3<i32>, value: f32, push: f32) -> f32 {
+    var v = fluid_atmosphere_identity(value, step.far_velocity.z, step.far_velocity_end.z, step.keep) + push;
+
+    let weight = select(0.0, fluid_relaxation_weight(fluid_mac_face_row_w(face)), step.band != 0u);
+
+    if (weight > 0.0) {
+        let toward = fluid_atmosphere_identity(fluid_parent_face_w(face, step.cells.corner - parent.origin), step.far_velocity.z, step.far_velocity_end.z, step.keep);
+
+        v += weight * (toward - v);
+    }
+
+    return fluid_deviation_clamp(v, step.far_velocity_end.z, step.deviation_limit);
+}
+`, [
+        chunk_fluid_cascade_parent_velocity,
+    ]
+);

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

@@ -0,0 +1,41 @@
+/**
+ * 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;
+/**
+ * `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;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_fluid_cascade_parent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_fluid_cascade_parent.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/coupling/chunk_fluid_cascade_parent.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,kDAFU,SAAS,CAiIjB;AAEF;;;;;;;;;;;;;;;GAeG;AACH,kDAFU,SAAS,CAmDjB;0BAxOwB,oCAAoC"}