- GC proposal: struct/array types, recursive type groups, subtyping, GC opcodes

- Exception handling: tags (import, export, define)
- GC opcodes accept builder objects directly instead of requiring .index
- Disassembler: converts parsed WASM binary back to WAT
- Instruction decoder: decodes raw instruction bytes into structured objects
- BinaryReader now handles GC types, tags, data count section, passive segments
- WatParser parses rec groups with forward references and sub/sub_final subtyping
- WatParser supports named type references in functions
- Verifier handles GC opcodes and ref subtype assignments
- Replace any with proper types in opcode signatures
- Rename defineFuncType→defineFunctionType, defineTableSegment→defineElementSegment
- Added mut to playground exports so structDSL example works in browser
- Removed disableVerification from structDSL playground example
- Removed stale examples/ directory
- Cleaned up index exports
- Added docs for Disassembler, InstructionDecoder, parseWat rec/sub syntax, GC builder-object support
- Added tests for all new features

Author: DevNamedZed

README.md

@@ -186,7 +186,7 @@ npm run build
 npm test
 
 # Run tests with coverage
-npm run test:cover
+npm run test:coverage
 
 # Regenerate opcode definitions from spec
 npm run generate

docs/api.md

@@ -51,7 +51,7 @@ importFunction(
 ): ImportBuilder
 
 // Import memory
