qarl 1.2.5 → 1.3.1

package/dist/index.js

@@ -0,0 +1 @@
+var R=Object.create;var L=Object.defineProperty;var j=Object.getOwnPropertyDescriptor;var V=Object.getOwnPropertyNames;var B=Object.getPrototypeOf,G=Object.prototype.hasOwnProperty;var q=(t,s,e)=>s in t?L(t,s,{enumerable:!0,configurable:!0,writable:!0,value:e}):t[s]=e;var N=(t,s)=>()=>(s||t((s={exports:{}}).exports,s),s.exports);var Y=(t,s,e,i)=>{if(s&&typeof s=="object"||typeof s=="function")for(let r of V(s))!G.call(t,r)&&r!==e&&L(t,r,{get:()=>s[r],enumerable:!(i=j(s,r))||i.enumerable});return t};var z=(t,s,e)=>(e=t!=null?R(B(t)):{},Y(s||!t||!t.__esModule?L(e,"default",{value:t,enumerable:!0}):e,t));var y=(t,s,e)=>(q(t,typeof s!="symbol"?s+"":s,e),e);var k=N(($,b)=>{"use strict";var K=Object.prototype.hasOwnProperty,g="~";function T(){}Object.create&&(T.prototype=Object.create(null),new T().__proto__||(g=!1));function H(t,s,e){this.fn=t,this.context=s,this.once=e||!1}function F(t,s,e,i,r){if(typeof e!="function")throw new TypeError("The listener must be a function");var n=new H(e,i||t,r),a=g?g+s:s;return t._events[a]?t._events[a].fn?t._events[a]=[t._events[a],n]:t._events[a].push(n):(t._events[a]=n,t._eventsCount++),t}function D(t,s){--t._eventsCount===0?t._events=new T:delete t._events[s]}function f(){this._events=new T,this._eventsCount=0}f.prototype.eventNames=function(){var s=[],e,i;if(this._eventsCount===0)return s;for(i in e=this._events)K.call(e,i)&&s.push(g?i.slice(1):i);return Object.getOwnPropertySymbols?s.concat(Object.getOwnPropertySymbols(e)):s};f.prototype.listeners=function(s){var e=g?g+s:s,i=this._events[e];if(!i)return[];if(i.fn)return[i.fn];for(var r=0,n=i.length,a=new Array(n);r<n;r++)a[r]=i[r].fn;return a};f.prototype.listenerCount=function(s){var e=g?g+s:s,i=this._events[e];return i?i.fn?1:i.length:0};f.prototype.emit=function(s,e,i,r,n,a){var p=g?g+s:s;if(!this._events[p])return!1;var o=this._events[p],l=arguments.length,m,h;if(o.fn){switch(o.once&&this.removeListener(s,o.fn,void 0,!0),l){case 1:return o.fn.call(o.context),!0;case 2:return o.fn.call(o.context,e),!0;case 3:return o.fn.call(o.context,e,i),!0;case 4:return o.fn.call(o.context,e,i,r),!0;case 5:return o.fn.call(o.context,e,i,r,n),!0;case 6:return o.fn.call(o.context,e,i,r,n,a),!0}for(h=1,m=new Array(l-1);h<l;h++)m[h-1]=arguments[h];o.fn.apply(o.context,m)}else{var I=o.length,c;for(h=0;h<I;h++)switch(o[h].once&&this.removeListener(s,o[h].fn,void 0,!0),l){case 1:o[h].fn.call(o[h].context);break;case 2:o[h].fn.call(o[h].context,e);break;case 3:o[h].fn.call(o[h].context,e,i);break;case 4:o[h].fn.call(o[h].context,e,i,r);break;default:if(!m)for(c=1,m=new Array(l-1);c<l;c++)m[c-1]=arguments[c];o[h].fn.apply(o[h].context,m)}}return!0};f.prototype.on=function(s,e,i){return F(this,s,e,i,!1)};f.prototype.once=function(s,e,i){return F(this,s,e,i,!0)};f.prototype.removeListener=function(s,e,i,r){var n=g?g+s:s;if(!this._events[n])return this;if(!e)return D(this,n),this;var a=this._events[n];if(a.fn)a.fn===e&&(!r||a.once)&&(!i||a.context===i)&&D(this,n);else{for(var p=0,o=[],l=a.length;p<l;p++)(a[p].fn!==e||r&&!a[p].once||i&&a[p].context!==i)&&o.push(a[p]);o.length?this._events[n]=o.length===1?o[0]:o:D(this,n)}return this};f.prototype.removeAllListeners=function(s){var e;return s?(e=g?g+s:s,this._events[e]&&D(this,e)):(this._events=new T,this._eventsCount=0),this};f.prototype.off=f.prototype.removeListener;f.prototype.addListener=f.prototype.on;f.prefixed=g;f.EventEmitter=f;typeof b<"u"&&(b.exports=f)});var U=z(k(),1);var Q=U.default;var C={processors:[],time:0,loop:!1,mode:null,delay:0,repeat:0,target:null,easing:t=>t,reversed:!1,repeatDelay:0,autoApplyProcessors:!0};var _={PLAY:"play",STOP:"stop",BEGIN:"begin",UPDATE:"update",REPEAT:"repeat",COMPLETE:"complete"};var x=Math.PI*2,v=Math.pow,E={reverse:t=>1-t,linear:t=>t,yoyo:t=>1-Math.abs(1-t*2),inQuad:t=>v(t,2),outQuad:t=>1-(1-t)*(1-t),inOutQuad:t=>t<.5?2*t*t:-1+(4-2*t)*t,inCubic:t=>v(t,3),outCubic:t=>--t*t*t+1,inOutCubic:t=>t<.5?4*v(t,3):(t-1)*(2*t-2)*(2*t-2)+1,inQuart:t=>v(t,4),outQuart:t=>1- --t*v(t,3),inOutQuart:t=>t<.5?8*v(t,4):1-8*--t*t*t*t,inQuint:t=>v(t,5),outQuint:t=>1+--t*v(t,4),inOutQuint:t=>t<.5?16*v(t,5):1+16*--t*t*t*t*t,inSine:t=>1-Math.cos(t*Math.PI/2),outSine:t=>Math.sin(t*Math.PI/2),inOutSine:t=>-(Math.cos(Math.PI*t)-1)/2,inBack:(t,s=1.70158)=>t*t*((s+1)*t-s),outBack:(t,s=1.70158)=>(t-=1)*t*((s+1)*t+s)+1,inOutBack:(t,s=1.70158)=>(t*=2)<1?.5*(t*t*((s*1.525+1)*t-s*1.525)):.5*((t-=2)*t*((s*1.525+1)*t+s*1.525)+2),inExpo:t=>t===0?0:Math.pow(2,10*(t-1)),outExpo:t=>t===1?1:1-Math.pow(2,-10*t),inOutExpo:t=>t===0?0:t===1?1:t<.5?.5*Math.pow(2,20*t-10):1-.5*Math.pow(2,-20*t+10),inElastic:(t,s=1,e=.5)=>t===0?0:t===1?1:-s*Math.pow(2,10*(t-1))*Math.sin((t-1-e/x*Math.asin(1/s))*x/e),outElastic:(t,s=1,e=.5)=>t===0?0:t===1?1:s*Math.pow(2,-10*t)*Math.sin((t-e/x*Math.asin(1/s))*x/e)+1,inOutElastic:(t,s=1,e=.5)=>t===0?0:t===1?1:t<.5?-.5*s*Math.pow(2,20*t-10)*Math.sin((20*t-11.125)*x/e):.5*s*Math.pow(2,-20*t+10)*Math.sin((20*t-11.125)*x/e)+1};var O={pingPong:function(t){return t<=.5?this._easing(t*2):1-this._easing((t-.5)*2)},yoyo:function(t){return this._easing(E.yoyo(t))},bounce:function(t){return E.yoyo(this._easing(t))}};var J=0,d=class d extends Q{constructor(e={},i){super();y(this,"_reversedEasing",e=>this.settings.easing(1-e));y(this,"_stepDelay",e=>{this.remainingDelay-=e,this.lastDeltaTime=e,!(this.remainingDelay>0)&&(this.emit(_.BEGIN),this.step=this._stepTime,this.step(Math.abs(this.remainingDelay)),this.remainingDelay=this.settings.delay)});y(this,"_stepTime",(e=0)=>{this.elapsedTime+=e,this.lastDeltaTime=e,this.elapsedTime>=this.time?(this.elapsedTime=this.time,this._update(),this._complete()):this._update()});this.index=J++,this.overrides=e,this.settings={},this.reset(e),i&&(this.manager=i),this.lastDeltaTime=0}on(...e){return super.on(...e),this}off(...e){return super.off(...e),this}once(...e){return super.once(...e),this}onComplete(...e){return super.on(_.COMPLETE,...e),this}onUpdate(...e){return super.on(_.UPDATE,...e),this}onceComplete(...e){return super.once(_.COMPLETE,...e),this}static _noop(){}static mergeConfigs(e,i){e!==i&&Object.keys(i).forEach(r=>{typeof i[r]=="object"&&i[r]!==null?((!e[r]||typeof e[r]!="object")&&(e[r]={}),d.mergeConfigs(e[r],i[r])):e[r]=i[r]})}static lerp(e,i,r){return e+(i-e)*r}_processState(){this.step=d._noop,this.progress=0,this.easeValue=0,this.elapsedTime=0,this.promise=null,this._resolve=d._noop,this._refreshDynamicProps()}_refreshDynamicProps(){this.applyProcessors(this.settings);let{target:e,time:i,repeat:r,loop:n,reversed:a,delay:p}=this.settings;this.target=e,this.time=Math.max(i,0),this.repeat=r>0?r:n?1/0:0,this.reversed=a,this.remainingDelay=p,this._processEasing()}_processEasing(){let e=typeof this.settings.easing=="string"?E[this.settings.easing]||E.linear:this.settings.easing;this._easing=this.reversed?this._reversedEasing:e;let i=typeof this.settings.mode=="string"?O[this.settings.mode]:this.settings.mode;this._calculateEasing=i?i.bind(this):this._easing}_update(){this.progress=this.elapsedTime/this.time,this.easeValue=this._calculateEasing(this.progress),this.emit(_.UPDATE,this)}_complete(){this.repeat-- >0?this._repeat():(this._resolve(),this.stop(!1),this.emit(_.COMPLETE))}_repeat(e=!0){this.remainingDelay=this.settings.repeatDelay,this.elapsedTime=0,this.remainingDelay>0&&(this.step=this._stepDelay),this._update(),e&&this.emit(_.REPEAT)}reset(e=this.constructor.DEFAULTS){return this.settings={...this.constructor.DEFAULTS,...e},this._processState(),this}applyProcessors(e=this.settings){e.processors.forEach(i=>{d.mergeConfigs(e,i.call(this,e)||{})})}tweak(e={}){return d.mergeConfigs(this.settings,e),this._refreshDynamicProps(),this}seek(e=0,i=!0){return this.elapsedTime=Math.min(Math.max(e,0),this.time),i&&this._update(),this}setProgress(e=0,i=!0){return this.seek(this.time*e,i)}reverse(e=!1){return this.reversed=!this.reversed,this.seek(this.time-this.elapsedTime,e),this._processEasing(),this}play(e=!0){return this.isPlaying?this:(this.settings.autoApplyProcessors&&this._refreshDynamicProps(),e&&this.emit(_.PLAY),this.remainingDelay>0?this.step=this._stepDelay:(this.step=this._stepTime,this.emit(_.BEGIN)),this.manager&&this.manager.addToActive(this),this)}playPromise(e=this.promise){return this.play(),this.promise=e||new Promise(i=>{this._resolve=i}),this.promise}stop(e=!0){return this._processState(),e&&this.emit(_.STOP),this.manager&&this.manager.removeFromActive(this),this}pause(){return this.step=d._noop,this.manager&&this.manager.removeFromActive(this),this}replay(e=!1){return this.stop(e),this.play(e),this}get isPlaying(){return this.step!==d._noop}remove(){this.stop(),this.manager.remove(this)}};y(d,"DEFAULTS",C);var u=d;var P=class extends u{_preparePropertySetters(){this.propertySetters=this.properties.map(s=>{let e=s.split("."),i=e.pop();return r=>{let n=this.target;for(let a=0;a<e.length;a++)n=n[e[a]];n[i]=r}})}_generatePath(){let s=this.settings.points,e=Math.max(this.settings.smoothing,1),i=[];this.totalLength=0;function r(n,a,p,o,l){let m=l*l,h=m*l;return n.map((I,c)=>.5*(2*a[c]+(-n[c]+p[c])*l+(2*n[c]-5*a[c]+4*p[c]-o[c])*m+(-n[c]+3*a[c]-3*p[c]+o[c])*h))}for(let n=0;n<s.length-1;n++){let a=s[n===0?n:n-1],p=s[n],o=s[n+1],l=s[n+2<s.length?n+2:n+1];for(let m=0;m<e;m++){let h=r(a,p,o,l,m/e);i.push(h),i.length>1&&(this.totalLength+=this._calculateDistance(i[i.length-2],h))}}return i.push(s[s.length-1]),i}_calculateDistance(s,e){return Math.sqrt(s.reduce((i,r,n)=>i+Math.pow(e[n]-s[n],2),0))}_refreshDynamicProps(){super._refreshDynamicProps(),this.path=this._generatePath(),!this.target||this.path.length===0?this._setTargetProperties=u._noop:(this._tryToSetupProperties(),this._preparePropertySetters())}_tryToSetupProperties(){if(this.settings.properties)this.properties=this.settings.properties;else if(this.path[0].length<=3){let s=[["position.x"],["position.x","position.y"],["position.x","position.y","position.z"]];this.properties=s[this.path[0].length-1]}else this.properties=[]}_setTargetProperties(s){for(let e=0;e<this.propertySetters.length;e++)this.propertySetters[e](s[e])}_clamp(s,e,i){return Math.max(e,Math.min(s,i))}_getInterpolatedPosition(){let s=this.path.length-1,e=this.easeValue*s,i=this._clamp(e,0,s),r=i>=s?s-1:Math.floor(i),n=Math.min(r+1,s),a=e-r,p=this.path[r],o=this.path[n];return p.map((l,m)=>u.lerp(l,o[m],a))}_update(){super._update(),this._setTargetProperties(this._getInterpolatedPosition())}};y(P,"DEFAULTS",{...u.DEFAULTS,properties:null,points:[],smoothing:20});var A=class extends u{_refreshDynamicProps(){super._refreshDynamicProps(),this._processFromTo()}_processFromTo(){this._lerps=[],this.target&&(this._setupStates(),this._createLerps())}_setupStates(){this._from=this.settings.from||this._createState(this.settings.to||{},this.target),this._to=this.settings.to||this._createState(this.settings.from||{},this.target)}_createState(s={},e={},i={}){let r=(n,a,p)=>{for(let o in n)typeof n[o]=="object"?(p[o]={},r(n[o],a[o],p[o])):p[o]=a[o]};return r(s,e,i),i}_createLerpStep(s,e,i,r){if(this.settings.dynamic)return()=>{s[r]=u.lerp(e[r],i[r],this.easeValue)};{let n=e[r],a=i[r]-n;return()=>{s[r]=n+a*this.easeValue}}}_createLerps(s=this.target,e=this._from,i=this._to){for(let r in i)typeof i[r]=="object"?this._createLerps(s[r],e[r],i[r]):this._lerps.push(this._createLerpStep(s,e,i,r))}_update(){super._update();for(let s of this._lerps)s()}from(s={}){return this.tweak({from:s}),this}to(s={}){return this.tweak({to:s}),this}swap(){return this.tweak({from:this.settings.to,to:this.settings.from}),this}};y(A,"DEFAULTS",{...u.DEFAULTS,dynamic:!1,from:null,to:null});function w(t){return t.target?t.creator?t.creator.prototype instanceof u?t.creator:(console.error("Invalid creator provided. Using default creator."),u):t.points?P:t.from||t.to?A:u:u}var S=class{constructor(){y(this,"update",s=>{this.activeAnimations.forEach(e=>{e.step(s)})});this.activeAnimations=new Map,this.allAnimations=new Map}create({on:s={},once:e={},...i}){let r=w(i),n=new r(i,this);return Object.keys(s).forEach(a=>{n.on(a,s[a])}),Object.keys(e).forEach(a=>{n.once(a,e[a])}),this.add(n),n}getActiveAnimations(){return Array.from(this.activeAnimations.values())}getAllAnimations(){return Array.from(this.allAnimations.values())}remove({index:s}={}){s&&(this.activeAnimations.delete(s),this.allAnimations.delete(s))}add(s){this.allAnimations.set(s.index,s)}addToActive(s){this.activeAnimations.set(s.index,s)}removeFromActive(s){this.activeAnimations.delete(s.index)}stopAll(){this.activeAnimations.forEach(s=>{s.stop()})}removeAll(){this.stopAll(),this.activeAnimations.clear(),this.allAnimations.clear()}};var W=new S;var M=class t{constructor(s,e={}){this.callback=s,this.options={maxDeltaTime:100,...e},this.isRunning=!1,this.lastTime=0,this.animationId=null}static start(s,e={}){let i=new t(s,e);return i.start(),i}start(){if(this.isRunning)return;this.isRunning=!0;let s=e=>{if(!this.isRunning)return;let i=Math.min(e-this.lastTime,this.options.maxDeltaTime);this.lastTime=e,this.callback(i),this.isRunning&&(this.animationId=requestAnimationFrame(s))};requestAnimationFrame(e=>{this.lastTime=e,s(e)})}stop(){this.isRunning=!1,this.animationId&&(cancelAnimationFrame(this.animationId),this.animationId=null)}get running(){return this.isRunning}};function X(t,s){let e=new w(t),i=new e(t);return M.start(i.step.bind(i)),s?i.playPromise():i.play()}export{u as Core,P as Curve,C as DEFAULTS,_ as EVENTS,A as FromTo,W as GlobalManager,M as Loop,S as Manager,E as easings,O as modes,X as play};

