@woosh/meep-engine 3.22.0 → 3.23.0

package/src/core/geom/3d/shape/sdf/sdf3_cylinder.d.ts

@@ -0,0 +1,60 @@
+/**
+ * # Capped cylinder — signed distance and its analytic gradient
+ *
+ * A cylinder about the **Y axis** of its own frame: `radius` across, `height`
+ * tall, so the flat caps sit at `±height/2`. Inigo Quilez's capped-cylinder
+ * field, written with the radial and axial distances named:
+ *
+ *     s  = ‖(x, z)‖
+ *     dr = s − r                     distance outside the infinite cylinder
+ *     da = |y| − h/2                 distance outside the slab
+ *     d  = ‖max(dr, 0), max(da, 0)‖ + min(max(dr, da), 0)
+ *
+ * The gradient is the two directions the field is built from, blended by how
+ * much of each the point is outside by:
+ *
+ *     û = (x, 0, z)/s                the radial direction
+ *     â = (0, sign(y), 0)            the axial direction
+ *     ∇d = (max(dr,0)·û + max(da,0)·â) / d      outside
+ *     ∇d = û or â, whichever of dr, da is larger        inside
+ *
+ * — which is exactly right on the rim, where both terms are live and the
+ * normalised sum sweeps continuously from the side to the cap.
+ *
+ * ## The axis is degenerate, and not in the way the others are
+ *
+ * On the axis, `û` does not exist. Unlike the sphere and the capsule this is
+ * *not* covered by `sdf3_degenerate_normal.js`'s `+Y`: a long thin cylinder's
+ * nearest exit from a point on its axis is sideways, and `+Y` is the one
+ * direction that is certainly not it. The fallback here is therefore `+X` — an
+ * arbitrary radial direction, which is what the configuration actually is:
+ * every radial direction is equally near and one has to be chosen.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Signed distance from a point to a capped cylinder's surface: negative inside.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} radius
+ * @param {number} height total extent along Y
+ * @returns {number}
+ */
+export function sdf3_cylinder(x: number, y: number, z: number, radius: number, height: number): number;
+/**
+ * Signed distance and the unit outward gradient, written to `out`.
+ *
+ * @param {Float32Array|Float64Array|number[]} out gradient destination
+ * @param {number} out_offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} radius
+ * @param {number} height
+ * @returns {number} the signed distance
+ */
+export function sdf3_cylinder_gradient(out: Float32Array | Float64Array | number[], out_offset: number, x: number, y: number, z: number, radius: number, height: number): number;
+//# sourceMappingURL=sdf3_cylinder.d.ts.map

package/src/core/geom/3d/shape/sdf/sdf3_cylinder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdf3_cylinder.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/sdf/sdf3_cylinder.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;;;;;;;GASG;AACH,iCAPW,MAAM,KACN,MAAM,KACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CAYlB;AAED;;;;;;;;;;;GAWG;AACH,4CATW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CAuDlB"}

package/src/core/geom/3d/shape/sdf/sdf3_cylinder.js

