webgl2 1.0.3 → 1.0.5

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

@@ -1,120 +1,205 @@
-## GLSL++: Unified WASM Core for Debugging and Generation
+# WebGL2 Development Platform: VISION
 
-This plan is a comprehensive roadmap for the **GLSL++** project. The core is a single **WASM artifact** that provides two distinct, clean interfaces for both runtime emulation (Component 1) and build-time code generation (Component 2).
+A **Rust + WASM** based toolkit for debugging GLSL shaders and generating ergonomic WebGL2 bindings.
 
-The entire system is focused on **Correctness and Debugging Fidelity**, leveraging existing Rust graphics crates to minimize the implementation of the $\sim$300 WebGL2 APIs.
+![WebGL2 Singing Dog Logo](./webgl2.png)
 
------
+## 🎯 Quick Start
 
-## I. Unified WASM Architecture and Delivery
+```bash
+# Build the project
+cargo build --release
 
-The project compiles into a single `.wasm` file and a single `.js` glue file, ensuring maximum portability between Node.js and browsers.
+# Compile a GLSL shader to WASM with debug info
+cargo run --bin webgl2 -- compile tests/fixtures/simple.vert --debug
 
-### A. Final Artifacts
+# Validate a shader
+cargo run --bin webgl2 -- validate tests/fixtures/simple.frag
 
-| Artifact | Content | Purpose |
-| :--- | :--- | :--- |
-| **`glsl_plus_plus.wasm`** | Compiled Rust code for both Component 1 (GL Emulation) and Component 2 (Transpiler). | The **Core Engine**. |
-| **`glsl_plus_plus.js`** | Universal ES Module wrapper for asynchronous loading and initialization. | The **Clean Interface** for consumers. |
+# Generate TypeScript harness
+cargo run --bin webgl2 -- codegen tests/fixtures/simple.vert -o output.ts
+```
 
-### B. Core Dependencies (Shared `Cargo.toml`)
+### 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
+```
 
-| Crate | Role | Component(s) |
+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 |
 | :--- | :--- | :--- |
-| **`glow`** | **API Surface Definition (300+ methods).** | **C1** |
-| **`wasm-bindgen`** | **JS/WASM Interop and Struct Export.** | **C1 & C2** |
-| **`naga`** | **GLSL Parsing, Reflection, and IR Generation.** | **C1 & C2** |
-| **`glam`** | **Vector/Matrix Math for Rasterizer.** | **C1** |
-| **`hashbrown`** | **Fast Resource Registry (`u32` handles).** | **C1** |
-| **`serde` / `serde-wasm-bindgen`** | **Safe, clean transfer of configuration and metadata objects.** | **C2** |
-| **`wgpu-types`** | **Validated Resource Structs (optional, highly recommended).** | **C1** |
+| **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. |
 
 -----
 
-## II. Component 1: WASM GL Emulation Core (Runtime) 🎨
+## 🛠️ Functional Block 1: WebGL2 Software Rendering Pipeline (The Debugger)
 
-This component implements the $\sim$300 WebGL2 API methods via the `glow` trait, running a pure software rasterizer for unit testing.
+This block provides the **deterministic, inspectable execution environment** for GLSL logic.
 
-### A. External Interface: The Factory Function
+### 1\. **Core Component: Rust-based WebGL2 Emulator (`wasm-gl-emu`)**
 
-Component 1 is accessed through a factory function to manage state initialization, ensuring the clean API shape requested.
+  * **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.
 
-```rust
-// In src/gl_emulation.rs
-#[wasm_bindgen(js_name = createGLContext)]
-pub fn create_gl_context(width: u32, height: u32) -> GLContextHandle {
-    // Initializes internal state (framebuffer, viewport, etc.)
-    // Returns a handle to the initialized context instance.
-    // ...
-}
+### 2\. **GLSL Translation and Debugging Integration (`glsl-to-wasm`)**
 