package/package.json

@@ -1,16 +1,25 @@
 {
   "name": "qarl",
-  "version": "1.2.5",
+  "version": "1.3.1",
   "description": "simple animation library",
-  "main": "dist/qarl.es.min.js",
-  "module": "dist/qarl.es.min.js",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./types/index.d.ts",
   "exports": {
-    ".": "./dist/qarl.es.min.js"
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./types/index.d.ts"
+    }
   },
+  "files": [
+    "dist",
+    "types"
+  ],
   "scripts": {
-    "build": "webpack --mode=production",
-    "dev": "node kill-port.js && webpack serve --mode=development",
-    "publish": "npm run build && npm publish"
+    "build": "esbuild src/index.js --bundle --format=esm --outfile=dist/index.js --minify --target=es2020 && npm run type-check",
+    "type-check": "tsc --noEmit",
+    "prepare": "npm run build"
   },
   "repository": {
     "type": "git",
@@ -26,12 +35,7 @@
     "eventemitter3": "^5.0.1"
   },
   "devDependencies": {
-    "html-loader": "^5.1.0",
-    "html-webpack-plugin": "^5.6.4",
-    "terser-webpack-plugin": "^5.3.14",
-    "three": "^0.180.0",
-    "webpack": "^5.102.1",
-    "webpack-cli": "^6.0.1",
-    "webpack-dev-server": "^5.2.2"
+    "esbuild": "^0.19.0",
+    "typescript": "^5.3.0"
   }
 }

