xbintsc 0.3.46 → 0.3.49

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.49",
   "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/gui.cpp

@@ -73,7 +73,9 @@ static int ensure_init(void) {
     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);

package/runtime/ext_gui/renderer.cpp

@@ -130,30 +130,32 @@ bool xt_gui_renderer_ensure(SDL_GPUDevice *device, SDL_Window *reference) {
   using namespace xtgui::renderer_detail;
   if (g_pipeline != nullptr) return true;
   if (g_renderer_failed) return false;
-  if ((SDL_GetGPUShaderFormats(device) & SDL_GPU_SHADERFORMAT_MSL) == 0) {
+  const ShaderSource fill_vs = selectShader(device, ShaderProgram::Fill, false);
+  const ShaderSource fill_fs = selectShader(device, ShaderProgram::Fill, true);
+  if (!fill_vs.valid() || !fill_fs.valid()) {
     fprintf(stderr,
-            "xt_gui: backend has no MSL shader support; shape/text painting disabled "
-            "(Vulkan/D3D12 shader blobs are a TODO)\n");
+            "xt_gui: backend supports neither Metal nor D3D12 shaders; shape/text painting "
+            "disabled (Vulkan SPIR-V blobs are a TODO)\n");
     g_renderer_failed = 1;
     return false;
   }
 
   SDL_GPUShaderCreateInfo vs_info;
   memset(&vs_info, 0, sizeof(vs_info));
-  vs_info.code_size = strlen(kFillMSL);
-  vs_info.code = (const Uint8 *)kFillMSL;
-  vs_info.entrypoint = "vs_main";
-  vs_info.format = SDL_GPU_SHADERFORMAT_MSL;
+  vs_info.code_size = fill_vs.size;
+  vs_info.code = fill_vs.code;
+  vs_info.entrypoint = fill_vs.entry;
+  vs_info.format = fill_vs.format;
   vs_info.stage = SDL_GPU_SHADERSTAGE_VERTEX;
   vs_info.num_uniform_buffers = 1;
   SDL_GPUShader *vs = SDL_CreateGPUShader(device, &vs_info);
 
   SDL_GPUShaderCreateInfo fs_info;
   memset(&fs_info, 0, sizeof(fs_info));
-  fs_info.code_size = strlen(kFillMSL);
-  fs_info.code = (const Uint8 *)kFillMSL;
-  fs_info.entrypoint = "fs_main";
-  fs_info.format = SDL_GPU_SHADERFORMAT_MSL;
+  fs_info.code_size = fill_fs.size;
+  fs_info.code = fill_fs.code;
+  fs_info.entrypoint = fill_fs.entry;
+  fs_info.format = fill_fs.format;
   fs_info.stage = SDL_GPU_SHADERSTAGE_FRAGMENT;
   SDL_GPUShader *fs = SDL_CreateGPUShader(device, &fs_info);
 

package/runtime/ext_gui/renderer_image.cpp

@@ -17,22 +17,26 @@ namespace xtgui {
 namespace renderer_detail {
 
 SDL_GPUGraphicsPipeline *createImagePipeline(SDL_GPUDevice *device, SDL_Window *reference) {
+  const ShaderSource image_vs = selectShader(device, ShaderProgram::Image, false);
+  const ShaderSource image_fs = selectShader(device, ShaderProgram::Image, true);
+  if (!image_vs.valid() || !image_fs.valid()) return nullptr;
+
   SDL_GPUShaderCreateInfo vs_info;
   memset(&vs_info, 0, sizeof(vs_info));
-  vs_info.code_size = strlen(kTextMSL);
-  vs_info.code = (const Uint8 *)kTextMSL;
-  vs_info.entrypoint = "vs_text";
-  vs_info.format = SDL_GPU_SHADERFORMAT_MSL;
+  vs_info.code_size = image_vs.size;
+  vs_info.code = image_vs.code;
+  vs_info.entrypoint = image_vs.entry;
+  vs_info.format = image_vs.format;
   vs_info.stage = SDL_GPU_SHADERSTAGE_VERTEX;
   vs_info.num_uniform_buffers = 1;
   SDL_GPUShader *vs = SDL_CreateGPUShader(device, &vs_info);
 
   SDL_GPUShaderCreateInfo fs_info;
   memset(&fs_info, 0, sizeof(fs_info));
-  fs_info.code_size = strlen(kTextMSL);
-  fs_info.code = (const Uint8 *)kTextMSL;
-  fs_info.entrypoint = "fs_image";
-  fs_info.format = SDL_GPU_SHADERFORMAT_MSL;
+  fs_info.code_size = image_fs.size;
+  fs_info.code = image_fs.code;
+  fs_info.entrypoint = image_fs.entry;
+  fs_info.format = image_fs.format;
   fs_info.stage = SDL_GPU_SHADERSTAGE_FRAGMENT;
   fs_info.num_samplers = 1;
   SDL_GPUShader *fs = SDL_CreateGPUShader(device, &fs_info);

package/runtime/ext_gui/renderer_shaders.h

@@ -1,13 +1,39 @@
 /*
- * xbintsc GUI engine — SDL_GPU Metal (MSL) shader sources.
+ * xbintsc GUI engine — shader sources.
  *
- * Shared by `renderer.cpp` (fills), `renderer_text.cpp` (glyphs) and
- * `renderer_image.cpp` (images). Text and image quads reuse `kTextMSL`; only
- * the fragment entry point differs (`fs_text` vs `fs_image`).
+ * `renderer.cpp` (fills), `renderer_text.cpp` (glyphs) and `renderer_image.cpp`
+ * (images) each build one SDL_GPU graphics pipeline. Three shader families back
+ * them, one per SDL_GPU backend:
+ *
+ *   - Metal: the MSL string literals below, which SDL_GPU compiles at runtime.
+ *   - Vulkan: SPIR-V blobs in `renderer_shaders_data.h`, compiled from
+ *     `spirv/*.{vert,frag}` by `scripts/build-gui-shaders.mjs`.
+ *   - Direct3D 12: DXIL blobs from the same header, compiled from `shaders.hlsl`.
+ *
+ * `selectShader` resolves a logical program and stage to whichever of those the
+ * device accepts. The backend rejects any other format, so a missing blob means
+ * "no pipeline", never a mismatched one.
+ *
+ * Text and image quads share the vertex program; only the fragment entry point
+ * differs (`fs_text` vs `fs_image`).
+ *
+ * Note the entry-point names differ per format: MSL/DXIL keep the descriptive
+ * names from their sources, while glslc emits the GLSL `main`.
  */
 #ifndef XT_GUI_RENDERER_SHADERS_H
 #define XT_GUI_RENDERER_SHADERS_H
 
+#include <SDL3/SDL.h>
+#include <cstring>
+
+#include "renderer_shaders_data.h"
+
+namespace xtgui {
+namespace renderer_detail {
+
+/** The three pipeline programs the engine builds. */
+enum class ShaderProgram { Fill, Text, Image };
+
 /* Rounded-rectangle fill. Vertex attributes (matching SDL_GPUVertexAttribute):
  *   0 -> position (pixels, viewport-relative)
  *   1 -> local   (pixels, relative to the rectangle centre)
@@ -105,4 +131,105 @@ fragment float4 fs_image(TextOut in [[stage_in]],
 }
 )MSL";
 
+/** One stage of one pipeline program, in whichever format the device accepts. */
+struct ShaderSource {
+  SDL_GPUShaderFormat format = 0;
+  const unsigned char *code = nullptr;
+  size_t size = 0;
+  const char *entry = nullptr;
+
+  bool valid() const { return code != nullptr; }
+};
+
+/** The MSL text backing `program` (one literal covers both stages). */
+inline const char *mslSource(ShaderProgram program) {
+  return program == ShaderProgram::Fill ? kFillMSL : kTextMSL;
+}
+
+/** MSL entry point names for `program`, matching the literals below. */
+inline const char *vertexEntry(ShaderProgram program) {
+  return program == ShaderProgram::Fill ? "vs_main" : "vs_text";
+}
+
+inline const char *fragmentEntry(ShaderProgram program) {
+  if (program == ShaderProgram::Fill) return "fs_main";
+  return program == ShaderProgram::Text ? "fs_text" : "fs_image";
+}
+
+/** A blob pair for one shader format: bytes plus the entry-point names it uses.
+ * The names are stored in `ShaderSource` rather than resolved at the call site
+ * because cross-compilers rename entry points (glslc emits `main`, dxc keeps the
+ * HLSL name, MSL keeps the Metal name). */
+struct ShaderBlobs {
+  const unsigned char *vertex;
+  size_t vertex_size;
+  const char *vertex_entry;
+  const unsigned char *fragment;
+  size_t fragment_size;
+  const char *fragment_entry;
+};
+
+/** SPIR-V blobs for `program` (Vulkan). glslc names every entry point `main`. */
+inline ShaderBlobs spirvBlobs(ShaderProgram program) {
+  switch (program) {
+    case ShaderProgram::Fill:
+      return {kFillSpirvVs, kFillSpirvVsSize, "main", kFillSpirvFs, kFillSpirvFsSize, "main"};
+    case ShaderProgram::Text:
+      return {kTextSpirvVs, kTextSpirvVsSize, "main", kTextSpirvFs, kTextSpirvFsSize, "main"};
+    case ShaderProgram::Image:
+      return {kTextSpirvVs, kTextSpirvVsSize, "main", kImageSpirvFs, kImageSpirvFsSize, "main"};
+  }
+  return {nullptr, 0, nullptr, nullptr, 0, nullptr};
+}
+
+/** DXIL blobs for `program` (Direct3D 12); one blob per entry point. */
+inline ShaderBlobs dxilBlobs(ShaderProgram program) {
+  switch (program) {
+    case ShaderProgram::Fill:
+      return {kFillDxilVs, kFillDxilVsSize, "vs_main", kFillDxilFs, kFillDxilFsSize, "fs_main"};
+    case ShaderProgram::Text:
+      return {kTextDxilVs, kTextDxilVsSize, "vs_text", kTextDxilFs, kTextDxilFsSize, "fs_text"};
+    case ShaderProgram::Image:
+      return {kTextDxilVs, kTextDxilVsSize, "vs_text", kImageDxilFs, kImageDxilFsSize, "fs_image"};
+  }
+  return {nullptr, 0, nullptr, nullptr, 0, nullptr};
+}
+
+/** MSL for `program`: a single source holds both stages, so it is expressed as a
+ * blob pair sharing one buffer. */
+inline ShaderBlobs mslBlobs(ShaderProgram program) {
+  const char *msl = mslSource(program);
+  const size_t size = strlen(msl);
+  const unsigned char *code = (const unsigned char *)msl;
+  return {code, size, vertexEntry(program), code, size, fragmentEntry(program)};
+}
+
+/** Resolve `program`'s vertex and fragment stages to shaders the device accepts.
+ * Returns an invalid source when the backend supports none of the formats the
+ * engine ships. */
+inline ShaderSource selectShader(SDL_GPUDevice *device, ShaderProgram program, bool fragment) {
+  ShaderSource source;
+  const SDL_GPUShaderFormat formats = SDL_GetGPUShaderFormats(device);
+  ShaderBlobs blobs;
+  if ((formats & SDL_GPU_SHADERFORMAT_MSL) != 0) {
+    source.format = SDL_GPU_SHADERFORMAT_MSL;
+    blobs = mslBlobs(program);
+  } else if ((formats & SDL_GPU_SHADERFORMAT_SPIRV) != 0) {
+    source.format = SDL_GPU_SHADERFORMAT_SPIRV;
+    blobs = spirvBlobs(program);
+  } else if ((formats & SDL_GPU_SHADERFORMAT_DXIL) != 0) {
+    source.format = SDL_GPU_SHADERFORMAT_DXIL;
+    blobs = dxilBlobs(program);
+  } else {
+    return source;
+  }
+  source.code = fragment ? blobs.fragment : blobs.vertex;
+  source.size = fragment ? blobs.fragment_size : blobs.vertex_size;
+  source.entry = fragment ? blobs.fragment_entry : blobs.vertex_entry;
+  return source;
+}
+
+}  // namespace renderer_detail
+}  // namespace xtgui
+
 #endif /* XT_GUI_RENDERER_SHADERS_H */