glslh 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -1,6 +1,22 @@
 ## 📋 `glslh` Changelog
 
-### **v1.1.1** (Latest)
+### **v1.2.0** (Latest)
+
+- **Topological Sorting for Derived Uniforms**: Upgraded `buildDerived` in `derived.js` to implement Kahn's algorithm for dependency graphs, ensuring derived uniform expressions evaluate in the correct order regardless of JSON declaration placement and throwing immediate errors on circular dependencies.
+- **Enhanced Expression Engine & Math Utilities**: Fixed operator precedence for exponentiation (`**`) with correct right-associativity, and introduced software implementations of essential GLSL math functions (`mix`, `smoothstep`, `clamp`, `fract`, `step`, `mod`, `length`, `distance`, `dot`) for CPU-side derived uniform evaluations. Secured variable resolution using `Object.hasOwn()`.
+- **Overload-Aware Static Collision Detection**: Refactored `detectFunctionCollisions` in `parser.js` to support valid GLSL function overloading (distinguishing functions by parameter signatures) and filter out forward declaration prototypes ending in semicolons (`;`).
+- **DOM Canvas Lifecycle & Mouse Tracking**: Enhanced `GLSLHDomCanvas` with real-time normalized/pixel mouse coordinate tracking (`mouseX`, `mouseY`), fixed Three.js clock delta calculation order, and added resource cleanup (`dispose()`) for geometries, materials, and WebGL contexts.
+- **Native Version Pipeline Integration**: Streamlined `#version` handling by removing forced string injections and delegating version management natively to Three.js via `glslVersion: THREE.GLSL3`, completely eliminating WebGL driver compilation clashes.
+
+---
+
+### **v1.1.2**
+
+- **AI-Native Error Context Mapping**: Upgraded `translateShaderError` inside `parser.js` to automatically extract and embed surrounding 5-line code snippets (`--- Code Context ---`) directly alongside modular file and line indicators, allowing developers and AI assistants to diagnose and patch WebGL compilation errors instantly without manual file lookups.
+
+---
+
+### **v1.1.1**
 
 - **Documentation & README Refinement**: Updated documentation, architecture diagrams, and release logs to reflect complete structural guides for modular struct-based composition, CPU/GPU division of labor, and extension workflows.
 

package/README.md

