@woosh/meep-engine 2.138.20 → 2.140.0

package/src/core/geom/3d/tetrahedra/tetrahedral_mesh_vertex_is_boundary.js

@@ -0,0 +1,97 @@
+import { assert } from "../../../assert.js";
+import { INVALID_NEIGHBOUR } from "./TetrahedralMesh.js";
+
+/**
+ * Return true if the given vertex lies on the boundary of the
+ * tetrahedral mesh — equivalently, if it sits on any face that has no
+ * neighbouring tet (INVALID_NEIGHBOUR).
+ *
+ * Used by quality-improvement passes to skip boundary vertices when
+ * smoothing or collapsing, because moving them would change the mesh's
+ * external surface (which usually represents some geometric constraint
+ * the caller wants preserved).
+ *
+ * Cost without `vertex_to_tets_map`: O(N) over the live tets, same as
+ * {@link tetrahedral_mesh_find_tets_attached_to_vertex} which it shares
+ * the same scan structure with.
+ *
+ * Cost with `vertex_to_tets_map`: O(deg(vertex)) — usually a small
+ * constant. For repeated calls over many vertices in a tight loop
+ * (e.g. a sliver-removal pass), build the map once via
+ * {@link tetrahedral_mesh_build_vertex_to_tets_map} and pass it in.
+ *
+ * Note: boundary status is invariant under interior 2-3 / 3-2 flips, so
+ * a once-per-pass cache stays valid for boundary queries even as the
+ * pass commits flips, as long as a freshly-snapshotted cache is built
+ * for each NEW pass.
+ *
+ * @param {TetrahedralMesh} mesh
+ * @param {number} vertex_id
+ * @param {Map<number, number[]>} [vertex_to_tets_map] optional cache
+ * @returns {boolean}
+ */
+export function tetrahedral_mesh_vertex_is_boundary(mesh, vertex_id, vertex_to_tets_map) {
+    assert.defined(mesh, 'mesh');
+    assert.isNonNegativeInteger(vertex_id, 'vertex_id');
+
+    if (vertex_to_tets_map !== undefined) {
+        const tets = vertex_to_tets_map.get(vertex_id);
+        if (tets === undefined) return false;
+
+        for (let ti = 0; ti < tets.length; ti++) {
+            const tet = tets[ti];
+            // Tets in the cache may have been deleted since it was built.
+            if (!mesh.exists(tet)) continue;
+
+            // Find the slot of vertex_id in this tet — present by
+            // construction unless a flip re-used the tet ID with
+            // different vertices, in which case skip.
+            let v_slot = -1;
+            for (let i = 0; i < 4; i++) {
+                if (mesh.getVertexIndex(tet, i) === vertex_id) {
+                    v_slot = i;
+                    break;
+                }
+            }
+            if (v_slot < 0) continue;
+
+            // The 3 faces containing vertex_id are the ones NOT opposite v_slot.
+            for (let j = 0; j < 4; j++) {
+                if (j === v_slot) continue;
+                if (mesh.getNeighbour(tet, j) === INVALID_NEIGHBOUR) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+
+    // Slow path: scan every live tet.
+    let is_boundary = false;
+
+    mesh.forEach((tet, m) => {
+        if (is_boundary) return;
+
+        // Find the slot of vertex_id in this tet (if any).
+        let v_slot = -1;
+        for (let i = 0; i < 4; i++) {
+            if (m.getVertexIndex(tet, i) === vertex_id) {
+                v_slot = i;
+                break;
+            }
+        }
+        if (v_slot < 0) return;
+
+        // The 3 faces containing vertex_id are the ones NOT opposite v_slot.
+        // (The face opposite v_slot is the only face that excludes vertex_id.)
+        for (let j = 0; j < 4; j++) {
+            if (j === v_slot) continue;
+            if (m.getNeighbour(tet, j) === INVALID_NEIGHBOUR) {
+                is_boundary = true;
+                return;
+            }
+        }
+    });
+
+    return is_boundary;
+}

package/src/core/geom/3d/tetrahedra/tetrahedron_compute_quality.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Compute the radius-ratio shape quality of a tetrahedron given by 4 vertex
+ * indices into the points array. Normalised so a regular tet returns 1 and
+ * a degenerate (zero-volume) tet returns 0.
+ *
+ * Formula: 3 · r_in / r_circ where
+ *   r_in  = inscribed-sphere radius = 3·|V| / S_total
+ *   r_circ = circumscribed-sphere radius
+ *   S_total = sum of the 4 face areas
+ *   |V| = absolute signed volume
+ *
+ * Quality bands (rough rule of thumb for the radius-ratio metric):
+ *   1.0       regular tet
+ *   ≥ 0.5     well-shaped, safe for FEM / fluid
+ *   0.1–0.5   acceptable, may slow convergence
+ *   0.01–0.1  sliver — usually a target for flipping / smoothing
+ *   < 0.01    near-degenerate, almost flat
+ *
+ * Indexed form (not mesh-bound) so callers can score hypothetical tets
+ * during a flip-candidate search without committing the flip first. The
+ * existing mesh-form wrapper {@link compute_tetrahedron_quality} fetches
+ * the four vertex IDs and forwards here.
+ *
+ * @param {ArrayLike<number>} points flat (x,y,z) positions
+ * @param {number} a vertex index
+ * @param {number} b vertex index
+ * @param {number} c vertex index
+ * @param {number} d vertex index
+ * @returns {number} quality in [0, 1]
+ */
+export function tetrahedron_compute_quality(points: ArrayLike<number>, a: number, b: number, c: number, d: number): number;
+//# sourceMappingURL=tetrahedron_compute_quality.d.ts.map

package/src/core/geom/3d/tetrahedra/tetrahedron_compute_quality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tetrahedron_compute_quality.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/tetrahedra/tetrahedron_compute_quality.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,oDAPW,UAAU,MAAM,CAAC,KACjB,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CA+BlB"}

package/src/core/geom/3d/tetrahedra/tetrahedron_compute_quality.js

@@ -0,0 +1,66 @@
+import { compute_triangle_area_3d } from "../triangle/compute_triangle_area_3d.js";
+import { tetrahedron_compute_circumsphere } from "./tetrahedron_compute_circumsphere.js";
+import { tetrahedron_compute_signed_volume } from "./tetrahedron_compute_signed_volume.js";
+
+const circ_scratch = new Float64Array(4);
+
+/**
+ * Compute the radius-ratio shape quality of a tetrahedron given by 4 vertex
+ * indices into the points array. Normalised so a regular tet returns 1 and
+ * a degenerate (zero-volume) tet returns 0.
+ *
+ * Formula: 3 · r_in / r_circ where
+ *   r_in  = inscribed-sphere radius = 3·|V| / S_total
+ *   r_circ = circumscribed-sphere radius
+ *   S_total = sum of the 4 face areas
+ *   |V| = absolute signed volume
+ *
+ * Quality bands (rough rule of thumb for the radius-ratio metric):
+ *   1.0       regular tet
+ *   ≥ 0.5     well-shaped, safe for FEM / fluid
+ *   0.1–0.5   acceptable, may slow convergence
+ *   0.01–0.1  sliver — usually a target for flipping / smoothing
+ *   < 0.01    near-degenerate, almost flat
+ *
+ * Indexed form (not mesh-bound) so callers can score hypothetical tets
+ * during a flip-candidate search without committing the flip first. The
+ * existing mesh-form wrapper {@link compute_tetrahedron_quality} fetches
+ * the four vertex IDs and forwards here.
+ *
+ * @param {ArrayLike<number>} points flat (x,y,z) positions
+ * @param {number} a vertex index
+ * @param {number} b vertex index
+ * @param {number} c vertex index
+ * @param {number} d vertex index
+ * @returns {number} quality in [0, 1]
+ */
+export function tetrahedron_compute_quality(points, a, b, c, d) {
+    const ax = points[a * 3],     ay = points[a * 3 + 1], az = points[a * 3 + 2];
+    const bx = points[b * 3],     by = points[b * 3 + 1], bz = points[b * 3 + 2];
+    const cx = points[c * 3],     cy = points[c * 3 + 1], cz = points[c * 3 + 2];
+    const dx = points[d * 3],     dy = points[d * 3 + 1], dz = points[d * 3 + 2];
+
+    // Negative signed volume → inverted tet. Treated as 0 quality so any
+    // mesh-improvement driver naturally rejects moves that would produce
+    // them. (For the radius-ratio shape value of the underlying triangle
+    // configuration, the caller would need to take abs(vol) explicitly.)
+    const signed_vol = tetrahedron_compute_signed_volume(points, a, b, c, d);
+    if (signed_vol <= 0) return 0;
+    const vol = signed_vol;
+
+    const area =
+        compute_triangle_area_3d(bx, by, bz, cx, cy, cz, dx, dy, dz) +
+        compute_triangle_area_3d(ax, ay, az, cx, cy, cz, dx, dy, dz) +
+        compute_triangle_area_3d(ax, ay, az, bx, by, bz, dx, dy, dz) +
+        compute_triangle_area_3d(ax, ay, az, bx, by, bz, cx, cy, cz);
+
+    if (area === 0) return 0;
+
+    tetrahedron_compute_circumsphere(circ_scratch, points, a, b, c, d);
+    const r_circ_sq = circ_scratch[3];
+    if (!isFinite(r_circ_sq) || r_circ_sq <= 0) return 0;
+    const r_circ = Math.sqrt(r_circ_sq);
+
+    const r_in = 3 * vol / area;
+    return 3 * r_in / r_circ;
+}

package/src/core/geom/3d/topology/struct/binary/BinaryElementPool.d.ts

@@ -66,12 +66,27 @@ export class BinaryElementPool implements Iterable<number> {
      * @private
      */
     private __capacity;
+    /**
+     * Occupancy index: bit `id` is 1 when slot `id` is allocated, 0 when
+     * free. Lets {@link is_allocated} answer in O(1) instead of scanning
+     * {@link __free}. The {@link __free} stack remains the allocator; this
+     * is purely a membership accelerator kept in lockstep with it.
+     * `preventShrink` stops the bitset reallocating smaller when top slots
+     * are cleared — its capacity tracks the pool, not the live set.
+     * @type {BitSet}
+     * @private
+     */
+    private __occupancy;
     /**
      *
      * @param {ArrayBuffer} buffer
      * @param {number} allocated_record_count
      */
     fromArrayBuffer(buffer: ArrayBuffer, allocated_record_count?: number): void;
+    /**
+     *
+     * @returns {ArrayBuffer}
+     */
     get arrayBuffer(): ArrayBuffer;
     /**
      * Size of a single record in bytes
@@ -155,12 +170,30 @@ export class BinaryElementPool implements Iterable<number> {
      * @return {number} offset where the range starts, this is your first ID basically
      */
     allocate_continuous(count: number): number;
+    /**
+     * Swap the bytes of two items in-place.
+     * No-op when `a === b`.
+     * @param {number} a item ID
+     * @param {number} b item ID
+     */
+    swap(a: number, b: number): void;
     /**
      * Please note that this method does not perform any checks at all.
      * You have to make sure that the item is actually unneeded and no duplicate calls are made
      * @param {number} id
      */
     release(id: number): void;
+    /**
+     * Unsafe operation, clears the free set without any checks.
+     */
+    clear_free_set(): void;
+    /**
+     * Reduce the used region down to `new_size` and discard the free set.
+     * Underlying memory is not reallocated; use {@link trim} for that.
+     * The caller is responsible for ensuring that no live data lives at IDs >= new_size.
+     * @param {number} new_size must not exceed the current {@link size}
+     */
+    truncate(new_size: number): void;
     /**
      * Removed all data from the pool
      * Note that initial allocation pointer is set to 0
@@ -171,6 +204,14 @@ export class BinaryElementPool implements Iterable<number> {
      * @param {BinaryElementPool} other
      */
     copy(other: BinaryElementPool): void;
+    /**
+     * Rebuild the occupancy index from `__size` and the current free set:
+     * every id in `[0, size)` is allocated except those held in `__free`.
+     * Used after {@link copy}, where the data buffer and free set are adopted
+     * wholesale.
+     * @private
+     */
+    private __rebuild_occupancy_from_free;
     /**
      * Used for type checking
      * @readonly

package/src/core/geom/3d/topology/struct/binary/BinaryElementPool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BinaryElementPool.d.ts","sourceRoot":"","sources":["../../../../../../../../src/core/geom/3d/topology/struct/binary/BinaryElementPool.js"],"names":[],"mappings":"AA0BA;;;GAGG;AACH,mDAFyB,MAAM;IA0B3B;;;;;OAKG;IACH,uBAJW,MAAM,qBACN,MAAM,sBACN,OAAO,EAkDjB;IA5ED;;;;OAIG;IACH,eAAY;IAEZ;;;;;OAKG;IACH,uBAAmB;IAEnB;;;;OAIG;IACH,eAAW;IAeP;;;;OAIG;IACH,oBAA4B;IAG5B;;;;OAIG;IACH,sBAA8F;IAC9F;;;;OAIG;IACH,qBAAsD;IACtD;;;;OAIG;IACH,sBAAwD;IACxD;;;;OAIG;IACH,uBAA0D;IAC1D,oBAAiD;IAEjD;;;;OAIG;IACH,mBAAkC;IAItC;;;;OAIG;IACH,wBAHW,WAAW,2BACX,MAAM,QAsBhB;IAED,+BAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;;OAIG;IACH,mBAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;OAGG;IACH,uBAEC;IAGD;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;OAEG;IACH,aAEC;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACL,MAAM,CAMjB;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACL,MAAM,CAIjB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACL,OAAO,CAsBlB;IAED;;;;OAIG;IACH,uBAwBC;IAED;;;;OAIG;IACH,wBAQC;IAED;;;OAGG;IACH,0BAFW,MAAM,QAMhB;IAGD;;;OAGG;IACH,YAFY,MAAM,CAqBjB;IAED;;;;OAIG;IACH,2BAHW,MAAM,GACL,MAAM,CAcjB;IAED;;;;OAIG;IACH,YAFW,MAAM,QAYhB;IAED;;;OAGG;IACH,cAGC;IAED;;;OAGG;IACH,YAFW,iBAAiB,QA0B3B;IAoBL;;;;OAIG;IACH,8BAFU,OAAO,CAE8B;IAvB3C;;;OAGG;IACH,qBAFY,UAAU,MAAM,CAAC,CAa5B;CACJ"}
+{"version":3,"file":"BinaryElementPool.d.ts","sourceRoot":"","sources":["../../../../../../../../src/core/geom/3d/topology/struct/binary/BinaryElementPool.js"],"names":[],"mappings":"AA4BA;;;GAGG;AACH,mDAFyB,MAAM;IA0B3B;;;;;OAKG;IACH,uBAJW,MAAM,qBACN,MAAM,sBACN,OAAO,EA+DjB;IAzFD;;;;OAIG;IACH,eAAY;IAEZ;;;;;OAKG;IACH,uBAAmB;IAEnB;;;;OAIG;IACH,eAAW;IAeP;;;;OAIG;IACH,oBAA4B;IAG5B;;;;OAIG;IACH,sBAA8F;IAC9F;;;;OAIG;IACH,qBAAsD;IACtD;;;;OAIG;IACH,sBAAwD;IACxD;;;;OAIG;IACH,uBAA0D;IAC1D,oBAAiD;IAEjD;;;;OAIG;IACH,mBAAkC;IAElC;;;;;;;;;OASG;IACH,oBAA8C;IAKlD;;;;OAIG;IACH,wBAHW,WAAW,2BACX,MAAM,QA8BhB;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;;OAIG;IACH,mBAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;OAGG;IACH,uBAEC;IAGD;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;OAEG;IACH,aAEC;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACL,MAAM,CAMjB;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACL,MAAM,CAIjB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACL,OAAO,CAYlB;IAED;;;;OAIG;IACH,uBA2BC;IAED;;;;OAIG;IACH,wBAQC;IAED;;;OAGG;IACH,0BAFW,MAAM,QAMhB;IAGD;;;OAGG;IACH,YAFY,MAAM,CAyBjB;IAED;;;;OAIG;IACH,2BAHW,MAAM,GACL,MAAM,CAmBjB;IAED;;;;;OAKG;IACH,QAHW,MAAM,KACN,MAAM,QAiBhB;IAED;;;;OAIG;IACH,YAFW,MAAM,QAchB;IAED;;OAEG;IACH,uBAOC;IAED;;;;;OAKG;IACH,mBAFW,MAAM,QAchB;IAED;;;OAGG;IACH,cAIC;IAED;;;OAGG;IACH,YAFW,iBAAiB,QA4B3B;IAED;;;;;;OAMG;IACH,sCAaC;IAoBL;;;;OAIG;IACH,8BAFU,OAAO,CAE8B;IAvB3C;;;OAGG;IACH,qBAFY,UAAU,MAAM,CAAC,CAa5B;CACJ"}

package/src/core/geom/3d/topology/struct/binary/BinaryElementPool.js

@@ -1,6 +1,8 @@
 import { assert } from "../../../../../assert.js";
 import { align_4 } from "../../../../../binary/align_4.js";
+import { BitSet } from "../../../../../binary/BitSet.js";
 import { makeArrayBuffer } from "../../../../../binary/makeArrayBuffer.js";
+import { array_swap } from "../../../../../collection/array/array_swap.js";
 import { array_buffer_copy } from "../../../../../collection/array/typed/array_buffer_copy.js";
 import { typed_array_copy } from "../../../../../collection/array/typed/typed_array_copy.js";
 import { max3 } from "../../../../../math/max3.js";
@@ -106,6 +108,19 @@ export class BinaryElementPool {
          */
         this.__capacity = initial_capacity;
 
+        /**
+         * Occupancy index: bit `id` is 1 when slot `id` is allocated, 0 when
+         * free. Lets {@link is_allocated} answer in O(1) instead of scanning
+         * {@link __free}. The {@link __free} stack remains the allocator; this
+         * is purely a membership accelerator kept in lockstep with it.
+         * `preventShrink` stops the bitset reallocating smaller when top slots
+         * are cleared — its capacity tracks the pool, not the live set.
+         * @type {BitSet}
+         * @private
+         */
+        this.__occupancy = new BitSet(this.__capacity);
+        this.__occupancy.preventShrink();
+
     }
 
     /**
@@ -133,8 +148,20 @@ export class BinaryElementPool {
         // drop free slots
         this.__free_pointer = 0;
         this.__size = allocated_record_count;
+
+        // Rebuild occupancy for the adopted buffer: the free set is dropped, so
+        // exactly [0, allocated_record_count) is allocated.
+        this.__occupancy = new BitSet(capacity);
+        this.__occupancy.preventShrink();
+        if (allocated_record_count > 0) {
+            this.__occupancy.setRange(0, allocated_record_count - 1);
+        }
     }
 
+    /**
+     *
+     * @returns {ArrayBuffer}
+     */
     get arrayBuffer() {
         return this.__data_buffer;
     }
@@ -230,18 +257,8 @@ export class BinaryElementPool {
             return false;
         }
 
-        const pointer = this.__free_pointer;
-
-        for (let i = 0; i < pointer; i++) {
-            const _id = this.__free[i];
-
-            if (id === _id) {
-                // found in unallocated set
-                return false;
-            }
-        }
-
-        return true;
+        // O(1) occupancy bit read.
+        return this.__occupancy.get(id);
     }
 
     /**
@@ -273,6 +290,9 @@ export class BinaryElementPool {
         typed_array_copy(old_data_uint8, this.__data_uint8);
 
         this.__capacity = new_capacity;
+
+        // The bitset self-manages capacity on set(); preventShrink keeps it from
+        // dropping below the used region on clears. Nothing to do here.
     }
 
     /**
@@ -309,7 +329,9 @@ export class BinaryElementPool {
         if (this.__free_pointer > 0) {
             // get unused slot
             this.__free_pointer--;
-            return this.__free[this.__free_pointer];
+            const id = this.__free[this.__free_pointer];
+            this.__occupancy.set(id, true);
+            return id;
         }
 
         // allocate new
@@ -323,6 +345,8 @@ export class BinaryElementPool {
 
         // assert.greaterThan(this.__data_buffer.byteLength, result * this.__item_size, 'memory underflow');
 
+        this.__occupancy.set(result, true);
+
         return result;
     }
 
@@ -342,9 +366,37 @@ export class BinaryElementPool {
 
         // assert.greaterThanOrEqual(this.__data_buffer.byteLength, (offset + count) * this.__item_size, 'memory underflow');
 
+        // Mark the whole range allocated.
+        if (count > 0) {
+            this.__occupancy.setRange(offset, offset + count - 1);
+        }
+
         return offset;
     }
 
+    /**
+     * Swap the bytes of two items in-place.
+     * No-op when `a === b`.
+     * @param {number} a item ID
+     * @param {number} b item ID
+     */
+    swap(a, b) {
+        assert.isNonNegativeInteger(a, 'a');
+        assert.isNonNegativeInteger(b, 'b');
+
+        if (a === b) {
+            return;
+        }
+
+        const item_size = this.__item_size;
+
+        array_swap(
+            this.__data_uint8, a * item_size,
+            this.__data_uint8, b * item_size,
+            item_size
+        );
+    }
+
     /**
      * Please note that this method does not perform any checks at all.
      * You have to make sure that the item is actually unneeded and no duplicate calls are made
@@ -354,11 +406,45 @@ export class BinaryElementPool {
         if (id === this.__size - 1) {
             // releasing item at the end of the reserved region, don't have to push it into free set
             this.__size--;
+            this.__occupancy.set(id, false);
         } else if (id >= this.__size) {
             // do nothing, just throw it away
             // this should never happen
         } else {
             this.__free[this.__free_pointer++] = id;
+            this.__occupancy.set(id, false);
+        }
+    }
+
+    /**
+     * Unsafe operation, clears the free set without any checks.
+     */
+    clear_free_set() {
+        this.__free_pointer = 0;
+
+        // With the free set empty, every slot in [0, size) is allocated again.
+        if (this.__size > 0) {
+            this.__occupancy.setRange(0, this.__size - 1);
+        }
+    }
+
+    /**
+     * Reduce the used region down to `new_size` and discard the free set.
+     * Underlying memory is not reallocated; use {@link trim} for that.
+     * The caller is responsible for ensuring that no live data lives at IDs >= new_size.
+     * @param {number} new_size must not exceed the current {@link size}
+     */
+    truncate(new_size) {
+        assert.isNonNegativeInteger(new_size, 'new_size');
+        assert.lessThanOrEqual(new_size, this.__size, 'new_size must not exceed current size');
+
+        this.__size = new_size;
+        this.__free_pointer = 0;
+
+        // Free set discarded: [0, new_size) is the live region with no holes.
+        this.__occupancy.reset();
+        if (new_size > 0) {
+            this.__occupancy.setRange(0, new_size - 1);
         }
     }
 
@@ -369,6 +455,7 @@ export class BinaryElementPool {
     clear() {
         this.__size = 0;
         this.__free_pointer = 0;
+        this.__occupancy.reset();
     }
 
     /**
@@ -399,6 +486,30 @@ export class BinaryElementPool {
 
         this.__free_pointer = other.__free_pointer;
         this.__free = other.__free.slice();
+
+        this.__rebuild_occupancy_from_free();
+    }
+
+    /**
+     * Rebuild the occupancy index from `__size` and the current free set:
+     * every id in `[0, size)` is allocated except those held in `__free`.
+     * Used after {@link copy}, where the data buffer and free set are adopted
+     * wholesale.
+     * @private
+     */
+    __rebuild_occupancy_from_free() {
+        this.__occupancy = new BitSet(Math.max(this.__capacity, this.__size));
+        this.__occupancy.preventShrink();
+
+        if (this.__size > 0) {
+            this.__occupancy.setRange(0, this.__size - 1);
+        }
+
+        const free = this.__free;
+        const pointer = this.__free_pointer;
+        for (let i = 0; i < pointer; i++) {
+            this.__occupancy.set(free[i], false);
+        }
     }
 
     /**

package/src/core/geom/3d/topology/struct/binary/BinaryTopology.d.ts

@@ -25,6 +25,20 @@ export class BinaryTopology {
      *      l: uint32 // The list of loops around the edge points at a Loop
      *      v1_disk_link: uint32[2] // Disk Cycle Pointers edge around vertex v1 and d2 does the same for v2.
      *      v2_disk_link: uint32[2] // see above
+     *
+     * Disk cycle convention:
+     *   For every vertex v with at least one incident edge, the edges incident
+     *   to v form a doubly-linked cycle threaded through their disk_link slots.
+     *   Each non-self-loop edge e uses exactly ONE slot in v's cycle: the v1
+     *   slot if `vertex1(e) === v`, otherwise the v2 slot. Callers select the
+     *   side with `is_v1 = edge_read_vertex1(e) === v`.
+     *
+     *   Self-loops (vertex1(e) === vertex2(e) === v) are represented with ONE
+     *   slot too, by convention the v1 slot. The v2_disk_link of a self-loop is
+     *   UNSPECIFIED -- readers must not follow it, writers must not assume any
+     *   prior value. Insertion/removal helpers must be called exactly once per
+     *   self-loop (not once per "endpoint"), otherwise the v1 slot is scribbled
+     *   on a second time and the cycle is corrupted.
      * @type {BinaryElementPool}
      * @private
      */
@@ -51,6 +65,31 @@ export class BinaryTopology {
      * @private
      */
     private __face_pool;
+    /**
+     * Optional opaque per-vertex data pool. Item IDs map 1:1 with vertex IDs.
+     * Null until {@link create_vertex_data} is called.
+     * @type {BinaryElementPool|null}
+     * @private
+     */
+    private __vertex_data_pool;
+    /**
+     * Optional opaque per-edge data pool. Item IDs map 1:1 with edge IDs.
+     * @type {BinaryElementPool|null}
+     * @private
+     */
+    private __edge_data_pool;
+    /**
+     * Optional opaque per-loop data pool. Item IDs map 1:1 with loop IDs.
+     * @type {BinaryElementPool|null}
+     * @private
+     */
+    private __loop_data_pool;
+    /**
+     * Optional opaque per-face data pool. Item IDs map 1:1 with face IDs.
+     * @type {BinaryElementPool|null}
+     * @private
+     */
+    private __face_data_pool;
     /**
      * Total (approximate) size of this structure in memory, in bytes
      * @return {number}
@@ -81,6 +120,79 @@ export class BinaryTopology {
      * @returns {BinaryElementPool}
      */
     get faces(): BinaryElementPool;
+    /**
+     * Opaque per-vertex data. The user is responsible for encoding/decoding the bytes,
+     * and for keeping the pool's allocation in sync with {@link vertices} — typically
+     * by calling `vertex_data.allocate()` whenever a vertex is allocated.
+     * Slot at vertex ID X holds that vertex's data.
+     * @returns {BinaryElementPool|null} null when no data pool has been created
+     */
+    get vertex_data(): BinaryElementPool;
+    /**
+     * Opaque per-edge data. See {@link vertex_data}.
+     * @returns {BinaryElementPool|null} null when no data pool has been created
+     */
+    get edge_data(): BinaryElementPool;
+    /**
+     * Opaque per-loop data. See {@link vertex_data}.
+     * @returns {BinaryElementPool|null} null when no data pool has been created
+     */
+    get loop_data(): BinaryElementPool;
+    /**
+     * Opaque per-face data. See {@link vertex_data}.
+     * @returns {BinaryElementPool|null} null when no data pool has been created
+     */
+    get face_data(): BinaryElementPool;
+    /**
+     * Create an opaque per-vertex data pool. If vertices already exist, the pool is
+     * sized to match (bytes zero-initialized).
+     *
+     * After this returns, it is the caller's responsibility to keep the data pool's
+     * allocation in sync with {@link vertices} (call `vertex_data.allocate()` /
+     * `vertex_data.allocate_continuous(n)` / `vertex_data.release(id)` /
+     * `vertex_data.clear()` alongside the matching base pool calls).
+     *
+     * @param {number} item_size_bytes
+     */
+    create_vertex_data(item_size_bytes: number): void;
+    /**
+     * Create an opaque per-edge data pool. See {@link create_vertex_data}.
+     * @param {number} item_size_bytes
+     */
+    create_edge_data(item_size_bytes: number): void;
+    /**
+     * Create an opaque per-loop data pool. See {@link create_vertex_data}.
+     * @param {number} item_size_bytes
+     */
+    create_loop_data(item_size_bytes: number): void;
+    /**
+     * Create an opaque per-face data pool. See {@link create_vertex_data}.
+     * @param {number} item_size_bytes
+     */
+    create_face_data(item_size_bytes: number): void;
+    /**
+     * @returns {boolean} true if a data pool was removed, false if there was none
+     */
+    delete_vertex_data(): boolean;
+    /**
+     * @returns {boolean} true if a data pool was removed, false if there was none
+     */
+    delete_edge_data(): boolean;
+    /**
+     * @returns {boolean} true if a data pool was removed, false if there was none
+     */
+    delete_loop_data(): boolean;
+    /**
+     * @returns {boolean} true if a data pool was removed, false if there was none
+     */
+    delete_face_data(): boolean;
+    /**
+     * @param {BinaryElementPool} base
+     * @param {number} item_size_bytes
+     * @returns {BinaryElementPool}
+     * @private
+     */
+    private __create_data_pool;
     /**
      * Clear the topology, removed all data
      */
@@ -201,6 +313,28 @@ export class BinaryTopology {
      * @param {number} id edge ID
      */
     edge_write_v2_disk_prev(id: number, value: number): void;
+    /**
+     * Allocate a new vertex and, if the vertex data pool exists, ensure its
+     * underlying buffer has capacity for the new ID. Tracking the data pool's
+     * __size remains the caller's responsibility.
+     * @returns {number} vertex ID
+     */
+    vertex_create(): number;
+    /**
+     * Allocate a new edge. See {@link vertex_create}.
+     * @returns {number} edge ID
+     */
+    edge_create(): number;
+    /**
+     * Allocate a new face. See {@link vertex_create}.
+     * @returns {number} face ID
+     */
+    face_create(): number;
+    /**
+     * Allocate a new loop and put it into a valid initial state.
+     * See {@link vertex_create} for the data pool sync semantics.
+     * @returns {number} loop ID
+     */
     loop_create(): number;
     /**
      * Put loop into valid initial state, set all pointers to NULL

package/src/core/geom/3d/topology/struct/binary/BinaryTopology.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BinaryTopology.d.ts","sourceRoot":"","sources":["../../../../../../../../src/core/geom/3d/topology/struct/binary/BinaryTopology.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"BinaryTopology.d.ts","sourceRoot":"","sources":["../../../../../../../../src/core/geom/3d/topology/struct/binary/BinaryTopology.js"],"names":[],"mappings":"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"}