@woosh/meep-engine 3.49.0 → 3.50.0

package/src/core/geom/3d/shape/record/shape_record_signed_distance.js

@@ -0,0 +1,135 @@
+import { sdf3_box_gradient_array } from "../sdf/sdf3_box.js";
+import { sdf3_capsule_gradient_array } from "../sdf/sdf3_capsule.js";
+import { sdf3_cylinder_gradient_array } from "../sdf/sdf3_cylinder.js";
+import { sdf3_plane, sdf3_plane_gradient_array } from "../sdf/sdf3_plane.js";
+import { sdf3_sphere_gradient_array } from "../sdf/sdf3_sphere.js";
+import { SHAPE_RECORD_KIND, SHAPE_RECORD_PARAM_0, SHAPE_RECORD_PARAM_1 } from "./ShapeRecord.js";
+import { ShapeRecordKind } from "./ShapeRecordKind.js";
+
+/**
+ * # Evaluating a shape record
+ *
+ * Signed distance and its gradient at a point in the record's own local frame: a branch on the kind,
+ * then the `sdf3_*` field the parameters were laid out for, read where they sit. The fields are the
+ * ones the shapes themselves call, so a record and the shape it was packed from answer from one
+ * implementation; this is the CPU oracle a GPU evaluation of the same records is held to.
+ *
+ * ## A hull is the maximum over its planes
+ *
+ *     d(x) = max_i (n_i · x − d_i)
+ *
+ * **Exact inside**: from a point inside a convex polytope the nearest surface point is the foot on the
+ * nearest face's plane, and that foot is on the face. **Exact outside where the nearest surface point
+ * is inside a face.** Outside near an edge or a corner it is **conservative** — it reads the distance to
+ * the nearest plane, never more than the distance to the solid — so a solid test (`d ≤ r`) answers
+ * true at least as often as the exact field, and a margin grows the hull towards its planes' wedge
+ * rather than towards a rounded edge. The gradient is the normal of the plane that attains the maximum.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Signed distance from a point to a record's surface, negative inside, in the record's local frame.
+ *
+ * @param {Float32Array|Float64Array|number[]} record
+ * @param {number} record_offset where the record starts
+ * @param {Float32Array|Float64Array|number[]} planes the plane array a hull record was packed with;
+ *   read only for a hull
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {number}
+ */
+export function shape_record_signed_distance(record, record_offset, planes, x, y, z) {
+    SCALAR_POINT[0] = x;
+    SCALAR_POINT[1] = y;
+    SCALAR_POINT[2] = z;
+
+    shape_record_signed_distance_gradient_array(SCALAR_RESULT, 0, record, record_offset, planes, SCALAR_POINT, 0);
+
+    return SCALAR_RESULT[3];
+}
+
+/**
+ * Signed distance and the unit outward gradient at a point read from an array, both written to `out`.
+ * For per-element loops: a point handed over as three numbers, or a distance handed back as one, is
+ * boxed into a heap object wherever V8 does not inline the call.
+ *
+ * @param {Float32Array|Float64Array|number[]} out receives `[gx, gy, gz, distance]` at `out_offset`
+ * @param {number} out_offset
+ * @param {Float32Array|Float64Array|number[]} record
+ * @param {number} record_offset where the record starts
+ * @param {Float32Array|Float64Array|number[]} planes the plane array a hull record was packed with;
+ *   read only for a hull
+ * @param {Float32Array|Float64Array|number[]} point `[x, y, z]`, in the record's local frame
+ * @param {number} point_offset
+ * @returns {void}
+ */
+export function shape_record_signed_distance_gradient_array(out, out_offset, record, record_offset, planes, point, point_offset) {
+    const kind = record[record_offset + SHAPE_RECORD_KIND];
+
+    // A record's shape parameters sit in a row from `SHAPE_RECORD_PARAM_0`, in the order each field's
+    // array form reads them.
+    const parameters = record_offset + SHAPE_RECORD_PARAM_0;
+
+    if (kind === ShapeRecordKind.Sphere) {
+        sdf3_sphere_gradient_array(out, out_offset, point, point_offset, record, parameters);
+    } else if (kind === ShapeRecordKind.Capsule) {
+        sdf3_capsule_gradient_array(out, out_offset, point, point_offset, record, parameters);
+    } else if (kind === ShapeRecordKind.Box) {
+        sdf3_box_gradient_array(out, out_offset, point, point_offset, record, parameters);
+    } else if (kind === ShapeRecordKind.Cylinder) {
+        sdf3_cylinder_gradient_array(out, out_offset, point, point_offset, record, parameters);
+    } else if (kind === ShapeRecordKind.Plane) {
+        sdf3_plane_gradient_array(out, out_offset, point, point_offset, record, parameters);
+    } else {
+        convex_hull_gradient_array(out, out_offset, record, record_offset, planes, point, point_offset);
+    }
+}
+
+/**
+ * @param {Float32Array|Float64Array|number[]} out
+ * @param {number} out_offset
+ * @param {Float32Array|Float64Array|number[]} record
+ * @param {number} record_offset
+ * @param {Float32Array|Float64Array|number[]} planes
+ * @param {Float32Array|Float64Array|number[]} point
+ * @param {number} point_offset
+ */
+function convex_hull_gradient_array(out, out_offset, record, record_offset, planes, point, point_offset) {
+    const x = point[point_offset];
+    const y = point[point_offset + 1];
+    const z = point[point_offset + 2];
+
+    const first = record[record_offset + SHAPE_RECORD_PARAM_0] * 4;
+    const end = first + record[record_offset + SHAPE_RECORD_PARAM_1] * 4;
+
+    let best_distance = -Infinity;
+    let best_plane = first;
+
+    for (let o = first; o < end; o += 4) {
+        const distance = sdf3_plane(x, y, z, planes[o], planes[o + 1], planes[o + 2], planes[o + 3]);
+
+        if (distance > best_distance) {
+            best_distance = distance;
+            best_plane = o;
+        }
+    }
+
+    sdf3_plane_gradient_array(out, out_offset, point, point_offset, planes, best_plane);
+}
+
+/**
+ * The scalar form's point, packed for the array form it delegates to.
+ * @type {Float64Array}
+ * @private
+ */
+const SCALAR_POINT = new Float64Array(3);
+
+/**
+ * {@link shape_record_signed_distance}'s gradient and distance, as the array form writes them.
+ * @type {Float64Array}
+ * @private
+ */
+const SCALAR_RESULT = new Float64Array(4);

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