-// All 300+ methods (e.g., buffer_data, draw_arrays) are implemented as methods on GLContextHandle
-// and are automatically exposed by wasm-bindgen.
-```
+  * **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.
 
-### B. Internal Implementation: The `glow::Context` Trait
+### 3\. **Debugging and Testing Harness**
 
-| Implementation Area | Detail | Rationale |
-| :--- | :--- | :--- |
-| **API Surface** | Implement the **`glow::Context`** trait on the internal `WasmGLContext` struct. Methods not required for unit testing (e.g., `end_query`, `fence_sync`) are stubbed out to return success/no-op. | Minimizes implementation effort while guaranteeing API correctness. |
-| **Resource Management** | **`WasmGLContext`** contains a **`hashbrown::HashMap<u32, ResourceData>`** registry. All API calls (`createBuffer`, `bindTexture`) reference and mutate resources based on these internal `u32` handles. | Avoids complex host pointers and ensures a deterministic, debuggable state machine. |
-| **Buffer Data Transfer** | The body of `buffer_data()` performs a **transactional copy** of the incoming JavaScript `TypedArray` data directly into the target `Vec<u8>` within the WASM linear memory heap. | Ensures data is persistent and safely managed within the WASM sandbox. |
+  * **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).
 
-### C. The Software Rasterizer Loop (Triggered by `draw_arrays`)
+-----
 
-The core of the emulation resides here:
+## ⚙️ Functional Block 2: Introspection and Codegen Tool (The Ergonomics Layer)
 
-1.  **Shader Integration (Naga):** The `link_program` step uses **`naga`** to translate the GLSL into a Rust function pointer/closure (the **CPU Kernel**).
-2.  **Execution Stages:** The `draw_arrays()` body runs the full pipeline: Input Assembly $\rightarrow$ **Vertex Kernel Execution** (calling the Rust function for each vertex) $\rightarrow$ Rasterization (`glam` math) $\rightarrow$ **Fragment Kernel Execution** (calling the Rust function for each pixel).
-3.  **Output:** Writes the final color values to the **`WasmGLContext.framebuffer`** array.
+This block automates the error-prone, repetitive JavaScript/TypeScript code required for WebGL2 resource setup.
 
-### D. Final Output
+### 1\. **GLSL Introspection Engine (`glsl-parser-rs`)**
 
-The last step exposes the pixel data cleanly for display:
+  * **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).
 
-```rust
-// In src/gl_emulation.rs
-#[wasm_bindgen(js_name = presentFrame)]
-pub fn present_frame(handle: &GLContextHandle) -> js_sys::Uint8Array {
-    // Safely creates a view/copy of the framebuffer Vec<u8> for JavaScript.
-    // ...
-}
-```
+### 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).
 
 -----
 
-## III. Component 2: Transpiler/Codegen Tool (Build-Time) 🛠️
+## ⏳ 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
 
-Component 2 runs once during the build process, taking GLSL source and returning a structured object containing the generated JS code and metadata. It operates as a stateless function.
+- [`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
 
-### A. External Interface: Structured Object Return
+## ⏳ Project Phases
 
-The function accepts the GLSL source and a native JS options object, returning a structured JS object that prevents string-whackery.
+| 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 |
 
-```rust
-// In src/codegen.rs
-#[wasm_bindgen(js_name = generateKernelJS)]
-pub fn generate_kernel_js(
-    glsl_source: &str, 
-    options_js: JsValue // Incoming JS object for configuration
-) -> Result<GeneratedOutput, JsValue> {
-    // ... logic ...
-}
+## 🧪 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
 ```
 
