glslh 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 ## 📋 `glslh` Changelog
 
-### **v1.0.1** (Latest)
+### **v1.1.1** (Latest)
+
+- **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.
+
+---
+
+### **v1.1.0**
+
+- **Duplicate Function Collision Detection & Overloading Support**: Added automated static analysis to scan included modules and warn developers if conflicting function signatures clash, while fully supporting valid GLSL function overloading distinguished by parameter signatures.
+- **Strict `#version` Directive Pinning**: Upgraded the preprocessor parsing pipeline to extract and pin `#version` directives to the absolute top of the generated string, ensuring full compliance with strict WebGL driver standards regardless of auto-injected uniform declarations or math constants.
+- **Enhanced Error Line Mapping**: Improved error translation utilities to map monolithic WebGL compilation error line numbers back to their exact source file and line number (`[shape_utils.glsl:14]`).
+
+---
+
+### **v1.0.1**
 
 - **Strict File Extension Whitelisting**: Added validation checks inside `GLSLHParser` to restrict `#include` directives exclusively to valid shader extensions (`.glsl`, `.glslh`, `.frag`, `.vert`, `.frag.glsl`, `.vert.glsl`), preventing security risks and unauthorized inclusions of non-shader files (e.g., `.py`, `.cpp`, `.txt`).
 - **Compound Header Support**: Enhanced path checking to natively support complex shader extension combinations like `.frag.glslh` and `.vert.glslh`.

package/README.md

@@ -13,22 +13,23 @@
 `glslh` establishes a clean pipeline separating CPU-side orchestration from GPU-side parallel rendering:
 
 ```
-  .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 Evaluator
- └──────────────┬──────────────┘
-                ▼
-      [ glslh Preprocessor ]
-                ▼
- ┌─────────────────────────────┐
- │  Final Pure GLSL String     │ ──► [GPU] Compiled & Executed via WebGL
- └─────────────────────────────┘
+
+.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
+└──────────────┬──────────────┘
+▼
+[ glslh Preprocessor ]
+▼
+┌─────────────────────────────┐
+│  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`), and real-time animation loops (`requestAnimationFrame`).
+- **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`).
 - **GPU-Side (WebGL / GLSL):** Pure parallel rasterization, vertex positioning, and fragment color blending executing simultaneously across graphics hardware cores.
 
 ---
@@ -37,8 +38,10 @@
 
 - **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.
-- **Self-Contained Metadata Blocks:** Define uniform data types and default values right at the top of your shader file (`@uniforms`).
+- **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]`).
+- **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="..."`).
@@ -53,7 +56,8 @@ The metadata block is an optional JSON declaration placed at the very top of you
 /* @uniforms
   {
     "u_intensity": { "type": "f", "value": 1.0 },
-    "u_color": { "type": "c", "value": [1.0, 0.4, 0.0] }
+    "u_color": { "type": "c", "value": [1.0, 0.4, 0.0] },
+    "u_wave": { "type": "f", "expr": "sin(u_time * 2.0) * 0.5" }
   }
 */
 
@@ -61,48 +65,53 @@ 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 so `glslh` can auto-bind them into Three.js uniform structures 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 so `glslh` can auto-bind and update them instantly.
 
 ### What if you forget it?
 
 **Nothing breaks.** The parser is completely fault-tolerant. If the comment block is missing, the parser simply returns an empty uniform object (`{}`), and your shader compiles and renders successfully using standard built-in uniforms (like `u_time` and `u_resolution`).
 
-- **When to Use:** Use it when your shader needs custom adjustable parameters, colors, or default numerical inputs managed from JavaScript.
-- **When to Omit:** Omit it when your shader is purely procedural, self-contained, or relies solely on built-in time and coordinate attributes.
+---
+
+## 📂 Project Structure
+
+```text
+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
+
+```
 
 ---
 
 ## 🚀 Installation & Quick Start
 
 ```bash
