@woosh/meep-engine 3.23.0 → 3.25.0

package/editor/entity_world_bounds.d.ts

@@ -1,9 +1,15 @@
 /**
  * Where an entity's model is, in world space.
  *
- * The renderer refreshes a world box per scene node as part of placing it, so the answer is the
- * renderer's rather than the component's — which is why this is a reader built from an engine rather
- * than a function over a component.
+ * The box the renderer draws a model by is derived on the GPU — from each primitive's geometry
+ * under the world transform the hierarchy pass composed, which for a subtree the GPU drives is a
+ * matrix the CPU never sees, and for a skinned primitive is the deformed clone's box rather than
+ * the rest pose's. So the answer is the renderer's where the renderer has one: the reader asks the
+ * scene context's bounds readback for every primitive of the model each time it is called, and
+ * once every primitive's box has landed the answer is their union, a frame or two behind the
+ * device. Until then — and with no device at all — it is what the ECS composes, from the same
+ * geometry under the entity's own transforms: exact for a model the CPU places, and what the
+ * renderer would draw were it drawing.
  *
  * **Precondition:** the engine has a {@link MeshSystem}. It is what puts anything on a screen at
  * all, so an editor running without one has nothing to select.

package/editor/entity_world_bounds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity_world_bounds.d.ts","sourceRoot":"","sources":["../../editor/entity_world_bounds.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,mEAJsB,UAAU,MAAM,CAAC,QAAE,MAAM,KAAG,OAAO,CAYxD"}
+{"version":3,"file":"entity_world_bounds.d.ts","sourceRoot":"","sources":["../../editor/entity_world_bounds.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,mEAJsB,UAAU,MAAM,CAAC,QAAE,MAAM,KAAG,OAAO,CAuBxD"}

package/editor/entity_world_bounds.js

@@ -1,12 +1,21 @@
 import { assert } from "../src/core/assert.js";
+import { aabb3_array_combine } from "../src/core/geom/3d/aabb/aabb3_array_combine.js";
 import { MeshSystem } from "../src/engine/graphics3/MeshSystem.js";
 
+const SCRATCH_BOX = new Float32Array(6);
+
 /**
  * Where an entity's model is, in world space.
  *
- * The renderer refreshes a world box per scene node as part of placing it, so the answer is the
- * renderer's rather than the component's — which is why this is a reader built from an engine rather
- * than a function over a component.
+ * The box the renderer draws a model by is derived on the GPU — from each primitive's geometry
+ * under the world transform the hierarchy pass composed, which for a subtree the GPU drives is a
+ * matrix the CPU never sees, and for a skinned primitive is the deformed clone's box rather than
+ * the rest pose's. So the answer is the renderer's where the renderer has one: the reader asks the
+ * scene context's bounds readback for every primitive of the model each time it is called, and
+ * once every primitive's box has landed the answer is their union, a frame or two behind the
+ * device. Until then — and with no device at all — it is what the ECS composes, from the same
+ * geometry under the entity's own transforms: exact for a model the CPU places, and what the
+ * renderer would draw were it drawing.
  *
  * **Precondition:** the engine has a {@link MeshSystem}. It is what puts anything on a screen at
  * all, so an editor running without one has nothing to select.
@@ -23,5 +32,53 @@ export function entity_world_bounds_reader(engine) {
 
     assert.notNull(meshes, 'MeshSystem');
 
-    return (target, entity) => meshes.compute_world_bounds(target, entity);
+    const graphics = engine.graphics;
+    const scene = meshes.scene;
+
+    return (target, entity) => {
+        const context = graphics === null || graphics === undefined ? null : graphics.scene_context(scene);
+
+        if (context !== null && drawn_bounds(context.bounds, meshes.mesh_entities_of(entity), target)) {
+            return true;
+        }
+
+        return meshes.compute_world_bounds(target, entity);
+    };
+}
+
+/**
+ * The union of the primitives' boxes as the GPU holds them, asking for each again for the frames
+ * to come.
+ *
+ * @param {import("../src/shade/renderer/scene/rows/GPUEntityBoundsReadback.js").GPUEntityBoundsReadback} bounds
+ * @param {number[]} primitives
+ * @param {ArrayLike<number>} target
+ * @returns {boolean} whether every primitive's box has landed; `false` leaves `target` alone
+ */
+function drawn_bounds(bounds, primitives, target) {
+    if (primitives.length === 0) {
+        return false;
+    }
+
+    let complete = true;
+
+    for (let i = 0; i < primitives.length; i++) {
+        const primitive = primitives[i];
+
+        bounds.request(primitive);
+
+        if (!bounds.get(primitive, SCRATCH_BOX)) {
+            complete = false;
+
+            continue;
+        }
+
+        if (complete) {
+            // combining the first box with itself is how it lands in `target` — one operation for
+            // both cases, rather than a copy that only ever runs once
+            aabb3_array_combine(target, 0, i === 0 ? SCRATCH_BOX : target, 0, SCRATCH_BOX, 0);
+        }
+    }
+
+    return complete;
 }

