@woosh/meep-engine 2.165.6 → 2.166.0

package/src/engine/graphics/trail/tube/TubeX.js

@@ -1,555 +1,557 @@
-import {
-    BufferAttribute,
-    BufferGeometry,
-    DynamicDrawUsage,
-    InterleavedBuffer,
-    InterleavedBufferAttribute
-} from "three";
-import { assert } from "../../../../core/assert.js";
-import { RowFirstTable } from "../../../../core/collection/table/RowFirstTable.js";
-import { aabb3_array_set } from "../../../../core/geom/3d/aabb/aabb3_array_set.js";
-import { v3_orthonormal_matrix_from_normal } from "../../../../core/geom/vec3/v3_orthonormal_matrix_from_normal.js";
-import { max2 } from "../../../../core/math/max2.js";
-import { min2 } from "../../../../core/math/min2.js";
-import {
-    TUBE_ATTRIBUTE_ADDRESS_ALPHA,
-    TUBE_ATTRIBUTE_ADDRESS_BINORMAL,
-    TUBE_ATTRIBUTE_ADDRESS_COLOR,
-    TUBE_ATTRIBUTE_ADDRESS_NORMAL,
-    TUBE_ATTRIBUTE_ADDRESS_OFF,
-    TUBE_ATTRIBUTE_ADDRESS_POSITION,
-    TUBE_ATTRIBUTE_ADDRESS_THICKNESS,
-    tube_attributes_spec
-} from "./tube_attributes_spec.js";
-
-/**
- * Default number of radial subdivisions around the tube. Overridable per-tube
- * via {@link TubeX#setCount}; never hard-coded into the geometry.
- * @type {number}
- */
-const DEFAULT_RADIAL_SEGMENTS = 8;
-
-/**
- * Scratch for the arbitrary default frame written at build time; module-static so
- * setCount stays allocation-free on the data path.
- * @type {Float64Array}
- */
-const m3_default_frame = new Float64Array(9);
-
-/**
- * Dynamic, non-allocating 3D tube geometry — the volumetric analogue of
- * {@link RibbonX}.
- *
- * A tube is a ring buffer of `count` KNOTS along a centre-line. Each knot owns a
- * ring of `radial + 1` vertices: the extra vertex duplicates vertex 0 so the UV
- * seam (u = 0 meeting u = 1) closes cleanly when the texture wraps the tube.
- * Vertices are extruded in the vertex shader from the knot's stored tangent
- * frame, so the CPU only ever writes per-knot data (centre, frame, colour, …) —
- * never per-triangle.
- *
- * Like {@link RibbonX} the geometry is a fixed-capacity ring: {@link rotate}
- * recycles the oldest knot as the new head and rewrites a single segment's worth
- * of indices, so steady-state updates allocate nothing.
- */
-export class TubeX {
-
-    /**
-     * @type {BufferGeometry}
-     */
-    #geometry = new BufferGeometry();
-
-    /**
-     * @type {RowFirstTable}
-     */
-    #data = new RowFirstTable(tube_attributes_spec);
-
-    /**
-     * Knot index at the END (oldest) of the tube.
-     * @type {number}
-     */
-    #tail_index = 0;
-
-    /**
-     * Knot index at the START (newest) of the tube.
-     * @type {number}
-     */
-    #head_index = 0;
-
-    /**
-     * Index of the segment (knot-to-knot span of `radial` quads) currently at the
-     * tail; recycled by {@link rotate}.
-     * @type {number}
-     */
-    #tail_segment_index = 0;
-
-    /**
-     * Number of knots.
-     * @type {number}
-     */
-    #count = 0;
-
-    /**
-     * Number of radial subdivisions. Ring vertex count per knot = radial + 1.
-     * @type {number}
-     */
-    #radial = DEFAULT_RADIAL_SEGMENTS;
-
-    // Interleaved buffers + attribute views over #data; created in buildGeometry().
-    #ib_uint8 = null;
-    #ib_float32 = null;
-    #iba_position = null;
-    #iba_normal = null;
-    #iba_binormal = null;
-    #iba_uv = null;
-    #iba_alpha = null;
-    #iba_thickness = null;
-    #iba_color = null;
-    #ba_index = null;
-
-    dispose() {
-        this.#geometry.dispose();
-    }
-
-    /**
-     * @returns {BufferGeometry}
-     */
-    getGeometry() {
-        return this.#geometry;
-    }
-
-    /**
-     * @returns {number} number of knots
-     */
-    getCount() {
-        return this.#count;
-    }
-
-    /**
-     * @returns {number} radial subdivisions
-     */
-    getRadialSegments() {
-        return this.#radial;
-    }
-
-    getHeadIndex() {
-        return this.#head_index;
-    }
-
-    getTailIndex() {
-        return this.#tail_index;
-    }
-
-    /**
-     * Number of vertices in a single knot ring (includes the duplicated seam vertex).
-     * @returns {number}
-     */
-    get #ring_vertex_count() {
-        return this.#radial + 1;
-    }
-
-    buildGeometry() {
-        const a_uint8 = new Uint8Array(this.#data.data);
-        const a_float32 = new Float32Array(this.#data.data);
-
-        const bpr = this.#data.spec.bytesPerRecord;
-
-        this.#ib_uint8 = new InterleavedBuffer(a_uint8, bpr);
-        this.#ib_float32 = new InterleavedBuffer(a_float32, bpr >> 2);
-
-        this.#iba_position = new InterleavedBufferAttribute(this.#ib_float32, 3, 1, false);
-        this.#iba_normal = new InterleavedBufferAttribute(this.#ib_float32, 3, 4, false);
-        this.#iba_binormal = new InterleavedBufferAttribute(this.#ib_float32, 3, 7, false);
-
-        // off (uv.x) and uv_v (uv.y) are contiguous, exposed as a single vec2.
-        this.#iba_uv = new InterleavedBufferAttribute(this.#ib_float32, 2, 10, false);
-        this.#iba_alpha = new InterleavedBufferAttribute(this.#ib_float32, 1, 12, false);
-        this.#iba_thickness = new InterleavedBufferAttribute(this.#ib_float32, 1, 13, false);
-
-        this.#iba_color = new InterleavedBufferAttribute(this.#ib_uint8, 3, 56, false);
-
-        // Uint32 (not Uint16): vertex count = count * (radial + 1) easily exceeds
-        // 65535 for a long tube with high radial resolution. WebGL2 supports it natively.
-        this.#ba_index = new BufferAttribute(new Uint32Array(0), 1, false);
-
-        this.#geometry.setAttribute('position', this.#iba_position);
-        this.#geometry.setAttribute('tn', this.#iba_normal);
-        this.#geometry.setAttribute('tb', this.#iba_binormal);
-        this.#geometry.setAttribute('tubeUv', this.#iba_uv);
-        this.#geometry.setAttribute('alpha', this.#iba_alpha);
-        this.#geometry.setAttribute('thickness', this.#iba_thickness);
-        this.#geometry.setAttribute('color', this.#iba_color);
-
-        this.#geometry.setIndex(this.#ba_index);
-
-        this.#ib_uint8.setUsage(DynamicDrawUsage);
-        this.#ib_float32.setUsage(DynamicDrawUsage);
-        this.#ba_index.setUsage(DynamicDrawUsage);
-    }
-
-    /**
-     * Write the static angular `off` coordinate (uv.x) for every ring vertex. The
-     * value goes 0 → 1 across the `radial + 1` vertices; vertex `radial` lands on
-     * 1.0 so its shader angle is 2π — co-incident with vertex 0's angle 0, closing
-     * the seam without a wrap-around index.
-     */
-    #initialize_off() {
-        const data = this.#data;
-        const count = this.#count;
-        const radial = this.#radial;
-        const v = this.#ring_vertex_count;
-
-        for (let k = 0; k < count; k++) {
-            const base = k * v;
-            for (let j = 0; j <= radial; j++) {
-                data.writeCellValue(base + j, TUBE_ATTRIBUTE_ADDRESS_OFF, j / radial);
-            }
-        }
-    }
-
-    /**
-     * Seed every knot with a valid (arbitrary) orthonormal frame so the geometry is
-     * well-formed from the moment it is built, before any head movement supplies a
-     * real tangent. Without this the frames would be zero-initialised and the
-     * transport's degeneracy fallback would have to cover the fresh-tube case; a
-     * concrete default keeps the invariant "every knot frame is unit + orthonormal"
-     * unconditionally true (read e.g. by getKnotNormal during transport).
-     */
-    #initialize_frame() {
-        v3_orthonormal_matrix_from_normal(m3_default_frame, 0, 0, 1, 0);
-
-        const nx = m3_default_frame[0], ny = m3_default_frame[1], nz = m3_default_frame[2];
-        const bx = m3_default_frame[3], by = m3_default_frame[4], bz = m3_default_frame[5];
-
-        const count = this.#count;
-
-        for (let k = 0; k < count; k++) {
-            this.setKnotFrame(k, nx, ny, nz, bx, by, bz);
-        }
-    }
-
-    /**
-     * Write the `radial` quads (2 triangles each) bridging the ring of knot `lo`
-     * to the ring of knot `hi`, starting at `address` in the index array.
-     * Winding matches the engine's static tube mesher (make_ring_faces).
-     * @param {number} address index-array offset (in index entries)
-     * @param {number} lo knot index whose ring is the "left" edge
-     * @param {number} hi knot index whose ring is the "right" edge
-     */
-    #write_segment_indices(address, lo, hi) {
-        const indices = this.#ba_index.array;
-        const radial = this.#radial;
-        const v = this.#ring_vertex_count;
-
-        const lo_base = lo * v;
-        const hi_base = hi * v;
-
-        for (let r = 0; r < radial; r++) {
-            const a = lo_base + r;
-            const b = hi_base + r;
-            const c = hi_base + r + 1;
-            const d = lo_base + r + 1;
-
-            const ci = address + r * 6;
-
-            indices[ci] = a;
-            indices[ci + 1] = b;
-            indices[ci + 2] = d;
-
-            indices[ci + 3] = b;
-            indices[ci + 4] = c;
-            indices[ci + 5] = d;
-        }
-    }
-
-    /**
-     * Build the index buffer as a linear strip of `count - 1` segments.
-     */
-    #initialize_index() {
-        const segment_count = this.#count - 1;
-        const indices_per_segment = this.#radial * 6;
-
-        for (let s = 0; s < segment_count; s++) {
-            this.#write_segment_indices(s * indices_per_segment, s, s + 1);
-        }
-    }
-
-    /**
-     * @param {number[]|Float32Array} result
-     * @param {number} knot_index
-     */
-    getKnotPosition(result, knot_index) {
-        const row = knot_index * this.#ring_vertex_count;
-        const data = this.#data;
-
-        result[0] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_POSITION);
-        result[1] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_POSITION + 1);
-        result[2] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_POSITION + 2);
-    }
-
-    /**
-     * Read the stored ring normal of a knot. Used by the head to parallel-transport
-     * its frame from the previous knot.
-     * @param {number[]|Float32Array} result
-     * @param {number} knot_index
-     */
-    getKnotNormal(result, knot_index) {
-        const row = knot_index * this.#ring_vertex_count;
-        const data = this.#data;
-
-        result[0] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_NORMAL);
-        result[1] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_NORMAL + 1);
-        result[2] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_NORMAL + 2);
-    }
-
-    /**
-     * Read the stored ring binormal of a knot.
-     * @param {number[]|Float32Array} result
-     * @param {number} knot_index
-     */
-    getKnotBinormal(result, knot_index) {
-        const row = knot_index * this.#ring_vertex_count;
-        const data = this.#data;
-
-        result[0] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_BINORMAL);
-        result[1] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_BINORMAL + 1);
-        result[2] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_BINORMAL + 2);
-    }
-
-    /**
-     * Write a vec3 attribute to all ring vertices of a knot.
-     * @param {number} knot_index
-     * @param {number} attribute_index
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     */
-    setKnotAttribute_Vector3(knot_index, attribute_index, x, y, z) {
-        const data = this.#data;
-        const v = this.#ring_vertex_count;
-        const base = knot_index * v;
-
-        for (let j = 0; j < v; j++) {
-            const row = base + j;
-            data.writeCellValue(row, attribute_index, x);
-            data.writeCellValue(row, attribute_index + 1, y);
-            data.writeCellValue(row, attribute_index + 2, z);
-        }
-    }
-
-    /**
-     * Write a scalar attribute to all ring vertices of a knot.
-     * @param {number} knot_index
-     * @param {number} attribute_index
-     * @param {number} value
-     */
-    setKnotAttribute_Scalar(knot_index, attribute_index, value) {
-        const data = this.#data;
-        const v = this.#ring_vertex_count;
-        const base = knot_index * v;
-
-        for (let j = 0; j < v; j++) {
-            data.writeCellValue(base + j, attribute_index, value);
-        }
-    }
-
-    /**
-     * Add `delta` to a scalar attribute on every ring vertex of a knot.
-     * @param {number} knot_index
-     * @param {number} attribute_index
-     * @param {number} delta
-     * @returns {number} incremented value
-     */
-    incrementKnotAttribute_Scalar(knot_index, attribute_index, delta) {
-        const data = this.#data;
-        const v = this.#ring_vertex_count;
-        const base = knot_index * v;
-
-        const value = data.readCellValue(base, attribute_index) + delta;
-
-        for (let j = 0; j < v; j++) {
-            data.writeCellValue(base + j, attribute_index, value);
-        }
-
-        return value;
-    }
-
-    /**
-     * @param {number} knot_index
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     */
-    setKnotPosition(knot_index, x, y, z) {
-        assert.isNonNegativeInteger(knot_index, 'knot_index');
-
-        this.setKnotAttribute_Vector3(knot_index, TUBE_ATTRIBUTE_ADDRESS_POSITION, x, y, z);
-
-        this.#ib_float32.needsUpdate = true;
-    }
-
-    /**
-     * Set the orienting tangent frame of a knot. `nx,ny,nz` and `bx,by,bz` must be
-     * unit vectors, mutually orthogonal and perpendicular to the local tangent.
-     * @param {number} knot_index
-     * @param {number} nx
-     * @param {number} ny
-     * @param {number} nz
-     * @param {number} bx
-     * @param {number} by
-     * @param {number} bz
-     */
-    setKnotFrame(knot_index, nx, ny, nz, bx, by, bz) {
-        this.setKnotAttribute_Vector3(knot_index, TUBE_ATTRIBUTE_ADDRESS_NORMAL, nx, ny, nz);
-        this.setKnotAttribute_Vector3(knot_index, TUBE_ATTRIBUTE_ADDRESS_BINORMAL, bx, by, bz);
-
-        this.#ib_float32.needsUpdate = true;
-    }
-
-    /**
-     * @param {number} knot_index
-     * @param {number} r 0..255
-     * @param {number} g 0..255
-     * @param {number} b 0..255
-     */
-    setKnotColor(knot_index, r, g, b) {
-        assert.isNonNegativeInteger(knot_index, 'knot_index');
-
-        this.setKnotAttribute_Vector3(knot_index, TUBE_ATTRIBUTE_ADDRESS_COLOR, r, g, b);
-
-        this.#ib_uint8.needsUpdate = true;
-    }
-
-    /**
-     * @param {number} knot_index
-     * @param {number} value
-     */
-    setKnotAlpha(knot_index, value) {
-        this.setKnotAttribute_Scalar(knot_index, TUBE_ATTRIBUTE_ADDRESS_ALPHA, value);
-
-        this.#ib_float32.needsUpdate = true;
-    }
-
-    /**
-     * @param {number} knot_index
-     * @param {number} value tube diameter
-     */
-    setKnotThickness(knot_index, value) {
-        this.setKnotAttribute_Scalar(knot_index, TUBE_ATTRIBUTE_ADDRESS_THICKNESS, value);
-
-        this.#ib_float32.needsUpdate = true;
-    }
-
-    /**
-     * @param {number} count number of knots (>= 2)
-     * @param {number} [radial] radial subdivisions (>= 3)
-     */
-    setCount(count, radial = DEFAULT_RADIAL_SEGMENTS) {
-        assert.greaterThanOrEqual(count, 2, 'a tube needs at least 2 knots (one segment)');
-        assert.isNonNegativeInteger(count, 'count');
-        assert.greaterThanOrEqual(radial, 3, 'a tube ring needs at least 3 radial segments');
-        assert.isNonNegativeInteger(radial, 'radial');
-
-        this.#geometry.dispose();
-
-        this.#radial = radial;
-
-        const v = radial + 1;
-        const vertex_count = count * v;
-
-        if (this.#data.length > vertex_count) {
-            this.#data.removeRows(vertex_count, this.#data.length - vertex_count);
-        }
-
-        this.#data.setCapacity(vertex_count);
-        this.#data.length = vertex_count;
-
-        const a_uint8 = new Uint8Array(this.#data.data);
-        const a_float32 = new Float32Array(this.#data.data);
-
-        const segment_count = count - 1;
-        const triangle_count = segment_count * radial * 2;
-        const index_array_size = triangle_count * 3;
-        const index_array = new Uint32Array(index_array_size);
-
-        this.#ba_index.array = index_array;
-        this.#ba_index.count = index_array_size;
-
-        this.#ib_uint8.array = a_uint8;
-        this.#ib_float32.array = a_float32;
-
-        this.#ib_uint8.count = vertex_count;
-        this.#ib_float32.count = vertex_count;
-
-        this.#head_index = 0;
-        this.#tail_index = count - 1;
-        this.#tail_segment_index = segment_count - 1;
-
-        this.#count = count;
-
-        this.#initialize_off();
-        this.#initialize_frame();
-        this.#initialize_index();
-    }
-
-    /**
-     * NOTE: takes tube thickness into account.
-     * @param {AABB3|ArrayLike<number>} result
-     */
-    computeBoundingBox(result) {
-        const count = this.#count;
-        const v = this.#ring_vertex_count;
-        const data = this.#data;
-
-        let _x0 = Infinity, _y0 = Infinity, _z0 = Infinity;
-        let _x1 = -Infinity, _y1 = -Infinity, _z1 = -Infinity;
-
-        for (let k = 0; k < count; k++) {
-            const row = k * v;
-
-            const half_thickness = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_THICKNESS) * 0.5;
-
-            const x = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_POSITION);
-            const y = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_POSITION + 1);
-            const z = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_POSITION + 2);
-
-            _x0 = min2(_x0, x - half_thickness);
-            _y0 = min2(_y0, y - half_thickness);
-            _z0 = min2(_z0, z - half_thickness);
-            _x1 = max2(_x1, x + half_thickness);
-            _y1 = max2(_y1, y + half_thickness);
-            _z1 = max2(_z1, z + half_thickness);
-        }
-
-        aabb3_array_set(result, 0, _x0, _y0, _z0, _x1, _y1, _z1);
-    }
-
-    /**
-     * Recycle the oldest knot as the new head, in O(radial). Mirrors
-     * {@link RibbonX#rotate}: the head/tail pointers decrement together (preserving
-     * `head === (tail + 1) mod count`), and the single tail segment's indices are
-     * rewritten to bridge the previous head's ring to the recycled (new head) ring.
-     */
-    rotate() {
-        const old_tail = this.#tail_index;
-        const old_head = this.#head_index;
-
-        const max_index = this.#count - 1;
-
-        // The recycled slot (old tail) becomes the new head: head and tail step
-        // back in lockstep so head stays exactly one slot ahead of tail.
-        this.#tail_index = old_tail <= 0 ? max_index : old_tail - 1;
-        this.#head_index = old_head <= 0 ? max_index : old_head - 1;
-
-        const old_segment = this.#tail_segment_index;
-        const address = old_segment * this.#radial * 6;
-
-        this.#tail_segment_index = old_segment > 0 ? old_segment - 1 : this.#count - 2;
-
-        // Bridge old head -> new head (== old tail slot) with a fresh segment.
-        this.#write_segment_indices(address, old_head, old_tail);
-
-        this.#ba_index.needsUpdate = true;
-    }
-}
-
-TubeX.DEFAULT_RADIAL_SEGMENTS = DEFAULT_RADIAL_SEGMENTS;
+import {
+    BufferAttribute,
+    BufferGeometry,
+    DynamicDrawUsage,
+    InterleavedBuffer,
+    InterleavedBufferAttribute
+} from "three";
+import { assert } from "../../../../core/assert.js";
+import { RowFirstTable } from "../../../../core/collection/table/RowFirstTable.js";
+import { aabb3_array_set } from "../../../../core/geom/3d/aabb/aabb3_array_set.js";
+import { v3_orthonormal_matrix_from_normal } from "../../../../core/geom/vec3/v3_orthonormal_matrix_from_normal.js";
+import { max2 } from "../../../../core/math/max2.js";
+import { min2 } from "../../../../core/math/min2.js";
+import {
+    TUBE_ATTRIBUTE_ADDRESS_ALPHA,
+    TUBE_ATTRIBUTE_ADDRESS_BINORMAL,
+    TUBE_ATTRIBUTE_ADDRESS_COLOR,
+    TUBE_ATTRIBUTE_ADDRESS_NORMAL,
+    TUBE_ATTRIBUTE_ADDRESS_OFF,
+    TUBE_ATTRIBUTE_ADDRESS_POSITION,
+    TUBE_ATTRIBUTE_ADDRESS_THICKNESS,
+    tube_attributes_spec
+} from "./tube_attributes_spec.js";
+
+/**
+ * Default number of radial subdivisions around the tube. Overridable per-tube
+ * via {@link TubeX#setCount}; never hard-coded into the geometry.
+ * @type {number}
+ */
+const DEFAULT_RADIAL_SEGMENTS = 8;
+
+/**
+ * Scratch for the arbitrary default frame written at build time; module-static so
+ * setCount stays allocation-free on the data path.
+ * @type {Float64Array}
+ */
+const m3_default_frame = new Float64Array(9);
+
+/**
+ * Dynamic, non-allocating 3D tube geometry — the volumetric analogue of
+ * {@link RibbonX}.
+ *
+ * A tube is a ring buffer of `count` KNOTS along a centre-line. Each knot owns a
+ * ring of `radial + 1` vertices: the extra vertex duplicates vertex 0 so the UV
+ * seam (u = 0 meeting u = 1) closes cleanly when the texture wraps the tube.
+ * Vertices are extruded in the vertex shader from the knot's stored tangent
+ * frame, so the CPU only ever writes per-knot data (centre, frame, colour, …) —
+ * never per-triangle.
+ *
+ * Like {@link RibbonX} the geometry is a fixed-capacity ring: {@link rotate}
+ * recycles the oldest knot as the new head and rewrites a single segment's worth
+ * of indices, so steady-state updates allocate nothing.
+ */
+export class TubeX {
+
+    /**
+     * @type {BufferGeometry}
+     */
+    #geometry = new BufferGeometry();
+
+    /**
+     * @type {RowFirstTable}
+     */
+    #data = new RowFirstTable(tube_attributes_spec);
+
+    /**
+     * Knot index at the END (oldest) of the tube.
+     * @type {number}
+     */
+    #tail_index = 0;
+
+    /**
+     * Knot index at the START (newest) of the tube.
+     * @type {number}
+     */
+    #head_index = 0;
+
+    /**
+     * Index of the segment (knot-to-knot span of `radial` quads) currently at the
+     * tail; recycled by {@link rotate}.
+     * @type {number}
+     */
+    #tail_segment_index = 0;
+
+    /**
+     * Number of knots.
+     * @type {number}
+     */
+    #count = 0;
+
+    /**
+     * Number of radial subdivisions. Ring vertex count per knot = radial + 1.
+     * @type {number}
+     */
+    #radial = DEFAULT_RADIAL_SEGMENTS;
+
+    // Interleaved buffers + attribute views over #data; created in buildGeometry().
+    #ib_uint8 = null;
+    #ib_float32 = null;
+    #iba_position = null;
+    #iba_normal = null;
+    #iba_binormal = null;
+    #iba_uv = null;
+    #iba_alpha = null;
+    #iba_thickness = null;
+    #iba_color = null;
+    #ba_index = null;
+
+    dispose() {
+        this.#geometry.dispose();
+    }
+
+    /**
+     * @returns {BufferGeometry}
+     */
+    getGeometry() {
+        return this.#geometry;
+    }
+
+    /**
+     * @returns {number} number of knots
+     */
+    getCount() {
+        return this.#count;
+    }
+
+    /**
+     * @returns {number} radial subdivisions
+     */
+    getRadialSegments() {
+        return this.#radial;
+    }
+
+    getHeadIndex() {
+        return this.#head_index;
+    }
+
+    getTailIndex() {
+        return this.#tail_index;
+    }
+
+    /**
+     * Number of vertices in a single knot ring (includes the duplicated seam vertex).
+     * @returns {number}
+     */
+    get #ring_vertex_count() {
+        return this.#radial + 1;
+    }
+
+    buildGeometry() {
+        const a_uint8 = new Uint8Array(this.#data.data);
+        const a_float32 = new Float32Array(this.#data.data);
+
+        const bpr = this.#data.spec.bytesPerRecord;
+
+        this.#ib_uint8 = new InterleavedBuffer(a_uint8, bpr);
+        this.#ib_float32 = new InterleavedBuffer(a_float32, bpr >> 2);
+
+        this.#iba_position = new InterleavedBufferAttribute(this.#ib_float32, 3, 1, false);
+        this.#iba_normal = new InterleavedBufferAttribute(this.#ib_float32, 3, 4, false);
+        this.#iba_binormal = new InterleavedBufferAttribute(this.#ib_float32, 3, 7, false);
+
+        // off (uv.x) and uv_v (uv.y) are contiguous, exposed as a single vec2.
+        this.#iba_uv = new InterleavedBufferAttribute(this.#ib_float32, 2, 10, false);
+        this.#iba_alpha = new InterleavedBufferAttribute(this.#ib_float32, 1, 12, false);
+        this.#iba_thickness = new InterleavedBufferAttribute(this.#ib_float32, 1, 13, false);
+
+        this.#iba_color = new InterleavedBufferAttribute(this.#ib_uint8, 3, 56, false);
+
+        // Uint32 (not Uint16): vertex count = count * (radial + 1) easily exceeds
+        // 65535 for a long tube with high radial resolution. WebGL2 supports it natively.
+        this.#ba_index = new BufferAttribute(new Uint32Array(0), 1, false);
+
+        this.#geometry.setAttribute('position', this.#iba_position);
+        this.#geometry.setAttribute('tn', this.#iba_normal);
+        this.#geometry.setAttribute('tb', this.#iba_binormal);
+        this.#geometry.setAttribute('tubeUv', this.#iba_uv);
+        this.#geometry.setAttribute('alpha', this.#iba_alpha);
+        this.#geometry.setAttribute('thickness', this.#iba_thickness);
+        this.#geometry.setAttribute('color', this.#iba_color);
+
+        this.#geometry.setIndex(this.#ba_index);
+
+        this.#ib_uint8.setUsage(DynamicDrawUsage);
+        this.#ib_float32.setUsage(DynamicDrawUsage);
+        this.#ba_index.setUsage(DynamicDrawUsage);
+    }
+
+    /**
+     * Write the static angular `off` coordinate (uv.x) for every ring vertex. The
+     * value goes 0 → 1 across the `radial + 1` vertices; vertex `radial` lands on
+     * 1.0 so its shader angle is 2π — co-incident with vertex 0's angle 0, closing
+     * the seam without a wrap-around index.
+     */
+    #initialize_off() {
+        const data = this.#data;
+        const count = this.#count;
+        const radial = this.#radial;
+        const v = this.#ring_vertex_count;
+
+        for (let k = 0; k < count; k++) {
+            const base = k * v;
+            for (let j = 0; j <= radial; j++) {
+                data.writeCellValue(base + j, TUBE_ATTRIBUTE_ADDRESS_OFF, j / radial);
+            }
+        }
+    }
+
+    /**
+     * Seed every knot with a valid (arbitrary) orthonormal frame so the geometry is
+     * well-formed from the moment it is built, before any head movement supplies a
+     * real tangent. Without this the frames would be zero-initialised and the
+     * transport's degeneracy fallback would have to cover the fresh-tube case; a
+     * concrete default keeps the invariant "every knot frame is unit + orthonormal"
+     * unconditionally true (read e.g. by getKnotNormal during transport).
+     */
+    #initialize_frame() {
+        v3_orthonormal_matrix_from_normal(m3_default_frame, 0, 0, 1, 0);
+
+        const nx = m3_default_frame[0], ny = m3_default_frame[1], nz = m3_default_frame[2];
+        const bx = m3_default_frame[3], by = m3_default_frame[4], bz = m3_default_frame[5];
+
+        const count = this.#count;
+
+        for (let k = 0; k < count; k++) {
+            this.setKnotFrame(k, nx, ny, nz, bx, by, bz);
+        }
+    }
+
+    /**
+     * Write the `radial` quads (2 triangles each) bridging the ring of knot `lo`
+     * to the ring of knot `hi`, starting at `address` in the index array.
+     * Winding matches the engine's static tube mesher (make_ring_faces).
+     * @param {number} address index-array offset (in index entries)
+     * @param {number} lo knot index whose ring is the "left" edge
+     * @param {number} hi knot index whose ring is the "right" edge
+     */
+    #write_segment_indices(address, lo, hi) {
+        const indices = this.#ba_index.array;
+        const radial = this.#radial;
+        const v = this.#ring_vertex_count;
+
+        const lo_base = lo * v;
+        const hi_base = hi * v;
+
+        for (let r = 0; r < radial; r++) {
+            const a = lo_base + r;
+            const b = hi_base + r;
+            const c = hi_base + r + 1;
+            const d = lo_base + r + 1;
+
+            const ci = address + r * 6;
+
+            indices[ci] = a;
+            indices[ci + 1] = b;
+            indices[ci + 2] = d;
+
+            indices[ci + 3] = b;
+            indices[ci + 4] = c;
+            indices[ci + 5] = d;
+        }
+    }
+
+    /**
+     * Build the index buffer as a linear strip of `count - 1` segments.
+     */
+    #initialize_index() {
+        const segment_count = this.#count - 1;
+        const indices_per_segment = this.#radial * 6;
+
+        for (let s = 0; s < segment_count; s++) {
+            this.#write_segment_indices(s * indices_per_segment, s, s + 1);
+        }
+    }
+
+    /**
+     * @param {number[]|Float32Array} result
+     * @param {number} knot_index
+     */
+    getKnotPosition(result, knot_index) {
+        const row = knot_index * this.#ring_vertex_count;
+        const data = this.#data;
+
+        result[0] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_POSITION);
+        result[1] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_POSITION + 1);
+        result[2] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_POSITION + 2);
+    }
+
+    /**
+     * Read the stored ring normal of a knot. Used by the head to parallel-transport
+     * its frame from the previous knot.
+     * @param {number[]|Float32Array} result
+     * @param {number} knot_index
+     */
+    getKnotNormal(result, knot_index) {
+        const row = knot_index * this.#ring_vertex_count;
+        const data = this.#data;
+
+        result[0] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_NORMAL);
+        result[1] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_NORMAL + 1);
+        result[2] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_NORMAL + 2);
+    }
+
+    /**
+     * Read the stored ring binormal of a knot.
+     * @param {number[]|Float32Array} result
+     * @param {number} knot_index
+     */
+    getKnotBinormal(result, knot_index) {
+        const row = knot_index * this.#ring_vertex_count;
+        const data = this.#data;
+
+        result[0] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_BINORMAL);
+        result[1] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_BINORMAL + 1);
+        result[2] = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_BINORMAL + 2);
+    }
+
+    /**
+     * Write a vec3 attribute to all ring vertices of a knot.
+     * @param {number} knot_index
+     * @param {number} attribute_index
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    setKnotAttribute_Vector3(knot_index, attribute_index, x, y, z) {
+        const data = this.#data;
+        const v = this.#ring_vertex_count;
+        const base = knot_index * v;
+
+        for (let j = 0; j < v; j++) {
+            const row = base + j;
+            data.writeCellValue(row, attribute_index, x);
+            data.writeCellValue(row, attribute_index + 1, y);
+            data.writeCellValue(row, attribute_index + 2, z);
+        }
+    }
+
+    /**
+     * Write a scalar attribute to all ring vertices of a knot.
+     * @param {number} knot_index
+     * @param {number} attribute_index
+     * @param {number} value
+     */
+    setKnotAttribute_Scalar(knot_index, attribute_index, value) {
+        const data = this.#data;
+        const v = this.#ring_vertex_count;
+        const base = knot_index * v;
+
+        for (let j = 0; j < v; j++) {
+            data.writeCellValue(base + j, attribute_index, value);
+        }
+    }
+
+    /**
+     * Add `delta` to a scalar attribute on every ring vertex of a knot.
+     * @param {number} knot_index
+     * @param {number} attribute_index
+     * @param {number} delta
+     * @returns {number} incremented value
+     */
+    incrementKnotAttribute_Scalar(knot_index, attribute_index, delta) {
+        const data = this.#data;
+        const v = this.#ring_vertex_count;
+        const base = knot_index * v;
+
+        const value = data.readCellValue(base, attribute_index) + delta;
+
+        for (let j = 0; j < v; j++) {
+            data.writeCellValue(base + j, attribute_index, value);
+        }
+
+        return value;
+    }
+
+    /**
+     * @param {number} knot_index
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    setKnotPosition(knot_index, x, y, z) {
+        assert.isNonNegativeInteger(knot_index, 'knot_index');
+
+        this.setKnotAttribute_Vector3(knot_index, TUBE_ATTRIBUTE_ADDRESS_POSITION, x, y, z);
+
+        this.#ib_float32.needsUpdate = true;
+    }
+
+    /**
+     * Set the orienting tangent frame of a knot. `nx,ny,nz` and `bx,by,bz` must be
+     * unit vectors, mutually orthogonal and perpendicular to the local tangent.
+     * @param {number} knot_index
+     * @param {number} nx
+     * @param {number} ny
+     * @param {number} nz
+     * @param {number} bx
+     * @param {number} by
+     * @param {number} bz
+     */
+    setKnotFrame(knot_index, nx, ny, nz, bx, by, bz) {
+        this.setKnotAttribute_Vector3(knot_index, TUBE_ATTRIBUTE_ADDRESS_NORMAL, nx, ny, nz);
+        this.setKnotAttribute_Vector3(knot_index, TUBE_ATTRIBUTE_ADDRESS_BINORMAL, bx, by, bz);
+
+        this.#ib_float32.needsUpdate = true;
+    }
+
+    /**
+     * @param {number} knot_index
+     * @param {number} r 0..255
+     * @param {number} g 0..255
+     * @param {number} b 0..255
+     */
+    setKnotColor(knot_index, r, g, b) {
+        assert.isNonNegativeInteger(knot_index, 'knot_index');
+
+        this.setKnotAttribute_Vector3(knot_index, TUBE_ATTRIBUTE_ADDRESS_COLOR, r, g, b);
+
+        this.#ib_uint8.needsUpdate = true;
+    }
+
+    /**
+     * @param {number} knot_index
+     * @param {number} value
+     */
+    setKnotAlpha(knot_index, value) {
+        this.setKnotAttribute_Scalar(knot_index, TUBE_ATTRIBUTE_ADDRESS_ALPHA, value);
+
+        this.#ib_float32.needsUpdate = true;
+    }
+
+    /**
+     * @param {number} knot_index
+     * @param {number} value tube diameter
+     */
+    setKnotThickness(knot_index, value) {
+        this.setKnotAttribute_Scalar(knot_index, TUBE_ATTRIBUTE_ADDRESS_THICKNESS, value);
+
+        this.#ib_float32.needsUpdate = true;
+    }
+
+    /**
+     * @param {number} count number of knots (>= 2)
+     * @param {number} [radial] radial subdivisions (>= 3)
+     */
+    setCount(count, radial = DEFAULT_RADIAL_SEGMENTS) {
+        assert.greaterThanOrEqual(count, 2, 'a tube needs at least 2 knots (one segment)');
+        assert.isNonNegativeInteger(count, 'count');
+        assert.greaterThanOrEqual(radial, 3, 'a tube ring needs at least 3 radial segments');
+        assert.isNonNegativeInteger(radial, 'radial');
+
+        this.#geometry.dispose();
+
+        this.#radial = radial;
+
+        const v = radial + 1;
+        const vertex_count = count * v;
+
+        if (this.#data.length > vertex_count) {
+            this.#data.removeRows(vertex_count, this.#data.length - vertex_count);
+        }
+
+        this.#data.setCapacity(vertex_count);
+        this.#data.length = vertex_count;
+
+        const a_uint8 = new Uint8Array(this.#data.data);
+        const a_float32 = new Float32Array(this.#data.data);
+
+        const segment_count = count - 1;
+        const triangle_count = segment_count * radial * 2;
+        const index_array_size = triangle_count * 3;
+        const index_array = new Uint32Array(index_array_size);
+
+        this.#ba_index.array = index_array;
+        this.#ba_index.count = index_array_size;
+
+        this.#ib_uint8.array = a_uint8;
+        this.#ib_float32.array = a_float32;
+
+        this.#ib_uint8.count = vertex_count;
+        this.#ib_float32.count = vertex_count;
+
+        this.#head_index = 0;
+        this.#tail_index = count - 1;
+        this.#tail_segment_index = segment_count - 1;
+
+        this.#count = count;
+
+        this.#initialize_off();
+        this.#initialize_frame();
+        this.#initialize_index();
+    }
+
+    /**
+     * NOTE: takes tube thickness into account.
+     * @param {AABB3|ArrayLike<number>} result
+     */
+    computeBoundingBox(result) {
+        const count = this.#count;
+        const v = this.#ring_vertex_count;
+        const data = this.#data;
+
+        let _x0 = Infinity, _y0 = Infinity, _z0 = Infinity;
+        let _x1 = -Infinity, _y1 = -Infinity, _z1 = -Infinity;
+
+        for (let k = 0; k < count; k++) {
+            const row = k * v;
+
+            const half_thickness = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_THICKNESS) * 0.5;
+
+            const x = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_POSITION);
+            const y = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_POSITION + 1);
+            const z = data.readCellValue(row, TUBE_ATTRIBUTE_ADDRESS_POSITION + 2);
+
+            _x0 = min2(_x0, x - half_thickness);
+            _y0 = min2(_y0, y - half_thickness);
+            _z0 = min2(_z0, z - half_thickness);
+            _x1 = max2(_x1, x + half_thickness);
+            _y1 = max2(_y1, y + half_thickness);
+            _z1 = max2(_z1, z + half_thickness);
+        }
+
+        aabb3_array_set(result, 0, _x0, _y0, _z0, _x1, _y1, _z1);
+    }
+
+    /**
+     * Recycle the oldest knot as the new head, in O(radial). Mirrors
+     * {@link RibbonX#rotate}: the head/tail pointers decrement together (preserving
+     * `head === (tail + 1) mod count`), and the single tail segment's indices are
+     * rewritten to bridge the previous head's ring to the recycled (new head) ring.
+     */
+    rotate() {
+        const old_tail = this.#tail_index;
+        const old_head = this.#head_index;
+
+        const max_index = this.#count - 1;
+
+        // The recycled slot (old tail) becomes the new head: head and tail step
+        // back in lockstep so head stays exactly one slot ahead of tail.
+        this.#tail_index = old_tail <= 0 ? max_index : old_tail - 1;
+        this.#head_index = old_head <= 0 ? max_index : old_head - 1;
+
+        const old_segment = this.#tail_segment_index;
+        const address = old_segment * this.#radial * 6;
+
+        this.#tail_segment_index = old_segment > 0 ? old_segment - 1 : this.#count - 2;
+
+        // Bridge old head -> new head (== old tail slot) with a fresh segment. The new head (old_tail slot)
+        // is the more head-ward knot, so it takes the `lo` position to match #initialize_index's winding
+        // convention (lo = more head-ward); swapping the two would invert this segment's triangle winding.
+        this.#write_segment_indices(address, old_tail, old_head);
+
+        this.#ba_index.needsUpdate = true;
+    }
+}
+
+TubeX.DEFAULT_RADIAL_SEGMENTS = DEFAULT_RADIAL_SEGMENTS;