xbintsc 0.3.46 → 0.3.49

package/doc/ai/cli.md

@@ -0,0 +1,142 @@
+# CLI and configuration reference
+
+The authoritative `--help` text is the `HELP` constant in
+[../../src/cli/main.ts](../../src/cli/main.ts). This page adds the semantics that
+the help text leaves implicit.
+
+## Commands
+
+| Command | Purpose | Needs clang? |
+| --- | --- | --- |
+| `xbintsc build <file.ts>` | Compile to `exe` (default), `obj` or `ir` | yes, except `--emit ir` |
+| `xbintsc run <file.ts> [-- args]` | Compile to an executable and execute it | yes (`--emit exe` only) |
+| `xbintsc emit <file.ts>` | Print LLVM IR to stdout, write nothing | no |
+| `xbintsc doctor` | Report the resolved toolchain, runtime and icon tools | only for the probe |
+| `xbintsc version` | Print the version | no |
+| `xbintsc help` | Print the help text | no |
+
+Any command also accepts `--help`, which prints the help text and exits 0. An
+unknown command prints an error plus the help text and exits 1.
+
+## Options
+
+```
+-o, --output <path>   Explicit output path (overrides --out and the config)
+    --out <dir>       Output directory (default: build/)
+    --emit <kind>     exe | obj | ir (default: exe)
+-O0 .. -O3            Optimization level passed to clang (default: -O2)
+    --ext <names>     Enable bundled extensions, comma separated (e.g. node,gui)
+    --ext-native <m>  Register a C++/Rust extension from a JSON manifest
+                      (comma separated for several)
+    --config <path>   Use this project config instead of discovering one
+    --no-config       Do not read any project config
+    --icon <path>     Embed an application icon (PNG/ICO/ICNS)
+    --bundle          macOS: also produce a <name>.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
+```
+
+Parsing details that occasionally surprise:
+
+- `--flag=value` and `--flag value` are both accepted.
+- `-O`, `-O1`, `-O2`, `-O3` all work; a bare `-O` means `-O2`.
+- `--` ends option parsing: everything after it belongs to the program under
+  `run`, or is a positional for the other commands.
+- `-o` consumes the next argument unconditionally; the other value flags leave
+  the value unset when the next argument starts with `-`.
+
+## Project config
+
+`xbintsc.config.json` is discovered by walking **up** from the entry file's
+directory (or from the current directory when no entry was given). Every path in
+the file resolves relative to the config file, and any CLI flag overrides the
+matching field. `--no-config` skips discovery entirely.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `entry` | string | Entry TypeScript file, so `xbintsc build` needs no positional |
+| `outDir` | string | Output directory (default `build/`) |
+| `output` | string | Explicit output path, overriding `outDir` |
+| `optimize` | `"0"｜"1"｜"2"｜"3"` | Optimization level |
+| `extensions` | string[] | Bundled extensions to enable, e.g. `["node"]` |
+| `extNative` | string[] | Native extension manifest paths |
+| `force` | boolean | Ignore the incremental cache |
+| `app.name` / `app.icon` / `app.bundle` / `app.bundleId` | | Application metadata ([icon.md](../icon.md)) |
+
+JSON schema: [xbintsc.config.schema.json](../xbintsc.config.schema.json). An
+unreadable or malformed config fails the build with `invalid JSON` or
+`Unable to read` rather than silently falling back to defaults.
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `xbintsc_CLANG` | Use this clang instead of resolving one from `PATH` |
+| `xbintsc_LINKER_ARGS` | Extra linker flags (e.g. `-fuse-ld=lld`) |
+| `xbintsc_CACHE_DIR` | Object-cache directory (default: `.xbintsc`) |
+| `xbintsc_PREFER_PREBUILT` | `0` forces the runtime to be compiled from source |
+| `xbintsc_BINARY` | Native compiler binary the `bin/` launcher should run |
+
+## Incremental compilation
+
+Each build is keyed on the entry source hash, the compiler version, the build
+options, the platform and the active extension set
+([../../src/driver/cache.ts](../../src/driver/cache.ts)). If every recorded
+output still exists, the build returns immediately and prints `(cached)`. The C
+runtime and extension sources are cached the same way; objects live in
+`.xbintsc/` (or `xbintsc_CACHE_DIR`).
+
+`--force` (or `force: true`) bypasses the freshness check. If a build ever
+returns stale output, that key is the first thing to inspect — and note that the
+object cache key deliberately excludes compiler flags, which is why the runtime
+coverage script uses a separate cache directory.
+
+## Exit codes
+
+- `0` — success (for `run`: the program exited 0).
+- `1` — diagnostics, a usage error, or a failure in the compiler itself.
+- `run` otherwise propagates the program's own exit status.
+
+## Diagnostics
+
+Errors are rendered as `file:line:col - error TS<code>: <message>` with a source
+excerpt and caret underline. Codes are grouped by stage
+([../../src/diagnostics/diagnostic.ts](../../src/diagnostics/diagnostic.ts)):
+
+| Range | Stage |
+| --- | --- |
+| TS1xxx | lexer |
+| TS2xxx | parser |
+| TS3xxx | binder |
+| TS4xxx | checker (`TS4005` is the `UnsupportedFeature` code) |
+| TS5xxx | codegen |
+| TS6xxx | driver: `TS6001` module not found, `TS6002` IO, `TS6003` toolchain, `TS6004` cache |
+
+The CLI appends a `hint:` line pointing at the relevant document (for example
+[language-support.md](./language-support.md) for `TS4005`, or
+[troubleshooting.md](./troubleshooting.md) for `TS6001`/`TS6003`). Toolchain and
+IO failures throw instead of producing a diagnostic, so the CLI reports those as
+`xbintsc: <message>` plus the same style of hint.
+
+## Programmatic API
+
+```ts
+import { build, compileString } from "xbintsc";
+```
+
+- `compileString(source, fileName?, extensions?)` → `{ ir, diagnostics }`.
+  Pure IR generation: no filesystem, no clang.
+- `build(entryPath, options?)` → `BuildResult`. `options` accepts `output`,
+  `outDir`, `emit`, `optimize`, `force`, `verbose`, `extensions` (a registry),
+  `app`, `clang`, `preferPrebuilt`.
+- `canonicalize` of results: `{ outputPath, irPath?, cached, diagnostics, ir?,
+  bundlePath? }`.
+
+`build` reports source-level problems through `diagnostics` — always check
+`diagnostics.some((d) => d.category === "error")` before using the artifact — but
+**throws** `ToolchainError` when clang itself fails
+([../../src/driver/toolchain.ts](../../src/driver/toolchain.ts)). The
+`xbintsc/driver` subpath additionally exports the cache, toolchain resolution,
+config loader, icon and macOS-bundle helpers.