@@ -0,0 +1,126 @@
+import { SDF3_EPSILON } from "./sdf3_degenerate_normal.js";
+
+/**
+ * # Capped cylinder — signed distance and its analytic gradient
+ *
+ * A cylinder about the **Y axis** of its own frame: `radius` across, `height`
+ * tall, so the flat caps sit at `±height/2`. Inigo Quilez's capped-cylinder
+ * field, written with the radial and axial distances named:
+ *
+ *     s  = ‖(x, z)‖
+ *     dr = s − r                     distance outside the infinite cylinder
+ *     da = |y| − h/2                 distance outside the slab
+ *     d  = ‖max(dr, 0), max(da, 0)‖ + min(max(dr, da), 0)
+ *
+ * The gradient is the two directions the field is built from, blended by how
+ * much of each the point is outside by:
+ *
+ *     û = (x, 0, z)/s                the radial direction
+ *     â = (0, sign(y), 0)            the axial direction
+ *     ∇d = (max(dr,0)·û + max(da,0)·â) / d      outside
+ *     ∇d = û or â, whichever of dr, da is larger        inside
+ *
+ * — which is exactly right on the rim, where both terms are live and the
+ * normalised sum sweeps continuously from the side to the cap.
+ *
+ * ## The axis is degenerate, and not in the way the others are
+ *
+ * On the axis, `û` does not exist. Unlike the sphere and the capsule this is
+ * *not* covered by `sdf3_degenerate_normal.js`'s `+Y`: a long thin cylinder's
+ * nearest exit from a point on its axis is sideways, and `+Y` is the one
+ * direction that is certainly not it. The fallback here is therefore `+X` — an
+ * arbitrary radial direction, which is what the configuration actually is:
+ * every radial direction is equally near and one has to be chosen.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Signed distance from a point to a capped cylinder's surface: negative inside.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} radius
+ * @param {number} height total extent along Y
+ * @returns {number}
+ */
+export function sdf3_cylinder(x, y, z, radius, height) {
+    const radial = Math.sqrt(x * x + z * z) - radius;
+    const axial = Math.abs(y) - height * 0.5;
+
+    const ext_r = radial > 0 ? radial : 0;
+    const ext_a = axial > 0 ? axial : 0;
+
+    const inner = radial > axial ? radial : axial;
+
+    return Math.sqrt(ext_r * ext_r + ext_a * ext_a) + (inner < 0 ? inner : 0);
+}
+
+/**
+ * Signed distance and the unit outward gradient, written to `out`.
+ *
+ * @param {Float32Array|Float64Array|number[]} out gradient destination
+ * @param {number} out_offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} radius
+ * @param {number} height
+ * @returns {number} the signed distance
+ */
+export function sdf3_cylinder_gradient(out, out_offset, x, y, z, radius, height) {
+    const s = Math.sqrt(x * x + z * z);
+
+    const radial = s - radius;
+    const axial = Math.abs(y) - height * 0.5;
+
+    // The radial direction, with an arbitrary one chosen on the axis.
+    let ux;
+    let uz;
+
+    if (s < SDF3_EPSILON) {
+        ux = 1;
+        uz = 0;
+    } else {
+        const inverse = 1 / s;
+
+        ux = x * inverse;
+        uz = z * inverse;
+    }
+
+    const axis_sign = y < 0 ? -1 : 1;
+
+    const ext_r = radial > 0 ? radial : 0;
+    const ext_a = axial > 0 ? axial : 0;
+
+    const outside = Math.sqrt(ext_r * ext_r + ext_a * ext_a);
+
+    if (outside > SDF3_EPSILON) {
+        const inverse = 1 / outside;
+
+        const wr = ext_r * inverse;
+        const wa = ext_a * inverse;
+
+        out[out_offset] = ux * wr;
+        out[out_offset + 1] = axis_sign * wa;
+        out[out_offset + 2] = uz * wr;
+
+        return outside;
+    }
+
+    if (radial >= axial) {
+        out[out_offset] = ux;
+        out[out_offset + 1] = 0;
+        out[out_offset + 2] = uz;
+
+        return radial;
+    }
+
+    out[out_offset] = 0;
+    out[out_offset + 1] = axis_sign;
+    out[out_offset + 2] = 0;
+
+    return axial;
+}

package/src/core/geom/3d/shape/sdf/sdf3_degenerate_normal.d.ts

@@ -0,0 +1,50 @@
+/**
+ * # The direction to leave a shape by when there is no direction
+ *
+ * Every analytic gradient in this directory has one configuration where the
+ * true gradient does not exist: the centre of a sphere, the axis of a capsule,
+ * the axis of a cylinder, the centre of a cube. `‖x‖` is not differentiable at
+ * zero, and no continuous choice fixes that — it is a property of the distance
+ * field, not of the arithmetic.
+ *
+ * A gradient of `(0, 0, 0)` is the mathematically honest answer and it is the
+ * wrong one for every caller. The consumers of these functions are pushing
+ * something *out* of the shape: a zero gradient carries no force, so a particle
+ * that reaches the exact centre of a sphere stays there for ever. "It does not
+ * get stuck" is the second design commitment of the cloth system and the first
+ * thing a zero would break, so the answer is an arbitrary unit vector rather
+ * than no vector.
+ *
+ * `+Y`, because a degenerate case wants a deterministic answer more than a
+ * clever one, and because it agrees with the axis every axis-aligned primitive
+ * in this family is already built around.
+ *
+ * {@link compute_signed_distance_gradient_by_sampling} answers these
+ * configurations differently and worse: at a sphere's centre it returns
+ * `(1,1,1)/√3`, which is unit-length, plausible-looking, and a pure artefact of
+ * sampling three positive offsets from one point. That it is *an* answer rather
+ * than obviously nothing is the reason it went unnoticed.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * @type {number}
+ */
+export const SDF3_DEGENERATE_NORMAL_X: number;
+/**
+ * @type {number}
+ */
+export const SDF3_DEGENERATE_NORMAL_Y: number;
+/**
+ * @type {number}
+ */
+export const SDF3_DEGENERATE_NORMAL_Z: number;
+/**
+ * Below this a length is treated as zero. It is well above `Float32`'s own
+ * resolution over a garment-sized coordinate and well below any distance a
+ * caller can act on, which is the whole of what an epsilon here has to be.
+ * @type {number}
+ */
+export const SDF3_EPSILON: number;
+//# sourceMappingURL=sdf3_degenerate_normal.d.ts.map