package/types/Core.d.ts

@@ -0,0 +1,243 @@
+import EventEmitter from 'eventemitter3';
+import { CoreSettings, EasingFunction } from './common';
+
+/**
+ * Core — base animation class built on EventEmitter3.
+ * Manages timing, easing, delays, repeats, and lifecycle events.
+ * Extended by FromTo (property interpolation) and Curve (spline animation).
+ *
+ * @example
+ * const anim = new Core({ time: 1000, easing: 'outQuad', loop: true });
+ * anim.onUpdate((a) => console.log(a.progress, a.easeValue));
+ * anim.play();
+ *
+ * @example
+ * // With promise
+ * await anim.playPromise();
+ * console.log('animation complete');
+ */
+export class Core extends EventEmitter {
+  /** Default settings applied to every new instance. */
+  static DEFAULTS: CoreSettings;
+
+  /**
+   * Linear interpolation between two values.
+   * @param a - Start value
+   * @param b - End value
+   * @param t - Interpolation factor (0..1)
+   * @returns Interpolated value
+   */
+  static lerp(a: number, b: number, t: number): number;
+
+  /**
+   * Deep-merge `source` into `target`, mutating `target` in place.
+   * Nested objects are merged recursively; primitives are overwritten.
+   */
+  static mergeConfigs(target: object, source: object): void;
+
+  /** Unique numeric index assigned at construction. */
+  index: number;
+
+  /** Original overrides passed to the constructor. */
+  overrides: Partial<CoreSettings>;
+
+  /** Current resolved settings (defaults merged with overrides). */
+  settings: CoreSettings;
+
+  /** Current animation progress (0..1), before easing. */
+  progress: number;
+
+  /** Current eased value (0..1 for standard easings, can overshoot for elastic/back). */
+  easeValue: number;
+
+  /** Elapsed time in milliseconds since animation started. */
+  elapsedTime: number;
+
+  /** Reference to `settings.target`. */
+  target: any;
+
+  /** Resolved animation duration in milliseconds (≥ 0). */
+  time: number;
+
+  /** Remaining repetitions. */
+  repeat: number;
+
+  /** Whether the animation is currently playing in reverse. */
+  reversed: boolean;
+
+  /** Remaining delay before next step in milliseconds. */
+  remainingDelay: number;
+
+  /** Delta time from the most recent `step()` call. */
+  lastDeltaTime: number;
+
+  /** The Manager this animation belongs to, if any. */
+  manager?: import('./Manager').Manager;
+
+  /**
+   * @param overrides - Settings to merge on top of `Core.DEFAULTS`
+   * @param manager - Optional Manager instance to auto-register with
+   */
+  constructor(overrides?: Partial<CoreSettings>, manager?: import('./Manager').Manager);
+
+  /**
+   * Advance the animation by `deltaTime` milliseconds.
+   * Called by Manager or Loop each frame.
+   * Internally delegates to delay/time step based on current state.
+   */
+  step(deltaTime: number): void;
+
+  /**
+   * Subscribe to an event. Returns `this` for chaining.
+   * @param event - Event name: `'play'` | `'stop'` | `'begin'` | `'update'` | `'repeat'` | `'complete'`
+   * @param fn - Callback
+   * @param context - Optional `this` context for the callback
+   */
+  on(event: string, fn: (...args: any[]) => void, context?: any): this;
+
+  /**
+   * Unsubscribe from an event. Returns `this` for chaining.
+   * @param event - Event name
+   * @param fn - The exact function reference that was passed to `.on()`
+   * @param context - The context that was passed to `.on()`
+   */
+  off(event: string, fn: (...args: any[]) => void, context?: any): this;
+
+  /**
+   * Subscribe to an event, auto-removed after first fire. Returns `this` for chaining.
+   * @param event - Event name
+   * @param fn - Callback
+   * @param context - Optional `this` context for the callback
+   */
+  once(event: string, fn: (...args: any[]) => void, context?: any): this;
+
+  /**
+   * Shorthand for `.on('complete', fn)`. Returns `this` for chaining.
+   *
+   * @example
+   * animation.onComplete(() => console.log('done')).play();
+   */
+  onComplete(fn: (animation: this) => void, context?: any): this;
+
+  /**
+   * Shorthand for `.on('update', fn)`. Returns `this` for chaining.
+   *
+   * @example
+   * animation.onUpdate((a) => {
+   *   console.log(a.progress, a.easeValue);
+   * });
+   */
+  onUpdate(fn: (animation: this) => void, context?: any): this;
+
+  /**
+   * Shorthand for `.once('complete', fn)`. Returns `this` for chaining.
+   * Callback fires once on the next complete, then is removed.
+   */
+  onceComplete(fn: (animation: this) => void, context?: any): this;
+
+  /**
+   * Reset the animation to its initial state.
+   * Merges `newSettings` (or DEFAULTS) and re-initializes all internal state.
+   * @param newSettings - New settings to apply (defaults to `DEFAULTS`)
+   * @returns `this` for chaining
+   */
+  reset(newSettings?: Partial<CoreSettings>): this;
+
+  /**
+   * Manually apply all processor functions to the current settings.
+   * Called automatically if `autoApplyProcessors` is `true`.
+   */
+  applyProcessors(settings?: CoreSettings): void;
+
+  /**
+   * Modify settings on a live animation without resetting progress.
+   * Deep-merges `newSettings` into current `settings` and refreshes dynamic props.
+   *
+   * @example
+   * animation.tweak({ time: 500, easing: 'inOutCubic' });
+   *
+   * @returns `this` for chaining
+   */
+  tweak(newSettings?: Partial<CoreSettings>): this;
+
+  /**
+   * Jump to a specific time in the animation.
+   * @param time - Target time in milliseconds, clamped to [0, this.time]
+   * @param callUpdate - Whether to fire the UPDATE event (default: `true`)
+   * @returns `this` for chaining
+   */
+  seek(time?: number, callUpdate?: boolean): this;
+
+  /**
+   * Jump to a specific progress value.
+   * @param progress - Target progress (0..1)
+   * @param callUpdate - Whether to fire the UPDATE event (default: `true`)
+   * @returns `this` for chaining
+   */
+  setProgress(progress?: number, callUpdate?: boolean): this;
+
+  /**
+   * Toggle animation direction. Flips `reversed` and adjusts `elapsedTime`
+   * so the animation continues from the mirrored position.
+   * @param callUpdate - Whether to fire the UPDATE event (default: `false`)
+   * @returns `this` for chaining
+   */
+  reverse(callUpdate?: boolean): this;
+
+  /**
+   * Start the animation.
+   * If a delay is set, transitions to delay state first (PLAY fires immediately, BEGIN fires after delay).
+   * No-op if already playing.
+   * @param withEvent - Whether to emit the PLAY event (default: `true`)
+   * @returns `this` for chaining
+   *
+   * @example
+   * animation.play();
+   */
+  play(withEvent?: boolean): this;
+
+  /**
+   * Start the animation and return a Promise that resolves on complete.
+   *
+   * @example
+   * await animation.playPromise();
+   * // animation finished
+   *
+   * @param promise - Optional existing promise to reuse
+   * @returns Promise that resolves when the animation completes
+   */
+  playPromise(promise?: Promise<void>): Promise<void>;
+
+  /**
+   * Stop the animation, reset internal state (`progress`, `elapsedTime`, etc.).
+   * Removes from Manager's active list.
+   * @param withEvent - Whether to emit the STOP event (default: `true`)
+   * @returns `this` for chaining
+   */
+  stop(withEvent?: boolean): this;
+
+  /**
+   * Pause the animation at its current position.
+   * Call `.play()` to resume from the paused point.
+   * @returns `this` for chaining
+   */
+  pause(): this;
+
+  /**
+   * Stop and immediately play again from the beginning.
+   * @param withEvent - Whether to emit STOP/PLAY events (default: `false`)
+   * @returns `this` for chaining
+   */
+  replay(withEvent?: boolean): this;
+
+  /**
+   * Remove this animation from its Manager (both active and all lists).
+   * Calls `.stop()` first.
+   */
+  remove(): void;
+
+  /**
+   * `true` if the animation is currently advancing (not paused/stopped).
+   */
+  get isPlaying(): boolean;
+}

