@rosalana/sandbox 0.0.1

package/dist/tools/clock.d.ts

@@ -0,0 +1,54 @@
+import type { ClockState, HookCallback } from "../types";
+/**
+ * High-precision animation timing using requestAnimationFrame.
+ * Tracks elapsed time, delta time, and frame count.
+ */
+export default class Clock {
+    /** Total elapsed time in seconds */
+    time: number;
+    /** Delta time since last frame in seconds */
+    delta: number;
+    /** Frame counter */
+    frame: number;
+    /** Is clock running */
+    running: boolean;
+    private startTime;
+    private lastTime;
+    private rafId;
+    private callback;
+    constructor();
+    /**
+     * Start the animation loop with a render callback.
+     */
+    start(callback: HookCallback): this;
+    /**
+     * Stop the animation loop.
+     * Clock state is preserved for resume.
+     */
+    stop(): this;
+    /**
+     * Reset clock to initial state.
+     */
+    reset(): this;
+    /**
+     * Get current clock state snapshot.
+     */
+    getState(): ClockState;
+    /**
+     * Advance clock by one tick (for single-shot rendering).
+     * Useful when autoplay is disabled.
+     */
+    tick(dt?: number): this;
+    /**
+     * Set time directly (for deterministic rendering).
+     */
+    setTime(time: number): this;
+    /**
+     * Cleanup.
+     */
+    destroy(): void;
+    /**
+     * Internal animation frame handler.
+     */
+    private loop;
+}

package/dist/tools/geometry.d.ts

@@ -0,0 +1,62 @@
+import type { WebGLContext } from "../types";
+import Program from "./program";
+/**
+ * Manages vertex buffers and geometry for rendering.
+ * Handles WebGL1 vs WebGL2 VAO differences automatically.
+ */
+export default class Geometry {
+    private gl;
+    private vao;
+    private vbo;
+    private ibo;
+    private vertexCount;
+    private indexCount;
+    private useIndices;
+    private vaoExt;
+    private isWebGL2;
+    constructor(gl: WebGLContext);
+    /**
+     * Create a fullscreen quad geometry.
+     * This is the most common use case for shader effects.
+     */
+    static fullscreenQuad(gl: WebGLContext): Geometry;
+    /**
+     * Setup geometry from vertex and index data.
+     */
+    setup(vertices: Float32Array, indices?: Uint16Array): this;
+    /**
+     * Link vertex attributes to shader program.
+     * Call this after compiling shaders.
+     */
+    linkAttributes(program: Program): this;
+    /**
+     * Bind geometry for rendering.
+     */
+    bind(): this;
+    /**
+     * Unbind geometry.
+     */
+    unbind(): this;
+    /**
+     * Draw the geometry.
+     */
+    draw(): this;
+    /**
+     * Cleanup all GPU resources.
+     */
+    destroy(): void;
+    /**
+     * Get position attribute location.
+     * Tries common naming conventions.
+     */
+    private getPositionLocation;
+    /**
+     * Get texcoord attribute location.
+     * Tries common naming conventions.
+     */
+    private getTexcoordLocation;
+    private createVAO;
+    private bindVAO;
+    private unbindVAO;
+    private deleteVAO;
+}

package/dist/tools/hooks.d.ts

@@ -0,0 +1,12 @@
+import { ClockState, HookCallback } from "../types";
+export default class Hooks {
+    private hooks;
+    private id;
+    /** Add a new hook, returns a removal function */
+    add(hook: HookCallback): () => void;
+    /** Remove a hook by its ID */
+    remove(id: string): void;
+    /** Run all hooks with the given state */
+    run(state: ClockState): void;
+    destroy(): void;
+}

package/dist/tools/listener.d.ts

@@ -0,0 +1,11 @@
+type EventMap<T extends EventTarget> = T extends Window ? WindowEventMap : T extends Document ? DocumentEventMap : T extends HTMLElement ? HTMLElementEventMap : Record<string, Event>;
+export default class Listener<T extends EventTarget = EventTarget, K extends keyof EventMap<T> = keyof EventMap<T>> {
+    private target;
+    private type;
+    private listener;
+    private options?;
+    constructor(target: T, type: K, listener: (event: EventMap<T>[K]) => void, options?: (boolean | AddEventListenerOptions) | undefined);
+    remove(): void;
+    static on<T extends EventTarget, K extends keyof EventMap<T>>(target: T, type: K, listener: (event: EventMap<T>[K]) => void, options?: AddEventListenerOptions): () => void;
+}
+export {};