@@ -5,6 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![JavaScript](https://img.shields.io/badge/language-JavaScript-f7df1e.svg)](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
 [![WebGL / Three.js](https://img.shields.io/badge/graphics-WebGL%20%2F%20Three.js-blue.svg)](https://threejs.org/)
+[![npm version](https://img.shields.io/badge/npm-v1.2.0-blue.svg)](https://www.npmjs.com/package/glslh)
 
 ---
 
@@ -12,24 +13,22 @@
 
 `glslh` establishes a clean pipeline separating CPU-side orchestration from GPU-side parallel rendering:
 
-```
-
+```text
 .glslh (Self-Contained Header)
 ┌─────────────────────────────┐
-│  /* @uniforms { ... } */    │ ──► [CPU] Auto-linked JS-to-GLSL Uniforms
-│  #include "utils/noise.glsl"│ ──► [CPU] Recursive File & Dependency Resolution
-│  Math.PI macro injection    │ ──► [CPU] JIT Constant & Expression Evaluator
+│   /* @uniforms { ... } */    │ ──► [CPU] Auto-linked JS-to-GLSL Uniforms
+│   #include "utils/noise.glsl"│ ──► [CPU] Recursive File & Dependency Resolution
+│   Math.PI macro injection    │ ──► [CPU] JIT Constant & Topological Expression Evaluator
 └──────────────┬──────────────┘
-▼
-[ glslh Preprocessor ]
-▼
+               ▼
+      [ glslh Preprocessor ]
+               ▼
 ┌─────────────────────────────┐
-│  Final Pure GLSL String     │ ──► [GPU] Compiled & Executed via WebGL
+│   Final Pure GLSL String    │ ──► [GPU] Compiled & Executed via WebGL
 └─────────────────────────────┘
-
 ```
 
-- **CPU-Side (JavaScript):** File fetching, `#include` stitching, uniform metadata parsing, constant macro evaluation (`Math.PI`, `Math.TAU`), function collision checking, error line mapping, and real-time derived uniform animation loops (`requestAnimationFrame`).
+- **CPU-Side (JavaScript):** File fetching, `#include` stitching, uniform metadata parsing, constant macro evaluation (`Math.PI`, `Math.TAU`), topological sorting for derived uniform expressions, function collision checking, error line mapping, and real-time animation loops (`requestAnimationFrame`).
 - **GPU-Side (WebGL / GLSL):** Pure parallel rasterization, vertex positioning, and fragment color blending executing simultaneously across graphics hardware cores.
 
 ---
@@ -39,12 +38,13 @@
 - **Clear CPU/GPU Separation:** All orchestration, math constant calculations (`Math.PI`), and uniform state updates run efficiently on the **CPU**, while heavy rasterization and pixel shading run natively in parallel on the **GPU**.
 - **Zero Runtime Performance Cost:** Because modular files are stitched and compiled once during initialization, your shaders execute at full native GPU speed with zero runtime overhead.
 - **C-Style `#include` Directives:** Split massive shaders into modular files with full circular dependency protection and strict extension validation.
-- **Duplicate Function Collision Detection:** Automatically scans included modules and warns you if multiple files define conflicting function signatures (`float hash()`) before WebGL compilation fails, while fully supporting valid GLSL function overloading.
-- **Error Line Mapping:** Instantly translates monolithic WebGL compilation error line numbers back to their exact source file and line number (`[shape_utils.glsl:14]`).
+- **Topological Derived Uniforms:** Chain derived expressions together in `@uniforms` (e.g., variable `u_b` depending on `u_a`) with automated Kahn's algorithm sorting and circular dependency detection.
+- **Overload-Aware Static Collision Detection:** Automatically scans included modules and warns you if conflicting function signatures clash, while fully supporting valid GLSL function overloading distinguished by parameter signatures.
+- **AI-Friendly Error Context Mapping:** Automatically captures and embeds 5-line surrounding code context snippets alongside modular file and line numbers when WebGL compilation fails.
 - **Self-Contained Metadata Blocks:** Define uniform data types, default values, and derived per-frame formulas right at the top of your shader file (`@uniforms`).
 - **Direct JavaScript Math Injection:** Use native JS constants like `Math.PI` or `Math.TAU` directly in your GLSL code; the preprocessor evaluates them before GPU compilation.
 - **Framework Agnostic:** Seamlessly output standard Three.js `ShaderMaterial` objects ready for Vanilla JS, Three.js, or React Three Fiber.
-- **HTML Declarative Support:** Spin up shaders instantly using HTML data attributes (`data-fragment-url="..."`).
+- **HTML Declarative Support & Cleanup:** Spin up shaders instantly using HTML data attributes (`data-fragment-url="..."`) with full canvas disposal and mouse tracking (`mouseX`, `mouseY`).
 
 ---
 
@@ -57,7 +57,8 @@ The metadata block is an optional JSON declaration placed at the very top of you
   {
     "u_intensity": { "type": "f", "value": 1.0 },
     "u_color": { "type": "c", "value": [1.0, 0.4, 0.0] },
-    "u_wave": { "type": "f", "expr": "sin(u_time * 2.0) * 0.5" }
+    "u_speed": { "type": "f", "expr": "u_time * 2.0" },
+    "u_wave": { "type": "f", "expr": "sin(u_speed) * 0.5" }
   }
 */
 
@@ -65,7 +66,7 @@ The metadata block is an optional JSON declaration placed at the very top of you
 
 ### Why use it?
 
-In standard WebGL and Three.js, wiring JavaScript variables to shader uniforms requires tedious boilerplate. The `@uniforms` block decentralizes this configuration, letting your shader file declare its own parameters and derived per-frame expressions so `glslh` can auto-bind and update them instantly.
+In standard WebGL and Three.js, wiring JavaScript variables to shader uniforms requires tedious boilerplate. The `@uniforms` block decentralizes this configuration, letting your shader file declare its own parameters and derived per-frame expressions (with automatic topological dependency sorting) so `glslh` can auto-bind and update them instantly.
 
 ### What if you forget it?
 
@@ -80,11 +81,11 @@ package/
 ├── package.json
 ├── README.md
 └── src/
-    ├── parser.js        # C-style #include preprocessor, path resolution, collision check & error mapper
-    ├── loader.js        # Metadata JSON parser & Three.js uniform binder
-    ├── dom-canvas.js    # HTML data-attribute and canvas auto-loader wrapper
-    ├── expr.js          # Safe, CSP-compliant AST-based JIT expression evaluator
-    └── derived.js       # Per-frame derived uniform state manager
+    ├── parser.js         # C-style #include preprocessor, path resolution, collision check & error mapper
+    ├── loader.js         # Metadata JSON parser & Three.js uniform binder
+    ├── dom-canvas.js     # HTML data-attribute and canvas auto-loader wrapper with mouse tracking & dispose()
+    ├── expr.js           # Safe, CSP-compliant AST-based JIT expression evaluator with custom math helpers
+    └── derived.js        # Topological sort & per-frame derived uniform state manager
 
 ```
 
@@ -93,7 +94,7 @@ package/
 ## 🚀 Installation & Quick Start
 
 ```bash
-npm install glslh@1.1.1
+npm install glslh@1.2.0
 ```
 
 ### 1. Create a `.glslh` Shader File (`./shaders/header.glslh`)
@@ -104,7 +105,7 @@ npm install glslh@1.1.1
 
 ## ⚡ VS Code Extension (Live Preview)
 
-Want instant syntax highlighting, color pickers, and a live WebGL preview pane right inside your editor? Install the official [**GLSLH Previewer**](https://marketplace.visualstudio.com/items?itemName=SudhanshuAmbastha.glslh-previewer) extension from the marketplace:
+Want instant syntax highlighting, color pickers, and a live WebGL preview pane right inside your editor? Install the official **[GLSLH Previewer](https://marketplace.visualstudio.com/items?itemName=SudhanshuAmbastha.glslh-previewer)** extension from the marketplace:
 
 - **Live WebGL Preview:** Inspect shaders side-by-side with automatic hot-reloading on save.
 - **Native Color Pickers:** Click color definitions or uniform arrays in `@uniforms` or `vec3()` blocks to adjust values visually.
@@ -114,4 +115,4 @@ Want instant syntax highlighting, color pickers, and a live WebGL preview pane r
 
 ## 📜 License
 
-Distributed under the **MIT License**. See [`LICENSE`](../LICENSE) for more information.
+Distributed under the **MIT License**. See [`LICENSE`](https://www.google.com/search?q=../LICENSE) for more information.

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "glslh",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "A lightweight GLSL preprocessor and runtime bridge for modular shader development.",
   "type": "module",
   "main": "./src/dom-canvas.js",
   "exports": {
     ".": "./src/dom-canvas.js",
     "./parser": "./src/parser.js",
-    "./loader": "./src/loader.js"
+    "./loader": "./src/loader.js",
+    "./validator": "./src/validator.js",
+    "./src/*": "./src/*"
   },
   "repository": {
     "type": "git",
@@ -17,7 +19,6 @@
     "url": "https://github.com/Sudhanshu-Ambastha/glsl-header/issues"
   },
   "homepage": "https://github.com/Sudhanshu-Ambastha/glsl-header#readme",
-  "logo": "./assets/glsl_header.svg",
   "keywords": [
     "glsl",
     "shaders",
@@ -29,6 +30,7 @@
   ],
   "author": "Sudhanshu Ambastha",
   "license": "MIT",
+  "sideEffects": false,
   "peerDependencies": {
     "three": "^0.150.0 || ^0.160.0"
   }

package/src/derived.js

@@ -1,11 +1,60 @@
 import { compileExpr } from "./expr.js";
 
 export function buildDerived(defs) {
-  const items = Object.entries(defs)
-    .filter(([, d]) => typeof d.expr === "string")
-    .map(([name, d]) => ({ name, ...compileExpr(d.expr) }));
+  const items = [];
+  const graph = new Map();
+  const inDegree = new Map();
+  const defsMap = new Map();
 
-  let first = true;
+  for (const [name, d] of Object.entries(defs)) {
+    if (d && typeof d.expr === "string") {
+      const compiled = compileExpr(d.expr);
+      defsMap.set(name, { name, ...compiled });
+      graph.set(name, new Set());
+      inDegree.set(name, 0);
+    }
+  }
+
+  for (const [name, item] of defsMap) {
+    for (const dep of item.deps) {
+      if (defsMap.has(dep)) {
+        if (!graph.has(dep)) graph.set(dep, new Set());
+        if (!graph.get(dep).has(name)) {
+          graph.get(dep).add(name);
+          inDegree.set(name, (inDegree.get(name) || 0) + 1);
+        }
+      }
+    }
+  }
+
+  const queue = [];
+  for (const [name, degree] of inDegree) {
+    if (degree === 0) queue.push(name);
+  }
+
+  const sortedNames = [];
+  while (queue.length > 0) {
+    const curr = queue.shift();
+    sortedNames.push(curr);
+
+    const neighbors = graph.get(curr) || new Set();
+    for (const neighbor of neighbors) {
+      inDegree.set(neighbor, inDegree.get(neighbor) - 1);
+      if (inDegree.get(neighbor) === 0) {
+        queue.push(neighbor);
+      }
+    }
+  }
+
+  if (sortedNames.length !== defsMap.size) {
+    throw new Error(
+      "GLSLH Dependency Error: Circular dependency detected in derived @uniforms expressions!",
+    );
+  }
+
+  for (const name of sortedNames) {
+    items.push(defsMap.get(name));
+  }
 
   return function update(
     uniforms,
@@ -22,30 +71,39 @@ export function buildDerived(defs) {
     };
 
     for (const [n, u] of Object.entries(uniforms)) {
-      if (typeof u.value === "number") {
-        ctx[n] = u.value;
+      if (u && u.value !== undefined) {
+        if (typeof u.value === "number") {
+          ctx[n] = u.value;
+        } else if (
+          Array.isArray(u.value) ||
+          u.value.isVector2 ||
+          u.value.isVector3 ||
+          u.value.isVector4
+        ) {
+          ctx[n] = u.value;
+        }
       }
     }
 
     for (const it of items) {
-      if (!first && it.deps.length === 0) continue;
-
       const v = it.run(ctx);
       const u = uniforms[it.name];
 
-      if (!u) continue;
+      if (!u || u.value === undefined) continue;
 
-      if (Array.isArray(v) && typeof u.value.set === "function") {
+      if (u.value.isColor && Array.isArray(v)) {
+        u.value.setRGB(v[0], v[1], v[2]);
+      } else if (Array.isArray(v) && typeof u.value.set === "function") {
         u.value.set(...v);
+      } else if (typeof v === "number" && typeof u.value === "number") {
+        u.value = v;
+      } else if (typeof u.value.set === "function" && typeof v === "number") {
+        u.value.set(v);
       } else {
         u.value = v;
       }
 
-      if (typeof v === "number") {
-        ctx[it.name] = v;
-      }
+      ctx[it.name] = v;
     }
-
-    first = false;
   };
 }

package/src/dom-canvas.js

@@ -8,80 +8,98 @@ export class GLSLHDomCanvas {
     this.width = Number.parseInt(this.canvas.getAttribute("width"), 10) || 600;
     this.height =
       Number.parseInt(this.canvas.getAttribute("height"), 10) || 400;
+
+    this.ready = false;
+    this.error = null;
+    this.animationId = null;
+    this.mouseX = 0.0;
+    this.mouseY = 0.0;
+
     this.init();
+    this.bindEvents();
+  }
+
+  bindEvents() {
+    this.onMouseMove = (e) => {
+      const rect = this.canvas.getBoundingClientRect();
+      this.mouseX = e.clientX - rect.left;
+      // Invert Y to match standard GLSL coordinate conventions (bottom-left origin)
+      this.mouseY = rect.height - (e.clientY - rect.top);
+    };
+    this.canvas.addEventListener("mousemove", this.onMouseMove);
   }
 
   async init() {
     const fragUrl = this.canvas.getAttribute("data-fragment-url");
 
     console.log("GLSLH: Initializing WebGL Renderer...");
-    this.renderer = new THREE.WebGLRenderer({
-      canvas: this.canvas,
-      antialias: true,
-    });
-    this.renderer.setSize(this.width, this.height, false);
-
-    this.scene = new THREE.Scene();
-    this.camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
-
-    const vertexShader = `
-      void main() {
-        gl_Position = vec4(position, 1.0);
-      }
-    `;
+    try {
+      this.renderer = new THREE.WebGLRenderer({
+        canvas: this.canvas,
+        antialias: true,
+      });
+      this.renderer.setSize(this.width, this.height, false);
 
-    let fragmentShader = "";
-    let uniforms = {};
-    let shaderModule = null;
+      this.scene = new THREE.Scene();
+      this.camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+
+      const vertexShader = `
+        void main() {
+          gl_Position = vec4(position, 1.0);
+        }
+      `;
+
+      let fragmentShader = "";
+      let uniforms = {};
+      let shaderModule = null;
 
-    try {
       console.log(`GLSLH: Fetching and parsing shader module -> ${fragUrl}`);
       shaderModule = await this.loader.loadShaderModule(fragUrl);
       console.log("GLSLH: Shader successfully parsed!", shaderModule);
 
       fragmentShader = shaderModule.source;
       uniforms = shaderModule.uniforms;
-    } catch (err) {
-      console.error("❌ GLSLH Pipeline Error:", err);
-      fragmentShader = `
-        void main() {
-          gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
-        }
-      `;
-    }
 
-    this.shaderModule = shaderModule;
-    this.uniforms = uniforms;
+      this.shaderModule = shaderModule;
+      this.uniforms = uniforms;
 
-    if (this.uniforms.u_resolution && !this.uniforms.u_resolution.value) {
-      this.uniforms.u_resolution.value = new THREE.Vector2(
-        this.width,
-        this.height,
-      );
-    }
-    if (this.uniforms.u_time && this.uniforms.u_time.value === undefined) {
-      this.uniforms.u_time.value = 0.0;
-    }
+      if (this.uniforms.u_resolution && !this.uniforms.u_resolution.value) {
+        this.uniforms.u_resolution.value = new THREE.Vector2(
+          this.width,
+          this.height,
+        );
+      }
+      if (this.uniforms.u_time && this.uniforms.u_time.value === undefined) {
+        this.uniforms.u_time.value = 0.0;
+      }
 
-    this.material = new THREE.ShaderMaterial({
-      vertexShader,
-      fragmentShader,
-      uniforms: this.uniforms,
-    });
+      this.material = new THREE.ShaderMaterial({
+        vertexShader,
+        fragmentShader,
+        uniforms: this.uniforms,
+        glslVersion: THREE.GLSL3,
+      });
 
-    const geometry = new THREE.PlaneGeometry(2, 2);
-    this.mesh = new THREE.Mesh(geometry, this.material);
-    this.scene.add(this.mesh);
+      const geometry = new THREE.PlaneGeometry(2, 2);
+      this.mesh = new THREE.Mesh(geometry, this.material);
+      this.scene.add(this.mesh);
 
-    this.clock = new THREE.Clock();
-    this.animate();
+      this.clock = new THREE.Clock();
+      this.ready = true;
+      this.animate();
+    } catch (err) {
+      this.error = err;
+      console.error("❌ GLSLH Pipeline Error:", err);
+    }
   }
 
   animate() {
-    requestAnimationFrame(() => this.animate());
+    if (!this.ready) return;
+    this.animationId = requestAnimationFrame(() => this.animate());
 
-    const elapsedTime = this.clock.getElapsedTime();
+    // Fix: Call getDelta() first to update the clock, then read elapsed time
     const delta = this.clock.getDelta();
+    const elapsedTime = this.clock.elapsedTime;
 
     if (this.uniforms.u_time) {
       this.uniforms.u_time.value = elapsedTime;
@@ -89,6 +107,9 @@ export class GLSLHDomCanvas {
     if (this.uniforms.u_delta) {
       this.uniforms.u_delta.value = delta;
     }
+    if (this.uniforms.u_mouse) {
+      this.uniforms.u_mouse.value.set(this.mouseX, this.mouseY);
+    }
 
     if (this.shaderModule && typeof this.shaderModule.update === "function") {
       try {
@@ -97,8 +118,8 @@ export class GLSLHDomCanvas {
           delta: delta,
           width: this.width,
           height: this.height,
-          mouseX: 0.0,
-          mouseY: 0.0,
+          mouseX: this.mouseX,
+          mouseY: this.mouseY,
         });
       } catch (evalErr) {
         console.error(
@@ -110,10 +131,26 @@ export class GLSLHDomCanvas {
 
     this.renderer.render(this.scene, this.camera);
   }
+
+  dispose() {
+    if (this.animationId) {
+      cancelAnimationFrame(this.animationId);
+    }
+    if (this.canvas && this.onMouseMove) {
+      this.canvas.removeEventListener("mousemove", this.onMouseMove);
+    }
+    this.mesh?.geometry?.dispose();
+    this.material?.dispose();
+    this.renderer?.dispose();
+    this.ready = false;
+    console.log("GLSLH: Canvas instance disposed cleanly.");
+  }
 }
 
 export function autoInitGlslCanvases(selector = "canvas.glsl-canvas") {
-  document
-    .querySelectorAll(selector)
-    .forEach((canvas) => new GLSLHDomCanvas(canvas));
+  const instances = [];
+  document.querySelectorAll(selector).forEach((canvas) => {
+    instances.push(new GLSLHDomCanvas(canvas));
+  });
+  return instances;
 }

package/src/expr.js

@@ -18,8 +18,44 @@ const FUNCS = new Set([
   "round",
   "sign",
   "hypot",
+  // Shader & procedural utility additions
+  "clamp",
+  "mix",
+  "smoothstep",
+  "step",
+  "mod",
+  "length",
+  "distance",
+  "dot",
+  "fract",
 ]);
 
+// Custom implementations for useful GLSL math functions not natively on Math
+const SHADER_MATH = {
+  clamp: (x, min, max) => Math.min(Math.max(x, min), max),
+  mix: (a, b, t) => a * (1 - t) + b * t,
+  smoothstep: (edge0, edge1, x) => {
+    const t = Math.max(0, Math.min(1, (x - edge0) / (edge1 - edge0)));
+    return t * t * (3 - 2 * t);
+  },
+  step: (edge, x) => (x < edge ? 0 : 1),
+  mod: (x, y) => x - y * Math.floor(x / y),
+  length: (arr) => (Array.isArray(arr) ? Math.hypot(...arr) : Math.abs(arr)),
+  distance: (a, b) => {
+    if (Array.isArray(a) && Array.isArray(b)) {
+      return Math.hypot(...a.map((v, i) => v - b[i]));
+    }
+    return Math.abs(a - b);
+  },
+  dot: (a, b) => {
+    if (Array.isArray(a) && Array.isArray(b)) {
+      return a.reduce((sum, v, i) => sum + v * b[i], 0);
+    }
+    return a * b;
+  },
+  fract: (x) => x - Math.floor(x),
+};
+
 const CONSTS = {
   PI: Math.PI,
   TAU: Math.PI * 2,
@@ -105,6 +141,10 @@ export function compileExpr(src) {
       if (eat("(")) {
         if (!FUNCS.has(name)) throw new Error(`Function not allowed: ${t.id}`);
         const args = list(")");
+
+        if (SHADER_MATH[name]) {
+          return (c) => SHADER_MATH[name](...args.map((f) => f(c)));
+        }
         return (c) => Math[name](...args.map((f) => f(c)));
       }
 
@@ -115,7 +155,7 @@ export function compileExpr(src) {
 
       deps.add(name);
       return (c) => {
-        if (!(name in c))
+        if (!Object.hasOwn(c, name))
           throw new Error(`Unknown variable "${name}" in "${src}"`);
         return c[name];
       };
@@ -123,18 +163,22 @@ export function compileExpr(src) {
     throw new Error(`Unexpected '${t.op}' in "${src}"`);
   }
 
+  function power() {
+    const base = primary();
+    if (eat("**")) {
+      const exp = power();
+      return (c) => base(c) ** exp(c);
+    }
+    return base;
+  }
+
   function unary() {
     if (eat("-")) {
       const a = unary();
       return (c) => -a(c);
     }
     eat("+");
-    const b = primary();
-    if (eat("**")) {
-      const e = unary();
-      return (c) => b(c) ** e(c);
-    }
-    return b;
+    return power();
   }
 
   const term = binary(unary, ["*", "/", "%"]);
@@ -144,3 +188,7 @@ export function compileExpr(src) {
   if (i !== toks.length) throw new Error(`Unexpected token in "${src}"`);
   return { run, deps: [...deps] };
 }
+
+export function parseExpression(src) {
+  return compileExpr(src);
+}

package/src/loader.js

@@ -1,6 +1,6 @@
 "use strict";
 import * as THREE from "three";
-import { GLSLHParser } from "./parser.js";
+import { GLSLHParser, BUILTINS } from "./parser.js";
 import { buildDerived } from "./derived.js";
 
 const ZERO_DEFAULTS = {
@@ -21,6 +21,16 @@ export class GLSLHLoader {
   async loadShaderModule(filePath) {
     const rawSource = await this.parser.fileResolver(filePath);
     const parsed = await this.parser.parse(rawSource, filePath);
+
+    for (const [builtinName, builtinInfo] of Object.entries(BUILTINS)) {
+      if (!parsed.uniforms[builtinName]) {
+        parsed.uniforms[builtinName] = {
+          type: builtinInfo.type,
+          builtin: true,
+        };
+      }
+    }
+
     const threeUniforms = this.buildThreeUniforms(parsed.uniforms);
     const updateDerived = buildDerived(parsed.uniforms);
 
@@ -34,6 +44,7 @@ export class GLSLHLoader {
           vertexShader: vertexShaderSource,
           fragmentShader: parsed.source,
           uniforms: threeUniforms,
+          glslVersion: THREE.GLSL3,
           ...extraOptions,
         });
       },

package/src/parser.js

@@ -1,3 +1,5 @@
+import { detectFunctionCollisions } from "./validator.js";
+
 export const BUILTINS = {
   u_time: { type: "f", from: (f) => f.time },
   u_delta: { type: "f", from: (f) => f.delta },
@@ -103,7 +105,6 @@ export class GLSLHParser {
       new Set(),
     );
 
-    // Run duplicate function collision check on the final flattened source
     detectFunctionCollisions(result.source);
 
     return result;
@@ -239,15 +240,10 @@ export class GLSLHParser {
       }
     }
 
-    // 1. Extract #version if present so it always stays at the absolute top
-    const versionMatch = processed.match(/^\s*#version[^\n]*\r?\n/);
-    let versionHeader = "";
-    if (versionMatch) {
-      versionHeader = versionMatch[0];
-      processed = processed.slice(versionHeader.length);
-    }
+    const versionRegex = /\s*#version\s+[^\r\n]+(?:\r?\n)?/g;
+    processed = processed.replace(versionRegex, "");
+    processed = processed.trimStart();
 
-    // 2. Build auto-injected math constants defines
     let constantsBlock = "";
     if (usedConstants.size > 0) {
       constantsBlock = "// --- GLSLH Auto-injected Math Constants ---\n";
@@ -258,7 +254,6 @@ export class GLSLHParser {
       constantsBlock += "\n";
     }
 
-    // 3. Build auto-injected uniform declarations
     let declBlock = "";
     const declLines = Object.entries(uniformsDefinition)
       .filter(
@@ -273,8 +268,7 @@ export class GLSLHParser {
         "\n\n";
     }
 
-    // 4. Re-assemble with #version strictly at the top
-    processed = versionHeader + constantsBlock + declBlock + processed;
+    processed = constantsBlock + declBlock + processed;
 
     return {
       source: processed,
@@ -282,88 +276,3 @@ export class GLSLHParser {
     };
   }
 }
-
-function detectFunctionCollisions(flattenedSource) {
-  const funcRegex =
-    /\b(float|int|bool|vec2|vec3|vec4|mat2|mat3|mat4|void)\s+(\w+)\s*\(([^)]*)\)/g;
-  const registry = new Map();
-  const lines = flattenedSource.split(/\r?\n/);
-  let currentFile = "root";
-
-  for (const line of lines) {
-    const beginMatch = line.match(/\/\/\s*---\s*BEGIN INCLUDE:\s*(.+)\s*---/);
-    if (beginMatch) {
-      currentFile = beginMatch[1].trim();
-      continue;
-    }
-
-    let match;
-    while ((match = funcRegex.exec(line)) !== null) {
-      const returnType = match[1];
-      const funcName = match[2];
-      const params = match[3].trim().replace(/\s+/g, " ");
-
-      if (funcName === "main") continue;
-      const signatureKey = `${funcName}(${params})`;
-
-      if (registry.has(signatureKey)) {
-        const firstFile = registry.get(signatureKey);
-        if (firstFile !== currentFile) {
-          console.warn(
-            `⚠️ GLSLH Duplicate Definition Warning: Exact signature '${signatureKey}' is defined in both '${firstFile}' and '${currentFile}'. This will cause a compilation clash in WebGL.`,
-          );
-        }
-      } else {
-        registry.set(signatureKey, currentFile);
-      }
-    }
-  }
-}
-
-export function translateShaderError(
-  errorMessage,
-  flattenedSource,
-  rootFilePath = "shader.glslh",
-) {
-  const lines = flattenedSource.split(/\r?\n/);
-  const lineMap = [];
-  const fileStack = [rootFilePath];
-  const lineCounters = { [rootFilePath]: 0 };
-
-  for (const line of lines) {
-    const beginMatch = line.match(/\/\/\s*---\s*BEGIN INCLUDE:\s*(.+)\s*---/);
-    const endMatch = line.match(/\/\/\s*---\s*END INCLUDE:\s*(.+)\s*---/);
-
-    if (beginMatch) {
-      const incPath = beginMatch[1].trim();
-      fileStack.push(incPath);
-      lineCounters[incPath] = 0;
-      lineMap.push({ file: incPath, line: -1, isMarker: true });
-      continue;
-    } else if (endMatch) {
-      fileStack.pop();
-      lineMap.push({
-        file: fileStack.at(-1),
-        line: -1,
-        isMarker: true,
-      });
-      continue;
-    }
-
-    const currentFile = fileStack.at(-1);
-    lineCounters[currentFile] = (lineCounters[currentFile] || 0) + 1;
-    lineMap.push({ file: currentFile, line: lineCounters[currentFile] });
-  }
-
-  const errorRegex = /(?:ERROR:\s*0:|Line\s+|:\s*0:)(\d+)/gi;
-
-  return errorMessage.replace(errorRegex, (match, lineNumStr) => {
-    const flatLine = Number.parseInt(lineNumStr, 10);
-    const mapped = lineMap.at(flatLine - 1);
-
-    if (mapped && !mapped.isMarker) {
-      return `[${mapped.file}:${mapped.line}]`;
-    }
-    return match;
-  });
-}

package/src/validator.js

@@ -0,0 +1,104 @@
+export function detectFunctionCollisions(flattenedSource) {
+  const funcRegex =
+    /\b(float|int|bool|vec2|vec3|vec4|mat2|mat3|mat4|void)\s+(\w+)\s*\(([^)]*)\)\s*(;|\{[^}]*\})/g;
+
+  const funcRegistry = new Map();
+  const lines = flattenedSource.split(/\r?\n/);
+  let currentFile = "root";
+
+  for (const line of lines) {
+    const beginMatch = line.match(/\/\/\s*---\s*BEGIN INCLUDE:\s*(.+)\s*---/);
+    if (beginMatch) {
+      currentFile = beginMatch[1].trim();
+      continue;
+    }
+
+    let match;
+    funcRegex.lastIndex = 0;
+    while ((match = funcRegex.exec(line)) !== null) {
+      const returnType = match[1];
+      const funcName = match[2];
+      const params = match[3].trim().replace(/\s+/g, " ");
+      const bodyOrSemi = match[4].trim();
+
+      if (funcName === "main") continue;
+      if (bodyOrSemi.startsWith(";")) continue;
+
+      if (!funcRegistry.has(funcName)) {
+        funcRegistry.set(funcName, new Map());
+      }
+
+      const overloads = funcRegistry.get(funcName);
+      const signatureKey = `(${params})`;
+
+      if (overloads.has(signatureKey)) {
+        const firstFile = overloads.get(signatureKey);
+        if (firstFile !== currentFile) {
+          console.warn(
+            `⚠️ GLSLH Duplicate Definition Warning: Exact signature '${funcName}${signatureKey}' is defined in both '${firstFile}' and '${currentFile}'. This will cause a compilation clash in WebGL.`,
+          );
+        }
+      } else {
+        overloads.set(signatureKey, currentFile);
+      }
+    }
+  }
+}
+
+export function translateShaderError(
+  errorMessage,
+  flattenedSource,
+  rootFilePath = "shader.glslh",
+) {
+  const lines = flattenedSource.split(/\r?\n/);
+  const lineMap = [];
+  const fileStack = [rootFilePath];
+  const lineCounters = { [rootFilePath]: 0 };
+
+  for (const line of lines) {
+    const beginMatch = line.match(/\/\/\s*---\s*BEGIN INCLUDE:\s*(.+)\s*---/);
+    const endMatch = line.match(/\/\/\s*---\s*END INCLUDE:\s*(.+)\s*---/);
+
+    if (beginMatch) {
+      const incPath = beginMatch[1].trim();
+      fileStack.push(incPath);
+      lineCounters[incPath] = 0;
+      lineMap.push({ file: incPath, line: -1, isMarker: true });
+      continue;
+    } else if (endMatch) {
+      fileStack.pop();
+      lineMap.push({
+        file: fileStack.at(-1),
+        line: -1,
+        isMarker: true,
+      });
+      continue;
+    }
+
+    const currentFile = fileStack.at(-1);
+    lineCounters[currentFile] = (lineCounters[currentFile] || 0) + 1;
+    lineMap.push({ file: currentFile, line: lineCounters[currentFile] });
+  }
+
+  const errorRegex = /(?:ERROR:\s*0:|Line\s+|:\s*0:)(\d+)/gi;
+
+  return errorMessage.replace(errorRegex, (match, lineNumStr) => {
+    const flatLine = Number.parseInt(lineNumStr, 10);
+    const mapped = lineMap.at(flatLine - 1);
+
+    if (mapped && !mapped.isMarker) {
+      const contextStart = Math.max(0, flatLine - 3);
+      const contextEnd = Math.min(lines.length - 1, flatLine + 1);
+      let snippet = "\n--- Code Context ---\n";
+
+      for (let i = contextStart; i <= contextEnd; i++) {
+        const prefix = i === flatLine - 1 ? " >> " : "    ";
+        snippet += `${prefix}${i + 1}: ${lines[i]}\n`;
+      }
+      snippet += "--------------------";
+
+      return `[File: ${mapped.file} | Line: ${mapped.line}]${snippet}`;
+    }
+    return match;
+  });
+}