-### B. Internal Implementation: Reflection and Codec
-
-1.  **Options Deserialization:** Use **`serde-wasm-bindgen`** to safely convert the incoming `JsValue` (the options object) into a **`CodegenOptions`** Rust struct for internal type safety.
-2.  **Naga Reflection:** The core logic uses **`naga`** to parse the GLSL and analyze the Intermediate Representation (IR). This analysis extracts:
-      * All **Uniform** names, types, and locations.
-      * All **Attribute** names and types.
-      * All **Texture/Sampler** definitions.
-3.  **JavaScript Generation:** Use the reflection data to programmatically generate the user-facing JavaScript class string, including:
-      * Class definition (`class MyKernel { ... }`).
-      * **Typed Setter Methods** (e.g., `setUniformFloat(name, value)`).
-      * WASM calls to Component 1's low-level `buffer_data`, `uniform_1f`, etc., methods.
-4.  **Structured Output (Codec):** Build the final **`GeneratedOutput`** struct, which uses **`#[wasm_bindgen]`** to ensure clean object transfer:
-      * `kernel_code`: The generated JavaScript class string.
-      * `metadata`: Array of objects detailing the introspected resources.
-      * `diagnostics`: Array of objects containing warnings and errors from `naga` and custom checks.
+## 🤝 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,221 @@
+// @ts-check
+
+import {
+  WasmWebGL2RenderingContext,
+  ERR_OK,
+  ERR_INVALID_HANDLE,
+  readErrorMessage
+} from './src/webgl2_context.js';
+
+/**
+ * WebGL2 Prototype: Rust-owned Context, JS thin-forwarder
+ * Implements docs/1.1.1-webgl2-prototype.md
+ *
+ * This module provides:
+ * - WasmWebGL2RenderingContext: JS class that forwards all calls to WASM
+ * - webGL2(): factory function to create a new context
+ *
+ * WASM owns all runtime state (textures, framebuffers, contexts).
+ * JS is a thin forwarder with no emulation of WebGL behavior.
+ *
+ * Explicit lifecycle: caller must call destroy() to free resources.
+ * All operations return errno (0 = OK). Non-zero errno causes JS to throw
+ * with the message from wasm_last_error_ptr/len.
+ */
+
+
+const isNode =
+  typeof process !== 'undefined' &&
+  process.versions != null &&
+  process.versions.node != null;
+
+/** @typedef {number} u32 */
+
+/**
+ * Factory function: create a new WebGL2 context.
+ *
+ * This function:
+ * 1. Auto-loads webgl2.wasm (expects it next to index2.js)
+ * 2. Instantiates the WASM module with memory
+ * 3. Creates a Rust-owned context via wasm_create_context()
+ * 4. Returns a WasmWebGL2RenderingContext JS wrapper
+ *
+ * @param {Object} opts - options (unused for now)
+ * @returns {Promise<WasmWebGL2RenderingContext>}
+ * @throws {Error} if WASM loading or instantiation fails
+ */
+async function webGL2(opts = {}) {
+  // Load WASM binary
+  const { ex, instance } = await (
+    wasmInitPromise ||
+    (async () => {
+      // ensure success is cached but not failure
+      let succeeded = false;
+      try {
+        const wasm = await initWASM();
+        succeeded = true;
+        return wasm;
+      } finally {
+        if (!succeeded)
+          wasmInitPromise = undefined;
+      }
+    })());
+
+  // Create a context in WASM
+  const ctxHandle = ex.wasm_create_context();
+  if (ctxHandle === 0) {
+    const msg = readErrorMessage(instance);
+    throw new Error(`Failed to create context: ${msg}`);
+  }
+
+  // Wrap and return
+  const gl = new WasmWebGL2RenderingContext(instance, ctxHandle);
+  return gl;
+}
+
+/**
+ * @type {(
+ *  Promise<{ ex: WebAssembly.Exports, instance: WebAssembly.Instance }> |
+ * { ex: WebAssembly.Exports, instance: WebAssembly.Instance } |
+ *  undefined
+ *  )}
+ */
+var wasmInitPromise;
+
+async function initWASM() {
+  let wasmBuffer;
+  if (isNode) {
+    // Use dynamic imports so this module can be loaded in the browser too.
+    const path = await import('path');
+    const fs = await import('fs');
+    const { fileURLToPath } = await import('url');
+    const wasmPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'webgl2.wasm');
+    if (!fs.existsSync(wasmPath)) {
+      throw new Error(`WASM not found at ${wasmPath}. Run: npm run build:wasm`);
+    }
+    // readFileSync is available on the imported namespace
+    wasmBuffer = fs.readFileSync(wasmPath);
+  } else {
+    // Browser: fetch the wasm relative to this module
+    const resp = await fetch(new URL('./webgl2.wasm', import.meta.url));
+    if (!resp.ok) {
+      throw new Error(`Failed to fetch webgl2.wasm: ${resp.status}`);
+    }
+    wasmBuffer = await resp.arrayBuffer();
+  }
+
+  // Compile WASM module
+  const wasmModule = await WebAssembly.compile(wasmBuffer);
+
+  // Create memory (WASM will import it)
+  const memory = new WebAssembly.Memory({ initial: 16, maximum: 256 });
+
+  // Instantiate WASM
+  const importObj = { env: { memory } };
+  const instance = await WebAssembly.instantiate(wasmModule, importObj);
+
+  // Verify required exports
+  const ex = instance.exports;
+  if (typeof ex.wasm_create_context !== 'function') {
+    throw new Error('WASM module missing wasm_create_context export');
+  }
+  return wasmInitPromise = { ex, instance };
+}
+
+/**
+ * Reads an error message from WASM memory and returns it.
+ * @param {WebAssembly.Instance} instance
+ * @returns {string}
+ */
+function _readErrorMessage(instance) {
+  const ex = instance.exports;
+  if (!ex || typeof ex.wasm_last_error_ptr !== 'function' || typeof ex.wasm_last_error_len !== 'function') {
+    return '(no error message available)';
+  }
+  const ptr = ex.wasm_last_error_ptr();
+  const len = ex.wasm_last_error_len();
+  if (ptr === 0 || len === 0) {
+    return '';
+  }
+  const mem = new Uint8Array(ex.memory.buffer);
+  const bytes = mem.subarray(ptr, ptr + len);
+  return new TextDecoder('utf-8').decode(bytes);
+}
+
+/**
+ * Checks a WASM return code (errno).
+ * If non-zero, reads the error message and throws.
+ * @param {number} code
+ * @param {WebAssembly.Instance} instance
+ * @throws {Error} if code !== 0
+ */
+function _checkErr(code, instance) {
+  if (code === ERR_OK) return;
+  const msg = _readErrorMessage(instance);
+  throw new Error(`WASM error ${code}: ${msg}`);
+}
+
+
+// Exports: ESM-style. Also attach globals in browser for convenience.
+export { webGL2, WasmWebGL2RenderingContext, ERR_OK, ERR_INVALID_HANDLE };
+
+if (typeof window !== 'undefined' && window) {
+  // also populate globals when running in a browser environment
+  try {
+    window.webGL2 = webGL2;
+    window.WasmWebGL2RenderingContext = WasmWebGL2RenderingContext;
+  } catch (e) {
+    // ignore if window is not writable
+  }
+}
+
+async function nodeDemo() {
+  console.log('Running index2.js demo...');
+  const gl = await webGL2();
+  console.log(`✓ Context created (handle will be managed by destroy())`);
+
+  // 1x1 texture with CornflowerBlue (100, 149, 237, 255)
+  const tex = gl.createTexture();
+  console.log(`✓ Texture created (handle: ${tex})`);
+
+  gl.bindTexture(0, tex);
+  const pixel = new Uint8Array([100, 149, 237, 255]);
+  gl.texImage2D(0, 0, 0, 1, 1, 0, 0, 0, pixel);
+  console.log(`✓ Texture uploaded`);
+
+  const fb = gl.createFramebuffer();
+  console.log(`✓ Framebuffer created (handle: ${fb})`);
+
+  gl.bindFramebuffer(0, fb);
+  gl.framebufferTexture2D(0, 0, 0, tex, 0);
+  console.log(`✓ Texture attached to framebuffer`);
+
+  const out = new Uint8Array(4);
+  gl.readPixels(0, 0, 1, 1, 0, 0, out);
+  console.log(
+    `✓ Pixel read: r=${out[0]}, g=${out[1]}, b=${out[2]}, a=${out[3]}`
+  );
+
+  if (out[0] === 100 && out[1] === 149 && out[2] === 237 && out[3] === 255) {
+    console.log('✓ Pixel matches expected CornflowerBlue!');
+  } else {
+    console.error('✗ Pixel mismatch!');
+    process.exit(1);
+  }
+
+  gl.destroy();
+  console.log('✓ Context destroyed');
+  console.log('\n✓ Demo passed!');
+  process.exit(0);
+}
+
+// CLI demo: run when executed directly in Node
+if (isNode) {
+  (async () => {
+    const { fileURLToPath } = await import('url');
+    const path = (await import('path'));
+    if (fileURLToPath(import.meta.url) === process.argv[1]) {
+      nodeDemo();
+    }
+  })();
+}