-npm install glslh
+npm install glslh@1.1.1
 ```
 
 ### 1. Create a `.glslh` Shader File (`./shaders/header.glslh`)
 
-Refer to the complete working example setup here: [GLSLH](./test/shaders/header.glslh)
-
 ### 2. Run Declaratively in HTML (`index.html`)
 
-Refer to the complete working example setup here: [index.html](./test/index.html)
-
 ---
 
-## 📂 Project Structure
+## ⚡ VS Code Extension (Live Preview)
 
-```text
-package/
-├── package.json
-├── README.md
-└── src/
-    ├── parser.js       # The C-style #include preprocessor & Math.PI injector
-    ├── loader.js       # Metadata JSON parser & Three.js uniform binder
-    └── dom-canvas.js   # HTML data-attribute and canvas auto-loader wrapper
+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.
+- **Multi-file Resolution:** Seamlessly traces `#include` dependencies across your project directory.
 
 ---
 
 ## 📜 License
 
-Distributed under the **MIT License**. See `LICENSE` for more information.
+Distributed under the **MIT License**. See [`LICENSE`](../LICENSE) for more information.

package/assets/glsl_header.svg

@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="24" height="24" viewBox="0 0 24 24">
-<desc>Created with SVGMaker Editor 3.5.0</desc>
-<defs>
-</defs>
-<path style="stroke: rgb(255,255,255); stroke-opacity: 0; fill: rgb(171,71,188); fill-rule: evenodd" stroke-linecap="round" d="M1.0408 8.824C2.6084 7.0349 5.4668 6.8126 7.591 8.3143 10.9769 10.6363 12.6966 10.6349 15.6607 8.2989 17.5028 6.7643 20.3984 6.9394 22.2957 8.7001 24.193 10.4608 24.448 13.2092 22.8799 14.998 21.3119 16.7868 18.4532 17.0087 16.3293 15.5065 12.9424 13.1865 11.2237 13.1858 8.2607 15.5225 6.4187 17.057 3.5233 16.8821 1.6259 15.1216-0.2714 13.3613-0.5268 10.613 1.0408 8.824Z"/>
-<path style="stroke: rgb(255,255,255); stroke-opacity: 0; fill: rgb(171,71,188); fill-rule: evenodd" stroke-linecap="round" d="M19.8155 7.7205C21.8744 7.7205 23.5435 6.092 23.5435 4.083 23.5435 2.074 21.8744 0.4455 19.8155 0.4455 17.7566 0.4455 16.0876 2.074 16.0876 4.083 16.0876 6.092 17.7566 7.7205 19.8155 7.7205Z"/>
-<path style="stroke: rgb(255,255,255); stroke-opacity: 0; fill: rgb(171,71,188); fill-rule: evenodd" stroke-linecap="round" d="M19.8155 23.5546C21.8744 23.5546 23.5435 21.926 23.5435 19.917 23.5435 17.908 21.8744 16.2795 19.8155 16.2795 17.7566 16.2795 16.0876 17.908 16.0876 19.917 16.0876 21.926 17.7566 23.5546 19.8155 23.5546Z"/>
-<path style="stroke: rgb(255,255,255); stroke-opacity: 0; fill: rgb(171,71,188); fill-rule: evenodd" stroke-linecap="round" d="M4.1845 7.7205C6.2434 7.7205 7.9124 6.092 7.9124 4.083 7.9124 2.074 6.2434 0.4454 4.1845 0.4454 2.1256 0.4454 0.4565 2.074 0.4565 4.083 0.4565 6.092 2.1256 7.7205 4.1845 7.7205Z"/>
-<path style="stroke: rgb(255,255,255); stroke-opacity: 0; fill: rgb(171,71,188); fill-rule: evenodd" stroke-linecap="round" d="M4.1845 23.5546C6.2434 23.5546 7.9124 21.926 7.9124 19.917 7.9124 17.908 6.2434 16.2795 4.1845 16.2795 2.1256 16.2795 0.4565 17.908 0.4565 19.917 0.4565 21.926 2.1256 23.5546 4.1845 23.5546Z"/>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#ab47bc">
+  <defs>
+    <circle id="circle" cx="4.184" cy="4.083" r="3.628" />
+  </defs>
+  <path fill-rule="evenodd" d="M1.041 8.824C2.608 7.035 5.467 6.813 7.591 8.314c3.386 2.322 5.106 2.321 8.07-0.015 1.842-1.535 4.738-1.36 6.635 0.401 1.897 1.761 2.152 4.51 0.584 6.298-1.568 1.789-4.427 2.011-6.551 0.509-3.387-2.32-5.105-2.321-8.068 0.016-1.842 1.534-4.737 1.359-6.635-0.402-1.897-1.761-2.152-4.509-0.585-6.297z" />
+  <use href="#circle" x="15.631" y="-.5" />
+  <use href="#circle" x="15.631" y="16.3" />
+  <use href="#circle" y="-0.5" />
+  <use href="#circle" y="16.3"/>
 </svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glslh",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "A lightweight GLSL preprocessor and runtime bridge for modular shader development.",
   "type": "module",
   "main": "./src/dom-canvas.js",
