@rosalana/sandbox 0.0.4 → 0.0.5

package/README.md

@@ -146,7 +146,7 @@ Sandbox figures out which WebGL version you're using by looking at your shader c
 If WebGL2 isn't available, Sandbox falls back to WebGL1 automatically. You can always check what you're running:
 
 ```ts
-sandbox.webglVersion();
+sandbox.version; // 1 or 2
 ```
 
 ## Uniforms
@@ -195,6 +195,8 @@ These uniforms are filled automatically every frame — no setup needed. Just de
 
 Hooks are one of the most powerful features in Sandbox. They let you run logic every frame — before or after render — which opens up a world of possibilities.
 
+The callback receives a `ClockState` object with `time`, `delta`, `frame`, `running`, and `fps` (smoothed).
+
 **Pre-compute values on the CPU** before they hit the shader:
 
 ```ts
@@ -327,6 +329,7 @@ interface SandboxOptions {
   autoplay?: boolean;
   pauseWhenHidden?: boolean;
   dpr?: number | "auto";
+  fps?: number;
   preserveDrawingBuffer?: boolean;
   antialias?: boolean;
   onError?: (error: SandboxError) => void;
@@ -337,20 +340,21 @@ interface SandboxOptions {
 }
 ```
 
-| Option                  | Default         | Description                     |
-| ----------------------- | --------------- | ------------------------------- |
-| `vertex`                | built-in        | Custom vertex shader            |
-| `fragment`              | built-in        | Fragment shader                 |
-| `autoplay`              | `true`          | Start rendering immediately     |
-| `pauseWhenHidden`       | `true`          | Pause when scrolled out of view |
-| `dpr`                   | `"auto"`        | Device pixel ratio              |
-| `preserveDrawingBuffer` | `false`         | Keep buffer for screenshots     |
-| `antialias`             | `true`          | Enable antialiasing             |
-| `onError`               | `console.error` | Error callback                  |
-| `onLoad`                | —               | Called when ready               |
-| `onBeforeRender`        | —               | Hook before each frame          |
-| `onAfterRender`         | —               | Hook after each frame           |
-| `uniforms`              | —               | Initial uniform values          |
+| Option                  | Default         | Description                                    |
+| ----------------------- | --------------- | ---------------------------------------------- |
+| `vertex`                | built-in        | Custom vertex shader                           |
+| `fragment`              | built-in        | Fragment shader                                |
+| `autoplay`              | `true`          | Start rendering immediately                    |
+| `pauseWhenHidden`       | `true`          | Pause when scrolled out of view                |
+| `dpr`                   | `"auto"`        | Device pixel ratio                             |
+| `fps`                   | `0` (unlimited) | Max frame rate (approximate due to rAF timing) |
+| `preserveDrawingBuffer` | `false`         | Keep buffer for screenshots                    |
+| `antialias`             | `true`          | Enable antialiasing                            |
+| `onError`               | `console.error` | Error callback                                 |
+| `onLoad`                | —               | Called on each shader compilation              |
+| `onBeforeRender`        | —               | Hook before each frame                         |
+| `onAfterRender`         | —               | Hook after each frame                          |
+| `uniforms`              | —               | Initial uniform values                         |
 
 ## Limitations (by design)
 

package/dist/index.cjs.js

