@woosh/meep-engine 3.24.0 → 3.25.0

package/src/engine/physics/cloth/ecs/cloth_gather_colliders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_gather_colliders.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_gather_colliders.js"],"names":[],"mappings":"AA8BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;;;GAQG;AACH,kGAHW,MAAM,GACJ,MAAM,CAsJlB;AAgDD;;;;;;;;;;;;GAYG;AACH,2FAFa,OAAO,CAsBnB"}
+{"version":3,"file":"cloth_gather_colliders.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_gather_colliders.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH;;;;;;;;GAQG;AACH,kGAHW,MAAM,GACJ,MAAM,CA2JlB;AAgDD;;;;;;;;;;;;GAYG;AACH,2FAFa,OAAO,CAsBnB"}

package/src/engine/physics/cloth/ecs/cloth_gather_colliders.js

@@ -27,6 +27,7 @@ import {
     CCR_TZ
 } from "../collider/ClothColliderRecord.js";
 import { cloth_collider_refit_bounds } from "../collider/cloth_collider_bounds.js";
+import { CLOTH_COLLIDER_SLOTS } from "../solver/cloth_solver_constants.js";
 
 /**
  * # Bringing the world's colliders into a cloth's frame
@@ -59,6 +60,24 @@ import { cloth_collider_refit_bounds } from "../collider/cloth_collider_bounds.j
  * it was gathered for; it is the velocity clamp of §7 P1 read as a distance,
  * which is the quantity it was built out of.
  *
+ * ## Where the table lives, and why it stopped growing
+ *
+ * In `ClothState`'s single buffer, {@link CLOTH_COLLIDER_SLOTS} records of it,
+ * which is §12's own layout. M2 grew a per-instance array instead, because the
+ * size is a property of the world rather than of the cloth — still true, and
+ * still not the deciding argument. M5's worker steps the cloth out of shared
+ * memory, and an array that can be replaced mid-run is memory the worker would
+ * have to be told about again before it could be named. A fixed region makes the
+ * two systems read the same bytes by construction.
+ *
+ * A cloth whose broadphase returns more than the capacity keeps the first
+ * {@link CLOTH_COLLIDER_SLOTS} the index hands back and says so once. That is
+ * arbitrary among the overflow — the index answers in its own order — which is
+ * why it warns rather than trusting a rule it does not have, and why the
+ * capacity is set well clear of what a scene reaches. `MEASUREMENTS.md` §41 is
+ * what the library's garments actually reach, and the answer is that they reach
+ * whatever the characters around them carry.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -66,8 +85,8 @@ import { cloth_collider_refit_bounds } from "../collider/cloth_collider_bounds.j
 /**
  * Query the index and rewrite the overlapping colliders into the cloth's frame.
  *
- * @param {ClothInstance} instance filled in place — `collider_table`,
- *   `collider_key` and `collider_count`
+ * @param {ClothInstance} instance read for its anchor pose and filter; its
+ *   state's `collider_table`, `collider_key` and `collider_count` are filled
  * @param {ClothColliderIndex} index
  * @param {number} reach how far a particle may travel this step, metres
  * @returns {number} how many colliders were gathered
@@ -101,7 +120,7 @@ export function cloth_gather_colliders(instance, index, reach) {
     }
 
     if (particle_count === 0) {
-        instance.collider_count = 0;
+        state.collider_count = 0;
 
         return 0;
     }
@@ -160,25 +179,30 @@ export function cloth_gather_colliders(instance, index, reach) {
 
     const cloth = instance.cloth;
 
-    const found = index.query(
+    const overlapping = index.query(
         HANDLES, world_min_x, world_min_y, world_min_z,
         world_max_x, world_max_y, world_max_z,
         cloth.layer, cloth.mask
     );
 
-    if (instance.collider_table === null || instance.collider_table.length < found * CCR_STRIDE) {
-        let capacity = 8;
+    let found = overlapping;
 
-        while (capacity < found) {
-            capacity *= 2;
-        }
+    if (found > CLOTH_COLLIDER_SLOTS) {
+        found = CLOTH_COLLIDER_SLOTS;
+
+        if (!instance.collider_overflow_reported) {
+            instance.collider_overflow_reported = true;
 
-        instance.collider_table = new Float32Array(capacity * CCR_STRIDE);
-        instance.collider_key = new Int32Array(capacity);
+            console.warn(
+                `ClothSystem: entity ${instance.entity} overlaps ${overlapping} cloth colliders and the`
+                + ` per-cloth table holds ${CLOTH_COLLIDER_SLOTS}; the rest are not collided against.`
+                + ` Narrow the cloth's layer/mask, or split the collider.`
+            );
+        }
     }
 
-    const table = instance.collider_table;
-    const keys = instance.collider_key;
+    const table = state.collider_table;
+    const keys = state.collider_key;
 
     const source = index.table;
 
@@ -217,7 +241,7 @@ export function cloth_gather_colliders(instance, index, reach) {
         cloth_collider_refit_bounds(table, i, CCR_STRIDE);
     }
 
-    instance.collider_count = found;
+    state.collider_count = found;
 
     return found;
 }
@@ -284,7 +308,7 @@ function localise(
 export function cloth_colliders_moved(instance, index) {
     const found = cloth_gather_colliders(instance, index, 0);
 
-    const table = instance.collider_table;
+    const table = instance.state.collider_table;
 
     for (let i = 0; i < found; i++) {
         const r = i * CCR_STRIDE;

package/src/engine/physics/cloth/ecs/cloth_worker_protocol.d.ts

@@ -0,0 +1,29 @@
+/**
+ * First word of the `index`-th cloth's parameter block.
+ *
+ * @param {number} index
+ * @returns {number}
+ */
+export function cloth_command_offset(index: number): number;
+/**
+ * Size the command region for a ceiling on simultaneously stepped cloths. The
+ * region is allocated once at startup and cannot grow, which is what makes that
+ * ceiling a constructor argument rather than something discovered at runtime.
+ *
+ * @param {number} max_cloth_count
+ * @returns {number} `Float64` words
+ */
+export function cloth_command_word_count(max_cloth_count: number): number;
+/**
+ * Header words of the command region.
+ */
+export type ClothCommand = number;
+export namespace ClothCommand {
+    let CLOTH_COUNT: number;
+}
+/**
+ * Command words consumed before the first cloth's block.
+ * @type {number}
+ */
+export const CLOTH_COMMAND_HEADER_WORDS: number;
+//# sourceMappingURL=cloth_worker_protocol.d.ts.map

