xbintsc 0.5.6 → 0.5.21

package/doc/implemented.md

@@ -1,377 +1,76 @@
 # xbintsc Implemented Syntax and Features
 
-This document was compiled by checking the source (`src/`, `runtime/`) and tests
-(`tests/`) file by file, and lists only the syntax and features that are
+This documentation was compiled by checking the source (`src/`, `runtime/`) and
+tests (`tests/`) file by file, and lists only the syntax and features that are
 **actually usable today**. Implementation locations are noted for traceability.
 
+The pages are split by compiler stage and feature area so a change lands in one
+small file instead of a single monolithic document.
+
 > Note: the compiler *parses* much more than it *generates code* for. Many
 > TypeScript constructs can be parsed, and even bound, but the code generation
 > stage reports `UnsupportedFeature`. Those are **not** listed here; see the
-> [unimplemented document](./unimplemented.md).
+> [unimplemented documentation](./unimplemented.md).
 
 > Language: **English** | [简体中文](./zh-CN/implemented.md)
 
----
-
-## 1. Compilation pipeline (fully implemented)
-
-```
-source.ts
-   │  lexer       src/lexer/scanner.ts + token.ts
-   ▼
- tokens
-   │  parser      src/parser/parser.ts  →  AST  src/ast/
-   ▼
- AST
-   │  binder      src/binder/binder.ts  →  scopes/symbols/closure capture
-   ▼
- bound AST
-   │  codegen     src/codegen/llvm.ts + values.ts  →  LLVM IR text
-   ▼
- module.ll ── clang ──► module.o ──link──► executable
-                                   ▲
-                          runtime/*.c (C runtime, split by function)
-```
-
-- Front end, back end, runtime and extensions are fully decoupled.
-- The flow is orchestrated by `src/driver/compiler.ts`: `read → parse → bind → IR → object file → link`.
-- **Self-hosting**: `xbintsc` compiles its own front end. Building `src/cli/main.ts`
-  with the compiler yields a working `xbintsc` binary, and that binary rebuilds
-  itself with byte-identical LLVM IR (source ≡ generation 1 ≡ generation 2 ≡
-  generation 3). The runtime is still hand-written C.
-
----
-
-## 2. Lexer (implemented)
-
-Location: `src/lexer/scanner.ts`, `src/lexer/token.ts`
-
-- Full token classification: identifiers, keywords, private identifiers, numbers, strings, templates, regex (scanning), all punctuation and operators.
-- Full keyword table: `abstract any as asserts async await bigint boolean break case catch class const constructor continue debugger declare default delete do else enum export extends false finally for from function get if implements import in infer instanceof interface is keyof let module namespace never new null number object package private protected public readonly return satisfies set static string super switch symbol this throw true try type typeof undefined unique unknown var void while with yield`
-- Numeric literals:
-  - Decimal, `0x` hex, `0o` octal, `0b` binary
-  - Underscore separators `1_000_000`
-  - Fractions, exponents `1.5e3`
-  - BigInt literals (`10n`, `0xFFn`) evaluate to arbitrary-precision integers (arithmetic, bitwise, shifts, comparisons, `toString(radix)`, `BigInt()` / `BigInt.asIntN` / `BigInt.asUintN`)
-  - BigInt literal values are parsed exactly into `bigint` (never routed through `Number`), so the token / AST value of a literal beyond 2^53 keeps full precision
-- String literals:
-  - Single / double quotes
-  - Escapes: `\n \t \r \b \f \0 \\ \' \"`, `\xHH`, `\uHHHH`, `\u{...}`
-- Template literals (lexer level): no-substitution templates, `TemplateHead`, `TemplateMiddle`, `TemplateTail`, with `${}` and escapes.
-- Regex literal scanning (`/pattern/flags`), distinguishing division `/`.
-- Private identifiers `#name`.
-- Comments: line `//` and block `/* */` (with unterminated diagnostics).
-- Newline and whitespace tracking (for ASI), BOM / CRLF normalization (`SourceFile`).
-- Lexical diagnostics: unterminated string / template / comment, illegal character, illegal number, illegal escape.
-
----
-
-## 3. Parser (implemented)
-
-Location: `src/parser/parser.ts`, `src/ast/nodes.ts`
-
-### 3.1 Statements
-
-- Variable declarations: `var` / `let` / `const`, with multiple declarators `const a = 1, b = 2;`
-- Function declarations, function expressions and methods, including the `async` modifier and generators (`function*`, `yield`, `yield*`, `.next`/`.throw`/`.return`)
-- `class` declarations / class expressions (constructor, fields, methods, `static`, `extends`)
-- `if` / `else`
-- `while`, `do...while`
-- `for` (init, condition and increment may all be omitted)
-- `for...of`, `for...in` (see the semantic limits in 3.5)
-- `return`, `break`, `continue`, `throw` (including labeled `break label` / `continue label`)
-- `switch` / `case` / `default` (including fall-through)
-- `try` / `catch` / `finally` (catchable exceptions based on a runtime setjmp frame)
-- `export var` / `export let` / `export const` (modifier parsed then erased)
-- Block statement `{}`, empty statement `;`, `debugger;`
-- Expression statements
-
-### 3.2 Expressions
-
-- All common operators with precedence / associativity (see section 5)
-- Assignment expressions and all compound assignments (see section 5)
-- Conditional (ternary) expressions `a ? b : c`
-- Arrow functions `() => expr` / `() => { ... }` (including type parameters and return type annotations)
-- Function expressions `function () {}` and named function expressions `function g() {}`
-- Call expressions `f(...)`, member access `a.b`, element access `a[i]`
-- Array literals `[1, 2]`, sparse array elision, spread `[...a]` (also over strings, `Map` and `Set`)
-- Object literals `{ a: 1 }`, shorthand properties `{ a }`, method shorthand `{ m() {} }`, getter / setter shorthand `{ get x() {} }` / `{ set x(v) {} }`, computed keys `{ [expr]: 1 }`, object spread `{ ...obj }`
-- Template literal `${}` substitutions, tagged templates (with raw strings and `String.raw`)
-- Parenthesized expressions, `as` / `satisfies` / non-null assertion `!` (type erasure)
-- Unary: `+ - ! ~ typeof void`, prefix / postfix `++ --`
-- Optional chaining `?.` / `?.[]` / `?.()` (with nullish short-circuit semantics)
-- `delete` expressions (delete an object property)
-
-### 3.3 TypeScript type syntax (parsed only, structure preserved then erased)
-
-- Type annotations, return type annotations, type parameters `<T>` and constraints `<T extends U>`, type parameter defaults
-- Type references, qualified names `A.B`
-- Unions `|`, intersections `&`, arrays `T[]`, tuples `[T, U]`, optional tuple members `T?`, rest tuple members `...T`
-- Function types `(a: T) => U`, construct signatures `new () => T`
-- Object type literals, property signatures, method signatures, index signatures `[k: string]: T`
-- Conditional types `T extends U ? X : Y`, mapped types `{ [K in T]: U }`, `infer`
-- Type operators `keyof`, `unique`, `readonly`
-- `typeof` (type query), indexed access types `T[K]`
-- Literal types, `this` types
-- Type predicates `x is T` / `asserts x is T`
-- Interfaces, type aliases, enums, namespace / module declarations
-- The various forms of `import` / `export` (structural parsing)
-
-### 3.4 Module syntax (structural parsing + driver bundling)
-
-- `import default, { named } from "..."`, `import * as ns from "..."` (namespace imports of relative modules are lowered to a synthetic object literal; extension modules such as `path` are also supported), `import type`
-- `export default`, `export { a as b }`, `export *`, `export =`
-- Import attributes (`with` / `assert`)
-- The **runtime semantics** of `import` / `export` are handled at the driver layer by `src/driver/modules.ts`: it recursively resolves relative dependencies *and* bare `node_modules` packages (following `exports` / `module` / `main` and package subpaths), renames top-level symbols with a per-module prefix, rewrites references, merges into a single file and rebinds. Packages may be ESM or CommonJS: a CommonJS file under `node_modules` gets a synthetic `module`/`exports` pair, its `require` calls are lowered to the bundled dependency's exports, and its statically-detected exports are exposed to ESM importers. `require()` outside `node_modules` is still rejected with a hint to use `import`. Circular dependencies error out.
-
-### 3.5 ASI
-
-- Automatic Semicolon Insertion, based on `precededByLineBreak` / `}` / EOF.
-
----
-
-## 4. Name binding and scopes (Binder, implemented)
-
-Location: `src/binder/binder.ts`
-
-- Scope kinds: module, function, block, `for`, `catch`
-- Symbol kinds: `var` / `let` / `const` / `function` / `parameter` / `class` / `interface` / `type` / `enum` / `import` / `namespace`
-- `var` and function declarations hoist to the function scope; `let` / `const` stay block-scoped
-- Identifier → declaration resolution; unresolved identifier collection (`CannotFindName`)
-- Closure capture analysis: outer variables referenced by an inner function are marked `captured` / `boxed`, and capture indices are threaded through intermediate closures
-- Parameters are registered as local symbols; the self-name of a named function expression is registered as `const`
-- Type-only declarations (interface / type alias) do not participate in value capture
-
----
-
-## 5. Operators and assignment (codegen implemented)
-
-Location: `src/codegen/llvm.ts` (`BINARY_RUNTIME`, `emitPrefix`, `emitPostfix`, `emitAssignment`)
-
-### 5.1 Arithmetic
-
-`+ - * / % **` (`**` is right-associative)
-
-### 5.2 Comparison and equality
-
-`< <= > >=`, `== !=` (loose equality), `=== !==` (strict equality)
-
-### 5.3 Logical and short-circuit
-
-`&& || ??` (with short-circuit evaluation), `!`
-
-### 5.4 Bitwise
-
-`& | ^ ~ << >> >>>`
-
-### 5.5 Unary
-
-`+ - ! ~`, prefix / postfix `++ --`
-
-### 5.6 Assignment
-
-`= += -= *= /= %= **= <<= >>= >>>= &= |= ^= &&= ||= ??=`
-
-### 5.7 Other expression operators
-
-- Comma expression `,`
-- `in` operator (`key in obj`, mapped to `xt_in`)
-- `delete obj.key` / `delete obj[key]` (mapped to `xt_delete`)
-- `instanceof` (mapped to `xt_instance_of`, walking the prototype chain)
-
-> `typeof` / `void` are implemented as unary operators.
-
----
-
-## 6. Value model and calling convention (implemented)
-
-Location: `src/codegen/values.ts`, `runtime/rt.h`
-
-- All JS values are unified as a 64-bit `xt_value` (NaN-boxing).
-- Doubles are not boxed; other types are tagged pointers with a 16-bit tag in the high bits and a 48-bit payload.
-- Tags: `undefined` / `null` / `false` / `true` / `string` / `object` / `array` / `function`.
-- Uniform function ABI:
-
-```c
-xt_value fn(xt_value thisValue, xt_value env, int32_t argc, xt_value *argv);
-```
-
-- `thisValue` is threaded as the first ABI parameter (exception-safe, supports nesting); arrow functions inherit `this` lexically from an extra environment slot.
-- Closures thread captured variables through `env` (by reference, boxed); direct calls and closure calls share one code path.
-- `xt_object` carries a prototype field, and property lookup walks the prototype chain; `xt_function` carries a `prototype` and a property bag (static members). `xt_array` also carries a `[[Prototype]]` (Array.prototype). `Object.prototype` is the root of ordinary objects and provides `hasOwnProperty` / `toString` / `valueOf` / `isPrototypeOf` / `propertyIsEnumerable` / `__proto__`; `Object.getPrototypeOf({}) === Object.prototype`.
-
----
-
-## 7. LLVM IR code generation (Codegen, implemented)
-
-Location: `src/codegen/llvm.ts`
-
-- Emits LLVM IR text (`.ll`); no custom register allocation (relies on `alloca` + mem2reg).
-- Statement / block boundary values live in `alloca`; conditionals and short-circuits materialize into temporary slots instead of `phi`.
-- Control flow: `if` / `while` / `do` / `for` / `for...of` / `for...in`, `switch`, `try/catch/finally`, `break` / `continue` / `return`.
-  - `for...of` and spread iterate arrays, strings, typed arrays, `Map`, `Set`, generators and any object exposing `[Symbol.iterator]()` through `xt_iter_open` → `xt_iter_has` / `xt_iter_value` (`Map` yields `[key, value]` pairs); a non-iterable throws `TypeError`.
-  - `switch` tests each `case` with strict equality, executes on a hit, and falls through until `break`.
-  - `try/catch/finally` is implemented with a runtime `_setjmp` frame: `xt_try_enter` pushes, `_setjmp` catches, `xt_throw` long-jumps. The IR passes the caller's frame address (`@llvm.frameaddress(0)`) as the second `_setjmp` argument, matching clang's MSVC lowering: the Windows UCRT `_setjmp` stores that frame in `_JUMP_BUFFER.Frame` and `longjmp` feeds it to `RtlUnwind`, so omitting it made `longjmp` unwind to a bogus target (`STATUS_BAD_FUNCTION_TABLE`). `_setjmp` is used rather than the exported `setjmp` symbol, whose Windows ABI is an incompatible two-argument routine. Functions containing `try` force local variables to stay in memory (inline-asm escape points) so values survive a long jump.
-  - `for...in` reuses `xt_object_keys` to enumerate keys (arrays / strings yield string indices).
-- Expressions:
-  - Identifiers, numbers, BigInt (arbitrary precision), strings, templates, booleans, `null`, `undefined`, `arguments`
-  - Arithmetic / comparison / logical / short-circuit / conditional / bitwise / unary (including `typeof` `void`) / prefix-postfix increment-decrement / compound assignment / logical assignment
-  - Array literals (including spread `[...]`), object literals (including shorthand / methods / object spread `{...obj}`)
-  - Typed arrays (`Uint8Array`, `Int8Array`, `Uint8ClampedArray`, `Uint16Array`, `Int16Array`, `Uint32Array`, `Int32Array`, `Float32Array`, `Float64Array`): construction (`new X(n)` / `new X(iterable)` / `X.from` / `X.of`), `length` / `byteLength` / `byteOffset` / `BYTES_PER_ELEMENT`, element reads/writes with per-type coercion (`ToIntN` / `ToUintN`, `Uint8ClampedArray` rounding, `Float32` single-precision rounding) and the prototype methods `fill` / `set` / `slice` / `subarray` / `join` / `toString` / `indexOf` / `lastIndexOf` / `includes` / `forEach` / `map` / `filter` / `every` / `some` / `find` / `findIndex` / `reduce` / `reverse` / `sort` / `copyWithin` / `at` / `keys` / `values` / `entries`. See the unimplemented document for the deliberate divergences (`subarray` copies, iterator methods return arrays, no `ArrayBuffer`/`DataView`).
-  - Property access (with a `length` special case, `Math` constants), element access, calls
-  - First-class built-in constructors (`const A = Array`, `const M = Map`, `const E = TypeError`, typed arrays): a bare reference lowers to `xt_builtin_constructor`, giving a cached function with `name` / `length`, a `prototype`, and its statics (`A.isArray`, `A.from`, `M.prototype`, ...). Calling or `new`-ing an alias dispatches to the same runtime constructor, and `x instanceof A` walks the shared prototype chain.
-  - Optional chaining `?.` / `?.[]` / `?.()`: nullish check short-circuits to `undefined`
-  - `delete`, `in`, `instanceof`
-  - `this` (saved to the function's `%saved.this`; arrow functions read from an environment slot), `super` (`super.x` / `super(...)`), `new`, `await`
-  - Closures (arrow functions / function expressions) and capture environment construction
-- Classes: constructor closure + prototype object, stored in an LLVM global (`@class.<id>`); instance fields are initialized before the constructor body; `static` members live in the constructor's property bag; `extends` sets up the prototype chain; `super(...)` is invoked through a hidden `__ctor` on the prototype.
-- `async`: closures are marked with `xt_function_set_async`; calling one runs the body on a stackful coroutine (`xt_coroutine.c`, `xt_async.c`) and immediately returns a promise. The body runs synchronously until the first `await` of a pending promise, then suspends; settlement queues a microtask that resumes the coroutine. An exception that escapes the body rejects that promise instead of throwing synchronously. `await` on a non-promise or settled promise keeps the synchronous fast path and raises on rejection.
-- Standard library calls: `console.*`, `Math.*`, `Object.*`, array / string methods all go through `xt_call_method` / `xt_math_call` / `xt_object_*`; `JSON`/`Date`/`Map`/`Set`/`RegExp`/`Promise` statics and constructors go through their `xt_*` functions; global functions (`parseInt`, `setTimeout`, etc.) go through `xt_parse_int`, `xt_set_timeout`, etc.
-- Global string pool (`@.str.N` private constants, UTF-8 escaped).
-- Builtin calls: `console.log` / `info` / `warn` / `error`, `Math.*`, `Object.*`, array / string methods, global functions, extension builtins (uniform `(argc, argv)` ABI).
-- `main` entry point (returns 0, calls the module function, then drains microtasks and runs the event loop until no timers or descriptors remain).
-- Unsupported nodes uniformly report `UnsupportedFeature`; they never crash.
-
----
-
-## 8. C runtime (Runtime, implemented)
-
-Location: `runtime/xt_alloc.c`, `runtime/xt_values.c`, `runtime/xt_containers.c`,
-`runtime/xt_stdlib.c`, `runtime/xt_stdlib2.c`, `runtime/xt_promise.c`, `runtime/xt_async.c`,
-`runtime/xt_coroutine.c`, `runtime/xt_builtins.c`,
-`runtime/xt_io.c`, sharing the private header `runtime/rt_internal.h`; the public ABI is in `runtime/rt.h`.
-
-- Allocator: non-moving mark-sweep collector behind `xt_alloc` (explicit roots, subsystem root providers and a conservative C-stack scan).
-- Value construction: `xt_undefined/xt_null/xt_bool/xt_number/xt_string_new/xt_string_from_cstr`.
-- Strings: UTF-8 storage exposed through JavaScript's UTF-16 view (`length`, indexing, `slice`, `indexOf`, `split`, `padStart` and `codePointAt` count code units; `for...of` and `Array.from` count code points; lone surrogate halves are kept as WTF-8 and recombined on concatenation), lazy cons-node concatenation (bytes are flattened on first observation, so append loops stay linear), equality comparison, formatted number-to-string. `xt_string_length` reports bytes for I/O; `xt_string_utf16_length` reports the JavaScript length.
-- Type conversion: `xt_truthy`, `xt_to_number`, `xt_to_string`, `xt_typeof`.
-- Arithmetic: `add/sub/mul/div/mod/pow/neg/pos`.
-- Bitwise: `and/or/xor/not/shl/shr/ushr` (including `ToInt32` semantics).
-- Comparison: `lt/le/gt/ge`, loose / strict equality, `not`, `is_nullish`.
-- Objects: linear property list, `object_new/get/set/has/keys/values/entries/assign/spread`.
-- Arrays: `array_new/get/set/push/length/spread`; assigning `arr.length` truncates or extends (matching JS); `iter_length` / `iter_value` expose a uniform iteration view over arrays, strings (by code point), `Map` and `Set`.
-- Typed arrays (`xt_typed_array.c`): typed arrays as property-bag objects with one prototype per element kind; element reads return the stored value and writes are coerced to the element type; `from` / `of` statics plus the full prototype method set; `subarray` copies.
-- Symbols (`xt_symbol.c`): `Symbol(description)` primitives (`XT_OBJECT_KIND_SYMBOL`), the 13 well-known symbols (`Symbol.iterator`, `Symbol.asyncIterator`, `Symbol.match`, …), `Symbol.for` / `Symbol.keyFor` global registry, `symbol.description` / `toString()` / `valueOf()`; symbols are valid property keys (`Object.getOwnPropertySymbols`, symbol keyed `get`/`set`/`in`/`delete`), are skipped by `Object.keys` / `values` / `entries` / `for...in` / `JSON.stringify`, and print as `Symbol(desc)`.
-- Generic member access: `xt_get` / `xt_set` (dispatch over arrays / objects / strings).
-- Standard library: `xt_call_method` (uniform dispatch of array / string methods and function properties on objects), `xt_math_call` (`Math.*` and constants), global functions `xt_parse_int/parse_float/is_nan/is_finite/number_ctor/string_ctor/boolean_ctor/fetch`.
-- Operator helpers: `xt_in` (`in`), `xt_delete` (`delete`), `xt_rest_args` (rest parameters / `arguments`).
-- Box: `box_new/get/set` (for closure-captured variables).
-- Functions and closures: `arg`, `closure_new/call/env/arity`.
-- Exceptions: `xt_try_enter` / `xt_try_exception` / `xt_try_leave` maintain the `_setjmp` frame stack; `xt_throw` long-jumps to the nearest `try` when a frame exists, otherwise prints `Uncaught ...` and exits. Codegen also maintains a shadow call stack (function name, source file and line): `Error.stack` captures it, and a fatal-signal handler dumps the same frames on a native crash. `--debug` additionally emits `!DICompileUnit` / `!DISubprogram` / `!DILocation` metadata and compiles with `-g -fno-omit-frame-pointer`, so gdb/lldb/WinDbg map instructions back to source lines.
-- Output: `xt_print/xt_println/xt_console_log/info/warn/error` (Node-style inspect: arrays `[ a, b ]`, objects `{ k: v }`; `info`/`log` to stdout, `warn`/`error` to stderr), plus `dir/trace/assert/count/countReset/group/groupEnd/table/time/timeEnd/timeLog`.
-- Objects / functions: `xt_object` with a prototype chain, `xt_function` with a property bag (static members and `prototype`); `xt_new` (instantiation), `xt_instance_of` (prototype chain), `xt_object_freeze/is_frozen/from_entries`; `xt_constructors.c` holds the first-class constructor cache, constructor prototypes and static-value dispatch.
-- Standard library extensions (`xt_stdlib2.c`): extended array / string / number / object methods; `Object` / `Array` / `Number` / `String` statics; `JSON.parse` / `JSON.stringify`; `Map` / `Set`; `Date` (`gmtime_r`); `RegExp` (POSIX ERE `regcomp`/`regexec` `test`/`exec`).
-- Promise (`xt_promise.c`): microtask queue (`xt_microtasks`); `xt_promise_ctor/resolve/reject/static`, instance `then/catch/finally`; `xt_drain_microtasks` empties the queue at program exit and the event loop drains it between callbacks. `xt_await` (in `xt_async.c`) returns a settled value synchronously, or suspends the running async coroutine and registers a waiter when the promise is pending.
-- Async coroutines (`xt_async.c`) on the shared stackful-coroutine runtime (`xt_coroutine.c`, POSIX `ucontext` / Windows fibers): each `async` call owns a private stack, swaps its `try` frame stack and GC stack region, and survives `await` across `try`/`finally`, loops and closures. A promise settled from a timer, a socket callback or another coroutine resumes the suspended body on the microtask queue.
-- Fetch (`xt_fetch.c`): global `fetch(input, init)` is a blocking HTTP/1.1 client whose promise is already settled (the exchange happens synchronously; it is not scheduled on the reactor). It accepts `http://` URLs only — `https://` rejects with a `TypeError` because no TLS backend is linked — and supports `method`, `headers` (plain object or `Headers`), `body` and `redirect` (`follow` / `manual` / `error`), following up to 20 redirects and switching POST to GET on 301/302/303. The resolved `Response`-shaped object exposes `ok` / `status` / `statusText` / `url` / `headers` plus `text()` / `json()` / `arrayBuffer()` / `bytes()` / `clone()`, and `Headers` is case-insensitive with `get` / `has` / `set` / `append` / `delete` / `keys` / `values` / `entries` / `forEach` / `getSetCookie`. Invalid URLs and network failures reject with a `TypeError`.
-
----
-
-## 9. Extension mechanism (Extensions, implemented)
-
-Location: `src/extensions/registry.ts`, `src/extensions/node/`
-
-- An extension is a plain object: `runtimeSources()` (extra C sources), `linkerFlags()` (extra link flags), `builtins()` (global identifier → runtime symbol, uniform `(argc, argv)` ABI) and `modules()` (import specifier → named exports / namespace).
-- `ExtensionRegistry`: register / unregister / lookup / aggregate builtins, modules, runtime sources and link flags.
-- The built-in core extension `core`: exposes `print` (mapped to `xt_println`), always registered.
-- The Node extension `node`:
-  - Modular organisation: `src/extensions/node/fs/` + `runtime/ext_node/fs/read_file.c`
-  - Exposes importable modules (`fs`, `fs/promises`, `path`, `os`, `process`, …) under both bare and `node:`-prefixed specifiers; `import { readFileSync } from "fs"` resolves to `xt_node_read_text_file`, and `path`/`os`/`process` map exports onto the namespace dispatchers.
-- Adding a new module only requires a new directory plus a C implementation; the core compiler never changes.
-- Native C++/Rust extensions (`src/extensions/native.ts`, `--ext-native`):
-  - `nativeObjects()` links pre-built objects/static archives that expose `extern "C"` symbols with the `(argc, argv)` ABI; a JSON manifest maps them onto builtins/modules (`linkerFlags` / `linkerFlagsByPlatform` cover C++/Rust runtimes).
-  - Authoring helpers live in `runtime/xt_ext.h` (C/C++) and `runtime/xt_ext.rs` (Rust); runnable projects are under `examples/extensions/`.
-  - The driver links the artifacts verbatim and the incremental cache fingerprints their contents, so a rebuilt library invalidates the cached binary.
-  - CI builds both language examples on Linux, macOS and Windows; on Windows the system clang links with the MSVC ABI (C++ `-lmsvcprt`, Rust `*-pc-windows-msvc` plus the Windows system libraries).
-
----
-
-## 10. Driver, incremental compilation and toolchain (implemented)
-
-Location: `src/driver/compiler.ts`, `src/driver/cache.ts`, `src/driver/toolchain.ts`, `src/driver/paths.ts`
-
-- Compilation pipeline: read source → module bundling (`src/driver/modules.ts`, when the entry contains `import`/`export`) → parse → bind/check → IR → object file → link.
-- Incremental cache: keyed on "compiler version + source hash + emit kind + optimization level + platform + extension fingerprint (names, linker flags, native object contents)"; if the artifacts exist and are fresh, the build is skipped.
-- C runtime and extension sources are cached as object files by content hash and compiled only once.
-- Toolchain wrapper: locates `clang` (overridable with `xbintsc_CLANG`), compiles IR, compiles C, links.
-- Link flags: `-lm` is added automatically on non-Windows; extensions may append extra link flags.
-- Project config (`src/driver/config.ts`, `xbintsc.config.json`): `entry`, `outDir`, `output`, `optimize`, `extensions`, `extNative`, `force` and `app` (`name`, `icon`, `bundle`, `bundleId`). Discovered by walking up from the entry/cwd, overridable with `--config`, disabled with `--no-config`; every path resolves against the config directory; CLI flags win over config values.
-- Application icon (`src/driver/icon.ts`, `win-icon.ts`, `mac-bundle.ts`, `--icon`/`app.icon`): PNG/ICO/ICNS is embedded as `xt_app_icon_*` symbols, synthesized into a PE resource via `llvm-rc`/`windres` on Windows, and packaged into `Foo.app` (with `AppIcon.icns` via `sips`/`iconutil`) on macOS. The `gui` extension calls `SDL_SetWindowIcon` from the embedded bytes. `xbintsc_RC` overrides the resource compiler.
-
----
-
-## 11. CLI and programmatic API (implemented)
-
-Location: `src/cli/main.ts`, `src/index.ts`, `bin/xbintsc.js`
-
-### 11.1 CLI commands
-
-```
-xbintsc build <file.ts> [options]   compile to a native binary
-xbintsc run   <file.ts> [-- args]   compile and run
-xbintsc emit  <file.ts>             print LLVM IR
-xbintsc version                     print the version
-xbintsc help                        help
-```
-
-### 11.2 CLI options
+## Contents
 
-```
--o, --output <path>   Output path
-    --out <dir>       Output directory (default: build/)
-    --emit <kind>     exe | obj | ir (default: exe)
--O0..-O3              Optimization level (default: -O2)
-    --ext <names>     Comma separated extensions (e.g. node)
-    --ext-native <m>  Register a C++/Rust extension from a JSON manifest
-    --config <path>   Use a project config (default: xbintsc.config.json)
-    --no-config       Do not read any project config
-    --icon <path>     Embed an application icon (PNG/ICO/ICNS)
-    --bundle          macOS: also produce a .app bundle
-    --app-name <name> Bundle / display name
-    --app-id <id>     macOS bundle identifier (e.g. com.example.demo)
-    --force           Ignore the incremental cache
-    --verbose         Print progress information
-```
+### Pipeline and front end
 
-### 11.3 Programmatic API
+- [Compilation pipeline](./implemented/pipeline.md) — source → tokens → AST → IR → binary, self-hosting
+- [Lexer](./implemented/lexer.md) — tokens, literals, keywords, lexical diagnostics
+- [Parser](./implemented/parser.md) — statements, expressions, type syntax, ASI
+- [Name binding and scopes](./implemented/binder.md) — scopes, symbols, closure capture
 
-```ts
-import { build, compileString } from "xbintsc";
+### Semantics and code generation
 
-const { ir } = compileString("console.log(1 + 1);");
-const result = build("program.ts", { emit: "exe", outDir: "build" });
-```
+- [Operators and assignment](./implemented/operators.md) — arithmetic, comparison, logical, bitwise, assignment
+- [Value model and calling convention](./implemented/value-model.md) — NaN-boxing, function ABI, closures, prototypes
+- [LLVM IR code generation](./implemented/codegen.md) — control flow, expressions, classes, inline caches, entry point
 
----
+### Runtime and standard library
 
-## 12. Tests (implemented)
+- [C runtime core](./implemented/runtime-core.md) — allocator/GC, values, conversions, objects, exceptions
+- [Strings and text](./implemented/strings.md) — UTF-8/UTF-16 model, string methods, text codecs
+- [Standard library](./implemented/stdlib.md) — Object, Array, Number/BigInt/Math, JSON, Date, RegExp, Symbol, errors, console
+- [Collections](./implemented/collections.md) — Map, Set, WeakMap, WeakSet, WeakRef, iteration
+- [Typed arrays and binary data](./implemented/typed-arrays.md) — typed arrays, ArrayBuffer, DataView
+- [Async, promises and generators](./implemented/async.md) — async/await, async generators, promises, timers
+- [fetch](./implemented/fetch.md) — reactor-driven HTTP/1.1 client and Headers
 
-Location: `tests/` (`lexer` / `parser` / `binder` / `codegen` / `driver` / `extensions` / `cli` / `e2e`)
+### Modules and tooling
 
-- Per-module unit tests; when `clang` is present, e2e really compiles and runs binaries, otherwise it is skipped automatically.
-- e2e coverage: arithmetic and printing, recursive functions, loops / arrays / string concatenation, closures capturing by reference, JS-style printing of objects / arrays, the Node `fs` extension via `import`, `switch` fall-through, array / string methods, `Math` and global functions and all `console` levels, default / rest parameters and `arguments`, `Object` helpers and spread and `in`/`delete`, `for...in` object key enumeration, `try/catch/finally`, optional chaining, classes and `new`/`this`/`static`/`extends`/`super`/`instanceof`, `async`/`await` and `Promise`, real await suspension (timers, TCP sockets and `fs/promises` across event-loop turns, rejection and `finally` after resuming), `Map`/`Set`/`JSON` and extended standard library, `for...of` over `Map`/`Set`, array `length` assignment and iterable spread, multi-file `import`/`export` (including `.js` specifiers and plain JavaScript sources), destructuring bindings and assignments (including object rest), built-in `instanceof`, `enum`/`const enum`, regular-expression literals and `new Error(...)`, the `Error` family and `AggregateError`, generators and `Symbol` with custom `Symbol.iterator` iterables, typed arrays (element coercion, `from`/`of`, iteration and the prototype methods), first-class built-in constructors and `Object.prototype` (aliases, statics, `getPrototypeOf`, `hasOwnProperty.call`), and the global `fetch` (HTTP GET/POST, headers, redirects, JSON/text/binary bodies and `TypeError` rejection).
+- [Module system](./implemented/modules.md) — import/export, bundling, `node_modules`, `import.meta`
+- [Extension mechanism](./implemented/extensions.md) — registry, the `node` extension, native C++/Rust extensions
+- [Node extension](./implemented/node.md) — 21 Node built-in modules, one page per module
+- [Driver, incremental compilation and toolchain](./implemented/driver.md) — cache, clang/LTO/PGO, config, icons
+- [CLI and programmatic API](./implemented/cli.md) — commands, flags, embedder API
+- [Tests](./implemented/tests.md) — unit, e2e and the differential harness
 
----
+## Where does a change belong?
 
-## 13. Implemented features quick reference
+Pick the page that owns the feature; that keeps unrelated branches out of the
+same file.
 
-| Category | Contents |
+| You changed... | Edit |
 | --- | --- |
-| Declarations | `var` `let` `const`, function declarations, function expressions, arrow functions, `class` (declaration / expression), `enum` / `const enum`, interfaces / type aliases (erased) |
-| Control flow | `if/else`, `while`, `do...while`, `for`, `for...of`, `for...in`, `switch`, `try/catch/finally`, `break`, `continue`, `return`, `throw` |
-| Expressions | Identifiers, literals, template strings, regular-expression literals, array / object literals (with spread), destructuring bindings and assignments, calls, member / element access, optional chaining, non-null `!`, closures, `arguments`, `this`, `new`, `super`, `await` |
-| Operators | Arithmetic, comparison, equality, logical, bitwise, shift, unary (including `typeof`/`void`), prefix/postfix increment-decrement, compound assignment, logical assignment, `in`, `delete`, `instanceof` |
-| Functions | Default parameters, rest parameters, capturing closures, `this` binding, lexical `this` in arrow functions, `call`/`apply`/`bind`, `name`/`length` |
-| Classes / OO | Constructors, instance fields, methods, `static`, inheritance `extends`/`super`, prototype chain, `instanceof` |
-| Async | `async`/`await` with real stackful-coroutine suspension (a pending promise pauses the body until a timer/socket/coroutine settles it), `Promise` (`then/catch/finally`, `resolve/reject/all/allSettled/race`) |
-| Modules | `import`/`export` (named / default / re-export / `export *` / `export type`), multi-file bundling over relative paths (`.js`-family specifiers resolve to their `.ts` sources, and TypeScript suffixes are preferred over JavaScript siblings when the specifier omits the extension; plain `.js` / `.jsx` / `.mjs` / `.cjs` sources are bundled directly too) and `node_modules` packages (`exports` / `module` / `main`, scoped packages and subpaths), bare specifiers resolved to extension modules; CommonJS packages under `node_modules` are lowered (`require` / `module.exports` / `exports`), while `require()` in user code is rejected with an `import` hint |
-| Standard library | Array / string / number / object extension methods, typed arrays, `Math`, `JSON`, `Date`, `RegExp`, `Map`, `Set`, `Symbol`, `Error` family, `Object/Array/Number/String/Symbol` statics, `console.*` |
-| Value model | 64-bit NaN-boxing, uniform function ABI (including `this`), closure environments, object prototype chains |
-| Runtime | Strings / objects / arrays / typed arrays / closures / arithmetic / comparison / catchable exceptions / Promise / async coroutines / collections / symbols / generators / `fetch` / `console` |
-| Extensions | Extension registry, `core` (print), `node` (fs / path / os / process / buffer / stream / net / dgram / http imported by specifier) |
-| GUI (`gui` extension) | Self-hosted HTML/CSS renderer window (SDL3 + SDL_GPU): DOM/CSS/layout, CSS `transform`/`transform-origin`, `<img>`/SVG, `<video>`/`<audio>`, `<canvas>` 2D, events, transitions (including `transform`) |
-| Toolchain | clang compiles IR/C, linking, incremental cache |
-| Project config | `xbintsc.config.json` (`entry` / `outDir` / `optimize` / `extensions` / `app`), discovery + CLI precedence |
-| Application icon | compile-time embed (PNG/ICO/ICNS), PE resource on Windows, `.app` bundle on macOS, runtime window/Dock icon via `gui` |
-| Self-hosting | `xbintsc` compiles `src/cli/main.ts` to a native binary; the emitted IR is at a fixpoint from generation 1 |
-| Platforms | macOS / Linux / Windows (adapted at the build level, CI in `.github/workflows`) |
+| tokenizer, literals, keywords | [Lexer](./implemented/lexer.md) |
+| statement/expression/type syntax | [Parser](./implemented/parser.md) |
+| scopes, symbols, captures | [Name binding](./implemented/binder.md) |
+| operators, assignment lowering | [Operators](./implemented/operators.md) |
+| value representation, function ABI | [Value model](./implemented/value-model.md) |
+| control flow, expression lowering, classes, `main` | [Codegen](./implemented/codegen.md) |
+| allocator, GC, conversion, exceptions | [Runtime core](./implemented/runtime-core.md) |
+| string model and methods | [Strings](./implemented/strings.md) |
+| Object/Array/Number/Math/JSON/Date/RegExp/Symbol/errors/console | [Standard library](./implemented/stdlib.md) |
+| Map/Set/WeakMap/WeakSet/WeakRef/iteration | [Collections](./implemented/collections.md) |
+| typed arrays, ArrayBuffer, DataView | [Typed arrays](./implemented/typed-arrays.md) |
+| async/await, promises, generators, timers | [Async](./implemented/async.md) |
+| HTTP client | [fetch](./implemented/fetch.md) |
+| import/export and bundling | [Modules](./implemented/modules.md) |
+| extension registry or the `node` extension | [Extensions](./implemented/extensions.md) |
+| a specific Node module (`fs`, `path`, `http`, ...) | [Node extension](./implemented/node.md) |
+| build cache, clang, LTO/PGO, config, icons | [Driver](./implemented/driver.md) |
+| CLI flags or the embedder API | [CLI](./implemented/cli.md) |
+| tests and the differential harness | [Tests](./implemented/tests.md) |