@rosalana/sandbox 0.0.1

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rosalana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,361 @@
+[![Rosalana](https://raw.githubusercontent.com/rosalana/.github/main/Sandbox_Banner.png)](https://github.com/rosalana)
+
+**Rosalana Sandbox** is a lightweight WebGL wrapper for **simple, beautiful shader effects**. It focuses on a clean API, type safety, and fast setup so you can go from idea to a shader in minutes.
+
+It's **DX‑friendly**, small, and intentionally minimal — perfect for gradients, ambient backgrounds, and animated GLSL experiments. If you're not building a full 3D engine, Sandbox is a delightful alternative to larger libraries like three.js or p5.js.
+
+### Bundle size comparison
+
+| Library       | Minified | Gzipped  |
+| ------------- | -------- | -------- |
+| **Sandbox**   | 31 KB    | **8 KB** |
+| three.js      | 694 KB   | 175 KB   |
+| p5.js         | 1.1 MB   | 351 KB   |
+
+Sandbox is **~22x smaller** than three.js and **~44x smaller** than p5.js.
+
+It works in both **WebGL1 and WebGL2** contexts, with automatic fallback and detection.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick setup](#quick-setup)
+- [Playback control](#playback-control)
+  - [Time control](#time-control)
+  - [Static rendering](#static-rendering)
+- [Shaders](#shaders)
+  - [WebGL version detection](#webgl-version-detection)
+- [Uniforms](#uniforms)
+- [Built‑in uniforms](#built-in-uniforms)
+- [Hooks](#hooks)
+  - [Self-removing hooks](#self-removing-hooks)
+- [Chaining](#chaining)
+- [Error handling](#error-handling)
+- [Vue integration](#vue-integration)
+- [Cleanup](#cleanup)
+- [Options](#options)
+- [Limitations (by design)](#limitations-by-design)
+- [License](#license)
+
+## Installation
+
+```bash
+npm install @rosalana/sandbox
+```
+
+## Quick setup
+
+Sandbox is designed to get you up and running with minimal effort. It ships with sensible defaults, so in most cases it only takes a few lines of code to get started.
+
+```ts
+import { Sandbox } from "@rosalana/sandbox";
+
+const sandbox = Sandbox.create(canvas, {
+  fragment: fragSource,
+});
+```
+
+That's it. You get a running render loop and a fullscreen quad. No WebGL ceremony, no boilerplate — just your shader doing its thing.
+
+## Playback control
+
+Autoplay is enabled by default, so your shader starts rendering immediately. But you're in full control — pause, play, scrub through time, whatever you need.
+
+```ts
+sandbox.play();
+sandbox.pause();
+sandbox.toggle();
+```
+
+Want to know if it's running?
+
+```ts
+sandbox.isPlaying();
+```
+
+### Time control
+
+This is where it gets fun. You can jump to any point in time, which is perfect for debugging or creating deterministic renders.
+
+Start playing from a specific moment:
+
+```ts
+sandbox.playAt(2.5);
+```
+
+Or set up an auto-pause — great for intro animations that should stop after a few seconds:
+
+```ts
+sandbox.pauseAt(10);
+```
+
+### Static rendering
+
+Sometimes you don't need animation at all. Maybe you're generating a gradient thumbnail or rendering a single frame for export.
+
+```ts
+const sandbox = Sandbox.create(canvas, {
+  fragment: fragSource,
+  autoplay: false,
+});
+
+sandbox.render();
+```
+
+Or render at a specific time — perfect for deterministic, reproducible output:
+
+```ts
+sandbox.renderAt(1.5);
+```
+
+## Shaders
+
+Shaders are the only thing you need to provide. Sandbox comes with a default fullscreen vertex shader, so you usually don't need to write one yourself — and it automatically switches between WebGL1 and WebGL2 versions depending on your fragment shader.
+
+Update your fragment shader on the fly:
+
+```ts
+sandbox.setFragment(fragmentSource);
+```
+
+When you need full control over both vertex and fragment:
+
+```ts
+sandbox.setShader(vertexSource, fragmentSource);
+```
+
+### WebGL version detection
+
+Sandbox figures out which WebGL version you're using by looking at your shader code:
+
+- `#version 300 es` → WebGL2
+- no version directive → WebGL1
+
+If WebGL2 isn't available, Sandbox falls back to WebGL1 automatically. You can always check what you're running:
+
+```ts
+sandbox.webglVersion();
+```
+
+## Uniforms
+
+Uniforms are how you feed data into your shader. Sandbox makes them **type‑safe** and **chainable** — no more guessing what went wrong.
+
+Set a single uniform:
+
+```ts
+sandbox.setUniform<number>("u_intensity", 0.8);
+```
+
+Set multiple uniforms at once:
+
+```ts
+sandbox.setUniforms<{
+  u_intensity: number;
+  u_color: Vec3;
+}>({
+  u_intensity: 0.75,
+  u_color: [1, 0.2, 0.3],
+});
+```
+
+Read back a uniform value:
+
+```ts
+const intensity = sandbox.getUniform<number>("u_intensity");
+```
+
+All numeric values are treated as floats. This keeps the API simple and predictable.
+
+## Built‑in uniforms
+
+These uniforms are filled automatically every frame — no setup needed. Just declare them in your shader and they work:
+
+| Uniform        | Type  | Description                 |
+| -------------- | ----- | --------------------------- |
+| `u_resolution` | vec2  | Canvas size in pixels       |
+| `u_time`       | float | Elapsed time (seconds)      |
+| `u_delta`      | float | Delta time since last frame |
+| `u_mouse`      | vec2  | Mouse position on canvas    |
+| `u_frame`      | int   | Frame counter               |
+
+## Hooks
+
+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.
+
+**Pre-compute values on the CPU** before they hit the shader:
+
+```ts
+sandbox.hook(({ time }) => {
+  const intensity = (Math.sin(time) + 1) / 2;
+  sandbox.setUniform("u_intensity", intensity);
+}, "before");
+```
+
+**Sync state with reactive frameworks** like Vue or React:
+
+```ts
+const playing = ref(false);
+
+sandbox.hook(() => {
+  playing.value = sandbox.isPlaying();
+}, "after");
+```
+
+The hook returns a removal function, so you can clean up whenever you want:
+
+```ts
+const remove = sandbox.hook(({ time }) => {
+  console.log(time);
+}, "after");
+
+remove();
+```
+
+### Self-removing hooks
+
+Sometimes you need a hook that runs only until a condition is met. Just return `false` and the hook removes itself:
+
+```ts
+sandbox.hook(({ time }) => {
+  if (time > 5) return false;
+}, "after");
+```
+
+This is how `pauseAt()` works internally — it's hooks all the way down.
+
+## Chaining
+
+Every method returns `this`, so you can chain calls for clean, expressive code:
+
+```ts
+sandbox
+  .setUniforms({ u_color: [1, 0, 0] })
+  .time(2.5)
+  .render();
+```
+
+## Error handling
+
+Shader errors happen — typos, syntax mistakes, driver quirks. Sandbox handles them gracefully and reports them via a single callback. No try/catch needed.
+
+```ts
+Sandbox.create(canvas, {
+  fragment: shader,
+  onError: (error) => {
+    console.error(error.message);
+  },
+});
+```
+
+The error object includes useful details:
+
+- `error.code` — error type (`SHADER_COMPILATION_FAILED`, `PROGRAM_LINK_FAILED`, etc.)
+- `error.lines` — line numbers where errors occurred (for compilation errors)
+- `error.shaderType` — which shader failed (`vertex` or `fragment`)
+
+Error codes: `WEBGL_NOT_SUPPORTED`, `SHADER_COMPILATION_FAILED`, `PROGRAM_LINK_FAILED`, `SHADER_VERSION_MISMATCH`
+
+## Vue integration
+
+Here's a complete example showing how to use Sandbox with Vue's reactivity system:
+
+```vue
+<script setup lang="ts">
+import { shallowRef, ref, onMounted, onUnmounted } from "vue";
+import { Sandbox } from "@rosalana/sandbox";
+
+const canvasRef = ref<HTMLCanvasElement>();
+const sandbox = shallowRef<Sandbox | null>(null);
+const isPlaying = ref(false);
+
+onMounted(() => {
+  sandbox.value = Sandbox.create(canvasRef.value!, {
+    onAfterRender: () => {
+      isPlaying.value = sandbox.value?.isPlaying() ?? false;
+    },
+  });
+});
+
+onUnmounted(() => {
+  sandbox.value?.destroy();
+});
+</script>
+
+<template>
+  {{ isPlaying ? "Playing" : "Paused" }}
+  <canvas ref="canvasRef" />
+</template>
+```
+
+Use `shallowRef` for the Sandbox instance — you don't want Vue making the WebGL context reactive.
+
+## Cleanup
+
+Always destroy when you're done. This releases all WebGL resources and removes event listeners:
+
+```ts
+sandbox.destroy();
+```
+
+In frameworks like Vue:
+
+```ts
+onUnmounted(() => {
+  sandbox.destroy();
+});
+```
+
+## Options
+
+```ts
+interface SandboxOptions {
+  vertex?: string;
+  fragment?: string;
+  autoplay?: boolean;
+  pauseWhenHidden?: boolean;
+  dpr?: number | "auto";
+  preserveDrawingBuffer?: boolean;
+  antialias?: boolean;
+  onError?: (error: SandboxError) => void;
+  onLoad?: () => void;
+  onBeforeRender?: HookCallback | null;
+  onAfterRender?: HookCallback | null;
+  uniforms?: UniformSchema;
+}
+```
+
+| 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          |
+
+## Limitations (by design)
+
+- No textures (planned for future)
+- No multi‑pass rendering
+- No 3D scene graph
+
+If you need a full engine, reach for three.js. For clean shader‑only effects, Sandbox is a joy to use.
+
+## License
+
+Rosalana Sandbox is open-source under the [MIT license](/LICENCE), allowing you to freely use, modify, and distribute it with minimal restrictions.
+
+You may not be able to use our systems but you can use our code to build your own.
+
+For details on how to contribute or how the Rosalana ecosystem is maintained, please refer to each repository's individual guidelines.
+
+**Questions or feedback?**
+
+Feel free to open an issue or contribute with a pull request. Happy coding with Rosalana!

package/dist/errors.d.ts

@@ -0,0 +1,32 @@
+/** Error codes for Sandbox errors */
+export type SandboxErrorCode = "WEBGL_NOT_SUPPORTED" | "CONTEXT_CREATION_FAILED" | "SHADER_COMPILATION_FAILED" | "PROGRAM_LINK_FAILED" | "SHADER_VERSION_MISMATCH" | "UNKNOWN_ERROR";
+/** Base error class for all Sandbox errors */
+export declare class SandboxError extends Error {
+    readonly code: SandboxErrorCode;
+    constructor(message: string, code: SandboxErrorCode);
+}
+/** WebGL context creation failure */
+export declare class SandboxContextError extends SandboxError {
+    constructor(reason: "not_supported" | "creation_failed");
+}
+export declare class SandboxShaderVersionMismatchError extends SandboxError {
+    readonly vertexVersion: number;
+    readonly fragmentVersion: number;
+    constructor(vertexVersion: number, fragmentVersion: number);
+}
+/** Shader compilation failure with line info extraction */
+export declare class SandboxShaderCompilationError extends SandboxError {
+    readonly shaderType: "vertex" | "fragment";
+    readonly source: string;
+    readonly infoLog: string;
+    /** Line numbers where errors occurred */
+    readonly lines: number[];
+    constructor(shaderType: "vertex" | "fragment", source: string, infoLog: string);
+    /** Parse error log to extract line numbers */
+    private static parseErrorLines;
+}
+/** Shader program linking failure */
+export declare class SandboxProgramError extends SandboxError {
+    readonly infoLog: string;
+    constructor(infoLog: string);
+}

package/dist/index.cjs.js

@@ -0,0 +1,57 @@
+"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 c extends l{constructor(e,r,s){const n=c.parseErrorLines(s),a=n.length>0?` at line(s): ${n.join(", ")}`:"";super(`${e} shader compilation failed${a}
+
+${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 f=parseInt(a[1],10);f>0&&s.add(f)}}return[...s].sort((n,a)=>n-a)}}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.startTime=e,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.stop(),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 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)}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
+precision mediump float;
+#endif
+
+attribute vec2 a_position;
+attribute vec2 a_texcoord;
+
+varying vec2 v_texcoord;
+
+void main() {
+  v_texcoord = a_texcoord;
+  gl_Position = vec4(a_position, 0.0, 1.0);
+}
+`,E=`#ifdef GL_ES
+precision mediump float;
+#endif
+
+uniform vec2 u_resolution;
+uniform float u_time;
+
+varying vec2 v_texcoord;
+
+void main() {
+  vec2 uv = v_texcoord;
+  vec3 color = vec3(uv.x, uv.y, 0.5 + 0.5 * sin(u_time));
+  gl_FragColor = vec4(color, 1.0);
+}
+`,y=`#version 300 es
+
+in vec2 a_position;
+in vec2 a_texcoord;
+
+out vec2 v_texcoord;
+
+void main() {
+    v_texcoord = a_texcoord;
+    gl_Position = vec4(a_position, 0.0, 1.0);
+}`,M=`#version 300 es
+precision highp float;
+
+uniform vec2 u_resolution;
+uniform float u_time;
+uniform vec2 u_mouse;
+
+in vec2 v_texcoord;
+out vec4 fragColor;
+
+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:E,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:E}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}return{...e,...t}}setupListeners(){this.listeners.push(u.on(window,"resize",()=>{this.setViewport()}),u.on(this.canvas,"resize",()=>{this.setViewport()}),u.on(document,"scroll",()=>{this.options.pauseWhenHidden&&(this.isInViewport()?this.play():this.pause())}),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:y;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=c;exports.SandboxShaderVersionMismatchError=L;

package/dist/index.d.ts

@@ -0,0 +1,156 @@
+import type { AnyUniformValue, HookCallback, SandboxOptions, UniformSchema, WebGLVersion } from "./types";
+export * from "./types";
+export * from "./errors";
+/**
+ * Sandbox - A lightweight WebGL wrapper for shader effects.
+ *
+ * @example
+ * // Static rendering
+ * const sandbox = new Sandbox(canvas, {
+ *   fragment: myShader,
+ *   autoplay: false,
+ * });
+ * sandbox.setUniforms({ u_time: 1.5 }).render();
+ *
+ * @example
+ * // Animation loop
+ * const sandbox = new Sandbox(canvas, {
+ *   fragment: myShader,
+ *   autoplay: true,
+ * });
+ */
+export declare class Sandbox {
+    /** Active event listeners */
+    private listeners;
+    /** HTML canvas element */
+    private canvas;
+    /** Resolved options */
+    private options;
+    /** WebGL engine */
+    private engine;
+    constructor(canvas: HTMLCanvasElement, options?: SandboxOptions);
+    /**
+     * Sandbox - A lightweight WebGL wrapper for shader effects.
+     *
+     * @example
+     * // Static rendering
+     * const sandbox = Sandbox.create(canvas, {
+     *   fragment: myShader,
+     *   autoplay: false,
+     * });
+     * sandbox.setUniforms({ u_time: 1.5 }).render();
+     *
+     * @example
+     * // Animation loop
+     * const sandbox = Sandbox.create(canvas, {
+     *   fragment: myShader,
+     *   autoplay: true,
+     * });
+     */
+    static create(canvas: HTMLCanvasElement, options?: SandboxOptions): Sandbox;
+    private resolveOptions;
+    private setupListeners;
+    private destroyListeners;
+    private setViewport;
+    private isInViewport;
+    private setMouse;
+    /**
+     * Set a single uniform value with type checking.
+     * @example
+     * sandbox.setUniform<Vec3>("u_color", [1, 0, 0]);
+     * sandbox.setUniform<number>("u_time", 1.5);
+     * sandbox.setUniform<Vec3[]>("u_colors", [[1, 0, 0], [0, 1, 0]]);
+     */
+    setUniform<T extends AnyUniformValue>(name: string, value: T): this;
+    /**
+     * Set multiple uniforms at once with type checking.
+     * @example
+     * interface MyUniforms extends UniformSchema {
+     *   u_time: number;
+     *   u_resolution: Vec2;
+     *   u_colors: Vec3[];
+     * }
+     * sandbox.setUniforms<MyUniforms>({
+     *   u_time: 1.5,
+     *   u_resolution: [800, 600],
+     *   u_colors: [[1, 0, 0], [0, 1, 0]],
+     * });
+     */
+    setUniforms<T extends UniformSchema>(uniforms: T): this;
+    /**
+     * Get current uniform value.
+     */
+    getUniform<T extends AnyUniformValue>(name: string): T | undefined;
+    /**
+     * Update shaders.
+     * @example
+     * sandbox.setShader(vertexSource, fragmentSource);
+     */
+    setShader(vertex: string, fragment: string): this;
+    /**
+     * Update only fragment shader (uses default vertex).
+     * @example
+     * sandbox.setFragment(fragmentSource);
+     */
+    setFragment(fragment: string): this;
+    /**
+     * Add a runtime render hook.
+     */
+    hook(callback: HookCallback, when?: "before" | "after"): () => void;
+    /**
+     * Start animation loop.
+     */
+    play(): this;
+    /**
+     * Start animation loop at specific time (in seconds).
+     */
+    playAt(time: number): this;
+    /**
+     * Stop animation loop.
+     */
+    pause(): this;
+    /**
+     * Pause animation loop at specific time (in seconds).
+     */
+    pauseAt(time: number): this;
+    /**
+     * Toggle play/pause state.
+     */
+    toggle(): this;
+    /**
+     * Set current time (in seconds).
+     */
+    time(time: number): this;
+    /**
+     * Render a single frame (for static rendering).
+     * @example
+     * sandbox.time(1.4).render();
+     */
+    render(): this;
+    /**
+     * Render at specific time (for deterministic output).
+     * @example
+     * sandbox.renderAt(2.5); // Render as if 2.5 seconds elapsed
+     */
+    renderAt(time: number): this;
+    /**
+     * Check if currently playing.
+     */
+    isPlaying(): boolean;
+    /**
+     * Get WebGL version using (1 or 2).
+     */
+    webglVersion(): WebGLVersion;
+    /**
+     * Get canvas element.
+     */
+    canvasElement(): HTMLCanvasElement;
+    /**
+     * Destroy sandbox and release all resources.
+     * @example
+     * onUnmounted(() => {
+     *   sandbox.destroy();
+     * });
+     */
+    destroy(): void;
+}