package/src/core/geom/3d/shape/sdf/sdf3_degenerate_normal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdf3_degenerate_normal.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/sdf/sdf3_degenerate_normal.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;GAEG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;GAEG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;GAEG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;;;;GAKG;AACH,2BAFU,MAAM,CAEiB"}

package/src/core/geom/3d/shape/sdf/sdf3_degenerate_normal.js

@@ -0,0 +1,53 @@
+/**
+ * # The direction to leave a shape by when there is no direction
+ *
+ * Every analytic gradient in this directory has one configuration where the
+ * true gradient does not exist: the centre of a sphere, the axis of a capsule,
+ * the axis of a cylinder, the centre of a cube. `‖x‖` is not differentiable at
+ * zero, and no continuous choice fixes that — it is a property of the distance
+ * field, not of the arithmetic.
+ *
+ * A gradient of `(0, 0, 0)` is the mathematically honest answer and it is the
+ * wrong one for every caller. The consumers of these functions are pushing
+ * something *out* of the shape: a zero gradient carries no force, so a particle
+ * that reaches the exact centre of a sphere stays there for ever. "It does not
+ * get stuck" is the second design commitment of the cloth system and the first
+ * thing a zero would break, so the answer is an arbitrary unit vector rather
+ * than no vector.
+ *
+ * `+Y`, because a degenerate case wants a deterministic answer more than a
+ * clever one, and because it agrees with the axis every axis-aligned primitive
+ * in this family is already built around.
+ *
+ * {@link compute_signed_distance_gradient_by_sampling} answers these
+ * configurations differently and worse: at a sphere's centre it returns
+ * `(1,1,1)/√3`, which is unit-length, plausible-looking, and a pure artefact of
+ * sampling three positive offsets from one point. That it is *an* answer rather
+ * than obviously nothing is the reason it went unnoticed.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * @type {number}
+ */
+export const SDF3_DEGENERATE_NORMAL_X = 0;
+
+/**
+ * @type {number}
+ */
+export const SDF3_DEGENERATE_NORMAL_Y = 1;
+
+/**
+ * @type {number}
+ */
+export const SDF3_DEGENERATE_NORMAL_Z = 0;
+
+/**
+ * Below this a length is treated as zero. It is well above `Float32`'s own
+ * resolution over a garment-sized coordinate and well below any distance a
+ * caller can act on, which is the whole of what an epsilon here has to be.
+ * @type {number}
+ */
+export const SDF3_EPSILON = 1e-9;

package/src/core/geom/3d/shape/sdf/sdf3_plane.d.ts