package/dist/tools/program.d.ts

@@ -0,0 +1,58 @@
+import type { WebGLContext, WebGLVersion } from "../types";
+/**
+ * Manages shader compilation and program linking.
+ * Automatically detects WebGL version from shader source.
+ */
+export default class Program {
+    private gl;
+    private program;
+    private vertexShader;
+    private fragmentShader;
+    private version;
+    constructor(gl: WebGLContext);
+    /**
+     * Detect WebGL version from shader source.
+     * Looks for "#version 300 es" directive.
+     */
+    static detectVersion(source: string): WebGLVersion;
+    /**
+     * Compile shaders and link program.
+     * @throws ShaderCompilationError if compilation fails
+     * @throws ProgramLinkError if linking fails
+     */
+    compile(vertexSource: string, fragmentSource: string): this;
+    /**
+     * Bind this program for rendering.
+     */
+    use(): this;
+    /**
+     * Get the compiled WebGL program.
+     */
+    getProgram(): WebGLProgram | null;
+    /**
+     * Get detected WebGL version.
+     */
+    getVersion(): WebGLVersion;
+    /**
+     * Get attribute location.
+     */
+    getAttribLocation(name: string): number;
+    /**
+     * Get uniform location.
+     */
+    getUniformLocation(name: string): WebGLUniformLocation | null;
+    /**
+     * Cleanup all GPU resources.
+     */
+    destroy(): void;
+    /**
+     * Compile a single shader.
+     * @throws ShaderCompilationError if compilation fails
+     */
+    private compileShader;
+    /**
+     * Link vertex and fragment shaders into a program.
+     * @throws ProgramLinkError if linking fails
+     */
+    private linkProgram;
+}

package/dist/tools/uniform.d.ts

@@ -0,0 +1,42 @@
+import type { AnyUniformValue, UniformMethod, WebGLContext } from "../types";
+/**
+ * Handles a single uniform variable.
+ * Caches WebGL location and infers the correct setter method from value type.
+ */
+export default class Uniform {
+    readonly name: string;
+    readonly method: UniformMethod;
+    readonly isArray: boolean;
+    readonly isMatrix: boolean;
+    private location;
+    private locationResolved;
+    private value;
+    constructor(name: string, value: AnyUniformValue);
+    /**
+     * Infer WebGL method and metadata from value type.
+     */
+    private static inferMethodInfo;
+    /**
+     * Resolve and cache uniform location from program.
+     * Returns null if uniform doesn't exist (optimized out by compiler, etc.)
+     */
+    resolveLocation(gl: WebGLContext, program: WebGLProgram): WebGLUniformLocation | null;
+    /**
+     * Invalidate cached location (call when program changes).
+     */
+    invalidateLocation(): void;
+    /**
+     * Update value (doesn't upload to GPU until upload() is called).
+     */
+    setValue(value: AnyUniformValue): void;
+    /**
+     * Get current value.
+     */
+    getValue(): AnyUniformValue;
+    /**
+     * Upload current value to GPU.
+     * @param gl - WebGL context
+     * @param program - Current WebGL program (for location resolution)
+     */
+    upload(gl: WebGLContext, program: WebGLProgram): void;
+}

package/dist/tools/uniforms.d.ts

