@woosh/meep-engine 3.28.0 → 3.29.0

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

@@ -219,14 +219,30 @@ export class OffsetAllocator {
      * The one node whose neighbour-next is {@link NODE_UNUSED}, so the one describing the arena's
      * end. {@link OffsetAllocator#grow} needs it in O(1) and has nothing to walk the chain from.
      *
-     * Maintained by `#insertNodeIntoBin`, which is the only place a node's end offset is ever set:
-     * `allocate` only shrinks the node it hands out, and `free_node` re-inserts every merged region
-     * through that same method.
+     * Maintained by `#insertNodeIntoBin`, which is where a node's end offset is set: `allocate`
+     * only shrinks the node it hands out, and `free_node` re-inserts every merged region through
+     * that same method. The one other writer of an end offset is {@link slide_down}, which moves a
+     * free node past the used one it swaps with and sets this itself when that puts the free
+     * node at the end.
      * uint32
      * @type {number}
      */
     #tail_node = NODE_UNUSED;
 
+    /**
+     * The one node whose neighbour-prev is {@link NODE_UNUSED}, so the one describing the arena's
+     * start. {@link first_used_node} needs it in O(1).
+     *
+     * Kept from the chain's links rather than from the offset a node is inserted at: a node is
+     * inserted with no links and linked by its caller, and a zero-sized node at offset 0 would
+     * otherwise be mislabelled. Set by `reset`, by `free_node` when the merged node has no
+     * predecessor, by `grow` when it stretches a free run that is the whole arena, and by
+     * {@link slide_down} when the used node moves to the front.
+     * uint32
+     * @type {number}
+     */
+    #head_node = NODE_UNUSED;
+
     /**
      *
      * @param {number} size amount of contiguous elements managed by this allocator (typically bytes)
@@ -283,24 +299,49 @@ export class OffsetAllocator {
     }
 
     /**
+     * Whether {@link allocate}`(size)` would land, without allocating: exactly its refusal test —
+     * a node left to describe a remainder with, and a filed run of a bin at or above the one the
+     * request is looked up from. Node exhaustion is the shortfall no arena size answers, and a
+     * probe that ignored it would send a caller to grow for nothing.
      *
      * @param {number} size
-     * @returns {Allocation}
+     * @returns {boolean}
      */
-    allocate(size) {
+    can_allocate(size) {
         assert.isNonNegativeInteger(size, 'size');
 
+        return this.#allocation_bin(size) !== ALLOCATOR_NO_SPACE;
+    }
+
+    /**
+     * The bin {@link allocate}`(size)` takes from, or {@link ALLOCATOR_NO_SPACE} when it is refused.
+     *
+     * @param {number} size
+     * @returns {number}
+     */
+    #allocation_bin(size) {
         // Out of allocations?
         if (this.freeOffset === 0) {
-            return Allocation.from(ALLOCATOR_NO_SPACE, ALLOCATOR_NO_SPACE);
+            return 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));
+        return this.#find_bin_at_least(uintToFloatRoundUp(size));
+    }
+
+    /**
+     *
+     * @param {number} size
+     * @returns {Allocation}
+     */
+    allocate(size) {
+        assert.isNonNegativeInteger(size, 'size');
+
+        const bin_index = this.#allocation_bin(size);
 
         if (bin_index === ALLOCATOR_NO_SPACE) {
-            // out of space
+            // out of space, or out of nodes
             return Allocation.from(ALLOCATOR_NO_SPACE, ALLOCATOR_NO_SPACE);
         }
 
@@ -455,7 +496,162 @@ export class OffsetAllocator {
         if (neighborPrev !== NODE_UNUSED) {
             nodes.writeCellValue(combinedNodeIndex, NODE_FIELD_NEIGHBOR_PREV, neighborPrev);
             nodes.writeCellValue(neighborPrev, NODE_FIELD_NEIGHBOR_NEXT, combinedNodeIndex);
+        } else {
+            // nothing before it: the merged region starts the arena
+            this.#head_node = combinedNodeIndex;
+        }
+    }
+
+    /**
+     * The used node that starts the arena, or {@link ALLOCATOR_NO_SPACE} when nothing is used.
+     *
+     * Free nodes never adjoin (`free_node` merges both sides), so at most one free node sits
+     * before the first used one, and this is a walk of at most one link.
+     *
+     * @returns {number} node index
+     */
+    first_used_node() {
+        const head = this.#head_node;
+
+        if (head === NODE_UNUSED) {
+            return ALLOCATOR_NO_SPACE;
+        }
+
+        const nodes = this.nodes;
+
+        if ((nodes.readCellValue(head, NODE_FIELD_FLAGS) & NODE_FLAGS_USED) !== 0) {
+            return head;
+        }
+
+        const next = nodes.readCellValue(head, NODE_FIELD_NEIGHBOR_NEXT);
+
+        return next === NODE_UNUSED ? ALLOCATOR_NO_SPACE : next;
+    }
+
+    /**
+     * The used node after `node_index` in address order, or {@link ALLOCATOR_NO_SPACE} at the
+     * arena's end. At most one free node sits between two used ones, so a walk of at most two
+     * links.
+     *
+     * @param {number} node_index a used node
+     * @returns {number} node index
+     */
+    next_used_node(node_index) {
+        assert.isNonNegativeInteger(node_index, 'node_index');
+
+        const nodes = this.nodes;
+
+        assert.notEqual(nodes.readCellValue(node_index, NODE_FIELD_FLAGS) & NODE_FLAGS_USED, 0, 'node is not in use');
+
+        let next = nodes.readCellValue(node_index, NODE_FIELD_NEIGHBOR_NEXT);
+
+        if (next === NODE_UNUSED) {
+            return ALLOCATOR_NO_SPACE;
+        }
+
+        if ((nodes.readCellValue(next, NODE_FIELD_FLAGS) & NODE_FLAGS_USED) === 0) {
+            next = nodes.readCellValue(next, NODE_FIELD_NEIGHBOR_NEXT);
+
+            if (next === NODE_UNUSED) {
+                return ALLOCATOR_NO_SPACE;
+            }
+        }
+
+        return next;
+    }
+
+    /**
+     * Move a used range down over the free range immediately before it, in O(1).
+     *
+     * The two nodes swap places: the used node's offset drops by the free node's size, the free
+     * node's offset rises by the used node's size. The free node's size — and so its bin — is
+     * unchanged, so its bin-list membership is untouched. If the free node then adjoins a free
+     * successor the two are merged, which returns one node to the freelist; nothing here ever
+     * takes a node. The used node keeps its index, so an {@link Allocation} a caller holds for it
+     * is still its handle — the caller updates the allocation's `offset` by the returned delta,
+     * as this method does not know the object.
+     *
+     * A sliding compactor walks the used nodes in address order calling this on each: every hole
+     * passed gathers into one free node just behind the walk, and the walk ends with all free
+     * space in one run at the tail (COMPACTION_PLAN_2026_09_16 §4.2–4.3).
+     *
+     * @param {number} node_index a used node
+     * @returns {number} how far the range moved: the free predecessor's size, or 0 when the
+     *          predecessor is used or there is none
+     */
+    slide_down(node_index) {
+        assert.isNonNegativeInteger(node_index, 'node_index');
+
+        const nodes = this.nodes;
+
+        assert.notEqual(nodes.readCellValue(node_index, NODE_FIELD_FLAGS) & NODE_FLAGS_USED, 0, 'node is not in use');
+
+        const free_node = nodes.readCellValue(node_index, NODE_FIELD_NEIGHBOR_PREV);
+
+        if (
+            free_node === NODE_UNUSED
+            || (nodes.readCellValue(free_node, NODE_FIELD_FLAGS) & NODE_FLAGS_USED) !== 0
+        ) {
+            return 0;
+        }
+
+        const free_size = nodes.readCellValue(free_node, NODE_FIELD_DATA_SIZE);
+        const free_offset = nodes.readCellValue(free_node, NODE_FIELD_DATA_OFFSET);
+        const used_size = nodes.readCellValue(node_index, NODE_FIELD_DATA_SIZE);
+
+        const before = nodes.readCellValue(free_node, NODE_FIELD_NEIGHBOR_PREV);
+        const after = nodes.readCellValue(node_index, NODE_FIELD_NEIGHBOR_NEXT);
+
+        // the swap: [before] [used] [free] [after]
+        nodes.writeCellValue(node_index, NODE_FIELD_DATA_OFFSET, free_offset);
+        nodes.writeCellValue(free_node, NODE_FIELD_DATA_OFFSET, free_offset + used_size);
+
+        nodes.writeCellValue(node_index, NODE_FIELD_NEIGHBOR_PREV, before);
+        nodes.writeCellValue(node_index, NODE_FIELD_NEIGHBOR_NEXT, free_node);
+        nodes.writeCellValue(free_node, NODE_FIELD_NEIGHBOR_PREV, node_index);
+        nodes.writeCellValue(free_node, NODE_FIELD_NEIGHBOR_NEXT, after);
+
+        if (before !== NODE_UNUSED) {
+            nodes.writeCellValue(before, NODE_FIELD_NEIGHBOR_NEXT, node_index);
+        } else {
+            this.#head_node = node_index;
+        }
+
+        if (after === NODE_UNUSED) {
+            // the used node was the tail; the free node ends the arena now
+            this.#tail_node = free_node;
+
+            return free_size;
+        }
+
+        nodes.writeCellValue(after, NODE_FIELD_NEIGHBOR_PREV, free_node);
+
+        if ((nodes.readCellValue(after, NODE_FIELD_FLAGS) & NODE_FLAGS_USED) !== 0) {
+            return free_size;
+        }
+
+        // Two free nodes adjoin: merge them. Both leave their bins before either changes size —
+        // `#removeNodeFromBin` finds a node's bin from its current size — and the combined node
+        // is inserted last, so the freelist pops what the removes pushed and never underflows.
+        const after_size = nodes.readCellValue(after, NODE_FIELD_DATA_SIZE);
+        const after_next = nodes.readCellValue(after, NODE_FIELD_NEIGHBOR_NEXT);
+
+        this.#removeNodeFromBin(free_node);
+        this.#removeNodeFromBin(after);
+
+        const merged = this.#insertNodeIntoBin(free_size + after_size, free_offset + used_size);
+
+        nodes.writeCellValue(merged, NODE_FIELD_NEIGHBOR_PREV, node_index);
+        nodes.writeCellValue(node_index, NODE_FIELD_NEIGHBOR_NEXT, merged);
+
+        nodes.writeCellValue(merged, NODE_FIELD_NEIGHBOR_NEXT, after_next);
+
+        if (after_next !== NODE_UNUSED) {
+            nodes.writeCellValue(after_next, NODE_FIELD_NEIGHBOR_PREV, merged);
         }
+        // else: the merged node ends the arena, and `#insertNodeIntoBin` has made it the tail
+
+        return free_size;
     }
 
     /**
@@ -589,6 +785,9 @@ export class OffsetAllocator {
             if (tail_neighbour_prev !== NODE_UNUSED) {
                 nodes.writeCellValue(grown_node, NODE_FIELD_NEIGHBOR_PREV, tail_neighbour_prev);
                 nodes.writeCellValue(tail_neighbour_prev, NODE_FIELD_NEIGHBOR_NEXT, grown_node);
+            } else {
+                // the whole arena was one free run; the stretched one starts it
+                this.#head_node = grown_node;
             }
 
             return;
@@ -767,7 +966,7 @@ export class OffsetAllocator {
 
         // Start state: Whole storage as one big node
         // Algorithm will split remainders and push them back as smaller nodes
-        this.#insertNodeIntoBin(this.size, 0);
+        this.#head_node = this.#insertNodeIntoBin(this.size, 0);
 
     }
 

package/src/core/binary/compression/compress_bytes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Compress pieces of one stream using the platform's compression API.
+ *
+ * The mirror of {@link decompress_bytes}, and written the same way for the same reason: the input
+ * goes through a pipe rather than a sequence of awaited writes, so that a failure on either side
+ * settles the other instead of deadlocking on backpressure. The input views must remain unchanged
+ * until the returned promise settles.
+ *
+ * There is no compression level here because the platform API does not expose one — `deflate-raw`
+ * is whatever the host's zlib defaults to. A caller that needs a level needs a different encoder.
+ *
+ * @param {Uint8Array[]} chunks
+ * @param {"deflate"|"deflate-raw"|"gzip"} [format] `deflate` writes the zlib header and checksum
+ * @returns {Promise<Uint8Array>}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function compress_bytes(chunks: Uint8Array[], format?: "deflate" | "deflate-raw" | "gzip"): Promise<Uint8Array>;
+//# sourceMappingURL=compress_bytes.d.ts.map

package/src/core/binary/compression/compress_bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compress_bytes.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/compression/compress_bytes.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,uCAPW,UAAU,EAAE,WACZ,SAAS,GAAC,aAAa,GAAC,MAAM,GAC5B,QAAQ,UAAU,CAAC,CAqB/B"}

package/src/core/binary/compression/compress_bytes.js

@@ -0,0 +1,35 @@
+/**
+ * Compress pieces of one stream using the platform's compression API.
+ *
+ * The mirror of {@link decompress_bytes}, and written the same way for the same reason: the input
+ * goes through a pipe rather than a sequence of awaited writes, so that a failure on either side
+ * settles the other instead of deadlocking on backpressure. The input views must remain unchanged
+ * until the returned promise settles.
+ *
+ * There is no compression level here because the platform API does not expose one — `deflate-raw`
+ * is whatever the host's zlib defaults to. A caller that needs a level needs a different encoder.
+ *
+ * @param {Uint8Array[]} chunks
+ * @param {"deflate"|"deflate-raw"|"gzip"} [format] `deflate` writes the zlib header and checksum
+ * @returns {Promise<Uint8Array>}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export async function compress_bytes(chunks, format = "deflate") {
+    let index = 0;
+
+    const input = new ReadableStream({
+        pull(controller) {
+            if (index === chunks.length) {
+                controller.close();
+            } else {
+                controller.enqueue(chunks[index++]);
+            }
+        }
+    });
+
+    const output = input.pipeThrough(new CompressionStream(format));
+
+    return new Uint8Array(await new Response(output).arrayBuffer());
+}

package/src/core/binary/compression/decompress_bytes_into.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Decompress pieces of one stream straight into a buffer the caller already owns, writing at most
+ * `limit` bytes and refusing the stream the moment it would write more.
+ *
+ * {@link decompress_bytes} collects the whole output first and hands back a fresh array, which is
+ * the wrong shape twice over when the caller knows the decoded length in advance: it costs a second
+ * copy of every byte, and — the reason this exists — it gives a hostile stream the whole decode to
+ * expand into before anybody can notice it disagrees with the length that was declared. Deflate
+ * reaches 1032:1, so "check the size afterwards" is an attacker-chosen allocation.
+ *
+ * Here the bound is applied per chunk as the chunks arrive, so a stream that lies stops at the
+ * first chunk past the caller's buffer and nothing beyond it is ever held.
+ *
+ * Output shorter than `limit` is *not* an error here — the caller knows whether its length was a
+ * cap or an exact expectation, and gets the count back to check. The input views must remain
+ * unchanged until the returned promise settles.
+ *
+ * @param {Uint8Array} destination
+ * @param {number} offset where the decompressed bytes start
+ * @param {number} limit most bytes to write; `destination` must hold that many at `offset`
+ * @param {Uint8Array[]} chunks
+ * @param {"deflate"|"deflate-raw"|"gzip"} [format] `deflate` expects the zlib header and checksum
+ * @returns {Promise<number>} bytes written
+ * @throws {Error} when the stream is malformed, or produces more than `limit` bytes
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function decompress_bytes_into(destination: Uint8Array, offset: number, limit: number, chunks: Uint8Array[], format?: "deflate" | "deflate-raw" | "gzip"): Promise<number>;
+//# sourceMappingURL=decompress_bytes_into.d.ts.map

package/src/core/binary/compression/decompress_bytes_into.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decompress_bytes_into.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/compression/decompress_bytes_into.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,mDAXW,UAAU,UACV,MAAM,SACN,MAAM,UACN,UAAU,EAAE,WACZ,SAAS,GAAC,aAAa,GAAC,MAAM,GAC5B,QAAQ,MAAM,CAAC,CA8D3B"}

package/src/core/binary/compression/decompress_bytes_into.js

@@ -0,0 +1,87 @@
+import { assert } from "../../assert.js";
+
+/**
+ * Decompress pieces of one stream straight into a buffer the caller already owns, writing at most
+ * `limit` bytes and refusing the stream the moment it would write more.
+ *
+ * {@link decompress_bytes} collects the whole output first and hands back a fresh array, which is
+ * the wrong shape twice over when the caller knows the decoded length in advance: it costs a second
+ * copy of every byte, and — the reason this exists — it gives a hostile stream the whole decode to
+ * expand into before anybody can notice it disagrees with the length that was declared. Deflate
+ * reaches 1032:1, so "check the size afterwards" is an attacker-chosen allocation.
+ *
+ * Here the bound is applied per chunk as the chunks arrive, so a stream that lies stops at the
+ * first chunk past the caller's buffer and nothing beyond it is ever held.
+ *
+ * Output shorter than `limit` is *not* an error here — the caller knows whether its length was a
+ * cap or an exact expectation, and gets the count back to check. The input views must remain
+ * unchanged until the returned promise settles.
+ *
+ * @param {Uint8Array} destination
+ * @param {number} offset where the decompressed bytes start
+ * @param {number} limit most bytes to write; `destination` must hold that many at `offset`
+ * @param {Uint8Array[]} chunks
+ * @param {"deflate"|"deflate-raw"|"gzip"} [format] `deflate` expects the zlib header and checksum
+ * @returns {Promise<number>} bytes written
+ * @throws {Error} when the stream is malformed, or produces more than `limit` bytes
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export async function decompress_bytes_into(destination, offset, limit, chunks, format = "deflate") {
+    assert.isNonNegativeInteger(offset, 'offset');
+    assert.isNonNegativeInteger(limit, 'limit');
+
+    // Ahead of the stream rather than at the first write past the end: the caller computed both of
+    // these from a length it read somewhere, and "your buffer is too small" is worth saying before
+    // a decode runs rather than as a `RangeError` from the middle of one.
+    assert.lessThanOrEqual(
+        offset + limit, destination.length,
+        'the destination must hold `limit` bytes at `offset`'
+    );
+
+    let index = 0;
+
+    const input = new ReadableStream({
+        pull(controller) {
+            if (index === chunks.length) {
+                controller.close();
+            } else {
+                controller.enqueue(chunks[index++]);
+            }
+        }
+    });
+
+    const reader = input.pipeThrough(new DecompressionStream(format)).getReader();
+
+    let written = 0;
+
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+
+            if (done) {
+                break;
+            }
+
+            if (written + value.length > limit) {
+                throw new Error(
+                    `the stream decompresses to more than the ${limit} bytes it was given`
+                );
+            }
+
+            destination.set(value, offset + written);
+
+            written += value.length;
+        }
+    } catch (e) {
+        // The reader holds a lock on the stream and the pipe behind it is still pulling; cancelling
+        // is what lets the source see that nobody is reading any more. Its own rejection is not
+        // news — we are already throwing the reason.
+        await reader.cancel(e).catch(() => undefined);
+
+        throw e;
+    }
+
+    return written;
+}

package/src/core/binary/compression/deflate_decompress_bound.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The most bytes a raw DEFLATE stream of `size` bytes can decode to.
+ *
+ * The counterpart of {@link lz4_decompress_bound}, and it exists for the same reason: a caller that
+ * allocates against a *claimed* decoded size — a container header, a page frame — is taking an
+ * untrusted number, and a claim above this bound is one no stream of that length could satisfy.
+ * Checking it before allocating is what keeps a corrupt length field from becoming a multi-gigabyte
+ * allocation. It is a bound on a length field, not a substitute for bounding the decode itself:
+ * {@link decompress_bytes_into} is what stops a stream that lies in the other direction.
+ *
+ * The densest thing RFC 1951 can code is a run of maximal matches under a dynamic Huffman table
+ * chosen to make them cheap. A match copies at most 258 bytes and costs at least two bits: one for
+ * its length code — the literal/length alphabet always carries end-of-block as well, so two symbols,
+ * so one bit each — and one for its distance code, which RFC 1951 §3.2.7 gives a whole bit even
+ * when the alphabet has a single symbol in it. Four matches per input byte at 258 bytes apiece is
+ * **1032:1**, which is zlib's documented maximum and what is returned here. The block header only
+ * takes bits away from that budget, so no slack is added at the short end, and a zero-length stream
+ * decodes to nothing because it is not a stream at all.
+ *
+ * @param {number} size bytes of stream
+ * @returns {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function deflate_decompress_bound(size: number): number;
+//# sourceMappingURL=deflate_decompress_bound.d.ts.map

package/src/core/binary/compression/deflate_decompress_bound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deflate_decompress_bound.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/compression/deflate_decompress_bound.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,+CANW,MAAM,GACJ,MAAM,CASlB"}

package/src/core/binary/compression/deflate_decompress_bound.js

@@ -0,0 +1,32 @@
+import { assert } from "../../assert.js";
+
+/**
+ * The most bytes a raw DEFLATE stream of `size` bytes can decode to.
+ *
+ * The counterpart of {@link lz4_decompress_bound}, and it exists for the same reason: a caller that
+ * allocates against a *claimed* decoded size — a container header, a page frame — is taking an
+ * untrusted number, and a claim above this bound is one no stream of that length could satisfy.
+ * Checking it before allocating is what keeps a corrupt length field from becoming a multi-gigabyte
+ * allocation. It is a bound on a length field, not a substitute for bounding the decode itself:
+ * {@link decompress_bytes_into} is what stops a stream that lies in the other direction.
+ *
+ * The densest thing RFC 1951 can code is a run of maximal matches under a dynamic Huffman table
+ * chosen to make them cheap. A match copies at most 258 bytes and costs at least two bits: one for
+ * its length code — the literal/length alphabet always carries end-of-block as well, so two symbols,
+ * so one bit each — and one for its distance code, which RFC 1951 §3.2.7 gives a whole bit even
+ * when the alphabet has a single symbol in it. Four matches per input byte at 258 bytes apiece is
+ * **1032:1**, which is zlib's documented maximum and what is returned here. The block header only
+ * takes bits away from that budget, so no slack is added at the short end, and a zero-length stream
+ * decodes to nothing because it is not a stream at all.
+ *
+ * @param {number} size bytes of stream
+ * @returns {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function deflate_decompress_bound(size) {
+    assert.isNonNegativeInteger(size, 'size');
+
+    return size * 1032;
+}

package/src/core/geom/3d/quadric/quadric_attribute_add.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Sum two attribute quadrics, elementwise.
+ *
+ * Elementwise is the whole of it, and that is deliberate: the reduction
+ * ({@link quadric_attribute_reduce}) divides by the accumulated weight, which is not a linear
+ * operation, so doing it here would make `add` depend on the order the quadrics arrived in. It is
+ * left to solve time, where the weight is final, and this stays associative — which is what lets a
+ * survivor absorb its victims one at a time and still hold what it would have held had they all
+ * been folded in at once.
+ *
+ * @param {number[]|Float32Array|Float64Array} out `quadric_attribute_size(components)` elements from
+ *     `out_offset`; may alias either input
+ * @param {number} out_offset
+ * @param {ArrayLike<number>} a
+ * @param {number} a_offset
+ * @param {ArrayLike<number>} b
+ * @param {number} b_offset
+ * @param {number} components number of scalar channels
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function quadric_attribute_add(out: number[] | Float32Array | Float64Array, out_offset: number, a: ArrayLike<number>, a_offset: number, b: ArrayLike<number>, b_offset: number, components: number): void;
+//# sourceMappingURL=quadric_attribute_add.d.ts.map

package/src/core/geom/3d/quadric/quadric_attribute_add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quadric_attribute_add.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quadric/quadric_attribute_add.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,2CAZW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAElC,MAAM,KACN,UAAU,MAAM,CAAC,YACjB,MAAM,KACN,UAAU,MAAM,CAAC,YACjB,MAAM,cACN,MAAM,QAWhB"}

package/src/core/geom/3d/quadric/quadric_attribute_add.js

@@ -0,0 +1,31 @@
+import { QUADRIC3_SIZE } from "./QUADRIC3_SIZE.js";
+
+/**
+ * Sum two attribute quadrics, elementwise.
+ *
+ * Elementwise is the whole of it, and that is deliberate: the reduction
+ * ({@link quadric_attribute_reduce}) divides by the accumulated weight, which is not a linear
+ * operation, so doing it here would make `add` depend on the order the quadrics arrived in. It is
+ * left to solve time, where the weight is final, and this stays associative — which is what lets a
+ * survivor absorb its victims one at a time and still hold what it would have held had they all
+ * been folded in at once.
+ *
+ * @param {number[]|Float32Array|Float64Array} out `quadric_attribute_size(components)` elements from
+ *     `out_offset`; may alias either input
+ * @param {number} out_offset
+ * @param {ArrayLike<number>} a
+ * @param {number} a_offset
+ * @param {ArrayLike<number>} b
+ * @param {number} b_offset
+ * @param {number} components number of scalar channels
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function quadric_attribute_add(out, out_offset, a, a_offset, b, b_offset, components) {
+    const size = QUADRIC3_SIZE + components * 4;
+
+    for (let i = 0; i < size; i++) {
+        out[out_offset + i] = a[a_offset + i] + b[b_offset + i];
+    }
+}

package/src/core/geom/3d/quadric/quadric_attribute_reduce.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The 3-D quadric an attribute quadric becomes once its attributes have been solved out of it.
+ *
+ * ## Why there is one at all
+ *
+ * The accumulated form is a quadratic in `3 + m` unknowns — a position and a value per channel. But
+ * the channels appear in it only as `-2 s_i (G_i . v + D_i) + s_i^2 W`, which is minimised exactly,
+ * with no search, at `s_i = (G_i . v + D_i) / W`. Substituting that back removes them, and what is
+ * left is a quadric in the position alone:
+ *
+ * ```
+ * A = P - SUM_i (G_i G_i^T) / W
+ * b = q - SUM_i (D_i G_i)   / W
+ * c = r - SUM_i (D_i^2)     / W
+ * ```
+ *
+ * That is the whole reason to hold Hoppe's form rather than the `(3 + m)`-dimensional lift: placing
+ * the vertex stays a 3x3 solve however many channels the mesh carries, and the channels' influence
+ * on *where it goes* is not lost — it is in `A` and `b`.
+ *
+ * The output is {@link Quadric3}-shaped, so `quadric3_optimize` places the vertex and
+ * `quadric3_evaluate` reads the attribute error at a position, both unchanged.
+ *
+ * ## What its weight is not
+ *
+ * Slot 10 carries the accumulated triangle count, as the header did. It is **not** a plane count,
+ * and {@link quadric3_distance} on this quadric is not a length: the value is an attribute residual
+ * in whatever units the caller's weights put it in. A caller wanting a length evaluates the *pure
+ * geometric* quadric at the position this one helped choose, which is the whole of the units
+ * discipline (`VIRTUAL_GEOMETRY_DESIGN.md` §3).
+ *
+ * A quadric that has accumulated nothing has no attributes to solve out and reduces to zero, which
+ * is what an empty quadric should add to a sum.
+ *
+ * @param {number[]|Float32Array|Float64Array} out destination, `QUADRIC3_SIZE` elements from
+ *     `out_offset`, overwritten
+ * @param {number} out_offset
+ * @param {ArrayLike<number>} q `quadric_attribute_size(components)` elements from `q_offset`
+ * @param {number} q_offset
+ * @param {number} components number of scalar channels
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function quadric_attribute_reduce(out: number[] | Float32Array | Float64Array, out_offset: number, q: ArrayLike<number>, q_offset: number, components: number): void;
+//# sourceMappingURL=quadric_attribute_reduce.d.ts.map

package/src/core/geom/3d/quadric/quadric_attribute_reduce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quadric_attribute_reduce.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quadric/quadric_attribute_reduce.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,8CAVW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAElC,MAAM,KACN,UAAU,MAAM,CAAC,YACjB,MAAM,cACN,MAAM,QA8DhB"}