package/src/engine/physics/cloth/ecs/cloth_worker_protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_worker_protocol.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_worker_protocol.js"],"names":[],"mappings":"AAyDA;;;;;GAKG;AACH,4CAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;GAOG;AACH,0DAHW,MAAM,GACJ,MAAM,CAIlB;;;;2BAnCS,MAAM;;;;AAShB;;;GAGG;AACH,yCAFU,MAAM,CAE4B"}

package/src/engine/physics/cloth/ecs/cloth_worker_protocol.js

@@ -0,0 +1,78 @@
+import { CLOTH_STEP_PARAM_STRIDE } from "../solver/cloth_step_instance.js";
+
+/**
+ * # The command region, and what is *not* in it
+ *
+ * Layout of the {@link WorkerSystem} command region used by
+ * {@link WorkerClothSystem}: a count, then one {@link ClothStepParam} block per
+ * cloth to step this tick.
+ *
+ * §12 asks for exactly this shape — "the command region names which instances
+ * are live this step, so sleeping (P5) and culled (§12.1) instances cost nothing
+ * but their absence from a list" — and for `ClothDynamics` to travel with it,
+ * "written every step … cheaper than tracking dirtiness, and it keeps
+ * `cloth.dynamics.slack = 0.2` working live". Both hold. What changed on the way
+ * to being built is that the per-cloth words are not a serialization of
+ * `ClothDynamics` but the **step's own parameter block** — `dt`, local gravity, a
+ * retention, a clamp — because a cloth's dynamics have already been mapped
+ * through `cloth_dynamics_map.js` by the time the step can use them, and mapping
+ * them on the far side would be a second copy of that mapping with no way to
+ * prove it agreed. `MEASUREMENTS.md` §38.
+ *
+ * The consequence is the useful one: the same block the worker reads is the
+ * block {@link ClothSystem} fills in a private scratch array, so the two systems
+ * do not agree on the numbers, they *share* them.
+ *
+ * ## What travels on the cold plane instead
+ *
+ * A cloth's `ClothState` — the particles, the rows, the duals, the collider
+ * table, the pair list. That is a `SharedArrayBuffer` per cloth, registered once
+ * when the cloth seeds and again whenever a re-seed replaces it, and nothing of
+ * it is ever copied: the worker cuts its own views over the same bytes
+ * (`ClothState.fromSharedDescriptor`). §12 asked for one buffer for the whole
+ * cloth world; `MEASUREMENTS.md` §39 is why it is one per cloth.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Header words of the command region.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const ClothCommand = {
+    /**
+     * How many {@link ClothStepParam} blocks follow.
+     */
+    CLOTH_COUNT: 0
+};
+
+/**
+ * Command words consumed before the first cloth's block.
+ * @type {number}
+ */
+export const CLOTH_COMMAND_HEADER_WORDS = 1;
+
+/**
+ * First word of the `index`-th cloth's parameter block.
+ *
+ * @param {number} index
+ * @returns {number}
+ */
+export function cloth_command_offset(index) {
+    return CLOTH_COMMAND_HEADER_WORDS + index * CLOTH_STEP_PARAM_STRIDE;
+}
+
+/**
+ * Size the command region for a ceiling on simultaneously stepped cloths. The
+ * region is allocated once at startup and cannot grow, which is what makes that
+ * ceiling a constructor argument rather than something discovered at runtime.
+ *
+ * @param {number} max_cloth_count
+ * @returns {number} `Float64` words
+ */
+export function cloth_command_word_count(max_cloth_count) {
+    return cloth_command_offset(max_cloth_count);
+}

