@sachitv/safe-math-ts 0.1.0

package/esm/src/geometry3d/mod.d.ts

@@ -0,0 +1,6 @@
+export { frame } from './types.js';
+export type { Delta3, Dir3, FrameTag, LinearMat4, Mat4, Point3, ProjectionMat4, Quaternion, } from './types.js';
+export { addPoint3, addVec3, angleBetweenVec3, angleBetweenVec3Unsafe, crossVec3, delta3, dir3, distancePoint3, distanceVec3, dotVec3, lengthSquaredVec3, lengthVec3, lerpVec3, negVec3, normalizeVec3, normalizeVec3Unsafe, point3, projectVec3, projectVec3Unsafe, reflectVec3, reflectVec3Unsafe, scaleDir3, scaleVec3, subPoint3, subPoint3Delta3, subVec3, zeroVec3, } from './vector3.js';
+export { composeQuats, type EulerOrder, quat, quatConjugate, quatFromAxisAngle, quatFromAxisAngleUnsafe, quatFromEuler, quatFromEulerUnsafe, quatIdentity, quatInverse, quatInverseUnsafe, quatNlerp, quatNlerpUnsafe, quatNorm, quatNormalize, quatNormalizeUnsafe, quatNormSquared, quatSlerp, quatSlerpUnsafe, rotateVec3ByQuat, rotateVec3ByQuatUnsafe, } from './quaternion.js';
+export { composeMat4, createTrsMat4Cache, invertRigidMat4, invertRigidMat4Unsafe, mat4, mat4FromQuaternion, mat4FromQuaternionUnsafe, mat4FromRigidTransform, mat4FromScale, mat4FromTranslation, mat4FromTRS, mat4FromTRSUnsafe, mat4Identity, mat4LookAt, mat4LookAtUnsafe, mat4Ortho, mat4OrthoUnsafe, mat4Perspective, mat4PerspectiveUnsafe, mat4Unsafe, normalMatrixFromMat4, normalMatrixFromMat4Unsafe, projectPoint3, projectPoint3Unsafe, transformDirection3, transformPoint3, transposeMat4, } from './matrix4.js';
+//# sourceMappingURL=mod.d.ts.map

package/esm/src/geometry3d/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../src/src/geometry3d/mod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EACV,MAAM,EACN,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,IAAI,EACJ,MAAM,EACN,cAAc,EACd,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,EACT,OAAO,EACP,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,MAAM,EACN,IAAI,EACJ,cAAc,EACd,YAAY,EACZ,OAAO,EACP,iBAAiB,EACjB,UAAU,EACV,QAAQ,EACR,OAAO,EACP,aAAa,EACb,mBAAmB,EACnB,MAAM,EACN,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,SAAS,EACT,SAAS,EACT,eAAe,EACf,OAAO,EACP,QAAQ,GACT,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,YAAY,EACZ,KAAK,UAAU,EACf,IAAI,EACJ,aAAa,EACb,iBAAiB,EACjB,uBAAuB,EACvB,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,QAAQ,EACR,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,SAAS,EACT,eAAe,EACf,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,IAAI,EACJ,kBAAkB,EAClB,wBAAwB,EACxB,sBAAsB,EACtB,aAAa,EACb,mBAAmB,EACnB,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,UAAU,EACV,oBAAoB,EACpB,0BAA0B,EAC1B,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,aAAa,GACd,MAAM,cAAc,CAAC"}

package/esm/src/geometry3d/mod.js

