glslh 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+## 📋 `glslh` Changelog
+
+### **v1.0.1** (Latest)
+
+- **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`.
+- **Robust Error Messaging**: Improved failure handling and descriptive console warnings/errors when file resolution or extension validation fails.
+
+---
+
+### **v1.0.0**
+
+- **Recursive C-Style `#include` Preprocessor**: Introduced core parsing logic enabling `.glslh` and `.glsl` files to modularly include other shader headers recursively with built-in circular dependency protection.
+- **Dynamic JavaScript Math Constant Injection**: Added automatic replacement of JS math expressions (such as `Math.PI` and `Math.TAU`) directly into clean GLSL numeric floats.
+- **Metadata Uniforms Block (`@uniforms`)**: Implemented support for JSON-parsed `@uniforms` comment blocks to automatically generate and format Three.js uniform maps.
+- **Zero-Config DOM Canvas Integration (`GLSLHDomCanvas`)**: Released `autoInitGlslCanvases()` to instantly bind canvas elements to Three.js WebGL renderers with automatic shader loading and animation loops.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# glslh ⚡
+
+> A modular C-style `#include` preprocessor and metadata-driven uniform binder for GLSL shaders, built for zero-boilerplate integration across Vanilla WebGL, Three.js, and React Three Fiber.
+
+[![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/)
+
+---
+
+## 🎨 Architecture & CPU/GPU Division of Labor
+
+`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
+ └─────────────────────────────┘
+
+```
+
+- **CPU-Side (JavaScript):** File fetching, `#include` stitching, uniform metadata parsing, constant macro evaluation (`Math.PI`, `Math.TAU`), 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.
+
+---
+
+## ✨ Features & Benefits
+
+- **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`).
+- **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="..."`).
+
+---
+
+## 🔍 Understanding the `/* @uniforms */` Block
+
+The metadata block is an optional JSON declaration placed at the very top of your `.glslh` header file:
+
+```glsl
+/* @uniforms
+  {
+    "u_intensity": { "type": "f", "value": 1.0 },
+    "u_color": { "type": "c", "value": [1.0, 0.4, 0.0] }
+  }
+*/
+
+```
+
+### 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.
+
+### 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.
+
+---
+
+## 🚀 Installation & Quick Start
+
+```bash
+npm install glslh
+```
+
+### 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
+
+```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
+
+```
+
+---
+
+## 📜 License
+
+Distributed under the **MIT License**. See `LICENSE` for more information.

package/assets/glsl_header.svg

@@ -0,0 +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>

package/package.json

@@ -1,6 +1,34 @@
-{
-  "name": "glslh",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "glslh",
+  "version": "1.0.1",
+  "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"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sudhanshu-Ambastha/glsl-header.git"
+  },
+  "bugs": {
+    "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",
+    "threejs",
+    "preprocessor",
+    "webgl",
+    "graphics"
+  ],
+  "author": "Sudhanshu Ambastha",
+  "license": "MIT",
+  "peerDependencies": {
+    "three": "^0.150.0 || ^0.160.0"
+  }
+}

package/src/dom-canvas.js

