* fix some bugs, update readme

Author: ziad

README.md

@@ -3,12 +3,14 @@
 [![CI](https://github.com/DevNamedZed/webasmjs/actions/workflows/ci.yml/badge.svg)](https://github.com/DevNamedZed/webasmjs/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-TypeScript library for programmatically generating WebAssembly modules. Build WASM bytecode using a fluent builder API — define functions, memory, tables, globals, imports, and exports, then compile and instantiate at runtime.
+TypeScript library for building and analyzing WebAssembly modules. Generate WASM bytecode with a fluent builder API, or point it at any `.wasm` binary to disassemble, inspect, and decompile it.
 
 [Playground](https://devnamedzed.github.io/webasmjs/) | [API Reference](docs/api.md) | [Getting Started](docs/getting-started.md) | [Examples](docs/examples.md)
 
 ## Features
 
+### Module Builder
+
 - Fluent builder pattern for constructing WASM modules
 - **562 instructions** — arithmetic, control flow, memory, tables, globals, SIMD, atomics, GC, exception handling
 - **Target system** — `mvp`, `2.0`, `3.0`, `latest` with automatic feature gating
@@ -21,9 +23,35 @@ TypeScript library for programmatically generating WebAssembly modules. Build WA
 - Function imports/exports with host interop
 - Memory and table management with import/export
 - WAT text format output and parsing
-- Binary reader for inspecting compiled modules
 - Compile-time verification (control flow + operand stack)
 - Data-driven — opcodes generated from `generator/opcodes.json`
+
+### Binary Analysis
+
+- **Binary reader** — parses all WASM sections: types, imports, functions, tables, memories, globals, exports, elements, data segments, tags, custom sections. Supports GC types (structs, arrays, recursive groups), SIMD, threads, memory64, and reference types.
+- **Disassembler** — generates WAT text format from binary, per-function or full-module
+- **Instruction decoder** — decodes all opcodes including prefixed families (GC, SIMD, bulk memory, threads) with offset and length tracking
+- **DWARF parser** — reads `.debug_info`, `.debug_abbrev`, `.debug_line`, `.debug_str` sections. Extracts function names, parameter/local variable names with WASM local indices, type information (structs, pointers, base types), struct field names, global variable addresses, and source file/line mappings. Supports DWARF 4 and 5.
+- **Source map parser** — V3 format with VLQ decoding, maps WASM byte offsets back to source files, lines, and columns
+- **Name demangling** — C++ (Itanium ABI) and Rust (v0 + legacy) symbol demangling
+
+### Decompiler
+
+Converts WASM functions into structured C-like pseudocode. The pipeline: decode instructions → build a control flow graph → convert to SSA → run optimization passes → compute dominance (Cooper-Harvey-Kennedy) → recover high-level control flow → lower to expression trees → emit output.
+
+- **Control flow recovery** — if/else, while, do-while, for loops, switch/case from `br_table`, early returns, break/continue. Natural loop detection via dominance and post-dominance analysis.
+- **SSA optimization** — constant folding, copy propagation, dead code elimination, double negation elimination, comparison inversion, common subexpression elimination, phi simplification. Iterates until convergence.
+- **Stack frame removal** — detects the `__stack_pointer - N` shadow-stack pattern from LLVM/Emscripten, removes prologue/epilogue, cleans up all `__stack_pointer` references from output.
+- **Memory patterns** — variables with 2+ distinct constant offsets become struct field access (`ptr->field_0`). Expressions like `base + (index << 2)` become array indexing (`base[index]`). With DWARF info, fields get their real names.
+- **Type inference** — maps WASM types to C types, recognizes sub-word loads as casts (`load8_s` → `(byte)`, `load16_u` → `(ushort)`), integrates DWARF type information when present.
+- **Variable naming** — context-aware names from definition site (loads, calls, loop counters) and use site (addresses → `ptr`, comparisons → `cond`). 326 known functions (C stdlib, POSIX, WASI, Emscripten, Rust, Go, AssemblyScript) provide parameter and return value names.
+- **String literals** — resolves constant addresses against data segments and inlines the string content.
+- **Expression formatting** — operator precedence, parenthesization, strength reduction display (`x << 2` → `x * 4`), unsigned comparison casts, ternary operators from `select`.
+
+Tested against real-world binaries — Quake (944 functions), Doom (769 functions), ioquake3, all decompiled successfully.
+
+### General
+
 - Zero production dependencies
 
 ## Install
@@ -165,7 +193,17 @@ See the [API Reference](docs/api.md) for complete documentation.
 
 ## Playground
 
-Try webasmjs in the browser with the [interactive playground](https://devnamedzed.github.io/webasmjs/). It includes 100+ examples covering arithmetic, control flow, memory, tables, imports, floating point, i64/BigInt, SIMD, GC types, algorithms, WAT parsing, and post-MVP features.
+Try webasmjs in the browser with the [interactive playground](https://devnamedzed.github.io/webasmjs/). 100+ builder examples covering arithmetic, control flow, memory, tables, imports, floating point, i64/BigInt, SIMD, GC types, algorithms, WAT parsing, and post-MVP features.
+
+Drop any `.wasm` file into the explorer to inspect it. The explorer provides:
+- Module structure — types, imports, functions, tables, memories, globals, exports, data segments
+- WAT disassembly and decompiled C-like output per function, with syntax highlighting
+- Hex view with instruction-colored bytes
+- Size analysis per section and per function
+- String extraction from data segments
+- Feature detection (which WASM proposals the binary uses)
+- Call graph, cyclomatic complexity, and dead code analysis
+- DWARF and source map integration for symbol recovery
 
 To run the playground locally:
 
@@ -192,15 +230,6 @@ npm run test:coverage
 npm run generate
 ```
 
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/my-feature`)
-3. Make your changes and add tests
-4. Run `npm test` to verify
-5. Commit and push
-6. Open a pull request
-
 ## License
 
 [MIT](LICENSE)

playground/WasmDecompiler.ts

@@ -1,9 +1,10 @@
 import { ModuleInfo } from '../src/BinaryReader';
 import { decompileFunction, createNameResolver } from '../src/decompiler/Decompiler';
 import type { NameResolver, NameResolution } from '../src/decompiler/Decompiler';
+import type { FieldResolver } from '../src/decompiler/LoweredEmitter';
 import type { DwarfDebugInfo, DwarfFunction } from '../src/DwarfParser';
 
-export type { NameResolver, NameResolution };
+export type { NameResolver, NameResolution, FieldResolver };
 export { decompileFunction, createNameResolver };
 
 export function createNameResolverWithDwarf(

playground/explorer.ts

@@ -100,7 +100,7 @@ function buildByteRanges(data: Uint8Array): ByteRangeMap {
 import { parseDwarfDebugInfo, getLineEntriesForAddressRange } from '../src/DwarfParser';
 import type { DwarfDebugInfo, DwarfLineInfo } from '../src/DwarfParser';
 import { decompileFunction, createNameResolver } from './WasmDecompiler';
-import type { NameResolver } from './WasmDecompiler';
+import type { NameResolver, FieldResolver } from './WasmDecompiler';
 import { parseSourceMap, lookupMapping, getSourceLine } from '../src/SourceMapParser';
 import type { ParsedSourceMap, SourceMapping } from '../src/SourceMapParser';
 
@@ -782,6 +782,112 @@ export default class Explorer {
     return this.dwarfFunctionMap;
   }
 
+  private buildFieldResolver(funcGlobalIndex: number): FieldResolver | undefined {
+    const dwarfData = this.getDwarfInfo();
+    if (!dwarfData || dwarfData.types.size === 0) {
+      return undefined;
+    }
+
+    // Find the DWARF function for this global index
+    const dwarfFunc = this.findDwarfFunctionByGlobalIndex(funcGlobalIndex);
+    if (!dwarfFunc) {
+      return undefined;
+    }
+
+    // For each parameter with a pointer-to-struct type, build varName → field map
+    const varFieldMaps = new Map<string, Map<number, string>>();
+
+    for (const param of dwarfFunc.parameters) {
+      if (!param.name || param.typeOffset === null) {
+        continue;
+      }
+
+      const structFields = this.resolvePointerToStructFields(param.typeOffset, dwarfData.types);
+      if (structFields && structFields.size > 0) {
+        const paramName = param.name.replace(/[^a-zA-Z0-9_$]/g, '_');
+        varFieldMaps.set(paramName, structFields);
+      }
+    }
+
+    // Also check local variables
+    for (const variable of dwarfFunc.variables) {
+      if (!variable.name || variable.typeOffset === null) {
+        continue;
+      }
+
+      const structFields = this.resolvePointerToStructFields(variable.typeOffset, dwarfData.types);
+      if (structFields && structFields.size > 0) {
+        const varName = variable.name.replace(/[^a-zA-Z0-9_$]/g, '_');
+        if (!varFieldMaps.has(varName)) {
+          varFieldMaps.set(varName, structFields);
+        }
+      }
+    }
+
+    if (varFieldMaps.size === 0) {
+      return undefined;
+    }
+
+    return {
+      resolveField(baseName: string, offset: number): string | null {
+        const fieldMap = varFieldMaps.get(baseName);
+        if (fieldMap) {
+          return fieldMap.get(offset) || null;
+        }
+        return null;
+      },
+    };
+  }
+
+  private resolvePointerToStructFields(typeOffset: number, types: Map<number, import('../src/DwarfParser').DwarfTypeInfo>): Map<number, string> | null {
+    const typeInfo = types.get(typeOffset);
+    if (!typeInfo) {
+      return null;
+    }
+
+    // Follow pointer → struct
+    if (typeInfo.tag === 'pointer' && typeInfo.referencedType !== null) {
+      return this.resolvePointerToStructFields(typeInfo.referencedType, types);
+    }
+
+    // Follow typedef → target
+    if (typeInfo.tag === 'typedef' && typeInfo.referencedType !== null) {
+      return this.resolvePointerToStructFields(typeInfo.referencedType, types);
+    }
+
+    // Follow const → target
+    if (typeInfo.tag === 'const' && typeInfo.referencedType !== null) {
+      return this.resolvePointerToStructFields(typeInfo.referencedType, types);
+    }
+
+    // Struct with fields
+    if (typeInfo.tag === 'struct' && typeInfo.fields && typeInfo.fields.length > 0) {
+      const fieldMap = new Map<number, string>();
+      for (const field of typeInfo.fields) {
+        fieldMap.set(field.byteOffset, field.name);
+      }
+      return fieldMap;
+    }
+
+    return null;
+  }
+
+  private findDwarfFunctionByGlobalIndex(globalIndex: number): import('../src/DwarfParser').DwarfFunction | null {
+    const dwarfFuncMap = this.getDwarfFunctionMap();
+    if (!dwarfFuncMap) {
+      return null;
+    }
+    const funcName = dwarfFuncMap.get(globalIndex);
+    if (!funcName) {
+      return null;
+    }
+    const dwarfData = this.getDwarfInfo();
+    if (!dwarfData) {
+      return null;
+    }
+    return dwarfData.functions.find(func => func.name === funcName) || null;
+  }
+
   private buildDwarfParameterTypeMap(): Map<number, Map<number, string>> | null {
     const dwarfData = this.getDwarfInfo();
     if (!dwarfData || dwarfData.functions.length === 0 || !this.moduleInfo) {
@@ -1171,6 +1277,18 @@ export default class Explorer {
           return funcParams?.get(paramIndex) || null;
         } : undefined,
       );
+
+      // Add global variable address resolution from DWARF
+      const dwarfGlobalVars = this.dwarfInfo?.globalVariables;
+      if (dwarfGlobalVars && dwarfGlobalVars.length > 0) {
+        const globalAddrMap = new Map<number, string>();
+        for (const globalVar of dwarfGlobalVars) {
+          globalAddrMap.set(globalVar.address, globalVar.name);
+        }
+        this.nameResolver.resolveGlobalAddress = (address: number): string | null => {
+          return globalAddrMap.get(address) || null;
+        };
+      }
       this.parsedSourceMap = null;
       this.detectSourceMappingUrl();
       this.renderExplorer();
@@ -2561,7 +2679,8 @@ export default class Explorer {
 
       if (activeTab === 'decompiled') {
         if (this.nameResolver && this.moduleInfo) {
-          const decompiledCode = decompileFunction(this.moduleInfo, funcIndex, this.nameResolver);
+          const globalFuncIdx = this.getImportedCount(0) + funcIndex;
+          const decompiledCode = decompileFunction(this.moduleInfo, funcIndex, this.nameResolver, this.buildFieldResolver(globalFuncIdx));
 
           // Build function name → local index map for clickable calls
           const funcNameMap = new Map<string, number>();