@@ -0,0 +1,4 @@
+export { frame } from './types.js';
+export { addPoint3, addVec3, angleBetweenVec3, angleBetweenVec3Unsafe, crossVec3, delta3, dir3, distancePoint3, distanceVec3, dotVec3, lengthSquaredVec3, lengthVec3, lerpVec3, negVec3, normalizeVec3, normalizeVec3Unsafe, point3, projectVec3, projectVec3Unsafe, reflectVec3, reflectVec3Unsafe, scaleDir3, scaleVec3, subPoint3, subPoint3Delta3, subVec3, zeroVec3, } from './vector3.js';
+export { composeQuats, quat, quatConjugate, quatFromAxisAngle, quatFromAxisAngleUnsafe, quatFromEuler, quatFromEulerUnsafe, quatIdentity, quatInverse, quatInverseUnsafe, quatNlerp, quatNlerpUnsafe, quatNorm, quatNormalize, quatNormalizeUnsafe, quatNormSquared, quatSlerp, quatSlerpUnsafe, rotateVec3ByQuat, rotateVec3ByQuatUnsafe, } from './quaternion.js';
+export { composeMat4, createTrsMat4Cache, invertRigidMat4, invertRigidMat4Unsafe, mat4, mat4FromQuaternion, mat4FromQuaternionUnsafe, mat4FromRigidTransform, mat4FromScale, mat4FromTranslation, mat4FromTRS, mat4FromTRSUnsafe, mat4Identity, mat4LookAt, mat4LookAtUnsafe, mat4Ortho, mat4OrthoUnsafe, mat4Perspective, mat4PerspectiveUnsafe, mat4Unsafe, normalMatrixFromMat4, normalMatrixFromMat4Unsafe, projectPoint3, projectPoint3Unsafe, transformDirection3, transformPoint3, transposeMat4, } from './matrix4.js';

package/esm/src/geometry3d/quaternion.d.ts

