webgl2 1.0.1 → 1.0.4

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2025 WebGL2 Platform Team
+All Rights Reserved.
+
+THIS IS A RESTRICTIVE PLACEHOLDER LICENSE (PROPRIETARY).
+
+Permission to use, copy, modify, distribute, or publish this software, in whole
+or in part, is NOT granted. All rights are reserved by the copyright holder.
+
+This file is intentionally restrictive and intended only as a temporary
+placeholder to allow packaging/testing in private. Replace this file with an
+appropriate open-source license (for example, MIT or Apache-2.0)
+ if you intend to grant any rights to others.
+
+-- END OF PLACEHOLDER LICENSE --

package/README.md

@@ -0,0 +1,203 @@
+# WebGL2 Development Platform: VISION
+
+A **Rust + WASM** based toolkit for debugging GLSL shaders and generating ergonomic WebGL2 bindings.
+
+## 🎯 Quick Start
+
+```bash
+# Build the project
+cargo build --release
+
+# Compile a GLSL shader to WASM with debug info
+cargo run --bin webgl2 -- compile tests/fixtures/simple.vert --debug
+
+# Validate a shader
+cargo run --bin webgl2 -- validate tests/fixtures/simple.frag
+
+# Generate TypeScript harness
+cargo run --bin webgl2 -- codegen tests/fixtures/simple.vert -o output.ts
+```
+
+### Build via npm
+
+This repository is both a Rust workspace and an npm package. Run the npm build helper to build the Rust workspace for the WASM target and copy produced .wasm files into `runners/wasm/`:
+
+```bash
+# from repository root
+npm run build
+```
+
+Notes:
+- The script runs `cargo build --target wasm32-unknown-unknown --release` and copies any `.wasm` files from `target/wasm32-unknown-unknown/release/` into `runners/wasm/`.
+- If you need `wasm-bindgen` output (JS glue), run `wasm-bindgen` manually on the produced `.wasm` files; adding automated wasm-bindgen support is a follow-up task.
+
+## 🚀 Project Overview and Goals
+
+The project aims to create a **Composite WebGL2 Development Platform** built with **Rust and WASM**. The primary objective is to significantly improve the developer experience by introducing standard software engineering practices—specifically, **robust debugging and streamlined resource management**—into the WebGL/GLSL workflow, which is currently hindered by platform-specific API complexity and opaque GPU execution.
+
+| Key Goals | Target Block | Value Proposition |
+| :--- | :--- | :--- |
+| **GPU Debugging** | Block 1 (Emulator) | Enable **step-through debugging**, breakpoints, and variable inspection for GLSL code. |
+| **Unit Testing** | Block 1 (Emulator) | Provide a stable, deterministic environment for **automated testing** of graphics logic. |
+| **API Ergonomics** | Block 2 (Codegen) | **Automate boilerplate code** for resource binding, attribute setup, and uniform linking. |
+| **Tech Stack** | Both | Utilize **Rust for safety and WASM for high-performance cross-platform execution** in the browser. |
+
+-----
+
+## 🛠️ Functional Block 1: WebGL2 Software Rendering Pipeline (The Debugger)
+
+This block provides the **deterministic, inspectable execution environment** for GLSL logic.
+
+### 1\. **Core Component: Rust-based WebGL2 Emulator (`wasm-gl-emu`)**
+
+  * **State Machine Emulation:** Implement a full software model of the WebGL2 state (e.g., Framebuffer Objects, Renderbuffers, Texture Units, Vertex Array Objects, current programs, depth/stencil settings). This component will track all API calls and maintain a CPU-accessible copy of all state.
+  * **Rasterization Logic:** Implement CPU-based vertex and fragment processing. This logic must precisely follow the WebGL2/OpenGL ES 3.0 specification, including clipping, primitive assembly, and the fragment pipeline (culling, depth test, blending).
+  * **Input/Output:** Expose the emulator's state and rendering results via a standard Rust interface that can be compiled to WASM and wrapped for JavaScript access.
+
+### 2\. **GLSL Translation and Debugging Integration (`glsl-to-wasm`)**
+
+  * **GLSL Frontend:** Use a Rust-based GLSL parser (e.g., based on `naga` or a custom parser) to convert shader source code into an Intermediate Representation (IR).
+  * **WASM Backend:** Compile the IR into **WASM module functions**. Each shader stage (Vertex, Fragment) will be converted into a function that executes the shader logic on a single vertex or fragment input.
+  * **Source Map Generation:** The crucial step is to generate **high-quality source maps** that link the generated WASM instructions back to the original GLSL source code line and variable names. This enables DevTools/IDE to pause WASM execution and display the corresponding GLSL line and variable values.
+  * **JIT Compilation:** For performance during debugging, the WASM modules can be compiled using a fast JIT compiler (potentially leveraging existing browser capabilities or a custom runtime) to execute the many vertex/fragment calls.
+
+### 3\. **Debugging and Testing Harness**
+
+  * **Test Runner:** Develop a testing harness in Rust/WASM that can execute a defined set of inputs (e.g., vertex attributes, uniform values) against the emulated pipeline and assert on the final pixel output or intermediate variable state.
+  * **Step-Through Integration:** The WASM modules, when run by the browser's JavaScript engine, will expose the generated source maps, allowing the developer to naturally set **breakpoints** within the GLSL source file viewed in the browser's DevTools (or a connected IDE).
+
+-----
+
+## ⚙️ Functional Block 2: Introspection and Codegen Tool (The Ergonomics Layer)
+
+This block automates the error-prone, repetitive JavaScript/TypeScript code required for WebGL2 resource setup.
+
+### 1\. **GLSL Introspection Engine (`glsl-parser-rs`)**
+
+  * **Parsing:** Use a dedicated Rust parser to analyze the GLSL source files (both Vertex and Fragment shaders).
+  * **Annotation Extraction:** The parser must identify and extract **discardable annotations** embedded in the GLSL source.
+      * *Example Annotation:*
+        ```glsl
+        //! @buffer_layout MeshData
+        layout(location = 0) in vec3 a_position;
+        // JSDoc-like for resource description
+        /** @uniform_group Camera @semantic ProjectionMatrix */
+        uniform mat4 u_projection;
+        ```
+  * **Resource Mapping:** Generate a structured data model (e.g., JSON or Rust structs) that lists all attributes, uniforms, uniform blocks, and their associated types, locations, and extracted metadata (like semantic hints from the annotations).
+
+### 2\. **Code Generation Module (`js-harness-codegen`)**
+
+  * **Harness Template:** Define a set of customizable templates (e.g., Handlebars, Tera) for generating the target **JavaScript/TypeScript harness code**.
+  * **Code Generation:** Using the resource map data from the parser, the module will generate files that:
+      * Define **JavaScript/TypeScript classes** for each shader program.
+      * Provide methods for **binding resource objects** (e.g., `program.setUniforms(cameraData)`).
+      * Implement all the necessary `gl.bindBuffer()`, `gl.getUniformLocation()`, `gl.vertexAttribPointer()`, and `gl.uniformX()` calls.
+      * *Goal:* Reduce the developer's WebGL setup code to simple, type-safe resource assignments.
+
+### 3\. **Tool Integration**
+
+  * Package the Rust component as a **Command-Line Interface (CLI)** tool (or an accompanying library) that runs during the build step, consuming GLSL files and outputting the JavaScript/TypeScript harness code. This integrates smoothly into modern build pipelines (e.g., Webpack, Vite).
+
+-----
+
+## ⏳ Project Phases and Deliverables
+
+| Phase | Duration | Focus | Key Deliverables |
+| :--- | :--- | :--- | :--- |
+| **Phase 1** | 3 Months | Core Compiler & Codegen | Functional GLSL parser (Block 2). CLI tool for JS harness generation (Block 2). Prototype `glsl-to-wasm` compiler (Block 1). |
+| **Phase 2** | 4 Months | Core Emulator Implementation | Basic WebGL2 State Machine and Triangle Rasterizer (Block 1). Source Map integration (GLSL \<-\> WASM \<-\> DevTools) (Block 1). |
+| **Phase 3** | 3 Months | Feature Completion & Polishing | Full WebGL2 feature set support in emulator (textures, complex blending, stencil). Robustness testing and documentation. |
+| **Phase 4** | 2 Months | Integration & Release | Unit testing framework integration. Final documentation and developer tutorials. Full platform release. |
+
+-----
+
+## � Project Structure
+
+```
+webgl2/
+├── crates/
+│   ├── naga-wasm-backend/    # Naga IR → WASM compiler with DWARF
+│   ├── wasm-gl-emu/          # Software rasterizer & WASM runtime
+│   ├── glsl-introspection/   # GLSL parser + annotation extraction
+│   ├── js-codegen/           # TypeScript harness generator
+│   └── webgl2-cli/           # Command-line interface
+├── tests/fixtures/           # Test shaders
+├── docs/                     # Detailed documentation
+│   ├── 1-plan.md            # Original project plan
+│   └── 1.1-ir-wasm.md       # Naga IR → WASM architecture
+└── external/                 # Reference implementations (naga, wgpu, servo)
+```
+
+## 🏗️ Architecture
+
+This project uses **Naga** (from the wgpu/WebGPU ecosystem) as the shader IR, rather than building a custom IR from scratch. This significantly reduces complexity while providing a proven, well-maintained foundation.
+
+### Key Components
+
+1. **naga-wasm-backend**: Translates Naga IR to WebAssembly with DWARF debug information
+2. **wasm-gl-emu**: Executes WASM shaders in a software rasterizer for debugging
+3. **glsl-introspection**: Parses GLSL and extracts resource metadata
+4. **js-codegen**: Generates ergonomic TypeScript bindings
+5. **webgl2-cli**: Unified command-line tool
+
+See [`docs/1.1-ir-wasm.md`](docs/1.1-ir-wasm.md) for detailed architecture documentation.
+
+## 🔧 Development Status
+
+**Current Phase: Phase 0 - Foundation Setup** ✅
+
+- [x] Workspace structure created
+- [x] Core crate skeletons implemented
+- [x] Basic WASM backend (emits empty functions)
+- [x] Runtime structure (wasmtime integration)
+- [x] CLI tool with compile/validate/codegen/run commands
+- [ ] DWARF debug information generation (in progress)
+- [ ] Browser DevTools integration validation
+
+## 📚 Documentation
+
+- [`docs/1-plan.md`](docs/1-plan.md) - Original project proposal and plan
+- [`docs/1.1-ir-wasm.md`](docs/1.1-ir-wasm.md) - Naga IR → WASM architecture (recommended reading)
+- [`external/use.md`](external/use.md) - Guide to leveraging external repositories
+
+## ⏳ Project Phases
+
+| Phase | Duration | Focus | Status |
+| :--- | :--- | :--- | :--- |
+| **Phase 0** | 2 Weeks | Foundation & DWARF Validation | **In Progress** |
+| **Phase 1** | 8 Weeks | Core Backend (scalars, vectors, control flow) | Not Started |
+| **Phase 2** | 6 Weeks | Advanced Features (uniforms, textures, matrices) | Not Started |
+| **Phase 3** | 4 Weeks | Software Rasterizer Integration | Not Started |
+| **Phase 4** | 8 Weeks | Codegen Tool & Polish | Not Started |
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+cargo test
+
+# Test with a simple shader
+cargo run --bin webgl2 -- compile tests/fixtures/simple.vert --debug -o output.wasm
+cargo run --bin webgl2 -- run output.wasm
+```
+
+## 🤝 Contributing
+
+This project is in early development. Contributions are welcome once Phase 0 is complete and the architecture is validated.
+
+## 📄 License
+
+MIT OR Apache-2.0
+
+-----
+
+## �💰 Resource Requirements
+
+The project will require specialized expertise in:
+
+  * **Rust and WASM Development**
+  * **Computer Graphics / GPU Pipeline Implementation** (for the emulator)
+  * **Compiler Design / Language Tooling** (for GLSL parsing and source map generation)
+
+Would you like to discuss the **specific toolchain recommendations** for the GLSL-to-WASM compilation process?

package/index.js

@@ -0,0 +1,15 @@
+// index.js (compat shim)
+// Re-export the new implementation in `index2.js` so existing consumers who
+// import `index.js` keep working. The legacy implementation was removed and
+// moved to `index2.js` which contains the canonical, tested API.
+
+const isNode = typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
+
+if (isNode) {
+  // In Node.js environments re-export everything from index2.js
+  module.exports = require('./index2.js');
+} else {
+  // In browsers assume `index2.js` is loaded alongside this file and has
+  // populated `window.webGL2`. Nothing else to do here.
+  // (Keeping a no-op shim avoids duplicating the implementation.)
+}

package/package.json

@@ -1,12 +1,37 @@
 {
   "name": "webgl2",
-  "version": "1.0.1",
-  "description": "",
+  "version": "1.0.4",
+  "description": "WebGL2 tools to derisk large GPU projects on the web beyond toys and demos.",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "start": "node ./index.js",
+    "build:wasm": "node ./scripts/build-wasm.js",
+    "build": "node -e \"(async()=>{const p=require('path');const dir=process.env.INIT_CWD||process.cwd();require(p.join(dir,'scripts','build-wasm.js'));})()\"",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "test:smoke": "npm run build:wasm && node ./test/smoke.js"
+  },
+  "wasmBuild": {
+    "outDir": "wasm",
+    "target": "wasm32-unknown-unknown",
+    "profile": "release"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mavity/mavity"
   },
   "keywords": [],
   "author": "",
-  "license": "ISC"
+  "license": "TBD",
+  "bugs": {
+    "url": "https://github.com/mavity/mavity/issues"
+  },
+  "homepage": "https://github.com/mavity/mavity#readme"
+  ,
+  "files": [
+    "index.js",
+    "wasm",
+    "README.md",
+    "LICENSE"
+  ]
 }