glslh 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -1,6 +1,26 @@
 ## 📋 `glslh` Changelog
 
-### **v1.0.1** (Latest)
+### **v1.1.2** (Latest)
+
+- **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.
+
+---
+
+### **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

@@ -39,8 +39,8 @@
 - **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.
-- **Error Line Mapping:** Instantly translates monolithic WebGL compilation error line numbers back to their exact source file and line number (`[shape_utils.glsl:14]`).
+- **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 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.
@@ -93,22 +93,18 @@ package/
 ## 🚀 Installation & Quick Start
 
 ```bash
-npm install glslh
+npm install glslh@1.1.2
 ```
 
 ### 1. Create a `.glslh` Shader File (`./shaders/header.glslh`)
 
-Refer to the complete working example setup here: [GLSLH](https://www.google.com/search?q=./test/shaders/header.glslh)
-
 ### 2. Run Declaratively in HTML (`index.html`)
 
-Refer to the complete working example setup here: [index.html](https://www.google.com/search?q=./test/index.html)
-
 ---
 
 ## ⚡ 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** 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.
@@ -118,4 +114,4 @@ Want instant syntax highlighting, color pickers, and a live WebGL preview pane r
 
 ## 📜 License
 
-Distributed under the [**MIT License**](../LICENSE). See `LICENSE` for more information.
+Distributed under the **MIT License**. See [`LICENSE`](../LICENSE) for more information.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glslh",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "A lightweight GLSL preprocessor and runtime bridge for modular shader development.",
   "type": "module",
   "main": "./src/dom-canvas.js",

package/src/parser.js

@@ -103,7 +103,6 @@ export class GLSLHParser {
       new Set(),
     );
 
-    // Run duplicate function collision check on the final flattened source
     detectFunctionCollisions(result.source);
 
     return result;
@@ -239,7 +238,6 @@ 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) {
@@ -247,7 +245,6 @@ export class GLSLHParser {
       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";
@@ -258,7 +255,6 @@ export class GLSLHParser {
       constantsBlock += "\n";
     }
 
-    // 3. Build auto-injected uniform declarations
     let declBlock = "";
     const declLines = Object.entries(uniformsDefinition)
       .filter(
@@ -273,7 +269,6 @@ export class GLSLHParser {
         "\n\n";
     }
 
-    // 4. Re-assemble with #version strictly at the top
     processed = versionHeader + constantsBlock + declBlock + processed;
 
     return {
@@ -362,7 +357,17 @@ export function translateShaderError(
     const mapped = lineMap.at(flatLine - 1);
 
     if (mapped && !mapped.isMarker) {
-      return `[${mapped.file}:${mapped.line}]`;
+      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;
   });