@rosalana/sandbox 0.0.5 → 0.2.0

package/dist/tools/compilable.d.ts

@@ -0,0 +1,79 @@
+import { ShaderFunction, ShaderUniform, WebGLVersion } from "../types";
+import Parser from "./parser";
+export default class Compilable {
+    /** Flag to track if the shader has been compiled */
+    protected isCompiled: boolean;
+    /** Original and compiled shader parsers */
+    protected original: Parser;
+    /** Compiled parser will be updated with rewritten source after processing imports */
+    protected compiled: Parser;
+    /** Collected requirements from imports */
+    protected requirements: {
+        uniforms: Map<string, ShaderUniform>;
+        functions: Map<string, ShaderFunction>;
+    };
+    constructor(source: string);
+    /**
+     * Detect WebGL version from shader source
+     */
+    version(): WebGLVersion;
+    /**
+     * Get the original source code of the shader
+     */
+    source(): string;
+    /**
+     * Force recompilation of the shader, reprocessing all imports and rewrites
+     * It's not necessary to call this manually because the state gets lost whenever the shader is switched out and back in.
+     */
+    recompile(): string;
+    /**
+     * Compile the shader source, resolving all imports
+     */
+    compile(): string;
+    /**
+     * Process all #import directives
+     */
+    private processImports;
+    /**
+     * Process an extraction: rewrite names and collect as requirements
+     */
+    private processExtraction;
+    /**
+     * Rewrite a function: namespace all uniform and helper function references
+     */
+    private rewriteFunction;
+    /**
+     * Apply rewrite operations to a string, processing from end to start
+     */
+    private applyRewrites;
+    /**
+     * Build the final compiled shader
+     */
+    private build;
+    private replaceMentions;
+    /**
+     * Remove #import lines from shader source
+     */
+    private removeImportLines;
+    /**
+     * Find insertion point for uniforms (after existing uniforms)
+     */
+    private findInsertionPointForUniforms;
+    private findInsertionPointForFunctions;
+    /**
+     * Generate GLSL code for uniforms
+     */
+    private generateUniformsCode;
+    /**
+     * Generate GLSL code for functions
+     */
+    private generateFunctionCode;
+    /**
+     * Check which required uniforms are missing from the original shader
+     */
+    private checkUniformsPresence;
+    /**
+     * Check which required functions are missing from the original shader
+     */
+    private checkFunctionsPresence;
+}

package/dist/tools/module.d.ts

@@ -0,0 +1,46 @@
+import { ModuleDefinition, ModuleFunctionExtraction } from "../types";
+import Compilable from "./compilable";
+export default class Module extends Compilable {
+    name: ModuleDefinition["name"];
+    options: ModuleDefinition["options"];
+    constructor(name: ModuleDefinition["name"], source: ModuleDefinition["source"], options?: ModuleDefinition["options"]);
+    private resolveOptions;
+    /**
+     * Define a module with given name and source, and register it
+     */
+    static define(definition: ModuleDefinition): Module;
+    /**
+     * Resolve a module by name from the registry, throwing an error if not found
+     */
+    static resolve(name: string): Module;
+    /**
+     * Create a copy of the module. To unplug references to the original object.
+     * Used when copying module to the runtime registry to allow independent runtime changes to options without affecting the original module definition.
+     */
+    copy(state?: "original" | "compiled"): Module;
+    /**
+     * Merge options from another module into this one, without affecting the original module definition.
+     * Used when merging imported modules into the runtime registry.
+     */
+    merge(module: Module): void;
+    /**
+     * Get the module definition
+     */
+    getDefinition(): {
+        name: string;
+        methods: string[];
+        uniforms: {
+            name: string;
+            type: import("..").GLSLType;
+        }[];
+        options: Record<string, Record<string, import("..").ModuleMethodOption>> | undefined;
+    };
+    /**
+     * Extract a method with all its dependencies
+     */
+    extract(name: string): ModuleFunctionExtraction;
+    /**
+     * Recursively collect all function and uniform dependencies
+     */
+    private collectDependencies;
+}

package/dist/tools/module_registry.d.ts