@@ -0,0 +1,52 @@
+/**
+ * # Half-space — signed distance and its analytic gradient
+ *
+ * The solid is `{ p : n·p − offset ≤ 0 }`, so `n` points **out** of the
+ * material and `offset` is how far along `n` the boundary plane sits from the
+ * origin.
+ *
+ *     d(x) = n·x − offset
+ *     ∇d(x) = n
+ *
+ * The only field in this family with no degenerate configuration anywhere and a
+ * gradient that is constant, which is why it is also the cheapest thing a
+ * simulation can collide against and the reason it is worth having as a shape
+ * rather than approximating with a very large box.
+ *
+ * PRECONDITION: `n` is unit length. A caller with an unnormalised normal has a
+ * scaled field rather than a distance field, and every consumer of a signed
+ * *distance* would then be wrong by that scale rather than merely imprecise.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Signed distance from a point to the boundary plane: negative inside the
+ * solid half-space.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} normal_x unit
+ * @param {number} normal_y unit
+ * @param {number} normal_z unit
+ * @param {number} offset
+ * @returns {number}
+ */
+export function sdf3_plane(x: number, y: number, z: number, normal_x: number, normal_y: number, normal_z: number, offset: number): number;
+/**
+ * Signed distance and the unit outward gradient, written to `out`.
+ *
+ * @param {Float32Array|Float64Array|number[]} out gradient destination
+ * @param {number} out_offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} normal_x unit
+ * @param {number} normal_y unit
+ * @param {number} normal_z unit
+ * @param {number} offset
+ * @returns {number} the signed distance
+ */
+export function sdf3_plane_gradient(out: Float32Array | Float64Array | number[], out_offset: number, x: number, y: number, z: number, normal_x: number, normal_y: number, normal_z: number, offset: number): number;
+//# sourceMappingURL=sdf3_plane.d.ts.map

package/src/core/geom/3d/shape/sdf/sdf3_plane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdf3_plane.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/sdf/sdf3_plane.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;;;;;GAYG;AACH,8BATW,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,UACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;;GAaG;AACH,yCAXW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,YACN,MAAM,YACN,MAAM,UACN,MAAM,GACJ,MAAM,CAQlB"}

package/src/core/geom/3d/shape/sdf/sdf3_plane.js

@@ -0,0 +1,61 @@
+/**
+ * # Half-space — signed distance and its analytic gradient
+ *
+ * The solid is `{ p : n·p − offset ≤ 0 }`, so `n` points **out** of the
+ * material and `offset` is how far along `n` the boundary plane sits from the
+ * origin.
+ *
+ *     d(x) = n·x − offset
+ *     ∇d(x) = n
+ *
+ * The only field in this family with no degenerate configuration anywhere and a
+ * gradient that is constant, which is why it is also the cheapest thing a
+ * simulation can collide against and the reason it is worth having as a shape
+ * rather than approximating with a very large box.
+ *
+ * PRECONDITION: `n` is unit length. A caller with an unnormalised normal has a
+ * scaled field rather than a distance field, and every consumer of a signed
+ * *distance* would then be wrong by that scale rather than merely imprecise.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Signed distance from a point to the boundary plane: negative inside the
+ * solid half-space.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} normal_x unit
+ * @param {number} normal_y unit
+ * @param {number} normal_z unit
+ * @param {number} offset
+ * @returns {number}
+ */
+export function sdf3_plane(x, y, z, normal_x, normal_y, normal_z, offset) {
+    return x * normal_x + y * normal_y + z * normal_z - offset;
+}
+
+/**
+ * Signed distance and the unit outward gradient, written to `out`.
+ *
+ * @param {Float32Array|Float64Array|number[]} out gradient destination
+ * @param {number} out_offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} normal_x unit
+ * @param {number} normal_y unit
+ * @param {number} normal_z unit
+ * @param {number} offset
+ * @returns {number} the signed distance
+ */
+export function sdf3_plane_gradient(out, out_offset, x, y, z, normal_x, normal_y, normal_z, offset) {
+    out[out_offset] = normal_x;
+    out[out_offset + 1] = normal_y;
+    out[out_offset + 2] = normal_z;
+
+    return x * normal_x + y * normal_y + z * normal_z - offset;
+}

package/src/core/geom/3d/shape/sdf/sdf3_sphere.d.ts

@@ -0,0 +1,41 @@
+/**
+ * # Sphere — signed distance and its analytic gradient
+ *
+ * A sphere of `radius` centred at the origin of its own frame.
+ *
+ *     d(x) = ‖x‖ − r
+ *     ∇d(x) = x/‖x‖
+ *
+ * Free functions over scalars rather than methods on {@link SphereShape3D},
+ * because the caller that needs them most has no shape object: cloth evaluates
+ * a collider SDF per particle per iteration against a packed record in a typed
+ * array (§8.2), and constructing a shape to ask it a question would cost more
+ * than the question. {@link SphereShape3D} calls these too, so there is one
+ * implementation of the arithmetic rather than two that can drift.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Signed distance from a point to a sphere's surface: negative inside.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} radius
+ * @returns {number}
+ */
+export function sdf3_sphere(x: number, y: number, z: number, radius: number): number;
+/**
+ * Signed distance and the unit outward gradient, written to `out`.
+ *
+ * @param {Float32Array|Float64Array|number[]} out gradient destination
+ * @param {number} out_offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} radius
+ * @returns {number} the signed distance
+ */
+export function sdf3_sphere_gradient(out: Float32Array | Float64Array | number[], out_offset: number, x: number, y: number, z: number, radius: number): number;
+//# sourceMappingURL=sdf3_sphere.d.ts.map