package/types/Curve.d.ts

@@ -0,0 +1,61 @@
+import { Core } from './Core';
+import { CurveSettings } from './common';
+
+/**
+ * Curve — animates target properties along a Catmull-Rom spline defined by keypoints.
+ *
+ * Auto-detects property mapping for 1D–3D points (`position.x`, `.y`, `.z`).
+ * For higher dimensions or custom paths, provide `properties` explicitly.
+ *
+ * @example
+ * // 3D path — properties auto-detected as position.x/y/z
+ * const anim = new Curve({
+ *   target: mesh,
+ *   time: 2000,
+ *   points: [
+ *     [0, 0, 0],
+ *     [5, 10, 0],
+ *     [10, 0, 5],
+ *     [0, 0, 0],
+ *   ],
+ *   easing: 'inOutSine',
+ *   loop: true,
+ * });
+ * anim.play();
+ *
+ * @example
+ * // Custom properties — 6D points controlling position + scale
+ * const anim = new Curve({
+ *   target: mesh,
+ *   time: 3000,
+ *   properties: ['position.x', 'position.y', 'position.z', 'scale.x', 'scale.y', 'scale.z'],
+ *   points: [
+ *     [0, 0, 0, 1, 1, 1],
+ *     [5, 10, 0, 2, 0.5, 2],
+ *     [0, 0, 0, 1, 1, 1],
+ *   ],
+ *   smoothing: 30,
+ * });
+ */
+export class Curve extends Core {
+  /** Default settings for Curve, extending Core.DEFAULTS with `points`, `properties`, `smoothing`. */
+  static DEFAULTS: CurveSettings;
+
+  /** Current resolved settings. */
+  settings: CurveSettings;
+
+  /** Generated spline path — array of interpolated points. */
+  path: number[][];
+
+  /** Total arc length of the generated path. */
+  totalLength: number;
+
+  /** Resolved property paths assigned from interpolated values each frame. */
+  properties: string[];
+
+  /**
+   * @param overrides - Settings to merge on top of `Curve.DEFAULTS`
+   * @param manager - Optional Manager instance to auto-register with
+   */
+  constructor(overrides?: Partial<CurveSettings>, manager?: import('./Manager').Manager);
+}

