xbintsc 0.3.46 → 0.3.61

package/doc/zh-CN/unimplemented.md

@@ -0,0 +1,247 @@
+# xbintsc 未实现语法与功能
+
+> 语言 / Language：[English](../unimplemented.md) | **简体中文**
+
+本文档基于对源码（`src/`、`runtime/`）与测试（`tests/`）的逐文件核对整理，列出**当前未实现 / 仅部分实现 / 语义与标准不符**的语法与功能。
+
+判定标准（按严重程度）：
+
+1. **未解析**：解析器直接报语法错误，无法进入代码生成。
+2. **解析但代码生成报错**：AST / 绑定能建立，但 `codegen` 报 `UnsupportedFeature`。
+3. **解析且能编译，但语义未实现或有偏差**：能产出二进制，但运行结果不符合 ECMAScript / TypeScript 语义。
+
+> 近期已补齐：**ECMAScript 语义 + 差分测试** —— 数字格式化 / 强制转换（`toFixed` / `toPrecision` / `toExponential`、十六 / 八 / 二进制解析、完整的 `+` 与关系运算 `ToPrimitive`）、`JSON.stringify` 省略规则、`Array.prototype.sort` 默认稳定字符串序、整数键插入序、整链可选链短路、`finally` 在提前 `return` / `break` / `continue` 时执行、对象键插入序、感知 UTF-8 且能展示循环引用的 `console` 输出、`Array.prototype.splice`、`String.prototype.match` / `lastIndexOf` / 带 limit 的 `split`、正则捕获组（`exec` / `match` / `replace` / `split` / `search`）、不可变数组方法（`toReversed` / `toSorted` / `toSpliced` / `with`）、`Object.getOwnPropertyNames` / `groupBy`、全局 URI 函数、标签语句、`#private` 字段 / 方法 / 静态成员、标记模板（含 raw 字符串与 `String.raw`）、相对模块的 `import * as ns`。测试套件新增了**差分测试脚手架**：每个用例同时经 xbintsc 与 Node 运行并逐字节比较输出。
+
+> 更早已补齐：`class` 声明 / 类表达式、`new` / `this`、继承 `extends` / `super`、`instanceof`、方法 / 静态成员 / 实例字段 / getter 与 setter / 构造器参数属性、`async` / `await` + `Promise`、`import` / `export` 多文件打包（含 `.js` → `.ts` 说明符解析与命名空间导入）、`Map` / `Set` / `Date` / `RegExp` / `JSON` / `BigInt`、解构绑定与解构参数、`enum` / `const enum`，以及**自举**（产出的 LLVM IR 达到逐字节不动点）。
+
+---
+
+## 1. 语句层未实现
+
+### 1.1 解析但代码生成报 `UnsupportedFeature`
+
+| 语法 | 现状 | 说明 |
+| --- | --- | --- |
+| `namespace` / `module` 声明 | 解析 ✓，代码生成 ✗ | → "does not yet support this statement (module declaration)" |
+
+> 标签语句（`label: statement`、`break label`、`continue label`）已实现，包括非循环语句上的标签。
+
+### 1.2 解析器不支持（直接语法错误）
+
+目前未知有语句级别的缺口。解析器有意保持宽松，接受绝大多数 TypeScript 语句语法；不支持的形式会在代码生成阶段报错（见上）。
+
+---
+
+## 2. 表达式层未实现
+
+### 2.1 解析但代码生成报 `UnsupportedFeature`
+
+无——生成器已实现。
+
+> 标记模板已实现，含 raw 字符串与 `String.raw`。生成器（`function*`、`yield`、`yield*`）
+> 基于有栈协程实现，支持 `next`/`throw`/`return`、`for...of`、展开与委托；
+> `import.meta` 可解析，但无运行时取值；异步生成器尚未支持。
+
+### 2.2 解析器不支持
+
+目前未知有表达式级别的缺口。
+
+### 2.3 运算符未实现
+
+| 运算符 | 现状 | 说明 |
+| --- | --- | --- |
+| `new.target` | ✗ | 未实现 |
+| `typeof` / `void` / `in` / `delete` / `instanceof` | ✓ | 映射到运行时辅助函数（`xt_typeof`、`xt_in`、`xt_delete`、`xt_instance_of`） |
+
+---
+
+## 3. 标准库未实现
+
+### 3.1 已实现（概要）
+
+- 数组：`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`，以及不可变的 `toReversed` / `toSorted` / `toSpliced` / `with`
+- 字符串：`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`
+- `Math`：完整函数与常量
+- `Object.keys` / `values` / `entries` / `assign` / `getOwnPropertyNames` / `groupBy`，对象展开 `{...obj}`
+- 全局函数：`parseInt` `parseFloat` `isNaN` `isFinite` `Number` `String` `Boolean` `encodeURI` `decodeURI` `encodeURIComponent` `decodeURIComponent`
+- `console.log` / `info` / `warn` / `error` / `dir` / `trace` / `assert` / `count` / `group` / `table` / `time`
+
+### 3.2 已补齐
+
+- `JSON.parse` / `JSON.stringify`
+- `Date`、`RegExp`（POSIX ERE 子集，支持捕获组）、`Map`、`Set`、`Promise`、`BigInt`
+- `Array` 静态（`isArray/of/from`）、`Object` 静态、`Number` 静态、`String` 静态（`fromCharCode` / `fromCodePoint` / `raw`）
+- `Error` 家族（`Error`、`TypeError`、`RangeError`、`SyntaxError`、`ReferenceError`、`EvalError`、`URIError`、`AggregateError`）：支持 `new`、`instanceof`、`extends`、`String(err)` / `err.toString()` 与 `.stack`
+
+### 3.3 仍未实现
+
+| 类别 | 现状 |
+| --- | --- |
+| `Symbol` 构造器与 symbol 原始值 | ✓ `Symbol(description)`、著名符号、`Symbol.for` / `Symbol.keyFor`、symbol 属性键与 `Object.getOwnPropertySymbols` |
+| `String.prototype.normalize` | ✗ 未实现 |
+| `structuredClone` | ✗ 未实现 |
+| 内置错误子类（`TypeError`、`RangeError` 等） | ✓ 一等公民构造器与原型；整个家族 `instanceof Error` 成立 |
+| `AggregateError` 构造器 | ✓ `new AggregateError(errors, message)`；`Promise.any` 现以其作为 rejection |
+| 迭代器协议 / `Symbol.iterator` / `for...of` 自定义可迭代 | ✓ 数组、字符串、`Map`、`Set`、生成器以及任何暴露 `[Symbol.iterator]()` 的对象均可在 `for...of` / 展开中使用 |
+| 生成器（`function*`、`yield`、`yield*`、`next`/`throw`/`return`） | ✓ 基于有栈协程实现；支持 `for...of`、展开与委托。`return()` 直接结束，不执行 `finally` |
+| 定时器 | ✓ 核心事件循环提供 `setTimeout` / `clearTimeout` / `setInterval` / `clearInterval`（返回数字 id，无 `Timeout` 对象；无 `setImmediate` / `queueMicrotask`） |
+| I/O / 进程等宿主 API | 仅通过扩展（如 Node `fs`）提供 |
+
+### 3.4 类型化数组
+
+已实现：`Uint8Array`、`Int8Array`、`Uint8ClampedArray`、`Uint16Array`、
+`Int16Array`、`Uint32Array`、`Int32Array`、`Float32Array`、`Float64Array`，支持
+`new X(n)` / `new X(数组样)`、`X.from` / `X.of`、`BYTES_PER_ELEMENT`、按类型强制的
+元素写入，以及 `fill` / `set` / `slice` / `subarray` / `join` / `toString` /
+`indexOf` / `lastIndexOf` / `includes` / `forEach` / `map` / `filter` / `every` /
+`some` / `find` / `findIndex` / `reduce` / `reverse` / `sort` / `copyWithin` /
+`at` / `keys` / `values` / `entries`。已知差异：
+
+| 功能 | 现状 |
+| --- | --- |
+| `subarray` | ~ 返回副本，而非共享缓冲区上的视图 |
+| `keys` / `values` / `entries` | ~ 返回数组，而非迭代器对象 |
+| `ArrayBuffer` / `DataView` / `.buffer` / `.byteOffset` 语义 | ✗ 无底层缓冲区类型；`.byteOffset` 恒为 0 |
+| `BigInt64Array` / `BigUint64Array` | ✗ 未实现 |
+| `instanceof Uint8Array` | ✗ 全局构造器不是一等公民值，`x instanceof Uint8Array` 会报 `Cannot find name 'Uint8Array'` |
+| 基于 `Buffer` / `ArrayBuffer` 的类型化数组视图 | ✗ 构造器仅能从长度 / 数组样 / 类型化数组复制 |
+
+---
+
+## 4. 模块系统
+
+| 功能 | 现状 |
+| --- | --- |
+| 多文件 / 模块解析与链接 | ✓ 驱动层 AST 打包（`src/driver/modules.ts`）：解析每个模块、按模块前缀重命名顶层符号、改写引用后合并为单文件重新绑定 |
+| 具名导入导出 | ✓ `import { a, b as c }` / `export { a as b }` / `export const/let/var/function/class` |
+| 默认导入导出 | ✓ `export default` / `import d from` |
+| 再导出 `export { x } from` / `export * from` | ✓（`export *` 复制依赖模块的导出） |
+| 命名空间导入 `import * as ns` | ✓ 降级为持有全部导出的合成对象字面量 |
+| 循环依赖 | ✗ 直接报错（不做循环初始化语义） |
+| 实时绑定（live bindings） | ✗ 命名空间对象与导入绑定是模块求值时的快照 |
+| ESM `node_modules` 包 | ✓ 裸说明符沿目录树解析，支持 `exports` / `module` / `main`、作用域包与子路径；包源码与相对模块一样被打包 |
+| CommonJS `require` / `module.exports` | ✓ 仅限 `node_modules` 内：打包器为每个 CommonJS 包注入合成的 `module` / `exports`，将 `require("x")` 降级为依赖的导出对象，并把外部/内置 `require` 提升为 ESM `import`。用户代码（`node_modules` 之外）的 `require()` 仍会报错并提示改用 ESM `import` |
+
+> 扩展模块（如 `fs`）可通过裸名称或 `node:` 前缀的 `import` 引入 —— `import { readFileSync } from "fs"` / `import path from "path"` —— 并解析到运行时入口（具名、默认与命名空间形式均可）。相对模块与 `node_modules` 中的 ESM/CJS 包均在驱动层打包；CJS 包内的 `require` 会静态解析并内联。
+
+---
+
+## 5. 函数特性未实现（或语义缺失）
+
+| 特性 | 解析 | 语义 |
+| --- | --- | --- |
+| 默认参数 `function f(a = 5)` | ✓ | ✓ 已实现 |
+| 剩余参数 `function f(...args)` | ✓ | ✓ 已实现 |
+| 调用参数展开 `f(...args)` | ✓ | ✓ 已实现 |
+| 解构参数 / 解构绑定 | ✓ | ✓ 已实现 |
+| `arguments` 对象 | ✓（隐式） | ✓ 已实现（箭头函数取的是自身参数，而非外层函数的 `arguments`，与 JS 不同） |
+| `this` 绑定 / 方法调用语义 | ✓ | ✓ 已实现（`this` 作为函数首个 ABI 参数线程化；箭头函数词法继承） |
+| `async` / `await` / Promise | ✓ | ✓ 已实现（同步微任务模型） |
+| `new.target` | ✗ | 未实现 |
+| 生成器 / 迭代器 / `yield` | ✓ 已实现 | `function*`、`yield`、`yield*`、`.next/.throw/.return`；不支持异步生成器 |
+| 闭包 `arity` | — | `xt_closure_arity` 恒为 -1，未填充 |
+| `fn.call` / `fn.apply` / `fn.bind` | ✓ | ✓ 已实现（绑定闭包不跟踪部分参数的 `length`） |
+| `fn.name` / `fn.length` | ✓ | ✓ 已实现（从声明 / 赋值 / 属性键推断；绑定函数为 `"bound ..."` 并调整 arity） |
+| 内置方法一等公民（`typeof arr.map`、`const f = arr.push`、`obj.method?.()`） | ✓ | ✓ 作为**未绑定**方法值实现：读取 `arr.map` 得到函数，`arr.map?.(cb)` 与 `obj.method?.()` 会把接收者作为 `this` 绑定，脱离接收者调用（`const f = arr.map; f(cb)`）会像 JavaScript 一样抛错。方法的 `name`/`length` 也一并暴露 |
+| `fn.toString()` | ~ | 返回原生占位字符串（`function name() { [native code] }`），而非原始源码文本 |
+
+---
+
+## 6. 类与面向对象
+
+| 特性 | 现状 |
+| --- | --- |
+| `class` 声明 / 类表达式 | ✓ 已实现 |
+| 构造函数 `constructor` | ✓ |
+| 实例字段 / 属性声明 | ✓ |
+| 方法 | ✓ |
+| `static` 字段 / 方法 | ✓ |
+| 继承 `extends` / `super` | ✓（单级正确；`super` 取 `this` 原型的原型，理论缺陷见第 8 节） |
+| 原型链 / 方法查找 | ✓ |
+| `instanceof` | ✓ |
+| `new` / 实例化 | ✓ |
+| `get` / `set` 访问器 | ✓ 已实现 |
+| 参数属性 `constructor(public x: T)` | ✓ 已实现 |
+| 私有字段 `#x` | ✓ 已实现（以字面量 `#x` 作为键存储；无访问控制强制） |
+| `enum` / `const enum` | ✓ 已实现（正向 + 反向映射） |
+| `private` / `protected` / `public` / `readonly` 修饰符 | ✗ 无访问控制（擦除） |
+| `abstract` / `implements` | ✗（擦除） |
+| 父子类 `#x` 同名 | ✗ 可能混用（同一字面量键） |
+
+---
+
+## 7. 类型系统未实现（仅解析、不检查）
+
+类型语法被解析为 AST 后在绑定 / 代码生成阶段**整体擦除**，不做任何类型检查：
+
+- 类型注解、返回类型、类型参数、类型别名、接口、泛型约束等：解析 ✓，检查 ✗。
+- 检查器诊断码（`TypeMismatch` `NotCallable` `PropertyNotFound` `ArgumentCountMismatch`）已定义但**未使用**。
+- `as` / `satisfies` / 非空断言 `!`：直接擦除，不做任何断言语义。
+- 泛型：无运行时实例化，类型参数被忽略。
+- 可选链 `?.` 的类型窄化：无（运行时短路已实现，但无类型层面的窄化）。
+
+---
+
+## 8. 运行时 / 语义与标准不符（已知偏差）
+
+这些特性**能编译、能运行**，但结果不完全符合 ECMAScript：
+
+| 项 | 偏差 |
+| --- | --- |
+| 字符串 `length` | 按 UTF-8 字节计数，而非 UTF-16 码元（`"\u00e9".length` 报 1 而非 2；`"\u{1F600}".length` 报 4 而非 2；`codePointAt` 同样有偏差） |
+| `Object.getPrototypeOf({})` | 返回 `undefined`，而非 `Object.prototype` 对象 |
+| 全局正则 `lastIndex` | `/g`、`/y` 正则的 `test` / `exec` 不推进也不读取调用方设置的 `lastIndex` |
+| `String.normalize` / `structuredClone` | 未实现 |
+| 内置方法一等公民 | 以未绑定方法值实现（见第 5 节）；`fn.toString()` 返回占位字符串而非源码文本 |
+| `for...in` | 枚举对象 / 数组 / 字符串的自身键；不含原型链属性 |
+| 数组越界 / 稀疏 | 越界访问返回 `undefined`；对 `arr.length` 赋值会截断 / 扩展，但不区分稀疏空洞 |
+| 内存管理 | 非移动标记-清扫回收器（在 `xt_alloc` 之后）：显式根、子系统根提供者与保守 C 栈扫描。单线程、stop-the-world；无移动/压缩与分代 |
+| 函数 `arity` / 调用参数个数 | 无参数个数校验；`fn.length` 报告声明的 arity，但调用不做校验 |
+| `async` / `await` | **同步微任务模型**：`await` 在已 settle 的 promise 上同步继续。定时器与套接字仅在程序主体执行完后由事件循环运行，因此无法等待由定时器回调 settle 的 promise |
+| `super` | `super.x` / `super(...)` 取 `this` 原型的原型；单级继承正确，继承深度 > 1 时可能不准确 |
+| `Error.stack` | 未捕获 |
+| 模块实时绑定 | 命名空间导入与导入绑定为快照（见第 4 节） |
+| `import.meta` | 可解析但无取值 |
+
+> 数字格式化、宽松相等、`+` / 关系运算 `ToPrimitive`、整链可选链、`finally` 提前退出、对象键顺序等均已对齐 Node，并由差分测试覆盖，故不再列为偏差。
+
+---
+
+## 9. 工具链 / 平台 / 工程未实现
+
+| 项 | 现状 |
+| --- | --- |
+| GC（垃圾回收） | ✓ `xt_alloc.c` 中的非移动标记-清扫，按存活堆阈值（`XT_GC_THRESHOLD`）或 `xt_gc_collect()` 触发；显式根 + 根提供者 + 保守活动栈扫描。无压缩、弱引用或后台回收 |
+| 自举（self-hosting） | ✓ 编译器已能自编译：`xbintsc build src/cli/main.ts` 可产出可用二进制，且从第 1 代起产出的 IR 保持稳定。运行时仍为 C |
+| 类型检查器 | ✗ 仅定义诊断码，无 checker |
+| 完整标准库 | 部分：Math / JSON / Date / Map / Set / RegExp / `Error` / `BigInt` / `Symbol` 已实现；String.normalize / structuredClone 缺失 |
+| 多文件模块打包 | 部分：相对路径 `.ts` 打包、ESM `node_modules` 包、命名空间导入、裸说明符扩展模块导入已实现；循环依赖 / CommonJS / 实时绑定未实现 |
+| 真正的异步运行时 / 事件循环 | ✗（Promise 为同步微任务模型） |
+| Windows 二进制产物验证 | 构建层已适配（`.exe` 后缀、链接参数分支），并在 CI 中验证 |
+| 精确的 ECMAScript 数值 / 字符串 / 比较语义 | 部分，见第 8 节 |
+
+---
+
+## 10. 速查：未实现 / 部分实现清单
+
+```
+未实现（语句）：namespace/module 声明
+
+未实现（表达式）：new.target、import.meta 取值
+
+未实现（函数）：`fn.toString()` 源码文本、异步生成器
+
+未实现（类/面向对象）：abstract/implements、访问控制、父子类 #x 同名
+
+未实现（标准库）：String.normalize、structuredClone
+
+未实现（模块）：循环依赖、实时绑定、动态 `require(expr)`、
+                     `require.resolve` / `require.cache`、`__dirname` / `__filename`
+
+未实现（类型系统）：类型检查、泛型实例化、断言语义、可选链类型窄化
+
+未实现（运行时）：真正的异步事件循环、UTF-16 length、
+                  Object.prototype 身份、全局正则 lastIndex
+
+未实现（工程）：类型检查器
+```

package/llms.txt

@@ -0,0 +1,45 @@
+# xbintsc
+
+> xbintsc compiles a subset of TypeScript directly to native binaries: it parses
+> TypeScript itself, lowers the program to LLVM IR text, and drives clang to
+> produce a standalone executable linked against a small C runtime. There is no
+> Node.js, V8 or TypeScript compiler inside the produced binary. It runs on
+> macOS, Linux and Windows (x64 and arm64), compiles itself, and ships prebuilt
+> archives per platform. A clang 16+ toolchain is required to link binaries;
+> `xbintsc emit` (LLVM IR only) needs nothing.
+
+## Start here
+
+- [AGENTS.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/AGENTS.md): entry point for an agent working in the repository — what xbintsc is, the repository map, the build gate and the rules
+- [doc/ai/README.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/ai/README.md): task-oriented AI guide — the three facts that decide everything, and which page to read for your task
+- [README.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/README.md): the project's human overview
+
+## Using the compiler
+
+- [doc/ai/build-recipe.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/ai/build-recipe.md): exact commands to run, build, inspect IR and configure a project, with the program shape that compiles
+- [doc/ai/cli.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/ai/cli.md): every CLI flag and its parsing quirks, project config fields, environment variables, incremental-cache behaviour, diagnostic codes, programmatic API
+- [doc/ai/language-support.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/ai/language-support.md): the supported TypeScript subset as tables — statements, expressions, classes, async, the erased type system, standard library gaps, modules, runtime deviations
+- [doc/ai/extensions.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/ai/extensions.md): Node built-in modules and the `--ext node` rule, the GUI extension, bundling third-party packages, C++/Rust native extensions via manifest
+- [doc/ai/troubleshooting.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/ai/troubleshooting.md): the clang version requirement and every frequent error message with its cause and fix
+- [doc/requirements.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/requirements.md): per-platform toolchain prerequisites
+- [doc/xbintsc.config.schema.json](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/xbintsc.config.schema.json): JSON schema for `xbintsc.config.json`
+
+## Changing the compiler
+
+- [doc/ai/contributing.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/ai/contributing.md): test suites, the self-hosting fixpoint invariant, the runtime ABI and value model, adding extensions or diagnostics, documentation duties
+- [doc/DESIGN.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/DESIGN.md): architecture and design rationale
+- [doc/implemented.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/implemented.md): everything implemented, by compiler stage — the canonical reference
+- [doc/unimplemented.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/unimplemented.md): unsupported syntax, missing semantics and known deviations, with a quick-reference list
+- [doc/node-implemented.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/node-implemented.md): Node module coverage of the `node` extension
+- [doc/node-unimplemented.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/node-unimplemented.md): what the `node` extension is still missing
+- [doc/gui.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/gui.md): the self-hosted GPU HTML/CSS renderer
+- [doc/gui-scripts.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/gui-scripts.md): the GUI scripting surface
+- [doc/icon.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/icon.md): application icons and project config packaging
+- [examples/extensions/README.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/examples/extensions/README.md): authoring C++ and Rust native extensions
+
+## Optional
+
+- [doc/zh-CN/](https://github.com/zy445566/xbintsc/tree/main/doc/zh-CN): Chinese translations of the canonical documents
+- [doc/ai/zh-CN/](https://github.com/zy445566/xbintsc/tree/main/doc/ai/zh-CN): Chinese translations of the AI guide
+- [doc/post/announce.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/doc/post/announce.md): announcement / project write-up
+- [README.zh-CN.md](https://raw.githubusercontent.com/zy445566/xbintsc/main/README.zh-CN.md): the project overview in Chinese

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xbintsc",
-  "version": "0.3.46",
+  "version": "0.3.61",
   "description": "xbintsc - a TypeScript binary compiler (TypeScript -> LLVM IR -> native binary)",
   "type": "module",
   "license": "MIT",
@@ -27,6 +27,9 @@
     "runtime",
     "scripts",
     "bin",
+    "doc",
+    "AGENTS.md",
+    "llms.txt",
     "README.md"
   ],
   "scripts": {

package/runtime/ext_gui/dom_api.cpp

@@ -136,6 +136,25 @@ xt_value xt_gui_node_handle(XtGuiWindow *win, const xtgui::Node *node) {
   return handle;
 }
 
+void xt_gui_node_handle_forget(XtGuiWindow *win, const xtgui::Node *node) {
+  if (win == nullptr || node == nullptr) return;
+  /* The node is about to be destroyed (a removal, or `innerHTML = …` dropping
+   * the old children). Drop its slot as well as its handle: the slot is what
+   * `resolve_node` reads, and leaving a freed pointer there is a
+   * use-after-free the next time any handle is resolved. Existing handles keep
+   * resolving to "stale" and no-op, which is the documented tombstone
+   * behaviour. */
+  auto index = win->node_index.find(node);
+  if (index != win->node_index.end()) {
+    int slot = index->second;
+    if (slot >= 0 && slot < (int)win->node_order.size()) {
+      win->node_order[(size_t)slot] = nullptr;
+    }
+    win->node_index.erase(index);
+  }
+  win->node_handles.erase(node);
+}
+
 xt_value xt_gui_document_handle(XtGuiWindow *win) {
   if (win == nullptr) return XT_UNDEFINED;
   if (!XT_IS_OBJECT(win->document_object)) {

package/runtime/ext_gui/dom_api_node.cpp

@@ -177,7 +177,10 @@ METHOD(node_replace_child) {
   xtgui::Node *newChild = resolve_node(xt_arg(argc, argv, 0), nullptr);
   xtgui::Node *oldChild = resolve_node(xt_arg(argc, argv, 1), nullptr);
   if (newChild == nullptr || oldChild == nullptr) return XT_UNDEFINED;
-  return xt_gui_node_handle(win, win->document->replaceChild(node, newChild, oldChild));
+  /* `replaceChild` frees the node it replaces, so its slot may not survive. */
+  xtgui::Node *replaced = win->document->replaceChild(node, newChild, oldChild);
+  if (replaced != oldChild) xt_gui_node_handle_forget(win, oldChild);
+  return xt_gui_node_handle(win, replaced);
 }
 
 METHOD(node_remove) {

package/runtime/ext_gui/dom_api_node_read.cpp

@@ -25,6 +25,13 @@ static void collect_text(const xtgui::Node *node, std::string &out) {
   for (const std::unique_ptr<xtgui::Node> &child : node->children) collect_text(child.get(), out);
 }
 
+/** Forget the handles of `node` and every descendant: they are about to be
+ * freed, and a slot left behind would dangle. */
+static void forget_subtree(XtGuiWindow *win, const xtgui::Node *node) {
+  xt_gui_node_handle_forget(win, node);
+  for (const std::unique_ptr<xtgui::Node> &child : node->children) forget_subtree(win, child.get());
+}
+
 #define METHOD(name) xt_value name(xt_value self, xt_value env, int32_t argc, xt_value *argv)
 
 METHOD(node_tag_name_get) {
@@ -105,6 +112,7 @@ METHOD(node_text_content_set) {
   std::vector<xtgui::Node *> existing;
   for (const std::unique_ptr<xtgui::Node> &child : node->children) existing.push_back(child.get());
   for (xtgui::Node *child : existing) win->document->removeChild(node, child);
+  for (xtgui::Node *child : existing) forget_subtree(win, child);
   if (!text.empty()) node->addText(text);
   mark_dirty(win);
   return XT_UNDEFINED;
@@ -132,6 +140,10 @@ METHOD(node_inner_html_set) {
   std::vector<xtgui::Node *> existing;
   for (const std::unique_ptr<xtgui::Node> &child : node->children) existing.push_back(child.get());
   for (xtgui::Node *child : existing) win->document->removeChild(node, child);
+  /* The old children are dropped here (only `removeChild` keeps a detached node
+   * alive), so forget them *and everything below them* before they are freed:
+   * a leftover slot would be a dangling pointer for the next handle lookup. */
+  for (xtgui::Node *child : existing) forget_subtree(win, child);
   std::unique_ptr<xtgui::Node> fragment = xtgui::xt_html_parse(html);
   for (std::unique_ptr<xtgui::Node> &child : fragment->children) node->append(std::move(child));
   mark_dirty(win);

package/runtime/ext_gui/gui.cpp

@@ -64,16 +64,44 @@ void xt_gui_apply_icon(SDL_Window *window) {
   SDL_DestroySurface(surface);
 }
 
+/* -- garbage collector roots ---------------------------------------------- */
+
+/**
+ * GC root provider: the engine caches `xt_value`s in C++ containers that the
+ * mark-sweep collector cannot see — per-window element handles, element
+ * listeners, the document handle and the queued/currently-running
+ * `requestAnimationFrame` callbacks. Rooting the window object alone does not
+ * reach these (they are not its properties), so without this provider a
+ * collection frees values the engine still uses and the next frame or DOM read
+ * crashes. The process-wide AOT `<script>` registry registers its own
+ * provider (`xt_gui_script_gc_scan`).
+ */
+static void xt_gui_gc_scan_roots(void) {
+  for (int i = 0; i < g_window_count; i++) {
+    const XtGuiWindow &win = g_windows[i];
+    xt_gc_mark_value(win.object);
+    xt_gc_mark_value(win.document_object);
+    for (const auto &entry : win.node_handles) xt_gc_mark_value(entry.second);
+    for (const auto &entry : win.node_listeners) {
+      for (const XtGuiNodeListener &listener : entry.second) xt_gc_mark_value(listener.fn);
+    }
+    for (const XtGuiAnimationFrame &frame : win.animation_frames) xt_gc_mark_value(frame.fn);
+    for (const XtGuiAnimationFrame &frame : win.running_frames) xt_gc_mark_value(frame.fn);
+  }
+}
+
 /* -- initialisation ------------------------------------------------------- */
 
-static int ensure_init(void) {
-  if (g_sdl_initialized) return 1;
+static int ensure_init(void) {  if (g_sdl_initialized) return 1;
+  xt_gc_register_root_provider(xt_gui_gc_scan_roots);
   if (!SDL_Init(SDL_INIT_VIDEO)) {
     fprintf(stderr, "xt_gui: SDL_Init failed: %s\n", SDL_GetError());
     return 0;
   }
   /* Accept every shader format so the same code runs on Metal, Vulkan and
-   * D3D12; the backend only needs the one it supports. */
+   * D3D12; the backend only needs the one it supports. The engine ships MSL,
+   * SPIR-V and DXIL shaders accordingly, and picks the matching one in
+   * `renderer_shaders.h`. */
   SDL_GPUShaderFormat formats =
       SDL_GPU_SHADERFORMAT_MSL | SDL_GPU_SHADERFORMAT_SPIRV | SDL_GPU_SHADERFORMAT_DXIL;
   g_device = SDL_CreateGPUDevice(formats, false, NULL);
@@ -100,6 +128,12 @@ static XtGuiWindow *window_by_object(xt_value object) {
 
 using namespace guidev;
 
+const char *xt_gui_driver(void) {
+  if (g_device == NULL) return "";
+  const char *driver = SDL_GetGPUDeviceDriver(g_device);
+  return driver != NULL ? driver : "";
+}
+
 XtGuiWindow *xt_gui_window_from_this(xt_value thisValue) {
   return window_by_object(thisValue);
 }
@@ -204,6 +238,14 @@ extern "C" xt_value xt_gui_create_window(int32_t argc, xt_value *argv) {
   xt_object_set(object, xt_string_from_cstr("__xt_gui_index"), xt_number((double)index));
   xt_object_set(object, xt_string_from_cstr("__xt_gui_html"), xt_string_from_cstr(""));
   xt_object_set(object, xt_string_from_cstr("__xt_gui_events"), xt_object_new());
+  /* The engine owns a graph of values on the window's behalf — element
+   * handles (`node_handles`), their event listeners and the queued animation
+   * frame closures. Most of them are referenced from TypeScript too, but not
+   * all: a handle the script queried once and dropped (or one only reachable
+   * through an ancestor element) would otherwise be collected while the engine
+   * still uses it, which is a use-after-free. Rooting the window object makes
+   * everything hanging off it reachable. */
+  xt_gc_add_root(&record->object);
 
   return object;
 }

package/runtime/ext_gui/gui_engine.h

@@ -24,6 +24,9 @@ xt_value xt_gui_run(int32_t argc, xt_value *argv);
 xt_value xt_gui_quit(int32_t argc, xt_value *argv);
 /** `__registerScript(id, fn)`: record an AOT-compiled `<script>` body. */
 xt_value xt_register_script(int32_t argc, xt_value *argv);
+/** Which SDL_GPU backend the device is using (`"vulkan"`, `"direct3d12"`,
+ * `"metal"`, …), or `""` before the device exists. */
+const char *xt_gui_driver(void);
 
 #ifdef __cplusplus
 } /* extern "C" */
@@ -84,6 +87,11 @@ struct XtGuiWindow {
   int struct_dirty = 0;
   /** Callbacks queued for the next frame, plus the id counter. */
   std::vector<XtGuiAnimationFrame> animation_frames;
+  /** The batch currently running: its callbacks have been swapped out of
+   * `animation_frames`, and a collection triggered by one of them must still
+   * see the rest. Kept on the record (not a local) so the GC root provider can
+   * mark it. Empty except while `xt_gui_run_animation_frames` runs. */
+  std::vector<XtGuiAnimationFrame> running_frames;
   int next_animation_frame_id = 1;
 };
 
@@ -93,6 +101,10 @@ XtGuiWindow *xt_gui_window_from_this(xt_value thisValue);
 xt_value xt_gui_document_handle(XtGuiWindow *win);
 /** Node handle for `node` (created and cached on first use). */
 xt_value xt_gui_node_handle(XtGuiWindow *win, const xtgui::Node *node);
+/** Forget a node's slot and handle because it is about to be destroyed (a
+ * removal that frees it, or `innerHTML = …` dropping the old children). Without
+ * this the node table would keep a dangling pointer. */
+void xt_gui_node_handle_forget(XtGuiWindow *win, const xtgui::Node *node);
 /** Drop every cached handle/listener and bump the document generation. */
 void xt_gui_handles_reset(XtGuiWindow *win);
 /** Deliver `type` to element listeners along the propagation path. */
@@ -105,6 +117,9 @@ void xt_gui_flush_dom(XtGuiWindow *win);
 /** Run every registered `<script data-xt-id>` body found in the document, in
  * document order, passing `(windowHandle, documentHandle)`. */
 void xt_gui_run_scripts(XtGuiWindow *win);
+/** GC root provider: mark every AOT-compiled `<script>` function in the
+ * process-wide registry. Registered with the collector by `xt_register_script`. */
+void xt_gui_script_gc_scan(void);
 /** Shared prototype carrying the window methods. */
 xt_value xt_gui_window_proto(void);
 /** Release GPU claim + destroy the window and mark the record closed. */

package/runtime/ext_gui/gui_events.cpp

@@ -220,15 +220,18 @@ void handle_event(const SDL_Event *event) {
 
 void xt_gui_run_animation_frames(XtGuiWindow *win, double timestamp_ms) {
   if (win == NULL || win->animation_frames.empty()) return;
-  /* Swap the queue out first: a callback that calls requestAnimationFrame
-   * again schedules for the *next* frame, not this one. */
-  std::vector<XtGuiAnimationFrame> frames;
+  /* Swap the queue into a member, not a local: the GC root provider marks
+   * `running_frames` too, so a collection triggered while one callback runs
+   * cannot free the rest of the batch. Re-queueing from a callback lands in
+   * `animation_frames` and runs on the *next* frame, not this one. */
+  std::vector<XtGuiAnimationFrame> &frames = win->running_frames;
   frames.swap(win->animation_frames);
   for (const XtGuiAnimationFrame &frame : frames) {
     if (!win->open) break;
     xt_value arg = xt_number(timestamp_ms);
     xt_call_with_this(frame.fn, win->object, 1, &arg);
   }
+  frames.clear();
 }
 
 void xt_gui_render_window(XtGuiWindow *win) {
@@ -244,6 +247,10 @@ void xt_gui_render_window(XtGuiWindow *win) {
   /* Animation-frame callbacks run before layout, so any DOM mutation they make
    * is picked up by this same frame. */
   xt_gui_run_animation_frames(win, now);
+  /* A callback may have closed the window (directly or through the
+   * auto-close guard): `xt_gui_quit_window` released the document and the GPU
+   * geometry, so there is nothing left to lay out or paint. */
+  if (!win->open) return;
   if (win->document != nullptr && win->document->advance(delta)) win->geometry.dirty = 1;
 
   /* A DOM mutation from a handler invalidates the tree: restyle/relayout

package/runtime/ext_gui/layout.cpp

@@ -96,6 +96,12 @@ void LayoutTree::compute(const Node *root, const std::unordered_map<const Node *
   root_->node = root;
   root_->style = &root_style_;
   root_->display = Display::Block;
+  /* The initial containing block: absolute boxes with no positioned ancestor
+   * resolve their insets against the viewport. */
+  root_->cb_x = 0;
+  root_->cb_y = 0;
+  root_->cb_width = viewportWidth;
+  root_->cb_height = viewportHeight;
   if (root != nullptr) {
     if (root->type == NodeType::Document) {
       for (const std::unique_ptr<Node> &child : root->children) {

package/runtime/ext_gui/layout.h

@@ -59,6 +59,10 @@ struct LayoutBox {
   float content_x = 0, content_y = 0, content_width = 0, content_height = 0;
   float baseline = 0;
 
+  /* The padding box of the nearest positioned ancestor (the viewport when there
+   * is none): the containing block `position: absolute` resolves against. */
+  float cb_x = 0, cb_y = 0, cb_width = 0, cb_height = 0;
+
   LayoutBox *parent = nullptr;
   std::vector<std::unique_ptr<LayoutBox>> children;
 };

package/runtime/ext_gui/layout_flex.cpp

@@ -19,9 +19,12 @@ float Layouter::layoutFlex(LayoutBox *container, float contentWidth, float defin
                  containerStyle.flex_direction == FlexDirection::ColumnReverse;
   float gap = px(containerStyle.gap, contentWidth, containerStyle.font_size, 0.0f);
 
+  /* An absolutely positioned child is out of flow: it takes no part in the flex
+   * algorithm and is placed against the container's padding box instead. */
   std::vector<LayoutBox *> items;
   for (const std::unique_ptr<LayoutBox> &child : container->children) {
-    if (child->display != Display::None) items.push_back(child.get());
+    if (child->display == Display::None || isAbsoluteChild(child.get())) continue;
+    items.push_back(child.get());
   }
   if (items.empty()) return 0;
   size_t count = items.size();
@@ -71,6 +74,7 @@ float Layouter::layoutFlex(LayoutBox *container, float contentWidth, float defin
     for (size_t i = 0; i < count; i++) {
       float contentW = mainSizes[i] - horizontalEdges(items[i]);
       if (contentW < 0) contentW = 0;
+      setContainingBlock(items[i], containingBlockAncestor(items[i]));
       layoutBlock(items[i], container->content_x, container->content_y, contentWidth,
                   definiteHeight, contentW);
       cross[i] = verticalEdges(items[i]) + items[i]->height;
@@ -98,8 +102,8 @@ float Layouter::layoutFlex(LayoutBox *container, float contentWidth, float defin
     for (size_t k = 0; k < count; k++) {
       size_t i = reverse ? (count - 1 - k) : k;
       float crossOffset = crossOffsetFor(containerStyle.align_items, crossSize, cross[i]);
-      float dx = cursor - items[i]->x;
-      float dy = container->content_y + crossOffset - items[i]->y;
+      float dx = cursor + items[i]->margin_left - items[i]->x;
+      float dy = container->content_y + crossOffset + items[i]->margin_top - items[i]->y;
       translate(items[i], dx, dy);
       cursor += mainSizes[i] + between;
     }
@@ -111,6 +115,7 @@ float Layouter::layoutFlex(LayoutBox *container, float contentWidth, float defin
   std::vector<float> outer(count, 0.0f);
   float sumBase = 0;
   for (size_t i = 0; i < count; i++) {
+    setContainingBlock(items[i], containingBlockAncestor(items[i]));
     layoutBlock(items[i], container->content_x, container->content_y, contentWidth, definiteHeight);
     outer[i] = verticalEdges(items[i]) + items[i]->height;
     sumBase += outer[i];
@@ -142,8 +147,11 @@ float Layouter::layoutFlex(LayoutBox *container, float contentWidth, float defin
   float cursor = container->content_y + offset;
   for (size_t k = 0; k < count; k++) {
     size_t i = reverse ? (count - 1 - k) : k;
-    float dx = container->content_x - items[i]->x;
-    float dy = cursor - items[i]->y;
+    float dx = container->content_x + items[i]->margin_left - items[i]->x;
+    /* Margins keep the item's outer box on the main axis, exactly like block
+     * flow — a negative `margin-top` pulls the item up instead of being
+     * silently dropped. */
+    float dy = cursor + items[i]->margin_top - items[i]->y;
     translate(items[i], dx, dy);
     cursor += mainSizes[i] + between;
   }