package/src/core/geom/3d/shape/sdf/sdf3_sphere.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdf3_sphere.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/sdf/sdf3_sphere.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;GAQG;AACH,+BANW,MAAM,KACN,MAAM,KACN,MAAM,UACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;GAUG;AACH,0CARW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,UACN,MAAM,GACJ,MAAM,CAsBlB"}

package/src/core/geom/3d/shape/sdf/sdf3_sphere.js

@@ -0,0 +1,71 @@
+import {
+    SDF3_DEGENERATE_NORMAL_X,
+    SDF3_DEGENERATE_NORMAL_Y,
+    SDF3_DEGENERATE_NORMAL_Z,
+    SDF3_EPSILON
+} from "./sdf3_degenerate_normal.js";
+
+/**
+ * # Sphere — signed distance and its analytic gradient
+ *
+ * A sphere of `radius` centred at the origin of its own frame.
+ *
+ *     d(x) = ‖x‖ − r
+ *     ∇d(x) = x/‖x‖
+ *
+ * Free functions over scalars rather than methods on {@link SphereShape3D},
+ * because the caller that needs them most has no shape object: cloth evaluates
+ * a collider SDF per particle per iteration against a packed record in a typed
+ * array (§8.2), and constructing a shape to ask it a question would cost more
+ * than the question. {@link SphereShape3D} calls these too, so there is one
+ * implementation of the arithmetic rather than two that can drift.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Signed distance from a point to a sphere's surface: negative inside.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} radius
+ * @returns {number}
+ */
+export function sdf3_sphere(x, y, z, radius) {
+    return Math.sqrt(x * x + y * y + z * z) - radius;
+}
+
+/**
+ * Signed distance and the unit outward gradient, written to `out`.
+ *
+ * @param {Float32Array|Float64Array|number[]} out gradient destination
+ * @param {number} out_offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} radius
+ * @returns {number} the signed distance
+ */
+export function sdf3_sphere_gradient(out, out_offset, x, y, z, radius) {
+    const length = Math.sqrt(x * x + y * y + z * z);
+
+    if (length < SDF3_EPSILON) {
+        // The centre. See `sdf3_degenerate_normal.js` for why this is a
+        // direction rather than nothing.
+        out[out_offset] = SDF3_DEGENERATE_NORMAL_X;
+        out[out_offset + 1] = SDF3_DEGENERATE_NORMAL_Y;
+        out[out_offset + 2] = SDF3_DEGENERATE_NORMAL_Z;
+
+        return -radius;
+    }
+
+    const inverse = 1 / length;
+
+    out[out_offset] = x * inverse;
+    out[out_offset + 1] = y * inverse;
+    out[out_offset + 2] = z * inverse;
+
+    return length - radius;
+}