@@ -0,0 +1,85 @@
+import * as THREE from "three";
+import { GLSLHLoader } from "./loader.js";
+
+export class GLSLHDomCanvas {
+  constructor(canvasElement) {
+    this.canvas = canvasElement;
+    this.loader = new GLSLHLoader();
+    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.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 = {
+      u_time: { value: 0.0 },
+      u_resolution: { value: new THREE.Vector2(width, height) },
+    };
+
+    try {
+      console.log(`GLSLH: Fetching and parsing shader module -> ${fragUrl}`);
+      const shaderModule = await this.loader.loadShaderModule(fragUrl);
+      console.log("GLSLH: Shader successfully parsed!", shaderModule);
+
+      fragmentShader = shaderModule.source;
+      uniforms = { ...shaderModule.uniforms, ...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);
+        }
+      `;
+    }
+
+    this.uniforms = uniforms;
+    this.material = new THREE.ShaderMaterial({
+      vertexShader,
+      fragmentShader,
+      uniforms: this.uniforms,
+    });
+
+    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();
+  }
+
+  animate() {
+    requestAnimationFrame(() => this.animate());
+
+    if (this.uniforms.u_time) {
+      this.uniforms.u_time.value = this.clock.getElapsedTime();
+    }
+
+    this.renderer.render(this.scene, this.camera);
+  }
+}
+
+export function autoInitGlslCanvases(selector = "canvas.glsl-canvas") {
+  document
+    .querySelectorAll(selector)
+    .forEach((canvas) => new GLSLHDomCanvas(canvas));
+}

package/src/loader.js

@@ -0,0 +1,61 @@
+import * as THREE from "three";
+import { GLSLHParser } from "./parser.js";
+
+export class GLSLHLoader {
+  constructor(parserInstance) {
+    this.parser = parserInstance || new GLSLHParser();
+  }
+
+  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);
+
+    return {
+      source: parsed.source,
+      uniforms: threeUniforms,
+
+      createMaterial(vertexShaderSource, extraOptions = {}) {
+        return new THREE.ShaderMaterial({
+          vertexShader: vertexShaderSource,
+          fragmentShader: parsed.source,
+          uniforms: threeUniforms,
+          ...extraOptions,
+        });
+      },
+    };
+  }
+
+  buildThreeUniforms(rawDefs) {
+    const threeUniforms = {};
+
+    for (const [key, def] of Object.entries(rawDefs)) {
+      let val = def.value;
+
+      switch (def.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;
+          break;
+        case "v3":
+          val = Array.isArray(val) ? new THREE.Vector3(...val) : val;
+          break;
+        case "v4":
+          val = Array.isArray(val) ? new THREE.Vector4(...val) : val;
+          break;
+        default:
+          val = val;
+          break;
+      }
+
+      threeUniforms[key] = { value: val };
+    }
+
+    return threeUniforms;
+  }
+}

package/src/parser.js

@@ -0,0 +1,131 @@
+export class GLSLHParser {
+  constructor(fileResolver) {
+    this.fileResolver =
+      fileResolver ||
+      (async (path) => {
+        const res = await fetch(path);
+        if (!res.ok)
+          throw new Error(
+            `Could not load shader file: ${path} (Status: ${res.status})`,
+          );
+        return await res.text();
+      });
+    this.includeCache = new Map();
+
+    this.allowedExtensions = [
+      ".glsl",
+      ".glslh",
+      ".frag",
+      ".vert",
+      ".frag.glsl",
+      ".vert.glsl",
+    ];
+  }
+
+  validateExtension(filePath) {
+    const lowerPath = filePath.toLowerCase();
+    const isValid = this.allowedExtensions.some((ext) =>
+      lowerPath.endsWith(ext),
+    );
+    if (!isValid) {
+      throw new Error(
+        `GLSLH Security Error: Unsupported file extension for include -> '${filePath}'. Allowed extensions: ${this.allowedExtensions.join(", ")}`,
+      );
+    }
+  }
+
+  resolvePath(parentPath, relativePath) {
+    if (!parentPath) return relativePath;
+
+    const lastSlash = parentPath.lastIndexOf("/");
+    if (lastSlash === -1) return relativePath;
+    const parentDir = parentPath.substring(0, lastSlash);
+
+    const cleanRelative = relativePath.startsWith("./")
+      ? relativePath.substring(2)
+      : relativePath;
+
+    return `${parentDir}/${cleanRelative}`;
+  }
+
+  async parse(sourceCode, currentFilePath = "") {
+    return await this._parseRecursive(sourceCode, currentFilePath, new Set());
+  }
+
+  async _parseRecursive(sourceCode, currentFilePath, includedFiles) {
+    let processed = sourceCode;
+    const uniformRegex = /\/\*\s*@uniforms([\s\S]*?)\*\//;
+    const match = processed.match(uniformRegex);
+    let uniformsDefinition = {};
+
+    if (match) {
+      try {
+        uniformsDefinition = JSON.parse(match[1].trim());
+        processed = processed.replace(uniformRegex, "");
+      } catch (e) {
+        console.error(
+          "GLSLH Parser Error: Invalid JSON format inside @uniforms block.",
+          e,
+        );
+      }
+    }
+
+    const includeRegex = /^#include\s+["<](.+)[">]/gm;
+    let includeMatch;
+    let includes = [];
+
+    while ((includeMatch = includeRegex.exec(processed)) !== null) {
+      includes.push({ fullMatch: includeMatch[0], path: includeMatch[1] });
+    }
+
+    for (const inc of includes) {
+      const resolvedPath = this.resolvePath(currentFilePath, inc.path);
+
+      this.validateExtension(resolvedPath);
+
+      if (includedFiles.has(resolvedPath)) {
+        processed = processed.replace(
+          inc.fullMatch,
+          `// Circular include prevented: ${resolvedPath}`,
+        );
+        continue;
+      }
+      includedFiles.add(resolvedPath);
+
+      let subSource = this.includeCache.get(resolvedPath);
+      if (!subSource) {
+        let rawSubText = await this.fileResolver(resolvedPath);
+        const parsedSub = await this._parseRecursive(
+          rawSubText,
+          resolvedPath,
+          includedFiles,
+        );
+        subSource = parsedSub.source;
+        this.includeCache.set(resolvedPath, subSource);
+      }
+
+      processed = processed.replace(
+        inc.fullMatch,
+        `\n// --- BEGIN INCLUDE: ${resolvedPath} ---\n${subSource}\n// --- END INCLUDE: ${resolvedPath} ---\n`,
+      );
+    }
+
+    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();
+        console.warn(
+          `GLSLH Warning: Unknown Math constant 'Math.${constantName}'`,
+        );
+        return match;
+      },
+    );
+
+    return {
+      source: processed,
+      uniforms: uniformsDefinition,
+    };
+  }
+}