@woosh/meep-engine 3.15.0 → 3.17.0

package/src/engine/ecs/transform/Transform64.d.ts

@@ -7,7 +7,11 @@
  */
 export const TRANSFORM64_MATRIX_OFFSET: number;
 /**
- * Index of the first element of the translation (x, y, z) inside a {@link Transform64}
+ * Index of the first element of the translation (x, y, z) inside a {@link Transform64}.
+ *
+ * It is 12, which is inside the matrix: for a column-major affine matrix elements 12..14 are the
+ * translation column, and neither rotation nor scale ever touch it, so the transform keeps a single
+ * copy and the translation is that column. See {@link Transform64#translation} for what that implies.
  * @type {number}
  */
 export const TRANSFORM64_TRANSLATION_OFFSET: number;
@@ -31,7 +35,7 @@ export const TRANSFORM64_SIZE: number;
  * packed into a single `Float64Array`.
  *
  * This is the passive counterpart of {@link Transform}. There are no signals, no flags and no change
- * detection: setting the translation, rotation or scale does **not** refresh {@link matrix}, you call
+ * detection: setting the rotation or scale does **not** refresh {@link matrix}, you call
  * {@link updateMatrix} yourself once you are done mutating. What you get for that is one allocation of one
  * contiguous buffer per transform, plain array stores instead of setter dispatch, and double precision
  * throughout.
@@ -40,18 +44,29 @@ export const TRANSFORM64_SIZE: number;
  * write the buffer without going through the accessors:
  * ```
  * [ 0..15] matrix, column-major
- * [16..18] translation  x, y, z
- * [19..22] rotation     x, y, z, w
- * [23..25] scale        x, y, z
+ * [12..14] translation  x, y, z   (aliased into the matrix)
+ * [16..19] rotation     x, y, z, w
+ * [20..22] scale        x, y, z
  * ```
  *
+ * The translation is not stored twice: it *is* the matrix's translation column, elements 12..14. Which
+ * gives the staleness rule its exact shape - {@link matrix} is correct as long as the rotation and scale
+ * have not changed since the last {@link updateMatrix}. A translation-only change needs no
+ * {@link updateMatrix}, it lands in the matrix as it is written.
+ *
+ * NOTE: the flip side of that is a matrix that can describe a state that never existed. Change the
+ * translation *and* the rotation without an {@link updateMatrix} in between, and the matrix now carries
+ * the new translation under the old orientation, rather than lagging wholesale as it did when the
+ * translation had its own copy. Nothing reads such a matrix on your behalf, but if you hand it out
+ * between the two writes, that is what the receiver sees.
+ *
  * @example
  *  const t = new Transform64();
  *
  *  t.setTranslation(1, 2, 3);
  *  t.setScale(2, 2, 2);
  *
- *  // nothing has touched the matrix up to this point
+ *  // the translation is already in the matrix, the scale is not
  *  t.updateMatrix();
  *
  * @example
