@rosalana/sandbox 0.0.4 → 0.1.0

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/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/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,5 +1,7 @@
 import type { AnyUniformValue, ResolvedSandboxOptions, 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.
@@ -61,7 +63,7 @@ export default class WebGL {
      * 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.
      */
@@ -82,6 +84,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

@@ -1,4 +1,5 @@
 import type { SandboxError } from "./errors";
+import Shader from "./tools/shader";
 /** Sandbox configuration options */
 export interface SandboxOptions {
     /** Vertex shader source code */
@@ -11,6 +12,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) */
@@ -25,9 +28,14 @@ export interface SandboxOptions {
     onAfterRender?: HookCallback | null;
     /** Initial uniforms to set */
     uniforms?: UniformSchema;
+    /** Configure used modules behavior */
+    modules?: Record<string, Record<string, AnyUniformValue>>;
 }
 /** 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 */
@@ -95,6 +103,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 {
@@ -109,3 +121,86 @@ export interface UniformEntry {
 export type DrawMode = "TRIANGLES" | "TRIANGLE_STRIP" | "TRIANGLE_FAN";
 /** Render callback signature */
 export type HookCallback = (clock: ClockState) => void | false;
+/** 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.4",
+  "version": "0.1.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);
-}