package/package.json

@@ -6,7 +6,7 @@
   "description": "Advanced 3D game engine",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.23.0",
+  "version": "3.25.0",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",

package/src/core/binary/allocator/OffsetAllocator.d.ts

@@ -1,3 +1,20 @@
+/**
+ * The smallest free run {@link OffsetAllocator#allocate} will accept for an allocation of `size`.
+ *
+ * Bins are 3-bit floats. A free run is filed under the largest bin that fits INSIDE it and a
+ * request is looked up from the smallest bin that fits the REQUEST, so consecutive bins being up
+ * to 9/8 apart is also how far apart those two answers can be: a free run of 68 is filed under 64,
+ * a request for 68 is looked up from 72, and the allocation is refused over space that is there.
+ * A run of exactly this value is filed in the bin the request starts from, and is the first one
+ * that is not — one element less is refused.
+ *
+ * For sizing a region that has to hold ONE allocation. A region holding a sequence of them needs
+ * the last of the sequence to still find a run this big, which is a larger question.
+ *
+ * @param {number} size the allocation to make room for, in elements
+ * @returns {number} free run size, in elements; never less than `size`
+ */
+export function allocator_run_size_for(size: number): number;
 export const ALLOCATOR_NO_SPACE: 4294967295;
 /**
  * One range handed out by {@link OffsetAllocator#allocate}: where it starts, plus the allocator's
@@ -119,6 +136,26 @@ export class OffsetAllocator {
      * @see free_node
      */
     free(allocation: Allocation): void;