package/src/engine/physics/cloth/ecs/makeClothWorker.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Spawn the cloth solver worker.
+ *
+ * Isolated in its own module on purpose: `import.meta` is a syntax error under
+ * the CommonJS transform the test runner uses, so any module containing it
+ * cannot be imported by a spec — even transitively. Keeping the expression here
+ * lets {@link WorkerClothSystem} stay testable while application code gets a
+ * one-import default.
+ *
+ * The `new Worker(new URL(...), { type: "module" })` form is what webpack 5
+ * detects statically, so the worker is emitted as a real chunk with its full
+ * dependency graph rather than being assembled at runtime.
+ *
+ * @returns {Worker}
+ */
+export function makeClothWorker(): Worker;
+//# sourceMappingURL=makeClothWorker.d.ts.map

package/src/engine/physics/cloth/ecs/makeClothWorker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"makeClothWorker.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/makeClothWorker.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,mCAFa,MAAM,CAIlB"}

package/src/engine/physics/cloth/ecs/makeClothWorker.js

@@ -0,0 +1,18 @@
+/**
+ * Spawn the cloth solver worker.
+ *
+ * Isolated in its own module on purpose: `import.meta` is a syntax error under
+ * the CommonJS transform the test runner uses, so any module containing it
+ * cannot be imported by a spec — even transitively. Keeping the expression here
+ * lets {@link WorkerClothSystem} stay testable while application code gets a
+ * one-import default.
+ *
+ * The `new Worker(new URL(...), { type: "module" })` form is what webpack 5
+ * detects statically, so the worker is emitted as a real chunk with its full
+ * dependency graph rather than being assembled at runtime.
+ *
+ * @returns {Worker}
+ */
+export function makeClothWorker() {
+    return new Worker(new URL("./cloth.worker.js", import.meta.url), { type: "module" });
+}

package/src/engine/physics/cloth/playground/README.md