package/doc/ai/contributing.md

@@ -0,0 +1,196 @@
+# Contributing to the compiler
+
+Use this page after [../AGENTS.md](../../AGENTS.md), which covers the layout, the
+build gate and the rules. This one covers the workflow details that are easy to
+get wrong.
+
+## Set up
+
+```bash
+npm install
+npm run typecheck        # tsc --noEmit
+npm run lint             # eslint + the 600-line file budget
+npm test                 # unit + end-to-end
+```
+
+Node.js ≥ 22 is required to run the compiler from source, and a **clang 16+**
+toolchain is required for anything that links a binary (see
+[troubleshooting.md](./troubleshooting.md)). `xbintsc emit` needs neither clang
+nor the runtime library, which makes it the fastest inner loop.
+
+Optional but recommended — install the repository hook:
+
+```bash
+git config core.hooksPath .githooks
+```
+
+`.githooks/pre-commit` **bumps the patch version on every commit** and folds
+`package.json` + `package-lock.json` into that commit (`npm version patch
+--no-git-tag-version`). Expect a version bump in your commits; do not countermand
+it. Release tags are created by `release.yml`, never by the hook.
+
+## The test suites
+
+| Command | Scope |
+| --- | --- |
+| `npm test` | everything: per-module unit tests plus `tests/e2e` |
+| `npm run test:e2e` | only the compile-and-run tests |
+| `npm run test:watch` | vitest in watch mode |
+| `npm run coverage` | V8 coverage of the TypeScript compiler (`src/`) |
+| `npm run coverage:runtime` | LLVM coverage of the C runtime (`runtime/`) |
+
+Unit tests live one directory per module under `tests/` (`lexer`, `parser`,
+`binder`, `codegen`, `driver`, `extensions`, `cli`, `e2e`) and mirror the source
+tree. Edge-case tests belong next to the module they cover.
+
+`tests/e2e/` compiles real programs and runs the resulting binaries, including a
+**differential harness** (`tests/e2e/differential-*.test.ts`) that executes the
+same source through both xbintsc and Node and compares output byte-for-byte. That
+harness is the strongest tool in the repository: when you touch semantics, add a
+case there rather than asserting a hand-written expected string. Tests that need
+clang skip themselves when it is unavailable (`hasClang()` in
+[tests/helpers.ts](../../tests/helpers.ts)) — do not turn that into a silent
+pass.
+
+## Two invariants you must not break
+
+### 1. The self-hosting fixpoint
+
+CI (`self-host` job in [.github/workflows/ci.yml](../../.github/workflows/ci.yml))
+compiles the compiler with itself and requires the emitted IR to be identical
+across generations:
+
+```
+source --emit--> ref.ll
+source --build--> gen1 binary
+gen1 --emit--> gen2.ll      # must equal ref.ll
+gen1 --build--> gen2 binary
+gen2 --emit--> gen3.ll      # must equal ref.ll
+```
+
+By consequence: **any change that alters emitted IR must still be reproducible by
+the compiler being changed**, and the IR must be byte-for-byte deterministic —
+iteration order, generated symbol names and numbering included. Never introduce
+nondeterminism (a `Map`/`Set` iteration over insertion-ordered data you did not
+control, a timestamp, a filesystem-order dependency) into codegen.
+
+A second consequence is the string model: the compiler's own source text has to
+mean the same thing in every generation. A compiled string is UTF-8 bytes, so the
+self-hosted `readFileSync` (`--ext node`) hands the scanner the bytes of a file,
+while Node hands it the same file already decoded — read source files through
+`decodeUtf8` ([src/diagnostics/utf8.ts](../../src/diagnostics/utf8.ts)) and never
+assume a code unit is a byte or a character. Getting this wrong shows up as a
+non-ASCII literal (`—` in a hint string) coming out re-encoded in `gen2.ll`, which
+is why the emitted IR is compared byte-for-byte rather than line-by-line.
+
+Verify locally:
+
+```bash
+npx tsx src/cli/main.ts emit src/cli/main.ts --ext node > scratch/ref.ll
+npx tsx src/cli/main.ts build src/cli/main.ts --ext node --out scratch/self --force
+./scratch/self/main emit src/cli/main.ts --ext node > scratch/gen2.ll   # .exe on Windows
+diff scratch/ref.ll scratch/gen2.ll
+```
+
+### 2. The runtime ABI and value model
+
+- Every compiled function uses
+  `xt_value fn(xt_value env, int32_t argc, xt_value *argv)` — direct calls and
+  closure calls share this one path, and `env` threads captured variables
+  through boxes.
+- Every value is a single 64-bit word: doubles unboxed, everything else a tagged
+  pointer (16-bit tag + 48-bit payload). The representation is defined **once**
+  in [../../src/codegen/values.ts](../../src/codegen/values.ts) and
+  [../../runtime/rt.h](../../runtime/rt.h); change both together or not at all.
+- Awkward JS semantics (`+` coercion, relational comparison, property access,
+  inspection) are delegated to `@xt_*` runtime calls rather than inlined.
+- The GC is a non-moving mark-sweep collector: new heap objects go through
+  `xt_alloc`, and a value must be reachable from an explicit root slot, a
+  registered root provider (the event loop, the microtask queue) or the
+  conservative C-stack scan while it is live. A value held only in a C local that
+  is not on the scanned stack is a bug.
+
+## Changing the runtime
+
+`runtime/` is C, split by function across translation units (`xt_alloc.c`,
+`xt_values.c`, `xt_containers.c`, `xt_stdlib.c`, …) sharing
+`runtime/rt_internal.h`. The runtime must be rebuilt for C changes to take
+effect:
+
+```bash
+npm run runtime            # tsx scripts/build-runtime.ts -> runtime/lib/<os>-<arch>/
+npm run runtime:clean      # drop build/runtime-obj and runtime/lib
+```
+
+Add a new C file only together with the place that lists the runtime sources
+(`RUNTIME_SOURCES` in [../../src/driver/compiler.ts](../../src/driver/compiler.ts)),
+because that list decides what gets compiled and linked. Extension C sources are
+declared by the extension itself.
+
+## Adding or extending an extension
+
+An extension is a plain object ([../../src/extensions/registry.ts](../../src/extensions/registry.ts))
+contributing `runtimeSources()`, `modules()` / `builtins()`, and optionally
+`nativeObjects()` or `assetLoaders()`. The Node extension is one folder per
+module, pairing its TypeScript exports with the C sources that implement them:
+
+```
+src/extensions/node/fs/index.ts        runtime/ext_node/fs/read_file.c
+```
+
+Adding a Node module therefore means dropping a folder in each place and
+registering it in the module list; the core compiler never changes. If your
+feature is optional or platform-specific, it belongs in an extension rather than
+in `src/codegen`. Bundled extensions are listed in
+[../../src/extensions/catalog.ts](../../src/extensions/catalog.ts) — an extension
+listed there but not enabled produces the actionable `pass --ext <name>` hint, so
+add modules to the list even when the feature is off by default.
+
+Extension authoring from C++/Rust without touching the compiler is documented in
+[../../examples/extensions/README.md](../../examples/extensions/README.md).
+
+## Adding a diagnostic
+
+1. Add a stable code to the enum grouped by pipeline stage in
+   [../../src/diagnostics/diagnostic.ts](../../src/diagnostics/diagnostic.ts)
+   (1xxx lexer, 2xxx parser, 3xxx binder, 4xxx checker, 5xxx codegen, 6xxx
+   driver). Codes are a public interface — never renumber one.
+2. Emit it with the most specific range you have; `formatDiagnostic` renders the
+   file, line, column, excerpt and caret from it.
+3. Make the message actionable, in the style of the existing ones: say what is
+   wrong *and* what to do (`pass --ext node`, `use an ESM import`, …). If a
+   reader needs more, the CLI hint layer maps codes to a document — extend that
+   map in [../../src/cli/main.ts](../../src/cli/main.ts) when you add a code.
+4. Cover it in `tests/diagnostics` or the module's own test.
+
+## Documentation is part of the change
+
+A feature is not done until the docs match:
+
+| Document | Update when |
+| --- | --- |
+| [../implemented.md](../implemented.md) | a feature starts working |
+| [../unimplemented.md](../unimplemented.md) | a limitation appears or is lifted |
+| [../node-implemented.md](../node-implemented.md) / [../node-unimplemented.md](../node-unimplemented.md) | Node module coverage changes |
+| [language-support.md](./language-support.md) | the AI-facing summary of the above changes |
+| [../requirements.md](../requirements.md) | the toolchain or platform requirements change |
+| [cli.md](./cli.md) | a flag, config field or environment variable changes |
+
+Keep the Chinese translation (`doc/zh-CN/`, `doc/ai/zh-CN/`) in step with the
+English source; a half-translated page is worse than none because it silently
+goes stale.
+
+## Repository hygiene
+
+- **600 lines per code file**, enforced by ESLint (`max-lines`) for TS/JS and by
+  [scripts/check-file-length.ts](../../scripts/check-file-length.ts) for C, C++,
+  Rust, `.inc` and shell files. Split by responsibility instead of growing a
+  file; vendored sources are exempt.
+- **No `any`**; `prefer-const` and `eqeqeq` are errors. The
+  declaration-merging pattern in the parser/generator is deliberately allowed.
+- **Public API changes** go through [../../src/index.ts](../../src/index.ts) and
+  must keep the `xbintsc` / `xbintsc/driver` export maps in
+  [../../package.json](../../package.json) valid.
+- `npm run package-release` assembles the per-platform archives into
+  `dist/release/`; the release workflow owns tagging, so never push a tag by
+  hand.

