@woosh/meep-engine 2.156.0 → 2.158.0

package/src/engine/physics/fluid/REVIEW_02_PLAN.md

@@ -0,0 +1,243 @@
+# Fluid review 02 — quality-gated solver upgrades
+
+Working doc for the staged execution of the 2026-06-12 fluid review. Each stage
+must leave `quality.spec.js` green; when a stage improves a metric its baseline
+is tightened in the same change. Constraints: single-core JS, real-time ECS,
+public API of effectors + `FluidField` frozen (state shape may change).
+
+## Quality gate baselines (quality.spec.js)
+
+| metric | stage 0 (baseline) | stage 2 | stage 3+4 | **stage 5 (MAC)** | notes |
+|---|---|---|---|---|---|
+| projection linear residual, SOR | 1.21 | 0.67 | 0.67 | 0.92 | 8 sweeps @ 16³; RHS grew 14.5→17.8 with face differencing |
+| projection linear residual, PCG | 3.34e-2 | 1.16e-2 | 1.16e-2 | 1.39e-2 | iteration/tolerance-capped |
+| cold post-div | 11.2 | 9.1 | 9.1 | **0.91 / 1.4e-2** | SOR / PCG. Now EQUALS the linear residual: D∘G ≡ L, the operator floor is gone |
+| warm post-div, SOR | 9.22 | 0.70 | 0.35 | **9.6e-3** | 1000× vs stage 0 |
+| warm post-div, PCG | 1.84 | 0.70 | 0.35 | **3.1e-5** | |
+| vortex KE retention (60 steps) | 0.498 | 0.495 | 0.527 | 0.530 | sealed box, default SL+reflection |
+| vortex peak-ω retention | 0.606 | 0.624 | 0.725 | **0.736** | |
+| wall penetration (seed 8) | 5.72 | 6.96 | 6.65 | **0 (exact)** | MAC pins wall-face normal velocity outright |
+| scalar mass retention | 0.231 | 0.849 | 0.837 | 0.818 | residual loss = gather SL + traces through the shell |
+| diffusion wall leak | 16.9 | 0 | 0 | 0 | stage-1 fix holds |
+| sealed-box gravity max\|vy\| | 1.24 | 1.24 | 0.97 | **0.070** | near-exact hydrostatic balance |
+| checkerboard residual (10 steps) | 0.593 | 0.627 | 0.587 | **0.058** | pure compressive mode; collocated was blind to it |
+| damped gravity terminal \|v\| | — | 4.92 = analytic | 4.92 | 4.92 | bounded forcing (was unbounded growth) |
+| atmosphere terminal velocity | — | 8.00/8 | 8.00/8 | (8.00, −5.00) = analytic | GlobalFluidEffector wind+force+drag holds `wind + force/drag` exactly |
+| step() 32×8×32 / 32³ / 64³ (ms) | 1.16 / 4.38 / 54.0 | 1.44 / 5.11 / — | 1.25 / 3.91 / 42.7 | 2.56 / 7.39 / 68.5 | MAC ≈ 2× collocated: 3 lattices + cross-component carriers; levers listed under follow-ups |
+
+Perf reference (review probe, this machine): step() 32×8×32 = 1.16 ms,
+32³ = 4.4 ms, 64³ = 54 ms. Division→reciprocal-table in SOR measured 14%
+SLOWER in V8 — do not do it.
+
+## Stages
+
+- [x] **Stage 0 — quality gate.** `quality.spec.js`: 8 deterministic scenarios,
+  baselines baked, runs by default (no timing). Deep sweeps stay in
+  `bench.spec.js`.
+- [x] **Stage 1 — bug fixes.** (183 fluid tests green; quality gate unchanged
+  except the leak metric dropping to exactly 0.)
+  - Wake effector: trail advance moves out of `apply()` for transform-managed
+    effectors (multi-field contract).
+  - Diffusion: no-flux at solid neighbours (walls stop acting as
+    sources/sinks); neighbour mask recomputed once at top of `step()`.
+  - `FluidField.shift`: migrate the solid mask (zero-fill exposed cells)
+    instead of clearing it — removes the one-tick wall-less window after every
+    re-anchor shift.
+  - PCG: relative-tolerance early exit (cap unchanged).
+- [x] **Stage 2 — boundary semantics + forcing stability.** (195 fluid tests
+  green. New `FluidField.pressure_diag` derived buffer carries the per-cell
+  Laplacian diagonal; mask kernel bakes both in one pass.)
+  - Domain edges are OPEN (ghost p = 0): out-of-bounds faces count in the
+    Laplacian diagonal and read zero pressure; solid faces stay reflecting
+    (Neumann). Sealed boxes are built explicitly with solid cells (see
+    `seal_box` in quality.spec.js).
+  - PCG null-space mean-subtraction made conditional — only for fully sealed
+    fields (open systems are non-singular; subtracting the mean there would
+    solve a different RHS). Disconnected sealed pockets remain a documented
+    limitation.
+  - `velocity_damping` knob on the simulator (exponential, default 0) — the
+    solver's only energy sink under sustained forcing; gives constant forces
+    a terminal velocity.
+  - New ambient-wind drive — relaxes toward a target wind velocity instead of
+    integrating constant acceleration (no unbounded accumulation; frame-rate
+    independent). Shipped first as a separate `AmbientWindFluidEffector`,
+    later UNIFIED into `GlobalFluidEffector` as the `wind` + `drag` fields of
+    the atmosphere model `dv/dt = force + drag·(wind − v)` (exact-ODE
+    integrator, terminal velocity `wind + force/drag`) — one global effector
+    instead of two competing ones.
+- [x] **Stage 3 — transport quality.** (213 tests green.)
+  - Fused 3-channel trilinear sampler (`scs3d_sample_linear3`); generalized
+    SL velocity kernel with separate carrier; MacCormack velocity + scalar
+    kernels with Selle's monotone limiter; `AdvectionScheme` enum;
+    `advection_reflection` step structure (Zehnder 2018, half-step form).
+  - **Measured scheme matrix** (sealed vortex, ke / peak-ω retention @ 1 s;
+    step ms @ 32×8×32):
+    | combo | ke | ω | ms | 10 s stability |
+    |---|---|---|---|---|
+    | SL (Stam baseline) | 0.495 | 0.624 | 0.92 | stable |
+    | **SL + reflection (DEFAULT)** | 0.527 | 0.725 | 1.10 | stable (peak 0.99) |
+    | MacCormack | 0.773 | 0.640 | 1.35 | **unstable** (peak 1.91) |
+    | MacCormack + reflection | 1.016 | 1.081 | 2.49 | **unstable** (peak 3.44) |
+  - **Key negative finding:** on the collocated grid, MacCormack's
+    anti-diffusive corrector amplifies the projection's operator-floor
+    residue — transient energy growth ×1.9–3.4 within 10 s, and passive
+    scalar total mass inflates ×1.8 in one second. Damping 0.2 does not tame
+    it. The kernels are correct in isolation (specs); the INTERACTION with
+    the collocated pressure floor is the problem. **MacCormack is therefore
+    default-off and gated on MAC staggering** — this is the strongest
+    argument yet for stage 5.
+  - Defaults: `advection_scheme = SEMI_LAGRANGIAN`,
+    `advection_reflection = true`. Reflection alone is a clean win: stable,
+    +20% step cost, warm steady-state divergence halves again (0.71 → 0.35),
+    sealed-gravity settles better (1.24 → 0.97).
+- [x] **Stage 4 — perf polish (bench-gated).** (219 tests green; quality gate
+  bit-identical.)
+  - SOR interior fast path (`mask === 63` → branch-free constant-diagonal
+    body, no diag read): measured **37% faster** per solve at 64³, noise-level
+    at 32×8×32, bit-identical results. Adopted.
+  - Rejected by measurement (stage-0 probe): division → reciprocal-table in
+    the SOR update was 14% SLOWER in V8. Recorded so nobody retries it.
+  - `vorticity_confinement` knob (Fedkiw 2001), default off — two O(N) passes
+    on existing scratch when enabled; pairs with `velocity_damping`.
+  - Final step() medians (this machine): 32×8×32 = 1.25 ms, 32³ = 3.91 ms,
+    64³ = 42.7 ms — at 32³ and up faster than the stage-0 baseline despite
+    reflection being on.
+- [x] **Stage 5 — MAC staggering migration (user-approved).** 223 tests green.
+  - Layout: `velocity_x/y/z` are face lattices ((rx+1)·ry·rz etc.); new derived
+    `face_solid_x/y/z` pin masks (either adjacent cell solid → face velocity is
+    a boundary condition). `setVelocityAt`/`addVelocityAt` write both faces per
+    axis; `sampleVelocity` interpolates per staggered lattice. Public
+    signatures unchanged.
+  - Kernels: new `v3_mac_*` divergence / gradient / SL + MacCormack advection
+    (velocity + scalar) / face-solid / vorticity confinement. The pressure
+    solvers and the mask/diag builder needed ZERO changes — stage 2's
+    open-boundary diagonal already was the MAC system. The legacy `v3_grid_*`
+    collocated kernels remain as standalone utilities with their specs.
+  - Exactness confirmed by the gate: cold post-divergence == linear residual
+    (D∘G ≡ L); wall-face penetration exactly 0; hydrostatic balance to 0.07;
+    the compressive checkerboard is annihilated (0.59 → 0.058).
+  - Scheme matrix on MAC: MC velocity is now long-horizon STABLE (10 s peak
+    0.96 vs collocated 1.9×), but (a) MC+reflection still pumps (3.6×) and
+    (b) MC SCALAR transport still inflates mass ~1.7× — back-traces sample
+    through solid walls and the corrector amplifies the bleed. Defaults stay
+    SL + reflection; MacCormack documented opt-in.
+  - Perf: 2.56 / 7.39 / 68.5 ms at 32×8×32 / 32³ / 64³ (~2× collocated). The
+    SL kernel's cross-component carrier reconstruction was optimized from
+    general trilinear to the exact fixed 4-tap MAC average (−31..39% step),
+    pinned by a trilinear-reference equivalence spec.
+
+## Phase A (post-MAC) — solid-aware traces + MacCormack default. DONE.
+
+- Back-traces (and MacCormack probes) are CLIPPED against solid cells
+  (`v3_mac_clip_trace`, bisection); scalar samples are solid-MASKED with
+  weight renormalization (`v3_grid_sample_scalar_masked`). Kills momentum
+  tunnelling through thin walls (spec-pinned) and wall dye bleed.
+- **Negative finding, gate-corrected:** MacCormack SCALAR mass inflation
+  (1.71×) was NOT wall sampling — bit-identical before/after the fix. It is
+  the corrector re-adding ~double the gather bias: intrinsic
+  non-conservation. Scalars are therefore ALWAYS semi-Lagrangian
+  (hard-coded; `advection_scheme` selects the VELOCITY scheme only).
+- MC + reflection re-probed WITH clipping: still pumps (10 s peak 3.7×) —
+  intrinsic to the pairing, stays barred.
+- **Defaults: `advection_scheme = MACCORMACK` (velocity),
+  `advection_reflection = false`.** Gate: vortex KE retention 0.53 → 0.80
+  on the default path; sealed gravity 0.070 → 0.047; warm divergence
+  settles at 2.96e-2 / 2.8e-4 (SOR/PCG — one mid-step projection fewer than
+  SL+refl's 9.6e-3 / 3.1e-5; still ~300× below pre-MAC).
+- **Perf lesson (measured 8.6×!):** V8 refuses to inline loop-bearing
+  callees — calling `v3_mac_clip_trace` per face made the SL kernel 8.6×
+  slower. Hot kernels now inline the straight-line "end cell solid?" test
+  and call the bisection helper only on wall hits (performance contract
+  documented on the helper). Final step(): MC default 2.74 ms @ 32×8×32 /
+  10.4 ms @ 32³; SL+refl 1.97 / 7.35.
+
+## Phase B — FluidObstacleSystem. DONE.
+
+- `FluidObstacle` component (inflation knob) + `FluidObstacleSystem`:
+  voxelizes each (FluidObstacle, Collider, Transform) entity's shape into
+  every overlapping FluidComponent's solid mask per tick, via
+  `PosedShape3D.signed_distance_at_point` (new posed point queries on
+  PosedShape3D, spec'd). Rigid pose — Transform.scale ignored, matching the
+  physics collider convention. Cell solid iff sdf(centre) <= inflation;
+  iteration clipped to the shape AABB.
+- Ownership contract: with >= 1 obstacle the system clears + rebuilds EVERY
+  field's mask each tick (moving obstacles leave no stale walls); with none
+  it touches nothing. Register BEFORE FluidSystem.
+- 8 system tests incl. rotation, inflation-for-thin-walls, origin offset,
+  broad-phase, and a same-tick FluidSystem integration check.
+
+## Phase C — moving-solid face velocity BCs. DONE.
+
+- **Pinned faces are the wall's normal-velocity BC**, not dead storage:
+  - `v3_mac_compute_face_solid` takes the velocity arrays and zeroes a face
+    only on the unpinned→pinned TRANSITION (static-wall default).
+    Pinned→pinned recomputes preserve the stored BC; pinned→unpinned keeps
+    the wall velocity behind as the uncovered fluid's wake seed. Spec'd
+    (`v3_mac_compute_face_solid.spec.js`).
+  - `v3_mac_compute_divergence` reads pinned faces at face value (the
+    face_solid params are gone) — this is the entire transmission mechanism:
+    a stamped wall face shows up as inflow/outflow in the adjacent fluid
+    cell and the projection does the rest.
+  - The pressure gradient, advection, damping and effectors all SKIP pinned
+    faces, so a stamped BC survives the whole step bit-exactly (asserted in
+    quality 8).
+- `FluidObstacleSystem` second pass: per obstacle, the wall velocity is
+  **`RigidBody.linearVelocity`** (world m/s — the obstacle tuple is the full
+  physics tuple FluidObstacle+Collider+RigidBody+Transform); cells it
+  voxelized get all six face slots stamped with the grid-units velocity.
+  The system refreshes each field's masks BEFORE stamping so the transition
+  zeroing is consumed there and the stamped values stick through the
+  simulator's own per-step refresh.
+- **Velocity source rationale** (replaced the initial Transform-delta
+  finite difference in the same session): pose differencing turns teleports
+  (spawn snaps, network corrections) into one-tick air detonations — the
+  exact failure mode BodyKind.KinematicPosition was deferred over in the
+  contact solver. Reading the body instead: air and contacts agree on wall
+  speed, first tick stamps (no `_prev` warm-up), no system-private pose
+  state to lose on snapshot restore, sleeping bodies stamp nothing (solver
+  zeroes velocities on sleep), and `angularVelocity` sits ready for the
+  ω×r follow-up. Pose-animated colliders read as stationary walls that
+  teleport — for air just as for contacts; movers go through
+  KinematicVelocity/Dynamic. Teleport spec pins the no-blast contract.
+- **Stop transition**: a wall that stops must stamp ONE more pass (zeros)
+  over its faces — pinned values persist by design, so without it the
+  divergence sees phantom inflow forever (`_was_moving` flag; obstacles
+  that never move never pay). Piston spec covers move → push → stop.
+- Rotation-induced surface velocity (ω × r) is NOT modelled — a spinner
+  reads as a translating wall only (documented on the system).
+- Ordering contract: PhysicsSystem → FluidObstacleSystem → FluidSystem.
+- Gate: scenario 8 (piston slab, faces stamped +4, 10 steps) — mean u ahead
+  2.08 baked, wake side 2.60 sign-checked; BC face value asserted == 4
+  after 10 steps. Static scenarios all unchanged.
+
+## Follow-ups (ordered by leverage)
+
+1. **Obstacle voxelization change detection** — static scenes currently pay
+   the full clear+rebuild every tick.
+2. **MC + reflection** — only via the second-order advection-reflection
+   formulation (Narain et al. 2019, implicit-midpoint form); the naive
+   pairing re-injects corrector overshoots (3.7×, with or without clipping).
+3. **bench.spec.js MAC refresh** — the `.skip` suites run, but the
+   per-primitive sections still measure the legacy collocated kernels.
+4. **ω × r surface velocity for rotating obstacles** — needs per-cell wall
+   velocity instead of one translation vector per obstacle; same stamping
+   machinery, finer-grained source.
+
+## Review findings driving this (2026-06-12 session)
+
+1. WakeFluidEffector mutates trail state in `apply()` → second field in the
+   same step sees a zero segment (confirmed: A=240, B=0).
+2. `v3_grid_apply_diffusion` gathers from solid neighbours → dye leak 16.9/100
+   through a wall in one step (confirmed).
+3. `FluidSystem` re-anchor shifts clear solids, then step runs immediately —
+   one tick with no walls per cell crossing.
+4. Closed Neumann edges + one-sided boundary divergence: uniform body force
+   produces zero discrete divergence → projection never opposes it → velocity
+   grows without bound (confirmed: −5/−10/−15 over 30/60/90 steps). No damping
+   term exists anywhere.
+5. Collocated grid: compact Laplacian ≠ div∘grad → checkerboard null mode
+   (interior div exactly 0 for ±1 mode, confirmed) + operator floor (cold
+   post-div 11.2 of 14.5 even with exact linear solve).
+6. Advection backtrace samples through/inside solids.
+7. PCG always runs the full SOR-scaled iteration budget (no tolerance exit);
+   mean-subtraction assumes a single connected fluid component.

package/src/engine/physics/fluid/ecs/FluidComponent.d.ts

@@ -56,9 +56,10 @@ export class FluidComponent {
     /**
      * Half-cell extra margin (in cells) the Transform must cross before the field
      * re-quantizes to the next cell. Without it, a Transform jittering right on the
-     * boundary between two cells would re-shift every frame, repeatedly clearing the
-     * solid mask and patching velocity edges — visible as flicker in the fluid and
-     * thrashing in any solid-voxelizer downstream of the shift.
+     * boundary between two cells would re-shift every frame, sloshing every buffer
+     * back and forth and re-extrapolating the exposed edges each time — visible as
+     * flicker in the fluid and thrashing in any solid-voxelizer downstream of the
+     * shift.
      *
      * Mechanism: the system keeps the current quantized cell `q` and only re-quantizes
      * when `|transform.position / cell_size - q| > 0.5 + hysteresis`. Crossing the

package/src/engine/physics/fluid/ecs/FluidComponent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FluidComponent.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidComponent.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAEI;;OAEG;IACH,OAFU,UAAU,CAEK;IAEzB;;;;;;;OAOG;IACH,QAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEf;IAEnB;;;;;;;;OAQG;IACH,QAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEf;IAEnB;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,SAFU,OAAO,CAEF;IAEf;;;;;OAKG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;OAOG;IACH,iBANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAQhC;IAED;;;;;;;OAOG;IACH,iBANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAOhC;IAED;;;;;;;;;;;;;;OAcG;IACH,2BANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAQhC;IAED;;;;;;;OAOG;IACH,0BANW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACL,MAAM,CAQjB;IAED;;;OAGG;IACH,cAHW,cAAc,GACb,OAAO,CAoBlB;IAED;;OAEG;IACH,QAFY,MAAM,CAgBjB;IAED;;;;;;;;OAQG;IACH,iCAYC;IAGL,0BAAyC;CAFxC;2BAzO0B,kBAAkB"}
+{"version":3,"file":"FluidComponent.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidComponent.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAEI;;OAEG;IACH,OAFU,UAAU,CAEK;IAEzB;;;;;;;OAOG;IACH,QAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEf;IAEnB;;;;;;;;OAQG;IACH,QAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEf;IAEnB;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,SAFU,OAAO,CAEF;IAEf;;;;;OAKG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;OAOG;IACH,iBANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAQhC;IAED;;;;;;;OAOG;IACH,iBANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAOhC;IAED;;;;;;;;;;;;;;OAcG;IACH,2BANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAQhC;IAED;;;;;;;OAOG;IACH,0BANW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACL,MAAM,CAQjB;IAED;;;OAGG;IACH,cAHW,cAAc,GACb,OAAO,CAoBlB;IAED;;OAEG;IACH,QAFY,MAAM,CAgBjB;IAED;;;;;;;;OAQG;IACH,iCAYC;IAGL,0BAAyC;CAFxC;2BA1O0B,kBAAkB"}

package/src/engine/physics/fluid/ecs/FluidComponent.js

@@ -65,9 +65,10 @@ export class FluidComponent {
     /**
      * Half-cell extra margin (in cells) the Transform must cross before the field
      * re-quantizes to the next cell. Without it, a Transform jittering right on the
-     * boundary between two cells would re-shift every frame, repeatedly clearing the
-     * solid mask and patching velocity edges — visible as flicker in the fluid and
-     * thrashing in any solid-voxelizer downstream of the shift.
+     * boundary between two cells would re-shift every frame, sloshing every buffer
+     * back and forth and re-extrapolating the exposed edges each time — visible as
+     * flicker in the fluid and thrashing in any solid-voxelizer downstream of the
+     * shift.
      *
      * Mechanism: the system keeps the current quantized cell `q` and only re-quantizes
      * when `|transform.position / cell_size - q| > 0.5 + hysteresis`. Crossing the

package/src/engine/physics/fluid/ecs/FluidObstacle.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Marks an entity's {@link Collider} as a fluid obstacle: each fixed update,
+ * {@link FluidObstacleSystem} voxelizes the collider's shape (via its signed
+ * distance function, under the entity's rigid `Transform` pose) into the solid
+ * mask of every overlapping {@link FluidComponent}, and stamps the entity's
+ * {@link RigidBody} velocity onto the wall faces as the moving-wall boundary
+ * condition. Wind stops at — and is pushed by — the bodies the physics
+ * already knows about; no separate fluid geometry to author.
+ *
+ * Requirements on the entity (the same tuple {@link PhysicsSystem} uses, so
+ * any physical body qualifies as-is):
+ *   - a `Collider` whose shape implements
+ *     {@link AbstractShape3D#signed_distance_at_point} (all analytic
+ *     primitives do; mesh-ish shapes that don't will throw at voxelization),
+ *   - a `RigidBody` — the wall-velocity source (see the system doc for the
+ *     exact semantics). Static walls use `BodyKind.Static` as usual.
+ *   - a `Transform` for the world pose. Following the collider convention,
+ *     the pose is RIGID — `Transform.scale` is ignored, exactly as the
+ *     physics narrowphase ignores it.
+ *
+ * Entities missing any part of the tuple are not obstacles and are skipped —
+ * standard ECS tuple semantics, nothing throws.
+ *
+ * This component is pure data; the behaviour lives on the system.
+ */
+export class FluidObstacle {
+    /**
+     * Voxelization threshold in WORLD units: a fluid cell becomes solid when
+     * the signed distance from its centre to the shape is `<= inflation`.
+     *
+     * `0` (default) marks exactly the cells whose centres lie inside the
+     * shape. Positive values grow the voxel footprint outward — useful for
+     * thin obstacles that would otherwise slip between cell centres (a wall
+     * thinner than one cell needs `inflation >= cell_size / 2` to voxelize
+     * reliably), or to give the fluid a safety margin around fast movers.
+     * Negative values shrink it.
+     *
+     * @type {number}
+     */
+    inflation: number;
+    /**
+     * True when the previous tick stamped a non-zero wall velocity. A body
+     * that stops (or sleeps — the solver zeroes velocities on sleep) must
+     * stamp once more with zeros to clear its stale moving BC, because
+     * pinned faces preserve their values across mask recomputes by design.
+     * System-private.
+     * @type {boolean}
+     */
+    _was_moving: boolean;
+    /**
+     * @param {FluidObstacle} other
+     * @return {boolean}
+     */
+    equals(other: FluidObstacle): boolean;
+    /**
+     * @return {number}
+     */
+    hash(): number;
+    toJSON(): {
+        inflation: number;
+    };
+    fromJSON(json: any): void;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isFluidObstacle: boolean;
+}
+export namespace FluidObstacle {
+    let typeName: string;
+}
+//# sourceMappingURL=FluidObstacle.d.ts.map

package/src/engine/physics/fluid/ecs/FluidObstacle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FluidObstacle.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidObstacle.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAEI;;;;;;;;;;;;OAYG;IACH,WAFU,MAAM,CAEF;IAEd;;;;;;;OAOG;IACH,aAFU,OAAO,CAEG;IAEpB;;;OAGG;IACH,cAHW,aAAa,GACZ,OAAO,CAUlB;IAED;;OAEG;IACH,QAFY,MAAM,CAIjB;IAED;;MAIC;IAED,0BAEC;IASL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;CAZtC;;kBAIS,MAAM"}

package/src/engine/physics/fluid/ecs/FluidObstacle.js

@@ -0,0 +1,97 @@
+import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
+
+/**
+ * Marks an entity's {@link Collider} as a fluid obstacle: each fixed update,
+ * {@link FluidObstacleSystem} voxelizes the collider's shape (via its signed
+ * distance function, under the entity's rigid `Transform` pose) into the solid
+ * mask of every overlapping {@link FluidComponent}, and stamps the entity's
+ * {@link RigidBody} velocity onto the wall faces as the moving-wall boundary
+ * condition. Wind stops at — and is pushed by — the bodies the physics
+ * already knows about; no separate fluid geometry to author.
+ *
+ * Requirements on the entity (the same tuple {@link PhysicsSystem} uses, so
+ * any physical body qualifies as-is):
+ *   - a `Collider` whose shape implements
+ *     {@link AbstractShape3D#signed_distance_at_point} (all analytic
+ *     primitives do; mesh-ish shapes that don't will throw at voxelization),
+ *   - a `RigidBody` — the wall-velocity source (see the system doc for the
+ *     exact semantics). Static walls use `BodyKind.Static` as usual.
+ *   - a `Transform` for the world pose. Following the collider convention,
+ *     the pose is RIGID — `Transform.scale` is ignored, exactly as the
+ *     physics narrowphase ignores it.
+ *
+ * Entities missing any part of the tuple are not obstacles and are skipped —
+ * standard ECS tuple semantics, nothing throws.
+ *
+ * This component is pure data; the behaviour lives on the system.
+ */
+export class FluidObstacle {
+
+    /**
+     * Voxelization threshold in WORLD units: a fluid cell becomes solid when
+     * the signed distance from its centre to the shape is `<= inflation`.
+     *
+     * `0` (default) marks exactly the cells whose centres lie inside the
+     * shape. Positive values grow the voxel footprint outward — useful for
+     * thin obstacles that would otherwise slip between cell centres (a wall
+     * thinner than one cell needs `inflation >= cell_size / 2` to voxelize
+     * reliably), or to give the fluid a safety margin around fast movers.
+     * Negative values shrink it.
+     *
+     * @type {number}
+     */
+    inflation = 0;
+
+    /**
+     * True when the previous tick stamped a non-zero wall velocity. A body
+     * that stops (or sleeps — the solver zeroes velocities on sleep) must
+     * stamp once more with zeros to clear its stale moving BC, because
+     * pinned faces preserve their values across mask recomputes by design.
+     * System-private.
+     * @type {boolean}
+     */
+    _was_moving = false;
+
+    /**
+     * @param {FluidObstacle} other
+     * @return {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+        if (other === null || other === undefined || other.isFluidObstacle !== true) {
+            return false;
+        }
+        return this.inflation === other.inflation;
+    }
+
+    /**
+     * @return {number}
+     */
+    hash() {
+        return computeHashFloat(this.inflation);
+    }
+
+    toJSON() {
+        return {
+            inflation: this.inflation,
+        };
+    }
+
+    fromJSON(json) {
+        if (json.inflation !== undefined) this.inflation = json.inflation;
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+FluidObstacle.typeName = "FluidObstacle";
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+FluidObstacle.prototype.isFluidObstacle = true;

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -0,0 +1,117 @@
+/**
+ * ECS system that voxelizes collider geometry into fluid solid masks and
+ * stamps rigid-body velocities onto the walls as moving-wall boundary
+ * conditions.
+ *
+ * Every fixed update, each entity carrying ({@link FluidObstacle},
+ * {@link Collider}, {@link RigidBody}, {@link Transform}) — the same tuple
+ * {@link PhysicsSystem} simulates, plus the marker — is swept against every
+ * {@link FluidComponent}: the collider's shape — posed rigidly at the
+ * transform's position/rotation via {@link PosedShape3D} — is sampled at the
+ * centre of every fluid cell inside its world AABB, and cells whose signed
+ * distance is `<= obstacle.inflation` become solid. The fluid then treats
+ * those cells exactly like hand-authored walls: faces pinned, pressure
+ * Neumann, traces clipped.
+ *
+ * **Ownership contract**: while at least one obstacle exists, this system
+ * OWNS the solid mask of every fluid field — masks are cleared and rebuilt
+ * from scratch each tick, so moving obstacles leave no stale walls behind.
+ * Hand-written `setSolidAt` state will be wiped; mix the two styles only by
+ * expressing the static geometry as obstacle entities too (a `BoxShape3D`
+ * collider is cheaper to author than a splat loop anyway). With NO obstacles
+ * present the system leaves every mask untouched.
+ *
+ * **Moving walls — the wall-velocity specification**:
+ *
+ *   - The velocity source is `RigidBody.linearVelocity` (world m/s) — the
+ *     SAME value the contact solver resolves against, so air and contacts
+ *     always agree on how fast a wall moves. It is stamped onto every face
+ *     of every cell the obstacle voxelized (converted to grid units per
+ *     field); the projection's divergence reads pinned faces at face value,
+ *     so a moving collider genuinely pushes and drags the air around it.
+ *   - Pose is still read from `Transform`; velocity is NOT derived from
+ *     pose deltas. A teleported body (spawn snap, network correction)
+ *     relocates its walls but stamps no velocity — no one-tick air blast.
+ *     This mirrors the engine's own contact-solver rule: see
+ *     {@link BodyKind}.KinematicPosition, deferred for exactly this reason.
+ *     Consequently pose-animated colliders read as stationary walls that
+ *     teleport, for air just as for contacts — drive movers through
+ *     `BodyKind.KinematicVelocity` (or Dynamic) to displace air.
+ *   - `BodyKind.Static` bodies have zero velocity and stamp nothing.
+ *     Sleeping bodies stamp nothing either — the solver zeroes velocities
+ *     on sleep.
+ *   - A body that stops stamps ONE extra pass of zeros
+ *     (`FluidObstacle._was_moving`): pinned faces preserve their values
+ *     across mask recomputes by design, so without it a stale moving BC
+ *     would drive phantom inflow forever.
+ *   - A retreating wall leaves its velocity behind on unpinned faces as the
+ *     wake seed for the fluid that takes its place.
+ *   - Rotation-induced surface velocity (ω × r from
+ *     `RigidBody.angularVelocity`) is not modelled yet — fast spinners read
+ *     as translating walls only (follow-up in REVIEW_02_PLAN.md).
+ *
+ * **Ordering**: register AFTER {@link PhysicsSystem} (so this tick's solved
+ * velocities and integrated poses are read) and BEFORE {@link FluidSystem}
+ * (so the simulation step sees this tick's walls and wall velocities).
+ * Engine systems run in registration order.
+ *
+ * Cost: clearing is O(cells) per field; voxelization is one
+ * `signed_distance_at_point` per cell inside each obstacle's AABB ∩ field.
+ * Static scenes pay the same as moving ones — change detection is a
+ * follow-up (REVIEW_02_PLAN.md) if profiling ever points here.
+ */
+export class FluidObstacleSystem extends System<any, any, any, any, any> {
+    /**
+     * @param {FluidComponent} fluid
+     */
+    static "__#143@#refresh_masks"(fluid: FluidComponent): void;
+    /**
+     * @param {FluidComponent} fluid
+     */
+    static "__#143@#clear_field"(fluid: FluidComponent): void;
+    /**
+     * Mark every cell of `fluid` whose centre lies within `inflation` of the
+     * posed shape as solid. Iteration is clipped to the shape's world AABB
+     * (grown by `inflation`), so far-away obstacles cost nothing.
+     *
+     * @param {FluidComponent} fluid
+     * @param {PosedShape3D} posed
+     * @param {Float64Array} aabb      world AABB of the posed shape
+     * @param {number} inflation       world-units SDF threshold
+     * @param {Float64Array} point     length-3 scratch
+     */
+    static "__#143@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    /**
+     * Write the obstacle's translation velocity onto every face of every cell
+     * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
+     * refresh, so the values stick (already-pinned faces keep their stored
+     * velocity through subsequent recomputes).
+     *
+     * Velocity is converted to grid units (cells/second) per field. Where
+     * obstacles overlap, the later-visited one wins on shared faces — both
+     * claims are walls, the disagreement is sub-cell.
+     *
+     * @param {FluidComponent} fluid
+     * @param {PosedShape3D} posed
+     * @param {Float64Array} aabb
+     * @param {number} inflation
+     * @param {Float64Array} point
+     * @param {number} wvx  world-units-per-second obstacle velocity
+     * @param {number} wvy
+     * @param {number} wvz
+     */
+    static "__#143@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    constructor();
+    dependencies: (typeof FluidObstacle)[];
+    components_used: (ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];
+    #private;
+}
+import { System } from "../../../ecs/System.js";
+import { FluidObstacle } from "./FluidObstacle.js";
+import { RigidBody } from "../../ecs/RigidBody.js";
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { Collider } from "../../ecs/Collider.js";
+import { Transform } from "../../../ecs/transform/Transform.js";
+import { FluidComponent } from "./FluidComponent.js";
+import { PosedShape3D } from "../../../../core/geom/3d/shape/PosedShape3D.js";
+//# sourceMappingURL=FluidObstacleSystem.d.ts.map

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FluidObstacleSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidObstacleSystem.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH;IA+GI;;OAEG;IACH,sCAFW,cAAc,QAIxB;IAED;;OAEG;IACH,oCAFW,cAAc,QAOxB;IAED;;;;;;;;;;OAUG;IACH,iCANW,cAAc,SACd,YAAY,QACZ,YAAY,aACZ,MAAM,SACN,YAAY,QAiDtB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,4CATW,cAAc,SACd,YAAY,QACZ,YAAY,aACZ,MAAM,SACN,YAAY,OACZ,MAAM,OACN,MAAM,OACN,MAAM,QAqEhB;IAxVe,cAAmB;IAwEnC,uCAA+B;IAE/B,2QAOE;;CAwQL;uBAxVsB,wBAAwB;8BAKjB,oBAAoB;0BAFxB,wBAAwB;4CAJN,uDAAuD;yBAG1E,uBAAuB;0BADtB,qCAAqC;+BAGhC,qBAAqB;6BAPvB,gDAAgD"}