+    /**
+     * The arena size {@link grow} has to be given for `allocate(size)` to succeed — the total, not
+     * the shortfall, and never less than the current {@link size}.
+     *
+     * Exact and minimal, so a caller with its own growth policy — a buffer alignment, a geometric
+     * step — is free to round this up and pass that instead. One element less than this is refused.
+     *
+     * Growth appends to the arena's end, so what the allocation is waiting for is the free run at
+     * that end reaching {@link allocator_run_size_for}. Free space the arena already ends in counts
+     * towards it; free space anywhere else does not, and does not need to — a run elsewhere large
+     * enough to take the request would have taken it already, and growing at the end never merges
+     * with one that is not.
+     *
+     * The one shortfall growing cannot answer is nodes: an allocator with none left to describe a
+     * region with refuses at any arena size, and {@link maxAllocs} is not raised by growing.
+     *
+     * @param {number} size the allocation to make room for, in elements
+     * @returns {number} arena size to grow to
+     */
+    grow_target_for(size: number): number;
     /**
      * Enlarge the arena in place. Every live allocation keeps the offset it was given.
      *
@@ -134,8 +171,9 @@ export class OffsetAllocator {
      * stripped that check is gone and the freelist pop underflows, so size {@link maxAllocs} for the
      * allocation count you intend to reach.
      *
-     * Growing by exactly N does not promise an allocation of N now fits: the bins round free runs
-     * down and requests up, up to 9/8 apart. Grow by `required * 9 / 8` before allocating `required`.
+     * Growing by exactly N does not promise an allocation of N now fits — the bins round free runs
+     * down and requests up, so the run has to reach a whole bin. Do not work that margin out at the
+     * call site: {@link grow_target_for} is the size to grow to, exactly.
      *
      * @param {number} new_size new total number of contiguous elements, must be >= the current size
      * @see reset

package/src/core/binary/allocator/OffsetAllocator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OffsetAllocator.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/allocator/OffsetAllocator.js"],"names":[],"mappings":"AAaA,4CAA6C;AAoC7C;;;;;;;;GAQG;AACH;IAII;;;;;OAKG;IACH,oBAJW,MAAM,YACN,MAAM,GACL,UAAU,CASrB;IAED;;;OAGG;IACH,yBAFU,UAAU,CAEoE;IAtBxF,eAA4B;IAC5B,iBAA8B;CAsBjC;AA6BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAoEI;;;;OAIG;IACH,kBAHW,MAAM,cACN,MAAM,EAYhB;IAlFD;;;;OAIG;IACH,MAFU,MAAM,CAEP;IAET;;;;OAIG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,UAFU,UAAU,CAEoB;IAExC;;;OAGG;IACH,YAFU,WAAW,CAEuB;IAE5C;;;OAGG;IACH,OAFU,aAAa,CAEmB;IAE1C;;OAEG;IACH,WAFU,WAAW,CAEX;IAEV;;;OAGG;IACH,YAFU,MAAM,CAED;IA+Bf;;;;OAIG;IACH,eAHW,MAAM,GACJ,UAAU,CAkGtB;IAED;;;;;;;OAOG;IACH,sBAHW,MAAM,QAqFhB;IAED;;;OAGG;IACH,iBAHW,UAAU,QAUpB;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,eAHW,MAAM,QA8DhB;IA0ID;;;OAGG;IACH,cA4BC;IAED;;;OAGG;IACH,iBAFY,aAAa,CA2BxB;;CACJ;8BAnsB6B,yCAAyC;AAqGvE;IACI,uBAAkB;IAClB,0BAAqB;CACxB"}
+{"version":3,"file":"OffsetAllocator.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/allocator/OffsetAllocator.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;GAeG;AACH,6CAHW,MAAM,GACJ,MAAM,CAYlB;AA7BD,4CAA6C;AAgE7C;;;;;;;;GAQG;AACH;IAII;;;;;OAKG;IACH,oBAJW,MAAM,YACN,MAAM,GACL,UAAU,CASrB;IAED;;;OAGG;IACH,yBAFU,UAAU,CAEoE;IAtBxF,eAA4B;IAC5B,iBAA8B;CAsBjC;AA6BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAoEI;;;;OAIG;IACH,kBAHW,MAAM,cACN,MAAM,EAYhB;IAlFD;;;;OAIG;IACH,MAFU,MAAM,CAEP;IAET;;;;OAIG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,UAFU,UAAU,CAEoB;IAExC;;;OAGG;IACH,YAFU,WAAW,CAEuB;IAE5C;;;OAGG;IACH,OAFU,aAAa,CAEmB;IAE1C;;OAEG;IACH,WAFU,WAAW,CAEX;IAEV;;;OAGG;IACH,YAFU,MAAM,CAED;IAqEf;;;;OAIG;IACH,eAHW,MAAM,GACJ,UAAU,CA+EtB;IAED;;;;;;;OAOG;IACH,sBAHW,MAAM,QAqFhB;IAED;;;OAGG;IACH,iBAHW,UAAU,QAUpB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,sBAHW,MAAM,GACJ,MAAM,CA4BlB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,eAHW,MAAM,QA8DhB;IA0ID;;;OAGG;IACH,cA4BC;IAED;;;OAGG;IACH,iBAFY,aAAa,CA2BxB;;CACJ;8BAlyB6B,yCAAyC;AAiIvE;IACI,uBAAkB;IAClB,0BAAqB;CACxB"}

package/src/core/binary/allocator/OffsetAllocator.js

@@ -14,6 +14,34 @@ const NUM_LEAF_BINS = NUM_TOP_BINS * BINS_PER_LEAF;
 export const ALLOCATOR_NO_SPACE = 0xffffffff;
 const NODE_UNUSED = 0xffffffff
 
+/**
+ * The smallest free run {@link OffsetAllocator#allocate} will accept for an allocation of `size`.
+ *
+ * Bins are 3-bit floats. A free run is filed under the largest bin that fits INSIDE it and a
+ * request is looked up from the smallest bin that fits the REQUEST, so consecutive bins being up
+ * to 9/8 apart is also how far apart those two answers can be: a free run of 68 is filed under 64,
+ * a request for 68 is looked up from 72, and the allocation is refused over space that is there.
+ * A run of exactly this value is filed in the bin the request starts from, and is the first one
+ * that is not — one element less is refused.
+ *
+ * For sizing a region that has to hold ONE allocation. A region holding a sequence of them needs
+ * the last of the sequence to still find a run this big, which is a larger question.
+ *
+ * @param {number} size the allocation to make room for, in elements
+ * @returns {number} free run size, in elements; never less than `size`
+ */
+export function allocator_run_size_for(size) {
+    assert.isNonNegativeInteger(size, 'size');
+
+    const run = floatToUint(uintToFloatRoundUp(size));
+
+    // The bin above 0xF0000000 is 2^32, which floatToUint folds to 0 — an answer a caller would read
+    // as nothing needed. No arena reaches it (grow caps below ALLOCATOR_NO_SPACE), so name it.
+    assert.greaterThanOrEqual(run, size, 'run, the bin above the request is past u32');
+
+    return run;
+}
+
 /**
  * Can potentially use u16, but number of allocation slots will be limited to 65k, so a severe limitation for little gain
  * @type {BinaryDataType}
@@ -217,48 +245,67 @@ export class OffsetAllocator {
     }
 
     /**
+     * The lowest non-empty bin at or above `min_bin_index`, or {@link ALLOCATOR_NO_SPACE} when
+     * every bin from there up is empty.
      *
-     * @param {number} size
-     * @returns {Allocation}
+     * Every run filed at or above a bin is at least that bin's own size, so this is exactly the
+     * search {@link allocate} does and exactly the one {@link grow_target_for} has to predict.
+     *
+     * @param {number} min_bin_index
+     * @returns {number} bin index, or ALLOCATOR_NO_SPACE
      */
-    allocate(size) {
-        assert.isNonNegativeInteger(size, 'size');
+    #find_bin_at_least(min_bin_index) {
+        const min_top_bin_index = min_bin_index >>> TOP_BINS_INDEX_SHIFT;
+        const min_leaf_bin_index = min_bin_index & LEAF_BINS_INDEX_MASK;
 
-        // Out of allocations?
-        if (this.freeOffset === 0) {
-            return Allocation.from(ALLOCATOR_NO_SPACE, ALLOCATOR_NO_SPACE);
-        }
-
-        // Round up to bin index to ensure that alloc >= bin
-        // Gives us min bin index that fits the size
-        let minBinIndex = uintToFloatRoundUp(size);
-
-        const minTopBinIndex = minBinIndex >>> TOP_BINS_INDEX_SHIFT;
-        const minLeafBinIndex = minBinIndex & LEAF_BINS_INDEX_MASK;
-
-        let topBinIndex = minTopBinIndex;
-        let leafBinIndex = ALLOCATOR_NO_SPACE;
+        let top_bin_index = min_top_bin_index;
+        let leaf_bin_index = ALLOCATOR_NO_SPACE;
 
         // If top bin exists, scan its leaf bin. This can fail (NO_SPACE).
-        if ((this.usedBinsTop & (1 << topBinIndex)) !== 0) {
-            leafBinIndex = findLowestSetBitAfter(this.usedBins[topBinIndex], minLeafBinIndex);
+        if ((this.usedBinsTop & (1 << top_bin_index)) !== 0) {
+            leaf_bin_index = findLowestSetBitAfter(this.usedBins[top_bin_index], min_leaf_bin_index);
         }
 
         // If we didn't find space in top bin, we search top bin from +1
-        if (leafBinIndex === ALLOCATOR_NO_SPACE) {
-            topBinIndex = findLowestSetBitAfter(this.usedBinsTop, minTopBinIndex + 1);
+        if (leaf_bin_index === ALLOCATOR_NO_SPACE) {
+            top_bin_index = findLowestSetBitAfter(this.usedBinsTop, min_top_bin_index + 1);
 
-            // Out of space?
-            if (topBinIndex === ALLOCATOR_NO_SPACE) {
-                return Allocation.from(ALLOCATOR_NO_SPACE, ALLOCATOR_NO_SPACE);
+            if (top_bin_index === ALLOCATOR_NO_SPACE) {
+                return ALLOCATOR_NO_SPACE;
             }
 
             // All leaf bins here fit the alloc, since the top bin was rounded up. Start leaf search from bit 0.
             // NOTE: This search can't fail since at least one leaf bit was set because the top bit was set.
-            leafBinIndex = ctz32(this.usedBins[topBinIndex]);
+            leaf_bin_index = ctz32(this.usedBins[top_bin_index]);
         }
 
-        let bin_index = ((topBinIndex << TOP_BINS_INDEX_SHIFT) | leafBinIndex) >>> 0; // ">>> 0" shift is to force UINT32
+        return ((top_bin_index << TOP_BINS_INDEX_SHIFT) | leaf_bin_index) >>> 0; // ">>> 0" shift is to force UINT32
+    }
+
+    /**
+     *
+     * @param {number} size
+     * @returns {Allocation}
+     */
+    allocate(size) {
+        assert.isNonNegativeInteger(size, 'size');
+
+        // Out of allocations?
+        if (this.freeOffset === 0) {
+            return Allocation.from(ALLOCATOR_NO_SPACE, ALLOCATOR_NO_SPACE);
+        }
+
+        // Round up to the bin index that fits the size: every run filed there or above is
+        // large enough, because a run is filed by rounding its size DOWN.
+        const bin_index = this.#find_bin_at_least(uintToFloatRoundUp(size));
+
+        if (bin_index === ALLOCATOR_NO_SPACE) {
+            // out of space
+            return Allocation.from(ALLOCATOR_NO_SPACE, ALLOCATOR_NO_SPACE);
+        }
+
+        const topBinIndex = bin_index >>> TOP_BINS_INDEX_SHIFT;
+        const leafBinIndex = bin_index & LEAF_BINS_INDEX_MASK;
 
         // Pop the top node of the bin. Bin top = node.next.
         let node_index = this.binIndices[bin_index];
@@ -424,6 +471,53 @@ export class OffsetAllocator {
         this.free_node(node_index);
     }
 
+    /**
+     * The arena size {@link grow} has to be given for `allocate(size)` to succeed — the total, not
+     * the shortfall, and never less than the current {@link size}.
+     *
+     * Exact and minimal, so a caller with its own growth policy — a buffer alignment, a geometric
+     * step — is free to round this up and pass that instead. One element less than this is refused.
+     *
+     * Growth appends to the arena's end, so what the allocation is waiting for is the free run at
+     * that end reaching {@link allocator_run_size_for}. Free space the arena already ends in counts
+     * towards it; free space anywhere else does not, and does not need to — a run elsewhere large
+     * enough to take the request would have taken it already, and growing at the end never merges
+     * with one that is not.
+     *
+     * The one shortfall growing cannot answer is nodes: an allocator with none left to describe a
+     * region with refuses at any arena size, and {@link maxAllocs} is not raised by growing.
+     *
+     * @param {number} size the allocation to make room for, in elements
+     * @returns {number} arena size to grow to
+     */
+    grow_target_for(size) {
+        assert.isNonNegativeInteger(size, 'size');
+
+        const required_run = allocator_run_size_for(size);
+
+        if (this.#find_bin_at_least(uintToFloatRoundUp(size)) !== ALLOCATOR_NO_SPACE) {
+            // a run that takes it is already filed; growing is not what this allocation is waiting for
+            return this.size;
+        }
+
+        const nodes = this.nodes;
+
+        // Only a free tail is extended by a grow; a used one is given a neighbour of the delta alone.
+        // The arena end is always described — reset() files one node ending at `size`, zero or not.
+        const tail_node = this.#tail_node;
+
+        const tail_run = (nodes.readCellValue(tail_node, NODE_FIELD_FLAGS) & NODE_FLAGS_USED) === 0
+            ? nodes.readCellValue(tail_node, NODE_FIELD_DATA_SIZE)
+            : 0;
+
+        // The search above consults the bins alone, so a free tail already reaching the run would
+        // have been found by it and answered from. Past that line the tail is short — of a whole
+        // bin, though not necessarily of `size` itself.
+        assert.lessThan(tail_run, required_run, 'tail run, a run the bin search did not find');
+
+        return this.size + (required_run - tail_run);
+    }
+
     /**
      * Enlarge the arena in place. Every live allocation keeps the offset it was given.
      *
@@ -439,8 +533,9 @@ export class OffsetAllocator {
      * stripped that check is gone and the freelist pop underflows, so size {@link maxAllocs} for the
      * allocation count you intend to reach.
      *
-     * Growing by exactly N does not promise an allocation of N now fits: the bins round free runs
-     * down and requests up, up to 9/8 apart. Grow by `required * 9 / 8` before allocating `required`.
+     * Growing by exactly N does not promise an allocation of N now fits — the bins round free runs
+     * down and requests up, so the run has to reach a whole bin. Do not work that margin out at the
+     * call site: {@link grow_target_for} is the size to grow to, exactly.
      *
      * @param {number} new_size new total number of contiguous elements, must be >= the current size
      * @see reset

package/src/core/collection/map/u32_index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * An open-addressed `u32 -> i32` index in a single `Uint32Array`, as free functions over the array
+ * rather than an object wrapping it. Nothing per entry is allocated, so an index that has reached
+ * its working size costs the garbage collector nothing at all; a `Map<number,number>` doing the
+ * same work allocates a fresh backing store every time it is cleared.
+ *
+ * **Keys** are `u32` and stored as `key + 1`, so a zero word is an empty slot and a freshly
+ * allocated array is already a valid empty index — {@link u32_index_clear} is one `fill(0)`, and
+ * creation needs no fill at all. `0xFFFFFFFF` is therefore not a usable key.
+ *
+ * **Values** are `i32`. A caller storing `-1` makes the key read back as {@link U32_INDEX_MISS},
+ * which is how a key is retired: the slot stays claimed, and no tombstone state has to exist for
+ * the probe to step over. Values are not otherwise interpreted.
+ *
+ * The probe is {@link generate_next_linear_congruential_index}, which is full-cycle over a
+ * power-of-two table — it visits every slot before repeating. Combined with the load factor, which
+ * guarantees at least one empty slot at all times, **the probe terminates by construction** and
+ * neither lookup nor insert carries a step limit. Both properties are load-bearing: a table
+ * allowed to fill would let a lookup for an absent key run forever.
+ *
+ * Sized for a key set that turns over completely each frame — build it up, clear it, build it
+ * again — which is what the GPU table upload streams do with it.
+ *
+ * @see cpu_build_hash_table for the same layout in a table the GPU also reads, where the probe
+ * count is instead bounded to match a WGSL twin that cannot grow.
+ */
+/**
+ * A new empty index.
+ *
+ * @param {number} [slots] power of two, rounded up to {@link MIN_SLOTS}
+ * @returns {Uint32Array}
+ */
+export function u32_index_create(slots?: number): Uint32Array;
+/**
+ * How many keys the index holds, retired ones included.
+ *
+ * @param {Uint32Array} table
+ * @returns {number}
+ */
+export function u32_index_count(table: Uint32Array): number;
+/**
+ * The value stored for a key, or {@link U32_INDEX_MISS} if the index does not hold it — or holds
+ * it retired.
+ *
+ * @param {Uint32Array} table
+ * @param {number} key
+ * @returns {number} i32
+ */
+export function u32_index_get(table: Uint32Array, key: number): number;
+/**
+ * Store a value for a key, replacing whatever the key held.
+ *
+ * Storing `-1` retires the key: it keeps its slot, and {@link u32_index_get} reports it as
+ * {@link U32_INDEX_MISS} from then on. That is the whole of the delete story — an open-addressed
+ * table cannot simply blank a slot without cutting the probe chains that run through it, and the
+ * callers that need removal only ever need the key to stop being found.
+ *
+ * Returns the index to store back: growing reallocates, so the array this hands back is not always
+ * the one it was given. Passing `null` creates one.
+ *
+ * @param {Uint32Array|null} table
+ * @param {number} key
+ * @param {number} value i32
+ * @returns {Uint32Array} the index to keep
+ */
+export function u32_index_set(table: Uint32Array | null, key: number, value: number): Uint32Array;
+/**
+ * Drop every key, keeping the allocation. The index is reusable immediately.
+ *
+ * @param {Uint32Array} table
+ */
+export function u32_index_clear(table: Uint32Array): void;
+/**
+ * What {@link u32_index_get} returns for a key the index does not hold.
+ *
+ * Also what a key holding the value `-1` reads back as — the two are deliberately
+ * indistinguishable, which is what lets a caller retire a key without the index needing tombstones.
+ * See {@link u32_index_set}.
+ *
+ * @type {number}
+ */
+export const U32_INDEX_MISS: number;
+//# sourceMappingURL=u32_index.d.ts.map

package/src/core/collection/map/u32_index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"u32_index.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/map/u32_index.js"],"names":[],"mappings":"AAsCA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;GAKG;AACH,yCAHW,MAAM,GACJ,WAAW,CAcvB;AAED;;;;;GAKG;AACH,uCAHW,WAAW,GACT,MAAM,CAIlB;AAED;;;;;;;GAOG;AACH,qCAJW,WAAW,OACX,MAAM,GACJ,MAAM,CAuBlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qCALW,WAAW,GAAC,IAAI,OAChB,MAAM,SACN,MAAM,GACJ,WAAW,CA2CvB;AAED;;;;GAIG;AACH,uCAFW,WAAW,QAQrB;AA/LD;;;;;;;;GAQG;AACH,6BAFU,MAAM,CAEiB"}