-importMemory(module: string, name: string, initial: number, maximum?: number, shared?: boolean): ImportBuilder
+importMemory(module: string, name: string, initial: number, maximum?: number, shared?: boolean, memory64?: boolean): ImportBuilder
 
 // Import a table
 importTable(
@@ -396,30 +396,32 @@ delegate(depth: number): void
 
 ### GC Operations (requires `gc` feature)
 
-```typescript
-// Struct operations
-struct_new(typeIndex: number): void
-struct_new_default(typeIndex: number): void
-struct_get(typeIndex: number, fieldIndex: number): void
-struct_get_s(typeIndex: number, fieldIndex: number): void
-struct_get_u(typeIndex: number, fieldIndex: number): void
-struct_set(typeIndex: number, fieldIndex: number): void
-
-// Array operations
-array_new(typeIndex: number): void
-array_new_default(typeIndex: number): void
-array_new_fixed(typeIndex: number, length: number): void
-array_new_data(typeIndex: number, dataIndex: number): void
-array_new_elem(typeIndex: number, elemIndex: number): void
-array_get(typeIndex: number): void
-array_get_s(typeIndex: number): void    // Signed packed field access
-array_get_u(typeIndex: number): void    // Unsigned packed field access
-array_set(typeIndex: number): void
+All `typeIndex` parameters accept either a numeric index or a builder object (`StructTypeBuilder`, `ArrayTypeBuilder`, etc.) — the `.index` is extracted automatically.
+
+```typescript
+// Struct operations — typeIndex accepts number or builder
+struct_new(typeIndex: number | { index: number }): void
+struct_new_default(typeIndex: number | { index: number }): void
+struct_get(typeIndex: number | { index: number }, fieldIndex: number): void
+struct_get_s(typeIndex: number | { index: number }, fieldIndex: number): void
+struct_get_u(typeIndex: number | { index: number }, fieldIndex: number): void
+struct_set(typeIndex: number | { index: number }, fieldIndex: number): void
+
+// Array operations — typeIndex accepts number or builder
+array_new(typeIndex: number | { index: number }): void
+array_new_default(typeIndex: number | { index: number }): void
+array_new_fixed(typeIndex: number | { index: number }, length: number): void
+array_new_data(typeIndex: number | { index: number }, dataIndex: number): void
+array_new_elem(typeIndex: number | { index: number }, elemIndex: number): void
+array_get(typeIndex: number | { index: number }): void
+array_get_s(typeIndex: number | { index: number }): void    // Signed packed field access
+array_get_u(typeIndex: number | { index: number }): void    // Unsigned packed field access
+array_set(typeIndex: number | { index: number }): void
 array_len(): void
-array_fill(typeIndex: number): void
-array_copy(dstTypeIndex: number, srcTypeIndex: number): void
-array_init_data(typeIndex: number, dataIndex: number): void
-array_init_elem(typeIndex: number, elemIndex: number): void
+array_fill(typeIndex: number | { index: number }): void
+array_copy(dstTypeIndex: number | { index: number }, srcTypeIndex: number | { index: number }): void
+array_init_data(typeIndex: number | { index: number }, dataIndex: number): void
+array_init_elem(typeIndex: number | { index: number }, elemIndex: number): void
 
 // Reference operations
 ref_null(heapType: number): void       // Push a null reference (HeapType value)
@@ -530,13 +532,19 @@ Returned by `ModuleBuilder.defineTag()`. Describes an exception tag for use with
 ```typescript
 // The function type describing the tag's parameter types
 get funcType(): FuncTypeBuilder
+
+// Export this tag
+withExport(name?: string): TagBuilder
+
+// Set the debug name for this tag
+withName(name: string): TagBuilder
 ```
 
 ---
 
 ## ImportBuilder
 
-Returned by `ModuleBuilder.importFunction()`, `importMemory()`, `importTable()`, `importGlobal()`.
+Returned by `ModuleBuilder.importFunction()`, `importMemory()`, `importTable()`, `importGlobal()`, `importTag()`.
 
 ```typescript
 // Properties
@@ -821,6 +829,64 @@ const info = reader.read();
 
 ---
 
+## Disassembler
+
+Converts a parsed WASM binary (from `BinaryReader`) back into WAT text format.
+
+```typescript
+import { BinaryReader, Disassembler } from 'webasmjs';
+
+const reader = new BinaryReader(wasmBytes);
+const moduleInfo = reader.read();
+
+const disassembler = new Disassembler(moduleInfo);
+const wat = disassembler.disassemble();
+// Returns a full WAT module string:
+// (module $name
+//   (type ...)
+//   (func ...)
+//   ...
+// )
+```
+
+Handles all section types including types (func, struct, array, rec groups), imports, functions with decoded instructions, tables, memories, globals, exports, start, elements, and data segments. Uses the name section when available for readable `$name` identifiers.
+
+---
+
+## InstructionDecoder
+
+Low-level decoder that converts raw WebAssembly instruction bytes into structured objects.
+
+```typescript
+import { InstructionDecoder } from 'webasmjs';
+import type { DecodedInstruction } from 'webasmjs';
+
+// Decode a buffer of instruction bytes
+const decoder = new InstructionDecoder(bodyBytes);
+const instructions: DecodedInstruction[] = decoder.decode();
+
+// Or decode an init expression (e.g. from a global or data segment offset)
+const initInstructions = InstructionDecoder.decodeInitExpr(initExprBytes);
+```
+
+Each `DecodedInstruction` contains:
+
+```typescript
+interface DecodedInstruction {
+  opCode: OpCodeDef;    // The opcode definition (mnemonic, value, prefix, etc.)
+  immediates: {
+    type: string;       // Immediate kind: 'VarUInt32', 'MemoryImmediate', etc.
+    values: any[];      // Decoded immediate values
+  };
+  offset: number;       // Byte offset in the original buffer
+  length: number;       // Total byte length of this instruction
+}
+```
+
+Supports all instruction encodings including single-byte opcodes, prefixed opcodes (0xFC bulk/sat-trunc, 0xFB GC, 0xFD SIMD), LEB128 integers, floats, branch tables, v128 constants, and GC type immediates.
+
+---
+
 ## parseWat
 
 Parses WAT text format into a `ModuleBuilder`.
@@ -842,6 +908,38 @@ const mod = parseWat(`
 const instance = await mod.instantiate();
 ```
 
+### Recursive type groups
+
+```typescript
+const mod = parseWat(`
+  (module
+    (rec
+      (type $list (sub (struct (field i32) (field (ref null $list)))))
+    )
+    (func $len (param (ref null $list)) (result i32)
+      (local $count i32)
+      ;; ...
+    )
+  )
+`);
+```
+
+### Subtype declarations
+
+```typescript
+const mod = parseWat(`
+  (module
+    (type $base (sub (struct (field $x (mut i32)))))
+    (type $child (sub $base (struct (field $x (mut i32)) (field $y f64))))
+    (type $sealed (sub_final $base (struct (field $x (mut i32)) (field $z i64))))
+  )
+`);
+```
+
+- `sub` — declares an open (non-final) type that can be further subtyped
+- `sub $parent` — declares an open subtype of `$parent`
+- `sub_final $parent` — declares a sealed (final) subtype of `$parent`
+
 ---
 
 ## Enums

docs/examples.md

@@ -1,6 +1,7 @@
 # Examples
 
-> For all 103 interactive examples, see the [playground](https://devnamedzed.github.io/webasmjs/).
+> For all 112 interactive examples, see the [playground](https://devnamedzed.github.io/webasmjs/).
+> The playground includes additional coverage for atomics, memory64, relaxed SIMD, tail calls, imports, and GC struct DSL.
 > This page covers the most important patterns in detail.
 
 ## Factorial

docs/getting-started.md

@@ -80,7 +80,7 @@ The `end` instruction is automatically added when using the callback form.
 
 ## Control Flow
 
-Use block, loop, and if/else with callbacks for structured control flow:
+Use block, loop, and if/else for structured control flow:
 
 ```typescript
 mod.defineFunction('abs', [ValueType.Int32], [ValueType.Int32], (f, a) => {
@@ -148,3 +148,19 @@ console.log(wat);
 - [API Reference](api.md) — complete documentation of all builders and emitters
 - [Examples](examples.md) — annotated examples covering common patterns
 - [Playground](https://devnamedzed.github.io/webasmjs/) — try webasmjs in the browser
+
+You can also build modules by parsing WAT text with `parseWat()`:
+
+```typescript
+import { parseWat } from 'webasmjs';
+
+const mod = parseWat(`
+  (module
+    (func (export "add") (param i32 i32) (result i32)
+      local.get 0
+      local.get 1
+      i32.add))
+`);
+
+const instance = await mod.instantiate();
+```

examples/factorial.js

@@ -46,9 +46,9 @@ function getOperandInfo(operand: string | null): OperandInfo | null {
     case 'VarUInt1':
       return { param: 'varUInt1: number', call: 'varUInt1' };
     case 'MemoryImmediate':
-      return { param: 'alignment: number, offset: number', call: 'alignment, offset' };
+      return { param: 'alignment: number, offset: number | bigint', call: 'alignment, offset' };
     case 'IndirectFunction':
-      return { param: 'funcTypeBuilder: any', call: 'funcTypeBuilder' };
+      return { param: 'funcTypeBuilder: any, tableIndex?: number', call: 'funcTypeBuilder, tableIndex' };
     case 'BlockSignature':
       return { param: 'blockType: any, label?: any', call: 'blockType, label' };
     case 'Function':
@@ -70,17 +70,17 @@ function getOperandInfo(operand: string | null): OperandInfo | null {
     case 'VarInt64':
       return { param: 'varInt64: number | bigint', call: 'varInt64' };
     case 'VarUInt32':
-      return { param: 'varUInt32: number', call: 'varUInt32' };
+      return { param: 'varUInt32: number | { index: number }', call: 'varUInt32' };
     case 'V128Const':
       return { param: 'bytes: Uint8Array', call: 'bytes' };
     case 'LaneIndex':
       return { param: 'laneIndex: number', call: 'laneIndex' };
     case 'ShuffleMask':
       return { param: 'mask: Uint8Array', call: 'mask' };
     case 'TypeIndexField':
-      return { param: 'typeIndex: number, fieldIndex: number', call: 'typeIndex, fieldIndex' };
+      return { param: 'typeIndex: number | { index: number }, fieldIndex: number', call: 'typeIndex, fieldIndex' };
     case 'TypeIndexIndex':
-      return { param: 'typeIndex: number, index: number', call: 'typeIndex, index' };
+      return { param: 'typeIndex: number | { index: number }, index: number', call: 'typeIndex, index' };
     case 'HeapType':
       return { param: 'heapType: any', call: 'heapType' };
     case 'BrOnCast':