@@ -4,7 +4,7 @@
 npm run dev --workspace @woosh/meep-engine
 ```
 
-Four pages, one directory, one layer of the system each. (Vite takes the next
+Five pages, one directory, one layer of the system each. (Vite takes the next
 free port if 5173 is busy — the terminal says which.)
 
 | | |
@@ -13,10 +13,16 @@ free port if 5173 is busy — the terminal says which.)
 | [`rig.html`](./rig.html) | **the entity subtree, M1.** A real `EntityManager`, real entities, `ClothSystem` walking and writing back. |
 | [`collide.html`](./collide.html) | **collision, M2.** The solver again, with a packed collider table in the argument list. |
 | [`garment.html`](./garment.html) | **skinned garments, M3, and self-collision, M4.** A skeleton of entities, a `Skin`, and a `Cloth` + `ClothRig` driving some of its joints. |
+| [`wind.html`](./wind.html) | **wind, M6.** A banner hanging in a real `FluidSimulator`'s wake, reading it through `ClothFluidWind`. |
 
-Both are at
+All are at
 `http://localhost:5173/src/engine/physics/cloth/playground/<page>`.
 
+There is no M5 page, and that is deliberate: a `SharedArrayBuffer` needs a
+cross-origin isolated page and `vite.config.mjs` sends no `COOP`/`COEP`
+(`MEASUREMENTS.md` §44). The worker bridge is tested by
+`SystemWorkerLoopback` instead, more precisely than a page could.
+
 ---
 
 # The solver page — `index.html`
@@ -337,3 +343,68 @@ has the numbers, because it cost an hour to diagnose the first time.
 step_once, draw, scene }`. `rebuild` returns a promise, because
 `EntityManager#startup` does and an entity created before it resolves is never
 linked.
+
+---
+
+# The wind page — `wind.html`
+
+## What it is
+
+§10's argument made watchable, and the word that matters is **simulated**. There
+is no wind model on this page. There is a `FluidField`, a `FluidSimulator`, a
+`GlobalFluidEffector` in its prevailing-wind regime, and a solid post standing in
+the flow; the banner reads the result through exactly the `ClothFluidWind` and
+`cloth_sample_air` a scene uses. The blue threads are the air on a horizontal
+slice through the banner's waist, the red squares are the post.
+
+The cloth is driven like the solver and collision pages — `cloth_step` in
+process, no `EntityManager` — because what is being shown is the air rather than
+the ECS wiring, and `ecs/cloth_wind.spec.js` covers that more precisely.
+
+## Three things to watch rather than read
+
+- **Turn the flow to 90° on `ambient only`.** The banner goes limp at the same
+  wind speed: the *drag accel* readout falls from 43 m/s² to 0.08, and the mean
+  facing factor from 0.221 to 0.000. That is §10's normal-facing factor, and it
+  is the sharpest single result in M6.
+- **Do the same on `fluid field + ambient`, and it does not go limp.** 0.216 at
+  0°, 0.280 at 90°. A wake has velocity in every direction, so no orientation of
+  a banner is edge-on to one — which is something the simulation knows and a wind
+  zone could not have told it.
+- **Take the post away.** The air at the banner goes from 6.0 m/s to 8.7. That
+  31% deficit is the incompressible projection's answer to a solid standing in a
+  flow, and there is no authored falloff anywhere in it.
+
+## The readout
+
+- **cloth step** — `cloth_wind_accelerate` plus `cloth_step`, against §17's 2 ms
+  bar. The wind's own share of it is about one per cent (`MEASUREMENTS.md` §49);
+  everything else on that bar is the solver.
+- **fluid step** — the `FluidSimulator`, which at the default grid is several
+  times the cloth. It is on the page to be honest about where the frame goes: the
+  simulation is the expensive half and cloth is renting it.
+- **air sample** and **sampled** — `cloth_sample_air`. Switch the source to
+  `ambient only` and watch it drop by a factor of twenty-five as "per particle"
+  becomes "once for the cloth". That is §10's "a cloth outside every fluid field's
+  bounds skips it entirely", and it is the reason the fallback is affordable.
+- **drag accel, mean** — the external acceleration with gravity taken back out:
+  the facing factor as a number.
+
+## What it does not show
+
+**A shedding street.** At the grids this page can afford the wake is a *steady*
+velocity deficit — measured at 18, 26 and 34 cells across, with damping and
+vorticity confinement at both ends of their range, the air behind the post varies
+by under 0.03 m/s. The banner's free corner moves twelve times as far per step
+with the post as without, and both of those are settled rather than fluttering.
+That is the fluid solver's answer at this scale rather than the cloth's, and
+`MEASUREMENTS.md` §51 records it so the page is not read as promising something
+it does not do.
+
+## Notes
+
+`globalThis.cloth_wind_playground` exposes `{ control, camera, rebuild,
+step_once, refresh_post, cloth, tunnel, wind, air_centre, sampled_per_particle,
+mean_drag, tripwire, timings }`. Changing `control.yaw` needs a `refresh_post()`
+after it, because the post stands upstream along the flow and only moves when it
+is asked to.