@@ -99,7 +114,14 @@ export class Transform64 extends Float64Array {
      * Affine transform matrix, column-major.
      *
      * Unlike {@link Transform}, this is not maintained for you - it holds whatever {@link updateMatrix},
-     * {@link fromMatrix} or {@link multiply} last wrote, and goes stale the moment you set a component.
+     * {@link fromMatrix} or {@link multiply} last wrote, and goes stale the moment you set the rotation
+     * or the scale.
+     *
+     * The translation column, elements 12..14, is shared with {@link translation} - the two are views over
+     * the same three numbers. Writing `matrix[12]` moves the transform, and setting the translation edits
+     * the matrix, so a translation-only change never leaves the matrix stale. Note the trap in the other
+     * direction: after poking the matrix directly, {@link translation} tracks it, while {@link rotation}
+     * and {@link scale} still lag until {@link updateComponents}.
      *
      * NOTE: the returned array is a live view over the transform's own buffer, but a freshly allocated
      * view on every access. Hold on to it rather than reading this property in a loop, or index the
@@ -108,12 +130,18 @@ export class Transform64 extends Float64Array {
      */
     get matrix(): Float64Array;
     /**
-     * Reads 3 elements, does not update {@link matrix}
+     * Reads 3 elements. Lands in {@link matrix} directly, since the translation is a column of it - no
+     * {@link updateMatrix} is needed for a translation-only change.
      * @param {number[]|Float32Array|Float64Array} v
      */
     set translation(arg: Float64Array);
     /**
      * Position in 3D space.
+     *
+     * This is the translation column of {@link matrix}, elements 12..14, not a separate copy: writing
+     * `translation[0]` edits the matrix, and writing `matrix[12]` shows up here. See {@link matrix} for
+     * the trap that comes with that.
+     *
      * NOTE: live view over the transform's own buffer, freshly allocated on every access
      * @returns {Float64Array}
      */
@@ -122,7 +150,8 @@ export class Transform64 extends Float64Array {
     get translation_y(): number;
     get translation_z(): number;
     /**
-     * Does not update {@link matrix}
+     * Lands in {@link matrix} directly, since the translation is a column of it - no {@link updateMatrix}
+     * is needed for a translation-only change.
      * @param {number} x
      * @param {number} y
      * @param {number} z
@@ -278,7 +307,11 @@ export class Transform64 extends Float64Array {
     setScaleScalar(s: number): void;
     /**
      * Write {@link matrix} from the current {@link translation}, {@link rotation} and {@link scale}.
-     * Nothing calls this for you, and until you do, the matrix is whatever it was before.
+     * Nothing calls this for you, and until you do, the rotation and scale part of the matrix is whatever
+     * it was before. The translation column needs no help - it is the translation, see {@link matrix}.
+     *
+     * The translation is passed in as three scalars, read before the first store, so writing it back
+     * over its own column is safe.
      */
     updateMatrix(): void;
     /**
@@ -287,6 +320,9 @@ export class Transform64 extends Float64Array {
      *
      * A matrix carrying shear cannot be described by a translation, a rotation and a scale, so shear is
      * dropped from the components. It survives in {@link matrix} until the next {@link updateMatrix}.
+     *
+     * The matrix itself is left bit-identical: the decompose reads every element before its first store,
+     * and the translation it writes is the matrix's own column copied onto itself.
      */
     updateComponents(): void;
     /**
@@ -327,7 +363,8 @@ export class Transform64 extends Float64Array {
     15: number;
     /**
      * Whether the translation is exactly [0,0,0], the rotation exactly [0,0,0,1] and the scale exactly
-     * [1,1,1]. Says nothing about {@link matrix}, which only agrees after an {@link updateMatrix}.
+     * [1,1,1]. Says nothing about the rotation and scale part of {@link matrix}, which only agrees after
+     * an {@link updateMatrix}; the translation column is the translation, so that much is covered.
      * @returns {boolean}
      */
     isIdentity(): boolean;

package/src/engine/ecs/transform/Transform64.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Transform64.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/Transform64.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"Transform64.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/Transform64.js"],"names":[],"mappings":"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"}

package/src/engine/ecs/transform/Transform64.js

@@ -18,28 +18,32 @@ import { t64_look_rotation } from "./t64_look_rotation.js";
 export const TRANSFORM64_MATRIX_OFFSET = 0;
 
 /**
- * Index of the first element of the translation (x, y, z) inside a {@link Transform64}
+ * Index of the first element of the translation (x, y, z) inside a {@link Transform64}.
+ *
+ * It is 12, which is inside the matrix: for a column-major affine matrix elements 12..14 are the
+ * translation column, and neither rotation nor scale ever touch it, so the transform keeps a single
+ * copy and the translation is that column. See {@link Transform64#translation} for what that implies.
  * @type {number}
  */
-export const TRANSFORM64_TRANSLATION_OFFSET = 16;
+export const TRANSFORM64_TRANSLATION_OFFSET = 12;
 
 /**
  * Index of the first element of the rotation quaternion (x, y, z, w) inside a {@link Transform64}
  * @type {number}
  */
-export const TRANSFORM64_ROTATION_OFFSET = 19;
+export const TRANSFORM64_ROTATION_OFFSET = 16;
 
 /**
  * Index of the first element of the scale (x, y, z) inside a {@link Transform64}
  * @type {number}
  */
-export const TRANSFORM64_SCALE_OFFSET = 23;
+export const TRANSFORM64_SCALE_OFFSET = 20;
 
 /**
  * Number of elements in a {@link Transform64}
  * @type {number}
  */
-export const TRANSFORM64_SIZE = 26;
+export const TRANSFORM64_SIZE = 23;
 
 /**
  * World up, the direction orientation is resolved against when nothing else says otherwise.
@@ -53,7 +57,7 @@ const WORLD_UP = new Float64Array([0, 1, 0]);
  * packed into a single `Float64Array`.
  *
  * This is the passive counterpart of {@link Transform}. There are no signals, no flags and no change
- * detection: setting the translation, rotation or scale does **not** refresh {@link matrix}, you call
+ * detection: setting the rotation or scale does **not** refresh {@link matrix}, you call
  * {@link updateMatrix} yourself once you are done mutating. What you get for that is one allocation of one
  * contiguous buffer per transform, plain array stores instead of setter dispatch, and double precision
  * throughout.
@@ -62,18 +66,29 @@ const WORLD_UP = new Float64Array([0, 1, 0]);
  * write the buffer without going through the accessors:
  * ```
  * [ 0..15] matrix, column-major
- * [16..18] translation  x, y, z
- * [19..22] rotation     x, y, z, w
- * [23..25] scale        x, y, z
+ * [12..14] translation  x, y, z   (aliased into the matrix)
+ * [16..19] rotation     x, y, z, w
+ * [20..22] scale        x, y, z
  * ```
  *
+ * The translation is not stored twice: it *is* the matrix's translation column, elements 12..14. Which
+ * gives the staleness rule its exact shape - {@link matrix} is correct as long as the rotation and scale
+ * have not changed since the last {@link updateMatrix}. A translation-only change needs no
+ * {@link updateMatrix}, it lands in the matrix as it is written.
+ *
+ * NOTE: the flip side of that is a matrix that can describe a state that never existed. Change the
+ * translation *and* the rotation without an {@link updateMatrix} in between, and the matrix now carries
+ * the new translation under the old orientation, rather than lagging wholesale as it did when the
+ * translation had its own copy. Nothing reads such a matrix on your behalf, but if you hand it out
+ * between the two writes, that is what the receiver sees.
+ *
  * @example
  *  const t = new Transform64();
  *
  *  t.setTranslation(1, 2, 3);
  *  t.setScale(2, 2, 2);
  *
- *  // nothing has touched the matrix up to this point
+ *  // the translation is already in the matrix, the scale is not
  *  t.updateMatrix();
  *
  * @example
@@ -105,7 +120,14 @@ export class Transform64 extends Float64Array {
      * Affine transform matrix, column-major.
      *
      * Unlike {@link Transform}, this is not maintained for you - it holds whatever {@link updateMatrix},
-     * {@link fromMatrix} or {@link multiply} last wrote, and goes stale the moment you set a component.
+     * {@link fromMatrix} or {@link multiply} last wrote, and goes stale the moment you set the rotation
+     * or the scale.
+     *
+     * The translation column, elements 12..14, is shared with {@link translation} - the two are views over
+     * the same three numbers. Writing `matrix[12]` moves the transform, and setting the translation edits
+     * the matrix, so a translation-only change never leaves the matrix stale. Note the trap in the other
+     * direction: after poking the matrix directly, {@link translation} tracks it, while {@link rotation}
+     * and {@link scale} still lag until {@link updateComponents}.
      *
      * NOTE: the returned array is a live view over the transform's own buffer, but a freshly allocated
      * view on every access. Hold on to it rather than reading this property in a loop, or index the
@@ -118,6 +140,11 @@ export class Transform64 extends Float64Array {
 
     /**
      * Position in 3D space.
+     *
+     * This is the translation column of {@link matrix}, elements 12..14, not a separate copy: writing
+     * `translation[0]` edits the matrix, and writing `matrix[12]` shows up here. See {@link matrix} for
+     * the trap that comes with that.
+     *
      * NOTE: live view over the transform's own buffer, freshly allocated on every access
      * @returns {Float64Array}
      */
@@ -126,7 +153,8 @@ export class Transform64 extends Float64Array {
     }
 
     /**
-     * Reads 3 elements, does not update {@link matrix}
+     * Reads 3 elements. Lands in {@link matrix} directly, since the translation is a column of it - no
+     * {@link updateMatrix} is needed for a translation-only change.
      * @param {number[]|Float32Array|Float64Array} v
      */
     set translation(v) {
@@ -146,7 +174,8 @@ export class Transform64 extends Float64Array {
     }
 
     /**
-     * Does not update {@link matrix}
+     * Lands in {@link matrix} directly, since the translation is a column of it - no {@link updateMatrix}
+     * is needed for a translation-only change.
      * @param {number} x
      * @param {number} y
      * @param {number} z
@@ -482,7 +511,11 @@ export class Transform64 extends Float64Array {
 
     /**
      * Write {@link matrix} from the current {@link translation}, {@link rotation} and {@link scale}.
-     * Nothing calls this for you, and until you do, the matrix is whatever it was before.
+     * Nothing calls this for you, and until you do, the rotation and scale part of the matrix is whatever
+     * it was before. The translation column needs no help - it is the translation, see {@link matrix}.
+     *
+     * The translation is passed in as three scalars, read before the first store, so writing it back
+     * over its own column is safe.
      */
     updateMatrix() {
         m4_from_rotation_translation_scale_scalar(
@@ -508,6 +541,9 @@ export class Transform64 extends Float64Array {
      *
      * A matrix carrying shear cannot be described by a translation, a rotation and a scale, so shear is
      * dropped from the components. It survives in {@link matrix} until the next {@link updateMatrix}.
+     *
+     * The matrix itself is left bit-identical: the decompose reads every element before its first store,
+     * and the translation it writes is the matrix's own column copied onto itself.
      */
     updateComponents() {
         m4_decompose_array(
@@ -530,6 +566,8 @@ export class Transform64 extends Float64Array {
 
         array_copy(m4, 0, this, TRANSFORM64_MATRIX_OFFSET, 16);
 
+        // the copy above already put the translation where it lives; the decompose writes those three
+        // elements onto themselves, which is harmless and keeps this a straight copy-then-decompose
         this.updateComponents();
 
         return this;
@@ -591,7 +629,8 @@ export class Transform64 extends Float64Array {
 
     /**
      * Whether the translation is exactly [0,0,0], the rotation exactly [0,0,0,1] and the scale exactly
-     * [1,1,1]. Says nothing about {@link matrix}, which only agrees after an {@link updateMatrix}.
+     * [1,1,1]. Says nothing about the rotation and scale part of {@link matrix}, which only agrees after
+     * an {@link updateMatrix}; the translation column is the translation, so that much is covered.
      * @returns {boolean}
      */
     isIdentity() {

package/src/engine/ecs/transform/Transform64SerializationAdapter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Binary serialization for {@link Transform64}.
+ *
+ * Writes the same bytes in the same order as {@link TransformSerializationAdapter}: translation as
+ * three `Float64`s, rotation packed into a single `Uint32`, scale equality-encoded. A save written by
+ * either adapter can be read by the other, which is what lets the engine move onto {@link Transform64}
+ * without a save-format break.
+ *
+ * The matrix is not written. It is derived, and {@link Transform64#updateMatrix} rebuilds it on load
+ * from the three components that were - storing it would cost 128 bytes per transform to persist a
+ * value that is a pure function of the rest.
+ *
+ * The decode helpers take an array and an offset, and a `Transform64` *is* that array, so rotation and
+ * scale are decoded straight into the transform at their own offsets with no intermediate.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Transform64SerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof Transform64;
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Transform64} value
+     */
+    serialize(buffer: BinaryBuffer, value: Transform64): void;
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Transform64} value
+     */
+    deserialize(buffer: BinaryBuffer, value: Transform64): void;
+}
+import { BinaryClassSerializationAdapter } from "../storage/binary/BinaryClassSerializationAdapter.js";
+import { Transform64 } from "./Transform64.js";
+//# sourceMappingURL=Transform64SerializationAdapter.d.ts.map

package/src/engine/ecs/transform/Transform64SerializationAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transform64SerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/Transform64SerializationAdapter.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;GAiBG;AACH;;IAEI,0BAAoB;IAGpB;;;;OAIG;IACH,uCAFW,WAAW,QAiBrB;IAED;;;;OAIG;IACH,yCAFW,WAAW,QAkBrB;CACJ;gDAtE+C,sDAAsD;4BACnB,kBAAkB"}

package/src/engine/ecs/transform/Transform64SerializationAdapter.js

@@ -0,0 +1,75 @@
+import { quat3_decode_from_uint32 } from "../../../core/geom/3d/quaternion/quat3_decode_from_uint32.js";
+import { quat3_encode_to_uint32 } from "../../../core/geom/3d/quaternion/quat3_encode_to_uint32.js";
+import { v3_binary_equality_decode } from "../../../core/geom/vec3/serialization/v3_binary_equality_decode.js";
+import { v3_binary_equality_encode } from "../../../core/geom/vec3/serialization/v3_binary_equality_encode.js";
+import { BinaryClassSerializationAdapter } from "../storage/binary/BinaryClassSerializationAdapter.js";
+import { Transform64, TRANSFORM64_ROTATION_OFFSET, TRANSFORM64_SCALE_OFFSET } from "./Transform64.js";
+
+/**
+ * Binary serialization for {@link Transform64}.
+ *
+ * Writes the same bytes in the same order as {@link TransformSerializationAdapter}: translation as
+ * three `Float64`s, rotation packed into a single `Uint32`, scale equality-encoded. A save written by
+ * either adapter can be read by the other, which is what lets the engine move onto {@link Transform64}
+ * without a save-format break.
+ *
+ * The matrix is not written. It is derived, and {@link Transform64#updateMatrix} rebuilds it on load
+ * from the three components that were - storing it would cost 128 bytes per transform to persist a
+ * value that is a pure function of the rest.
+ *
+ * The decode helpers take an array and an offset, and a `Transform64` *is* that array, so rotation and
+ * scale are decoded straight into the transform at their own offsets with no intermediate.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Transform64SerializationAdapter extends BinaryClassSerializationAdapter {
+
+    klass = Transform64;
+    version = 1;
+
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Transform64} value
+     */
+    serialize(buffer, value) {
+        buffer.writeFloat64(value.translation_x);
+        buffer.writeFloat64(value.translation_y);
+        buffer.writeFloat64(value.translation_z);
+
+        const encoded_rotation = quat3_encode_to_uint32(
+            value.rotation_x,
+            value.rotation_y,
+            value.rotation_z,
+            value.rotation_w
+        );
+
+        buffer.writeUint32(encoded_rotation);
+
+        v3_binary_equality_encode(buffer, value.scale_x, value.scale_y, value.scale_z);
+    }
+
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {Transform64} value
+     */
+    deserialize(buffer, value) {
+        const translation_x = buffer.readFloat64();
+        const translation_y = buffer.readFloat64();
+        const translation_z = buffer.readFloat64();
+
+        const encoded_rotation = buffer.readUint32();
+
+        v3_binary_equality_decode(buffer, value, TRANSFORM64_SCALE_OFFSET);
+
+        quat3_decode_from_uint32(value, TRANSFORM64_ROTATION_OFFSET, encoded_rotation);
+
+        value.setTranslation(translation_x, translation_y, translation_z);
+
+        // rotation and scale were both written, so the matrix owes an update. The translation does
+        // not, being the matrix's own column, but updateMatrix writes it back regardless.
+        value.updateMatrix();
+    }
+}

package/src/engine/ecs/transform/t64_allocation_probe.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Counts how many `Float64Array` views a piece of code causes {@link Transform64} to allocate.
+ *
+ * `t.translation`, `t.rotation` and `t.scale` each build a fresh view over the transform's buffer on
+ * every read. That is the right behaviour for a type that holds no state of its own - caching a view
+ * would mean a field, and being free of fields is the whole point - but it makes those three
+ * accessors the wrong way to read a transform in a loop that runs per entity per frame. The scalar
+ * accessors (`translation_x`, `rotation_w`, ...) and the exported offset constants read the same
+ * numbers without allocating.
+ *
+ * The counting is installed on the prototype for the duration of the call and removed afterwards, so
+ * {@link Transform64} itself carries no instrumentation and ships exactly as written. Nothing here
+ * runs unless a test calls it.
+ *
+ * @example
+ *  const allocations = t64_count_view_allocations(() => {
+ *      for (const t of transforms) {
+ *          total += t.translation_x;      // no view
+ *      }
+ *  });
+ *
+ *  expect(allocations).toBe(0);
+ *
+ * @param {function(): void} fn code to measure
+ * @returns {number} number of views allocated while `fn` ran
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function t64_count_view_allocations(fn: () => void): number;
+//# sourceMappingURL=t64_allocation_probe.d.ts.map

package/src/engine/ecs/transform/t64_allocation_probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"t64_allocation_probe.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/t64_allocation_probe.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qDANuB,IAAI,GACd,MAAM,CA6ClB"}

package/src/engine/ecs/transform/t64_allocation_probe.js

@@ -0,0 +1,78 @@
+import { Transform64 } from "./Transform64.js";
+
+/**
+ * The three accessors that hand out a view over a transform's buffer.
+ * @type {string[]}
+ */
+const VIEW_ACCESSORS = ["translation", "rotation", "scale"];
+
+/**
+ * Counts how many `Float64Array` views a piece of code causes {@link Transform64} to allocate.
+ *
+ * `t.translation`, `t.rotation` and `t.scale` each build a fresh view over the transform's buffer on
+ * every read. That is the right behaviour for a type that holds no state of its own - caching a view
+ * would mean a field, and being free of fields is the whole point - but it makes those three
+ * accessors the wrong way to read a transform in a loop that runs per entity per frame. The scalar
+ * accessors (`translation_x`, `rotation_w`, ...) and the exported offset constants read the same
+ * numbers without allocating.
+ *
+ * The counting is installed on the prototype for the duration of the call and removed afterwards, so
+ * {@link Transform64} itself carries no instrumentation and ships exactly as written. Nothing here
+ * runs unless a test calls it.
+ *
+ * @example
+ *  const allocations = t64_count_view_allocations(() => {
+ *      for (const t of transforms) {
+ *          total += t.translation_x;      // no view
+ *      }
+ *  });
+ *
+ *  expect(allocations).toBe(0);
+ *
+ * @param {function(): void} fn code to measure
+ * @returns {number} number of views allocated while `fn` ran
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function t64_count_view_allocations(fn) {
+    const prototype = Transform64.prototype;
+
+    /**
+     * @type {Map<string, PropertyDescriptor>}
+     */
+    const originals = new Map();
+
+    let count = 0;
+
+    for (const name of VIEW_ACCESSORS) {
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+
+        if (descriptor === undefined || typeof descriptor.get !== "function") {
+            throw new Error(`Transform64.prototype.${name} is not an accessor; the probe is out of date`);
+        }
+
+        originals.set(name, descriptor);
+
+        const original_get = descriptor.get;
+
+        Object.defineProperty(prototype, name, {
+            ...descriptor,
+            get() {
+                count++;
+
+                return original_get.call(this);
+            }
+        });
+    }
+
+    try {
+        fn();
+    } finally {
+        for (const [name, descriptor] of originals) {
+            Object.defineProperty(prototype, name, descriptor);
+        }
+    }
+
+    return count;
+}

package/src/engine/ecs/transform/t64_announce_change.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tell the dataset that an entity's {@link Transform64} was mutated in place.
+ *
+ * A {@link Transform64} carries no signals - that is the point of it - so a write is invisible until
+ * someone says so, and saying so is the writer's job. Every consumer that used to wake on
+ * `position.onChanged` wakes on {@link TRANSFORM64_EVENT_CHANGE} instead: the render placement,
+ * the parent/child sync, fog-of-war, the grid mirror, the spatial audio refit.
+ *
+ * The announcement is deliberately coarse - it names the transform, not what changed inside it - so
+ * a consumer that only tracks translation still wakes on a scale write. That is redundant work, not
+ * wrong work, and it is what lets one call stand in for the three signals it replaces.
+ *
+ * Nothing is sent with it. The event names the transform and reaches only this entity's listeners,
+ * which is everything a listener needs to know; the instance it wants is the one it linked with.
+ *
+ * Call it once per group of writes, after the last of them and after any
+ * {@link Transform64#updateMatrix} the group owes:
+ *
+ * ```
+ * transform.setRotation(x, y, z, w);
+ * transform.updateMatrix();
+ *
+ * t64_announce_change(ecd, entity);
+ * ```
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {number} entity the entity whose transform was written
+ * @returns {void}
+ *
+ * @see TRANSFORM64_EVENT_CHANGE
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function t64_announce_change(ecd: EntityComponentDataset, entity: number): void;
+//# sourceMappingURL=t64_announce_change.d.ts.map

package/src/engine/ecs/transform/t64_announce_change.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"t64_announce_change.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/t64_announce_change.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,yEARW,MAAM,GACJ,IAAI,CAShB"}

package/src/engine/ecs/transform/t64_announce_change.js

@@ -0,0 +1,39 @@
+import { TRANSFORM64_EVENT_CHANGE } from "./TRANSFORM64_EVENT_CHANGE.js";
+
+/**
+ * Tell the dataset that an entity's {@link Transform64} was mutated in place.
+ *
+ * A {@link Transform64} carries no signals - that is the point of it - so a write is invisible until
+ * someone says so, and saying so is the writer's job. Every consumer that used to wake on
+ * `position.onChanged` wakes on {@link TRANSFORM64_EVENT_CHANGE} instead: the render placement,
+ * the parent/child sync, fog-of-war, the grid mirror, the spatial audio refit.
+ *
+ * The announcement is deliberately coarse - it names the transform, not what changed inside it - so
+ * a consumer that only tracks translation still wakes on a scale write. That is redundant work, not
+ * wrong work, and it is what lets one call stand in for the three signals it replaces.
+ *
+ * Nothing is sent with it. The event names the transform and reaches only this entity's listeners,
+ * which is everything a listener needs to know; the instance it wants is the one it linked with.
+ *
+ * Call it once per group of writes, after the last of them and after any
+ * {@link Transform64#updateMatrix} the group owes:
+ *
+ * ```
+ * transform.setRotation(x, y, z, w);
+ * transform.updateMatrix();
+ *
+ * t64_announce_change(ecd, entity);
+ * ```
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {number} entity the entity whose transform was written
+ * @returns {void}
+ *
+ * @see TRANSFORM64_EVENT_CHANGE
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function t64_announce_change(ecd, entity) {
+    ecd.sendEvent(entity, TRANSFORM64_EVENT_CHANGE);
+}

package/src/engine/ecs/transform/t64_equals_components.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Whether two {@link Transform64}s hold the same translation, rotation and scale.
+ *
+ * The counterpart of {@link t64_equals_transform} for two transforms of the same type, and it exists
+ * for the same reason: a system that places on a poll rather than on a signal has to be able to tell
+ * that there is nothing to place. The cost of not asking is not the copy - it is that
+ * `Node3D.updateMatrices` bumps a version whether or not anything moved, and downstream a bumped
+ * version means a scene-database row uploaded and, for a mesh, a whole-tree rebuild of the top-level
+ * acceleration structure.
+ *
+ * **Not {@link Transform64#equals}.** That one compares all 23 elements, the matrix included, and so
+ * reports two transforms as different when only one of them has a stale matrix - which is a state
+ * this type invites, since a rotation or scale write does not refresh the matrix until
+ * {@link Transform64#updateMatrix} is called. Using it as a placement guard would answer "have the
+ * buffers diverged" when the question is "has anything moved", and would let the rebuild it is meant
+ * to prevent back in.
+ *
+ * Exact equality rather than a tolerance, for the same reason {@link t64_equals_transform} uses it:
+ * the question is whether a write would change anything, and a write of a value that differs by any
+ * amount does.
+ *
+ * @param {Transform64} a
+ * @param {Transform64} b
+ * @returns {boolean}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function t64_equals_components(a: Transform64, b: Transform64): boolean;
+//# sourceMappingURL=t64_equals_components.d.ts.map

package/src/engine/ecs/transform/t64_equals_components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"t64_equals_components.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/t64_equals_components.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,uEALa,OAAO,CA4BnB"}