package/doc/ai/extensions.md

@@ -0,0 +1,148 @@
+# Extensions: Node modules, GUI, C++/Rust libraries
+
+The compiler core is platform-agnostic. Anything platform-specific — Node's
+`fs`, an HTML/CSS renderer, your own C++ library — arrives as an **extension**
+that contributes module bindings plus the C/C++ sources or objects to link.
+
+## The rule that trips people up
+
+**An import of an extension-provided module fails until the extension is
+enabled.** xbintsc knows the module exists and says exactly what to pass:
+
+```bash
+$ xbintsc run app.ts            # app.ts: import { readFileSync } from "fs";
+error TS6001: module 'fs' is provided by the 'node' extension; pass --ext node
+```
+
+```bash
+xbintsc run app.ts --ext node
+```
+
+Enable several at once with a comma-separated list: `--ext node,gui`. In a
+project, put them in `xbintsc.config.json` so no flag is needed:
+
+```json
+{ "entry": "src/app.ts", "outDir": "build", "extensions": ["node"] }
+```
+
+## Bundled extensions
+
+### `node` — Node built-in modules
+
+Enable with `--ext node`. A module is importable by its bare name or the
+`node:` prefix (`import { readFileSync } from "node:fs"`), and both spellings
+resolve to the same implementation.
+
+| Module | Notes |
+| --- | --- |
+| `fs` | **synchronous API only** (`readFileSync`, `writeFileSync`, …); `fs/promises` is separate |
+| `fs/promises` | promise-based file APIs |
+| `path` | also hooks namespace dispatch, so `path.join(...)` works |
+| `os` | |
+| `process` | `process.cwd()`, `argv`, `env`, …; namespace dispatch too |
+| `buffer` | |
+| `crypto` | |
+| `stream`, `stream/promises` | |
+| `events` | |
+| `net`, `dgram`, `http` | sockets and servers on the xbintsc event loop (see the async caveat below) |
+| `child_process` | |
+| `worker_threads` | |
+| `util`, `querystring`, `url`, `assert`, `test`, `zlib` | |
+
+Coverage per module (exact functions and options) is in
+[../node-implemented.md](../node-implemented.md); what is missing is in
+[../node-unimplemented.md](../node-unimplemented.md).
+
+Remember the runtime model before building on `net`/`http`: the event loop runs
+**after** the program body, and `async`/`await` is a synchronous microtask
+model. See [language-support.md](./language-support.md).
+
+### `gui` — HTML/CSS window
+
+Enable with `--ext gui` and import the `gui` module:
+
+```ts
+import { createWindow, run } from "gui";
+```
+
+It is a self-contained GPU-accelerated renderer (own HTML parser, CSS cascade,
+layout and compositor) — not a system WebView. It ships as a per-platform
+prebuilt `gui.a`/`gui.lib` because it is C++. If that archive is missing for
+your platform, the build fails with an actionable message; design and roadmap
+live in [../gui.md](../gui.md), and the scripting surface in
+[../gui-scripts.md](../gui-scripts.md).
+
+## Third-party npm packages
+
+Bare specifiers that no enabled extension claims are looked up in `node_modules`
+and bundled **as source**. A package that is not plain ESM TypeScript/JavaScript
+— or that relies on CommonJS, `require`, `__dirname`, or circular dependencies —
+will not work. `require()` is rejected with a hint to convert to `import`.
+
+Practical consequence: for a Node program, enabling `--ext node` is usually the
+right answer; reach for an npm dependency only when you must.
+
+## Native extensions (C++ / Rust, no compiler changes)
+
+Any code that exposes `extern "C"` entry points with the runtime ABI can be
+linked in:
+
+```c
+xt_value my_fn(int32_t argc, xt_value *argv);
+```
+
+Build it with an **external** toolchain (clang++ or cargo), describe the
+artifacts in a JSON manifest, and pass the manifest:
+
+```bash
+xbintsc build demo.ts --ext-native ./xbintsc.manifest.json
+xbintsc build demo.ts --ext-native a.json,b.json      # several
+```
+
+```jsonc
+{
+  "name": "mathx-cpp",                       // required, unique
+  "objects": ["build/mathx.o"],              // .o / .a / .lib, relative to this file
+  "linkerFlagsByPlatform": {                 // C++/Rust runtimes
+    "linux":  ["-lstdc++", "-lm"],
+    "darwin": ["-lc++"],
+    "win32":  ["-lmsvcprt"]
+  },
+  "builtins": { "cppClamp": { "symbol": "mathx_clamp" } },   // no import needed
+  "modules": {
+    "mathx": { "exports": { "add": { "symbol": "mathx_add" } } }
+  }
+}
+```
+
+`import { add } from "mathx"` then lowers to the native symbol exactly like a C
+runtime binding; `builtins` are globally callable without importing.
+
+Authoring helpers: `runtime/xt_ext.h` (C/C++) and `runtime/xt_ext.rs` (Rust) —
+they wrap the argument and value helpers. Key ABI facts: values are 64-bit
+NaN-boxed words; strings are **not** NUL-terminated, so pair `xt_string_data`
+with `xt_string_length_value`; the runtime never moves or frees memory it handed
+out. Build with the same clang/ABI that xbintsc resolves (`xbintsc doctor`
+prints it), and on Windows build inside an **x64/ARM64 Native Tools Command
+Prompt**.
+
+Working projects to copy: [`examples/extensions/cpp`](../../examples/extensions/cpp)
+and [`examples/extensions/rust`](../../examples/extensions/rust); the full guide
+is [../../examples/extensions/README.md](../../examples/extensions/README.md).
+
+## Programmatic registration
+
+```ts
+import { build, createDefaultRegistry, nativeExtensionFromManifest, nodeExtension } from "xbintsc";
+
+const extensions = createDefaultRegistry()
+  .register(nodeExtension)
+  .register(nativeExtensionFromManifest("./xbintsc.manifest.json"));
+
+build("demo.ts", { extensions });
+```
+
+The registry is also how a host tool hints at a disabled extension, which is what
+produces the "pass `--ext node`" message instead of a confusing downstream error
+([../../src/extensions/catalog.ts](../../src/extensions/catalog.ts)). The list of
+bundled extensions is `bundledExtensions()`.

package/doc/ai/language-support.md

@@ -0,0 +1,152 @@
+# Language support: what compiles, what behaves differently
+
+xbintsc compiles a **practical subset** of TypeScript. Use this page to decide
+what you can write; follow the links for exact wording.
+
+Canonical detail (always current, much longer):
+
+- [../implemented.md](../implemented.md) — everything that works, by compiler stage
+- [../unimplemented.md](../unimplemented.md) — unsupported syntax, deviations, quick reference
+- [../node-implemented.md](../node-implemented.md) / [../node-unimplemented.md](../node-unimplemented.md) — the Node extension
+
+> Chinese: [../zh-CN/implemented.md](../zh-CN/implemented.md), [../zh-CN/unimplemented.md](../zh-CN/unimplemented.md)
+
+## Legend
+
+| Mark | Meaning |
+| --- | --- |
+| ✅ | Works as in Node/TypeScript |
+| ⚠️ | Works but deviates from the standard |
+| 🚫 | Rejected — parse error or `UnsupportedFeature` |
+| — | Parsed and erased, with no runtime effect |
+
+## Statements and declarations
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| `var` / `let` / `const`, blocks, `if`, `for`, `for...of`, `for...in`, `while`, `do...while` | ✅ | `for...in` enumerates own keys only (no prototype chain) |
+| `switch`, `break`, `continue`, labels | ✅ | labeled `break`/`continue` included |
+| `try` / `catch` / `finally`, `throw` | ✅ | `finally` runs on early `return`/`break`/`continue` |
+| `function`, arrow functions, default/rest parameters | ✅ | |
+| `return`, `throw` as expressions' operands | ✅ | |
+| `namespace` / `module` declaration | 🚫 | parse ✓, codegen ✗ |
+| `with`, `debugger` | 🚫 | not supported |
+| Top-level `await` | 🚫 | wrap it in an `async` function |
+
+## Expressions and operators
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| Arithmetic, bitwise, logical, comparison, assignment operators | ✅ | ES `ToPrimitive` / `+` coercion match Node |
+| `===` / `!==` / `==` / `!=` | ✅ | loose equality matches Node |
+| Optional chaining `?.`, nullish `??`, logical assignment `??=` | ✅ | whole-chain short-circuit implemented |
+| Template literals, tagged templates | ✅ | tagged templates have `raw` + `String.raw` |
+| Spread / rest in calls, arrays and object literals | ✅ | |
+| Destructuring (bindings, parameters, nested) | ✅ | defaults + rest supported |
+| `delete`, `in`, `instanceof`, `typeof` | ✅ | |
+| Comma operator, `void` | ✅ | |
+| `new.target` | 🚫 | not implemented |
+| `import.meta` | 🚫 | parsed but has no value |
+| `super` | ⚠️ | single-level inheritance correct; depth > 1 may be inaccurate |
+
+## Functions, classes, objects
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| Closures (capture by reference through boxes) | ✅ | one ABI for direct and closure calls |
+| `this`, method calls, arrow lexical `this` | ✅ | arrow functions get their own `arguments`, unlike JS |
+| `call` / `apply` / `bind`, `fn.name` / `fn.length` | ✅ | a bound closure does not track partial-argument `length` |
+| First-class built-in methods (`arr.map` as a value) | ✅ | exposed as *unbound* method values; a detached call throws like JS |
+| `fn.toString()` | ⚠️ | returns `function name() { [native code] }`, not the source text |
+| Classes: fields, methods, statics, getters/setters, `extends`/`super`, `instanceof` | ✅ | |
+| Constructor parameter properties `constructor(public x: T)` | ✅ | |
+| `#private` fields / methods / statics | ⚠️ | stored under a literal `#x` key; no access enforcement; parent/child name collisions may alias |
+| `enum` / `const enum` | ✅ | forward + reverse mapping |
+| `private` / `protected` / `public` / `readonly` / `abstract` / `implements` | — | erased, no access control |
+| Generators `function*`, `yield`, `yield*` | ✅ | `async` generators are not supported |
+| `arguments` object | ✅ | implicit; arrows see their own parameters |
+| Argument-count validation | 🚫 | never checked, though `fn.length` reports declared arity |
+
+## Async, Promises, event loop
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| `async` / `await`, `Promise`, `Promise.all` | ⚠️ | **synchronous microtask model** — `await` on a settled promise continues synchronously |
+| `setTimeout` and callbacks | ⚠️ | the event loop runs **after** the program body, so a promise settled from a timer cannot be awaited |
+| Sockets / servers (`http`, `net`, `dgram`) | ⚠️ | same model: callbacks run on the event loop after the program body |
+| A real async event loop, worker threads | 🚫 | not implemented |
+
+## Types: parsed, then erased
+
+**No type checking happens.** Type syntax is parsed into the AST and erased
+during binding/codegen:
+
+| Construct | Status |
+| --- | --- |
+| Type annotations, return types, type aliases, interfaces | — parsed, erased, never checked |
+| Generic type parameters and constraints | — no runtime instantiation |
+| `as`, `satisfies`, non-null `!` | — erased, no assertion semantics |
+| Optional-chaining type narrowing | 🚫 |
+| Diagnostics `TS4001`–`TS4004` (`TypeMismatch`, `NotCallable`, `PropertyNotFound`, `ArgumentCountMismatch`) | 🚫 defined but never emitted |
+
+A type error in your source is therefore not a compile error — only runtime
+behaviour is checked. Write the runtime code you mean.
+
+## Standard library
+
+Implemented: `Math`, `JSON`, `Date`, `RegExp`, `Map`, `Set`, `WeakMap`/`WeakSet`,
+`Symbol`, `Error` family, `BigInt`, `Array`/`String`/`Number`/`Object` methods,
+typed arrays, `String.prototype.match`/`split`/`replace` with capture groups,
+immutable array helpers (`toReversed`, `toSorted`, `toSpliced`, `with`), global
+URI functions.
+
+| Missing or different | Status |
+| --- | --- |
+| `String.prototype.normalize`, `structuredClone` | 🚫 |
+| `Error.stack` capture | 🚫 (not captured) |
+| `Object.getPrototypeOf({})` | ⚠️ returns `undefined`, not `Object.prototype` |
+| Global RegExp `lastIndex` | ⚠️ `test`/`exec` ignore it for `/g` and `/y` |
+| Sparse array holes, array out-of-bounds | ⚠️ holes are not tracked distinctly; out-of-bounds reads give `undefined` |
+
+See section 3 of [../unimplemented.md](../unimplemented.md) for the full list.
+
+## Modules
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| ESM `import` / `export` | ✅ | |
+| Relative multi-file bundling | ✅ | a `./helper.js` specifier resolves to `helper.ts` |
+| `import * as ns`, default and named imports | ✅ | |
+| Node built-in modules | ✅ | only with `--ext node` — see [extensions.md](./extensions.md) |
+| Bare third-party npm packages | 🚫 | `node_modules` ESM packages are bundled as source only when no extension claims the specifier |
+| `require()` / CommonJS | 🚫 | rejected with a hint to use `import` |
+| Circular dependencies | 🚫 | |
+| Live bindings | ⚠️ | imports and namespace members are snapshots |
+| `import.meta`, `__dirname`, `__filename` | 🚫 | |
+
+## Strings, numbers, memory
+
+| Item | Behaviour |
+| --- | --- |
+| `String.prototype.length` | ⚠️ **UTF-8 bytes**, not UTF-16 units: `"é".length === 1`, `"😀".length === 4`; `codePointAt` differs accordingly |
+| Number formatting and coercion | ✅ matches Node (`toFixed`, `toPrecision`, hex/octal/binary parsing) |
+| `BigInt` | ✅ implemented |
+| Garbage collection | ✅ non-moving mark-sweep; explicit roots plus a conservative C-stack scan; single-threaded and stop-the-world; no weak references |
+| Threads | 🚫 single-threaded; `worker_threads` exists in the Node extension only |
+
+## Platform
+
+Builds target macOS, Linux and Windows on x64 and arm64. On Windows the target
+is the **MSVC ABI**, so clang needs the MSVC/SDK environment — see
+[../requirements.md](../requirements.md). clang **16 or newer** is required.
+
+## Before you write a large program
+
+1. Skim the table for the features you plan to use; open
+   [../unimplemented.md](../unimplemented.md) for anything marked ⚠️ or 🚫.
+2. Prototype with `xbintsc emit app.ts` — the cheapest way to learn whether a
+   construct is supported, since it needs no clang.
+3. Run the real thing with `xbintsc run app.ts`. If a build fails, go to
+   [troubleshooting.md](./troubleshooting.md).
+4. When exact Node behaviour matters, run the same program under Node and
+   compare output; the project's own test suite does this differential check.