package/types/FromTo.d.ts

@@ -0,0 +1,87 @@
+import { Core } from './Core';
+import { FromToSettings } from './common';
+
+/**
+ * FromTo — animates target properties by interpolating between `from` and `to` values.
+ * Automatically detects numeric properties (including nested objects) and creates lerps.
+ *
+ * If only `from` is provided, current target values are used as `to` (and vice versa).
+ *
+ * @example
+ * const anim = new FromTo({
+ *   target: mesh.position,
+ *   from: { x: 0, y: 0 },
+ *   to: { x: 100, y: 200 },
+ *   time: 1000,
+ *   easing: 'outQuad',
+ * });
+ * anim.play();
+ *
+ * @example
+ * // Nested properties
+ * const anim = new FromTo({
+ *   target: mesh,
+ *   from: { position: { x: 0 }, scale: { x: 1 } },
+ *   to: { position: { x: 10 }, scale: { x: 2 } },
+ *   time: 500,
+ * });
+ *
+ * @example
+ * // Dynamic mode — from/to are re-read each frame
+ * const anim = new FromTo({
+ *   target: obj,
+ *   from: startValues,
+ *   to: endValues,
+ *   dynamic: true,
+ *   time: 1000,
+ * });
+ * // Changing startValues/endValues during animation takes effect immediately
+ */
+export class FromTo extends Core {
+  /** Default settings for FromTo, extending Core.DEFAULTS with `from`, `to`, `dynamic`. */
+  static DEFAULTS: FromToSettings;
+
+  /** Current resolved settings. */
+  settings: FromToSettings;
+
+  /**
+   * @param overrides - Settings to merge on top of `FromTo.DEFAULTS`
+   * @param manager - Optional Manager instance to auto-register with
+   */
+  constructor(overrides?: Partial<FromToSettings>, manager?: import('./Manager').Manager);
+
+  /**
+   * Update `from` values on a live animation.
+   * Calls `.tweak()` internally and rebuilds interpolation.
+   *
+   * @example
+   * animation.from({ x: 50 }).play();
+   *
+   * @param from - New starting values
+   * @returns `this` for chaining
+   */
+  from(from?: Record<string, any>): this;
+
+  /**
+   * Update `to` values on a live animation.
+   * Calls `.tweak()` internally and rebuilds interpolation.
+   *
+   * @example
+   * animation.to({ x: 200 }).play();
+   *
+   * @param to - New ending values
+   * @returns `this` for chaining
+   */
+  to(to?: Record<string, any>): this;
+
+  /**
+   * Swap `from` and `to` values, effectively reversing the interpolation direction.
+   * Unlike `.reverse()`, this swaps the actual values rather than inverting the easing.
+   *
+   * @example
+   * animation.swap().replay();
+   *
+   * @returns `this` for chaining
+   */
+  swap(): this;
+}