package/src/core/process/ConcurrencyGate.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Runs at most {@link max_concurrent} tasks at a time, highest priority first across everything
+ * submitted to it.
+ *
+ * The point of putting one of these between a caller and its work is almost never the cap on its
+ * own — a caller can count its own in-flight requests. It is that **one** gate shared by several
+ * callers orders their work against each other. Per-caller caps do not compose: the number a
+ * browser, a CDN or a disk cares about is the total, and a caller that knows about one file cannot
+ * see it. Neither can a per-caller queue say that the second caller's request matters more than the
+ * first caller's, however truthfully their priorities compare.
+ *
+ * Ties are broken arbitrarily. Two tasks submitted at the same priority are, by the only measure the
+ * gate has, equally worth running.
+ *
+ * Nothing here is a new idea in this engine, which is why it ended up here rather than inside any
+ * one of its callers. `AssetManager` has capped concurrent top-level loads on `load_concurrency` for the
+ * same stated reason — keeping network slots free for higher-priority requests — and orders its
+ * pending queue through `get_pending_asset_priority_score`, which negates the priority for exactly
+ * the reason this heap does: `BinaryHeap` pops the lowest score first. `VirtualTextureManager` caps
+ * `max_concurrent_loads` against `#loads_in_flight`. When the virtual-geometry residency layer
+ * wanted the cap a third time and wrote that same negation a second time, it stopped being a detail
+ * of any one caller. The other two keep their own queues anyway, deliberately, and each says why
+ * where its cap is declared; the three paragraphs below are those reasons.
+ *
+ * **Priority is read once, at {@link submit}.** A gate keyed on a number captured at submission is
+ * the wrong shape for work whose importance moves while it waits, or whose priorities were never on
+ * a common scale: `AssetRequestScope.final_priority` is a richer model than a bare number, but it
+ * propagates hierarchically from an asset's requesting scopes and so compares only inside one
+ * hierarchy. For either, keep a queue over live records and re-score it (see below).
+ *
+ * **A task must not wait on another submission to the same gate.** The parent holds a slot while the
+ * child waits for one, so at a full gate that is a deadlock, and the gate cannot detect it: it sees
+ * a task that has not settled. Work that nests needs the parent's slot to cover the child, which
+ * means dispatching the child over the cap — `AssetManager` does exactly that for the requests its
+ * loaders make while servicing a load, and keeps its own queue for it.
+ *
+ * **What it deliberately is not.** There is no cancellation, and no way to drop or re-order a
+ * submission once it is made: a queued entry holds a closure and the gate will eventually run it.
+ * A caller that wants to *discard* pending work — because the page stopped being on screen, or a
+ * coarser mip arrived instead — wants a queue of live records it can filter, drained on its own
+ * clock, not a gate that owns closures. `VirtualTextureManager` drops queued requests untouched for
+ * `queue_stale_window` frames; it is that second thing, and no worse for it.
+ *
+ * Nothing bounds how long a low-priority submission waits. A caller that keeps feeding the gate
+ * higher-priority work will starve it indefinitely, which is what a priority queue means and is
+ * fine for the admission gates named above — where a dropped want is re-derived next frame — and not
+ * fine for work that has to finish eventually.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ConcurrencyGate {
+    /**
+     * @param {number} max_concurrent how many tasks may be running at once
+     */
+    constructor(max_concurrent: number);
+    /**
+     * Raising this starts whatever was already waiting. Lowering it starts nothing and stops
+     * nothing — tasks already running are left to finish, and the gate admits again once they have
+     * drained below the new value.
+     *
+     * @param {number} value
+     */
+    set max_concurrent(value: number);
+    /**
+     * @returns {number}
+     */
+    get max_concurrent(): number;
+    /**
+     * @returns {number}
+     */
+    get in_flight(): number;
+    /**
+     * @returns {number}
+     */
+    get queued(): number;
+    /**
+     * How many tasks this gate has started. Telemetry.
+     * @returns {number}
+     */
+    get admitted(): number;
+    /**
+     * The most that were ever in flight at once — which should never exceed the cap that was in
+     * force when they started, and is here so that a test can say so rather than assume it.
+     * @returns {number}
+     */
+    get peak_in_flight(): number;
+    /**
+     * Run a task when there is room, highest priority first.
+     *
+     * The task is never invoked synchronously, even when the gate is empty: it runs from a
+     * microtask, so a task that throws on its first line is a rejected promise here rather than an
+     * exception thrown back at whoever called {@link submit}.
+     *
+     * @template T
+     * @param {number} priority higher runs sooner
+     * @param {function(): Promise<T>} task
+     * @returns {Promise<T>} whatever the task settled to, once it ran
+     */
+    submit<T>(priority: number, task: () => Promise<T>): Promise<T>;
+    #private;
+}
+//# sourceMappingURL=ConcurrencyGate.d.ts.map

package/src/core/process/ConcurrencyGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConcurrencyGate.d.ts","sourceRoot":"","sources":["../../../../src/core/process/ConcurrencyGate.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH;IA2BI;;OAEG;IACH,4BAFW,MAAM,EAMhB;IASD;;;;;;OAMG;IACH,kCAMC;IApBD;;OAEG;IACH,6BAEC;IAiBD;;OAEG;IACH,wBAEC;IAED;;OAEG;IACH,qBAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;OAIG;IACH,6BAEC;IAED;;;;;;;;;;;OAWG;IACH,oBAJW,MAAM,sCAahB;;CA0CJ"}