@@ -0,0 +1,221 @@
+import { type NoInfer, type UnitExpr } from '../units.js';
+import type { Delta3, Dir3, FrameTag, Quaternion } from './types.js';
+/** Axis composition order for Euler rotations. */
+export type EulerOrder = 'XYZ' | 'XZY' | 'YXZ' | 'YZX' | 'ZXY' | 'ZYX';
+/**
+ * Constructs a frame-aware quaternion.
+ *
+ * `toFrameTag` and `fromFrameTag` are required to enforce explicit frame declaration.
+ *
+ * @param toFrameTag Destination frame token.
+ * @param fromFrameTag Source frame token.
+ * @param x Quaternion x component.
+ * @param y Quaternion y component.
+ * @param z Quaternion z component.
+ * @param w Quaternion w component.
+ * @returns Quaternion in `<ToFrame, FromFrame>` order.
+ */
+export declare const quat: <ToFrame extends string, FromFrame extends string>(toFrameTag: FrameTag<ToFrame>, fromFrameTag: FrameTag<FromFrame>, x: number, y: number, z: number, w: number) => Quaternion<ToFrame, FromFrame>;
+/**
+ * Returns identity quaternion for a frame.
+ *
+ * @param frameTag Frame token.
+ * @returns Identity rotation for the frame.
+ */
+export declare const quatIdentity: <Frame extends string>(frameTag: FrameTag<Frame>) => Quaternion<Frame, Frame>;
+/**
+ * Computes quaternion conjugate.
+ *
+ * @param value Input quaternion.
+ * @returns Conjugated quaternion with swapped frame direction.
+ */
+export declare const quatConjugate: <ToFrame extends string, FromFrame extends string>(value: Quaternion<ToFrame, FromFrame>) => Quaternion<FromFrame, ToFrame>;
+/**
+ * Computes squared quaternion norm.
+ *
+ * @param value Input quaternion.
+ * @returns Squared norm.
+ */
+export declare const quatNormSquared: <ToFrame extends string, FromFrame extends string>(value: Quaternion<ToFrame, FromFrame>) => number;
+/**
+ * Computes quaternion norm.
+ *
+ * @param value Input quaternion.
+ * @returns Euclidean norm.
+ */
+export declare const quatNorm: <ToFrame extends string, FromFrame extends string>(value: Quaternion<ToFrame, FromFrame>) => number;
+/**
+ * Normalizes quaternion length to 1.
+ *
+ * Unsafe variant: performs no zero-length guard.
+ * Degenerate inputs can yield `NaN`/`Infinity`.
+ *
+ * @param value Quaternion to normalize.
+ * @returns Unit quaternion.
+ */
+export declare const quatNormalizeUnsafe: <ToFrame extends string, FromFrame extends string>(value: Quaternion<ToFrame, FromFrame>) => Quaternion<ToFrame, FromFrame>;
+/**
+ * Normalizes quaternion length to 1.
+ *
+ * Throws when quaternion norm is zero.
+ *
+ * @param value Quaternion to normalize.
+ * @returns Unit quaternion.
+ * @throws {Error} When the quaternion is near zero length.
+ */
+export declare const quatNormalize: <ToFrame extends string, FromFrame extends string>(value: Quaternion<ToFrame, FromFrame>) => Quaternion<ToFrame, FromFrame>;
+/**
+ * Computes quaternion inverse.
+ *
+ * Unsafe variant: performs no zero-length guard.
+ * Degenerate inputs can yield `NaN`/`Infinity`.
+ *
+ * @param value Quaternion to invert.
+ * @returns Inverse quaternion in swapped frame direction.
+ */
+export declare const quatInverseUnsafe: <ToFrame extends string, FromFrame extends string>(value: Quaternion<ToFrame, FromFrame>) => Quaternion<FromFrame, ToFrame>;
+/**
+ * Computes quaternion inverse.
+ *
+ * Throws when quaternion norm is zero.
+ *
+ * @param value Quaternion to invert.
+ * @returns Inverse quaternion in swapped frame direction.
+ * @throws {Error} When the quaternion is near zero length.
+ */
+export declare const quatInverse: <ToFrame extends string, FromFrame extends string>(value: Quaternion<ToFrame, FromFrame>) => Quaternion<FromFrame, ToFrame>;
+/**
+ * Composes two frame-compatible quaternions in chain order.
+ *
+ * `composeQuats(outer, inner)` returns `outer * inner`, so `inner` is applied
+ * first.
+ *
+ * @param outer Outer rotation.
+ * @param inner Inner rotation.
+ * @returns Composed rotation `outer * inner`.
+ */
+export declare const composeQuats: <ToFrame extends string, ViaFrame extends string, FromFrame extends string>(outer: Quaternion<ToFrame, ViaFrame>, inner: Quaternion<NoInfer<ViaFrame>, FromFrame>) => Quaternion<ToFrame, FromFrame>;
+/**
+ * Rotates a displacement vector from `FromFrame` into `ToFrame`.
+ *
+ * @param rotation Quaternion mapping `FromFrame -> ToFrame`.
+ * @param value Displacement to rotate.
+ * @returns Rotated displacement in `ToFrame`.
+ */
+export declare function rotateVec3ByQuatUnsafe<Unit extends UnitExpr, ToFrame extends string, FromFrame extends string>(rotation: Quaternion<ToFrame, FromFrame>, value: Delta3<Unit, NoInfer<FromFrame>>): Delta3<Unit, ToFrame>;
+/**
+ * Rotates a direction vector from `FromFrame` into `ToFrame`.
+ *
+ * @param rotation Quaternion mapping `FromFrame -> ToFrame`.
+ * @param value Direction to rotate.
+ * @returns Rotated direction in `ToFrame`.
+ */
+export declare function rotateVec3ByQuatUnsafe<ToFrame extends string, FromFrame extends string>(rotation: Quaternion<ToFrame, FromFrame>, value: Dir3<NoInfer<FromFrame>>): Dir3<ToFrame>;
+/**
+ * Rotates a displacement vector from `FromFrame` into `ToFrame`.
+ *
+ * @param rotation Quaternion mapping `FromFrame -> ToFrame`.
+ * @param value Displacement to rotate.
+ * @returns Rotated displacement in `ToFrame`.
+ */
+export declare function rotateVec3ByQuat<Unit extends UnitExpr, ToFrame extends string, FromFrame extends string>(rotation: Quaternion<ToFrame, FromFrame>, value: Delta3<Unit, NoInfer<FromFrame>>): Delta3<Unit, ToFrame>;
+/**
+ * Rotates a direction vector from `FromFrame` into `ToFrame`.
+ *
+ * @param rotation Quaternion mapping `FromFrame -> ToFrame`.
+ * @param value Direction to rotate.
+ * @returns Rotated direction in `ToFrame`.
+ */
+export declare function rotateVec3ByQuat<ToFrame extends string, FromFrame extends string>(rotation: Quaternion<ToFrame, FromFrame>, value: Dir3<NoInfer<FromFrame>>): Dir3<ToFrame>;
+/**
+ * Creates a quaternion from axis-angle representation.
+ *
+ * Axis is normalized internally.
+ * Unsafe variant: performs no zero-length guard for `axis`.
+ *
+ * @param frameTag Frame token.
+ * @param axis Rotation axis.
+ * @param angleRadians Rotation angle in radians.
+ * @returns Quaternion in `<Frame, Frame>` order.
+ */
+export declare const quatFromAxisAngleUnsafe: <Frame extends string>(frameTag: FrameTag<Frame>, axis: Dir3<Frame>, angleRadians: number) => Quaternion<Frame, Frame>;
+/**
+ * Creates a quaternion from axis-angle representation.
+ *
+ * Axis is normalized internally.
+ * Throws when axis has zero length.
+ *
+ * @param frameTag Frame token.
+ * @param axis Rotation axis.
+ * @param angleRadians Rotation angle in radians.
+ * @returns Quaternion in `<Frame, Frame>` order.
+ * @throws {Error} When `axis` is near zero length.
+ */
+export declare const quatFromAxisAngle: <Frame extends string>(frameTag: FrameTag<Frame>, axis: Dir3<Frame>, angleRadians: number) => Quaternion<Frame, Frame>;
+/**
+ * Builds a frame-local quaternion from Euler angles and explicit axis order.
+ *
+ * Rotations are composed in intrinsic order: the `order` string describes
+ * which axis is applied first (leftmost) through last (rightmost). For example
+ * `'ZYX'` applies Z first, then Y, then X.
+ *
+ * @param frameTag Frame token.
+ * @param xRadians Rotation around X axis in radians.
+ * @param yRadians Rotation around Y axis in radians.
+ * @param zRadians Rotation around Z axis in radians.
+ * @param order Euler axis composition order.
+ * @returns Quaternion in `<Frame, Frame>` order.
+ */
+export declare const quatFromEulerUnsafe: <Frame extends string>(frameTag: FrameTag<Frame>, xRadians: number, yRadians: number, zRadians: number, order?: EulerOrder) => Quaternion<Frame, Frame>;
+/**
+ * Builds a frame-local quaternion from Euler angles and explicit axis order.
+ *
+ * Rotations are composed in intrinsic order: the `order` string describes
+ * which axis is applied first (leftmost) through last (rightmost). For example
+ * `'ZYX'` applies Z first, then Y, then X.
+ *
+ * @param frameTag Frame token.
+ * @param xRadians Rotation around X axis in radians.
+ * @param yRadians Rotation around Y axis in radians.
+ * @param zRadians Rotation around Z axis in radians.
+ * @param order Euler axis composition order.
+ * @returns Normalized quaternion in `<Frame, Frame>` order.
+ */
+export declare const quatFromEuler: <Frame extends string>(frameTag: FrameTag<Frame>, xRadians: number, yRadians: number, zRadians: number, order?: EulerOrder) => Quaternion<Frame, Frame>;
+/**
+ * Normalized linear interpolation with shortest-path hemisphere selection.
+ *
+ * @param start Start quaternion.
+ * @param end End quaternion.
+ * @param t Interpolation parameter.
+ * @returns Interpolated normalized quaternion.
+ */
+export declare const quatNlerpUnsafe: <ToFrame extends string, FromFrame extends string>(start: Quaternion<ToFrame, FromFrame>, end: Quaternion<NoInfer<ToFrame>, NoInfer<FromFrame>>, t: number) => Quaternion<ToFrame, FromFrame>;
+/**
+ * Normalized linear interpolation with shortest-path hemisphere selection.
+ *
+ * @param start Start quaternion.
+ * @param end End quaternion.
+ * @param t Interpolation parameter.
+ * @returns Interpolated normalized quaternion.
+ */
+export declare const quatNlerp: <ToFrame extends string, FromFrame extends string>(start: Quaternion<ToFrame, FromFrame>, end: Quaternion<NoInfer<ToFrame>, NoInfer<FromFrame>>, t: number) => Quaternion<ToFrame, FromFrame>;
+/**
+ * Spherical interpolation with shortest-path hemisphere selection.
+ *
+ * @param start Start quaternion.
+ * @param end End quaternion.
+ * @param t Interpolation parameter.
+ * @returns Interpolated normalized quaternion.
+ */
+export declare const quatSlerpUnsafe: <ToFrame extends string, FromFrame extends string>(start: Quaternion<ToFrame, FromFrame>, end: Quaternion<NoInfer<ToFrame>, NoInfer<FromFrame>>, t: number) => Quaternion<ToFrame, FromFrame>;
+/**
+ * Spherical interpolation with shortest-path hemisphere selection.
+ *
+ * @param start Start quaternion.
+ * @param end End quaternion.
+ * @param t Interpolation parameter.
+ * @returns Interpolated normalized quaternion.
+ */
+export declare const quatSlerp: <ToFrame extends string, FromFrame extends string>(start: Quaternion<ToFrame, FromFrame>, end: Quaternion<NoInfer<ToFrame>, NoInfer<FromFrame>>, t: number) => Quaternion<ToFrame, FromFrame>;
+//# sourceMappingURL=quaternion.d.ts.map