@@ -24,7 +24,8 @@
     "threejs",
     "preprocessor",
     "webgl",
-    "graphics"
+    "graphics",
+    "glslh"
   ],
   "author": "Sudhanshu Ambastha",
   "license": "MIT",

package/src/derived.js

@@ -0,0 +1,51 @@
+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) }));
+
+  let first = true;
+
+  return function update(
+    uniforms,
+    { time, delta, width, height, mouseX = 0, mouseY = 0 },
+  ) {
+    const ctx = {
+      time,
+      delta,
+      width,
+      height,
+      aspect: width / height,
+      mouseX,
+      mouseY,
+    };
+
+    for (const [n, u] of Object.entries(uniforms)) {
+      if (typeof u.value === "number") {
+        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 (Array.isArray(v) && typeof u.value.set === "function") {
+        u.value.set(...v);
+      } else {
+        u.value = v;
+      }
+
+      if (typeof v === "number") {
+        ctx[it.name] = v;
+      }
+    }
+
+    first = false;
+  };
+}

package/src/dom-canvas.js

@@ -5,20 +5,21 @@ export class GLSLHDomCanvas {
   constructor(canvasElement) {
     this.canvas = canvasElement;
     this.loader = new GLSLHLoader();
+    this.width = Number.parseInt(this.canvas.getAttribute("width"), 10) || 600;
+    this.height =
+      Number.parseInt(this.canvas.getAttribute("height"), 10) || 400;
     this.init();
   }
 
   async init() {
     const fragUrl = this.canvas.getAttribute("data-fragment-url");
-    const width = parseInt(this.canvas.getAttribute("width")) || 600;
-    const height = parseInt(this.canvas.getAttribute("height")) || 400;
 
     console.log("GLSLH: Initializing WebGL Renderer...");
     this.renderer = new THREE.WebGLRenderer({
       canvas: this.canvas,
       antialias: true,
     });
-    this.renderer.setSize(width, height, false);
+    this.renderer.setSize(this.width, this.height, false);
 
     this.scene = new THREE.Scene();
     this.camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
@@ -30,21 +31,18 @@ export class GLSLHDomCanvas {
     `;
 
     let fragmentShader = "";
-    let uniforms = {
-      u_time: { value: 0.0 },
-      u_resolution: { value: new THREE.Vector2(width, height) },
-    };
+    let uniforms = {};
+    let shaderModule = null;
 
     try {
       console.log(`GLSLH: Fetching and parsing shader module -> ${fragUrl}`);
-      const shaderModule = await this.loader.loadShaderModule(fragUrl);
+      shaderModule = await this.loader.loadShaderModule(fragUrl);
       console.log("GLSLH: Shader successfully parsed!", shaderModule);
 
       fragmentShader = shaderModule.source;
-      uniforms = { ...shaderModule.uniforms, ...uniforms };
+      uniforms = shaderModule.uniforms;
     } catch (err) {
       console.error("❌ GLSLH Pipeline Error:", err);
-      // Fallback to bright red if loading fails
       fragmentShader = `
         void main() {
           gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
@@ -52,7 +50,19 @@ export class GLSLHDomCanvas {
       `;
     }
 
+    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;
+    }
+
     this.material = new THREE.ShaderMaterial({
       vertexShader,
       fragmentShader,
@@ -70,8 +80,32 @@ export class GLSLHDomCanvas {
   animate() {
     requestAnimationFrame(() => this.animate());
 
+    const elapsedTime = this.clock.getElapsedTime();
+    const delta = this.clock.getDelta();
+
     if (this.uniforms.u_time) {
-      this.uniforms.u_time.value = this.clock.getElapsedTime();
+      this.uniforms.u_time.value = elapsedTime;
+    }
+    if (this.uniforms.u_delta) {
+      this.uniforms.u_delta.value = delta;
+    }
+
+    if (this.shaderModule && typeof this.shaderModule.update === "function") {
+      try {
+        this.shaderModule.update(this.uniforms, {
+          time: elapsedTime,
+          delta: delta,
+          width: this.width,
+          height: this.height,
+          mouseX: 0.0,
+          mouseY: 0.0,
+        });
+      } catch (evalErr) {
+        console.error(
+          "GLSLH Evaluation Error in derived update loop:",
+          evalErr,
+        );
+      }
     }
 
     this.renderer.render(this.scene, this.camera);

package/src/expr.js

@@ -0,0 +1,146 @@
+const FUNCS = new Set([
+  "sin",
+  "cos",
+  "tan",
+  "asin",
+  "acos",
+  "atan",
+  "atan2",
+  "sqrt",
+  "abs",
+  "pow",
+  "exp",
+  "log",
+  "min",
+  "max",
+  "floor",
+  "ceil",
+  "round",
+  "sign",
+  "hypot",
+]);
+
+const CONSTS = {
+  PI: Math.PI,
+  TAU: Math.PI * 2,
+  E: Math.E,
+  SQRT2: Math.SQRT2,
+};
+
+export function compileExpr(src) {
+  src = src.trim();
+  const toks = [];
+  const re =
+    /\s*(?:(\d*\.?\d+(?:[eE][+-]?\d+)?)|([A-Za-z_][\w.]*)|(\*\*|[-+*/%(),\[\]]))/y;
+
+  for (let pos = 0; pos < src.length; ) {
+    re.lastIndex = pos;
+    const m = re.exec(src);
+    if (!m) throw new Error(`Bad expression "${src}" near ${pos}`);
+    pos = re.lastIndex;
+    toks.push(
+      m[1] !== undefined
+        ? { n: +m[1] }
+        : m[2] !== undefined
+          ? { id: m[2] }
+          : { op: m[3] },
+    );
+  }
+
+  let i = 0;
+  const deps = new Set();
+  const eat = (op) => (toks[i]?.op === op ? (i++, true) : false);
+  const expect = (op) => {
+    if (!eat(op)) throw new Error(`Expected '${op}' in "${src}"`);
+  };
+
+  const binary = (next, ops) => () => {
+    let l = next();
+    for (;;) {
+      const op = ops.find(eat);
+      if (!op) return l;
+      const a = l,
+        b = next();
+      l =
+        op === "+"
+          ? (c) => a(c) + b(c)
+          : op === "-"
+            ? (c) => a(c) - b(c)
+            : op === "*"
+              ? (c) => a(c) * b(c)
+              : op === "/"
+                ? (c) => a(c) / b(c)
+                : (c) => a(c) % b(c);
+    }
+  };
+
+  const list = (end) => {
+    const xs = [];
+    if (!eat(end)) {
+      do xs.push(expr());
+      while (eat(","));
+      expect(end);
+    }
+    return xs;
+  };
+
+  function primary() {
+    const t = toks[i++];
+    if (!t) throw new Error(`Unexpected end of "${src}"`);
+    if (t.n !== undefined) return () => t.n;
+    if (t.op === "(") {
+      const e = expr();
+      expect(")");
+      return e;
+    }
+    if (t.op === "[") {
+      const xs = list("]");
+      return (c) => xs.map((f) => f(c));
+    }
+
+    if (t.id) {
+      const isMath = t.id.startsWith("Math.");
+      const name = isMath ? t.id.slice(5) : t.id;
+
+      if (eat("(")) {
+        if (!FUNCS.has(name)) throw new Error(`Function not allowed: ${t.id}`);
+        const args = list(")");
+        return (c) => Math[name](...args.map((f) => f(c)));
+      }
+
+      if (isMath) {
+        if (!(name in CONSTS)) throw new Error(`Unknown constant: ${t.id}`);
+        return () => CONSTS[name];
+      }
+
+      deps.add(name);
+      return (c) => {
+        if (!(name in c))
+          throw new Error(`Unknown variable "${name}" in "${src}"`);
+        return c[name];
+      };
+    }
+    throw new Error(`Unexpected '${t.op}' in "${src}"`);
+  }
+
+  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;
+  }
+
+  const term = binary(unary, ["*", "/", "%"]);
+  const expr = binary(term, ["+", "-"]);
+
+  const run = expr();
+  if (i !== toks.length) throw new Error(`Unexpected token in "${src}"`);
+  return { run, deps: [...deps] };
+}

package/src/loader.js

@@ -1,5 +1,17 @@
+"use strict";
 import * as THREE from "three";
 import { GLSLHParser } from "./parser.js";
+import { buildDerived } from "./derived.js";
+
+const ZERO_DEFAULTS = {
+  f: 0,
+  i: 0,
+  b: false,
+  c: [1, 1, 1],
+  v2: [0, 0],
+  v3: [0, 0, 0],
+  v4: [0, 0, 0, 0],
+};
 
 export class GLSLHLoader {
   constructor(parserInstance) {
@@ -8,13 +20,14 @@ export class GLSLHLoader {
 
   async loadShaderModule(filePath) {
     const rawSource = await this.parser.fileResolver(filePath);
-    // Pass filePath here so the parser knows the starting directory!
     const parsed = await this.parser.parse(rawSource, filePath);
     const threeUniforms = this.buildThreeUniforms(parsed.uniforms);
+    const updateDerived = buildDerived(parsed.uniforms);
 
     return {
       source: parsed.source,
       uniforms: threeUniforms,
+      update: updateDerived,
 
       createMaterial(vertexShaderSource, extraOptions = {}) {
         return new THREE.ShaderMaterial({
@@ -31,22 +44,31 @@ export class GLSLHLoader {
     const threeUniforms = {};
 
     for (const [key, def] of Object.entries(rawDefs)) {
-      let val = def.value;
+      const type =
+        def.type || (key === "u_resolution" || key === "u_mouse" ? "v2" : "f");
+      let val =
+        def.value !== undefined ? def.value : (ZERO_DEFAULTS[type] ?? 0);
 
-      switch (def.type) {
+      switch (type) {
         case "c":
           val = Array.isArray(val)
             ? new THREE.Color(...val)
             : new THREE.Color(val);
           break;
         case "v2":
-          val = Array.isArray(val) ? new THREE.Vector2(...val) : val;
+          val = Array.isArray(val)
+            ? new THREE.Vector2(...val)
+            : new THREE.Vector2(val, val);
           break;
         case "v3":
-          val = Array.isArray(val) ? new THREE.Vector3(...val) : val;
+          val = Array.isArray(val)
+            ? new THREE.Vector3(...val)
+            : new THREE.Vector3(val, val, val);
           break;
         case "v4":
-          val = Array.isArray(val) ? new THREE.Vector4(...val) : val;
+          val = Array.isArray(val)
+            ? new THREE.Vector4(...val)
+            : new THREE.Vector4(val, val, val, val);
           break;
         default:
           val = val;

package/src/parser.js

@@ -1,5 +1,23 @@
+export const BUILTINS = {
+  u_time: { type: "f", from: (f) => f.time },
+  u_delta: { type: "f", from: (f) => f.delta },
+  u_resolution: { type: "v2", from: (f) => [f.width, f.height] },
+  u_aspect: { type: "f", from: (f) => f.width / f.height },
+  u_mouse: { type: "v2", from: (f) => [f.mouseX, f.mouseY] },
+};
+
+const GLSL_TYPE = {
+  f: "float",
+  i: "int",
+  b: "bool",
+  c: "vec3",
+  v2: "vec2",
+  v3: "vec3",
+  v4: "vec4",
+};
+
 export class GLSLHParser {
-  constructor(fileResolver) {
+  constructor(fileResolver, standardLibraryResolver) {
     this.fileResolver =
       fileResolver ||
       (async (path) => {
@@ -10,6 +28,18 @@ export class GLSLHParser {
           );
         return await res.text();
       });
+
+    this.standardLibraryResolver =
+      standardLibraryResolver ||
+      (async (libPath) => {
+        const res = await fetch(`https://unpkg.com/glslh/lib/${libPath}`);
+        if (!res.ok)
+          throw new Error(
+            `Could not load standard library module: <${libPath}>`,
+          );
+        return await res.text();
+      });
+
     this.includeCache = new Map();
 
     this.allowedExtensions = [
@@ -23,6 +53,9 @@ export class GLSLHParser {
   }
 
   validateExtension(filePath) {
+    if (filePath.startsWith("http://") || filePath.startsWith("https://"))
+      return;
+
     const lowerPath = filePath.toLowerCase();
     const isValid = this.allowedExtensions.some((ext) =>
       lowerPath.endsWith(ext),
@@ -34,34 +67,58 @@ export class GLSLHParser {
     }
   }
 
-  resolvePath(parentPath, relativePath) {
+  resolvePath(parentPath, relativePath, isSystemInclude) {
+    if (isSystemInclude) {
+      return relativePath;
+    }
+
     if (!parentPath) return relativePath;
 
+    if (relativePath.startsWith("/")) {
+      return relativePath.substring(1);
+    }
+
     const lastSlash = parentPath.lastIndexOf("/");
     if (lastSlash === -1) return relativePath;
     const parentDir = parentPath.substring(0, lastSlash);
+    const stack = parentDir ? parentDir.split("/") : [];
+    const parts = relativePath.split("/");
 
-    const cleanRelative = relativePath.startsWith("./")
-      ? relativePath.substring(2)
-      : relativePath;
+    for (const part of parts) {
+      if (part === "" || part === ".") continue;
+      if (part === "..") {
+        if (stack.length > 0) stack.pop();
+      } else {
+        stack.push(part);
+      }
+    }
 
-    return `${parentDir}/${cleanRelative}`;
+    return stack.join("/");
   }
 
   async parse(sourceCode, currentFilePath = "") {
-    return await this._parseRecursive(sourceCode, currentFilePath, new Set());
+    const result = await this._parseRecursive(
+      sourceCode,
+      currentFilePath,
+      new Set(),
+    );
+
+    // Run duplicate function collision check on the final flattened source
+    detectFunctionCollisions(result.source);
+
+    return result;
   }
 
   async _parseRecursive(sourceCode, currentFilePath, includedFiles) {
     let processed = sourceCode;
-    const uniformRegex = /\/\*\s*@uniforms([\s\S]*?)\*\//;
-    const match = processed.match(uniformRegex);
+    const uniformRegex = /\/\*\s*@uniforms([\s\S]*?)\*\//g;
+    let match;
     let uniformsDefinition = {};
 
-    if (match) {
+    while ((match = uniformRegex.exec(sourceCode)) !== null) {
       try {
-        uniformsDefinition = JSON.parse(match[1].trim());
-        processed = processed.replace(uniformRegex, "");
+        const parsedBlock = JSON.parse(match[1].trim());
+        uniformsDefinition = { ...uniformsDefinition, ...parsedBlock };
       } catch (e) {
         console.error(
           "GLSLH Parser Error: Invalid JSON format inside @uniforms block.",
@@ -69,17 +126,39 @@ export class GLSLHParser {
         );
       }
     }
+    processed = processed.replace(uniformRegex, "");
 
-    const includeRegex = /^#include\s+["<](.+)[">]/gm;
+    const includeRegex = /^#include\s+(["<])(.+)([">])/gm;
     let includeMatch;
     let includes = [];
 
     while ((includeMatch = includeRegex.exec(processed)) !== null) {
-      includes.push({ fullMatch: includeMatch[0], path: includeMatch[1] });
+      const openDelimiter = includeMatch[1];
+      const incPath = includeMatch[2];
+      const closeDelimiter = includeMatch[3];
+
+      if (
+        (openDelimiter === '"' && closeDelimiter !== '"') ||
+        (openDelimiter === "<" && closeDelimiter !== ">")
+      ) {
+        throw new Error(
+          `GLSLH Syntax Error: Mismatched include delimiters for '${incPath}'`,
+        );
+      }
+
+      includes.push({
+        fullMatch: includeMatch[0],
+        path: incPath,
+        isSystem: openDelimiter === "<",
+      });
     }
 
     for (const inc of includes) {
-      const resolvedPath = this.resolvePath(currentFilePath, inc.path);
+      const resolvedPath = this.resolvePath(
+        currentFilePath,
+        inc.path,
+        inc.isSystem,
+      );
 
       this.validateExtension(resolvedPath);
 
@@ -92,30 +171,46 @@ export class GLSLHParser {
       }
       includedFiles.add(resolvedPath);
 
-      let subSource = this.includeCache.get(resolvedPath);
+      let subSource = this.includeCache.get(resolvedPath)?.source;
+      let subUniforms = {};
+
       if (!subSource) {
-        let rawSubText = await this.fileResolver(resolvedPath);
+        const rawSubText = inc.isSystem
+          ? await this.standardLibraryResolver(resolvedPath)
+          : await this.fileResolver(resolvedPath);
+
         const parsedSub = await this._parseRecursive(
           rawSubText,
           resolvedPath,
           includedFiles,
         );
         subSource = parsedSub.source;
-        this.includeCache.set(resolvedPath, subSource);
+        subUniforms = parsedSub.uniforms;
+        this.includeCache.set(resolvedPath, {
+          source: subSource,
+          uniforms: subUniforms,
+        });
+      } else {
+        subUniforms = this.includeCache.get(resolvedPath).uniforms;
       }
 
+      uniformsDefinition = { ...subUniforms, ...uniformsDefinition };
+
       processed = processed.replace(
         inc.fullMatch,
         `\n// --- BEGIN INCLUDE: ${resolvedPath} ---\n${subSource}\n// --- END INCLUDE: ${resolvedPath} ---\n`,
       );
     }
 
+    const usedConstants = new Set();
+
     processed = processed.replace(
       /Math\.([A-Z0-9_]+)/g,
       (match, constantName) => {
-        if (constantName === "TAU") return (Math.PI * 2).toString();
-        if (typeof Math[constantName] === "number")
-          return Math[constantName].toString();
+        if (constantName === "TAU" || typeof Math[constantName] === "number") {
+          usedConstants.add(constantName);
+          return `MATH_${constantName}`;
+        }
         console.warn(
           `GLSLH Warning: Unknown Math constant 'Math.${constantName}'`,
         );
@@ -123,9 +218,152 @@ export class GLSLHParser {
       },
     );
 
+    const cleanCodeForScanning = processed.replace(
+      /\/\/.*|\/\*[\s\S]*?\*\//g,
+      "",
+    );
+    const usedUniforms = [
+      ...new Set(cleanCodeForScanning.match(/\bu_\w+\b/g) ?? []),
+    ];
+
+    for (const name of usedUniforms) {
+      if (BUILTINS[name]) {
+        uniformsDefinition[name] ??= {
+          type: BUILTINS[name].type,
+          builtin: true,
+        };
+      } else if (!uniformsDefinition[name]) {
+        console.warn(
+          `GLSLH Warning: Uniform '${name}' is used in shader source but not defined in @uniforms or built-ins.`,
+        );
+      }
+    }
+
+    // 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);
+    }
+
+    // 2. Build auto-injected math constants defines
+    let constantsBlock = "";
+    if (usedConstants.size > 0) {
+      constantsBlock = "// --- GLSLH Auto-injected Math Constants ---\n";
+      for (const constantName of usedConstants) {
+        const val = constantName === "TAU" ? Math.PI * 2 : Math[constantName];
+        constantsBlock += `#define MATH_${constantName} ${val}\n`;
+      }
+      constantsBlock += "\n";
+    }
+
+    // 3. Build auto-injected uniform declarations
+    let declBlock = "";
+    const declLines = Object.entries(uniformsDefinition)
+      .filter(
+        ([n]) => !new RegExp(`\\buniform\\s+\\w+\\s+${n}\\b`).test(processed),
+      )
+      .map(([n, d]) => `uniform ${GLSL_TYPE[d.type] ?? "float"} ${n};`);
+
+    if (declLines.length > 0) {
+      declBlock =
+        "\n// --- GLSLH Auto-injected Uniform Declarations ---\n" +
+        declLines.join("\n") +
+        "\n\n";
+    }
+
+    // 4. Re-assemble with #version strictly at the top
+    processed = versionHeader + constantsBlock + declBlock + processed;
+
     return {
       source: processed,
       uniforms: uniformsDefinition,
     };
   }
 }
+
+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;
+  });
+}