package/types/Loop.d.ts

@@ -0,0 +1,65 @@
+import { LoopOptions } from './common';
+
+/**
+ * Loop — requestAnimationFrame wrapper with delta-time capping.
+ * Calls the provided callback every frame with `dt` in milliseconds.
+ *
+ * @example
+ * // Static shorthand — create and start in one call
+ * const loop = Loop.start((dt) => {
+ *   manager.update(dt);
+ * });
+ *
+ * // Stop later
+ * loop.stop();
+ *
+ * @example
+ * // Manual lifecycle
+ * const loop = new Loop((dt) => console.log(dt), { maxDeltaTime: 50 });
+ * loop.start();
+ * // ...
+ * loop.stop();
+ */
+export class Loop {
+  /** The callback invoked each frame with `dt` (capped by `maxDeltaTime`). */
+  callback: (dt: number) => void;
+
+  /** Resolved options with defaults applied. */
+  options: Required<LoopOptions>;
+
+  /** Whether the loop is currently running. */
+  isRunning: boolean;
+
+  /** Timestamp of the previous frame (from `requestAnimationFrame`). */
+  lastTime: number;
+
+  /** Current `requestAnimationFrame` handle, or `null` if stopped. */
+  animationId: number | null;
+
+  /**
+   * @param callback - Function called every frame with delta time in ms
+   * @param options - Loop options
+   */
+  constructor(callback: (dt: number) => void, options?: LoopOptions);
+
+  /**
+   * Create a Loop and immediately start it.
+   *
+   * @example
+   * const loop = Loop.start(manager.update);
+   *
+   * @param callback - Function called every frame with delta time in ms
+   * @param options - Loop options
+   * @returns The running Loop instance
+   */
+  static start(callback: (dt: number) => void, options?: LoopOptions): Loop;
+
+  /** Start the loop. No-op if already running. */
+  start(): void;
+
+  /** Stop the loop and cancel the next animation frame. */
+  stop(): void;
+
+  /** Alias for `isRunning`. */
+  get running(): boolean;
+}

