rust_browser/docs/js_feature_matrix.md

# JavaScript Feature Matrix

Status of JS language features in the custom interpreter (`js_parser` + `js_vm`).

## Legend

| Status | Meaning |
|--------|---------|
| Supported | Feature works and has conformance tests |
| Not Supported | Feature not yet implemented (tracked as known_fail) |
| Partial | Some sub-features work, others don't |

## Language Core

| Feature | Status | Conformance Tests | Known Failures | Notes |
|---------|--------|-------------------|----------------|-------|
| `var` declarations | Supported | 11 | 0 | Hoisting, function scope, block visibility |
| `let` declarations | Supported | (in var-decl tests) | 0 | Block scoping, TDZ |
| `const` declarations | Supported | (in var-decl tests) | 0 | Immutability enforced |
| Number literals | Supported | (in expr tests) | 0 | IEEE 754 f64 |
| String literals | Supported | (in expr tests) | 0 | UTF-8, escape sequences |
| Boolean literals | Supported | (in type tests) | 0 | |
| `null` / `undefined` | Supported | (in type tests) | 0 | |
| Arithmetic operators | Supported | 16 | 0 | `+`, `-`, `*`, `/`, `%` with coercion |
| Comparison operators | Supported | (in expr tests) | 0 | `==`, `===`, `!=`, `!==`, `<`, `>`, `<=`, `>=` |
| Unary operators | Supported | (in expr tests) | 0 | `typeof`, `-`, `!` |
| Logical operators | Supported | 2 | 0 | `&&`, `\|\|` with short-circuit evaluation |
| Bitwise operators | Not Supported | 0 | 1 | `&`, `\|`, `^`, `~`, `<<`, `>>` |
| Ternary operator | Not Supported | 0 | 1 | `? :` |
| Compound assignment | Supported | 1 | 0 | `+=`, `-=`, `*=` |
| Increment/decrement | Supported | 1 | 0 | `++`, `--` (prefix and postfix) |
| Computed member access | Supported | 1 | 0 | `obj[key]` |
| `instanceof` | Not Supported | 0 | 1 | |
| Template literals | Supported | 24 | 0 | `` `${expr}` `` |
| `if`/`else` | Supported | 6 | 0 | Nested, truthiness rules |
| `for` loops | Supported | 6 | 0 | `for (init; test; update)`, break, continue, let scoping |
| `for...in` | Not Supported | 0 | 1 | |
| `while` loops | Supported | 3 | 0 | break, continue |
| `do...while` loops | Supported | 2 | 0 | Executes body at least once |
| `switch` | Supported | 1 | 0 | Basic matching, fall-through, break, default |
| Function declarations | Supported | 10 | 0 | Hoisting, recursion, closures |
| Function expressions | Supported | (in func tests) | 0 | Named and anonymous |
| Arrow functions | Supported | 3 | 0 | Expression/block body, lexical `this`, `new` rejection |
| `try`/`catch`/`finally` | Supported | 5 | 0 | All clause combinations, catch param scoping |
| `throw` | Supported | (in try-catch tests) | 0 | Throw + catch integration |
| Array literals | Supported | 6 | 0 | `[1,2,3]`, `.push()`, `.pop()`, `.join()`, `.indexOf()`, `.slice()`, `.concat()` |
| Object literals | Supported | 4 | 0 | Creation, dot access, assignment, nesting |
| `this` keyword | Supported | 5 | 0 | Global scope, constructors, method calls |
| String methods | Supported | 3 | 0 | `.length`, `.charAt()`, `.indexOf()`, `.slice()`, etc. (ASCII-focused, `chars()` indexing) |
| `Function.name` / `.call()` | Supported | 1 | 0 | Direct member-call only (`fn.call(thisArg, ...)`) |
| `Object.prototype.toString` | Supported | 1 | 0 | `Object.prototype.toString.call(value)` type tagging |
| Function properties | Supported | (in test262 tests) | 0 | `fn.prop = val`, `fn.prop`, `fn.method()` |
| `typeof` | Supported | 5 | 0 | All value types |

## Web APIs (DOM / Events / Scheduling)

| Feature | Status | Conformance Tests | Known Failures | Notes |
|---------|--------|-------------------|----------------|-------|
| `document.getElementById()` | Supported | 6 | 0 | Returns null for missing |
| `document.createElement()` | Supported | (in dom tests) | 0 | |
| `element.appendChild()` | Supported | (in dom tests) | 0 | Returns appended child |
| `element.removeChild()` | Supported | (in dom tests) | 0 | Error if not a child |
| `element.textContent` | Supported | (in dom tests) | 0 | Get and set |
| `element.addEventListener()` | Supported | 6 | 0 | Click events, bubbling |
| `element.removeEventListener()` | Supported | (in event tests) | 0 | |
| `event.preventDefault()` | Supported | (in event tests) | 0 | |
| `event.stopPropagation()` | Supported | (in event tests) | 0 | |
| `event.type` | Supported | (in event tests) | 0 | |
| `setTimeout()` | Supported | 7 | 0 | Deterministic virtual clock |
| `clearTimeout()` | Supported | (in sched tests) | 0 | |
| `queueMicrotask()` | Supported | (in sched tests) | 0 | |
| `Promise` constructor | Supported | 5 | 0 | `new Promise(fn)` |
| `Promise.resolve()` | Supported | (in promise tests) | 0 | |
| `Promise.reject()` | Supported | (in promise tests) | 0 | |
| `.then()` / `.catch()` | Supported | (in promise tests) | 0 | Chaining, error recovery |
| `console.log()` | Supported | (in unit tests) | 0 | Capture sink for testing |

## Error Handling

| Error Type | Status | Notes |
|------------|--------|-------|
| `ReferenceError` | Supported | Undeclared variables, TDZ |
| `TypeError` | Supported | Null property access, non-function calls, const assignment |
| `ParseError` | Supported | Syntax errors |
| `RuntimeError` | Supported | Statement limit exceeded |
| Source locations | Supported | Line:col in error messages |

## Test Counts Summary

| Category | Pass | Known Fail | Total |
|----------|------|------------|-------|
| JS262 conformance | 121 | 5 | 127 |
| Integration (js_tests) | 45 | — | 45 |
| Integration (js_dom_tests) | 25 | — | 25 |
| Integration (js_events) | 14 | — | 14 |
| Integration (js_scheduling) | 24 | — | 24 |
| Unit (js_vm interpreter) | 395 | — | 395 |
| Unit (js_vm value) | 57 | — | 57 |
| Unit (js_vm other) | 50 | — | 50 |
| Unit (js_parser) | 214 | — | 214 |
| Unit (js_parser tokenizer) | 39 | — | 39 |
| Unit (js_parser token) | 13 | — | 13 |
| Unit (js crate) | 28 | — | 28 |
| Unit (web_api) | 111 | — | 111 |
| **Total** | **1136** | **5** | **1142** |

## Test262 Coverage (Phase A)

50 real Test262 tests vendored from `tc39/test262` and run via `mode = "test262"` in the JS262 harness.
These are **in addition** to the hand-written conformance tests counted above.

| Feature Area | Pass | Known Fail | Total |
|--------------|------|------------|-------|
| asi | 3 | 2 | 5 |
| block-scope | 12 | 8 | 20 |
| comments | 5 | 0 | 5 |
| directive-prologue | 5 | 0 | 5 |
| expressions | 10 | 5 | 15 |
| **Total** | **35** | **15** | **50** |

See `docs/test262_roadmap.md` for the integration plan and `docs/js_conformance_report.md` for known-fail details.