Update documentation to the latest version

Author: johnsamuelwrites

design/index.md

@@ -101,17 +101,17 @@ Source File (.ml)
     ┌──┴──┐
     │     │
     ▼     ▼
-┌───────┐ ┌────────┐
-│Python │ │  WASM  │  Code generation targets
-│Code   │ │  Code  │
-│Gen.   │ │  Gen.  │
-└───┬───┘ └───┬────┘
-    │         │
-    ▼         ▼
+┌───────┐ ┌─────────┐
+│Python │ │   WAT   │  Code generation targets
+│Code   │ │   Code  │
+│Gen.   │ │   Gen.  │
+└───┬───┘ └────┬────┘
+    │          │
+    ▼          ▼
 ┌───────┐ ┌──────────────┐
-│Python │ │  Cranelift   │
-│Runtime│ │  Compiler    │
-│(exec) │ │  → .wasm     │
+│Python │ │  WAT text    │
+│Runtime│ │  → wasmtime  │
+│(exec) │ │  (→ .wasm)   │
 └───────┘ └──────────────┘
 ```
 
@@ -363,6 +363,7 @@ JSON-based keyword files allow community contributors to add new languages witho
 | `multilingualprogramming/core/ir.py` | CoreIRProgram definition |
 | `multilingualprogramming/core/lowering.py` | AST → Core IR lowering |
 | `multilingualprogramming/codegen/python_generator.py` | Python code generation |
-| `multilingualprogramming/codegen/wasm_generator.py` | WASM code generation |
+| `multilingualprogramming/codegen/wat_generator.py` | AST → WebAssembly Text (WAT) generation |
+| `multilingualprogramming/codegen/wasm_generator.py` | WAT text → WASM binary |
 | `multilingualprogramming/runtime/backend_selector.py` | WASM/Python backend selection |
 | `multilingualprogramming/runtime/python_fallbacks.py` | Pure Python WASM fallbacks |

index.md

@@ -6,7 +6,7 @@ permalink: /
 ---
 
 <section class="hero">
-  <span class="hero-eyebrow">v0.4.0 &mdash; Now with WASM</span>
+  <span class="hero-eyebrow">v0.5.1 &mdash; Now with WASM &amp; OOP</span>
   <h1 class="hero-title">
     Write Code in<br/>
     <span class="gradient-text">Any Human Language</span>
@@ -27,7 +27,7 @@ permalink: /
     <div class="stat-label">Human Languages</div>
   </div>
   <div class="stat-item">
-    <div class="stat-value">858</div>
+    <div class="stat-value">1,797</div>
     <div class="stat-label">Test Cases</div>
   </div>
   <div class="stat-item">
@@ -39,7 +39,7 @@ permalink: /
     <div class="stat-label">Localized Builtins</div>
   </div>
   <div class="stat-item">
-    <div class="stat-value">0.4.0</div>
+    <div class="stat-value">0.5.1</div>
     <div class="stat-label">Current Version</div>
   </div>
 </div>
@@ -184,7 +184,7 @@ saludar(nombre)
 
 <div class="feature-card">
 <span class="feature-icon">🧪</span>
-<div class="feature-title">858 Tests, 78 Suites</div>
+<div class="feature-title">~1,797 Tests, 58 Files</div>
 <p class="feature-desc">Comprehensive test coverage across all 17 languages. Every language frontend is validated end-to-end: lexer → parser → semantic → codegen → execution.</p>
 </div>
 
@@ -330,15 +330,15 @@ Surface Language (.ml file)
     ┌────┴────┐
     │         │
     ▼         ▼
-┌───────┐ ┌──────┐
-│Python │ │ WASM │  Code generation targets
-│  Gen  │ │  Gen │
-└───┬───┘ └──┬───┘
-    │         │
-    ▼         ▼
+┌───────┐ ┌─────────┐
+│Python │ │   WAT   │  Code generation targets
+│  Gen  │ │   Gen   │
+└───┬───┘ └────┬────┘
+    │           │
+    ▼           ▼
 ┌───────┐ ┌──────────┐
-│Python │ │ Cranelift│
-│Runtime│ │ Compiler │
+│Python │ │ wasmtime │
+│Runtime│ │ (→ .wasm)│
 └───────┘ └──────────┘
 ```
 