package/esm/src/geometry3d/quaternion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quaternion.d.ts","sourceRoot":"","sources":["../../../src/src/geometry3d/quaternion.ts"],"names":[],"mappings":"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"}

package/esm/src/geometry3d/quaternion.js

@@ -0,0 +1,419 @@
+import { normalizeVec3, normalizeVec3Unsafe } from './vector3.js';
+const NEAR_ZERO = 1e-14;
+/**
+ * Casts a raw number into a branded quantity.
+ *
+ * @param value Raw numeric scalar.
+ * @returns Branded quantity.
+ */
+const asQuantity = (value) => value;
+/**
+ * Casts xyzw components to a branded quaternion.
+ *
+ * @param x Quaternion x component.
+ * @param y Quaternion y component.
+ * @param z Quaternion z component.
+ * @param w Quaternion w component.
+ * @returns Branded quaternion.
+ */
+const asQuaternion = (x, y, z, w) => [x, y, z, w];
+/**
+ * Constructs a frame-aware quaternion.
+ *
+ * `toFrameTag` and `fromFrameTag` are required to enforce explicit frame declaration.
+ *
+ * @param toFrameTag Destination frame token.
+ * @param fromFrameTag Source frame token.
+ * @param x Quaternion x component.
+ * @param y Quaternion y component.
+ * @param z Quaternion z component.
+ * @param w Quaternion w component.
+ * @returns Quaternion in `<ToFrame, FromFrame>` order.
+ */
+export const quat = (toFrameTag, fromFrameTag, x, y, z, w) => {
+    void toFrameTag;
+    void fromFrameTag;
+    return asQuaternion(x, y, z, w);
+};
+/**
+ * Returns identity quaternion for a frame.
+ *
+ * @param frameTag Frame token.
+ * @returns Identity rotation for the frame.
+ */
+export const quatIdentity = (frameTag) => {
+    void frameTag;
+    return asQuaternion(0, 0, 0, 1);
+};
+/**
+ * Computes quaternion conjugate.
+ *
+ * @param value Input quaternion.
+ * @returns Conjugated quaternion with swapped frame direction.
+ */
+export const quatConjugate = (value) => asQuaternion(-value[0], -value[1], -value[2], value[3]);
+/**
+ * Computes squared quaternion norm.
+ *
+ * @param value Input quaternion.
+ * @returns Squared norm.
+ */
+export const quatNormSquared = (value) => value[0] * value[0] +
+    value[1] * value[1] +
+    value[2] * value[2] +
+    value[3] * value[3];
+/**
+ * Computes quaternion norm.
+ *
+ * @param value Input quaternion.
+ * @returns Euclidean norm.
+ */
+export const quatNorm = (value) => Math.sqrt(quatNormSquared(value));
+/**
+ * Normalizes quaternion length to 1.
+ *
+ * Unsafe variant: performs no zero-length guard.
+ * Degenerate inputs can yield `NaN`/`Infinity`.
+ *
+ * @param value Quaternion to normalize.
+ * @returns Unit quaternion.
+ */
+export const quatNormalizeUnsafe = (value) => {
+    const norm = quatNorm(value);
+    return asQuaternion(value[0] / norm, value[1] / norm, value[2] / norm, value[3] / norm);
+};
+/**
+ * Normalizes quaternion length to 1.
+ *
+ * Throws when quaternion norm is zero.
+ *
+ * @param value Quaternion to normalize.
+ * @returns Unit quaternion.
+ * @throws {Error} When the quaternion is near zero length.
+ */
+export const quatNormalize = (value) => {
+    const norm = quatNorm(value);
+    if (norm <= NEAR_ZERO) {
+        throw new Error('Cannot normalize a zero-length quaternion');
+    }
+    return quatNormalizeUnsafe(value);
+};
+/**
+ * Computes quaternion inverse.
+ *
+ * Unsafe variant: performs no zero-length guard.
+ * Degenerate inputs can yield `NaN`/`Infinity`.
+ *
+ * @param value Quaternion to invert.
+ * @returns Inverse quaternion in swapped frame direction.
+ */
+export const quatInverseUnsafe = (value) => {
+    const normSquared = quatNormSquared(value);
+    const conjugate = quatConjugate(value);
+    return asQuaternion(conjugate[0] / normSquared, conjugate[1] / normSquared, conjugate[2] / normSquared, conjugate[3] / normSquared);
+};
+/**
+ * Computes quaternion inverse.
+ *
+ * Throws when quaternion norm is zero.
+ *
+ * @param value Quaternion to invert.
+ * @returns Inverse quaternion in swapped frame direction.
+ * @throws {Error} When the quaternion is near zero length.
+ */
+export const quatInverse = (value) => {
+    const normSquared = quatNormSquared(value);
+    if (normSquared <= NEAR_ZERO * NEAR_ZERO) {
+        throw new Error('Cannot invert a zero-length quaternion');
+    }
+    return quatInverseUnsafe(value);
+};
+/**
+ * Composes two frame-compatible quaternions in chain order.
+ *
+ * `composeQuats(outer, inner)` returns `outer * inner`, so `inner` is applied
+ * first.
+ *
+ * @param outer Outer rotation.
+ * @param inner Inner rotation.
+ * @returns Composed rotation `outer * inner`.
+ */
+export const composeQuats = (outer, inner) => {
+    const [x1, y1, z1, w1] = inner;
+    const [x2, y2, z2, w2] = outer;
+    const x = w2 * x1 +
+        x2 * w1 +
+        y2 * z1 -
+        z2 * y1;
+    const y = w2 * y1 -
+        x2 * z1 +
+        y2 * w1 +
+        z2 * x1;
+    const z = w2 * z1 +
+        x2 * y1 -
+        y2 * x1 +
+        z2 * w1;
+    const w = w2 * w1 -
+        x2 * x1 -
+        y2 * y1 -
+        z2 * z1;
+    return asQuaternion(x, y, z, w);
+};
+export function rotateVec3ByQuatUnsafe(rotation, value) {
+    const [qx, qy, qz, qw] = quatNormalizeUnsafe(rotation);
+    const [vx, vy, vz] = value;
+    // Quaternion-vector rotation via optimized form:
+    // t = 2 * cross(q.xyz, v), v' = v + qw * t + cross(q.xyz, t)
+    const tx = 2 * (qy * vz -
+        qz * vy);
+    const ty = 2 * (qz * vx -
+        qx * vz);
+    const tz = 2 * (qx * vy -
+        qy * vx);
+    const rotatedX = vx +
+        qw * tx +
+        (qy * tz - qz * ty);
+    const rotatedY = vy +
+        qw * ty +
+        (qz * tx - qx * tz);
+    const rotatedZ = vz +
+        qw * tz +
+        (qx * ty - qy * tx);
+    return [
+        asQuantity(rotatedX),
+        asQuantity(rotatedY),
+        asQuantity(rotatedZ),
+    ];
+}
+export function rotateVec3ByQuat(rotation, value) {
+    quatNormalize(rotation);
+    return rotateVec3ByQuatUnsafe(rotation, value);
+}
+/**
+ * Creates a quaternion from axis-angle representation.
+ *
+ * Axis is normalized internally.
+ * Unsafe variant: performs no zero-length guard for `axis`.
+ *
+ * @param frameTag Frame token.
+ * @param axis Rotation axis.
+ * @param angleRadians Rotation angle in radians.
+ * @returns Quaternion in `<Frame, Frame>` order.
+ */
+export const quatFromAxisAngleUnsafe = (frameTag, axis, angleRadians) => {
+    void frameTag;
+    const normalizedAxis = normalizeVec3Unsafe(axis);
+    const halfAngle = angleRadians * 0.5;
+    const sinHalfAngle = Math.sin(halfAngle);
+    const cosHalfAngle = Math.cos(halfAngle);
+    return asQuaternion(normalizedAxis[0] * sinHalfAngle, normalizedAxis[1] * sinHalfAngle, normalizedAxis[2] * sinHalfAngle, cosHalfAngle);
+};
+/**
+ * Creates a quaternion from axis-angle representation.
+ *
+ * Axis is normalized internally.
+ * Throws when axis has zero length.
+ *
+ * @param frameTag Frame token.
+ * @param axis Rotation axis.
+ * @param angleRadians Rotation angle in radians.
+ * @returns Quaternion in `<Frame, Frame>` order.
+ * @throws {Error} When `axis` is near zero length.
+ */
+export const quatFromAxisAngle = (frameTag, axis, angleRadians) => {
+    normalizeVec3(axis);
+    return quatFromAxisAngleUnsafe(frameTag, axis, angleRadians);
+};
+/**
+ * Builds a frame-local quaternion from Euler angles and explicit axis order.
+ *
+ * Rotations are composed in intrinsic order: the `order` string describes
+ * which axis is applied first (leftmost) through last (rightmost). For example
+ * `'ZYX'` applies Z first, then Y, then X.
+ *
+ * @param frameTag Frame token.
+ * @param xRadians Rotation around X axis in radians.
+ * @param yRadians Rotation around Y axis in radians.
+ * @param zRadians Rotation around Z axis in radians.
+ * @param order Euler axis composition order.
+ * @returns Quaternion in `<Frame, Frame>` order.
+ */
+export const quatFromEulerUnsafe = (frameTag, xRadians, yRadians, zRadians, order = 'ZYX') => {
+    const makeAxisQuat = (axis) => {
+        const angle = axis === 'X' ? xRadians : axis === 'Y' ? yRadians : zRadians;
+        const half = angle * 0.5;
+        const sinHalf = Math.sin(half);
+        const cosHalf = Math.cos(half);
+        if (axis === 'X') {
+            return asQuaternion(sinHalf, 0, 0, cosHalf);
+        }
+        if (axis === 'Y') {
+            return asQuaternion(0, sinHalf, 0, cosHalf);
+        }
+        return asQuaternion(0, 0, sinHalf, cosHalf);
+    };
+    let quat_result = quatIdentity(frameTag);
+    for (let index = 0; index < order.length; index += 1) {
+        const axis = order[index];
+        quat_result = composeQuats(makeAxisQuat(axis), quat_result);
+    }
+    return quatNormalizeUnsafe(quat_result);
+};
+/**
+ * Builds a frame-local quaternion from Euler angles and explicit axis order.
+ *
+ * Rotations are composed in intrinsic order: the `order` string describes
+ * which axis is applied first (leftmost) through last (rightmost). For example
+ * `'ZYX'` applies Z first, then Y, then X.
+ *
+ * @param frameTag Frame token.
+ * @param xRadians Rotation around X axis in radians.
+ * @param yRadians Rotation around Y axis in radians.
+ * @param zRadians Rotation around Z axis in radians.
+ * @param order Euler axis composition order.
+ * @returns Normalized quaternion in `<Frame, Frame>` order.
+ */
+export const quatFromEuler = (frameTag, xRadians, yRadians, zRadians, order = 'ZYX') => {
+    const quat_result = quatFromEulerUnsafe(frameTag, xRadians, yRadians, zRadians, order);
+    return quatNormalize(quat_result);
+};
+/**
+ * Normalized linear interpolation with shortest-path hemisphere selection.
+ *
+ * @param start Start quaternion.
+ * @param end End quaternion.
+ * @param t Interpolation parameter.
+ * @returns Interpolated normalized quaternion.
+ */
+export const quatNlerpUnsafe = (start, end, t) => {
+    let endX = end[0];
+    let endY = end[1];
+    let endZ = end[2];
+    let endW = end[3];
+    const dot = start[0] * endX +
+        start[1] * endY +
+        start[2] * endZ +
+        start[3] * endW;
+    if (dot < 0) {
+        endX = -endX;
+        endY = -endY;
+        endZ = -endZ;
+        endW = -endW;
+    }
+    const inverseT = 1 - t;
+    return quatNormalizeUnsafe(asQuaternion(start[0] * inverseT +
+        endX * t, start[1] * inverseT +
+        endY * t, start[2] * inverseT +
+        endZ * t, start[3] * inverseT +
+        endW * t));
+};
+/**
+ * Normalized linear interpolation with shortest-path hemisphere selection.
+ *
+ * @param start Start quaternion.
+ * @param end End quaternion.
+ * @param t Interpolation parameter.
+ * @returns Interpolated normalized quaternion.
+ */
+export const quatNlerp = (start, end, t) => {
+    let endX = end[0];
+    let endY = end[1];
+    let endZ = end[2];
+    let endW = end[3];
+    const dot = start[0] * endX +
+        start[1] * endY +
+        start[2] * endZ +
+        start[3] * endW;
+    if (dot < 0) {
+        endX = -endX;
+        endY = -endY;
+        endZ = -endZ;
+        endW = -endW;
+    }
+    const inverseT = 1 - t;
+    const quat_blend = asQuaternion(start[0] * inverseT +
+        endX * t, start[1] * inverseT +
+        endY * t, start[2] * inverseT +
+        endZ * t, start[3] * inverseT +
+        endW * t);
+    return quatNormalize(quat_blend);
+};
+/**
+ * Spherical interpolation with shortest-path hemisphere selection.
+ *
+ * @param start Start quaternion.
+ * @param end End quaternion.
+ * @param t Interpolation parameter.
+ * @returns Interpolated normalized quaternion.
+ */
+export const quatSlerpUnsafe = (start, end, t) => {
+    let endX = end[0];
+    let endY = end[1];
+    let endZ = end[2];
+    let endW = end[3];
+    let cosine = start[0] * endX +
+        start[1] * endY +
+        start[2] * endZ +
+        start[3] * endW;
+    if (cosine < 0) {
+        cosine = -cosine;
+        endX = -endX;
+        endY = -endY;
+        endZ = -endZ;
+        endW = -endW;
+    }
+    if (cosine > 0.9995) {
+        return quatNlerpUnsafe(start, asQuaternion(endX, endY, endZ, endW), t);
+    }
+    const theta0 = Math.acos(Math.max(-1, Math.min(1, cosine)));
+    const sinTheta0 = Math.sin(theta0);
+    const theta = theta0 * t;
+    const sinTheta = Math.sin(theta);
+    const s0 = Math.sin(theta0 - theta) / sinTheta0;
+    const s1 = sinTheta / sinTheta0;
+    return quatNormalizeUnsafe(asQuaternion(s0 * start[0] +
+        s1 * endX, s0 * start[1] +
+        s1 * endY, s0 * start[2] +
+        s1 * endZ, s0 * start[3] +
+        s1 * endW));
+};
+/**
+ * Spherical interpolation with shortest-path hemisphere selection.
+ *
+ * @param start Start quaternion.
+ * @param end End quaternion.
+ * @param t Interpolation parameter.
+ * @returns Interpolated normalized quaternion.
+ */
+export const quatSlerp = (start, end, t) => {
+    let endX = end[0];
+    let endY = end[1];
+    let endZ = end[2];
+    let endW = end[3];
+    let cosine = start[0] * endX +
+        start[1] * endY +
+        start[2] * endZ +
+        start[3] * endW;
+    if (cosine < 0) {
+        cosine = -cosine;
+        endX = -endX;
+        endY = -endY;
+        endZ = -endZ;
+        endW = -endW;
+    }
+    if (cosine > 0.9995) {
+        return quatNlerp(start, asQuaternion(endX, endY, endZ, endW), t);
+    }
+    const theta0 = Math.acos(Math.max(-1, Math.min(1, cosine)));
+    const sinTheta0 = Math.sin(theta0);
+    const theta = theta0 * t;
+    const sinTheta = Math.sin(theta);
+    const s0 = Math.sin(theta0 - theta) / sinTheta0;
+    const s1 = sinTheta / sinTheta0;
+    const quat_blend = asQuaternion(s0 * start[0] +
+        s1 * endX, s0 * start[1] +
+        s1 * endY, s0 * start[2] +
+        s1 * endZ, s0 * start[3] +
+        s1 * endW);
+    return quatNormalize(quat_blend);
+};