@@ -17,6 +17,13 @@
  * 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.
  *
+ * ## On the GPU the sign of the offset flips
+ *
+ * There is no plane chunk of this form. WGSL's plane is `vec4(n, w)` with
+ * `d = n·p + w` (`point_distance_above_plane`, the engine-wide convention, and
+ * `v3_distance_above_plane` in JS), so this half-space is packed for the GPU as
+ * `w = −offset`.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */

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

@@ -1 +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,CAmBlB;AAED;;;;;;;;;;;;;GAaG;AACH,+CAVW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAElC,MAAM,SACN,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,gBAClC,MAAM,SACN,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,gBAElC,MAAM,GACJ,IAAI,CAgBhB"}
+{"version":3,"file":"sdf3_plane.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/sdf/sdf3_plane.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;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,CAmBlB;AAED;;;;;;;;;;;;;GAaG;AACH,+CAVW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAElC,MAAM,SACN,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,gBAClC,MAAM,SACN,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,gBAElC,MAAM,GACJ,IAAI,CAgBhB"}

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

@@ -17,6 +17,13 @@
  * 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.
  *
+ * ## On the GPU the sign of the offset flips
+ *
+ * There is no plane chunk of this form. WGSL's plane is `vec4(n, w)` with
+ * `d = n·p + w` (`point_distance_above_plane`, the engine-wide convention, and
+ * `v3_distance_above_plane` in JS), so this half-space is packed for the GPU as
+ * `w = −offset`.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */

package/src/core/geom/3d/shape/util/compute_signed_distance_gradient_by_sampling.d.ts

@@ -1,4 +1,7 @@
 /**
+ * The probes go down in `result`, not in a module scratch: the shape may hold a wrapper whose distance
+ * samples a gradient of its own, which rewrote a shared probe while a union above it still had children
+ * to ask about it. `point` may be `result` itself, so it is read first.
  *
  * @param {number[]} result
  * @param {AbstractShape3D} shape

package/src/core/geom/3d/shape/util/compute_signed_distance_gradient_by_sampling.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compute_signed_distance_gradient_by_sampling.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/util/compute_signed_distance_gradient_by_sampling.js"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,qEALW,MAAM,EAAE,iCAER,MAAM,EAAE,GACN,MAAM,CA0ClB"}
+{"version":3,"file":"compute_signed_distance_gradient_by_sampling.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/util/compute_signed_distance_gradient_by_sampling.js"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,qEALW,MAAM,EAAE,iCAER,MAAM,EAAE,GACN,MAAM,CA8ClB"}

package/src/core/geom/3d/shape/util/compute_signed_distance_gradient_by_sampling.js

@@ -1,7 +1,9 @@
 const SAMPLE_STEP = 1e-5;
-const scratch_v = [0, 0, 0];
 
 /**
+ * The probes go down in `result`, not in a module scratch: the shape may hold a wrapper whose distance
+ * samples a gradient of its own, which rewrote a shared probe while a union above it still had children
+ * to ask about it. `point` may be `result` itself, so it is read first.
  *
  * @param {number[]} result
  * @param {AbstractShape3D} shape
@@ -9,25 +11,29 @@ const scratch_v = [0, 0, 0];
  * @returns {number}
  */
 export function compute_signed_distance_gradient_by_sampling(result, shape, point) {
+    const px = point[0];
+    const py = point[1];
+    const pz = point[2];
+
     const v0 = shape.signed_distance_at_point(point);
 
-    scratch_v[0] = point[0] + SAMPLE_STEP;
-    scratch_v[1] = point[1];
-    scratch_v[2] = point[2];
+    result[0] = px + SAMPLE_STEP;
+    result[1] = py;
+    result[2] = pz;
 
-    const vx = shape.signed_distance_at_point(scratch_v);
+    const vx = shape.signed_distance_at_point(result);
 
-    scratch_v[0] = point[0];
-    scratch_v[1] = point[1] + SAMPLE_STEP;
-    scratch_v[2] = point[2];
+    result[0] = px;
+    result[1] = py + SAMPLE_STEP;
+    result[2] = pz;
 
-    const vy = shape.signed_distance_at_point(scratch_v);
+    const vy = shape.signed_distance_at_point(result);
 
-    scratch_v[0] = point[0];
-    scratch_v[1] = point[1];
-    scratch_v[2] = point[2] + SAMPLE_STEP;
+    result[0] = px;
+    result[1] = py;
+    result[2] = pz + SAMPLE_STEP;
 
-    const vz = shape.signed_distance_at_point(scratch_v);
+    const vz = shape.signed_distance_at_point(result);
 
     // finite-difference partial derivatives
     const gx = (vx - v0) / SAMPLE_STEP;

package/src/core/geom/clipmap/ClipmapWindowSet.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The windows of a clipmap: per level, a box of `size` cells of that level placed around an anchor,
+ * moving in whole steps as the anchor moves, over storage that wraps.
+ *
+ * **Corners.** A level's window is the integer box `[corner, corner + size)` on each axis, in that
+ * level's cells. What a cell of a level is in the world, and how the levels nest, is the caller's;
+ * the levels here are independent.
+ *
+ * **Placement** ({@link place}) applies {@link quantize_hysteretic} to the corner on each axis: a
+ * window holds while its anchor is within `0.5·step + hysteresis` cells of the window's centre, and
+ * past that moves to the corner, a multiple of `step`, that centres it best. The first placement of a
+ * level takes that corner outright. A caller that nests its levels holds each to its bounds after
+ * that with {@link clamp_corner}.
+ *
+ * **Storage wraps.** A cell sits in storage cell `cell mod size` on every axis, wherever the window
+ * is ({@link storage_cell}), so a window that moves keeps every cell still inside it where it was,
+ * and the slots it vacates are exactly the slots the cells it exposes take
+ * ({@link window_scroll_regions}). {@link decode} goes back from a storage cell to the cell of the
+ * window that sits in it.
+ *
+ * 2 or 3 dimensions. A 2-D set has a z size of 1 and never reads a z argument.
+ */
+export class ClipmapWindowSet {
+    /**
+     * @param {Object} options
+     * @param {number} options.level_count
+     * @param {number} options.dimensions 2 or 3
+     * @param {ArrayLike<number>} options.size `dimensions` sides, cells
+     * @param {number} options.step a positive integer, cells
+     * @param {number} options.hysteresis cells, not negative
+     */
+    constructor({ level_count, dimensions, size, step, hysteresis }: {
+        level_count: number;
+        dimensions: number;
+        size: ArrayLike<number>;
+        step: number;
+        hysteresis: number;
+    });
+    /**
+     * @type {number}
+     * @readonly
+     */
+    readonly level_count: number;
+    /**
+     * 2 or 3.
+     * @type {number}
+     * @readonly
+     */
+    readonly dimensions: number;
+    /**
+     * A window's side on each axis, in cells: x, y, z. A 2-D set's z is 1.
+     * @type {Int32Array}
+     * @readonly
+     */
+    readonly size: Int32Array;
+    /**
+     * Corners move in multiples of this many cells.
+     * @type {number}
+     * @readonly
+     */
+    readonly step: number;
+    /**
+     * Cells past half a step the anchor goes from the window's centre before the window moves.
+     * @type {number}
+     * @readonly
+     */
+    readonly hysteresis: number;
+    /**
+     * Bumped every time a window moves, its first placement included.
+     * @returns {number}
+     */
+    get version(): number;
+    /**
+     * Storage cells of one level: the product of the sides.
+     * @returns {number}
+     */
+    get cells_per_level(): number;
+    /**
+     * @param {number} level
+     * @returns {boolean} whether {@link place} has placed the level's window
+     */
+    placed(level: number): boolean;
+    /**
+     * @param {number} level
+     * @param {number} axis 0, 1 or 2
+     * @returns {number} the smallest cell the level's window holds on the axis
+     */
+    corner(level: number, axis: number): number;
+    /**
+     * Move a level's window toward an anchor, by the hysteretic rule.
+     *
+     * @param {number} level
+     * @param {number} x the anchor, in the level's cells: where the window's centre should be
+     * @param {number} y
+     * @param {number} [z] not read by a 2-D set
+     * @returns {boolean} whether the window moved; true on its first placement
+     */
+    place(level: number, x: number, y: number, z?: number): boolean;
+    /**
+     * Hold a placed level's window to a range of corners on one axis, after {@link place}'s own rule:
+     * the bound a caller nests its levels by. A corner outside `[min, max]` moves to the nearer end;
+     * one inside stays. Both ends are multiples of {@link step}, so the corner stays one.
+     *
+     * @param {number} level
+     * @param {number} axis 0, 1 or 2
+     * @param {number} min the smallest corner the window may have, cells
+     * @param {number} max the largest, not below `min`
+     * @returns {boolean} whether the window moved
+     */
+    clamp_corner(level: number, axis: number, min: number, max: number): boolean;
+    /**
+     * @param {number} level
+     * @param {number} x a cell of the level
+     * @param {number} y
+     * @param {number} [z] not read by a 2-D set
+     * @returns {boolean} whether the level's window is placed and holds the cell
+     */
+    contains(level: number, x: number, y: number, z?: number): boolean;
+    /**
+     * The storage cell a cell of a level sits in, as a row from the first level's first: level-major,
+     * then z, y, x. The cell need not be in the window; this is the slot it takes when it is.
+     *
+     * @param {number} level
+     * @param {number} x
+     * @param {number} y
+     * @param {number} [z] not read by a 2-D set
+     * @returns {number}
+     */
+    storage_cell(level: number, x: number, y: number, z?: number): number;
+    /**
+     * The cell of a level's window that sits in a storage coordinate: `corner + mod(storage − corner, size)`.
+     *
+     * @param {number} level
+     * @param {number} axis 0, 1 or 2
+     * @param {number} storage the storage coordinate on the axis, in `[0, size)`
+     * @returns {number}
+     */
+    decode(level: number, axis: number, storage: number): number;
+    #private;
+}
+//# sourceMappingURL=ClipmapWindowSet.d.ts.map

package/src/core/geom/clipmap/ClipmapWindowSet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClipmapWindowSet.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/clipmap/ClipmapWindowSet.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAkDI;;;;;;;OAOG;IACH;QAN2B,WAAW,EAA3B,MAAM;QACU,UAAU,EAA1B,MAAM;QACqB,IAAI,EAA/B,UAAU,MAAM,CAAC;QACD,IAAI,EAApB,MAAM;QACU,UAAU,EAA1B,MAAM;OAyBhB;IA/ED;;;OAGG;IACH,sBAHU,MAAM,CAGJ;IAEZ;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IAEX;;;;OAIG;IACH,eAHU,UAAU,CAGf;IAEL;;;;OAIG;IACH,eAHU,MAAM,CAGX;IAEL;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IAiDX;;;OAGG;IACH,sBAEC;IAED;;;OAGG;IACH,8BAIC;IAED;;;OAGG;IACH,cAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;OAIG;IACH,cAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;OAQG;IACH,aANW,MAAM,KACN,MAAM,KACN,MAAM,MACN,MAAM,GACJ,OAAO,CAsBnB;IAED;;;;;;;;;;OAUG;IACH,oBANW,MAAM,QACN,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CA0BnB;IAyBD;;;;;;OAMG;IACH,gBANW,MAAM,KACN,MAAM,KACN,MAAM,MACN,MAAM,GACJ,OAAO,CAyBnB;IAED;;;;;;;;;OASG;IACH,oBANW,MAAM,KACN,MAAM,KACN,MAAM,MACN,MAAM,GACJ,MAAM,CAUlB;IAED;;;;;;;OAOG;IACH,cALW,MAAM,QACN,MAAM,WACN,MAAM,GACJ,MAAM,CAMlB;;CACJ"}

package/src/core/geom/clipmap/ClipmapWindowSet.js

@@ -0,0 +1,301 @@
+import { assert } from "../../assert.js";
+import { euclidean_modulo } from "../../math/euclidean_modulo.js";
+import { quantize_hysteretic } from "./quantize_hysteretic.js";
+
+/**
+ * The windows of a clipmap: per level, a box of `size` cells of that level placed around an anchor,
+ * moving in whole steps as the anchor moves, over storage that wraps.
+ *
+ * **Corners.** A level's window is the integer box `[corner, corner + size)` on each axis, in that
+ * level's cells. What a cell of a level is in the world, and how the levels nest, is the caller's;
+ * the levels here are independent.
+ *
+ * **Placement** ({@link place}) applies {@link quantize_hysteretic} to the corner on each axis: a
+ * window holds while its anchor is within `0.5·step + hysteresis` cells of the window's centre, and
+ * past that moves to the corner, a multiple of `step`, that centres it best. The first placement of a
+ * level takes that corner outright. A caller that nests its levels holds each to its bounds after
+ * that with {@link clamp_corner}.
+ *
+ * **Storage wraps.** A cell sits in storage cell `cell mod size` on every axis, wherever the window
+ * is ({@link storage_cell}), so a window that moves keeps every cell still inside it where it was,
+ * and the slots it vacates are exactly the slots the cells it exposes take
+ * ({@link window_scroll_regions}). {@link decode} goes back from a storage cell to the cell of the
+ * window that sits in it.
+ *
+ * 2 or 3 dimensions. A 2-D set has a z size of 1 and never reads a z argument.
+ */
+export class ClipmapWindowSet {
+
+    /**
+     * @type {number}
+     * @readonly
+     */
+    level_count;
+
+    /**
+     * 2 or 3.
+     * @type {number}
+     * @readonly
+     */
+    dimensions;
+
+    /**
+     * A window's side on each axis, in cells: x, y, z. A 2-D set's z is 1.
+     * @type {Int32Array}
+     * @readonly
+     */
+    size;
+
+    /**
+     * Corners move in multiples of this many cells.
+     * @type {number}
+     * @readonly
+     */
+    step;
+
+    /**
+     * Cells past half a step the anchor goes from the window's centre before the window moves.
+     * @type {number}
+     * @readonly
+     */
+    hysteresis;
+
+    /**
+     * Per level, the window's corner: x, y, z.
+     * @type {Int32Array}
+     */
+    #corner;
+
+    /**
+     * Per level, 1 once {@link place} has placed it.
+     * @type {Uint8Array}
+     */
+    #placed;
+
+    #version = 0;
+
+    /**
+     * @param {Object} options
+     * @param {number} options.level_count
+     * @param {number} options.dimensions 2 or 3
+     * @param {ArrayLike<number>} options.size `dimensions` sides, cells
+     * @param {number} options.step a positive integer, cells
+     * @param {number} options.hysteresis cells, not negative
+     */
+    constructor({ level_count, dimensions, size, step, hysteresis }) {
+        assert.isPositiveInteger(level_count, 'level_count');
+        assert.ok(dimensions === 2 || dimensions === 3, 'dimensions must be 2 or 3');
+        assert.equal(size.length, dimensions, 'size.length');
+        assert.isPositiveInteger(step, 'step');
+        assert.isNumber(hysteresis, 'hysteresis');
+        assert.greaterThanOrEqual(hysteresis, 0, 'hysteresis');
+
+        this.level_count = level_count;
+        this.dimensions = dimensions;
+        this.size = new Int32Array([1, 1, 1]);
+
+        for (let axis = 0; axis < dimensions; axis++) {
+            assert.isPositiveInteger(size[axis], `size[${axis}]`);
+
+            this.size[axis] = size[axis];
+        }
+
+        this.step = step;
+        this.hysteresis = hysteresis;
+
+        this.#corner = new Int32Array(level_count * 3);
+        this.#placed = new Uint8Array(level_count);
+    }
+
+    /**
+     * Bumped every time a window moves, its first placement included.
+     * @returns {number}
+     */
+    get version() {
+        return this.#version;
+    }
+
+    /**
+     * Storage cells of one level: the product of the sides.
+     * @returns {number}
+     */
+    get cells_per_level() {
+        const size = this.size;
+
+        return size[0] * size[1] * size[2];
+    }
+
+    /**
+     * @param {number} level
+     * @returns {boolean} whether {@link place} has placed the level's window
+     */
+    placed(level) {
+        return this.#placed[level] !== 0;
+    }
+
+    /**
+     * @param {number} level
+     * @param {number} axis 0, 1 or 2
+     * @returns {number} the smallest cell the level's window holds on the axis
+     */
+    corner(level, axis) {
+        return this.#corner[level * 3 + axis];
+    }
+
+    /**
+     * Move a level's window toward an anchor, by the hysteretic rule.
+     *
+     * @param {number} level
+     * @param {number} x the anchor, in the level's cells: where the window's centre should be
+     * @param {number} y
+     * @param {number} [z] not read by a 2-D set
+     * @returns {boolean} whether the window moved; true on its first placement
+     */
+    place(level, x, y, z) {
+        assert.isNonNegativeInteger(level, 'level');
+        assert.lessThan(level, this.level_count, 'level');
+
+        const placed = this.#placed[level] !== 0;
+        const base = level * 3;
+
+        const moved_x = this.#place_axis(base, 0, x, placed);
+        const moved_y = this.#place_axis(base, 1, y, placed);
+        const moved_z = this.dimensions === 3 && this.#place_axis(base, 2, z, placed);
+
+        this.#placed[level] = 1;
+
+        if (placed && !moved_x && !moved_y && !moved_z) {
+            return false;
+        }
+
+        this.#version++;
+
+        return true;
+    }
+
+    /**
+     * Hold a placed level's window to a range of corners on one axis, after {@link place}'s own rule:
+     * the bound a caller nests its levels by. A corner outside `[min, max]` moves to the nearer end;
+     * one inside stays. Both ends are multiples of {@link step}, so the corner stays one.
+     *
+     * @param {number} level
+     * @param {number} axis 0, 1 or 2
+     * @param {number} min the smallest corner the window may have, cells
+     * @param {number} max the largest, not below `min`
+     * @returns {boolean} whether the window moved
+     */
+    clamp_corner(level, axis, min, max) {
+        assert.isNonNegativeInteger(level, 'level');
+        assert.lessThan(level, this.level_count, 'level');
+        assert.ok(this.#placed[level] !== 0, 'the level is placed');
+        assert.isNonNegativeInteger(axis, 'axis');
+        assert.lessThan(axis, this.dimensions, 'axis');
+        assert.isInteger(min, 'min');
+        assert.isInteger(max, 'max');
+        assert.lessThanOrEqual(min, max, 'min');
+        assert.equal(min % this.step, 0, 'min is a multiple of the step');
+        assert.equal(max % this.step, 0, 'max is a multiple of the step');
+
+        const i = level * 3 + axis;
+        const corner = this.#corner[i];
+        const next = Math.min(max, Math.max(min, corner));
+
+        if (next === corner) {
+            return false;
+        }
+
+        this.#corner[i] = next;
+        this.#version++;
+
+        return true;
+    }
+
+    /**
+     * @param {number} base the level's first corner index
+     * @param {number} axis
+     * @param {number} anchor
+     * @param {boolean} placed
+     * @returns {boolean} whether the corner changed
+     */
+    #place_axis(base, axis, anchor, placed) {
+        const step = this.step;
+        const i = base + axis;
+        const corner = this.#corner[i];
+
+        // the window's centre is half its side past its corner: quantize where the corner would be
+        const index = quantize_hysteretic(anchor - this.size[axis] * 0.5, corner / step, step, this.hysteresis, placed);
+        const next = index * step;
+
+        assert.equal(next, next | 0, 'corner leaves the 32-bit range');
+
+        this.#corner[i] = next;
+
+        return next !== corner;
+    }
+
+    /**
+     * @param {number} level
+     * @param {number} x a cell of the level
+     * @param {number} y
+     * @param {number} [z] not read by a 2-D set
+     * @returns {boolean} whether the level's window is placed and holds the cell
+     */
+    contains(level, x, y, z) {
+        if (this.#placed[level] === 0) {
+            return false;
+        }
+
+        const corner = this.#corner;
+        const size = this.size;
+        const base = level * 3;
+
+        const rx = x - corner[base];
+        const ry = y - corner[base + 1];
+
+        if (rx < 0 || ry < 0 || rx >= size[0] || ry >= size[1]) {
+            return false;
+        }
+
+        if (this.dimensions === 2) {
+            return true;
+        }
+
+        const rz = z - corner[base + 2];
+
+        return rz >= 0 && rz < size[2];
+    }
+
+    /**
+     * The storage cell a cell of a level sits in, as a row from the first level's first: level-major,
+     * then z, y, x. The cell need not be in the window; this is the slot it takes when it is.
+     *
+     * @param {number} level
+     * @param {number} x
+     * @param {number} y
+     * @param {number} [z] not read by a 2-D set
+     * @returns {number}
+     */
+    storage_cell(level, x, y, z) {
+        const size = this.size;
+
+        const sx = euclidean_modulo(x, size[0]);
+        const sy = euclidean_modulo(y, size[1]);
+        const sz = this.dimensions === 3 ? euclidean_modulo(z, size[2]) : 0;
+
+        return ((level * size[2] + sz) * size[1] + sy) * size[0] + sx;
+    }
+
+    /**
+     * The cell of a level's window that sits in a storage coordinate: `corner + mod(storage − corner, size)`.
+     *
+     * @param {number} level
+     * @param {number} axis 0, 1 or 2
+     * @param {number} storage the storage coordinate on the axis, in `[0, size)`
+     * @returns {number}
+     */
+    decode(level, axis, storage) {
+        const corner = this.#corner[level * 3 + axis];
+
+        return corner + euclidean_modulo(storage - corner, this.size[axis]);
+    }
+}