xbintsc 0.3.35 → 0.3.49

package/doc/icon.md

@@ -0,0 +1,265 @@
+# xbintsc application icons (compile-time icon embedding)
+
+> Language: **English** | [简体中文](./zh-CN/icon.md)
+
+Status: **implemented** — milestones I0–I3 below have shipped. I4 (Linux
+desktop integration) and I5 (per-window icon) remain optional follow-ups.
+
+## Goal
+
+Give a compiled program a real OS-level **application / window icon** supplied
+at *compile time* and baked into the artifact, so the binary needs no side-car
+icon file at runtime:
+
+- **Windows** — the icon shows in Explorer, the taskbar and Alt-Tab (PE
+  resource).
+- **macOS** — the icon shows in Finder and the Dock (`.app` bundle with an
+  `.icns`).
+- **Linux** — the running window/taskbar icon is set from the embedded image;
+  desktop integration (`.desktop` + themed PNG) is a follow-up.
+
+The core compiler stays platform-agnostic: the lexer/parser/binder/codegen never
+learn what an icon is. Icon handling is a *driver* concern (like the per-platform
+linker flags that already live there) plus an optional *runtime* concern (the
+`gui` extension).
+
+## UX
+
+```bash
+# CLI — icon is a build option
+xbintsc build app.ts --icon assets/app.png -o app
+xbintsc run   app.ts --icon assets/app.png
+
+# programmatic API
+build("app.ts", { icon: "assets/app.png" });
+```
+
+Icon settings — and the app metadata that comes with them (name, bundle id) —
+are normally declared once in a project build config (`xbintsc.config.json`):
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/xbintsc.config.schema.json",
+  "entry": "src/app.ts",
+  "outDir": "build",
+  "extensions": ["gui"],
+  "app": {
+    "name": "Demo",
+    "icon": "assets/app.png",
+    "bundle": true,
+    "bundleId": "com.example.demo"
+  }
+}
+```
+
+```bash
+xbintsc build                   # reads xbintsc.config.json
+xbintsc build --icon other.png  # a flag overrides the config
+```
+
+```ts
+// GUI apps pick the embedded icon up automatically
+import { createWindow, run } from "gui";
+createWindow({ title: "Demo", width: 800, height: 600 });
+run(); // window/taskbar/Dock icon = the one configured at build time
+```
+
+## Layer 0 — project build config (`xbintsc.config.json`)
+
+Introduced by this feature (there was no project-level compile config before).
+A single checked-in file makes a build reproducible (`xbintsc build` with no
+arguments).
+
+### Schema
+
+Every field is optional:
+
+```json
+{
+  "entry": "src/app.ts",
+  "outDir": "build",
+  "output": "build/Demo",
+  "optimize": "2",
+  "extensions": ["gui", "node"],
+  "extNative": ["native/xbintsc.manifest.json"],
+  "force": false,
+  "app": {
+    "name": "Demo",
+    "icon": "assets/app.png",
+    "bundle": true,
+    "bundleId": "com.example.demo"
+  }
+}
+```
+
+- Strict JSON (`JSON.parse`); unknown keys are ignored.
+- All relative paths resolve against the **config file's directory**, not the
+  cwd.
+- `app.bundle` is macOS-only and controls the `.app` bundle.
+
+### Discovery & precedence
+
+1. `--config <path>` selects a config explicitly; `--no-config` disables it.
+2. Otherwise walk up from the positional entry's directory, then the cwd, until
+   `xbintsc.config.json` is found.
+3. Precedence for every option: **CLI flag > config value > built-in default**.
+4. `xbintsc build` with no positional entry falls back to `entry` in the config;
+   an error is reported if neither is present.
+
+Implemented in `src/driver/config.ts` (`loadProjectConfig`, `parseProjectConfig`,
+`findProjectConfig`, `resolveConfigPaths`, `ProjectConfigError`) and wired into
+`src/cli/main.ts`.
+
+## Layer 1 — embed & package
+
+### `src/driver/icon.ts`
+
+```ts
+export type IconFormat = "png" | "ico" | "icns";
+export interface IconInfo {
+  readonly path: string;
+  readonly format: IconFormat;
+  readonly bytes: Uint8Array;
+  readonly width: number;  // 0 when unknown (e.g. .icns)
+  readonly height: number;
+}
+export function readIcon(path: string): IconInfo;                  // throws IconError
+export function iconSource(icon: IconInfo): string;                // generated C
+export function ensureIconObject(runner, clang, cacheDir, icon): string;
+export function pngToIco(png: Uint8Array, width, height): Uint8Array;
+export function toIcoBytes(icon: IconInfo): Uint8Array;
+```
+
+`readIcon` sniffs the magic bytes (PNG/ICO/ICNS), rejects missing/empty/
+unsupported files with an `IconError`, and reads the intrinsic size where it is
+cheap (PNG IHDR, ICO directory entry).
+
+### Embedded symbols
+
+When an icon is configured — and for every GUI build even without one — the
+driver generates a tiny C file in the cache dir (never in the user's tree),
+compiles it with the existing `compileC`, and appends the object to the `link()`
+input list:
+
+```c
+/* generated, cached by icon content hash */
+const unsigned char      xt_app_icon_data[];   /* raw icon bytes      */
+const unsigned long long xt_app_icon_size;     /* 0 == no icon        */
+const char               xt_app_icon_format[]; /* "png" | "ico" | "icns" */
+const unsigned int       xt_app_icon_width;
+const unsigned int       xt_app_icon_height;
+```
+
+The GUI extension references these symbols **unconditionally**, so the driver
+links an empty icon object (`EMPTY_ICON`) into GUI programs even when no icon is
+configured; `xt_app_icon_size == 0` tells the runtime to skip it. This avoids
+fragile weak-symbol tricks (Mach-O `weak` does not resolve to null the way ELF
+does).
+
+### CLI & API wiring
+
+- `src/cli/main.ts`: `--icon`, `--bundle`, `--app-name`, `--app-id`, `--config`,
+  `--no-config`; merged with the config (`mergeAppConfig`).
+- `src/driver/compiler.ts`: `BuildOptions.icon` and `BuildOptions.app`.
+  - The icon **content hash** and the packaging options are part of the
+    executable `cacheKey`, so changing the icon rebuilds.
+  - The icon object and (on win32) the resource object are appended to the link
+    inputs.
+  - The macOS `.app` bundle is produced after linking; `BuildResult.bundlePath`
+    reports it (the executable path is unchanged, so `run` still works).
+
+### Per-platform packaging
+
+#### Windows (PE resource) — `src/driver/win-icon.ts`
+
+1. A PNG input is wrapped in a minimal ICO container (`ICONDIR` +
+   `ICONDIRENTRY` pointing at the PNG payload); Vista+ accepts PNG-in-ICO.
+2. A `.rc` (`1 ICON "icon-<hash>.ico"`) is written next to it in the cache.
+3. `llvm-rc /fo app.res app.rc` (preferred, next to the resolved clang or on
+   `PATH`), else MinGW `windres app.rc -O coff -o app_res.o`. Override with
+   `xbintsc_RC`.
+4. If no resource compiler exists, the build continues with the runtime icon only
+   (a cosmetic feature never hard-fails a build).
+
+#### macOS (`MyApp.app` bundle) — `src/driver/mac-bundle.ts`
+
+```
+MyApp.app/Contents/
+  Info.plist            CFBundleName/Identifier/Executable/IconFile
+  MacOS/MyApp           copy of the linked executable
+  Resources/AppIcon.icns
+```
+
+- `.icns` inputs are copied; `.png` inputs are converted with `sips` +
+  `iconutil`. If those tools are unavailable the PNG is shipped as
+  `AppIcon.png` and the runtime Dock icon still applies.
+- `bundleId` supplies `CFBundleIdentifier`; the default is
+  `com.xbintsc.<binary>`.
+- Bundling is opt-in (`app.bundle` / `--bundle`) because it changes the output
+  layout.
+
+#### Linux
+
+ELF has no icon convention. The only in-binary use is the runtime window icon
+(via the embedded bytes). A follow-up may synthesize a `<name>.desktop` +
+`hicolor` PNG and set `SDL_SetAppMetadata`/app-id hints for Wayland.
+
+### Format policy
+
+- **PNG is canonical** and works everywhere.
+- `.ico` (Windows) and `.icns` (macOS) are accepted; `.ico` is best-effort as a
+  PE resource, `.icns` is copied into the mac bundle verbatim.
+
+## Layer 2 — runtime window/Dock icon (`gui`)
+
+`runtime/ext_gui/gui.cpp` defines `xt_gui_apply_icon(SDL_Window *)`, called from
+`xt_gui_create_window` after the window is created:
+
+- Reads `xt_app_icon_{data,size,format}`; skips when `size == 0`.
+- Decodes PNG bytes with the existing `xtgui::xt_image_decode` (stb_image).
+- Builds an `SDL_Surface` (`SDL_CreateSurfaceFrom(..., SDL_PIXELFORMAT_RGBA32,
+  pitch)`) and calls `SDL_SetWindowIcon`.
+- Any failure is silent: an icon is cosmetic and must never stop the program.
+
+## Caching
+
+- The executable cache key includes the icon bytes hash, format, app name,
+  bundle flag and bundle id.
+- The generated C object is cached on the icon content hash.
+- The Windows `.res`/COFF object is cached on the icon+compiler hash.
+- The `.app` bundle is part of the cached outputs, so a stale bundle is never
+  reused.
+
+## Testing
+
+- `tests/driver/config.test.ts` — parse/validate, discovery, path resolution.
+- `tests/driver/icon.test.ts` — format sniffing, generated C, ICO conversion,
+  icon object caching, `llvm-rc`/`windres` command lines, mac bundle layout and
+  fallbacks, and `build()` integration (icon objects linked, missing icon ⇒
+  `DiagnosticCode.IOError`).
+- `tests/e2e/icon.test.ts` — compiles a real GUI program with `app.icon`,
+  asserts the PNG bytes are present in the executable, runs it headless, and
+  (darwin) checks the `.app` bundle + `.icns`.
+- The CLI suites cover `--config`/`--no-config`/`--icon`.
+
+## Milestones
+
+0. **I0 — project build config** ✅ (`src/driver/config.ts`, CLI wiring, tests).
+1. **I1 — embedded icon + runtime window icon** ✅ (`--icon`,
+   `src/driver/icon.ts`, `xt_app_icon_*`, `SDL_SetWindowIcon`, cache key).
+2. **I2 — Windows PE resource** ✅ (`src/driver/win-icon.ts`).
+3. **I3 — macOS `.app` bundle** ✅ (`src/driver/mac-bundle.ts`).
+4. **I4 — Linux desktop integration** (optional).
+5. **I5 — per-window / per-asset icon** (optional).
+
+## Decisions
+
+- **OQ-1 UX** — icon lives in the project build config (`app.icon`) with a
+  `--icon` override. *Done.*
+- **OQ-2 macOS bundling** — explicit `--bundle` / `app.bundle`. *Done.*
+- **OQ-3 formats** — PNG required; ICO/ICNS best-effort. *Done.*
+- **OQ-4 non-GUI apps** — supported everywhere (it is just a resource). *Done.*
+- **OQ-5 default icon** — none; opt-in. *Done.*
+- **OQ-6 config format/name** — `xbintsc.config.json`, strict JSON (`$schema`
+  allowed but ignored). *Done.*
+- **OQ-7 config scope** — single `entry` for now. *Done.*

package/doc/implemented.md

@@ -0,0 +1,373 @@
+# 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
+**actually usable today**. Implementation locations are noted for traceability.
+
+> 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).
+
+> 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).
+
+---
+
+## 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
+  - 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`: wrapped with `xt_promise_resolve` before returning; `await` calls `xt_await` (drives the microtask queue and raises an exception 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, and runs `xt_drain_microtasks` before returning).
+- 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_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, concatenation, equality comparison, formatted number-to-string.
+- 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, `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.
+- 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`.
+- 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`): synchronous microtask queue (`xt_microtasks`); `xt_promise_ctor/resolve/reject/static`, instance `then/catch/finally`; `xt_await` drives the queue until settle, and rejection raises via `xt_throw`; `xt_drain_microtasks` empties the queue at program exit.
+- Fetch (`xt_fetch.c`): global `fetch(input, init)` is a blocking HTTP/1.1 client whose promise is already settled (the runtime has no event loop). 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
+
+```
+-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
+```
+
+### 11.3 Programmatic API
+
+```ts
+import { build, compileString } from "xbintsc";
+
+const { ir } = compileString("console.log(1 + 1);");
+const result = build("program.ts", { emit: "exe", outDir: "build" });
+```
+
+---
+
+## 12. Tests (implemented)
+
+Location: `tests/` (`lexer` / `parser` / `binder` / `codegen` / `driver` / `extensions` / `cli` / `e2e`)
+
+- 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`, `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, `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), and the global `fetch` (HTTP GET/POST, headers, redirects, JSON/text/binary bodies and `TypeError` rejection).
+
+---
+
+## 13. Implemented features quick reference
+
+| Category | Contents |
+| --- | --- |
+| 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`, `Promise` (`then/catch/finally`, `resolve/reject/all/allSettled/race`), synchronous microtask queue |
+| 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 / collections / symbols / generators / `fetch` / `console` |
+| Extensions | Extension registry, `core` (print), `node` (fs / path / os / process / buffer / stream / net / dgram / http imported by specifier) |
+| 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`) |