package/src/engine/physics/cloth/playground/wind.html

@@ -0,0 +1,166 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — cloth wind (M6)</title>
+    <style>
+        :root {
+            color-scheme: dark;
+            --ink: #d6dae0;
+            --dim: #8b939f;
+            --line: #2b3038;
+            --panel: #14171c;
+            --warn: #e5b54a;
+            --bad: #e5533d;
+            --good: #5ad19a;
+        }
+
+        html, body {
+            margin: 0;
+            height: 100%;
+            background: #0d0f12;
+            color: var(--ink);
+            font: 12px/1.5 ui-monospace, Consolas, monospace;
+            overflow: hidden;
+        }
+
+        body { display: flex; }
+
+        #stage { position: relative; flex: 1; min-width: 0; }
+        #view { display: block; width: 100%; height: 100%; cursor: grab; }
+        #view.grabbing { cursor: grabbing; }
+
+        #hint {
+            position: absolute; left: 14px; bottom: 12px;
+            color: var(--dim); pointer-events: none;
+        }
+
+        #readout {
+            position: absolute; left: 14px; top: 12px;
+            background: rgba(13, 15, 18, 0.82);
+            border: 1px solid var(--line);
+            padding: 8px 12px;
+            min-width: 288px;
+        }
+
+        #readout table { border-collapse: collapse; width: 100%; }
+        #readout td { padding: 1px 0; white-space: nowrap; }
+        #readout td:last-child { text-align: right; padding-left: 18px; }
+        #readout td:first-child { color: var(--dim); }
+
+        #budget { height: 4px; margin-top: 7px; background: #22262d; position: relative; overflow: hidden; }
+        #budget > i { display: block; height: 100%; background: var(--good); width: 0; }
+        #budget.over > i { background: var(--bad); }
+
+        aside {
+            width: 300px; flex: none;
+            border-left: 1px solid var(--line);
+            background: var(--panel);
+            overflow-y: auto;
+            padding: 12px 14px 40px;
+        }
+
+        h1 { font-size: 13px; margin: 0 0 2px; }
+        h2 {
+            font-size: 11px; margin: 18px 0 6px; color: var(--dim);
+            text-transform: uppercase; letter-spacing: 0.08em; font-weight: normal;
+            border-bottom: 1px solid var(--line); padding-bottom: 4px;
+        }
+        p.blurb { color: var(--dim); margin: 0 0 6px; }
+        a { color: #6fa8dc; }
+
+        label { display: flex; align-items: center; gap: 8px; margin: 5px 0; }
+        label > span:first-child { flex: none; width: 96px; color: var(--dim); }
+        label > input[type=range] { flex: 1; min-width: 0; height: 16px; }
+        label > output { flex: none; width: 62px; text-align: right; }
+        label > select {
+            flex: 1; min-width: 0; background: #0d0f12; color: var(--ink);
+            border: 1px solid var(--line); font: inherit; padding: 2px 4px;
+        }
+
+        .buttons { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 8px; }
+        button {
+            background: #1b1f26; color: var(--ink); border: 1px solid var(--line);
+            font: inherit; padding: 4px 10px; cursor: pointer;
+        }
+        button:hover { background: #232832; }
+        button.on { border-color: var(--warn); color: var(--warn); }
+
+        #tripwire.bad { color: var(--bad); }
+        #tripwire.good { color: var(--good); }
+    </style>
+</head>
+<body>
+
+<div id="stage">
+    <canvas id="view"></canvas>
+
+    <div id="readout">
+        <table>
+            <tr><td>cloth step</td><td><b id="ms">—</b> ms</td></tr>
+            <tr><td>fluid step</td><td><span id="fluid_ms">—</span> ms</td></tr>
+            <tr><td>air sample</td><td><span id="sample_us">—</span> µs</td></tr>
+            <tr><td>sampled</td><td id="sample_mode">—</td></tr>
+            <tr><td>particles / rows</td><td id="counts">—</td></tr>
+            <tr><td>air at the banner</td><td id="air">—</td></tr>
+            <tr><td>drag accel, mean</td><td id="drag_accel">—</td></tr>
+            <tr><td>state</td><td id="tripwire" class="good">ok</td></tr>
+        </table>
+        <div id="budget"><i></i></div>
+    </div>
+
+    <div id="hint">drag to orbit · wheel to zoom · shift-drag to pan · the blue threads are the air, the red squares the post</div>
+</div>
+
+<aside>
+    <h1>Cloth wind — M6</h1>
+    <p class="blurb">
+        §10's argument, made watchable: there is no wind model here. A real
+        <code>FluidField</code>, a real <code>FluidSimulator</code>, a solid post standing in the
+        flow, and a banner reading the result through <code>ClothFluidWind</code> — the same path a
+        scene uses. The other pages are
+        <a href="./index.html">index</a>, <a href="./rig.html">rig</a>,
+        <a href="./collide.html">collide</a> and <a href="./garment.html">garment</a>.
+    </p>
+
+    <h2>Banner</h2>
+    <label><span>fabric</span><select id="fabric"></select></label>
+    <label><span>size</span><input id="size" type="range" min="6" max="28" step="1"><output id="size_out"></output></label>
+    <label><span>spacing</span><input id="spacing" type="range" min="0.02" max="0.09" step="0.005"><output id="spacing_out"></output></label>
+    <label><span>drag</span><input id="drag" type="range" min="0" max="1" step="0.01"><output id="drag_out"></output></label>
+    <label><span>substeps</span><input id="substeps" type="range" min="1" max="6" step="1"><output id="substeps_out"></output></label>
+    <label><span>iterations</span><input id="iterations" type="range" min="1" max="12" step="1"><output id="iterations_out"></output></label>
+
+    <h2>Air</h2>
+    <p class="blurb">
+        On <em>ambient only</em>, turn the flow to 90° and the banner goes limp at the same wind
+        speed — <em>drag accel</em> falls from 43 to 0.08. That is §10's normal-facing factor.
+        On the <em>fluid field</em> it does not go limp: a wake has velocity in every direction,
+        so nothing is edge-on to one. Take the post away and the air at the banner goes from
+        6.0 to 8.7 m/s — that deficit is the projection's answer, not an authored falloff.
+    </p>
+    <label><span>source</span><select id="source">
+        <option value="field">fluid field + ambient</option>
+        <option value="ambient">ambient only</option>
+    </select></label>
+    <label><span>wind</span><input id="speed" type="range" min="0" max="20" step="0.5"><output id="speed_out"></output></label>
+    <label><span>flow angle</span><input id="yaw" type="range" min="0" max="90" step="5"><output id="yaw_out"></output></label>
+    <label><span>ambient gust</span><input id="gust" type="range" min="0" max="6" step="0.1"><output id="gust_out"></output></label>
+    <label><span>grid</span><input id="resolution" type="range" min="8" max="28" step="2"><output id="resolution_out"></output></label>
+
+    <div class="buttons">
+        <button id="post">post</button>
+        <button id="show_field">show the air</button>
+    </div>
+
+    <h2>Run</h2>
+    <div class="buttons">
+        <button id="pause">pause</button>
+        <button id="single">step once</button>
+        <button id="reset">rebuild</button>
+    </div>
+</aside>
+
+<script type="module" src="./wind_main.js"></script>
+</body>
+</html>

package/src/engine/physics/cloth/playground/wind_build.d.ts

@@ -0,0 +1,81 @@
+/**
+ * # The wind tunnel the banner hangs in
+ *
+ * A real {@link FluidField} stepped by a real {@link FluidSimulator}, with a
+ * real {@link GlobalFluidEffector} driving the flow and a solid post standing in
+ * it — which is the whole of §10's argument made visible. Nothing here is a
+ * wind model: the wake behind the post is the incompressible projection's
+ * answer, and the cloth reads it through the same {@link FluidComponent} an
+ * ordinary scene would.
+ *
+ * At the grid a sixty-hertz page can afford the wake is a **steady** velocity
+ * deficit rather than a shedding street — measured at 18, 26 and 34 cells
+ * across, with and without damping and confinement, the air a banner's width
+ * downstream varies by under 0.03 m/s. That is the fluid solver's answer at
+ * this scale rather than the cloth's, and `MEASUREMENTS.md` §49 records it so
+ * the page is not read as promising something it does not do.
+ *
+ * The post is written straight into `FluidField#solid` rather than voxelised by
+ * `FluidObstacle`, because the page has no ECS to hang a `Collider` on and the
+ * obstacle is not what is being demonstrated. `FluidSimulator#step` refreshes
+ * the derived masks itself, so writing the cells is the whole of it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * @typedef {object} WindTunnel
+ * @property {FluidComponent} component the volume, placed in world space
+ * @property {FluidSimulator} simulator
+ * @property {GlobalFluidEffector} effector the prevailing flow
+ * @property {Float32Array} world_to_grid
+ * @property {number} cell_size
+ * @property {number[]} resolution
+ */
+/**
+ * @param {object} options
+ * @param {number} options.cell_size metres
+ * @param {number[]} options.resolution cells along x, y, z
+ * @param {number[]} options.origin world position of cell (0,0,0)'s centre
+ * @returns {WindTunnel}
+ */
+export function build_wind_tunnel({ cell_size, resolution, origin }: {
+    cell_size: number;
+    resolution: number[];
+    origin: number[];
+}): WindTunnel;
+/**
+ * Stand a solid post across the flow, upstream of the banner.
+ *
+ * @param {WindTunnel} tunnel
+ * @param {object} options
+ * @param {boolean} options.present
+ * @param {number} options.x world x of the post's centre
+ * @param {number} options.z world z of the post's centre
+ * @param {number} options.radius metres
+ * @returns {void}
+ */
+export function place_wind_post(tunnel: WindTunnel, { present, x, z, radius }: {
+    present: boolean;
+    x: number;
+    z: number;
+    radius: number;
+}): void;
+export type WindTunnel = {
+    /**
+     * the volume, placed in world space
+     */
+    component: FluidComponent;
+    simulator: FluidSimulator;
+    /**
+     * the prevailing flow
+     */
+    effector: GlobalFluidEffector;
+    world_to_grid: Float32Array;
+    cell_size: number;
+    resolution: number[];
+};
+import { FluidComponent } from "../../fluid/ecs/FluidComponent.js";
+import { FluidSimulator } from "../../fluid/FluidSimulator.js";
+import { GlobalFluidEffector } from "../../fluid/effector/GlobalFluidEffector.js";
+//# sourceMappingURL=wind_build.d.ts.map

package/src/engine/physics/cloth/playground/wind_build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wind_build.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/playground/wind_build.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH;IAL2B,SAAS,EAAzB,MAAM;IACY,UAAU,EAA5B,MAAM,EAAE;IACU,MAAM,EAAxB,MAAM,EAAE;IACN,UAAU,CA2CtB;AAED;;;;;;;;;;GAUG;AACH,wCARW,UAAU;IAEO,OAAO,EAAxB,OAAO;IACS,CAAC,EAAjB,MAAM;IACU,CAAC,EAAjB,MAAM;IACU,MAAM,EAAtB,MAAM;IACJ,IAAI,CAwChB;;;;;eA3Ga,cAAc;eACd,cAAc;;;;cACd,mBAAmB;mBACnB,YAAY;eACZ,MAAM;gBACN,MAAM,EAAE;;+BAnCS,mCAAmC;+BAFnC,+BAA+B;oCAC1B,6CAA6C"}