@@ -0,0 +1,63 @@
+import { ModuleMethodOption, UniformSchema } from "../types";
+import type Module from "./module";
+export default class ModuleRegistry {
+    private modules;
+    constructor(initialModules?: Module[]);
+    /**
+     * Compile all registered modules.
+     */
+    compile(): void;
+    /**
+     * Get the list of available shader modules.
+     */
+    available(): {
+        name: string;
+        methods: string[];
+        uniforms: {
+            name: string;
+            type: import("..").GLSLType;
+        }[];
+        options: Record<string, Record<string, ModuleMethodOption>> | undefined;
+    }[];
+    /**
+     * Get the list of uniforms required by the currently registered modules.
+     * This is used to automatically set up the uniforms in the shader based on the modules in use.
+     */
+    defaults(): UniformSchema;
+    /**
+     * Resolve the options from the module definitions for a given function name.
+     */
+    resolveOptions(func: string): Record<string, ModuleMethodOption> | null;
+    /**
+     * Register a new module in the registry.
+     */
+    register(name: string, module: Module): void;
+    /**
+     * Merge a module into the registry. If a module with the same name already exists, options will be merged together.
+     */
+    merge(name: string, module: Module): void;
+    /**
+     * Resolve a module by name. Throws an error if the module is not found.
+     */
+    resolve(name: string): Module;
+    /**
+     * Check if a module exists in the registry by name.
+     */
+    has(name: string): boolean;
+    /**
+     * Check if the registry is empty (no modules registered).
+     */
+    isEmpty(): boolean;
+    /**
+     * Remove a module from the registry by name.
+     */
+    remove(name: string): void;
+    /**
+     * Load multiple modules into the registry at once.
+     */
+    load(modules: Module[]): void;
+    /**
+     * Clear all registered modules from the registry.
+     */
+    clear(): void;
+}

package/dist/tools/parser.d.ts

@@ -0,0 +1,32 @@
+import { ShaderParseResult, WebGLVersion } from "../types";
+export default class Parser {
+    source: string;
+    parsed: ShaderParseResult | null;
+    constructor(source: string);
+    /**
+     * Parse the shader source to extract imports, uniforms, functions, and version.
+     */
+    parse(): ShaderParseResult;
+    /**
+     * Check if the shader source has already been parsed
+     */
+    isParsed(): boolean;
+    /**
+     * Change the shader source and reset the parsed result
+     */
+    setSource(newSource: string): void;
+    /**
+     * Get the detected GLSL version from the shader source without parsing the entire shader
+     */
+    version(): WebGLVersion;
+    private detectVersion;
+    private detectImports;
+    private diagnoseImport;
+    private detectUniforms;
+    private detectFunctions;
+    private parseParams;
+    private findClosingBrace;
+    private findFunctionCalls;
+    private findUniformCalls;
+    private findMentionCalls;
+}

package/dist/tools/program.d.ts