@@ -1,8 +1,8 @@
-"use strict";var w=Object.defineProperty;var k=(o,t,e)=>t in o?w(o,t,{enumerable:!0,configurable:!0,writable:!0,value:e}):o[t]=e;var i=(o,t,e)=>k(o,typeof t!="symbol"?t+"":t,e);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});class u{constructor(t,e,r,s){this.target=t,this.type=e,this.listener=r,this.options=s,this.target.addEventListener(this.type,this.listener,this.options)}remove(){this.target.removeEventListener(this.type,this.listener,this.options)}static on(t,e,r,s){return t.addEventListener(e,r,s),()=>t.removeEventListener(e,r,s)}}class l extends Error{constructor(t,e){super(t),this.code=e,this.name="SandboxError"}}class S extends l{constructor(t){const e=t==="not_supported"?"WebGL is not supported in this browser.":"Failed to create WebGL context. The GPU may be unavailable.";super(e,t==="not_supported"?"WEBGL_NOT_SUPPORTED":"CONTEXT_CREATION_FAILED"),this.name="SandboxContextError"}}class L extends l{constructor(t,e){super(`Vertex and fragment shader WebGL versions do not match (${t} vs ${e})`,"SHADER_VERSION_MISMATCH"),this.vertexVersion=t,this.fragmentVersion=e,this.name="SandboxShaderVersionMismatchError"}}class f extends l{constructor(e,r,s){const n=f.parseErrorLines(s),a=n.length>0?` at line(s): ${n.join(", ")}`:"";super(`${e} shader compilation failed${a}
+"use strict";var w=Object.defineProperty;var k=(o,t,e)=>t in o?w(o,t,{enumerable:!0,configurable:!0,writable:!0,value:e}):o[t]=e;var r=(o,t,e)=>k(o,typeof t!="symbol"?t+"":t,e);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});class u{constructor(t,e,i,s){this.target=t,this.type=e,this.listener=i,this.options=s,this.target.addEventListener(this.type,this.listener,this.options)}remove(){this.target.removeEventListener(this.type,this.listener,this.options)}static on(t,e,i,s){return t.addEventListener(e,i,s),()=>t.removeEventListener(e,i,s)}}class l extends Error{constructor(t,e){super(t),this.code=e,this.name="SandboxError"}}class S extends l{constructor(t){const e=t==="not_supported"?"WebGL is not supported in this browser.":"Failed to create WebGL context. The GPU may be unavailable.";super(e,t==="not_supported"?"WEBGL_NOT_SUPPORTED":"CONTEXT_CREATION_FAILED"),this.name="SandboxContextError"}}class L extends l{constructor(t,e){super(`Vertex and fragment shader WebGL versions do not match (${t} vs ${e})`,"SHADER_VERSION_MISMATCH"),this.vertexVersion=t,this.fragmentVersion=e,this.name="SandboxShaderVersionMismatchError"}}class f extends l{constructor(e,i,s){const n=f.parseErrorLines(s),h=n.length>0?` at line(s): ${n.join(", ")}`:"";super(`${e} shader compilation failed${h}
 
-${s}`,"SHADER_COMPILATION_FAILED");i(this,"lines");this.shaderType=e,this.source=r,this.infoLog=s,this.name="SandboxShaderCompilationError",this.lines=n}static parseErrorLines(e){const r=[/ERROR:\s*\d*:(\d+)/g,/(\d+):(\d+)\(\d+\):/g,/^(\d+):/gm],s=new Set;for(const n of r){let a;for(;(a=n.exec(e))!==null;){const c=parseInt(a[1],10);c>0&&s.add(c)}}return[...s].sort((n,a)=>n-a)}}class d extends l{constructor(t){super(`Shader program linking failed
+${s}`,"SHADER_COMPILATION_FAILED");r(this,"lines");this.shaderType=e,this.source=i,this.infoLog=s,this.name="SandboxShaderCompilationError",this.lines=n}static parseErrorLines(e){const i=[/ERROR:\s*\d*:(\d+)/g,/(\d+):(\d+)\(\d+\):/g,/^(\d+):/gm],s=new Set;for(const n of i){let h;for(;(h=n.exec(e))!==null;){const c=parseInt(h[1],10);c>0&&s.add(c)}}return[...s].sort((n,h)=>n-h)}}class d extends l{constructor(t){super(`Shader program linking failed
 
-${t}`,"PROGRAM_LINK_FAILED"),this.infoLog=t,this.name="SandboxProgramError"}}class R{constructor(){i(this,"time",0);i(this,"delta",0);i(this,"frame",0);i(this,"running",!1);i(this,"startTime",0);i(this,"lastTime",0);i(this,"rafId",null);i(this,"callback",null);this.loop=this.loop.bind(this)}start(t){if(this.running)return this;this.callback=t,this.running=!0;const e=performance.now();return this.frame===0?this.startTime=e:this.startTime=e-this.time*1e3,this.lastTime=e,this.rafId=requestAnimationFrame(this.loop),this}stop(){return this.running?(this.running=!1,this.rafId!==null&&(cancelAnimationFrame(this.rafId),this.rafId=null),this):this}reset(){return this.stop(),this.time=0,this.delta=0,this.frame=0,this}getState(){return{time:this.time,delta:this.delta,frame:this.frame}}tick(t=0){return this.delta=t,this.time+=t,this.frame++,this.callback&&this.callback(this.getState()),this}setTime(t){return this.time=t,this}destroy(){this.reset(),this.callback=null}loop(t){this.running&&(this.delta=(t-this.lastTime)/1e3,this.lastTime=t,this.time=(t-this.startTime)/1e3,this.frame++,this.callback&&this.callback(this.getState()),this.rafId=requestAnimationFrame(this.loop))}}class p{constructor(t){i(this,"gl");i(this,"vao",null);i(this,"vbo",null);i(this,"ibo",null);i(this,"vertexCount",0);i(this,"indexCount",0);i(this,"useIndices",!1);i(this,"vaoExt",null);i(this,"isWebGL2");this.gl=t,this.isWebGL2=t instanceof WebGL2RenderingContext,this.isWebGL2||(this.vaoExt=t.getExtension("OES_vertex_array_object"))}static fullscreenQuad(t){const e=new p(t),r=new Float32Array([-1,-1,0,0,1,-1,1,0,-1,1,0,1,1,1,1,1]),s=new Uint16Array([0,1,2,2,1,3]);return e.setup(r,s),e}setup(t,e){const r=this.gl;return this.createVAO(),this.bindVAO(),this.vbo=r.createBuffer(),r.bindBuffer(r.ARRAY_BUFFER,this.vbo),r.bufferData(r.ARRAY_BUFFER,t,r.STATIC_DRAW),this.vertexCount=t.length/4,e&&(this.ibo=r.createBuffer(),r.bindBuffer(r.ELEMENT_ARRAY_BUFFER,this.ibo),r.bufferData(r.ELEMENT_ARRAY_BUFFER,e,r.STATIC_DRAW),this.indexCount=e.length,this.useIndices=!0),this.unbindVAO(),this}linkAttributes(t){const e=this.gl;this.bindVAO(),e.bindBuffer(e.ARRAY_BUFFER,this.vbo);const r=4*Float32Array.BYTES_PER_ELEMENT,s=this.getPositionLocation(t);s>=0&&(e.enableVertexAttribArray(s),e.vertexAttribPointer(s,2,e.FLOAT,!1,r,0));const n=this.getTexcoordLocation(t);return n>=0&&(e.enableVertexAttribArray(n),e.vertexAttribPointer(n,2,e.FLOAT,!1,r,2*Float32Array.BYTES_PER_ELEMENT)),this.useIndices&&e.bindBuffer(e.ELEMENT_ARRAY_BUFFER,this.ibo),this.unbindVAO(),this}bind(){return this.bindVAO(),this}unbind(){return this.unbindVAO(),this}draw(){const t=this.gl;return this.bindVAO(),this.useIndices?t.drawElements(t.TRIANGLES,this.indexCount,t.UNSIGNED_SHORT,0):t.drawArrays(t.TRIANGLE_STRIP,0,this.vertexCount),this}destroy(){const t=this.gl;this.deleteVAO(),this.vbo&&(t.deleteBuffer(this.vbo),this.vbo=null),this.ibo&&(t.deleteBuffer(this.ibo),this.ibo=null)}getPositionLocation(t){let e=t.getAttribLocation("a_position");return e>=0||(e=t.getAttribLocation("aPosition"),e>=0)||(e=t.getAttribLocation("position"),e>=0)?e:-1}getTexcoordLocation(t){let e=t.getAttribLocation("a_texcoord");return e>=0||(e=t.getAttribLocation("aTexCoord"),e>=0)||(e=t.getAttribLocation("texcoord"),e>=0)||(e=t.getAttribLocation("a_uv"),e>=0)?e:-1}createVAO(){this.isWebGL2?this.vao=this.gl.createVertexArray():this.vaoExt&&(this.vao=this.vaoExt.createVertexArrayOES())}bindVAO(){this.vao&&(this.isWebGL2?this.gl.bindVertexArray(this.vao):this.vaoExt&&this.vaoExt.bindVertexArrayOES(this.vao))}unbindVAO(){this.isWebGL2?this.gl.bindVertexArray(null):this.vaoExt&&this.vaoExt.bindVertexArrayOES(null)}deleteVAO(){this.vao&&(this.isWebGL2?this.gl.deleteVertexArray(this.vao):this.vaoExt&&this.vaoExt.deleteVertexArrayOES(this.vao),this.vao=null)}}class h{constructor(t){i(this,"gl");i(this,"program",null);i(this,"vertexShader",null);i(this,"fragmentShader",null);i(this,"version",1);this.gl=t}static detectVersion(t){return/^\s*#version\s+300\s+es/m.test(t)?2:1}compile(t,e){this.destroy();const r=h.detectVersion(t),s=h.detectVersion(e);if(r!=s)throw new L(r,s);return this.version=Math.max(r,s),this.vertexShader=this.compileShader("vertex",t),this.fragmentShader=this.compileShader("fragment",e),this.linkProgram(),this}use(){return this.program&&this.gl.useProgram(this.program),this}getProgram(){return this.program}getVersion(){return this.version}getAttribLocation(t){return this.program?this.gl.getAttribLocation(this.program,t):-1}getUniformLocation(t){return this.program?this.gl.getUniformLocation(this.program,t):null}destroy(){const t=this.gl;this.program&&(this.vertexShader&&t.detachShader(this.program,this.vertexShader),this.fragmentShader&&t.detachShader(this.program,this.fragmentShader),t.deleteProgram(this.program),this.program=null),this.vertexShader&&(t.deleteShader(this.vertexShader),this.vertexShader=null),this.fragmentShader&&(t.deleteShader(this.fragmentShader),this.fragmentShader=null)}compileShader(t,e){const r=this.gl,s=t==="vertex"?r.VERTEX_SHADER:r.FRAGMENT_SHADER,n=r.createShader(s);if(!n)throw new f(t,e,"Failed to create shader object");if(r.shaderSource(n,e),r.compileShader(n),!r.getShaderParameter(n,r.COMPILE_STATUS)){const c=r.getShaderInfoLog(n)||"Unknown error";throw r.deleteShader(n),new f(t,e,c)}return n}linkProgram(){const t=this.gl;if(!this.vertexShader||!this.fragmentShader)throw new d("Shaders not compiled");const e=t.createProgram();if(!e)throw new d("Failed to create program object");if(t.attachShader(e,this.vertexShader),t.attachShader(e,this.fragmentShader),t.linkProgram(e),!t.getProgramParameter(e,t.LINK_STATUS)){const s=t.getProgramInfoLog(e)||"Unknown error";throw t.deleteProgram(e),new d(s)}this.program=e}}class x{constructor(t,e){i(this,"name");i(this,"method");i(this,"isArray");i(this,"isMatrix");i(this,"location",null);i(this,"locationResolved",!1);i(this,"value");this.name=t,this.value=e;const r=x.inferMethodInfo(e);this.method=r.method,this.isArray=r.isArray,this.isMatrix=r.isMatrix}static inferMethodInfo(t){if(typeof t=="boolean")return{method:"uniform1i",isArray:!1,isMatrix:!1};if(typeof t=="number")return{method:"uniform1f",isArray:!1,isMatrix:!1};if(!Array.isArray(t))return{method:"uniform1f",isArray:!1,isMatrix:!1};const e=t.length,r=t[0];if(Array.isArray(r))switch(r.length){case 2:return{method:"uniform2fv",isArray:!0,isMatrix:!1};case 3:return{method:"uniform3fv",isArray:!0,isMatrix:!1};case 4:return{method:"uniform4fv",isArray:!0,isMatrix:!1};default:return{method:"uniform1fv",isArray:!0,isMatrix:!1}}switch(e){case 2:return{method:"uniform2fv",isArray:!1,isMatrix:!1};case 3:return{method:"uniform3fv",isArray:!1,isMatrix:!1};case 4:return{method:"uniform4fv",isArray:!1,isMatrix:!1};case 9:return{method:"uniformMatrix3fv",isArray:!1,isMatrix:!0};case 16:return{method:"uniformMatrix4fv",isArray:!1,isMatrix:!0};default:return{method:"uniform1fv",isArray:!0,isMatrix:!1}}}resolveLocation(t,e){return this.locationResolved||(this.location=t.getUniformLocation(e,this.name),this.locationResolved=!0),this.location}invalidateLocation(){this.location=null,this.locationResolved=!1}setValue(t){this.value=t}getValue(){return this.value}upload(t,e){const r=this.resolveLocation(t,e);if(r===null)return;const s=this.value;let n;switch(typeof s=="boolean"?n=s?1:0:typeof s=="number"?n=s:this.isArray&&Array.isArray(s[0])?n=new Float32Array(s.flat()):n=new Float32Array(s),this.method){case"uniform1f":t.uniform1f(r,n);break;case"uniform1i":t.uniform1i(r,n);break;case"uniform1fv":t.uniform1fv(r,n);break;case"uniform2fv":t.uniform2fv(r,n);break;case"uniform3fv":t.uniform3fv(r,n);break;case"uniform4fv":t.uniform4fv(r,n);break;case"uniformMatrix2fv":t.uniformMatrix2fv(r,!1,n);break;case"uniformMatrix3fv":t.uniformMatrix3fv(r,!1,n);break;case"uniformMatrix4fv":t.uniformMatrix4fv(r,!1,n);break}}}const m=class m{constructor(t){i(this,"gl");i(this,"program",null);i(this,"uniforms",new Map);this.gl=t}attachProgram(t){this.program=t;for(const e of this.uniforms.values())e.invalidateLocation();return this}set(t,e){const r=this.uniforms.get(t);return r?r.setValue(e):this.uniforms.set(t,new x(t,e)),this}setMany(t){for(const[e,r]of Object.entries(t))this.set(e,r);return this}get(t){var e;return(e=this.uniforms.get(t))==null?void 0:e.getValue()}has(t){return this.uniforms.has(t)}delete(t){return this.uniforms.delete(t)}uploadAll(){if(!this.program)return this;for(const t of this.uniforms.values())t.upload(this.gl,this.program);return this}uploadBuiltIns(t,e,r){if(this.set("u_resolution",e),this.set("u_time",t.time),this.set("u_delta",t.delta),this.set("u_mouse",r),this.set("u_frame",t.frame),!this.program)return this;for(const s of m.BUILT_INS){const n=this.uniforms.get(s);n&&n.upload(this.gl,this.program)}return this}clear(){this.uniforms.clear()}destroy(){this.uniforms.clear(),this.program=null}keys(){return this.uniforms.keys()}get size(){return this.uniforms.size}};i(m,"BUILT_INS",new Set(["u_resolution","u_time","u_delta","u_mouse","u_frame"]));let v=m;class A{constructor(){i(this,"hooks",new Map)}id(){return Math.random().toString(36).substring(2,10)}add(t){const e=this.id();return this.hooks.set(e,t),()=>this.remove(e)}remove(t){this.hooks.delete(t)}run(t){for(const[e,r]of this.hooks)r(t)===!1&&this.remove(e)}destroy(){this.hooks.clear()}}class b{constructor(t,e){i(this,"canvas");i(this,"gl");i(this,"options");i(this,"onBeforeHooks",new A);i(this,"onAfterHooks",new A);i(this,"_program");i(this,"_geometry");i(this,"_uniforms");i(this,"_clock");i(this,"_resolution",[1,1]);i(this,"_mouse",[0,0]);i(this,"_version",1);i(this,"playing",!1);this.canvas=t,this.options=e,this.gl=this.initContext(),this.enableExtensions(),this._program=new h(this.gl),this._geometry=p.fullscreenQuad(this.gl),this._uniforms=new v(this.gl),this._clock=new R,this.options.onBeforeRender&&this.onBeforeHooks.add(this.options.onBeforeRender),this.options.onAfterRender&&this.onAfterHooks.add(this.options.onAfterRender),this.onRender=this.onRender.bind(this)}static setup(t,e){const r=new b(t,e);return e.vertex&&e.fragment&&r.shader(e.vertex,e.fragment),e.uniforms&&r._uniforms.setMany(e.uniforms),r}initContext(){const t={antialias:this.options.antialias,preserveDrawingBuffer:this.options.preserveDrawingBuffer,alpha:!0,depth:!1,stencil:!1},e=this.canvas.getContext("webgl2",t);if(e)return this._version=2,e;const r=this.canvas.getContext("webgl",t);if(r)return this._version=1,r;const s=new S("not_supported");throw this.options.onError(s),s}enableExtensions(){this.gl.getExtension("OES_standard_derivatives"),this.gl.getExtension("OES_texture_float"),this.gl.getExtension("OES_texture_float_linear"),this._version===1&&this.gl.getExtension("OES_vertex_array_object")}viewport(t,e,r,s){return this.canvas.width=r,this.canvas.height=s,this.gl.viewport(t,e,r,s),this._resolution=[r,s],this}clock(t){return this._clock.setTime(t),this}mouse(t,e){return this._mouse=[t,e],this}uniform(t,e){return this._uniforms.set(t,e),this}uniforms(t){return this._uniforms.setMany(t),this}getUniform(t){return this._uniforms.get(t)}shader(t,e){try{this._program.compile(t,e),this._version=this._program.getVersion(),this._geometry.linkAttributes(this._program);const r=this._program.getProgram();r&&this._uniforms.attachProgram(r)}catch(r){r instanceof l&&this.options.onError(r)}return this}play(){return this.playing?this:(this.playing=!0,this._clock.start(this.onRender),this)}pause(){if(!this.playing)return this;const t=this._clock.getState();return this.onBeforeHooks.run(t),this.playing=!1,this._clock.stop(),this.onAfterHooks.run(t),this}render(){return this.onRender(this._clock.getState()),this}getContext(){return this.gl}getVersion(){return this._version}destroy(){this.pause(),this._clock.destroy(),this._geometry.destroy(),this._program.destroy(),this._uniforms.destroy(),this.onAfterHooks.destroy(),this.onBeforeHooks.destroy()}onRender(t){const e=this.gl;this.onBeforeHooks.run(t),e.clearColor(0,0,0,0),e.clear(e.COLOR_BUFFER_BIT),this._program.use(),this._uniforms.uploadBuiltIns(t,this._resolution,this._mouse),this._uniforms.uploadAll(),this._geometry.bind(),this._geometry.draw(),this.onAfterHooks.run(t)}}const g=`#ifdef GL_ES
+${t}`,"PROGRAM_LINK_FAILED"),this.infoLog=t,this.name="SandboxProgramError"}}class R{constructor(){r(this,"time",0);r(this,"delta",0);r(this,"frame",0);r(this,"running",!1);r(this,"fps",0);r(this,"startTime",0);r(this,"lastTime",0);r(this,"rafId",null);r(this,"callback",null);r(this,"maxFps",0);this.loop=this.loop.bind(this)}start(t){if(this.running)return this;this.callback=t,this.running=!0;const e=performance.now();return this.frame===0?this.startTime=e:this.startTime=e-this.time*1e3,this.lastTime=e,this.rafId=requestAnimationFrame(this.loop),this}stop(){return this.running?(this.running=!1,this.rafId!==null&&(cancelAnimationFrame(this.rafId),this.rafId=null),this):this}reset(){return this.stop(),this.time=0,this.delta=0,this.frame=0,this.fps=0,this}getState(){return{time:this.time,delta:this.delta,frame:this.frame,running:this.running,fps:Math.round(this.fps)}}tick(t=0){return this.delta=t,this.time+=t,this.frame++,this.callback&&this.callback(this.getState()),this}setTime(t){return this.time=t,this}destroy(){this.reset(),this.callback=null}setMaxFps(t){return this.maxFps=t,this}loop(t){if(!this.running)return;if(this.maxFps>0){const i=1e3/this.maxFps;if(t-this.lastTime<i){this.rafId=requestAnimationFrame(this.loop);return}}this.delta=(t-this.lastTime)/1e3,this.lastTime=t;const e=this.delta>0?1/this.delta:0;this.fps=this.fps*.95+e*.05,this.time=(t-this.startTime)/1e3,this.frame++,this.callback&&this.callback(this.getState()),this.rafId=requestAnimationFrame(this.loop)}}class p{constructor(t){r(this,"gl");r(this,"vao",null);r(this,"vbo",null);r(this,"ibo",null);r(this,"vertexCount",0);r(this,"indexCount",0);r(this,"useIndices",!1);r(this,"vaoExt",null);r(this,"isWebGL2");this.gl=t,this.isWebGL2=t instanceof WebGL2RenderingContext,this.isWebGL2||(this.vaoExt=t.getExtension("OES_vertex_array_object"))}static fullscreenQuad(t){const e=new p(t),i=new Float32Array([-1,-1,0,0,1,-1,1,0,-1,1,0,1,1,1,1,1]),s=new Uint16Array([0,1,2,2,1,3]);return e.setup(i,s),e}setup(t,e){const i=this.gl;return this.createVAO(),this.bindVAO(),this.vbo=i.createBuffer(),i.bindBuffer(i.ARRAY_BUFFER,this.vbo),i.bufferData(i.ARRAY_BUFFER,t,i.STATIC_DRAW),this.vertexCount=t.length/4,e&&(this.ibo=i.createBuffer(),i.bindBuffer(i.ELEMENT_ARRAY_BUFFER,this.ibo),i.bufferData(i.ELEMENT_ARRAY_BUFFER,e,i.STATIC_DRAW),this.indexCount=e.length,this.useIndices=!0),this.unbindVAO(),this}linkAttributes(t){const e=this.gl;this.bindVAO(),e.bindBuffer(e.ARRAY_BUFFER,this.vbo);const i=4*Float32Array.BYTES_PER_ELEMENT,s=this.getPositionLocation(t);s>=0&&(e.enableVertexAttribArray(s),e.vertexAttribPointer(s,2,e.FLOAT,!1,i,0));const n=this.getTexcoordLocation(t);return n>=0&&(e.enableVertexAttribArray(n),e.vertexAttribPointer(n,2,e.FLOAT,!1,i,2*Float32Array.BYTES_PER_ELEMENT)),this.useIndices&&e.bindBuffer(e.ELEMENT_ARRAY_BUFFER,this.ibo),this.unbindVAO(),this}bind(){return this.bindVAO(),this}unbind(){return this.unbindVAO(),this}draw(){const t=this.gl;return this.bindVAO(),this.useIndices?t.drawElements(t.TRIANGLES,this.indexCount,t.UNSIGNED_SHORT,0):t.drawArrays(t.TRIANGLE_STRIP,0,this.vertexCount),this}destroy(){const t=this.gl;this.deleteVAO(),this.vbo&&(t.deleteBuffer(this.vbo),this.vbo=null),this.ibo&&(t.deleteBuffer(this.ibo),this.ibo=null)}getPositionLocation(t){let e=t.getAttribLocation("a_position");return e>=0||(e=t.getAttribLocation("aPosition"),e>=0)||(e=t.getAttribLocation("position"),e>=0)?e:-1}getTexcoordLocation(t){let e=t.getAttribLocation("a_texcoord");return e>=0||(e=t.getAttribLocation("aTexCoord"),e>=0)||(e=t.getAttribLocation("texcoord"),e>=0)||(e=t.getAttribLocation("a_uv"),e>=0)?e:-1}createVAO(){this.isWebGL2?this.vao=this.gl.createVertexArray():this.vaoExt&&(this.vao=this.vaoExt.createVertexArrayOES())}bindVAO(){this.vao&&(this.isWebGL2?this.gl.bindVertexArray(this.vao):this.vaoExt&&this.vaoExt.bindVertexArrayOES(this.vao))}unbindVAO(){this.isWebGL2?this.gl.bindVertexArray(null):this.vaoExt&&this.vaoExt.bindVertexArrayOES(null)}deleteVAO(){this.vao&&(this.isWebGL2?this.gl.deleteVertexArray(this.vao):this.vaoExt&&this.vaoExt.deleteVertexArrayOES(this.vao),this.vao=null)}}class a{constructor(t){r(this,"gl");r(this,"program",null);r(this,"vertexShader",null);r(this,"fragmentShader",null);r(this,"version",1);this.gl=t}static detectVersion(t){return/^\s*#version\s+300\s+es/m.test(t)?2:1}compile(t,e){this.destroy();const i=a.detectVersion(t),s=a.detectVersion(e);if(i!=s)throw new L(i,s);return this.version=Math.max(i,s),this.vertexShader=this.compileShader("vertex",t),this.fragmentShader=this.compileShader("fragment",e),this.linkProgram(),this}use(){return this.program&&this.gl.useProgram(this.program),this}getProgram(){return this.program}getVersion(){return this.version}getAttribLocation(t){return this.program?this.gl.getAttribLocation(this.program,t):-1}getUniformLocation(t){return this.program?this.gl.getUniformLocation(this.program,t):null}destroy(){const t=this.gl;this.program&&(this.vertexShader&&t.detachShader(this.program,this.vertexShader),this.fragmentShader&&t.detachShader(this.program,this.fragmentShader),t.deleteProgram(this.program),this.program=null),this.vertexShader&&(t.deleteShader(this.vertexShader),this.vertexShader=null),this.fragmentShader&&(t.deleteShader(this.fragmentShader),this.fragmentShader=null)}compileShader(t,e){const i=this.gl,s=t==="vertex"?i.VERTEX_SHADER:i.FRAGMENT_SHADER,n=i.createShader(s);if(!n)throw new f(t,e,"Failed to create shader object");if(i.shaderSource(n,e),i.compileShader(n),!i.getShaderParameter(n,i.COMPILE_STATUS)){const c=i.getShaderInfoLog(n)||"Unknown error";throw i.deleteShader(n),new f(t,e,c)}return n}linkProgram(){const t=this.gl;if(!this.vertexShader||!this.fragmentShader)throw new d("Shaders not compiled");const e=t.createProgram();if(!e)throw new d("Failed to create program object");if(t.attachShader(e,this.vertexShader),t.attachShader(e,this.fragmentShader),t.linkProgram(e),!t.getProgramParameter(e,t.LINK_STATUS)){const s=t.getProgramInfoLog(e)||"Unknown error";throw t.deleteProgram(e),new d(s)}this.program=e}}class x{constructor(t,e){r(this,"name");r(this,"method");r(this,"isArray");r(this,"isMatrix");r(this,"location",null);r(this,"locationResolved",!1);r(this,"value");this.name=t,this.value=e;const i=x.inferMethodInfo(e);this.method=i.method,this.isArray=i.isArray,this.isMatrix=i.isMatrix}static inferMethodInfo(t){if(typeof t=="boolean")return{method:"uniform1i",isArray:!1,isMatrix:!1};if(typeof t=="number")return{method:"uniform1f",isArray:!1,isMatrix:!1};if(!Array.isArray(t))return{method:"uniform1f",isArray:!1,isMatrix:!1};const e=t.length,i=t[0];if(Array.isArray(i))switch(i.length){case 2:return{method:"uniform2fv",isArray:!0,isMatrix:!1};case 3:return{method:"uniform3fv",isArray:!0,isMatrix:!1};case 4:return{method:"uniform4fv",isArray:!0,isMatrix:!1};default:return{method:"uniform1fv",isArray:!0,isMatrix:!1}}switch(e){case 2:return{method:"uniform2fv",isArray:!1,isMatrix:!1};case 3:return{method:"uniform3fv",isArray:!1,isMatrix:!1};case 4:return{method:"uniform4fv",isArray:!1,isMatrix:!1};case 9:return{method:"uniformMatrix3fv",isArray:!1,isMatrix:!0};case 16:return{method:"uniformMatrix4fv",isArray:!1,isMatrix:!0};default:return{method:"uniform1fv",isArray:!0,isMatrix:!1}}}resolveLocation(t,e){return this.locationResolved||(this.location=t.getUniformLocation(e,this.name),this.locationResolved=!0),this.location}invalidateLocation(){this.location=null,this.locationResolved=!1}setValue(t){this.value=t}getValue(){return this.value}upload(t,e){const i=this.resolveLocation(t,e);if(i===null)return;const s=this.value;let n;switch(typeof s=="boolean"?n=s?1:0:typeof s=="number"?n=s:this.isArray&&Array.isArray(s[0])?n=new Float32Array(s.flat()):n=new Float32Array(s),this.method){case"uniform1f":t.uniform1f(i,n);break;case"uniform1i":t.uniform1i(i,n);break;case"uniform1fv":t.uniform1fv(i,n);break;case"uniform2fv":t.uniform2fv(i,n);break;case"uniform3fv":t.uniform3fv(i,n);break;case"uniform4fv":t.uniform4fv(i,n);break;case"uniformMatrix2fv":t.uniformMatrix2fv(i,!1,n);break;case"uniformMatrix3fv":t.uniformMatrix3fv(i,!1,n);break;case"uniformMatrix4fv":t.uniformMatrix4fv(i,!1,n);break}}}const m=class m{constructor(t){r(this,"gl");r(this,"program",null);r(this,"uniforms",new Map);this.gl=t}attachProgram(t){this.program=t;for(const e of this.uniforms.values())e.invalidateLocation();return this}set(t,e){const i=this.uniforms.get(t);return i?i.setValue(e):this.uniforms.set(t,new x(t,e)),this}setMany(t){for(const[e,i]of Object.entries(t))this.set(e,i);return this}get(t){var e;return(e=this.uniforms.get(t))==null?void 0:e.getValue()}has(t){return this.uniforms.has(t)}delete(t){return this.uniforms.delete(t)}uploadAll(){if(!this.program)return this;for(const t of this.uniforms.values())t.upload(this.gl,this.program);return this}uploadBuiltIns(t,e,i){if(this.set("u_resolution",e),this.set("u_time",t.time),this.set("u_delta",t.delta),this.set("u_mouse",i),this.set("u_frame",t.frame),!this.program)return this;for(const s of m.BUILT_INS){const n=this.uniforms.get(s);n&&n.upload(this.gl,this.program)}return this}clear(){this.uniforms.clear()}destroy(){this.uniforms.clear(),this.program=null}keys(){return this.uniforms.keys()}get size(){return this.uniforms.size}};r(m,"BUILT_INS",new Set(["u_resolution","u_time","u_delta","u_mouse","u_frame"]));let v=m;class A{constructor(){r(this,"hooks",new Map)}id(){return Math.random().toString(36).substring(2,10)}add(t){const e=this.id();return this.hooks.set(e,t),()=>this.remove(e)}remove(t){this.hooks.delete(t)}run(t){for(const[e,i]of this.hooks)i(t)===!1&&this.remove(e)}destroy(){this.hooks.clear()}}class _{constructor(t,e){r(this,"canvas");r(this,"gl");r(this,"options");r(this,"onBeforeHooks",new A);r(this,"onAfterHooks",new A);r(this,"_program");r(this,"_geometry");r(this,"_uniforms");r(this,"_clock");r(this,"_resolution",[1,1]);r(this,"_mouse",[0,0]);r(this,"_version",1);r(this,"playing",!1);this.canvas=t,this.options=e,this.gl=this.initContext(),this.enableExtensions(),this._program=new a(this.gl),this._geometry=p.fullscreenQuad(this.gl),this._uniforms=new v(this.gl),this._clock=new R,this.options.fps&&this._clock.setMaxFps(this.options.fps),this.options.onBeforeRender&&this.onBeforeHooks.add(this.options.onBeforeRender),this.options.onAfterRender&&this.onAfterHooks.add(this.options.onAfterRender),this.onRender=this.onRender.bind(this)}static setup(t,e){const i=new _(t,e);return e.vertex&&e.fragment&&i.shader(e.vertex,e.fragment),e.uniforms&&i._uniforms.setMany(e.uniforms),i}initContext(){const t={antialias:this.options.antialias,preserveDrawingBuffer:this.options.preserveDrawingBuffer,alpha:!0,depth:!1,stencil:!1},e=this.canvas.getContext("webgl2",t);if(e)return this._version=2,e;const i=this.canvas.getContext("webgl",t);if(i)return this._version=1,i;const s=new S("not_supported");throw this.options.onError(s),s}enableExtensions(){this.gl.getExtension("OES_standard_derivatives"),this.gl.getExtension("OES_texture_float"),this.gl.getExtension("OES_texture_float_linear"),this._version===1&&this.gl.getExtension("OES_vertex_array_object")}viewport(t,e,i,s){return this.canvas.width=i,this.canvas.height=s,this.gl.viewport(t,e,i,s),this._resolution=[i,s],this}clock(t){return this._clock.setTime(t),this}mouse(t,e){return this._mouse=[t,e],this}uniform(t,e){return this._uniforms.set(t,e),this}uniforms(t){return this._uniforms.setMany(t),this}getUniform(t){return this._uniforms.get(t)}shader(t,e){try{this._program.compile(t,e),this._version=this._program.getVersion(),this._geometry.linkAttributes(this._program);const i=this._program.getProgram();i&&this._uniforms.attachProgram(i),this.options.onLoad()}catch(i){i instanceof l&&this.options.onError(i)}return this}play(){return this.playing?this:(this.playing=!0,this._clock.start(this.onRender),this)}pause(){if(!this.playing)return this;const t=this._clock.getState();return this.onBeforeHooks.run(t),this.playing=!1,this._clock.stop(),this.onAfterHooks.run(t),this}render(){return this.onRender(this._clock.getState()),this}getContext(){return this.gl}getVersion(){return this._version}getClock(){return this._clock}destroy(){this.pause(),this._clock.destroy(),this._geometry.destroy(),this._program.destroy(),this._uniforms.destroy(),this.onAfterHooks.destroy(),this.onBeforeHooks.destroy()}onRender(t){const e=this.gl;this.onBeforeHooks.run(t),e.clearColor(0,0,0,0),e.clear(e.COLOR_BUFFER_BIT),this._program.use(),this._uniforms.uploadBuiltIns(t,this._resolution,this._mouse),this._uniforms.uploadAll(),this._geometry.bind(),this._geometry.draw(),this.onAfterHooks.run(t)}}const g=`#ifdef GL_ES
 precision mediump float;
 #endif
 
@@ -15,7 +15,7 @@ void main() {
   v_texcoord = a_texcoord;
   gl_Position = vec4(a_position, 0.0, 1.0);
 }
-`,y=`#ifdef GL_ES
+`,E=`#ifdef GL_ES
 precision mediump float;
 #endif
 
@@ -29,7 +29,7 @@ void main() {
   vec3 color = vec3(uv.x, uv.y, 0.5 + 0.5 * sin(u_time));
   gl_FragColor = vec4(color, 1.0);
 }
-`,E=`#version 300 es
+`,y=`#version 300 es
 
 in vec2 a_position;
 in vec2 a_texcoord;
@@ -39,7 +39,7 @@ out vec2 v_texcoord;
 void main() {
     v_texcoord = a_texcoord;
     gl_Position = vec4(a_position, 0.0, 1.0);
-}`,M=`#version 300 es
+}`,V=`#version 300 es
 precision highp float;
 
 uniform vec2 u_resolution;
@@ -53,5 +53,5 @@ void main() {
     vec2 uv = gl_FragCoord.xy / u_resolution;
     vec3 color = vec3(uv.x, uv.y, 0.5 + 0.5 * sin(u_time));
     fragColor = vec4(color, 1.0);
-}`;class _{constructor(t,e){i(this,"listeners",[]);i(this,"canvas");i(this,"options");i(this,"engine");this.canvas=t,this.options=this.resolveOptions(e),this.engine=b.setup(this.canvas,this.options),this.setupListeners(),this.setViewport(),this.options.onLoad(),this.options.autoplay&&this.play()}static create(t,e){return new _(t,e)}resolveOptions(t){const e={vertex:g,fragment:y,autoplay:!0,pauseWhenHidden:!0,dpr:"auto",preserveDrawingBuffer:!1,antialias:!0,onError:r=>{console.error("Oops!",r,`
-You can handle errors programmatically by providing an onError callback to suppress this log and implement custom fallback behavior.`)},onLoad:()=>{},onBeforeRender:null,onAfterRender:null,uniforms:{}};if(t!=null&&t.vertex&&!(t!=null&&t.fragment)){const r=h.detectVersion(t.vertex);e.vertex=t.vertex,e.fragment=r===2?M:y}if(t!=null&&t.fragment&&!(t!=null&&t.vertex)){const r=h.detectVersion(t.fragment);e.fragment=t.fragment,e.vertex=r===2?E:g}return{...e,...t}}setupListeners(){this.listeners.push(u.on(window,"resize",()=>{this.setViewport()}),u.on(this.canvas,"resize",()=>{this.setViewport()}),(()=>{let t=!1;return u.on(document,"scroll",e=>{this.options.pauseWhenHidden&&(this.isInViewport()?t&&!this.isPlaying()&&(this.play(),t=!1):this.isPlaying()&&(this.pause(),t=!0))})})(),u.on(document,"mousemove",t=>{this.setMouse(t.clientX||t.pageX,t.clientY||t.pageY)}),u.on(document,"touchmove",t=>{t.touches.length>0&&this.setMouse(t.touches[0].clientX,t.touches[0].clientY)}))}destroyListeners(){this.listeners.forEach(t=>t()),this.listeners=[]}setViewport(){const t=this.options.dpr==="auto"?Math.min(2,window.devicePixelRatio||1):this.options.dpr,e=this.canvas.clientWidth||this.canvas.width||1,r=this.canvas.clientHeight||this.canvas.height||1;this.engine.viewport(0,0,Math.max(1,Math.floor(e*t)),Math.max(1,Math.floor(r*t)))}isInViewport(){const t=this.canvas.getBoundingClientRect();return t.bottom>=0&&t.right>=0&&t.top<=(window.innerHeight||document.documentElement.clientHeight)&&t.left<=(window.innerWidth||document.documentElement.clientWidth)}setMouse(t,e){const r=this.canvas.getBoundingClientRect();t>=r.left&&t<=r.right&&e>=r.top&&e<=r.bottom&&this.engine.mouse(t-r.left,e-r.top)}setUniform(t,e){return this.engine.uniform(t,e),this}setUniforms(t){return this.engine.uniforms(t),this}getUniform(t){return this.engine.getUniform(t)}setShader(t,e){return this.engine.shader(t,e),this}setFragment(t){const r=this.webglVersion()===1?g:E;return this.engine.shader(r,t),this}hook(t,e="before"){return e==="before"?this.engine.onBeforeHooks.add(t):this.engine.onAfterHooks.add(t)}play(){return this.engine.play(),this}playAt(t){return this.engine.clock(t),this.engine.play(),this}pause(){return this.engine.pause(),this}pauseAt(t){const e=this.hook(r=>{r.time>=t&&(e(),this.pause())},"after");return this}toggle(){return this.engine.playing?this.pause():this.play(),this}time(t){return this.engine.clock(t),this}render(){return this.engine.render(),this}renderAt(t){return this.engine.clock(t),this.engine.render(),this}isPlaying(){return this.engine.playing}webglVersion(){return this.engine.getVersion()}canvasElement(){return this.canvas}destroy(){this.destroyListeners(),this.engine.destroy()}}exports.Sandbox=_;exports.SandboxContextError=S;exports.SandboxError=l;exports.SandboxProgramError=d;exports.SandboxShaderCompilationError=f;exports.SandboxShaderVersionMismatchError=L;
+}`;class b{constructor(t,e){r(this,"listeners",[]);r(this,"canvasEl");r(this,"options");r(this,"engine");r(this,"usingCustomVertex",!1);this.canvasEl=t,this.options=this.resolveOptions(e),this.engine=_.setup(this.canvasEl,this.options),this.setupListeners(),this.setViewport(),this.options.autoplay&&this.play()}static create(t,e){return new b(t,e)}resolveOptions(t){const e={vertex:g,fragment:E,autoplay:!0,pauseWhenHidden:!0,dpr:"auto",fps:0,preserveDrawingBuffer:!1,antialias:!0,onError:i=>{console.error("Oops!",i,`
+You can handle errors programmatically by providing an onError callback to suppress this log and implement custom fallback behavior.`)},onLoad:()=>{},onBeforeRender:null,onAfterRender:null,uniforms:{}};if(t!=null&&t.vertex&&(this.usingCustomVertex=!0),t!=null&&t.vertex&&!(t!=null&&t.fragment)){const i=a.detectVersion(t.vertex);e.vertex=t.vertex,e.fragment=i===2?V:E}if(t!=null&&t.fragment&&!(t!=null&&t.vertex)){const i=a.detectVersion(t.fragment);e.fragment=t.fragment,e.vertex=i===2?y:g}return{...e,...t}}setupListeners(){this.listeners.push(u.on(window,"resize",()=>{this.setViewport()}),u.on(this.canvasEl,"resize",()=>{this.setViewport()}),(()=>{let t=!1;return u.on(document,"scroll",e=>{this.options.pauseWhenHidden&&(this.isInViewport()?t&&!this.isPlaying()&&(this.play(),t=!1):this.isPlaying()&&(this.pause(),t=!0))})})(),u.on(document,"mousemove",t=>{this.setMouse(t.clientX||t.pageX,t.clientY||t.pageY)}),u.on(document,"touchmove",t=>{t.touches.length>0&&this.setMouse(t.touches[0].clientX,t.touches[0].clientY)}))}destroyListeners(){this.listeners.forEach(t=>t()),this.listeners=[]}setViewport(){const t=this.options.dpr==="auto"?Math.min(2,window.devicePixelRatio||1):this.options.dpr,e=this.canvasEl.clientWidth||this.canvasEl.width||1,i=this.canvasEl.clientHeight||this.canvasEl.height||1;this.engine.viewport(0,0,Math.max(1,Math.floor(e*t)),Math.max(1,Math.floor(i*t)))}isInViewport(){const t=this.canvasEl.getBoundingClientRect();return t.bottom>=0&&t.right>=0&&t.top<=(window.innerHeight||document.documentElement.clientHeight)&&t.left<=(window.innerWidth||document.documentElement.clientWidth)}setMouse(t,e){const i=this.canvasEl.getBoundingClientRect();t>=i.left&&t<=i.right&&e>=i.top&&e<=i.bottom&&this.engine.mouse(t-i.left,e-i.top)}setUniform(t,e){return this.engine.uniform(t,e),this}setUniforms(t){return this.engine.uniforms(t),this}getUniform(t){return this.engine.getUniform(t)}setShader(t,e){return this.options.vertex=t,this.options.fragment=e,this.usingCustomVertex=!0,this.engine.shader(this.options.vertex,this.options.fragment),this}setFragment(t){const e=a.detectVersion(t),i=a.detectVersion(this.options.vertex);return this.options.fragment=t,e!==i&&(this.usingCustomVertex||(this.options.vertex=e===2?y:g)),this.engine.shader(this.options.vertex,this.options.fragment),this}setFps(t){return this.engine.getClock().setMaxFps(t),this}hook(t,e="before"){return e==="before"?this.engine.onBeforeHooks.add(t):this.engine.onAfterHooks.add(t)}play(){return this.engine.play(),this}playAt(t){return this.engine.clock(t),this.engine.play(),this}pause(){return this.engine.pause(),this}pauseAt(t){const e=this.hook(i=>{i.time>=t&&(e(),this.pause())},"after");return this}toggle(){return this.engine.playing?this.pause():this.play(),this}time(t){return this.engine.clock(t),this}render(){return this.engine.render(),this}renderAt(t){return this.engine.clock(t),this.engine.render(),this}isPlaying(){return this.engine.playing}get version(){return this.engine.getVersion()}get canvas(){return this.canvasEl}destroy(){this.destroyListeners(),this.engine.destroy()}}exports.Sandbox=b;exports.SandboxContextError=S;exports.SandboxError=l;exports.SandboxProgramError=d;exports.SandboxShaderCompilationError=f;exports.SandboxShaderVersionMismatchError=L;

package/dist/index.d.ts

@@ -23,11 +23,13 @@ export declare class Sandbox {
     /** Active event listeners */
     private listeners;
     /** HTML canvas element */
-    private canvas;
+    private canvasEl;
     /** Resolved options */
     private options;
     /** WebGL engine */
     private engine;
+    /** User sets custom vertex shader */
+    private usingCustomVertex;
     constructor(canvas: HTMLCanvasElement, options?: SandboxOptions);
     /**
      * Sandbox - A lightweight WebGL wrapper for shader effects.
@@ -93,6 +95,14 @@ export declare class Sandbox {
      * sandbox.setFragment(fragmentSource);
      */
     setFragment(fragment: string): this;
+    /**
+     * Set the max frame rate runtime
+     *
+     * @example
+     * sandbox.setFps(30); // Limit to 30 FPS
+     * sandbox.setFps(0);  // Unlimited FPS
+     */
+    setFps(fps: number): this;
     /**
      * Add a runtime render hook.
      */
@@ -140,11 +150,11 @@ export declare class Sandbox {
     /**
      * Get WebGL version using (1 or 2).
      */
-    webglVersion(): WebGLVersion;
+    get version(): WebGLVersion;
     /**
      * Get canvas element.
      */
-    canvasElement(): HTMLCanvasElement;
+    get canvas(): HTMLCanvasElement;
     /**
      * Destroy sandbox and release all resources.
      * @example

package/dist/index.es.js

@@ -1,9 +1,9 @@
 var S = Object.defineProperty;
 var L = (o, t, e) => t in o ? S(o, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : o[t] = e;
-var i = (o, t, e) => L(o, typeof t != "symbol" ? t + "" : t, e);
+var r = (o, t, e) => L(o, typeof t != "symbol" ? t + "" : t, e);
 class l {
-  constructor(t, e, r, s) {
-    this.target = t, this.type = e, this.listener = r, this.options = s, this.target.addEventListener(
+  constructor(t, e, i, s) {
+    this.target = t, this.type = e, this.listener = i, this.options = s, this.target.addEventListener(
       this.type,
       this.listener,
       this.options
@@ -16,8 +16,8 @@ class l {
       this.options
     );
   }
-  static on(t, e, r, s) {
-    return t.addEventListener(e, r, s), () => t.removeEventListener(e, r, s);
+  static on(t, e, i, s) {
+    return t.addEventListener(e, i, s), () => t.removeEventListener(e, i, s);
   }
 }
 class u extends Error {
@@ -43,21 +43,21 @@ class k extends u {
   }
 }
 class c extends u {
-  constructor(e, r, s) {
-    const n = c.parseErrorLines(s), a = n.length > 0 ? ` at line(s): ${n.join(", ")}` : "";
+  constructor(e, i, s) {
+    const n = c.parseErrorLines(s), h = n.length > 0 ? ` at line(s): ${n.join(", ")}` : "";
     super(
-      `${e} shader compilation failed${a}
+      `${e} shader compilation failed${h}
 
 ${s}`,
       "SHADER_COMPILATION_FAILED"
     );
     /** Line numbers where errors occurred */
-    i(this, "lines");
-    this.shaderType = e, this.source = r, this.infoLog = s, this.name = "SandboxShaderCompilationError", this.lines = n;
+    r(this, "lines");
+    this.shaderType = e, this.source = i, this.infoLog = s, this.name = "SandboxShaderCompilationError", this.lines = n;
   }
   /** Parse error log to extract line numbers */
   static parseErrorLines(e) {
-    const r = [
+    const i = [
       /ERROR:\s*\d*:(\d+)/g,
       // Chrome/ANGLE: ERROR: 0:15
       /(\d+):(\d+)\(\d+\):/g,
@@ -65,14 +65,14 @@ ${s}`,
       /^(\d+):/gm
       // Simple: 15:
     ], s = /* @__PURE__ */ new Set();
-    for (const n of r) {
-      let a;
-      for (; (a = n.exec(e)) !== null; ) {
-        const f = parseInt(a[1], 10);
+    for (const n of i) {
+      let h;
+      for (; (h = n.exec(e)) !== null; ) {
+        const f = parseInt(h[1], 10);
         f > 0 && s.add(f);
       }
     }
-    return [...s].sort((n, a) => n - a);
+    return [...s].sort((n, h) => n - h);
   }
 }
 class m extends u {
@@ -85,17 +85,20 @@ ${t}`, "PROGRAM_LINK_FAILED"), this.infoLog = t, this.name = "SandboxProgramErro
 class R {
   constructor() {
     /** Total elapsed time in seconds */
-    i(this, "time", 0);
+    r(this, "time", 0);
     /** Delta time since last frame in seconds */
-    i(this, "delta", 0);
+    r(this, "delta", 0);
     /** Frame counter */
-    i(this, "frame", 0);
+    r(this, "frame", 0);
     /** Is clock running */
-    i(this, "running", !1);
-    i(this, "startTime", 0);
-    i(this, "lastTime", 0);
-    i(this, "rafId", null);
-    i(this, "callback", null);
+    r(this, "running", !1);
+    /** Smoothed frames per second */
+    r(this, "fps", 0);
+    r(this, "startTime", 0);
+    r(this, "lastTime", 0);
+    r(this, "rafId", null);
+    r(this, "callback", null);
+    r(this, "maxFps", 0);
     this.loop = this.loop.bind(this);
   }
   /**
@@ -118,7 +121,7 @@ class R {
    * Reset clock to initial state.
    */
   reset() {
-    return this.stop(), this.time = 0, this.delta = 0, this.frame = 0, this;
+    return this.stop(), this.time = 0, this.delta = 0, this.frame = 0, this.fps = 0, this;
   }
   /**
    * Get current clock state snapshot.
@@ -127,7 +130,9 @@ class R {
     return {
       time: this.time,
       delta: this.delta,
-      frame: this.frame
+      frame: this.frame,
+      running: this.running,
+      fps: Math.round(this.fps)
     };
   }
   /**
@@ -149,25 +154,41 @@ class R {
   destroy() {
     this.reset(), this.callback = null;
   }
+  /**
+   * Set maximum frames per second.
+   */
+  setMaxFps(t) {
+    return this.maxFps = t, this;
+  }
   /**
    * Internal animation frame handler.
    */
   loop(t) {
-    this.running && (this.delta = (t - this.lastTime) / 1e3, this.lastTime = t, this.time = (t - this.startTime) / 1e3, this.frame++, this.callback && this.callback(this.getState()), this.rafId = requestAnimationFrame(this.loop));
+    if (!this.running) return;
+    if (this.maxFps > 0) {
+      const i = 1e3 / this.maxFps;
+      if (t - this.lastTime < i) {
+        this.rafId = requestAnimationFrame(this.loop);
+        return;
+      }
+    }
+    this.delta = (t - this.lastTime) / 1e3, this.lastTime = t;
+    const e = this.delta > 0 ? 1 / this.delta : 0;
+    this.fps = this.fps * 0.95 + e * 0.05, this.time = (t - this.startTime) / 1e3, this.frame++, this.callback && this.callback(this.getState()), this.rafId = requestAnimationFrame(this.loop);
   }
 }
 class p {
   constructor(t) {
-    i(this, "gl");
-    i(this, "vao", null);
-    i(this, "vbo", null);
-    i(this, "ibo", null);
-    i(this, "vertexCount", 0);
-    i(this, "indexCount", 0);
-    i(this, "useIndices", !1);
+    r(this, "gl");
+    r(this, "vao", null);
+    r(this, "vbo", null);
+    r(this, "ibo", null);
+    r(this, "vertexCount", 0);
+    r(this, "indexCount", 0);
+    r(this, "useIndices", !1);
     // WebGL1 VAO extension (if available)
-    i(this, "vaoExt", null);
-    i(this, "isWebGL2");
+    r(this, "vaoExt", null);
+    r(this, "isWebGL2");
     this.gl = t, this.isWebGL2 = t instanceof WebGL2RenderingContext, this.isWebGL2 || (this.vaoExt = t.getExtension("OES_vertex_array_object"));
   }
   /**
@@ -175,7 +196,7 @@ class p {
    * This is the most common use case for shader effects.
    */
   static fullscreenQuad(t) {
-    const e = new p(t), r = new Float32Array([
+    const e = new p(t), i = new Float32Array([
       // position    texcoord
       -1,
       -1,
@@ -207,14 +228,14 @@ class p {
       3
       // second triangle
     ]);
-    return e.setup(r, s), e;
+    return e.setup(i, s), e;
   }
   /**
    * Setup geometry from vertex and index data.
    */
   setup(t, e) {
-    const r = this.gl;
-    return this.createVAO(), this.bindVAO(), this.vbo = r.createBuffer(), r.bindBuffer(r.ARRAY_BUFFER, this.vbo), r.bufferData(r.ARRAY_BUFFER, t, r.STATIC_DRAW), this.vertexCount = t.length / 4, e && (this.ibo = r.createBuffer(), r.bindBuffer(r.ELEMENT_ARRAY_BUFFER, this.ibo), r.bufferData(r.ELEMENT_ARRAY_BUFFER, e, r.STATIC_DRAW), this.indexCount = e.length, this.useIndices = !0), this.unbindVAO(), this;
+    const i = this.gl;
+    return this.createVAO(), this.bindVAO(), this.vbo = i.createBuffer(), i.bindBuffer(i.ARRAY_BUFFER, this.vbo), i.bufferData(i.ARRAY_BUFFER, t, i.STATIC_DRAW), this.vertexCount = t.length / 4, e && (this.ibo = i.createBuffer(), i.bindBuffer(i.ELEMENT_ARRAY_BUFFER, this.ibo), i.bufferData(i.ELEMENT_ARRAY_BUFFER, e, i.STATIC_DRAW), this.indexCount = e.length, this.useIndices = !0), this.unbindVAO(), this;
   }
   /**
    * Link vertex attributes to shader program.
@@ -223,15 +244,15 @@ class p {
   linkAttributes(t) {
     const e = this.gl;
     this.bindVAO(), e.bindBuffer(e.ARRAY_BUFFER, this.vbo);
-    const r = 4 * Float32Array.BYTES_PER_ELEMENT, s = this.getPositionLocation(t);
-    s >= 0 && (e.enableVertexAttribArray(s), e.vertexAttribPointer(s, 2, e.FLOAT, !1, r, 0));
+    const i = 4 * Float32Array.BYTES_PER_ELEMENT, s = this.getPositionLocation(t);
+    s >= 0 && (e.enableVertexAttribArray(s), e.vertexAttribPointer(s, 2, e.FLOAT, !1, i, 0));
     const n = this.getTexcoordLocation(t);
     return n >= 0 && (e.enableVertexAttribArray(n), e.vertexAttribPointer(
       n,
       2,
       e.FLOAT,
       !1,
-      r,
+      i,
       2 * Float32Array.BYTES_PER_ELEMENT
     )), this.useIndices && e.bindBuffer(e.ELEMENT_ARRAY_BUFFER, this.ibo), this.unbindVAO(), this;
   }
@@ -293,13 +314,13 @@ class p {
     this.vao && (this.isWebGL2 ? this.gl.deleteVertexArray(this.vao) : this.vaoExt && this.vaoExt.deleteVertexArrayOES(this.vao), this.vao = null);
   }
 }
-class h {
+class a {
   constructor(t) {
-    i(this, "gl");
-    i(this, "program", null);
-    i(this, "vertexShader", null);
-    i(this, "fragmentShader", null);
-    i(this, "version", 1);
+    r(this, "gl");
+    r(this, "program", null);
+    r(this, "vertexShader", null);
+    r(this, "fragmentShader", null);
+    r(this, "version", 1);
     this.gl = t;
   }
   /**
@@ -316,10 +337,10 @@ class h {
    */
   compile(t, e) {
     this.destroy();
-    const r = h.detectVersion(t), s = h.detectVersion(e);
-    if (r != s)
-      throw new k(r, s);
-    return this.version = Math.max(r, s), this.vertexShader = this.compileShader("vertex", t), this.fragmentShader = this.compileShader("fragment", e), this.linkProgram(), this;
+    const i = a.detectVersion(t), s = a.detectVersion(e);
+    if (i != s)
+      throw new k(i, s);
+    return this.version = Math.max(i, s), this.vertexShader = this.compileShader("vertex", t), this.fragmentShader = this.compileShader("fragment", e), this.linkProgram(), this;
   }
   /**
    * Bind this program for rendering.
@@ -363,16 +384,16 @@ class h {
    * @throws ShaderCompilationError if compilation fails
    */
   compileShader(t, e) {
-    const r = this.gl, s = t === "vertex" ? r.VERTEX_SHADER : r.FRAGMENT_SHADER, n = r.createShader(s);
+    const i = this.gl, s = t === "vertex" ? i.VERTEX_SHADER : i.FRAGMENT_SHADER, n = i.createShader(s);
     if (!n)
       throw new c(
         t,
         e,
         "Failed to create shader object"
       );
-    if (r.shaderSource(n, e), r.compileShader(n), !r.getShaderParameter(n, r.COMPILE_STATUS)) {
-      const f = r.getShaderInfoLog(n) || "Unknown error";
-      throw r.deleteShader(n), new c(t, e, f);
+    if (i.shaderSource(n, e), i.compileShader(n), !i.getShaderParameter(n, i.COMPILE_STATUS)) {
+      const f = i.getShaderInfoLog(n) || "Unknown error";
+      throw i.deleteShader(n), new c(t, e, f);
     }
     return n;
   }
@@ -396,16 +417,16 @@ class h {
 }
 class x {
   constructor(t, e) {
-    i(this, "name");
-    i(this, "method");
-    i(this, "isArray");
-    i(this, "isMatrix");
-    i(this, "location", null);
-    i(this, "locationResolved", !1);
-    i(this, "value");
+    r(this, "name");
+    r(this, "method");
+    r(this, "isArray");
+    r(this, "isMatrix");
+    r(this, "location", null);
+    r(this, "locationResolved", !1);
+    r(this, "value");
     this.name = t, this.value = e;
-    const r = x.inferMethodInfo(e);
-    this.method = r.method, this.isArray = r.isArray, this.isMatrix = r.isMatrix;
+    const i = x.inferMethodInfo(e);
+    this.method = i.method, this.isArray = i.isArray, this.isMatrix = i.isMatrix;
   }
   /**
    * Infer WebGL method and metadata from value type.
@@ -417,9 +438,9 @@ class x {
       return { method: "uniform1f", isArray: !1, isMatrix: !1 };
     if (!Array.isArray(t))
       return { method: "uniform1f", isArray: !1, isMatrix: !1 };
-    const e = t.length, r = t[0];
-    if (Array.isArray(r))
-      switch (r.length) {
+    const e = t.length, i = t[0];
+    if (Array.isArray(i))
+      switch (i.length) {
         case 2:
           return { method: "uniform2fv", isArray: !0, isMatrix: !1 };
         case 3:
@@ -475,8 +496,8 @@ class x {
    * @param program - Current WebGL program (for location resolution)
    */
   upload(t, e) {
-    const r = this.resolveLocation(t, e);
-    if (r === null)
+    const i = this.resolveLocation(t, e);
+    if (i === null)
       return;
     const s = this.value;
     let n;
@@ -484,40 +505,40 @@ class x {
       s.flat()
     ) : n = new Float32Array(s), this.method) {
       case "uniform1f":
-        t.uniform1f(r, n);
+        t.uniform1f(i, n);
         break;
       case "uniform1i":
-        t.uniform1i(r, n);
+        t.uniform1i(i, n);
         break;
       case "uniform1fv":
-        t.uniform1fv(r, n);
+        t.uniform1fv(i, n);
         break;
       case "uniform2fv":
-        t.uniform2fv(r, n);
+        t.uniform2fv(i, n);
         break;
       case "uniform3fv":
-        t.uniform3fv(r, n);
+        t.uniform3fv(i, n);
         break;
       case "uniform4fv":
-        t.uniform4fv(r, n);
+        t.uniform4fv(i, n);
         break;
       case "uniformMatrix2fv":
-        t.uniformMatrix2fv(r, !1, n);
+        t.uniformMatrix2fv(i, !1, n);
         break;
       case "uniformMatrix3fv":
-        t.uniformMatrix3fv(r, !1, n);
+        t.uniformMatrix3fv(i, !1, n);
         break;
       case "uniformMatrix4fv":
-        t.uniformMatrix4fv(r, !1, n);
+        t.uniformMatrix4fv(i, !1, n);
         break;
     }
   }
 }
 const d = class d {
   constructor(t) {
-    i(this, "gl");
-    i(this, "program", null);
-    i(this, "uniforms", /* @__PURE__ */ new Map());
+    r(this, "gl");
+    r(this, "program", null);
+    r(this, "uniforms", /* @__PURE__ */ new Map());
     this.gl = t;
   }
   /**
@@ -535,15 +556,15 @@ const d = class d {
    * Creates the uniform if it doesn't exist, updates if it does.
    */
   set(t, e) {
-    const r = this.uniforms.get(t);
-    return r ? r.setValue(e) : this.uniforms.set(t, new x(t, e)), this;
+    const i = this.uniforms.get(t);
+    return i ? i.setValue(e) : this.uniforms.set(t, new x(t, e)), this;
   }
   /**
    * Set multiple uniforms at once.
    */
   setMany(t) {
-    for (const [e, r] of Object.entries(t))
-      this.set(e, r);
+    for (const [e, i] of Object.entries(t))
+      this.set(e, i);
     return this;
   }
   /**
@@ -580,8 +601,8 @@ const d = class d {
    * Upload only built-in uniforms (u_resolution, u_time, u_delta, u_mouse, u_frame).
    * Call this every frame with current values.
    */
-  uploadBuiltIns(t, e, r) {
-    if (this.set("u_resolution", e), this.set("u_time", t.time), this.set("u_delta", t.delta), this.set("u_mouse", r), this.set("u_frame", t.frame), !this.program)
+  uploadBuiltIns(t, e, i) {
+    if (this.set("u_resolution", e), this.set("u_time", t.time), this.set("u_delta", t.delta), this.set("u_mouse", i), this.set("u_frame", t.frame), !this.program)
       return this;
     for (const s of d.BUILT_INS) {
       const n = this.uniforms.get(s);
@@ -615,7 +636,7 @@ const d = class d {
   }
 };
 /** Built-in uniform names that are handled automatically */
-i(d, "BUILT_INS", /* @__PURE__ */ new Set([
+r(d, "BUILT_INS", /* @__PURE__ */ new Set([
   "u_resolution",
   "u_time",
   "u_delta",
@@ -625,7 +646,7 @@ i(d, "BUILT_INS", /* @__PURE__ */ new Set([
 let v = d;
 class b {
   constructor() {
-    i(this, "hooks", /* @__PURE__ */ new Map());
+    r(this, "hooks", /* @__PURE__ */ new Map());
   }
   id() {
     return Math.random().toString(36).substring(2, 10);
@@ -641,8 +662,8 @@ class b {
   }
   /** Run all hooks with the given state */
   run(t) {
-    for (const [e, r] of this.hooks)
-      r(t) === !1 && this.remove(e);
+    for (const [e, i] of this.hooks)
+      i(t) === !1 && this.remove(e);
   }
   destroy() {
     this.hooks.clear();
@@ -650,27 +671,27 @@ class b {
 }
 class _ {
   constructor(t, e) {
-    i(this, "canvas");
-    i(this, "gl");
-    i(this, "options");
-    i(this, "onBeforeHooks", new b());
-    i(this, "onAfterHooks", new b());
-    i(this, "_program");
-    i(this, "_geometry");
-    i(this, "_uniforms");
-    i(this, "_clock");
-    i(this, "_resolution", [1, 1]);
-    i(this, "_mouse", [0, 0]);
-    i(this, "_version", 1);
-    i(this, "playing", !1);
-    this.canvas = t, this.options = e, this.gl = this.initContext(), this.enableExtensions(), this._program = new h(this.gl), this._geometry = p.fullscreenQuad(this.gl), this._uniforms = new v(this.gl), this._clock = new R(), this.options.onBeforeRender && this.onBeforeHooks.add(this.options.onBeforeRender), this.options.onAfterRender && this.onAfterHooks.add(this.options.onAfterRender), this.onRender = this.onRender.bind(this);
+    r(this, "canvas");
+    r(this, "gl");
+    r(this, "options");
+    r(this, "onBeforeHooks", new b());
+    r(this, "onAfterHooks", new b());
+    r(this, "_program");
+    r(this, "_geometry");
+    r(this, "_uniforms");
+    r(this, "_clock");
+    r(this, "_resolution", [1, 1]);
+    r(this, "_mouse", [0, 0]);
+    r(this, "_version", 1);
+    r(this, "playing", !1);
+    this.canvas = t, this.options = e, this.gl = this.initContext(), this.enableExtensions(), this._program = new a(this.gl), this._geometry = p.fullscreenQuad(this.gl), this._uniforms = new v(this.gl), this._clock = new R(), this.options.fps && this._clock.setMaxFps(this.options.fps), this.options.onBeforeRender && this.onBeforeHooks.add(this.options.onBeforeRender), this.options.onAfterRender && this.onAfterHooks.add(this.options.onAfterRender), this.onRender = this.onRender.bind(this);
   }
   /**
    * Factory method to create and setup WebGL instance.
    */
   static setup(t, e) {
-    const r = new _(t, e);
-    return e.vertex && e.fragment && r.shader(e.vertex, e.fragment), e.uniforms && r._uniforms.setMany(e.uniforms), r;
+    const i = new _(t, e);
+    return e.vertex && e.fragment && i.shader(e.vertex, e.fragment), e.uniforms && i._uniforms.setMany(e.uniforms), i;
   }
   /**
    * Initialize WebGL context.
@@ -687,9 +708,9 @@ class _ {
     }, e = this.canvas.getContext("webgl2", t);
     if (e)
       return this._version = 2, e;
-    const r = this.canvas.getContext("webgl", t);
-    if (r)
-      return this._version = 1, r;
+    const i = this.canvas.getContext("webgl", t);
+    if (i)
+      return this._version = 1, i;
     const s = new w("not_supported");
     throw this.options.onError(s), s;
   }
@@ -702,8 +723,8 @@ class _ {
   /**
    * Set viewport dimensions.
    */
-  viewport(t, e, r, s) {
-    return this.canvas.width = r, this.canvas.height = s, this.gl.viewport(t, e, r, s), this._resolution = [r, s], this;
+  viewport(t, e, i, s) {
+    return this.canvas.width = i, this.canvas.height = s, this.gl.viewport(t, e, i, s), this._resolution = [i, s], this;
   }
   /**
    * Set the clock time
@@ -742,10 +763,10 @@ class _ {
   shader(t, e) {
     try {
       this._program.compile(t, e), this._version = this._program.getVersion(), this._geometry.linkAttributes(this._program);
-      const r = this._program.getProgram();
-      r && this._uniforms.attachProgram(r);
-    } catch (r) {
-      r instanceof u && this.options.onError(r);
+      const i = this._program.getProgram();
+      i && this._uniforms.attachProgram(i), this.options.onLoad();
+    } catch (i) {
+      i instanceof u && this.options.onError(i);
     }
     return this;
   }
@@ -781,6 +802,12 @@ class _ {
   getVersion() {
     return this._version;
   }
+  /**
+   * Get the clock instance
+   */
+  getClock() {
+    return this._clock;
+  }
   /**
    * Cleanup all resources.
    */
@@ -822,7 +849,7 @@ void main() {
   vec3 color = vec3(uv.x, uv.y, 0.5 + 0.5 * sin(u_time));
   gl_FragColor = vec4(color, 1.0);
 }
-`, y = `#version 300 es
+`, E = `#version 300 es
 
 in vec2 a_position;
 in vec2 a_texcoord;
@@ -832,7 +859,7 @@ out vec2 v_texcoord;
 void main() {
     v_texcoord = a_texcoord;
     gl_Position = vec4(a_position, 0.0, 1.0);
-}`, M = `#version 300 es
+}`, V = `#version 300 es
 precision highp float;
 
 uniform vec2 u_resolution;
@@ -847,17 +874,19 @@ void main() {
     vec3 color = vec3(uv.x, uv.y, 0.5 + 0.5 * sin(u_time));
     fragColor = vec4(color, 1.0);
 }`;
-class E {
+class y {
   constructor(t, e) {
     /** Active event listeners */
-    i(this, "listeners", []);
+    r(this, "listeners", []);
     /** HTML canvas element */
-    i(this, "canvas");
+    r(this, "canvasEl");
     /** Resolved options */
-    i(this, "options");
+    r(this, "options");
     /** WebGL engine */
-    i(this, "engine");
-    this.canvas = t, this.options = this.resolveOptions(e), this.engine = _.setup(this.canvas, this.options), this.setupListeners(), this.setViewport(), this.options.onLoad(), this.options.autoplay && this.play();
+    r(this, "engine");
+    /** User sets custom vertex shader */
+    r(this, "usingCustomVertex", !1);
+    this.canvasEl = t, this.options = this.resolveOptions(e), this.engine = _.setup(this.canvasEl, this.options), this.setupListeners(), this.setViewport(), this.options.autoplay && this.play();
   }
   /**
    * Sandbox - A lightweight WebGL wrapper for shader effects.
@@ -878,7 +907,7 @@ class E {
    * });
    */
   static create(t, e) {
-    return new E(t, e);
+    return new y(t, e);
   }
   resolveOptions(t) {
     const e = {
@@ -887,12 +916,13 @@ class E {
       autoplay: !0,
       pauseWhenHidden: !0,
       dpr: "auto",
+      fps: 0,
       preserveDrawingBuffer: !1,
       antialias: !0,
-      onError: (r) => {
+      onError: (i) => {
         console.error(
           "Oops!",
-          r,
+          i,
           `
 You can handle errors programmatically by providing an onError callback to suppress this log and implement custom fallback behavior.`
         );
@@ -903,13 +933,13 @@ You can handle errors programmatically by providing an onError callback to suppr
       onAfterRender: null,
       uniforms: {}
     };
-    if (t != null && t.vertex && !(t != null && t.fragment)) {
-      const r = h.detectVersion(t.vertex);
-      e.vertex = t.vertex, e.fragment = r === 2 ? M : A;
+    if (t != null && t.vertex && (this.usingCustomVertex = !0), t != null && t.vertex && !(t != null && t.fragment)) {
+      const i = a.detectVersion(t.vertex);
+      e.vertex = t.vertex, e.fragment = i === 2 ? V : A;
     }
     if (t != null && t.fragment && !(t != null && t.vertex)) {
-      const r = h.detectVersion(t.fragment);
-      e.fragment = t.fragment, e.vertex = r === 2 ? y : g;
+      const i = a.detectVersion(t.fragment);
+      e.fragment = t.fragment, e.vertex = i === 2 ? E : g;
     }
     return { ...e, ...t };
   }
@@ -920,7 +950,7 @@ You can handle errors programmatically by providing an onError callback to suppr
         this.setViewport();
       }),
       // Canvas resize
-      l.on(this.canvas, "resize", () => {
+      l.on(this.canvasEl, "resize", () => {
         this.setViewport();
       }),
       // Visibility check on scroll
@@ -944,21 +974,21 @@ You can handle errors programmatically by providing an onError callback to suppr
     this.listeners.forEach((t) => t()), this.listeners = [];
   }
   setViewport() {
-    const t = this.options.dpr === "auto" ? Math.min(2, window.devicePixelRatio || 1) : this.options.dpr, e = this.canvas.clientWidth || this.canvas.width || 1, r = this.canvas.clientHeight || this.canvas.height || 1;
+    const t = this.options.dpr === "auto" ? Math.min(2, window.devicePixelRatio || 1) : this.options.dpr, e = this.canvasEl.clientWidth || this.canvasEl.width || 1, i = this.canvasEl.clientHeight || this.canvasEl.height || 1;
     this.engine.viewport(
       0,
       0,
       Math.max(1, Math.floor(e * t)),
-      Math.max(1, Math.floor(r * t))
+      Math.max(1, Math.floor(i * t))
     );
   }
   isInViewport() {
-    const t = this.canvas.getBoundingClientRect();
+    const t = this.canvasEl.getBoundingClientRect();
     return t.bottom >= 0 && t.right >= 0 && t.top <= (window.innerHeight || document.documentElement.clientHeight) && t.left <= (window.innerWidth || document.documentElement.clientWidth);
   }
   setMouse(t, e) {
-    const r = this.canvas.getBoundingClientRect();
-    t >= r.left && t <= r.right && e >= r.top && e <= r.bottom && this.engine.mouse(t - r.left, e - r.top);
+    const i = this.canvasEl.getBoundingClientRect();
+    t >= i.left && t <= i.right && e >= i.top && e <= i.bottom && this.engine.mouse(t - i.left, e - i.top);
   }
   /**
    * Set a single uniform value with type checking.
@@ -999,7 +1029,7 @@ You can handle errors programmatically by providing an onError callback to suppr
    * sandbox.setShader(vertexSource, fragmentSource);
    */
   setShader(t, e) {
-    return this.engine.shader(t, e), this;
+    return this.options.vertex = t, this.options.fragment = e, this.usingCustomVertex = !0, this.engine.shader(this.options.vertex, this.options.fragment), this;
   }
   /**
    * Update only fragment shader (uses default vertex).
@@ -1007,8 +1037,18 @@ You can handle errors programmatically by providing an onError callback to suppr
    * sandbox.setFragment(fragmentSource);
    */
   setFragment(t) {
-    const r = this.webglVersion() === 1 ? g : y;
-    return this.engine.shader(r, t), this;
+    const e = a.detectVersion(t), i = a.detectVersion(this.options.vertex);
+    return this.options.fragment = t, e !== i && (this.usingCustomVertex || (this.options.vertex = e === 2 ? E : g)), this.engine.shader(this.options.vertex, this.options.fragment), this;
+  }
+  /**
+   * Set the max frame rate runtime
+   * 
+   * @example
+   * sandbox.setFps(30); // Limit to 30 FPS
+   * sandbox.setFps(0);  // Unlimited FPS
+   */
+  setFps(t) {
+    return this.engine.getClock().setMaxFps(t), this;
   }
   /**
    * Add a runtime render hook.
@@ -1038,8 +1078,8 @@ You can handle errors programmatically by providing an onError callback to suppr
    * Pause animation loop at specific time (in seconds).
    */
   pauseAt(t) {
-    const e = this.hook((r) => {
-      r.time >= t && (e(), this.pause());
+    const e = this.hook((i) => {
+      i.time >= t && (e(), this.pause());
     }, "after");
     return this;
   }
@@ -1080,14 +1120,14 @@ You can handle errors programmatically by providing an onError callback to suppr
   /**
    * Get WebGL version using (1 or 2).
    */
-  webglVersion() {
+  get version() {
     return this.engine.getVersion();
   }
   /**
    * Get canvas element.
    */
-  canvasElement() {
-    return this.canvas;
+  get canvas() {
+    return this.canvasEl;
   }
   /**
    * Destroy sandbox and release all resources.
@@ -1101,7 +1141,7 @@ You can handle errors programmatically by providing an onError callback to suppr
   }
 }
 export {
-  E as Sandbox,
+  y as Sandbox,
   w as SandboxContextError,
   u as SandboxError,
   m as SandboxProgramError,

package/dist/tools/clock.d.ts

@@ -12,10 +12,13 @@ export default class Clock {
     frame: number;
     /** Is clock running */
     running: boolean;
+    /** Smoothed frames per second */
+    fps: number;
     private startTime;
     private lastTime;
     private rafId;
     private callback;
+    private maxFps;
     constructor();
     /**
      * Start the animation loop with a render callback.
@@ -47,6 +50,10 @@ export default class Clock {
      * Cleanup.
      */
     destroy(): void;
+    /**
+     * Set maximum frames per second.
+     */
+    setMaxFps(fps: number): this;
     /**
      * Internal animation frame handler.
      */

package/dist/tools/web_gl.d.ts

@@ -1,4 +1,5 @@
 import type { AnyUniformValue, ResolvedSandboxOptions, UniformSchema, WebGLContext, WebGLVersion } from "../types";
+import Clock from "./clock";
 import Hooks from "./hooks";
 /**
  * Main WebGL orchestrator.
@@ -82,6 +83,10 @@ export default class WebGL {
      * Get detected WebGL version.
      */
     getVersion(): WebGLVersion;
+    /**
+     * Get the clock instance
+     */
+    getClock(): Clock;
     /**
      * Cleanup all resources.
      */

package/dist/types.d.ts

@@ -11,6 +11,8 @@ export interface SandboxOptions {
     pauseWhenHidden?: boolean;
     /** Device pixel ratio - "auto" uses window.devicePixelRatio (default: "auto") */
     dpr?: number | "auto";
+    /** Max Frame rate (default: 0 as unlimited) */
+    fps?: number;
     /** Preserve drawing buffer for screenshots (default: false) */
     preserveDrawingBuffer?: boolean;
     /** Enable antialiasing (default: true) */
@@ -95,6 +97,10 @@ export interface ClockState {
     delta: number;
     /** Frame counter */
     frame: number;
+    /** Is the clock currently running */
+    running: boolean;
+    /** Frame rate in frames per second */
+    fps: number;
 }
 /** Internal uniform entry for caching */
 export interface UniformEntry {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rosalana/sandbox",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Lightweight WebGL wrapper for simple, beautiful shader effects",
   "keywords": [
     "webgl",