@@ -0,0 +1,65 @@
+import type { AnyUniformValue, ClockState, UniformSchema, Vec2, WebGLContext } from "../types";
+/**
+ * Manages a collection of uniforms with fluent API.
+ * Handles built-in uniforms (u_resolution, u_time, etc.) automatically.
+ */
+export default class Uniforms {
+    private gl;
+    private program;
+    private uniforms;
+    /** Built-in uniform names that are handled automatically */
+    private static readonly BUILT_INS;
+    constructor(gl: WebGLContext);
+    /**
+     * Attach to a WebGL program.
+     * Invalidates all cached locations since they're program-specific.
+     */
+    attachProgram(program: WebGLProgram): this;
+    /**
+     * Set a uniform value.
+     * Creates the uniform if it doesn't exist, updates if it does.
+     */
+    set<T extends AnyUniformValue>(name: string, value: T): this;
+    /**
+     * Set multiple uniforms at once.
+     */
+    setMany<T extends UniformSchema>(values: T): this;
+    /**
+     * Get current uniform value.
+     */
+    get<T extends AnyUniformValue>(name: string): T | undefined;
+    /**
+     * Check if uniform exists.
+     */
+    has(name: string): boolean;
+    /**
+     * Remove a uniform.
+     */
+    delete(name: string): boolean;
+    /**
+     * Upload all uniforms to GPU.
+     * Requires a program to be attached.
+     */
+    uploadAll(): this;
+    /**
+     * Upload only built-in uniforms (u_resolution, u_time, u_delta, u_mouse, u_frame).
+     * Call this every frame with current values.
+     */
+    uploadBuiltIns(clock: ClockState, resolution: Vec2, mouse: Vec2): this;
+    /**
+     * Clear all uniforms.
+     */
+    clear(): void;
+    /**
+     * Cleanup.
+     */
+    destroy(): void;
+    /**
+     * Get all uniform names.
+     */
+    keys(): IterableIterator<string>;
+    /**
+     * Get uniform count.
+     */
+    get size(): number;
+}

package/dist/tools/web_gl.d.ts

@@ -0,0 +1,93 @@
+import type { AnyUniformValue, ResolvedSandboxOptions, UniformSchema, WebGLContext, WebGLVersion } from "../types";
+import Hooks from "./hooks";
+/**
+ * Main WebGL orchestrator.
+ * Manages context, program, geometry, uniforms, and rendering loop.
+ */
+export default class WebGL {
+    private canvas;
+    private gl;
+    private options;
+    onBeforeHooks: Hooks;
+    onAfterHooks: Hooks;
+    private _program;
+    private _geometry;
+    private _uniforms;
+    private _clock;
+    private _resolution;
+    private _mouse;
+    private _version;
+    playing: boolean;
+    private constructor();
+    /**
+     * Factory method to create and setup WebGL instance.
+     */
+    static setup(canvas: HTMLCanvasElement, options: ResolvedSandboxOptions): WebGL;
+    /**
+     * Initialize WebGL context.
+     * Tries WebGL2 first, falls back to WebGL1.
+     * Context errors are fatal but still reported via onError.
+     */
+    private initContext;
+    /**
+     * Enable useful WebGL extensions.
+     */
+    private enableExtensions;
+    /**
+     * Set viewport dimensions.
+     */
+    viewport(x: number, y: number, width: number, height: number): this;
+    /**
+     * Set the clock time
+     */
+    clock(time: number): this;
+    /**
+     * Update mouse position.
+     */
+    mouse(x: number, y: number): this;
+    /**
+     * Set a uniform value.
+     */
+    uniform<T extends AnyUniformValue>(name: string, value: T): this;
+    /**
+     * Set multiple uniforms.
+     */
+    uniforms<T extends UniformSchema>(values: T): this;
+    /**
+     * Get current uniform value.
+     */
+    getUniform<T extends AnyUniformValue>(name: string): T | undefined;
+    /**
+     * Compile and link shaders.
+     * Errors are handled via onError callback, never thrown.
+     */
+    shader(vertex: string, fragment: string): this;
+    /**
+     * Start animation loop.
+     */
+    play(): this;
+    /**
+     * Stop animation loop.
+     */
+    pause(): this;
+    /**
+     * Render a single frame.
+     */
+    render(): this;
+    /**
+     * Get WebGL context.
+     */
+    getContext(): WebGLContext;
+    /**
+     * Get detected WebGL version.
+     */
+    getVersion(): WebGLVersion;
+    /**
+     * Cleanup all resources.
+     */
+    destroy(): void;
+    /**
+     * Internal render callback.
+     */
+    private onRender;
+}

package/dist/types.d.ts