package/types/Manager.d.ts

@@ -0,0 +1,121 @@
+import { Core } from './Core';
+import { ManagerCreateConfig } from './common';
+
+/**
+ * Manager — creates, stores, and batch-updates animations.
+ * Animations created via `.create()` are automatically registered in the Manager.
+ * Call `.update(dt)` each frame (typically from a Loop) to advance all active animations.
+ *
+ * @example
+ * const manager = new Manager();
+ *
+ * const anim = manager.create({
+ *   target: mesh.position,
+ *   from: { x: 0 },
+ *   to: { x: 100 },
+ *   time: 1000,
+ *   on: { complete: () => console.log('done') },
+ * });
+ *
+ * anim.play();
+ * Loop.start(manager.update);
+ */
+export class Manager {
+  /** Map of currently playing animations (index → animation). */
+  activeAnimations: Map<number, Core>;
+
+  /** Map of all registered animations, active or not (index → animation). */
+  allAnimations: Map<number, Core>;
+
+  /**
+   * Create a new animation, auto-detecting the type (Core, FromTo, or Curve).
+   * The animation is registered in the Manager but not started — call `.play()`.
+   *
+   * Type detection:
+   * - `config.points` → Curve
+   * - `config.from` or `config.to` → FromTo
+   * - otherwise → Core
+   * - `config.creator` → custom class (must extend Core)
+   *
+   * Event binding shortcuts:
+   * - `config.on` — persistent listeners (`.on()`)
+   * - `config.once` — one-time listeners (`.once()`)
+   *
+   * @example
+   * const anim = manager.create({
+   *   target: obj,
+   *   to: { x: 10 },
+   *   time: 500,
+   *   easing: 'outQuad',
+   *   on: { update: (a) => render(a.target) },
+   * });
+   * anim.play();
+   */
+  create(config: ManagerCreateConfig): Core;
+
+  /**
+   * Advance all active animations by `dt` milliseconds.
+   * Bound to the instance — safe to pass directly to `Loop.start()`.
+   *
+   * @example
+   * Loop.start(manager.update);
+   */
+  update(dt: number): void;
+
+  /**
+   * Get a snapshot array of all currently playing animations.
+   */
+  getActiveAnimations(): Core[];
+
+  /**
+   * Get a snapshot array of all registered animations (active + inactive).
+   */
+  getAllAnimations(): Core[];
+
+  /**
+   * Remove an animation from both active and all lists by its index.
+   * @param animation - Object with an `index` property
+   */
+  remove(animation: { index?: number }): void;
+
+  /**
+   * Register an animation in the `allAnimations` map.
+   * Called automatically by `.create()`.
+   */
+  add(animation: Core): void;
+
+  /**
+   * Move an animation to the active list (it will receive `.update()` calls).
+   * Called automatically by `animation.play()` when a Manager is attached.
+   */
+  addToActive(animation: Core): void;
+
+  /**
+   * Remove an animation from the active list (stops receiving updates).
+   * Called automatically by `animation.stop()` / `.pause()`.
+   */
+  removeFromActive(animation: Core): void;
+
+  /**
+   * Stop all active animations (calls `.stop()` on each).
+   */
+  stopAll(): void;
+
+  /**
+   * Stop all animations and clear both active and all lists.
+   */
+  removeAll(): void;
+}
+
+/**
+ * Pre-created global Manager singleton.
+ * Convenient when you don't need multiple independent animation groups.
+ *
+ * @example
+ * import { GlobalManager, Loop } from 'qarl';
+ *
+ * const anim = GlobalManager.create({ target: obj, to: { x: 10 }, time: 500 });
+ * anim.play();
+ * Loop.start(GlobalManager.update);
+ */
+export const GlobalManager: Manager;