@woosh/meep-engine 3.1.0 → 3.2.0

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

@@ -1,814 +1,814 @@
-import { assert } from "../../../core/assert.js";
-import { array_copy } from "../../../core/collection/array/array_copy.js";
-import { array_range_equal_strict } from "../../../core/collection/array/array_range_equal_strict.js";
-import { m4_decompose_array } from "../../../core/geom/3d/mat4/m4_decompose_array.js";
-import { m4_from_rotation_translation_scale_scalar } from "../../../core/geom/3d/mat4/m4_from_rotation_translation_scale_scalar.js";
-import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
-import { quat3_multiply } from "../../../core/geom/3d/quaternion/quat3_multiply.js";
-import { v3_quaternion_apply } from "../../../core/geom/vec3/v3_quaternion_apply.js";
-import { t64_look_rotation } from "./t64_look_rotation.js";
-
-/**
- * Index of the first element of the 4x4 affine matrix inside a {@link Transform64}.
- *
- * It is 0, which means a `Transform64` can be passed to any `mat4` function directly,
- * in place of the matrix - `m4_multiply(out, a_transform, b_transform)` and the like.
- * @type {number}
- */
-export const TRANSFORM64_MATRIX_OFFSET = 0;
-
-/**
- * Index of the first element of the translation (x, y, z) inside a {@link Transform64}
- * @type {number}
- */
-export const TRANSFORM64_TRANSLATION_OFFSET = 16;
-
-/**
- * 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;
-
-/**
- * Index of the first element of the scale (x, y, z) inside a {@link Transform64}
- * @type {number}
- */
-export const TRANSFORM64_SCALE_OFFSET = 23;
-
-/**
- * Number of elements in a {@link Transform64}
- * @type {number}
- */
-export const TRANSFORM64_SIZE = 26;
-
-/**
- * World up, the direction orientation is resolved against when nothing else says otherwise.
- * @readonly
- * @type {Float64Array}
- */
-const WORLD_UP = new Float64Array([0, 1, 0]);
-
-/**
- * Position, rotation and scale of an object in 3D space, along with the affine matrix they compose into,
- * 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
- * {@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.
- *
- * Every element is addressable directly, and the layout is part of the contract, so hot code can read and
- * 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
- * ```
- *
- * @example
- *  const t = new Transform64();
- *
- *  t.setTranslation(1, 2, 3);
- *  t.setScale(2, 2, 2);
- *
- *  // nothing has touched the matrix up to this point
- *  t.updateMatrix();
- *
- * @example
- *  // reading a component in a hot loop, without the accessors
- *  const x = t[TRANSFORM64_TRANSLATION_OFFSET];
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class Transform64 extends Float64Array {
-
-    /**
-     * Arrays derived from a transform (`slice`, `subarray`, `map`, ...) are plain `Float64Array`s
-     * @returns {Float64ArrayConstructor}
-     */
-    static get [Symbol.species]() {
-        // without this the derived array would be built by our own constructor, which takes no length,
-        // so it would silently come back sized as a whole transform
-        return Float64Array;
-    }
-
-    constructor() {
-        super(TRANSFORM64_SIZE);
-
-        this.makeIdentity();
-    }
-
-    /**
-     * 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.
-     *
-     * 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
-     * transform itself - the matrix starts at element 0.
-     * @returns {Float64Array}
-     */
-    get matrix() {
-        return new Float64Array(this.buffer, this.byteOffset, 16);
-    }
-
-    /**
-     * Position in 3D space.
-     * NOTE: live view over the transform's own buffer, freshly allocated on every access
-     * @returns {Float64Array}
-     */
-    get translation() {
-        return new Float64Array(this.buffer, this.byteOffset + TRANSFORM64_TRANSLATION_OFFSET * 8, 3);
-    }
-
-    /**
-     * Reads 3 elements, does not update {@link matrix}
-     * @param {number[]|Float32Array|Float64Array} v
-     */
-    set translation(v) {
-        array_copy(v, 0, this, TRANSFORM64_TRANSLATION_OFFSET, 3);
-    }
-
-    get translation_x() {
-        return this[TRANSFORM64_TRANSLATION_OFFSET];
-    }
-
-    get translation_y() {
-        return this[TRANSFORM64_TRANSLATION_OFFSET + 1];
-    }
-
-    get translation_z() {
-        return this[TRANSFORM64_TRANSLATION_OFFSET + 2];
-    }
-
-    /**
-     * Does not update {@link matrix}
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     */
-    setTranslation(x, y, z) {
-        assert.isNumber(x, 'x');
-        assert.isNumber(y, 'y');
-        assert.isNumber(z, 'z');
-
-        this[TRANSFORM64_TRANSLATION_OFFSET] = x;
-        this[TRANSFORM64_TRANSLATION_OFFSET + 1] = y;
-        this[TRANSFORM64_TRANSLATION_OFFSET + 2] = z;
-    }
-
-    /**
-     * Orientation, as a quaternion (x, y, z, w).
-     * NOTE: live view over the transform's own buffer, freshly allocated on every access
-     * @returns {Float64Array}
-     */
-    get rotation() {
-        return new Float64Array(this.buffer, this.byteOffset + TRANSFORM64_ROTATION_OFFSET * 8, 4);
-    }
-
-    /**
-     * Reads 4 elements, does not update {@link matrix}
-     * @param {number[]|Float32Array|Float64Array} q
-     */
-    set rotation(q) {
-        array_copy(q, 0, this, TRANSFORM64_ROTATION_OFFSET, 4);
-    }
-
-    get rotation_x() {
-        return this[TRANSFORM64_ROTATION_OFFSET];
-    }
-
-    get rotation_y() {
-        return this[TRANSFORM64_ROTATION_OFFSET + 1];
-    }
-
-    get rotation_z() {
-        return this[TRANSFORM64_ROTATION_OFFSET + 2];
-    }
-
-    get rotation_w() {
-        return this[TRANSFORM64_ROTATION_OFFSET + 3];
-    }
-
-    /**
-     * The quaternion is expected to be of unit length, nothing here normalizes it.
-     * Does not update {@link matrix}.
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     * @param {number} w
-     */
-    setRotation(x, y, z, w) {
-        assert.isNumber(x, 'x');
-        assert.isNumber(y, 'y');
-        assert.isNumber(z, 'z');
-        assert.isNumber(w, 'w');
-
-        this[TRANSFORM64_ROTATION_OFFSET] = x;
-        this[TRANSFORM64_ROTATION_OFFSET + 1] = y;
-        this[TRANSFORM64_ROTATION_OFFSET + 2] = z;
-        this[TRANSFORM64_ROTATION_OFFSET + 3] = w;
-    }
-
-    /**
-     * Local +Z axis, in world space, unit length - for the unit {@link rotation} the class expects.
-     *
-     * Read off {@link rotation} rather than {@link matrix}, so a stale matrix does not lie about it,
-     * and neither does {@link scale} - this is where the transform faces, not how far it reaches.
-     * Use {@link t64_transform_direction} when you want the matrix's answer instead.
-     *
-     * NOTE: this is where {@link Transform#forward} and this one part company. That one reads the
-     * matrix, which it can afford to because it maintains it; here the matrix is stale by design, and
-     * an axis read off it would contradict the setter that had just written the rotation. The two only
-     * disagree under a mirroring (negative) scale, which the matrix carries and the rotation does not.
-     *
-     * NOTE: a freshly allocated copy on every access, not a live view - writing into it does nothing.
-     * @returns {Float64Array}
-     */
-    get forward() {
-        const result = new Float64Array(3);
-
-        v3_quaternion_apply(
-            result, 0,
-            0, 0, 1,
-            this[TRANSFORM64_ROTATION_OFFSET],
-            this[TRANSFORM64_ROTATION_OFFSET + 1],
-            this[TRANSFORM64_ROTATION_OFFSET + 2],
-            this[TRANSFORM64_ROTATION_OFFSET + 3]
-        );
-
-        return result;
-    }
-
-    /**
-     * Turn to face along `v`, that is, set {@link rotation} so that local +Z lands on `v`.
-     *
-     * A direction alone does not pin an orientation down - the spin about it is still free - and that
-     * spin is resolved against world up (0,1,0): local +Y comes out as close to world up as `v` allows.
-     * {@link _lookAt} is the same operation stated as a point to face rather than a direction.
-     *
-     * `v` does not have to be normalized. Reads 3 elements, does not update {@link matrix}.
-     *
-     * NOTE: for a `v` parallel to world up the spin is undetermined, and the answer is whatever
-     * {@link t64_look_rotation} settles on - forward lands within about a milliradian of `v` rather
-     * than exactly on it.
-     *
-     * @param {number[]|Float32Array|Float64Array} v
-     */
-    set forward(v) {
-        assert.notOk(v[0] === 0 && v[1] === 0 && v[2] === 0, 'v must not be zero-length');
-
-        t64_look_rotation(this, v[0], v[1], v[2], 0, 1, 0);
-    }
-
-    /**
-     * Local +X axis, in world space, unit length. See {@link forward} for how this is read.
-     *
-     * NOTE: a freshly allocated copy on every access, not a live view - writing into it does nothing.
-     * @returns {Float64Array}
-     */
-    get right() {
-        const result = new Float64Array(3);
-
-        v3_quaternion_apply(
-            result, 0,
-            1, 0, 0,
-            this[TRANSFORM64_ROTATION_OFFSET],
-            this[TRANSFORM64_ROTATION_OFFSET + 1],
-            this[TRANSFORM64_ROTATION_OFFSET + 2],
-            this[TRANSFORM64_ROTATION_OFFSET + 3]
-        );
-
-        return result;
-    }
-
-    /**
-     * Set {@link rotation} so that local +X lands on `v`, with the spin about it resolved against world
-     * up (0,1,0) exactly as {@link forward} resolves it - local +Y comes out as close to world up as
-     * `v` allows. Setting it to world +X (1,0,0) therefore leaves an identity rotation identity.
-     *
-     * `v` does not have to be normalized. Reads 3 elements, does not update {@link matrix}.
-     *
-     * NOTE: shares {@link forward}'s undetermined case, for a `v` parallel to world up.
-     *
-     * @param {number[]|Float32Array|Float64Array} v
-     */
-    set right(v) {
-        assert.notOk(v[0] === 0 && v[1] === 0 && v[2] === 0, 'v must not be zero-length');
-
-        // `v` goes on local +Z first, which is the case that is already solved - spin, degenerate input
-        // and all. A quarter turn about local Y then carries local +X onto it, and being about Y it
-        // leaves local +Y - the axis the spin was resolved for - exactly where it was.
-        t64_look_rotation(this, v[0], v[1], v[2], 0, 1, 0);
-
-        quat3_multiply(
-            this, TRANSFORM64_ROTATION_OFFSET,
-
-            this[TRANSFORM64_ROTATION_OFFSET],
-            this[TRANSFORM64_ROTATION_OFFSET + 1],
-            this[TRANSFORM64_ROTATION_OFFSET + 2],
-            this[TRANSFORM64_ROTATION_OFFSET + 3],
-
-            // -90 degrees about Y
-            0, -Math.SQRT1_2, 0, Math.SQRT1_2
-        );
-    }
-
-    /**
-     * Local +Y axis, in world space, unit length. See {@link forward} for how this is read.
-     *
-     * NOTE: a freshly allocated copy on every access, not a live view - writing into it does nothing.
-     * @returns {Float64Array}
-     */
-    get up() {
-        const result = new Float64Array(3);
-
-        v3_quaternion_apply(
-            result, 0,
-            0, 1, 0,
-            this[TRANSFORM64_ROTATION_OFFSET],
-            this[TRANSFORM64_ROTATION_OFFSET + 1],
-            this[TRANSFORM64_ROTATION_OFFSET + 2],
-            this[TRANSFORM64_ROTATION_OFFSET + 3]
-        );
-
-        return result;
-    }
-
-    /**
-     * Set {@link rotation} so that local +Y lands on `v`, tipping the transform over.
-     *
-     * World up is of no use as a spin reference here - it is the axis being placed - so the leftover
-     * spin is resolved against world forward (0,0,1) instead: local +Z comes out as close to world
-     * forward as `v` allows. Setting it to world up (0,1,0) therefore leaves an identity rotation
-     * identity, and tipping by a right angle is a pure roll.
-     *
-     * `v` does not have to be normalized. Reads 3 elements, does not update {@link matrix}.
-     *
-     * NOTE: shares {@link forward}'s undetermined case, but for a `v` parallel to world forward.
-     *
-     * @param {number[]|Float32Array|Float64Array} v
-     */
-    set up(v) {
-        assert.notOk(v[0] === 0 && v[1] === 0 && v[2] === 0, 'v must not be zero-length');
-
-        // as in `right`, `v` goes on local +Z first and is relabeled from there; the reference is world
-        // back rather than world forward because the relabeling below reverses that axis on the way
-        t64_look_rotation(this, v[0], v[1], v[2], 0, 0, -1);
-
-        quat3_multiply(
-            this, TRANSFORM64_ROTATION_OFFSET,
-
-            this[TRANSFORM64_ROTATION_OFFSET],
-            this[TRANSFORM64_ROTATION_OFFSET + 1],
-            this[TRANSFORM64_ROTATION_OFFSET + 2],
-            this[TRANSFORM64_ROTATION_OFFSET + 3],
-
-            // +90 degrees about X
-            Math.SQRT1_2, 0, 0, Math.SQRT1_2
-        );
-    }
-
-    /**
-     * Turn to face a point: set {@link rotation} so that local +Z points from {@link translation} at
-     * `(target_x, target_y, target_z)`. The spin about that direction is resolved against `up`, see
-     * {@link forward} for what that means.
-     *
-     * NOTE: a target sitting exactly on the transform's own translation gives no direction to face, and
-     * the rotation is left alone rather than filled with NaN. This matches {@link Transform#lookAt}.
-     *
-     * Neither argument has to be normalized - `up` is a reference direction, not a length. Does not
-     * update {@link matrix}.
-     *
-     * @param {number} target_x point to face, in world space
-     * @param {number} target_y
-     * @param {number} target_z
-     * @param {number} [up_x=0] spin reference, defaults to world up
-     * @param {number} [up_y=1]
-     * @param {number} [up_z=0]
-     */
-    _lookAt(target_x, target_y, target_z, up_x = 0, up_y = 1, up_z = 0) {
-        assert.isNumber(target_x, 'target_x');
-        assert.isNumber(target_y, 'target_y');
-        assert.isNumber(target_z, 'target_z');
-
-        assert.isNumber(up_x, 'up_x');
-        assert.isNumber(up_y, 'up_y');
-        assert.isNumber(up_z, 'up_z');
-
-        // a zero-length up has no direction to resolve the spin against, and would quietly produce a
-        // NaN rotation rather than an unexpected one
-        assert.notOk(up_x === 0 && up_y === 0 && up_z === 0, 'up must not be zero-length');
-
-        const delta_x = target_x - this[TRANSFORM64_TRANSLATION_OFFSET];
-        const delta_y = target_y - this[TRANSFORM64_TRANSLATION_OFFSET + 1];
-        const delta_z = target_z - this[TRANSFORM64_TRANSLATION_OFFSET + 2];
-
-        if (delta_x === 0 && delta_y === 0 && delta_z === 0) {
-            return;
-        }
-
-        t64_look_rotation(this, delta_x, delta_y, delta_z, up_x, up_y, up_z);
-    }
-
-    /**
-     * Turn to face a point, see {@link _lookAt}
-     * @param {number[]|Float32Array|Float64Array|Vector3} target reads 3 elements
-     * @param {number[]|Float32Array|Float64Array|Vector3} [up] reads 3 elements, defaults to world up
-     */
-    lookAt(target, up = WORLD_UP) {
-        this._lookAt(
-            target[0], target[1], target[2],
-            up[0], up[1], up[2]
-        );
-    }
-
-    /**
-     * Size along each local axis.
-     * NOTE: live view over the transform's own buffer, freshly allocated on every access
-     * @returns {Float64Array}
-     */
-    get scale() {
-        return new Float64Array(this.buffer, this.byteOffset + TRANSFORM64_SCALE_OFFSET * 8, 3);
-    }
-
-    /**
-     * Reads 3 elements, does not update {@link matrix}
-     * @param {number[]|Float32Array|Float64Array} v
-     */
-    set scale(v) {
-        array_copy(v, 0, this, TRANSFORM64_SCALE_OFFSET, 3);
-    }
-
-    get scale_x() {
-        return this[TRANSFORM64_SCALE_OFFSET];
-    }
-
-    get scale_y() {
-        return this[TRANSFORM64_SCALE_OFFSET + 1];
-    }
-
-    get scale_z() {
-        return this[TRANSFORM64_SCALE_OFFSET + 2];
-    }
-
-    /**
-     * Does not update {@link matrix}
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     */
-    setScale(x, y, z) {
-        assert.isNumber(x, 'x');
-        assert.isNumber(y, 'y');
-        assert.isNumber(z, 'z');
-
-        this[TRANSFORM64_SCALE_OFFSET] = x;
-        this[TRANSFORM64_SCALE_OFFSET + 1] = y;
-        this[TRANSFORM64_SCALE_OFFSET + 2] = z;
-    }
-
-    /**
-     * Uniform scale. Does not update {@link matrix}.
-     * @param {number} s
-     */
-    setScaleScalar(s) {
-        this.setScale(s, s, s);
-    }
-
-    /**
-     * 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.
-     */
-    updateMatrix() {
-        m4_from_rotation_translation_scale_scalar(
-            this,
-            this[TRANSFORM64_ROTATION_OFFSET],
-            this[TRANSFORM64_ROTATION_OFFSET + 1],
-            this[TRANSFORM64_ROTATION_OFFSET + 2],
-            this[TRANSFORM64_ROTATION_OFFSET + 3],
-
-            this[TRANSFORM64_TRANSLATION_OFFSET],
-            this[TRANSFORM64_TRANSLATION_OFFSET + 1],
-            this[TRANSFORM64_TRANSLATION_OFFSET + 2],
-
-            this[TRANSFORM64_SCALE_OFFSET],
-            this[TRANSFORM64_SCALE_OFFSET + 1],
-            this[TRANSFORM64_SCALE_OFFSET + 2]
-        );
-    }
-
-    /**
-     * Write {@link translation}, {@link rotation} and {@link scale} from the current {@link matrix}.
-     * The inverse of {@link updateMatrix}; call it after writing the matrix in place.
-     *
-     * 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}.
-     */
-    updateComponents() {
-        m4_decompose_array(
-            this,
-            this, TRANSFORM64_TRANSLATION_OFFSET,
-            this, TRANSFORM64_ROTATION_OFFSET,
-            this, TRANSFORM64_SCALE_OFFSET
-        );
-    }
-
-    /**
-     * Set the whole transform, matrix and components both, from an affine matrix.
-     * See {@link updateComponents} for how shear is handled.
-     * @param {number[]|Float32Array|Float64Array|mat4} m4 4x4 affine matrix, column-major
-     * @returns {this}
-     */
-    fromMatrix(m4) {
-        assert.isArrayLike(m4, 'm4');
-        assert.greaterThanOrEqual(m4.length, 16, 'm4.length');
-
-        array_copy(m4, 0, this, TRANSFORM64_MATRIX_OFFSET, 16);
-
-        this.updateComponents();
-
-        return this;
-    }
-
-    /**
-     * Post-multiplication, `this = this * other`. See {@link multiplyTransforms}.
-     * @param {Transform64} other
-     * @returns {this}
-     */
-    multiply(other) {
-        return this.multiplyTransforms(this, other);
-    }
-
-    /**
-     * Multiply two transforms, writing the result into this one. Either operand may be this transform.
-     *
-     * Both operands are read through their matrices, not their components, so a stale matrix on either
-     * side produces a stale result - {@link updateMatrix} them first if you have been setting components.
-     * Both the matrix and the components of the result are left up to date.
-     *
-     * @param {Transform64} a
-     * @param {Transform64} b
-     * @returns {this}
-     */
-    multiplyTransforms(a, b) {
-        assert.equal(a.isTransform64, true, 'a.isTransform64 !== true');
-        assert.equal(b.isTransform64, true, 'b.isTransform64 !== true');
-
-        // both operands are fully read into locals before the first write, so aliasing is safe
-        m4_multiply(this, a, b);
-
-        this.updateComponents();
-
-        return this;
-    }
-
-    /**
-     * Reset to the identity transform, matrix included:
-     *      - translation: [0,0,0]
-     *      - rotation:    [0,0,0,1]
-     *      - scale:       [1,1,1]
-     */
-    makeIdentity() {
-        this.fill(0);
-
-        // matrix diagonal
-        this[0] = 1;
-        this[5] = 1;
-        this[10] = 1;
-        this[15] = 1;
-
-        this[TRANSFORM64_ROTATION_OFFSET + 3] = 1;
-
-        this[TRANSFORM64_SCALE_OFFSET] = 1;
-        this[TRANSFORM64_SCALE_OFFSET + 1] = 1;
-        this[TRANSFORM64_SCALE_OFFSET + 2] = 1;
-    }
-
-    /**
-     * 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}.
-     * @returns {boolean}
-     */
-    isIdentity() {
-        return this[TRANSFORM64_TRANSLATION_OFFSET] === 0
-            && this[TRANSFORM64_TRANSLATION_OFFSET + 1] === 0
-            && this[TRANSFORM64_TRANSLATION_OFFSET + 2] === 0
-            && this[TRANSFORM64_ROTATION_OFFSET] === 0
-            && this[TRANSFORM64_ROTATION_OFFSET + 1] === 0
-            && this[TRANSFORM64_ROTATION_OFFSET + 2] === 0
-            && this[TRANSFORM64_ROTATION_OFFSET + 3] === 1
-            && this[TRANSFORM64_SCALE_OFFSET] === 1
-            && this[TRANSFORM64_SCALE_OFFSET + 1] === 1
-            && this[TRANSFORM64_SCALE_OFFSET + 2] === 1;
-    }
-
-    /**
-     * Set this transform to match `other`, matrix included. The `other` is left unchanged.
-     * @param {Transform64} other
-     */
-    copy(other) {
-        this.set(other);
-    }
-
-    /**
-     * A new transform equal to this one
-     * @returns {Transform64}
-     */
-    clone() {
-        const r = new Transform64();
-
-        r.copy(this);
-
-        return r;
-    }
-
-    /**
-     * Strict equality across the whole transform, {@link matrix} included. Two transforms whose components
-     * match but whose matrices do not - because one of them is stale - are not equal.
-     * @param {Transform64} other
-     * @returns {boolean}
-     */
-    equals(other) {
-        return array_range_equal_strict(this, 0, other, 0, TRANSFORM64_SIZE);
-    }
-
-    /**
-     * Only the translation contributes, for speed - in most applications it is what varies the most.
-     *
-     * This is weaker than {@link equals}: transforms differing only in rotation, scale or matrix collide.
-     * Legal for a hash, but a poor key if your set varies along those axes alone.
-     * @returns {number}
-     */
-    hash() {
-        const x = this[TRANSFORM64_TRANSLATION_OFFSET];
-        const y = this[TRANSFORM64_TRANSLATION_OFFSET + 1];
-        const z = this[TRANSFORM64_TRANSLATION_OFFSET + 2];
-
-        // Same arithmetic as `computeHashFloat`, written out by hand so that this is a straight line with
-        // no calls and no loop. Per component: split into whole and fractional parts, scale the fraction
-        // into uint32 range and flip it so that tiny fractions land in the high bits, then XOR the two.
-        const x_whole = x >> 0;
-        const y_whole = y >> 0;
-        const z_whole = z >> 0;
-
-        const x_hash = (4294967295 - (((x - x_whole) * 4294967295) >>> 0)) ^ x_whole;
-        const y_hash = (4294967295 - (((y - y_whole) * 4294967295) >>> 0)) ^ y_whole;
-        const z_hash = (4294967295 - (((z - z_whole) * 4294967295) >>> 0)) ^ z_whole;
-
-        // mix, `h*31 + v` expressed as a shift so it stays in integer arithmetic
-        let hash = ((x_hash << 5) - x_hash + y_hash) | 0;
-
-        hash = ((hash << 5) - hash + z_hash) | 0;
-
-        return hash;
-    }
-
-    /**
-     * Read the components from `{translation, rotation, scale}`, each of them optional and defaulting to
-     * identity. Composes {@link matrix} from the result.
-     *
-     * NOTE: the translation is keyed `translation`, where {@link Transform} keys the same thing
-     * `position`. The two JSON forms are not interchangeable.
-     * @param json
-     */
-    fromJSON(json) {
-        const t = json.translation;
-
-        if (t !== undefined) {
-            this.setTranslation(t.x, t.y, t.z);
-        } else {
-            this.setTranslation(0, 0, 0);
-        }
-
-        const r = json.rotation;
-
-        if (r !== undefined) {
-            this.setRotation(r.x, r.y, r.z, r.w);
-        } else {
-            this.setRotation(0, 0, 0, 1);
-        }
-
-        const s = json.scale;
-
-        if (s !== undefined) {
-            this.setScale(s.x, s.y, s.z);
-        } else {
-            this.setScale(1, 1, 1);
-        }
-
-        this.updateMatrix();
-    }
-
-    /**
-     * Writes out the components only; {@link matrix} is recomposed from them on the way back in
-     * @returns {{translation:{x:number,y:number,z:number}, rotation:{x:number,y:number,z:number,w:number}, scale:{x:number,y:number,z:number}}}
-     */
-    toJSON() {
-        return {
-            translation: {
-                x: this[TRANSFORM64_TRANSLATION_OFFSET],
-                y: this[TRANSFORM64_TRANSLATION_OFFSET + 1],
-                z: this[TRANSFORM64_TRANSLATION_OFFSET + 2]
-            },
-            rotation: {
-                x: this[TRANSFORM64_ROTATION_OFFSET],
-                y: this[TRANSFORM64_ROTATION_OFFSET + 1],
-                z: this[TRANSFORM64_ROTATION_OFFSET + 2],
-                w: this[TRANSFORM64_ROTATION_OFFSET + 3]
-            },
-            scale: {
-                x: this[TRANSFORM64_SCALE_OFFSET],
-                y: this[TRANSFORM64_SCALE_OFFSET + 1],
-                z: this[TRANSFORM64_SCALE_OFFSET + 2]
-            }
-        };
-    }
-
-    /**
-     * Human-readable form, components only
-     * @returns {string}
-     */
-    toString() {
-        return `Transform64{ translation: [${this.translation_x}, ${this.translation_y}, ${this.translation_z}]`
-            + `, rotation: [${this.rotation_x}, ${this.rotation_y}, ${this.rotation_z}, ${this.rotation_w}]`
-            + `, scale: [${this.scale_x}, ${this.scale_y}, ${this.scale_z}] }`;
-    }
-
-    /**
-     * Build a transform from loose components, with {@link matrix} already composed from them
-     * @param {number} translation_x
-     * @param {number} translation_y
-     * @param {number} translation_z
-     * @param {number} rotation_x
-     * @param {number} rotation_y
-     * @param {number} rotation_z
-     * @param {number} rotation_w
-     * @param {number} scale_x
-     * @param {number} scale_y
-     * @param {number} scale_z
-     * @returns {Transform64}
-     */
-    static from(
-        translation_x, translation_y, translation_z,
-        rotation_x, rotation_y, rotation_z, rotation_w,
-        scale_x, scale_y, scale_z
-    ) {
-        const r = new Transform64();
-
-        r.setTranslation(translation_x, translation_y, translation_z);
-        r.setRotation(rotation_x, rotation_y, rotation_z, rotation_w);
-        r.setScale(scale_x, scale_y, scale_z);
-
-        r.updateMatrix();
-
-        return r;
-    }
-
-    /**
-     * Build a transform from an affine matrix, see {@link fromMatrix}
-     * @param {number[]|Float32Array|Float64Array|mat4} m4 4x4 affine matrix, column-major
-     * @returns {Transform64}
-     */
-    static fromMatrix(m4) {
-        const r = new Transform64();
-
-        r.fromMatrix(m4);
-
-        return r;
-    }
-
-    /**
-     * Build a transform from its JSON form, see {@link fromJSON}
-     * @param json
-     * @returns {Transform64}
-     */
-    static fromJSON(json) {
-        const r = new Transform64();
-
-        r.fromJSON(json);
-
-        return r;
-    }
-}
-
-/**
- * @readonly
- * @type {string}
- */
-Transform64.typeName = "Transform64";
-
-/**
- * Enables a fast type check, without having to import the class separately.
- * @readonly
- * @type {boolean}
- * @example
- *  if(t.isTransform64){
- *      // t is a Transform64, do stuff
- *  }
- */
-Transform64.prototype.isTransform64 = true;
+import { assert } from "../../../core/assert.js";
+import { array_copy } from "../../../core/collection/array/array_copy.js";
+import { array_range_equal_strict } from "../../../core/collection/array/array_range_equal_strict.js";
+import { m4_decompose_array } from "../../../core/geom/3d/mat4/m4_decompose_array.js";
+import { m4_from_rotation_translation_scale_scalar } from "../../../core/geom/3d/mat4/m4_from_rotation_translation_scale_scalar.js";
+import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
+import { quat3_multiply } from "../../../core/geom/3d/quaternion/quat3_multiply.js";
+import { v3_quaternion_apply } from "../../../core/geom/vec3/v3_quaternion_apply.js";
+import { t64_look_rotation } from "./t64_look_rotation.js";
+
+/**
+ * Index of the first element of the 4x4 affine matrix inside a {@link Transform64}.
+ *
+ * It is 0, which means a `Transform64` can be passed to any `mat4` function directly,
+ * in place of the matrix - `m4_multiply(out, a_transform, b_transform)` and the like.
+ * @type {number}
+ */
+export const TRANSFORM64_MATRIX_OFFSET = 0;
+
+/**
+ * Index of the first element of the translation (x, y, z) inside a {@link Transform64}
+ * @type {number}
+ */
+export const TRANSFORM64_TRANSLATION_OFFSET = 16;
+
+/**
+ * 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;
+
+/**
+ * Index of the first element of the scale (x, y, z) inside a {@link Transform64}
+ * @type {number}
+ */
+export const TRANSFORM64_SCALE_OFFSET = 23;
+
+/**
+ * Number of elements in a {@link Transform64}
+ * @type {number}
+ */
+export const TRANSFORM64_SIZE = 26;
+
+/**
+ * World up, the direction orientation is resolved against when nothing else says otherwise.
+ * @readonly
+ * @type {Float64Array}
+ */
+const WORLD_UP = new Float64Array([0, 1, 0]);
+
+/**
+ * Position, rotation and scale of an object in 3D space, along with the affine matrix they compose into,
+ * 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
+ * {@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.
+ *
+ * Every element is addressable directly, and the layout is part of the contract, so hot code can read and
+ * 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
+ * ```
+ *
+ * @example
+ *  const t = new Transform64();
+ *
+ *  t.setTranslation(1, 2, 3);
+ *  t.setScale(2, 2, 2);
+ *
+ *  // nothing has touched the matrix up to this point
+ *  t.updateMatrix();
+ *
+ * @example
+ *  // reading a component in a hot loop, without the accessors
+ *  const x = t[TRANSFORM64_TRANSLATION_OFFSET];
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Transform64 extends Float64Array {
+
+    /**
+     * Arrays derived from a transform (`slice`, `subarray`, `map`, ...) are plain `Float64Array`s
+     * @returns {Float64ArrayConstructor}
+     */
+    static get [Symbol.species]() {
+        // without this the derived array would be built by our own constructor, which takes no length,
+        // so it would silently come back sized as a whole transform
+        return Float64Array;
+    }
+
+    constructor() {
+        super(TRANSFORM64_SIZE);
+
+        this.makeIdentity();
+    }
+
+    /**
+     * 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.
+     *
+     * 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
+     * transform itself - the matrix starts at element 0.
+     * @returns {Float64Array}
+     */
+    get matrix() {
+        return new Float64Array(this.buffer, this.byteOffset, 16);
+    }
+
+    /**
+     * Position in 3D space.
+     * NOTE: live view over the transform's own buffer, freshly allocated on every access
+     * @returns {Float64Array}
+     */
+    get translation() {
+        return new Float64Array(this.buffer, this.byteOffset + TRANSFORM64_TRANSLATION_OFFSET * 8, 3);
+    }
+
+    /**
+     * Reads 3 elements, does not update {@link matrix}
+     * @param {number[]|Float32Array|Float64Array} v
+     */
+    set translation(v) {
+        array_copy(v, 0, this, TRANSFORM64_TRANSLATION_OFFSET, 3);
+    }
+
+    get translation_x() {
+        return this[TRANSFORM64_TRANSLATION_OFFSET];
+    }
+
+    get translation_y() {
+        return this[TRANSFORM64_TRANSLATION_OFFSET + 1];
+    }
+
+    get translation_z() {
+        return this[TRANSFORM64_TRANSLATION_OFFSET + 2];
+    }
+
+    /**
+     * Does not update {@link matrix}
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    setTranslation(x, y, z) {
+        assert.isNumber(x, 'x');
+        assert.isNumber(y, 'y');
+        assert.isNumber(z, 'z');
+
+        this[TRANSFORM64_TRANSLATION_OFFSET] = x;
+        this[TRANSFORM64_TRANSLATION_OFFSET + 1] = y;
+        this[TRANSFORM64_TRANSLATION_OFFSET + 2] = z;
+    }
+
+    /**
+     * Orientation, as a quaternion (x, y, z, w).
+     * NOTE: live view over the transform's own buffer, freshly allocated on every access
+     * @returns {Float64Array}
+     */
+    get rotation() {
+        return new Float64Array(this.buffer, this.byteOffset + TRANSFORM64_ROTATION_OFFSET * 8, 4);
+    }
+
+    /**
+     * Reads 4 elements, does not update {@link matrix}
+     * @param {number[]|Float32Array|Float64Array} q
+     */
+    set rotation(q) {
+        array_copy(q, 0, this, TRANSFORM64_ROTATION_OFFSET, 4);
+    }
+
+    get rotation_x() {
+        return this[TRANSFORM64_ROTATION_OFFSET];
+    }
+
+    get rotation_y() {
+        return this[TRANSFORM64_ROTATION_OFFSET + 1];
+    }
+
+    get rotation_z() {
+        return this[TRANSFORM64_ROTATION_OFFSET + 2];
+    }
+
+    get rotation_w() {
+        return this[TRANSFORM64_ROTATION_OFFSET + 3];
+    }
+
+    /**
+     * The quaternion is expected to be of unit length, nothing here normalizes it.
+     * Does not update {@link matrix}.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number} w
+     */
+    setRotation(x, y, z, w) {
+        assert.isNumber(x, 'x');
+        assert.isNumber(y, 'y');
+        assert.isNumber(z, 'z');
+        assert.isNumber(w, 'w');
+
+        this[TRANSFORM64_ROTATION_OFFSET] = x;
+        this[TRANSFORM64_ROTATION_OFFSET + 1] = y;
+        this[TRANSFORM64_ROTATION_OFFSET + 2] = z;
+        this[TRANSFORM64_ROTATION_OFFSET + 3] = w;
+    }
+
+    /**
+     * Local +Z axis, in world space, unit length - for the unit {@link rotation} the class expects.
+     *
+     * Read off {@link rotation} rather than {@link matrix}, so a stale matrix does not lie about it,
+     * and neither does {@link scale} - this is where the transform faces, not how far it reaches.
+     * Use {@link t64_transform_direction} when you want the matrix's answer instead.
+     *
+     * NOTE: this is where {@link Transform#forward} and this one part company. That one reads the
+     * matrix, which it can afford to because it maintains it; here the matrix is stale by design, and
+     * an axis read off it would contradict the setter that had just written the rotation. The two only
+     * disagree under a mirroring (negative) scale, which the matrix carries and the rotation does not.
+     *
+     * NOTE: a freshly allocated copy on every access, not a live view - writing into it does nothing.
+     * @returns {Float64Array}
+     */
+    get forward() {
+        const result = new Float64Array(3);
+
+        v3_quaternion_apply(
+            result, 0,
+            0, 0, 1,
+            this[TRANSFORM64_ROTATION_OFFSET],
+            this[TRANSFORM64_ROTATION_OFFSET + 1],
+            this[TRANSFORM64_ROTATION_OFFSET + 2],
+            this[TRANSFORM64_ROTATION_OFFSET + 3]
+        );
+
+        return result;
+    }
+
+    /**
+     * Turn to face along `v`, that is, set {@link rotation} so that local +Z lands on `v`.
+     *
+     * A direction alone does not pin an orientation down - the spin about it is still free - and that
+     * spin is resolved against world up (0,1,0): local +Y comes out as close to world up as `v` allows.
+     * {@link _lookAt} is the same operation stated as a point to face rather than a direction.
+     *
+     * `v` does not have to be normalized. Reads 3 elements, does not update {@link matrix}.
+     *
+     * NOTE: for a `v` parallel to world up the spin is undetermined, and the answer is whatever
+     * {@link t64_look_rotation} settles on - forward lands within about a milliradian of `v` rather
+     * than exactly on it.
+     *
+     * @param {number[]|Float32Array|Float64Array} v
+     */
+    set forward(v) {
+        assert.notOk(v[0] === 0 && v[1] === 0 && v[2] === 0, 'v must not be zero-length');
+
+        t64_look_rotation(this, v[0], v[1], v[2], 0, 1, 0);
+    }
+
+    /**
+     * Local +X axis, in world space, unit length. See {@link forward} for how this is read.
+     *
+     * NOTE: a freshly allocated copy on every access, not a live view - writing into it does nothing.
+     * @returns {Float64Array}
+     */
+    get right() {
+        const result = new Float64Array(3);
+
+        v3_quaternion_apply(
+            result, 0,
+            1, 0, 0,
+            this[TRANSFORM64_ROTATION_OFFSET],
+            this[TRANSFORM64_ROTATION_OFFSET + 1],
+            this[TRANSFORM64_ROTATION_OFFSET + 2],
+            this[TRANSFORM64_ROTATION_OFFSET + 3]
+        );
+
+        return result;
+    }
+
+    /**
+     * Set {@link rotation} so that local +X lands on `v`, with the spin about it resolved against world
+     * up (0,1,0) exactly as {@link forward} resolves it - local +Y comes out as close to world up as
+     * `v` allows. Setting it to world +X (1,0,0) therefore leaves an identity rotation identity.
+     *
+     * `v` does not have to be normalized. Reads 3 elements, does not update {@link matrix}.
+     *
+     * NOTE: shares {@link forward}'s undetermined case, for a `v` parallel to world up.
+     *
+     * @param {number[]|Float32Array|Float64Array} v
+     */
+    set right(v) {
+        assert.notOk(v[0] === 0 && v[1] === 0 && v[2] === 0, 'v must not be zero-length');
+
+        // `v` goes on local +Z first, which is the case that is already solved - spin, degenerate input
+        // and all. A quarter turn about local Y then carries local +X onto it, and being about Y it
+        // leaves local +Y - the axis the spin was resolved for - exactly where it was.
+        t64_look_rotation(this, v[0], v[1], v[2], 0, 1, 0);
+
+        quat3_multiply(
+            this, TRANSFORM64_ROTATION_OFFSET,
+
+            this[TRANSFORM64_ROTATION_OFFSET],
+            this[TRANSFORM64_ROTATION_OFFSET + 1],
+            this[TRANSFORM64_ROTATION_OFFSET + 2],
+            this[TRANSFORM64_ROTATION_OFFSET + 3],
+
+            // -90 degrees about Y
+            0, -Math.SQRT1_2, 0, Math.SQRT1_2
+        );
+    }
+
+    /**
+     * Local +Y axis, in world space, unit length. See {@link forward} for how this is read.
+     *
+     * NOTE: a freshly allocated copy on every access, not a live view - writing into it does nothing.
+     * @returns {Float64Array}
+     */
+    get up() {
+        const result = new Float64Array(3);
+
+        v3_quaternion_apply(
+            result, 0,
+            0, 1, 0,
+            this[TRANSFORM64_ROTATION_OFFSET],
+            this[TRANSFORM64_ROTATION_OFFSET + 1],
+            this[TRANSFORM64_ROTATION_OFFSET + 2],
+            this[TRANSFORM64_ROTATION_OFFSET + 3]
+        );
+
+        return result;
+    }
+
+    /**
+     * Set {@link rotation} so that local +Y lands on `v`, tipping the transform over.
+     *
+     * World up is of no use as a spin reference here - it is the axis being placed - so the leftover
+     * spin is resolved against world forward (0,0,1) instead: local +Z comes out as close to world
+     * forward as `v` allows. Setting it to world up (0,1,0) therefore leaves an identity rotation
+     * identity, and tipping by a right angle is a pure roll.
+     *
+     * `v` does not have to be normalized. Reads 3 elements, does not update {@link matrix}.
+     *
+     * NOTE: shares {@link forward}'s undetermined case, but for a `v` parallel to world forward.
+     *
+     * @param {number[]|Float32Array|Float64Array} v
+     */
+    set up(v) {
+        assert.notOk(v[0] === 0 && v[1] === 0 && v[2] === 0, 'v must not be zero-length');
+
+        // as in `right`, `v` goes on local +Z first and is relabeled from there; the reference is world
+        // back rather than world forward because the relabeling below reverses that axis on the way
+        t64_look_rotation(this, v[0], v[1], v[2], 0, 0, -1);
+
+        quat3_multiply(
+            this, TRANSFORM64_ROTATION_OFFSET,
+
+            this[TRANSFORM64_ROTATION_OFFSET],
+            this[TRANSFORM64_ROTATION_OFFSET + 1],
+            this[TRANSFORM64_ROTATION_OFFSET + 2],
+            this[TRANSFORM64_ROTATION_OFFSET + 3],
+
+            // +90 degrees about X
+            Math.SQRT1_2, 0, 0, Math.SQRT1_2
+        );
+    }
+
+    /**
+     * Turn to face a point: set {@link rotation} so that local +Z points from {@link translation} at
+     * `(target_x, target_y, target_z)`. The spin about that direction is resolved against `up`, see
+     * {@link forward} for what that means.
+     *
+     * NOTE: a target sitting exactly on the transform's own translation gives no direction to face, and
+     * the rotation is left alone rather than filled with NaN. This matches {@link Transform#lookAt}.
+     *
+     * Neither argument has to be normalized - `up` is a reference direction, not a length. Does not
+     * update {@link matrix}.
+     *
+     * @param {number} target_x point to face, in world space
+     * @param {number} target_y
+     * @param {number} target_z
+     * @param {number} [up_x=0] spin reference, defaults to world up
+     * @param {number} [up_y=1]
+     * @param {number} [up_z=0]
+     */
+    _lookAt(target_x, target_y, target_z, up_x = 0, up_y = 1, up_z = 0) {
+        assert.isNumber(target_x, 'target_x');
+        assert.isNumber(target_y, 'target_y');
+        assert.isNumber(target_z, 'target_z');
+
+        assert.isNumber(up_x, 'up_x');
+        assert.isNumber(up_y, 'up_y');
+        assert.isNumber(up_z, 'up_z');
+
+        // a zero-length up has no direction to resolve the spin against, and would quietly produce a
+        // NaN rotation rather than an unexpected one
+        assert.notOk(up_x === 0 && up_y === 0 && up_z === 0, 'up must not be zero-length');
+
+        const delta_x = target_x - this[TRANSFORM64_TRANSLATION_OFFSET];
+        const delta_y = target_y - this[TRANSFORM64_TRANSLATION_OFFSET + 1];
+        const delta_z = target_z - this[TRANSFORM64_TRANSLATION_OFFSET + 2];
+
+        if (delta_x === 0 && delta_y === 0 && delta_z === 0) {
+            return;
+        }
+
+        t64_look_rotation(this, delta_x, delta_y, delta_z, up_x, up_y, up_z);
+    }
+
+    /**
+     * Turn to face a point, see {@link _lookAt}
+     * @param {number[]|Float32Array|Float64Array|Vector3} target reads 3 elements
+     * @param {number[]|Float32Array|Float64Array|Vector3} [up] reads 3 elements, defaults to world up
+     */
+    lookAt(target, up = WORLD_UP) {
+        this._lookAt(
+            target[0], target[1], target[2],
+            up[0], up[1], up[2]
+        );
+    }
+
+    /**
+     * Size along each local axis.
+     * NOTE: live view over the transform's own buffer, freshly allocated on every access
+     * @returns {Float64Array}
+     */
+    get scale() {
+        return new Float64Array(this.buffer, this.byteOffset + TRANSFORM64_SCALE_OFFSET * 8, 3);
+    }
+
+    /**
+     * Reads 3 elements, does not update {@link matrix}
+     * @param {number[]|Float32Array|Float64Array} v
+     */
+    set scale(v) {
+        array_copy(v, 0, this, TRANSFORM64_SCALE_OFFSET, 3);
+    }
+
+    get scale_x() {
+        return this[TRANSFORM64_SCALE_OFFSET];
+    }
+
+    get scale_y() {
+        return this[TRANSFORM64_SCALE_OFFSET + 1];
+    }
+
+    get scale_z() {
+        return this[TRANSFORM64_SCALE_OFFSET + 2];
+    }
+
+    /**
+     * Does not update {@link matrix}
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    setScale(x, y, z) {
+        assert.isNumber(x, 'x');
+        assert.isNumber(y, 'y');
+        assert.isNumber(z, 'z');
+
+        this[TRANSFORM64_SCALE_OFFSET] = x;
+        this[TRANSFORM64_SCALE_OFFSET + 1] = y;
+        this[TRANSFORM64_SCALE_OFFSET + 2] = z;
+    }
+
+    /**
+     * Uniform scale. Does not update {@link matrix}.
+     * @param {number} s
+     */
+    setScaleScalar(s) {
+        this.setScale(s, s, s);
+    }
+
+    /**
+     * 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.
+     */
+    updateMatrix() {
+        m4_from_rotation_translation_scale_scalar(
+            this,
+            this[TRANSFORM64_ROTATION_OFFSET],
+            this[TRANSFORM64_ROTATION_OFFSET + 1],
+            this[TRANSFORM64_ROTATION_OFFSET + 2],
+            this[TRANSFORM64_ROTATION_OFFSET + 3],
+
+            this[TRANSFORM64_TRANSLATION_OFFSET],
+            this[TRANSFORM64_TRANSLATION_OFFSET + 1],
+            this[TRANSFORM64_TRANSLATION_OFFSET + 2],
+
+            this[TRANSFORM64_SCALE_OFFSET],
+            this[TRANSFORM64_SCALE_OFFSET + 1],
+            this[TRANSFORM64_SCALE_OFFSET + 2]
+        );
+    }
+
+    /**
+     * Write {@link translation}, {@link rotation} and {@link scale} from the current {@link matrix}.
+     * The inverse of {@link updateMatrix}; call it after writing the matrix in place.
+     *
+     * 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}.
+     */
+    updateComponents() {
+        m4_decompose_array(
+            this,
+            this, TRANSFORM64_TRANSLATION_OFFSET,
+            this, TRANSFORM64_ROTATION_OFFSET,
+            this, TRANSFORM64_SCALE_OFFSET
+        );
+    }
+
+    /**
+     * Set the whole transform, matrix and components both, from an affine matrix.
+     * See {@link updateComponents} for how shear is handled.
+     * @param {number[]|Float32Array|Float64Array|mat4} m4 4x4 affine matrix, column-major
+     * @returns {this}
+     */
+    fromMatrix(m4) {
+        assert.isArrayLike(m4, 'm4');
+        assert.greaterThanOrEqual(m4.length, 16, 'm4.length');
+
+        array_copy(m4, 0, this, TRANSFORM64_MATRIX_OFFSET, 16);
+
+        this.updateComponents();
+
+        return this;
+    }
+
+    /**
+     * Post-multiplication, `this = this * other`. See {@link multiplyTransforms}.
+     * @param {Transform64} other
+     * @returns {this}
+     */
+    multiply(other) {
+        return this.multiplyTransforms(this, other);
+    }
+
+    /**
+     * Multiply two transforms, writing the result into this one. Either operand may be this transform.
+     *
+     * Both operands are read through their matrices, not their components, so a stale matrix on either
+     * side produces a stale result - {@link updateMatrix} them first if you have been setting components.
+     * Both the matrix and the components of the result are left up to date.
+     *
+     * @param {Transform64} a
+     * @param {Transform64} b
+     * @returns {this}
+     */
+    multiplyTransforms(a, b) {
+        assert.equal(a.isTransform64, true, 'a.isTransform64 !== true');
+        assert.equal(b.isTransform64, true, 'b.isTransform64 !== true');
+
+        // both operands are fully read into locals before the first write, so aliasing is safe
+        m4_multiply(this, a, b);
+
+        this.updateComponents();
+
+        return this;
+    }
+
+    /**
+     * Reset to the identity transform, matrix included:
+     *      - translation: [0,0,0]
+     *      - rotation:    [0,0,0,1]
+     *      - scale:       [1,1,1]
+     */
+    makeIdentity() {
+        this.fill(0);
+
+        // matrix diagonal
+        this[0] = 1;
+        this[5] = 1;
+        this[10] = 1;
+        this[15] = 1;
+
+        this[TRANSFORM64_ROTATION_OFFSET + 3] = 1;
+
+        this[TRANSFORM64_SCALE_OFFSET] = 1;
+        this[TRANSFORM64_SCALE_OFFSET + 1] = 1;
+        this[TRANSFORM64_SCALE_OFFSET + 2] = 1;
+    }
+
+    /**
+     * 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}.
+     * @returns {boolean}
+     */
+    isIdentity() {
+        return this[TRANSFORM64_TRANSLATION_OFFSET] === 0
+            && this[TRANSFORM64_TRANSLATION_OFFSET + 1] === 0
+            && this[TRANSFORM64_TRANSLATION_OFFSET + 2] === 0
+            && this[TRANSFORM64_ROTATION_OFFSET] === 0
+            && this[TRANSFORM64_ROTATION_OFFSET + 1] === 0
+            && this[TRANSFORM64_ROTATION_OFFSET + 2] === 0
+            && this[TRANSFORM64_ROTATION_OFFSET + 3] === 1
+            && this[TRANSFORM64_SCALE_OFFSET] === 1
+            && this[TRANSFORM64_SCALE_OFFSET + 1] === 1
+            && this[TRANSFORM64_SCALE_OFFSET + 2] === 1;
+    }
+
+    /**
+     * Set this transform to match `other`, matrix included. The `other` is left unchanged.
+     * @param {Transform64} other
+     */
+    copy(other) {
+        this.set(other);
+    }
+
+    /**
+     * A new transform equal to this one
+     * @returns {Transform64}
+     */
+    clone() {
+        const r = new Transform64();
+
+        r.copy(this);
+
+        return r;
+    }
+
+    /**
+     * Strict equality across the whole transform, {@link matrix} included. Two transforms whose components
+     * match but whose matrices do not - because one of them is stale - are not equal.
+     * @param {Transform64} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return array_range_equal_strict(this, 0, other, 0, TRANSFORM64_SIZE);
+    }
+
+    /**
+     * Only the translation contributes, for speed - in most applications it is what varies the most.
+     *
+     * This is weaker than {@link equals}: transforms differing only in rotation, scale or matrix collide.
+     * Legal for a hash, but a poor key if your set varies along those axes alone.
+     * @returns {number}
+     */
+    hash() {
+        const x = this[TRANSFORM64_TRANSLATION_OFFSET];
+        const y = this[TRANSFORM64_TRANSLATION_OFFSET + 1];
+        const z = this[TRANSFORM64_TRANSLATION_OFFSET + 2];
+
+        // Same arithmetic as `computeHashFloat`, written out by hand so that this is a straight line with
+        // no calls and no loop. Per component: split into whole and fractional parts, scale the fraction
+        // into uint32 range and flip it so that tiny fractions land in the high bits, then XOR the two.
+        const x_whole = x >> 0;
+        const y_whole = y >> 0;
+        const z_whole = z >> 0;
+
+        const x_hash = (4294967295 - (((x - x_whole) * 4294967295) >>> 0)) ^ x_whole;
+        const y_hash = (4294967295 - (((y - y_whole) * 4294967295) >>> 0)) ^ y_whole;
+        const z_hash = (4294967295 - (((z - z_whole) * 4294967295) >>> 0)) ^ z_whole;
+
+        // mix, `h*31 + v` expressed as a shift so it stays in integer arithmetic
+        let hash = ((x_hash << 5) - x_hash + y_hash) | 0;
+
+        hash = ((hash << 5) - hash + z_hash) | 0;
+
+        return hash;
+    }
+
+    /**
+     * Read the components from `{translation, rotation, scale}`, each of them optional and defaulting to
+     * identity. Composes {@link matrix} from the result.
+     *
+     * NOTE: the translation is keyed `translation`, where {@link Transform} keys the same thing
+     * `position`. The two JSON forms are not interchangeable.
+     * @param json
+     */
+    fromJSON(json) {
+        const t = json.translation;
+
+        if (t !== undefined) {
+            this.setTranslation(t.x, t.y, t.z);
+        } else {
+            this.setTranslation(0, 0, 0);
+        }
+
+        const r = json.rotation;
+
+        if (r !== undefined) {
+            this.setRotation(r.x, r.y, r.z, r.w);
+        } else {
+            this.setRotation(0, 0, 0, 1);
+        }
+
+        const s = json.scale;
+
+        if (s !== undefined) {
+            this.setScale(s.x, s.y, s.z);
+        } else {
+            this.setScale(1, 1, 1);
+        }
+
+        this.updateMatrix();
+    }
+
+    /**
+     * Writes out the components only; {@link matrix} is recomposed from them on the way back in
+     * @returns {{translation:{x:number,y:number,z:number}, rotation:{x:number,y:number,z:number,w:number}, scale:{x:number,y:number,z:number}}}
+     */
+    toJSON() {
+        return {
+            translation: {
+                x: this[TRANSFORM64_TRANSLATION_OFFSET],
+                y: this[TRANSFORM64_TRANSLATION_OFFSET + 1],
+                z: this[TRANSFORM64_TRANSLATION_OFFSET + 2]
+            },
+            rotation: {
+                x: this[TRANSFORM64_ROTATION_OFFSET],
+                y: this[TRANSFORM64_ROTATION_OFFSET + 1],
+                z: this[TRANSFORM64_ROTATION_OFFSET + 2],
+                w: this[TRANSFORM64_ROTATION_OFFSET + 3]
+            },
+            scale: {
+                x: this[TRANSFORM64_SCALE_OFFSET],
+                y: this[TRANSFORM64_SCALE_OFFSET + 1],
+                z: this[TRANSFORM64_SCALE_OFFSET + 2]
+            }
+        };
+    }
+
+    /**
+     * Human-readable form, components only
+     * @returns {string}
+     */
+    toString() {
+        return `Transform64{ translation: [${this.translation_x}, ${this.translation_y}, ${this.translation_z}]`
+            + `, rotation: [${this.rotation_x}, ${this.rotation_y}, ${this.rotation_z}, ${this.rotation_w}]`
+            + `, scale: [${this.scale_x}, ${this.scale_y}, ${this.scale_z}] }`;
+    }
+
+    /**
+     * Build a transform from loose components, with {@link matrix} already composed from them
+     * @param {number} translation_x
+     * @param {number} translation_y
+     * @param {number} translation_z
+     * @param {number} rotation_x
+     * @param {number} rotation_y
+     * @param {number} rotation_z
+     * @param {number} rotation_w
+     * @param {number} scale_x
+     * @param {number} scale_y
+     * @param {number} scale_z
+     * @returns {Transform64}
+     */
+    static from(
+        translation_x, translation_y, translation_z,
+        rotation_x, rotation_y, rotation_z, rotation_w,
+        scale_x, scale_y, scale_z
+    ) {
+        const r = new Transform64();
+
+        r.setTranslation(translation_x, translation_y, translation_z);
+        r.setRotation(rotation_x, rotation_y, rotation_z, rotation_w);
+        r.setScale(scale_x, scale_y, scale_z);
+
+        r.updateMatrix();
+
+        return r;
+    }
+
+    /**
+     * Build a transform from an affine matrix, see {@link fromMatrix}
+     * @param {number[]|Float32Array|Float64Array|mat4} m4 4x4 affine matrix, column-major
+     * @returns {Transform64}
+     */
+    static fromMatrix(m4) {
+        const r = new Transform64();
+
+        r.fromMatrix(m4);
+
+        return r;
+    }
+
+    /**
+     * Build a transform from its JSON form, see {@link fromJSON}
+     * @param json
+     * @returns {Transform64}
+     */
+    static fromJSON(json) {
+        const r = new Transform64();
+
+        r.fromJSON(json);
+
+        return r;
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+Transform64.typeName = "Transform64";
+
+/**
+ * Enables a fast type check, without having to import the class separately.
+ * @readonly
+ * @type {boolean}
+ * @example
+ *  if(t.isTransform64){
+ *      // t is a Transform64, do stuff
+ *  }
+ */
+Transform64.prototype.isTransform64 = true;