package/package.json

@@ -1,10 +1,20 @@
 {
   "name": "webgl2",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "WebGL2 tools to derisk large GPU projects on the web beyond toys and demos.",
+  "type": "module",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "start": "node ./index.js",
+    "build": "cargo build --target wasm32-unknown-unknown --release && cp target/wasm32-unknown-unknown/release/*.wasm .",
+    "prepublishOnly": "npm run build",
+    "test": "node --test test/*.test.js --parallel=1",
+    "test:smoke": "npm run build:wasm && node ./test/smoke.js"
+  },
+  "wasmBuild": {
+    "outDir": "wasm",
+    "target": "wasm32-unknown-unknown",
+    "profile": "release"
   },
   "repository": {
     "type": "git",
@@ -17,4 +27,11 @@
     "url": "https://github.com/mavity/mavity/issues"
   },
   "homepage": "https://github.com/mavity/mavity#readme"
+  ,
+  "files": [
+    "index.js",
+    "wasm",
+    "README.md",
+    "LICENSE"
+  ]
 }

package/docs/1-webgl-emulator.md

@@ -1,51 +0,0 @@
-# WebGL Emulator (Component 1) Deep Dive
-
-The **WebGL Emulator** is the **pure-Rust software graphics driver** that compiles to a single, single-threaded WASM module. Its primary goal is **correctness, fidelity, and debuggability** by mimicking the entire WebGL2 state machine and rendering pipeline on the CPU.
-
-## 1. ⚙️ Core Architecture and State Management
-
-The emulator's design centers on satisfying the **`glow::Context` trait** while managing all resources within the WASM linear memory.
-
-* **Factory Function:** The entire system is instantiated via the clean factory function: `createGLContext(width, height)`. This function initializes the full internal state and returns a handle.
-* **State Container:** The central struct, e.g., `WasmGLContext`, is the single source of truth for the entire GL state. It manages:
-    * **Resource Registry (`hashbrown::HashMap<u32, ResourceData>`):** Maps the user-facing $\mathbf{u32}$ integer handles (returned by `gl.createBuffer()`, etc.) to the actual Rust structs holding the data and parameters.
-    * **Framebuffer:** A large `Vec<u32>` or `Vec<u8>` in the WASM heap that stores the final pixel output.
-    * **Bound State:** Fields tracking the currently bound program, active VAO, active texture unit, viewport dimensions, etc.
-
-## 2. 🔌 Implementing the $\mathbf{300+}$ API Surface with `glow`
-
-This step minimizes bug surface by reusing the `glow` API definition.
-
-* **Trait Implementation:** The `WasmGLContext` struct implements every method defined in the `glow::Context` trait.
-* **Stubbing:** Approximately $\mathbf{80\%}$ of the methods implement simple state updates or stubs:
-    * **State Setting:** Methods like `enable(DEPTH_TEST)` simply flip a boolean in the `WasmGLContext` struct.
-    * **Resource Binding:** Methods like `bind_buffer(ARRAY_BUFFER, handle)` update the state machine's field to hold the input $\mathbf{u32}$ handle.
-    * **Unsupported Features:** Methods for complex GPU features like `begin_query` or `fence_sync` are implemented as **no-ops** (stubs), returning success without affecting internal state, as they are non-goals for a unit-testing platform.
-* **Data Transfer (`buffer_data`):** The body of this function handles the vital **transactional copy** of `TypedArray` data from JavaScript into the WASM heap buffer referenced by the `u32` handle, ensuring data integrity within the emulation.
-
-## 3. 🧠 The Complex Core: Shader Translation and Execution
-
-The most bespoke and critical logic is transforming the GLSL source into executable Rust code.
-
-### A. Shader Compilation Flow (`compile_shader` / `link_program`)
-
-1.  **Parse & Reflect:** The `shader_source()` and `compile_shader()` methods feed the GLSL code into **`naga`**.
-    * **Naga Output:** `naga` performs parsing, validation, and produces its **Intermediate Representation (IR)**.
-2.  **Code Generation (IR $\rightarrow$ Rust):** A custom routine is required to traverse the Naga IR and output a **Rust source code string** that accurately replicates the shader's logic.
-    * **Vertex Kernel:** Generates a Rust function signature like `fn vs_kernel(uniforms: &Uniforms, vertex_in: &VertexIn) -> VertexOut`, where `VertexIn` and `VertexOut` are structs derived from the shader's attributes and varyings.
-    * **Fragment Kernel:** Generates a Rust function signature like `fn fs_kernel(uniforms: &Uniforms, fragment_in: &FragmentIn) -> Color`, implementing all shading logic.
-3.  **Kernel Storage:** The Rust source code is compiled (or dynamically built/cached), and a **function pointer or closure** to this executable kernel is stored in the internal `ProgramData` resource.
-
-### B. Software Rasterizer Execution (`draw_arrays` and similar)
-
-The `draw_arrays()` call initiates the CPU-bound process:
-
-1.  **Vertex Execution:** The emulation loop iterates through the vertex data. For each vertex, it calls the **Vertex Kernel (Rust function)**, which performs the vertex transformation using **`glam`** math and outputs the clip-space coordinates.
-2.  **Rasterization:** The **`glam`**-powered core logic handles triangle setup, clipping, barycentric interpolation of varyings, and determining which pixels are covered.
-3.  **Fragment Execution:** For every covered pixel, the loop calls the **Fragment Kernel (Rust function)**, passing the interpolated varyings and uniform data. This executes the final shading calculation.
-4.  **Output Merger:** Applies depth, stencil, and blending logic based on the current state before writing the final color result to the **WASM Framebuffer**.
-
-## 4. 🔬 Debugging and Output
-
-* **Debugging Hooks:** The structure of the generated **Rust CPU Kernels** is explicitly designed to be inspected by WASM debugging tools (like browser DevTools). Because the GLSL is translated into traceable Rust code, the developer can pause execution inside the shader logic.
-* **Final Output:** The separate `presentFrame()` function acts as the single bridge to the host, copying the contents of the **WASM Framebuffer** to a JavaScript `Uint8Array` for display via `ctx.putImageData()`.