@rosalana/sandbox 0.0.5 → 0.1.0

package/README.md

@@ -18,13 +18,13 @@ It's **DX‑friendly**, small, and intentionally minimal — perfect for gradien
 
 ### Bundle size comparison
 
-| Library     | Minified | Gzipped  |
-| ----------- | -------- | -------- |
-| **Sandbox** | 31 KB    | **8 KB** |
-| three.js    | 694 KB   | 175 KB   |
-| p5.js       | 1.1 MB   | 351 KB   |
+| Library     | Minified | Gzipped   |
+| ----------- | -------- | --------- |
+| **Sandbox** | 85 KB    | **23 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.
+Sandbox is **~8x smaller** than three.js and **~15x smaller** than p5.js.
 
 It works in both **WebGL1 and WebGL2** contexts, with automatic fallback and detection.
 
@@ -35,10 +35,7 @@ It works in both **WebGL1 and WebGL2** contexts, with automatic fallback and det
 - [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)
+- [Sandbox Shaders](#sandbox-shaders)
 - [Hooks](#hooks)
   - [Self-removing hooks](#self-removing-hooks)
 - [Chaining](#chaining)
@@ -120,76 +117,177 @@ Or render at a specific time — perfect for deterministic, reproducible output:
 sandbox.renderAt(1.5);
 ```
 
-## Shaders
+## Sandbox 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.
+Writing GLSL from scratch means a lot of ceremony — uniform declarations, copy-pasting utility functions, wiring everything together. Sandbox takes care of the boring parts so you can focus on the shader itself.
 
-Update your fragment shader on the fly:
+The idea is simple: define reusable GLSL snippets as **modules**, then `#import` them with a single line. Sandbox resolves dependencies, declares uniforms, and injects everything into the final shader automatically.
+
+### Writing shaders
+
+You only need to provide a fragment shader. Sandbox ships with a default fullscreen vertex shader and automatically matches WebGL versions — so you can focus on the fun part.
 
 ```ts
 sandbox.setFragment(fragmentSource);
 ```
 
-When you need full control over both vertex and fragment:
+Need full control over both shaders? No problem:
 
 ```ts
 sandbox.setShader(vertexSource, fragmentSource);
 ```
 
-### WebGL version detection
+Sandbox detects WebGL version from your code (`#version 300 es` → WebGL2, no directive → WebGL1) and falls back gracefully. You can always check what you're running:
 
-Sandbox figures out which WebGL version you're using by looking at your shader code:
+```ts
+sandbox.version; // 1 or 2
+```
 
-- `#version 300 es` → WebGL2
-- no version directive → WebGL1
+### Built-in uniforms
 
-If WebGL2 isn't available, Sandbox falls back to WebGL1 automatically. You can always check what you're running:
+These uniforms are populated automatically every frame. Just use them in your shader — no declaration or setup needed:
+
+| 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               |
+
+Built-in uniforms are globally available — even inside imported module functions. They're never namespaced, so `u_time` is always just `u_time`, everywhere.
+
+### Custom uniforms
+
+Need your own data in the shader? Declare the uniform in GLSL, then set it from JavaScript:
 
 ```ts
-sandbox.version; // 1 or 2
+sandbox.setUniform<number>("u_intensity", 0.8);
+
+sandbox.setUniforms({
+  u_intensity: 0.75,
+  u_color: [1, 0.2, 0.3],
+});
+```
+
+Read a value back:
+
+```ts
+const intensity = sandbox.getUniform<number>("u_intensity");
 ```
 
-## Uniforms
+Everything is **type-safe** and **chainable**. All numeric values are treated as floats — simple and predictable.
 
-Uniforms are how you feed data into your shader. Sandbox makes them **type‑safe** and **chainable** — no more guessing what went wrong.
+### Modules
 
-Set a single uniform:
+> [!IMPORTANT]
+> Sandbox's built-in GLSL modules are still in beta and may change at any time.
+> We published them early to get feedback. If you have ideas for improvements, please open an issue or a PR — we'd love your input.
+
+Modules are reusable GLSL snippets that you can import into any shader. Sandbox ships with a built-in `"sandbox"` module, and you can define your own:
 
 ```ts
-sandbox.setUniform<number>("u_intensity", 0.8);
+Sandbox.defineModule("my_effects", myGLSLSource);
 ```
 
-Set multiple uniforms at once:
+Then import any function from it:
+
+```glsl
+#import bloom from "my_effects"
+#import hex from "sandbox"
+
+void main() {
+  vec3 color = hex(0xFF5733);
+  fragColor = vec4(bloom(color), 1.0);
+}
+```
+
+When you import a function, Sandbox pulls in everything it needs — the function body, any helper functions it calls, and any required uniforms. Each import is fully isolated, so importing the same function twice won't cause conflicts.
+
+> [!NOTE]
+> All imported code is namespaced automatically to avoid naming collisions.
+
+Module names starting with `"sandbox"` are reserved for built-in modules. Each module can only be defined once — this prevents accidental overwrites.
+
+Want to see what's available? Inspect all registered modules at any time:
 
 ```ts
-sandbox.setUniforms<{
-  u_intensity: number;
-  u_color: Vec3;
-}>({
-  u_intensity: 0.75,
-  u_color: [1, 0.2, 0.3],
+Sandbox.availableModules();
+```
+
+You can also preview how your shader will look after processing:
+
+```ts
+Sandbox.compile(shaderSource);
+```
+
+This is useful for debugging or precompiling shaders before deploying.
+
+### Module options
+
+Imported functions can expose configurable options — friendly names that map to GLSL uniforms under the hood. You control them from JavaScript using `sandbox.module()`:
+
+```ts
+sandbox.module("effect", {
+  intensity: 0.8,
 });
 ```
 
-Read back a uniform value:
+This is a powerful way to customize imported effects without touching any GLSL code.
+
+#### Hardcoded vs. dynamic values
+
+By default, a module's uniforms are only included in the final shader when you actually reference them. This gives you a choice — hardcode a value directly, or use the `@` syntax to wire it up as a configurable uniform:
+
+```glsl
+#import effect from "my_module"
+
+void main() {
+  vec3 a = effect(v_texcoord, 2.0);                  // hardcoded value
+  vec3 b = effect(v_texcoord, @effect.intensity);     // dynamic — set via sandbox.module()
+  fragColor = vec4(a + b, 1.0);
+}
+```
+
+The `@effect.intensity` syntax tells Sandbox to inject the uniform and keep it in sync with whatever you set in JavaScript.
+
+#### Defining options
+
+When defining a module, you declare which options each function supports:
 
 ```ts
-const intensity = sandbox.getUniform<number>("u_intensity");
+Sandbox.defineModule("my_gradient", gradientSource, {
+  myFunc: {
+    colors: {
+      uniform: "u_colors",
+      default: [[1, 0, 0], [0, 0, 1]],
+    },
+    speed: { uniform: "u_speed", default: 1.0 },
+  },
+});
 ```
 
-All numeric values are treated as floats. This keeps the API simple and predictable.
+Each option has a `uniform` (the GLSL name it maps to) and an optional `default` value applied automatically on import.
 
-## Built‑in uniforms
+If all functions in your module share the same options, use the `default` key to avoid repetition:
 
-These uniforms are filled automatically every frame — no setup needed. Just declare them in your shader and they work:
+```ts
+Sandbox.defineModule("my_module", source, {
+  default: {
+    colors: {
+      uniform: "u_colors",
+      default: [[1, 0, 0], [0, 0, 1]],
+    },
+    speed: { uniform: "u_speed", default: 1.0 },
+  },
+  specialFunc: {
+    speed: { uniform: "u_speed", default: 2.0 },
+    // "colors" is inherited from default
+  },
+});
+```
 
-| 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               |
+Per-function options always take priority over `default` when both define the same key.
 
 ## Hooks
 
@@ -264,11 +362,18 @@ Sandbox.create(canvas, {
 
 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.code` — error category (see table below)
+- `error.lines` — line numbers where errors occurred (for shader compilation errors)
 - `error.shaderType` — which shader failed (`vertex` or `fragment`)
 
-Error codes: `WEBGL_NOT_SUPPORTED`, `SHADER_COMPILATION_FAILED`, `PROGRAM_LINK_FAILED`, `SHADER_VERSION_MISMATCH`
+| Code               | When                                                                                  |
+| ------------------ | ------------------------------------------------------------------------------------- |
+| `CONTEXT_ERROR`    | WebGL not supported or context creation failed                                        |
+| `SHADER_ERROR`     | Shader compilation failed, version mismatch, import syntax error, or missing function |
+| `PROGRAM_ERROR`    | Shader program linking failed                                                         |
+| `VALIDATION_ERROR` | Vertex/fragment shader version mismatch                                               |
+| `MODULE_ERROR`     | Module not found, method not found, forbidden name, or duplicate definition           |
+| `UNKNOWN_ERROR`    | Unexpected error in callbacks (onLoad, hooks)                                         |
 
 ## Vue integration
 
@@ -337,6 +442,7 @@ interface SandboxOptions {
   onBeforeRender?: HookCallback | null;
   onAfterRender?: HookCallback | null;
   uniforms?: UniformSchema;
+  modules?: Record<string, Record<string, AnyUniformValue>>;
 }
 ```
 
@@ -355,6 +461,7 @@ interface SandboxOptions {
 | `onBeforeRender`        | —               | Hook before each frame                         |
 | `onAfterRender`         | —               | Hook after each frame                          |
 | `uniforms`              | —               | Initial uniform values                         |
+| `modules`               | —               | Configure module options per imported function |
 
 ## Limitations (by design)
 

package/dist/errors/base.d.ts

@@ -0,0 +1,6 @@
+export type SandboxErrorCode = "CONTEXT_ERROR" | "VALIDATION_ERROR" | "PROGRAM_ERROR" | "SHADER_ERROR" | "MODULE_ERROR" | "UNKNOWN_ERROR";
+export declare class SandboxError extends Error {
+    readonly code: SandboxErrorCode;
+    readonly name: string;
+    constructor(message: string, code: SandboxErrorCode);
+}

package/dist/errors/context.d.ts

@@ -0,0 +1,7 @@
+import { SandboxError } from "./base";
+export declare class SandboxWebGLNotSupportedError extends SandboxError {
+    constructor();
+}
+export declare class SandboxContextCreationError extends SandboxError {
+    constructor();
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./base";
+export * from "./context";
+export * from "./shader";
+export * from "./module";
+export * from "./program";
+export * from "./unknown";

package/dist/errors/module.d.ts

@@ -0,0 +1,42 @@
+import { SandboxError } from "./base";
+export declare class SandboxModuleNotFoundError extends SandboxError {
+    readonly moduleName: string;
+    constructor(moduleName: string);
+}
+export declare class SandboxModuleMethodNotFoundError extends SandboxError {
+    readonly moduleName: string;
+    readonly methodName: string;
+    constructor(moduleName: string, methodName: string);
+}
+export declare class SandboxAttemptedToImportMainFunctionError extends SandboxError {
+    readonly moduleName: string;
+    constructor(moduleName: string);
+}
+export declare class SandboxAttemptedToImportDefaultFunctionError extends SandboxError {
+    readonly moduleName: string;
+    constructor(moduleName: string);
+}
+export declare class SandboxForbiddenModuleNameError extends SandboxError {
+    readonly moduleName: string;
+    constructor(moduleName: string);
+}
+export declare class SandboxOverwriteModuleError extends SandboxError {
+    readonly moduleName: string;
+    constructor(moduleName: string);
+}
+export declare class SandboxMentionUniformNotFoundError extends SandboxError {
+    readonly moduleName: string;
+    readonly functionName: string;
+    readonly uniformName: string;
+    constructor(moduleName: string, functionName: string, uniformName: string);
+}
+export declare class SandboxMentionFunctionNotFoundError extends SandboxError {
+    readonly functionName: string;
+    readonly uniformName: string;
+    constructor(functionName: string, uniformName: string);
+}
+export declare class SandboxMentionCouldNotBeReplacedError extends SandboxError {
+    readonly mentionName: string;
+    readonly calledInFunction: string;
+    constructor(mentionName: string, calledInFunction: string);
+}

package/dist/errors/program.d.ts

@@ -0,0 +1,5 @@
+import { SandboxError } from "./base";
+export declare class SandboxProgramError extends SandboxError {
+    readonly infoLog: string;
+    constructor(infoLog: string);
+}

package/dist/errors/shader.d.ts

@@ -0,0 +1,34 @@
+import { SandboxError } from "./base";
+export declare class SandboxShaderVersionMismatchError extends SandboxError {
+    readonly vertexVersion: number;
+    readonly fragmentVersion: number;
+    constructor(vertexVersion: number, fragmentVersion: number);
+}
+export declare class SandboxGLSLShaderCompilationError extends SandboxError {
+    readonly shaderType: "vertex" | "fragment";
+    readonly source: string;
+    readonly infoLog: string;
+    readonly lines: number[];
+    constructor(shaderType: "vertex" | "fragment", source: string, infoLog: string);
+    private static parseErrorLines;
+}
+export declare class SandboxShaderRequirementMismatchError extends SandboxError {
+    readonly requirement: "uniform" | "function";
+    readonly name: string;
+    readonly expectedType: string;
+    readonly actualType: string;
+    constructor(requirement: "uniform" | "function", name: string, expectedType: string, actualType: string);
+}
+export declare class SandboxShaderWithoutFunctionError extends SandboxError {
+    constructor();
+}
+export declare class SandboxShaderImportSyntaxError extends SandboxError {
+    readonly line: number;
+    readonly details: string;
+    constructor(line: number, details: string);
+}
+export declare class SandboxShaderDuplicateImportNameError extends SandboxError {
+    readonly name: string;
+    readonly line: number;
+    constructor(name: string, line: number);
+}

package/dist/errors/unknown.d.ts

@@ -0,0 +1,7 @@
+import { SandboxError } from "./base";
+export declare class SandboxOnLoadCallbackError extends SandboxError {
+    constructor(message: string);
+}
+export declare class SandboxOnHookCallbackError extends SandboxError {
+    constructor(id: string, message: string);
+}

package/dist/globals.d.ts

@@ -0,0 +1,17 @@
+import ModuleRegistry from "./tools/module_registry";
+/**
+ * Default modules bundled with Sandbox.
+ * These modules are available for import in shader source without needing to be registered manually.
+ * This registry will grow when more modules are defined
+ */
+export declare const modules: ModuleRegistry;
+/**
+ * A global registry of modules that are currently in use by the webGL context.
+ * This is flushed on every shader switch.
+ */
+export declare const runtime_modules: ModuleRegistry;
+/**
+ * Global uniforms that are automatically provided by Sandbox.
+ * These uniforms will NOT be renamed during preprocessing.
+ */
+export declare const uniforms: Map<string, import("./types").GLSLType>;