@@ -0,0 +1,111 @@
+import type { SandboxError } from "./errors";
+/** Sandbox configuration options */
+export interface SandboxOptions {
+    /** Vertex shader source code */
+    vertex?: string;
+    /** Fragment shader source code */
+    fragment?: string;
+    /** Auto-play the sandbox on creation (default: true) */
+    autoplay?: boolean;
+    /** Pause rendering when canvas not visible (default: true) */
+    pauseWhenHidden?: boolean;
+    /** Device pixel ratio - "auto" uses window.devicePixelRatio (default: "auto") */
+    dpr?: number | "auto";
+    /** Preserve drawing buffer for screenshots (default: false) */
+    preserveDrawingBuffer?: boolean;
+    /** Enable antialiasing (default: true) */
+    antialias?: boolean;
+    /** Error callback for shader compilation or runtime errors */
+    onError?: (error: SandboxError) => void;
+    /** Callback when sandbox is ready */
+    onLoad?: () => void;
+    /** Callback called each frame before render */
+    onBeforeRender?: HookCallback | null;
+    /** Callback called each frame after render */
+    onAfterRender?: HookCallback | null;
+    /** Initial uniforms to set */
+    uniforms?: UniformSchema;
+}
+/** Resolved sandbox options with all defaults applied */
+export type ResolvedSandboxOptions = Required<SandboxOptions>;
+/** WebGL version (1 = WebGL, 2 = WebGL2) */
+export type WebGLVersion = 1 | 2;
+/** Union of WebGL context types */
+export type WebGLContext = WebGLRenderingContext | WebGL2RenderingContext;
+/** Vector types as tuples */
+export type Vec2 = [number, number];
+export type Vec3 = [number, number, number];
+export type Vec4 = [number, number, number, number];
+/** Matrix types (column-major, as WebGL expects) */
+export type Mat2 = [number, number, number, number];
+export type Mat3 = [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number
+];
+export type Mat4 = [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number
+];
+/** Single uniform value types (scalars and vectors) */
+export type UniformValue = number | boolean | Vec2 | Vec3 | Vec4 | Mat2 | Mat3 | Mat4;
+/** Array uniform types (for u_colors[10], u_positions[10], etc.) */
+export type UniformArrayValue = number[] | Vec2[] | Vec3[] | Vec4[];
+/** All valid uniform value types */
+export type AnyUniformValue = UniformValue | UniformArrayValue;
+/**
+ * Helper type for defining uniform schemas.
+ * @example
+ * interface GradientUniforms extends UniformSchema {
+ *   u_time: number;
+ *   u_resolution: Vec2;
+ *   u_colors: Vec3[];
+ * }
+ */
+export interface UniformSchema {
+    [key: string]: AnyUniformValue;
+}
+/** WebGL uniform setter method names */
+export type UniformMethod = "uniform1f" | "uniform1i" | "uniform1fv" | "uniform2fv" | "uniform3fv" | "uniform4fv" | "uniformMatrix2fv" | "uniformMatrix3fv" | "uniformMatrix4fv";
+/** Clock state passed to render callbacks */
+export interface ClockState {
+    /** Total elapsed time in seconds */
+    time: number;
+    /** Delta time since last frame in seconds */
+    delta: number;
+    /** Frame counter */
+    frame: number;
+}
+/** Internal uniform entry for caching */
+export interface UniformEntry {
+    name: string;
+    location: WebGLUniformLocation | null;
+    method: UniformMethod;
+    value: AnyUniformValue;
+    isArray: boolean;
+    needsTranspose: boolean;
+}
+/** Geometry draw mode */
+export type DrawMode = "TRIANGLES" | "TRIANGLE_STRIP" | "TRIANGLE_FAN";
+/** Render callback signature */
+export type HookCallback = (clock: ClockState) => void | false;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@rosalana/sandbox",
+  "version": "0.0.1",
+  "description": "Lightweight WebGL wrapper for simple, beautiful shader effects",
+  "keywords": [
+    "webgl",
+    "shader",
+    "glsl",
+    "canvas",
+    "graphics",
+    "animation",
+    "fragment-shader",
+    "webgl2",
+    "gpu",
+    "effects"
+  ],
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.cjs.js",
+  "module": "./dist/index.es.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.cjs.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev:vite": "vite build --watch",
+    "dev:tsc": "tsc --declaration --emitDeclarationOnly --watch",
+    "typecheck": "tsc --noEmit",
+    "dev": "npm run build -- --watch",
+    "build": "vite build && tsc --declaration --emitDeclarationOnly",
+    "clean": "rm -rf dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rosalana/sandbox.git"
+  },
+  "homepage": "https://github.com/rosalana/sandbox#readme",
+  "bugs": {
+    "url": "https://github.com/rosalana/sandbox/issues"
+  },
+  "author": "michaelbany <mobany526@gmail.com>",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vite": "^5.2.0"
+  }
+}