@gasm-compiler/core 0.1.0 → 0.1.1

package/README.md

@@ -1,481 +1,49 @@
-# Gasm Compiler Core Compiler
+# @gasm-compiler/core
 
 **Compile WebAssembly to WGSL for GPU Execution**
 
-This package implements the core compiler that transforms WebAssembly binaries into WGSL (WebGPU Shading Language) code for execution on GPUs. It implements the [Gasm v0.1 specification](../../spec/gasm-v0.1.md), a GPU-executable subset of WebAssembly.
+Transform WebAssembly binaries into WGSL (WebGPU Shading Language) compute shaders. Write your GPU kernels in any language that compiles to WebAssembly (C, C++, Rust, Go, AssemblyScript, or hand-written WAT), then run them on the GPU via WebGPU.
 
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Architecture](#architecture)
-- [Compilation Pipeline](#compilation-pipeline)
-- [IR Types](#ir-types)
-- [Instruction Mapping](#instruction-mapping)
-- [Gasm Conformance](#gasm-conformance)
-- [Usage](#usage)
-- [Testing](#testing)
-- [API Reference](#api-reference)
-
----
-
-## Overview
-
-**Gasm Compiler Core** is a TypeScript/Deno compiler that:
-
-1. **Parses** WebAssembly binaries (Wasm Core 1.0)
-2. **Validates** GPU execution constraints (Gasm spec)
-3. **Transforms** stack-based Wasm to structured WGSL
-4. **Generates** WGSL compute shaders ready for WebGPU
-
-### Key Features
-
-- ✅ Full L0 conformance (scalar operations)
-- ✅ 120+ WebAssembly instructions supported
-- ✅ Control flow restructuring (Relooper algorithm)
-- ✅ Memory operation lowering (sub-word access)
-- ✅ Global imports and Gasm built-ins
-- ✅ Type-safe SSA intermediate representation
-- 🚧 L1/L2 conformance (SIMD, atomics) — planned
-
----
-
-## Architecture
-
-The compiler uses a **5-phase pipeline** to transform WebAssembly into WGSL:
-
-```
-┌─────────────┐
-│  Wasm Binary │  Input: .wasm file (Uint8Array)
-└──────┬──────┘
-       │
-       v
-┌─────────────┐
-│  Phase 1:   │  Parse & Validate
-│  Parser     │  • Binary format parsing
-│             │  • Gasm restriction validation (Section 10)
-└──────┬──────┘  • Output: WasmModule (stack-based IR)
-       │
-       v
-┌─────────────┐
-│  Phase 2:   │  Stack → SSA Conversion
-│  SSA IR     │  • Convert stack operations to SSA form
-│             │  • Type inference for locals
-└──────┬──────┘  • Output: SSAModule (SSA IR)
-       │
-       v
-┌─────────────┐
-│  Phase 3:   │  Control Flow Restructuring
-│  Relooper   │  • Transform unstructured jumps (br, br_if, br_table)
-│             │  • Generate structured blocks/loops
-└──────┬──────┘  • Output: StructuredModule
-       │
-       v
-┌─────────────┐
-│  Phase 4:   │  Memory Lowering
-│  MemLower   │  • Lower i8/i16 loads/stores to i32 word access
-│             │  • Generate bit-masking and shifting
-└──────┬──────┘  • Output: StructuredModule (memory-lowered)
-       │
-       v
-┌─────────────┐
-│  Phase 5:   │  WGSL Code Generation
-│  Codegen    │  • Emit WGSL functions, variables, structs
-│             │  • Map Wasm instructions to WGSL expressions
-└──────┬──────┘  • Output: WGSL string
-       │
-       v
-┌─────────────┐
-│  WGSL Code  │  Output: Valid WebGPU shader
-└─────────────┘
-```
-
----
-
-## Compilation Pipeline
-
-### Phase 1: Parse & Validate
-
-**File:** `src/parser.ts`  
-**Input:** WebAssembly binary (`Uint8Array`)  
-**Output:** `WasmModule` (stack-based IR)
-
-**Responsibilities:**
-- Parse Wasm binary format (magic, version, sections)
-- Extract types, imports, functions, tables, memories, globals, exports, code
-- Validate Gasm restrictions:
-  - Max 1 memory (no multi-memory)
-  - Max 1 table (no multi-table)
-  - No imports except globals (built-ins)
-  - Memory must be exported as `"memory"`
-- Decode instruction bytecode to IR
-
-**Key Functions:**
-```typescript
-export function parseWasm(binary: Uint8Array): WasmModule
-```
-
-**Error Handling:**
-Throws `CompileError` with descriptive message for invalid binaries or Gasm violations.
-
----
-
-### Phase 2: Stack → SSA Conversion
-
-**File:** `src/phases.ts` → `phaseStackToSSA()`  
-**Input:** `WasmModule`  
-**Output:** `SSAModule`
-
-**Responsibilities:**
-- Convert stack-based operations to Static Single Assignment (SSA) form
-- Infer types for local variables (from usage patterns)
-- Preserve global definitions and imports
-- Generate unique SSA variable names (`%0`, `%1`, `%2`, ...)
-
-**Example:**
-```wasm
-;; WebAssembly (stack-based)
-local.get 0
-i32.const 1
-i32.add
-local.set 0
-```
-
-↓
-
-```
-// SSA IR
-%0 = local.get 0: i32
-%1 = i32.const 1
-%2 = i32.add %0, %1
-local.set 0, %2
-```
-
-**Key Functions:**
-```typescript
-export function phaseStackToSSA(module: WasmModule): SSAModule
-```
-
----
-
-### Phase 3: Control Flow Restructuring
-
-**File:** `src/relooper.ts`  
-**Input:** `SSAModule`  
-**Output:** `StructuredModule`
-
-**Responsibilities:**
-- Apply the **Relooper algorithm** to restructure control flow
-- Transform unstructured jumps (`br`, `br_if`, `br_table`) into structured loops/blocks
-- Generate WGSL-compatible control structures (`if`, `loop`, `break`, `continue`)
-
-**Example:**
-```wasm
-;; WebAssembly (unstructured)
-block $exit
-  loop $loop
-    local.get 0
-    i32.const 10
-    i32.lt_s
-    br_if $exit
-    ;; loop body
-    br $loop
-  end
-end
-```
-
-↓
-
-```wgsl
-// WGSL (structured)
-loop {
-  if (var_0 < 10i) { break; }
-  // loop body
-}
-```
-
-**Key Functions:**
-```typescript
-export function reloop(module: SSAModule): StructuredModule
-```
-
----
-
-### Phase 4: Memory Lowering
-
-**File:** `src/phases.ts` → `phaseMemoryLowering()`  
-**Input:** `StructuredModule`  
-**Output:** `StructuredModule` (memory-lowered)
-
-**Responsibilities:**
-- Lower sub-word memory operations (i8/i16) to word-aligned access (i32)
-- Generate bit-masking and shifting for unaligned access
-- Preserve i32/i64/f32/f64 memory operations
-
-**Example:**
-```wasm
-;; i32.load8_u offset=0 align=1
-i32.load8_u offset=0 align=1
-```
-
-↓
-
-```wgsl
-// WGSL (lowered to word access)
-let word_addr = offset / 4u;
-let byte_offset = offset % 4u;
-let word = memory[word_addr];
-let byte = (word >> (byte_offset * 8u)) & 0xFFu;
-```
-
-**Key Functions:**
-```typescript
-export function phaseMemoryLowering(module: StructuredModule): StructuredModule
-```
-
----
-
-### Phase 5: WGSL Code Generation
-
-**File:** `src/phases.ts` → `phaseWgslCodegen()`  
-**Input:** `StructuredModule`  
-**Output:** WGSL string
-
-**Responsibilities:**
-- Emit WGSL variable declarations (globals, locals)
-- Emit function definitions with signatures
-- Emit main entry point with Gasm built-in parameters:
-  - `@builtin(global_invocation_id)` → `global_invocation_id_{x,y,z}`
-  - `@builtin(local_invocation_id)` → `local_invocation_id_{x,y,z}`
-  - `@builtin(workgroup_id)` → `workgroup_id_{x,y,z}`
-  - `@builtin(num_workgroups)` → `num_workgroups_{x,y,z}`
-- Map Wasm instructions to WGSL expressions
-- Generate structured control flow (blocks, loops, conditionals)
-
-**Example:**
-```wasm
-(func $add (param i32 i32) (result i32)
-  local.get 0
-  local.get 1
-  i32.add)
-```
-
-↓
-
-```wgsl
-fn func_0(param_0: i32, param_1: i32) -> i32 {
-  return param_0 + param_1;
-}
-```
-
-**Key Functions:**
-```typescript
-export function phaseWgslCodegen(
-  module: StructuredModule,
-  options?: CompileOptions
-): string
-```
+Implements the [Gasm v0.1 specification](https://github.com/gasm-compiler/spec) — a GPU-executable subset of WebAssembly.
 
 ---
 
-## IR Types
-
-The compiler uses three IR representations:
+## Installation
 
-### 1. WasmModule (Stack-Based IR)
-
-**File:** `src/types.ts`  
-**Purpose:** Direct representation of WebAssembly binary
-
-```typescript
-export interface WasmModule {
-  types: WasmType[];
-  imports: Import[];
-  functions: WasmFunction[];
-  tables: Table[];
-  memories: Memory[];
-  globals: Global[];  // ImportedGlobal | DefinedGlobal
-  exports: Export[];
-  start?: number;
-  elements: Element[];
-  dataSegments: DataSegment[];
-  customSections: CustomSection[];
-}
+```bash
+npm install @gasm-compiler/core
 ```
 
-**Key Properties:**
-- `types`: Function signatures (param/result types)
-- `functions`: Function bodies with stack-based instructions
-- `globals`: Global variables (imported built-ins or definitions)
-- `memories`: Linear memory configuration (initial/max pages)
-- `exports`: Exported functions and memory
+**Requirements:** TypeScript 5.0+ (peer dependency)
 
 ---
 
-### 2. SSAModule (SSA IR)
-
-**File:** `src/types.ts`  
-**Purpose:** Static Single Assignment form for analysis
+## Quick Start
 
 ```typescript
-export interface SSAModule {
-  types: WasmType[];
-  imports: Import[];
-  functions: SSAFunction[];
-  tables: Table[];
-  memories: Memory[];
-  globals: Global[];
-  exports: Export[];
-  start?: number;
-  elements: Element[];
-  dataSegments: DataSegment[];
-  customSections: CustomSection[];
-}
-
-export interface SSAFunction {
-  typeIndex: number;
-  locals: Local[];
-  body: SSAInstruction[];
-}
-
-export interface SSAInstruction {
-  opcode: number;
-  name: string;
-  type?: string;
-  operands?: string[];
-  result?: string;
-  immediates?: unknown[];
-}
-```
-
-**Key Properties:**
-- `SSAFunction.body`: Instructions with explicit SSA operands/results
-- `SSAInstruction.result`: SSA variable name (e.g., `%0`, `%1`)
-- `SSAInstruction.operands`: SSA variable dependencies (e.g., `["%0", "%1"]`)
-
----
-
-### 3. StructuredModule (Structured IR)
-
-**File:** `src/types.ts`  
-**Purpose:** Structured control flow for WGSL generation
+import { compile } from "@gasm-compiler/core";
 
-```typescript
-export interface StructuredModule {
-  types: WasmType[];
-  imports: Import[];
-  functions: StructuredFunction[];
-  tables: Table[];
-  memories: Memory[];
-  globals: Global[];
-  exports: Export[];
-  start?: number;
-  elements: Element[];
-  dataSegments: DataSegment[];
-  customSections: CustomSection[];
-}
+// Load a WebAssembly binary (.wasm file)
+const wasmBytes = new Uint8Array(await fetch("shader.wasm").then(r => r.arrayBuffer()));
 
-export interface StructuredFunction {
-  typeIndex: number;
-  locals: Local[];
-  body: StructuredInstruction[];
-}
+// Compile to WGSL
+const wgslCode = compile(wasmBytes);
 
-export interface StructuredInstruction {
-  opcode: number;
-  name: string;
-  type?: string;
-  operands?: string[];
-  result?: string;
-  immediates?: unknown[];
-}
+// Use with WebGPU
+const shaderModule = device.createShaderModule({ code: wgslCode });
 ```
 
-**Key Properties:**
-- Control flow is fully structured (no `br`, `br_if`, `br_table`)
-- Instructions use WGSL-compatible constructs (`if`, `loop`, `break`)
-- Memory operations are word-aligned (i32/i64/f32/f64 only)
-
----
-
-## Instruction Mapping
-
-The compiler maps 120+ WebAssembly instructions to WGSL equivalents. See the full table in the [Instruction Set Reference](../../docs/instruction-set.md).
-
-### Quick Reference
-
-| Category | Example Instructions | WGSL Equivalent |
-|----------|---------------------|-----------------|
-| **Arithmetic** | `i32.add`, `f32.mul` | `a + b`, `a * b` |
-| **Bitwise** | `i32.and`, `i32.shl` | `a & b`, `a << (b & 31u)` |
-| **Comparisons** | `i32.lt_s`, `f32.eq` | `a < b`, `a == b` |
-| **Memory** | `i32.load`, `i32.store8` | `memory[addr/4u]`, bit-masking |
-| **Conversions** | `i32.trunc_f32_s`, `f32.convert_i32_u` | `i32(trunc(a))`, `f32(u32(a))` |
-| **Control Flow** | `block`, `loop`, `br_if` | `{ ... }`, `loop { ... }`, `if (c) { break; }` |
-| **Variables** | `local.get`, `global.set` | `var_N`, `global_N = val` |
-| **Special** | `select`, `memory.size` | `select(a, b, c)`, `arrayLength(&memory)` |
-
 ---
 
-## Gasm Conformance
+## Features
 
-The compiler implements **Gasm v0.1 L0 (Core)** conformance:
-
-### Conformance Levels
-
-| Level | Features | Status |
-|-------|----------|--------|
-| **L0 (Core)** | Scalar operations (i32, i64, f32, f64) | ✅ Implemented |
-| **L1 (SIMD)** | 128-bit SIMD operations (v128) | 🚧 Planned |
-| **L2 (Extended)** | Atomics + Relaxed SIMD | 🚧 Planned |
-
-### Gasm Restrictions (Section 10)
-
-The compiler enforces these restrictions during Phase 1 validation:
-
-1. **Single Memory**: Max 1 memory, must be exported as `"memory"`
-2. **Single Table**: Max 1 table (for indirect calls)
-3. **No Imports** (except globals): Only global imports allowed (Gasm built-ins)
-4. **Deterministic Execution**: No `unreachable` or trapping operations in production code
-5. **Structured Control Flow**: All `br`, `br_if`, `br_table` must be restructurable (Phase 3)
-
-### Gasm Built-in Globals
-
-The compiler automatically maps WGSL built-ins to global imports:
-
-| Global Name | WGSL Built-in | Type |
-|-------------|---------------|------|
-| `global_invocation_id_x` | `@builtin(global_invocation_id).x` | `u32` |
-| `global_invocation_id_y` | `@builtin(global_invocation_id).y` | `u32` |
-| `global_invocation_id_z` | `@builtin(global_invocation_id).z` | `u32` |
-| `local_invocation_id_x` | `@builtin(local_invocation_id).x` | `u32` |
-| `local_invocation_id_y` | `@builtin(local_invocation_id).y` | `u32` |
-| `local_invocation_id_z` | `@builtin(local_invocation_id).z` | `u32` |
-| `workgroup_id_x` | `@builtin(workgroup_id).x` | `u32` |
-| `workgroup_id_y` | `@builtin(workgroup_id).y` | `u32` |
-| `workgroup_id_z` | `@builtin(workgroup_id).z` | `u32` |
-| `num_workgroups_x` | `@builtin(num_workgroups).x` | `u32` |
-| `num_workgroups_y` | `@builtin(num_workgroups).y` | `u32` |
-| `num_workgroups_z` | `@builtin(num_workgroups).z` | `u32` |
-
-**Example:**
-```wasm
-(import "gasm" "global_invocation_id_x" (global $gid_x i32))
-```
-
-↓
-
-```wgsl
-@compute @workgroup_size(64)
-fn main(
-  @builtin(global_invocation_id) global_invocation_id: vec3<u32>,
-  // ... other built-ins
-) {
-  var global_invocation_id_x: u32 = global_invocation_id.x;
-  // ... use in function body
-}
-```
+- 120+ WebAssembly instructions mapped to WGSL equivalents
+- Full L0 conformance (i32, i64, f32, f64 scalar operations)
+- Control flow restructuring — WebAssembly's unstructured branches become WGSL loops/blocks
+- Sub-word memory access — i8/i16 loads/stores lowered to word-aligned operations
+- Gasm built-in globals for GPU thread identification
+- Optional math extension for direct WGSL built-in math calls
+- Works in Node.js, Deno, and browsers
 
 ---
 
@@ -486,51 +54,42 @@ fn main(
 ```typescript
 import { compile } from "@gasm-compiler/core";
 
-// Load WebAssembly binary
-const wasmBytes = await Deno.readFile("shader.wasm");
-
-// Compile to WGSL
 const wgslCode = compile(wasmBytes);
-
-// Use with WebGPU
-const shaderModule = device.createShaderModule({ code: wgslCode });
 ```
 
-### With Options
+### Compilation Options
 
 ```typescript
-import { compile, CompileOptions } from "@gasm-compiler/core";
+import { compile } from "@gasm-compiler/core";
 
-const options: CompileOptions = {
+const wgslCode = compile(wasmBytes, {
   workgroupSize: [128, 1, 1],  // Default: [64, 1, 1]
-  debug: true,                  // Emit debug comments
+  debug: true,                  // Emit source-mapping comments
   mathExtension: true,          // Enable gasm:math built-ins
-};
-
-const wgslCode = compile(wasmBytes, options);
+});
 ```
 
-### Math Extension (gasm:math)
+### Math Extension
 
-The `mathExtension` option enables WGSL built-in math functions to be called directly from WebAssembly via imports from the `"gasm"` module:
+Enable direct mapping of WebAssembly imports to WGSL built-in math functions:
 
 ```typescript
-import { compile } from "@gasm-compiler/core";
-
 const wgslCode = compile(wasmBytes, {
-  mathExtension: true,   // Enable all levels (M0, M1, M2)
-  // or: mathExtension: "M0"  // Core scalar functions only
-  // or: mathExtension: "M1"  // Core + vector functions
-  // or: mathExtension: "M2"  // All functions
+  mathExtension: true,    // Enable all levels (M0, M1, M2)
+  // or: mathExtension: "M0"   // Core scalar functions only
+  // or: mathExtension: "M1"   // Core + vector functions
+  // or: mathExtension: "M2"   // All functions
 });
 ```
 
-When enabled, imports like `(import "gasm" "sin" (func ...))` are compiled to direct WGSL built-in calls like `sin(...)` instead of function calls.
+When enabled, WebAssembly imports like `(import "gasm" "sin" (func ...))` compile to direct WGSL built-in calls (`sin(...)`) with zero overhead.
 
 **Math Levels:**
-- **M0 (Core)**: Scalar functions (sin, cos, sqrt, abs, min, max, clamp, etc.)
-- **M1 (Vector)**: Geometric functions (length, dot, cross, normalize, reflect, etc.)
-- **M2 (Advanced)**: modf, frexp, ldexp, degrees, radians, bit manipulation
+- **M0 (Core):** sin, cos, sqrt, abs, min, max, clamp, floor, ceil, etc.
+- **M1 (Vector):** length, dot, cross, normalize, reflect, refract, etc.
+- **M2 (Advanced):** modf, frexp, ldexp, degrees, radians, bit manipulation
+
+> See also: [`@gasm-compiler/math-reference`](https://www.npmjs.com/package/@gasm-compiler/math-reference) for CPU-side reference implementations of these math functions.
 
 ### Error Handling
 
@@ -539,7 +98,6 @@ import { compile, isCompileError } from "@gasm-compiler/core";
 
 try {
   const wgslCode = compile(wasmBytes);
-  console.log("Compilation successful!");
 } catch (error) {
   if (isCompileError(error)) {
     console.error("Compile Error:", error.message);
@@ -547,123 +105,144 @@ try {
       console.error(`  at line ${error.location.line}, column ${error.location.column}`);
     }
   } else {
-    throw error;  // Unexpected error
+    throw error;
   }
 }
 ```
 
----
+### Browser Usage
+
+```typescript
+import { compile } from "@gasm-compiler/core/browser";
+
+const wgslCode = compile(wasmBytes);
+```
+
+### Using with WebGPU
 
-## Testing
+```typescript
+import { compile } from "@gasm-compiler/core";
 
-### Running Tests
+// 1. Compile Wasm → WGSL
+const wgslCode = compile(wasmBytes, { workgroupSize: [256, 1, 1] });
 
-```bash
-# Run all tests
-pnpm test:core
+// 2. Create shader module
+const shaderModule = device.createShaderModule({ code: wgslCode });
 
-# Or directly with Deno
-cd packages/core
-deno test --allow-all
+// 3. Create compute pipeline
+const pipeline = device.createComputePipeline({
+  layout: "auto",
+  compute: { module: shaderModule, entryPoint: "main" },
+});
 
-# Run specific test file
-deno test tests/compiler_test.ts --allow-all
+// 4. Dispatch
+const commandEncoder = device.createCommandEncoder();
+const pass = commandEncoder.beginComputePass();
+pass.setPipeline(pipeline);
+pass.setBindGroup(0, bindGroup);
+pass.dispatchWorkgroups(numWorkgroups);
+pass.end();
+device.queue.submit([commandEncoder.finish()]);
 ```
 
-### Test Organization
+---
+
+## How It Works
 
-Tests are organized by phase:
+The compiler transforms WebAssembly into WGSL through a multi-phase pipeline:
 
 ```
-packages/core/tests/
-├── compiler_test.ts      # Integration tests (full pipeline)
-└── fixtures/             # Test data files (future)
+WebAssembly Binary (.wasm)
+        ↓
+   Parse & Validate (Gasm restrictions)
+        ↓
+   Convert to SSA form
+        ↓
+   Restructure control flow (Relooper)
+        ↓
+   Lower memory operations
+        ↓
+   WGSL Code Generation
+        ↓
+WGSL Compute Shader (.wgsl)
 ```
 
-**Current Test Coverage (Session 3):**
-- ✅ **Phase 1: Parser validation** (26 tests)
-- ✅ **Phase 2-5: Integration tests** (12 tests)
-- ✅ **i32 Arithmetic** (18 tests)
-- ✅ **i32 Bitwise** (32 tests)
-- ✅ **i32 Comparison** (20 tests)
-- ✅ **i64 Arithmetic** (19 tests)
-- ✅ **i64 Bitwise** (32 tests)
-- ✅ **i64 Comparison** (20 tests)
-- ✅ **f32 Arithmetic** (48 tests)
-- ✅ **f64 Arithmetic** (48 tests)
-- ✅ **Float Comparison** (17 tests)
-- ✅ **Float Edge Cases** (18 tests)
-- ✅ **Type Conversions** (53 tests: 16 original + 37 new comprehensive tests)
-- ✅ **Control Flow** (9 tests)
-- ✅ **Memory Operations** (14 tests)
-- ✅ **Functions, Stack, Constants** (19 tests)
-- ✅ **Error Handling** (19 tests)
-- ✅ **WGSL Output Validation** (40 tests)
-- ✅ **Global & Options** (2 tests)
-
-**Total:** 471 tests passing (414ms execution time)
-**Test Files:** 23 organized by instruction category
-
-### Adding New Tests
+### Gasm Restrictions
 
-```typescript
-import { assertEquals } from "jsr:@std/assert";
-import { compile } from "../src/mod.ts";
-
-Deno.test("Compiler - Feature Name", () => {
-  // Create WebAssembly binary (WAT → Wasm)
-  const wat = `
-    (module
-      (func (export "add") (param i32 i32) (result i32)
-        local.get 0
-        local.get 1
-        i32.add))
-  `;
-  const wasmBytes = wat2wasm(wat);  // Use wat2wasm utility
-
-  // Compile to WGSL
-  const wgslCode = compile(wasmBytes);
+Your WebAssembly module must conform to the Gasm subset:
 
-  // Verify output
-  assertEquals(wgslCode.includes("param_0 + param_1"), true);
-});
+- **Single memory** — max 1 linear memory, exported as `"memory"`
+- **Single table** — max 1 table (for indirect calls)
+- **Global imports only** — no function or memory imports (except Gasm built-in globals)
+- **Structured control flow** — all branches must be restructurable
+
+### Gasm Built-in Globals
+
+Import GPU thread identifiers as WebAssembly globals from the `"gasm"` module:
+
+| Import Name | Maps to WGSL | Type |
+|-------------|--------------|------|
+| `global_invocation_id_x/y/z` | `@builtin(global_invocation_id)` | `u32` |
+| `local_invocation_id_x/y/z` | `@builtin(local_invocation_id)` | `u32` |
+| `workgroup_id_x/y/z` | `@builtin(workgroup_id)` | `u32` |
+| `num_workgroups_x/y/z` | `@builtin(num_workgroups)` | `u32` |
+
+**Example (WAT):**
+```wasm
+(module
+  (import "gasm" "global_invocation_id_x" (global $gid_x i32))
+  (memory (export "memory") 1)
+  (func (export "main")
+    ;; Use $gid_x to index into memory per-thread
+  ))
 ```
 
+### Instruction Support
+
+| Category | Examples | WGSL Output |
+|----------|---------|-------------|
+| Arithmetic | `i32.add`, `f32.mul` | `a + b`, `a * b` |
+| Bitwise | `i32.and`, `i32.shl` | `a & b`, `a << (b & 31u)` |
+| Comparisons | `i32.lt_s`, `f32.eq` | `a < b`, `a == b` |
+| Memory | `i32.load`, `i32.store8` | `memory[addr/4u]`, bit-masking |
+| Conversions | `i32.trunc_f32_s` | `i32(trunc(a))` |
+| Control Flow | `block`, `loop`, `br_if` | `loop { ... }`, `if (c) { break; }` |
+| Variables | `local.get`, `global.set` | `var_N`, `global_N = val` |
+
 ---
 
 ## API Reference
 
-### Main API
+### `compile(source, options?)`
 
-#### `compile(source: Uint8Array, options?: CompileOptions): string`
+```typescript
+function compile(source: Uint8Array, options?: CompileOptions): string
+```
 
 Compiles a WebAssembly binary to WGSL.
 
 **Parameters:**
-- `source`: WebAssembly binary (Uint8Array)
-- `options`: Optional compilation options
-
-**Returns:** WGSL shader code (string)
+- `source` — WebAssembly binary as `Uint8Array`
+- `options` — Optional `CompileOptions`
 
-**Throws:** `CompileError` if validation or transformation fails
+**Returns:** WGSL shader code as a string
 
----
-
-### Types
+**Throws:** `CompileError` on validation or compilation failure
 
-#### `CompileOptions`
+### `CompileOptions`
 
 ```typescript
-export interface CompileOptions {
+interface CompileOptions {
   workgroupSize?: [number, number, number];  // Default: [64, 1, 1]
   debug?: boolean;                           // Emit debug comments (default: false)
+  mathExtension?: boolean | "M0" | "M1" | "M2";  // Enable math built-ins
 }
 ```
 
-#### `CompileError`
+### `CompileError`
 
 ```typescript
-export interface CompileError {
+interface CompileError {
   type: "CompileError";
   message: string;
   location?: { line: number; column: number };
@@ -671,50 +250,23 @@ export interface CompileError {
 }
 ```
 
-#### `isCompileError(error: unknown): error is CompileError`
-
-Type guard to check if an error is a `CompileError`.
-
----
-
-### Internal APIs
+### `isCompileError(error)`
 
-These are exported for testing but not intended for public use:
+```typescript
+function isCompileError(error: unknown): error is CompileError
+```
 
-- `parseWasm(binary: Uint8Array): WasmModule` — Parse Wasm binary
-- `phaseStackToSSA(module: WasmModule): SSAModule` — Convert to SSA
-- `reloop(module: SSAModule): StructuredModule` — Restructure control flow
-- `phaseMemoryLowering(module: StructuredModule): StructuredModule` — Lower memory ops
-- `phaseWgslCodegen(module: StructuredModule, options?: CompileOptions): string` — Generate WGSL
+Type guard for `CompileError`.
 
 ---
 
-## Contributing
-
-See [AGENTS.md](../../AGENTS.md) for guidelines on working with the core compiler.
+## Related Packages
 
-### Development Workflow
-
-1. **Write tests first** for new features
-2. **Run tests** with `pnpm test:core`
-3. **Keep platform-agnostic** — no Deno-specific APIs in core logic
-4. **Follow TypeScript strict mode** — all types must be explicit
-5. **Document public APIs** — JSDoc for all exported functions
+- [`@gasm-compiler/cli`](https://www.npmjs.com/package/@gasm-compiler/cli) — Command-line compiler for Wasm/AssemblyScript → WGSL
+- [`@gasm-compiler/math-reference`](https://www.npmjs.com/package/@gasm-compiler/math-reference) — CPU-side reference implementations of Gasm math functions
 
 ---
 
 ## License
 
-MIT License — See [LICENSE](../../LICENSE) for details.
-
----
-
-## Related Documentation
-
-- [Gasm Specification v0.1](../../spec/gasm-v0.1.md) — GPU-executable WebAssembly spec
-- [Instruction Set Reference](../../docs/instruction-set.md) — Detailed instruction mappings
-- [AGENTS.md](../../AGENTS.md) — Development guidelines for agents
-
----
-
-**Last Updated:** December 2025
+See [LICENSE](./LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gasm-compiler/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Gasm Compiler — compile WebAssembly to WGSL (WebGPU Shading Language)",
   "type": "module",
   "main": "./dist/mod.js",
@@ -36,6 +36,7 @@
   },
   "files": [
     "dist",
+    "!dist/**/*.map",
     "LICENSE",
     "README.md"
   ],