@@ -1,20 +1,13 @@
-import type { WebGLContext, WebGLVersion } from "../types";
+import type { WebGLContext } 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
@@ -29,10 +22,6 @@ export default class Program {
      * Get the compiled WebGL program.
      */
     getProgram(): WebGLProgram | null;
-    /**
-     * Get detected WebGL version.
-     */
-    getVersion(): WebGLVersion;
     /**
      * Get attribute location.
      */

package/dist/tools/shader.d.ts

@@ -0,0 +1,4 @@
+import Compilable from "./compilable";
+export default class Shader extends Compilable {
+    constructor(source: string);
+}

package/dist/tools/texture.d.ts

@@ -0,0 +1,64 @@
+import type { TextureOptions, TextureSource, WebGLContext } from "../types";
+/**
+ * Handles a single WebGL texture.
+ * Manages texture creation, pixel upload, binding, and location caching.
+ * Mirrors the Uniform class pattern for consistency.
+ */
+export default class Texture {
+    readonly name: string;
+    private gl;
+    private texture;
+    private location;
+    private locationResolved;
+    private source;
+    private options;
+    private dynamicOverride;
+    private needsUpload;
+    private needsReupload;
+    constructor(gl: WebGLContext, name: string, source: TextureSource, options?: TextureOptions);
+    /**
+     * Update the texture source.
+     * Marks texture for re-upload on next bind.
+     * Respects the original `dynamic` option if explicitly set, otherwise re-infers from source type.
+     */
+    setSource(source: TextureSource): void;
+    /**
+     * Resolve and cache uniform location from program.
+     * Returns null if the sampler uniform doesn't exist in the shader.
+     */
+    resolveLocation(gl: WebGLContext, program: WebGLProgram): WebGLUniformLocation | null;
+    /**
+     * Invalidate cached location (call when program changes).
+     */
+    invalidateLocation(): void;
+    /**
+     * Bind texture to a texture unit and set the sampler uniform.
+     * @param program - Current WebGL program (for location resolution)
+     * @param unit - Texture unit index (0, 1, 2, ...)
+     */
+    upload(program: WebGLProgram, unit: number): void;
+    /**
+     * Cleanup WebGL texture resource.
+     */
+    destroy(): void;
+    /**
+     * Upload pixel data from source and apply texture parameters.
+     */
+    private uploadPixels;
+    /**
+     * Apply texture wrap and filter parameters.
+     */
+    private applyParameters;
+    /**
+     * Resolve wrap mode string to WebGL constant.
+     */
+    private static resolveWrap;
+    /**
+     * Resolve texture options with defaults.
+     */
+    private static resolveOptions;
+    /**
+     * Check if a source is dynamic (needs re-upload every frame).
+     */
+    private static isDynamicSource;
+}

package/dist/tools/textures.d.ts

@@ -0,0 +1,48 @@
+import type { TextureOptions, TextureSource, WebGLContext } from "../types";
+import Texture from "./texture";
+/**
+ * Manages a collection of textures with fluent API.
+ * Assigns texture units sequentially and handles program attachment.
+ * Mirrors the Uniforms class pattern for consistency.
+ */
+export default class Textures {
+    private gl;
+    private program;
+    private textures;
+    constructor(gl: WebGLContext);
+    /**
+     * Attach to a WebGL program.
+     * Invalidates all cached locations since they're program-specific.
+     */
+    attachProgram(program: WebGLProgram): this;
+    /**
+     * Set a texture.
+     * Creates the texture entry if it doesn't exist, updates source if it does.
+     */
+    set(name: string, source: TextureSource, options?: TextureOptions): this;
+    /**
+     * Get a texture by name.
+     */
+    get(name: string): Texture | undefined;
+    /**
+     * Check if a texture exists.
+     */
+    has(name: string): boolean;
+    /**
+     * Remove a texture and free its GPU resources.
+     */
+    delete(name: string): boolean;
+    /**
+     * Upload all textures to their respective texture units.
+     * Units are assigned sequentially (0, 1, 2, ...).
+     */
+    uploadAll(): this;
+    /**
+     * Get texture count.
+     */
+    get size(): number;
+    /**
+     * Cleanup all textures.
+     */
+    destroy(): void;
+}

package/dist/tools/uniforms.d.ts

@@ -7,8 +7,6 @@ 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.

package/dist/tools/web_gl.d.ts

@@ -1,6 +1,7 @@
-import type { AnyUniformValue, ResolvedSandboxOptions, UniformSchema, WebGLContext, WebGLVersion } from "../types";
+import type { AnyUniformValue, ResolvedSandboxOptions, TextureOptions, TextureSchema, TextureSource, UniformSchema, WebGLContext, WebGLVersion } from "../types";
 import Clock from "./clock";
 import Hooks from "./hooks";
+import Shader from "./shader";
 /**
  * Main WebGL orchestrator.
  * Manages context, program, geometry, uniforms, and rendering loop.
@@ -14,6 +15,7 @@ export default class WebGL {
     private _program;
     private _geometry;
     private _uniforms;
+    private _textures;
     private _clock;
     private _resolution;
     private _mouse;
@@ -58,11 +60,23 @@ export default class WebGL {
      * Get current uniform value.
      */
     getUniform<T extends AnyUniformValue>(name: string): T | undefined;
+    /**
+     * Set a texture.
+     */
+    texture(name: string, source: TextureSource, options?: TextureOptions): this;
+    /**
+     * Set multiple textures from a schema.
+     */
+    texturesFromSchema(schema: TextureSchema): this;
+    /**
+     * Remove a texture.
+     */
+    removeTexture(name: string): this;
     /**
      * Compile and link shaders.
      * Errors are handled via onError callback, never thrown.
      */
-    shader(vertex: string, fragment: string): this;
+    shader(vertex: Shader, fragment: Shader): this;
     /**
      * Start animation loop.
      */

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { SandboxError } from "./errors";
+import Shader from "./tools/shader";
 /** Sandbox configuration options */
 export interface SandboxOptions {
     /** Vertex shader source code */
@@ -27,9 +28,16 @@ export interface SandboxOptions {
     onAfterRender?: HookCallback | null;
     /** Initial uniforms to set */
     uniforms?: UniformSchema;
+    /** Configure used modules behavior */
+    modules?: Record<string, Record<string, AnyUniformValue>>;
+    /** Initial textures to bind */
+    textures?: TextureSchema;
 }
 /** Resolved sandbox options with all defaults applied */
-export type ResolvedSandboxOptions = Required<SandboxOptions>;
+export type ResolvedSandboxOptions = Omit<Required<SandboxOptions>, "vertex" | "fragment"> & {
+    vertex: Shader;
+    fragment: Shader;
+};
 /** WebGL version (1 = WebGL, 2 = WebGL2) */
 export type WebGLVersion = 1 | 2;
 /** Union of WebGL context types */
@@ -115,3 +123,117 @@ export interface UniformEntry {
 export type DrawMode = "TRIANGLES" | "TRIANGLE_STRIP" | "TRIANGLE_FAN";
 /** Render callback signature */
 export type HookCallback = (clock: ClockState) => void | false;
+/** Valid texture source types */
+export type TextureSource = HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | ImageBitmap | ImageData | OffscreenCanvas;
+/** Texture wrapping mode */
+export type TextureWrap = "clamp" | "repeat" | "mirror";
+/** Texture filter mode */
+export type TextureFilter = "nearest" | "linear";
+/** Per-texture configuration */
+export interface TextureOptions {
+    /** Wrapping mode for both axes (shorthand for wrapS + wrapT) */
+    wrap?: TextureWrap;
+    /** Wrapping mode for S (horizontal) axis */
+    wrapS?: TextureWrap;
+    /** Wrapping mode for T (vertical) axis */
+    wrapT?: TextureWrap;
+    /** Minification filter */
+    minFilter?: TextureFilter;
+    /** Magnification filter */
+    magFilter?: TextureFilter;
+    /** Flip texture vertically on upload (default: true) */
+    flipY?: boolean;
+    /** Re-upload pixels every frame for animated sources (default: true for video, false otherwise) */
+    dynamic?: boolean;
+}
+/** Resolved texture options with all defaults applied */
+export type ResolvedTextureOptions = Required<TextureOptions>;
+/** Schema for defining multiple textures at once */
+export interface TextureSchema {
+    [name: string]: TextureSource | ({
+        source: TextureSource;
+    } & TextureOptions);
+}
+/** GLSL uniform types */
+export type GLSLType = "float" | "int" | "bool" | "vec2" | "vec3" | "vec4" | "ivec2" | "ivec3" | "ivec4" | "bvec2" | "bvec3" | "bvec4" | "mat2" | "mat3" | "mat4" | "sampler2D" | "samplerCube";
+export type GLSLVariable = {
+    /** Variable name */
+    name: string;
+    /** GLSL type */
+    type: GLSLType;
+};
+/** Import statement parsed from shader */
+export type ShaderImport = {
+    /** Module identifier (e.g., "sandbox/math") */
+    module: string;
+    /** Original function name in module */
+    name: string;
+    /** Alias to use in shader (defaults to name) */
+    alias: string;
+    /** Line number where import appears */
+    line?: number;
+};
+export type ShaderUniform = GLSLVariable & {
+    /** Line number where import appears */
+    name: "u_time" | "u_resolution" | "u_delta" | "u_mouse" | "u_frame" | string;
+    arrayNum?: number;
+    line?: number;
+};
+type ShaderFunctionDependency = {
+    /** Name of the dependent */
+    name: string;
+    /** Type of dependency */
+    type: "function" | "uniform" | "mention";
+    /** Character index from start of the function body for rewriting purposes */
+    index?: number;
+};
+export type ShaderFunction = {
+    /** Function name */
+    name: string;
+    /** Return type */
+    type: GLSLType;
+    /** Function parameters */
+    params: GLSLVariable[];
+    /** Function body (including braces) */
+    body: string;
+    /** List of dependencies (functions or uniforms) this function has */
+    dependencies: ShaderFunctionDependency[];
+    /** Line number where function is declared */
+    line?: number;
+};
+export type ShaderParseResult = {
+    /** All imports found in shader */
+    imports: ShaderImport[];
+    /** All uniforms declared in shader */
+    uniforms: ShaderUniform[];
+    /** All functions declared in shader */
+    functions: ShaderFunction[];
+    /** GLSL version */
+    version: WebGLVersion;
+};
+export interface ModuleDefinition {
+    /** Module name */
+    name: string;
+    /** GLSL source code containing functions */
+    source: string;
+    /**
+     * Options per-function if the module has custom uniforms that can be used to configure methods behavior.
+     * The key is the function name.
+     * For each function set the option name and link it to a uniform with optional default value.
+     */
+    options?: Record<string, Record<string, ModuleMethodOption>>;
+}
+export type ModuleMethodOption = {
+    uniform: string;
+    default?: AnyUniformValue;
+};
+export type ModuleFunctionExtraction = {
+    /** Extracted function definition */
+    function: ShaderFunction;
+    /** All dependencies (functions and uniforms) required by this function */
+    dependencies: {
+        functions: ShaderFunction[];
+        uniforms: ShaderUniform[];
+    };
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rosalana/sandbox",
-  "version": "0.0.5",
+  "version": "0.2.0",
   "description": "Lightweight WebGL wrapper for simple, beautiful shader effects",
   "keywords": [
     "webgl",
@@ -21,9 +21,9 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.es.js",
-      "require": "./dist/index.cjs.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.cjs.js"
     }
   },
   "files": [
@@ -35,7 +35,9 @@
     "typecheck": "tsc --noEmit",
     "dev": "npm run build -- --watch",
     "build": "vite build && tsc --declaration --emitDeclarationOnly",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "repository": {
     "type": "git",
@@ -49,6 +51,7 @@
   "license": "MIT",
   "devDependencies": {
     "typescript": "^5.4.0",
-    "vite": "^5.2.0"
+    "vite": "^5.2.0",
+    "vitest": "^4.0.18"
   }
 }

package/dist/errors.d.ts

@@ -1,32 +0,0 @@
-/** 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);
-}