reference/compatibility.md

@@ -1,7 +1,7 @@
 ---
 layout: page
 title: "Compatibility Matrix"
-description: "Python 3.12 compatibility baseline for multilingual — 858 tests, 78 suites, 17 languages."
+description: "Python 3.12 compatibility baseline for multilingual — ~1,797 tests, 58 test files, 17 languages."
 category: "Reference"
 permalink: /reference/compatibility/
 prev_page:
@@ -12,7 +12,7 @@ prev_page:
 This matrix defines the current compatibility baseline for `multilingual`. The source of truth is:
 
 - `examples/complete_features_en.ml` and equivalents in all 17 languages
-- `tests/` (858 tests across 78 test suites)
+- `tests/` (~1,797 tests across 58 test files)
 
 **Target runtime**: CPython 3.12.x
 
@@ -187,10 +187,10 @@ SOV and RTL languages can use natural word order. The surface normalizer rewrite
 
 ## Test Coverage
 
-858 tests across 78 test suites:
+~1,797 tests across 58 test files (~19,848 lines of test code):
 
-| Test area | Suites | Description |
-|-----------|--------|-------------|
+| Test area | Files | Description |
+|-----------|-------|-------------|
 | Numerals and dates | 8 | Multilingual numerals, Unicode, Roman, complex, fractions, datetime |
 | Lexer | 2 | Tokenization and lexer behavior |
 | Parser | 5 | Expressions, statements, compounds, multilingual, errors |
@@ -200,6 +200,7 @@ SOV and RTL languages can use natural word order. The surface normalizer rewrite
 | Critical features | 8 | Triple-quoted strings, slices, parameters, tuples, comprehensions, decorators, f-strings |
 | Language completeness and CLI | 8 | Augmented assignment, membership, ternary, assert, chained assignment, CLI, REPL |
 | Advanced language features | 23 | Loop else, yield/raise from, set comprehensions, parameter separators, f-string formatting, match guards/OR/AS, global/nonlocal, builtins, exceptions, surface normalization, extended builtins, alias resolution, starred unpacking, integration, multilingual |
+| WAT/WASM backend | 5 | WAT generation, OOP/inheritance in WAT, WASM execution, corpus projects (20) |
 | Infrastructure | 10 | Keyword registry, AST nodes, AST printer, error messages, runtime builtins, REPL |
 
 ---
@@ -218,11 +219,22 @@ The following are **not** claimed as universally compatible:
 
 ---
 
+## Known Fixes (v0.5.x)
+
+| Version | Fix |
+|---------|-----|
+| v0.5.1 | Documentation updates |
+| v0.5.0 | WAT/WASM OOP object model: class lowering with linear-memory bump allocator, inheritance with C3 MRO, `super()` resolution, WAT execution tests |
+| v0.5.0 | SemanticAnalyzer: plain assignments (`x = 5`) now correctly define the variable in scope rather than triggering a false `UNDEFINED_NAME` error (was a false-positive in some languages, e.g., French) |
+| v0.5.0 | Augmented assignment (`x += 1`) now correctly reports `UNDEFINED_NAME` when the target variable has not been previously defined |
+
+---
+
 ## Recommendation
 
 When evaluating compatibility for a real codebase:
 
 1. Start from this matrix
-2. Run smoke tests: `python -m multilingualprogramming smoke --all`
-3. Run focused tests: `python -m multilingualprogramming run yourprogram.ml --lang en`
+2. Run smoke tests: `multilingual smoke --all`
+3. Run focused tests: `multilingual run yourprogram.ml --lang en`
 4. Track gaps as concrete syntax/runtime items

reference/index.md

@@ -8,7 +8,7 @@ next_page:
   title: "Built-in Aliases"
   url: /reference/builtins/
 badges:
-  - text: "v0.4.0"
+  - text: "v0.5.1"
     type: default
   - text: "Python 3.12+"
     type: success
@@ -356,21 +356,28 @@ output = repl.eval_line("afficher(x)")
 
 ```bash
 # Run a program file
-python -m multilingualprogramming run <file.ml> --lang <code>
 multilingual run <file.ml> --lang en
 multilg run programme.ml --lang fr
 
 # Start REPL
-python -m multilingualprogramming repl
-python -m multilingualprogramming repl --lang fr
-python -m multilingualprogramming repl --show-python
+multilingual repl
+multilingual repl --lang fr --show-python --show-wat
+
+# Transpile to Python (print output, no execution)
+multilingual compile hello.ml --lang en
+
+# Build WASM bundle
+multilingual build-wasm-bundle hello.ml --lang en --out-dir ./dist
 
 # Validate a language pack
-python -m multilingualprogramming smoke --lang fr
-python -m multilingualprogramming smoke --all
+multilingual smoke --lang fr
+multilingual smoke --all
+
+# Check generated output encoding
+multilingual encoding-check-generated hello.ml --lang en
 
 # Show version
-python -m multilingualprogramming --version
+multilingual --version
 ```
 
 ---
@@ -420,4 +427,15 @@ python -m multilingualprogramming --version
 | Localized built-in aliases (41 concepts) | ✅ |
 | Surface normalization (SOV/RTL languages) | ✅ |
 
-**858 tests across 78 test suites** provide the compatibility baseline.
+**~1,797 tests across 58 test files** provide the compatibility baseline.
+
+---
+
+## Version History
+
+| Version | Highlights |
+|---------|-----------|
+| `0.5.1` | Documentation updates |
+| `0.5.0` | WAT/WASM OOP object model; class lowering with linear-memory bump allocator; inheritance with C3 MRO; `super()` resolution; WAT execution tests; SemanticAnalyzer plain-assignment fix |
+| `0.4.0` | WAT/WASM code generation; browser playground; WASM backend with 25+ Python fallbacks; 20 corpus projects |
+| `0.3.0` | Earlier milestone |

wasm/architecture.md

@@ -20,7 +20,7 @@ The WASM infrastructure is designed around three principles: **transparent selec
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│              Multilingual Programming Language v0.5          │
+│              Multilingual Programming Language v0.5.1         │
 └─────────────────────────────────────────────────────────────┘
                               │
                 ┌─────────────┴──────────────┐
@@ -291,6 +291,81 @@ The WASM bridge handles errors at multiple levels:
 
 ---
 
+## OOP Object Model in WAT (v0.5.0+)
+
+Classes with instance attributes use a **linear-memory bump allocator** for object storage. Stateless classes (no `self.attr` assignments) use `f64.const 0` as the `self` value for backward compatibility.
+
+### Heap Allocator
+
+```wat
+(global $__heap_ptr (mut i32) (i32.const HEAP_BASE))
+```
+
+- Emitted only when at least one stateful class exists.
+- `HEAP_BASE` is computed from string data size, rounded up to 8-byte alignment (minimum 64).
+- Each constructor advances `$__heap_ptr` by the object's byte size and returns the pointer as `f64`.
+
+### Field Layout
+
+Fields are stored as `f64` values (8 bytes each) in linear memory. Inherited fields come first:
+
+```
+Object memory layout:
+┌─────────────────────────────────────────────────┐
+│ +0   │ field_0 (f64, 8 bytes)                   │
+│ +8   │ field_1 (f64, 8 bytes)                   │
+│ ...  │                                           │
+└─────────────────────────────────────────────────┘
+```
+
+Field store/load pattern:
+
+```wat
+;; self.attr = value  (store)
+local.get $self
+i32.trunc_f64_u
+i32.const <field_offset>   ;; field_index * 8
+i32.add
+<value>
+f64.store
+
+;; x = self.attr  (load)
+local.get $self
+i32.trunc_f64_u
+i32.const <field_offset>
+i32.add
+f64.load
+```
+
+### Inheritance
+
+- `_effective_field_layout(cls)`: merges parent fields before own fields recursively.
+- `_mro(cls)`: C3 linearization (same algorithm as CPython, cycle-safe).
+- Method resolution: if a subclass does not define a method, the parent's WAT function name is used.
+- Constructor inheritance: if a class has no `__init__`, the parent's constructor is inherited.
+- `super()` calls: `_resolve_super_call(expr)` detects `super().method(...)` and maps to the parent's WAT function.
+
+### Stub Detection
+
+Unsupported WAT constructs emit comment stubs:
+
+```wat
+;; unsupported call: len(mylist)
+```
+
+Use `has_stub_calls(wat_text)` to detect stubs programmatically:
+
+```python
+from multilingualprogramming.codegen.wat_generator import WATCodeGenerator, has_stub_calls
+
+gen = WATCodeGenerator("en")
+wat = gen.generate(ast)
+if has_stub_calls(wat):
+    print("WAT contains unsupported call stubs")
+```
+
+---
+
 ## Extending WASM with New Functions
 
 To add a new operation to the WAT backend:

wasm/index.md

@@ -58,8 +58,8 @@ The multilingual WASM backend provides 50–100x performance improvements for co
 
 <div class="card">
 <span class="card-icon">🔧</span>
-<h3>Cranelift Backend</h3>
-<p>Uses the Cranelift compiler (Rust-based, part of Wasmtime) for native-speed code generation from the multilingual AST.</p>
+<h3>WAT Code Generation</h3>
+<p>Compiles the Core AST directly to WebAssembly Text (WAT) format. WAT is assembled to binary WASM and executed via wasmtime — no external Rust toolchain required.</p>
 </div>
 
 <div class="card">
@@ -146,9 +146,9 @@ multilingual Source (.ml)
          │ Core AST
          ▼
   ┌─────────────────┐
-  │  WASM Generator │  → Rust intermediate code
-  │  (wasm_generator.py) │    ↓
-  └─────────────────┘  Cranelift compiler
+  │  WAT Generator  │  → WAT text (module.wat)
+  │  (wat_generator.py)  │    ↓
+  └─────────────────┘  wabt / wat2wasm
                             ↓
                        .wasm binary
                             │
@@ -184,6 +184,40 @@ multilingual Source (.ml)
 
 ---
 
+## WAT Language Support
+
+The WAT backend supports a rich subset of the multilingual language. Unsupported constructs emit stub comments and fall back to Python.
+
+| Construct | WAT support |
+|---|---|
+| Variable declaration/assignment | ✓ |
+| Arithmetic (+, -, *, /) | ✓ (f64) |
+| Augmented assignment (+=, -=, *=, /=, //=, %=) | ✓ |
+| Augmented assignment (&=, \|=, ^=, <<=, >>=) | ✓ i32 round-trip |
+| Comparisons and boolean logic | ✓ |
+| `if` / `elif` / `else` | ✓ |
+| `while` loop | ✓ |
+| `for` loop | ✓ |
+| Function definition and `return` | ✓ |
+| `async def` / `await` | ✓ best-effort |
+| Class definition (OOP) with fields | ✓ linear-memory object model |
+| Inheritance and `super()` | ✓ C3 MRO |
+| `match`/`case` (numeric/boolean) | ✓ lowered to WAT blocks |
+| `match`/`case` (string/complex) | stub |
+| `print` | ✓ host import |
+| `abs`, `min`, `max` (n-arg) | ✓ native f64 ops |
+| `len` (string literal/var, list, tuple) | ✓ |
+| List/tuple literal allocation | ✓ heap bump-allocator |
+| List/tuple index read | ✓ |
+| `try/except/finally` | ✓ best-effort |
+| `with` statement | ✓ best-effort |
+| Lambda expressions | ✓ lifted to named WAT functions |
+| List/generator comprehension over `range` | ✓ |
+| String concatenation, indexing, slicing | not supported |
+| `async for` / `async with` | not supported |
+
+---
+
 ## Supported Operations
 
 All 17 languages support both Python and WASM backends. The WASM backend accelerates: