xbintsc 0.5.6 → 0.5.21

package/doc/implemented/node/util.md

@@ -0,0 +1,25 @@
+# `util`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/util.md)
+
+Location: `src/extensions/node/util/index.ts`, `runtime/ext_node/util/util.c`
+
+Both named imports (`import { format } from "util"`) and namespace calls
+(`import util from "util"` / `import * as util from "util"`) are supported.
+
+| Function | Notes |
+| --- | --- |
+| `format(fmt, ...args)` | `%s` `%d` `%i` `%f` `%j` `%o` `%O` `%c` `%%` placeholders |
+| `formatWithOptions(opts, fmt, ...args)` | options accepted and ignored |
+| `inspect(value)` | recursive printer (depth-limited, strings quoted) |
+| `isDeepStrictEqual(a, b)` | structural comparison (`NaN` equals `NaN`) |
+| `inherits(ctor, superCtor)` | prototype wiring |
+| `deprecate(fn, msg)` | returns `fn` unchanged (there is no warning channel) |
+| `promisify(fn)` | wraps a trailing-callback function into a `Promise` |
+| `isString` `isNumber` `isBoolean` `isUndefined` `isNull` `isFunction` `isArray` `isObject` `isBuffer` `isDate` `isRegExp` `isPromise` `isError` | type predicates |
+
+```ts
+import { format, promisify } from "util";
+
+console.log(format("%s=%d", "n", 3)); // n=3
+```

package/doc/implemented/node/worker-threads.md

@@ -0,0 +1,10 @@
+# `worker_threads`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/worker-threads.md)
+
+Location: `src/extensions/node/worker_threads/index.ts`, `runtime/ext_node/worker_threads/worker_threads.c`
+
+- `Worker`, `isMainThread`, `workerData`, `parentPort`.
+- xbintsc emulates a worker by re-running the current executable as a child
+  process; `isMainThread` / `workerData` / `parentPort` are value bindings
+  (nullary runtime getters) and `Worker` is a constructor.

package/doc/implemented/node/zlib.md

@@ -0,0 +1,8 @@
+# `zlib`
+
+> Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/zlib.md)
+
+Location: `src/extensions/node/zlib/index.ts`, `runtime/ext_node/zlib/zlib.c`
+
+- Only `createGzip()` is implemented. It returns a gzip transform consumed by
+  [`stream/promises`](./stream-promises.md) `pipeline`.

package/doc/implemented/node.md

@@ -0,0 +1,48 @@
+# Node extension: implemented
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/node.md)
+
+Location: `src/extensions/node/`, `runtime/ext_node/`
+
+The `node` extension is optional: enable it with `--ext node` (or
+`"extensions": ["node"]` in `xbintsc.config.json`). It is a platform extension:
+one subdirectory per Node module, pairing the TypeScript exports with the C
+implementation. Adding a module does not change the core compiler; the extension
+contract is described in [Extension mechanism](./extensions.md).
+
+Every module has its own page so a change to one module does not collide with
+work on another. Missing or different behaviour is recorded under
+[Node extension: unimplemented](../unimplemented/node.md).
+
+## Modules
+
+| Module | Page | Notes |
+| --- | --- | --- |
+| `fs` | [fs](./node/fs.md) | synchronous API only |
+| `fs/promises` | [fs/promises](./node/fs-promises.md) | reactor-driven file and `FileHandle` operations on the async I/O pool |
+| `path` | [path](./node/path.md) | `path.<name>(...)` namespace calls |
+| `os` | [os](./node/os.md) | `os.<name>(...)` namespace calls |
+| `process` | [process](./node/process.md) | object: methods and properties |
+| `buffer` | [buffer](./node/buffer.md) | `Buffer` represented as a plain object |
+| `stream` | [stream](./node/stream.md) | `Readable` / `Writable` / `Duplex` / `Transform` / `PassThrough` |
+| `stream/promises` | [stream/promises](./node/stream-promises.md) | `pipeline` only |
+| `net` | [net](./node/net.md) | TCP server and client |
+| `dgram` | [dgram](./node/dgram.md) | UDP sockets |
+| `http` | [http](./node/http.md) | server and client, `Connection: close` |
+| `child_process` | [child_process](./node/child-process.md) | `spawnSync` only |
+| `events` | [events](./node/events.md) | `EventEmitter` (global and named export) |
+| `util` | [util](./node/util.md) | formatting, inspection and predicates |
+| `querystring` | [querystring](./node/querystring.md) | parse / stringify / escape |
+| `assert` | [assert](./node/assert.md) | assertion functions |
+| `test` | [test](./node/test.md) | minimal TAP runner |
+| `crypto` | [crypto](./node/crypto.md) | `createHash` (SHA-1 / SHA-256) |
+| `url` | [url](./node/url.md) | `pathToFileURL` / `fileURLToPath` |
+| `zlib` | [zlib](./node/zlib.md) | `createGzip` only |
+| `worker_threads` | [worker_threads](./node/worker-threads.md) | emulated with child processes |
+
+## Where does a change belong?
+
+A Node module change normally touches `src/extensions/node/<module>/` and
+`runtime/ext_node/<module>/`; document it in `node/<module>.md` and, if it
+changes a limitation, in the matching page under
+`../../unimplemented/node/`. The compiler core does not change.

package/doc/implemented/operators.md

@@ -0,0 +1,38 @@
+# Operators and assignment
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/operators.md)
+
+Location: `src/codegen/llvm.ts` (`BINARY_RUNTIME`, `emitPrefix`, `emitPostfix`, `emitAssignment`)
+
+## Arithmetic
+
+`+ - * / % **` (`**` is right-associative)
+
+## Comparison and equality
+
+`< <= > >=`, `== !=` (loose equality), `=== !==` (strict equality)
+
+## Logical and short-circuit
+
+`&& || ??` (with short-circuit evaluation), `!`
+
+## Bitwise
+
+`& | ^ ~ << >> >>>`
+
+## Unary
+
+`+ - ! ~`, prefix / postfix `++ --`
+
+## Assignment
+
+`= += -= *= /= %= **= <<= >>= >>>= &= |= ^= &&= ||= ??=`
+
+## 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.

package/doc/implemented/parser.md

@@ -0,0 +1,58 @@
+# Parser
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/parser.md)
+
+Location: `src/parser/parser.ts`, `src/ast/nodes.ts`
+
+Module syntax (`import` / `export`, import attributes) and the driver-level bundling that gives it runtime meaning are covered in [Module system](./modules.md).
+
+## Statements
+
+- Variable declarations: `var` / `let` / `const`, with multiple declarators `const a = 1, b = 2;`
+- Function declarations, function expressions and methods, including the `async` modifier, generators (`function*`, `yield`, `yield*`, `.next`/`.throw`/`.return`) and async generators (`async function*`, `for await...of`)
+- `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`
+- `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
+
+## Expressions
+
+- All common operators with precedence / associativity (see [Operators](./operators.md))
+- Assignment expressions and all compound assignments (see [Operators](./operators.md))
+- 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)
+
+## 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)
+
+## ASI
+
+- Automatic Semicolon Insertion, based on `precededByLineBreak` / `}` / EOF.

package/doc/implemented/pipeline.md

@@ -0,0 +1,28 @@
+# Compilation pipeline
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/pipeline.md)
+
+```
+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`. The front end lives in `src/driver/frontend.ts`, the cache key in `src/driver/build-key.ts`, runtime compilation in `src/driver/runtime-objects.ts`, and platform artifacts in `src/driver/app-artifacts.ts`.
+- **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.

package/doc/implemented/runtime-core.md

@@ -0,0 +1,32 @@
+# C runtime core
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/runtime-core.md)
+
+Location: `runtime/xt_alloc.c`, `runtime/xt_values.c`, `runtime/xt_containers.c`,
+`runtime/xt_builtins.c`, `runtime/xt_constructors.c`, `runtime/xt_io.c`, sharing the
+private header `runtime/rt_internal.h`; the public ABI is in `runtime/rt.h`.
+
+Strings, symbols, typed arrays, collections, promises/async, `fetch` and the
+standard-library surface have their own pages:
+
+- [Strings and text](./strings.md)
+- [Standard library](./stdlib.md)
+- [Collections](./collections.md)
+- [Typed arrays and binary data](./typed-arrays.md)
+- [Async, promises and generators](./async.md)
+- [fetch](./fetch.md)
+
+- 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`.
+- 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`.
+- Generic member access: `xt_get` / `xt_set` (dispatch over arrays / objects / strings).
+- 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) that `Error.stack` captures (see [Standard library](./stdlib.md)), 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.
+- 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.

package/doc/implemented/stdlib.md

@@ -0,0 +1,78 @@
+# Standard library
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/stdlib.md)
+
+Location: `runtime/xt_stdlib.c`, `runtime/xt_stdlib2.c`, `runtime/xt_symbol.c`,
+`runtime/xt_builtins.c`, `runtime/xt_constructors.c`, `runtime/xt_io.c`,
+`runtime/xt_structured_clone.c`, `runtime/xt_url.c`.
+
+The dispatch layer is `xt_call_method` (array / string methods and function
+properties on objects), `xt_math_call` (`Math.*` and constants) and the
+`xt_*` entry point of each constructor. Well-known symbols and the iterator
+protocol are in [Symbol](#symbol) below; collections and typed arrays have their
+own pages: [Collections](./collections.md), [Typed arrays and binary data](./typed-arrays.md).
+
+## Objects
+
+- `Object.keys` / `values` / `entries` / `assign` / `getOwnPropertyNames` / `groupBy`, object spread `{...obj}`.
+- `Object.defineProperty` / `getOwnPropertyDescriptor(s)` — data and accessor descriptors; the attribute flags are reported but not enforced on later writes/enumeration.
+- `Object.freeze` / `is_frozen` / `from_entries`, `Object.getPrototypeOf`.
+- `Object.prototype`: `hasOwnProperty` / `toString` / `valueOf` / `isPrototypeOf` / `propertyIsEnumerable` / `__proto__`; `Object.getPrototypeOf({}) === Object.prototype`.
+- First-class built-in constructors (`const A = Array`, `new A(...)`, `A.isArray`, `x instanceof A`) are covered in [Codegen](./codegen.md#llvm-ir-code-generation-codegen).
+
+## Arrays
+
+- `push` `pop` `shift` `unshift` `join` `slice` `splice` `indexOf` `lastIndexOf` `includes` `concat` `reverse` `forEach` `map` `filter` `reduce` `reduceRight` `find` `findIndex` `findLast` `findLastIndex` `some` `every` `sort` `flat` `flatMap` `fill` `copyWithin` `at` `keys` `values` `entries`
+- Immutable helpers: `toReversed` / `toSorted` / `toSpliced` / `with`.
+- Statics: `Array.isArray` / `of` / `from`.
+- Default `sort` is stable and compares string forms, like Node; assigning `arr.length` truncates or extends the array.
+
+## Numbers, BigInt and Math
+
+- Number formatting and coercion match Node: `toFixed` / `toPrecision` / `toExponential`, hex / octal / binary parsing, and the full `+` / relational `ToPrimitive` rules. These are covered by the differential tests.
+- `BigInt` literals and values: arbitrary precision arithmetic, bitwise and shift operators, comparisons, `toString(radix)`, `BigInt()`, `BigInt.asIntN` / `BigInt.asUintN`.
+- `Math`: the full function set and constants.
+- `Number` statics and `Number()` conversion; `parseInt` / `parseFloat` / `isNaN` / `isFinite`.
+
+## JSON
+
+- `JSON.parse` with a `reviver`.
+- `JSON.stringify` with a function or array `replacer`, `toJSON`, and `space` (number or string, clamped to 10). `undefined` / function / symbol values follow the standard omission rules.
+- Object keys are emitted in insertion order, with integer keys ordered numerically; circular references throw.
+
+## Date
+
+- `Date` backed by `gmtime_r`; ISO 8601 parsing through `Date.parse` / `new Date(string)`.
+
+## RegExp
+
+- `RegExp` uses POSIX ERE (`regcomp` / `regexec`) for `test` / `exec`, with capture groups exposed through `exec` / `match` / `replace` / `split` / `search`.
+- Matching is byte-oriented and `/g` / `/y` `lastIndex` is not honoured — see [Runtime deviations](../unimplemented/deviations.md).
+
+## Symbol
+
+- `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)`.
+
+## URLSearchParams
+
+- `URLSearchParams` is implemented in `runtime/xt_url.c`.
+
+## Errors
+
+- The `Error` family: `Error`, `TypeError`, `RangeError`, `SyntaxError`, `ReferenceError`, `EvalError`, `URIError`, `AggregateError` — `new`, `instanceof`, `extends`, `String(err)` / `err.toString()` and `.stack`.
+- `Promise.any` rejects with an `AggregateError`.
+- `.stack` contains function-level frames (`at name (file:line)`), captured from the runtime shadow call stack; the exact limitations are in [Runtime deviations](../unimplemented/deviations.md).
+
+## console
+
+- `xt_print` / `xt_println` / `xt_console_log` / `info` / `warn` / `error`; `info` / `log` go to stdout, `warn` / `error` to stderr.
+- Node-style inspection: arrays `[ a, b ]`, objects `{ k: v }`, UTF-8-aware, with circular references marked.
+- `dir` / `trace` / `assert` / `count` / `countReset` / `group` / `groupEnd` / `table` / `time` / `timeEnd` / `timeLog`.
+
+## Global functions
+
+- `parseInt` `parseFloat` `isNaN` `isFinite` `Number` `String` `Boolean` `encodeURI` `decodeURI` `encodeURIComponent` `decodeURIComponent`.
+- `btoa` / `atob` base64 encoding and decoding (core globals; not Node-extension-only).
+- `structuredClone`: arrays, objects, `Map`, `Set`, `Date`, `RegExp` and typed arrays, preserving cycles and shared references; functions, symbols, promises and generators are rejected.
+- Timers, `queueMicrotask` and `performance.now` are described in [Async, promises and generators](./async.md); `fetch` in [fetch](./fetch.md).

package/doc/implemented/strings.md

@@ -0,0 +1,27 @@
+# Strings and text
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/strings.md)
+
+Location: the string value lives in the core runtime (`runtime/xt_values.c`);
+the method surface is dispatched from `runtime/xt_stdlib.c` / `xt_stdlib2.c`;
+`TextEncoder` / `TextDecoder` live in `runtime/xt_text_codec.c`.
+
+## Value model
+
+- 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, and formatted number-to-string.
+- `xt_string_length` reports bytes for I/O; `xt_string_utf16_length` reports the JavaScript length.
+
+## Methods
+
+- `charAt` `charCodeAt` `codePointAt` `indexOf` `lastIndexOf` `includes` `startsWith` `endsWith` `slice` `substring` `substr` `split` `match` `replace` `replaceAll` `search` `toUpperCase` `toLowerCase` `trim` `trimStart` `trimEnd` `padStart` `padEnd` `repeat` `concat` `at` `localeCompare` `valueOf`
+- `String.match` / `lastIndexOf` / `split` with a limit; RegExp capture groups flow through `match` / `replace` / `split` / `search` (see [Standard library](./stdlib.md)).
+- `String` statics: `fromCharCode` / `fromCodePoint` / `raw`; tagged templates keep their raw strings.
+
+## Text encoding
+
+- `TextEncoder` / `TextDecoder` encode and decode through a `Uint8Array`; only the UTF-8 encoding is supported.
+
+Known divergences (`String.prototype.normalize`, byte-oriented RegExp matching)
+are listed in [Unimplemented: standard library](../unimplemented/stdlib.md).

package/doc/implemented/tests.md

@@ -0,0 +1,10 @@
+# Tests
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/tests.md)
+
+Location: `tests/` (`lexer` / `parser` / `binder` / `codegen` / `driver` / `extensions` / `cli` / `e2e`)
+
+- Per-module unit tests mirror the source tree.
+- `tests/e2e/` compiles real programs and runs the resulting binaries. When `clang` is absent the suite skips itself automatically; it is not a silent pass.
+- `tests/e2e/differential-*.test.ts` runs the same source through both `xbintsc` and Node and compares output byte-for-byte. When semantics change, add a differential case instead of a hand-written expected string.
+- Feature pages in this directory record the supported behaviour; the tests are the executable form of that contract. See [Contributing](../ai/contributing.md) for the gate (`npm run typecheck && npm run lint && npm test`).

package/doc/implemented/typed-arrays.md

@@ -0,0 +1,26 @@
+# Typed arrays and binary data
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/typed-arrays.md)
+
+Location: `runtime/xt_typed_array.c`, `runtime/xt_array_buffer.c`.
+
+## Typed arrays
+
+- `Uint8Array`, `Int8Array`, `Uint8ClampedArray`, `Uint16Array`, `Int16Array`, `Uint32Array`, `Int32Array`, `Float32Array`, `Float64Array`.
+- Construction: `new X(n)` / `new X(iterable)` / `new X(buffer[, offset[, length]])` / `X.from` / `X.of`.
+- Properties: `length` / `byteLength` / `byteOffset` / `.buffer` / `BYTES_PER_ELEMENT`.
+- Element reads/writes apply the per-type coercion (`ToIntN` / `ToUintN`, `Uint8ClampedArray` rounding, `Float32` single-precision rounding).
+- 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`. Iterator methods still return arrays, not iterator objects.
+- Typed arrays are views over an `ArrayBuffer`; `subarray` shares the buffer and `slice` copies.
+
+## ArrayBuffer and DataView
+
+- `ArrayBuffer`: `byteLength`, `slice`, `ArrayBuffer.isView`.
+- `DataView`: big-endian by default, optional `littleEndian`, with `get` / `set` for Uint8 / Int8 / Uint16 / Int16 / Uint32 / Int32 / Float32 / Float64.
+- Multiple views over one buffer share its bytes.
+
+## Not implemented
+
+- `BigInt64Array` / `BigUint64Array`.
+- `Buffer`-backed typed-array views.
+- `TextEncoder` / `TextDecoder` are implemented (UTF-8) and documented in [Strings and text](./strings.md); `structuredClone` copies typed arrays.

package/doc/implemented/value-model.md

@@ -0,0 +1,18 @@
+# Value model and calling convention
+
+> Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/value-model.md)
+
+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`.