xbintsc 0.3.35 → 0.3.49

package/doc/ai/zh-CN/troubleshooting.md

@@ -0,0 +1,150 @@
+# 排错指南
+
+先跑这条命令，看 xbintsc 到底解析到了什么：
+
+```bash
+xbintsc doctor
+```
+
+它会打印平台、将要使用的工具链（以及来源）、编译器版本、运行时目录、运行时库目录
+与图标资源编译器。绝大多数"跑不起来"的答案都在这里。
+
+## 首先确认：clang 够新吗？
+
+**需要 clang/LLVM 16 或更新。** 更老的 clang 会以有类型指针（typed pointer）错误
+拒绝生成的 IR：
+
+```
+D:\...\build\app.ll:382:37: error: '@.str.0' defined with type '[6 x i8]*' but expected 'i8*'
+  %r0 = call i64 @xt_string_new(i8* @.str.0, i64 5)
+```
+
+编译器生成的 LLVM IR 依赖不透明指针（opaque pointers），而有类型指针在 LLVM 16
+中被移除（[LLVM 发布说明](https://github.com/llvm/llvm-project/blob/release/15.x/llvm/docs/ReleaseNotes.rst#changes-to-the-llvm-ir)）。
+用 `clang --version` 确认；如果机器上的系统 clang 太旧，装一个新版 LLVM 并让 xbintsc
+用它：
+
+```powershell
+$env:xbintsc_CLANG = "C:\Program Files\LLVM\bin\clang.exe"
+```
+
+```bash
+export xbintsc_CLANG=/usr/lib/llvm-18/bin/clang
+```
+
+注意：只做前端工作（`xbintsc emit`）完全不需要 clang，所以在旧工具链上它照常可用。
+
+## 报错信息对照
+
+### `module '…' is provided by the 'node' extension; pass --ext node`
+
+程序导入了 Node 模块但扩展没开。加上参数，或写进 `xbintsc.config.json` 让它始终生效：
+
+```bash
+xbintsc run app.ts --ext node
+```
+
+### `module '<pkg>' is not supported: xbintsc can import built-in platform modules, relative '.ts' files and ESM packages under node_modules; CommonJS packages are not supported`
+
+一个没人认领、也链不进来的裸第三方导入。要么该包是 CommonJS（不支持），要么它是
+打包失败的 ESM 包。优先改用 `node` 扩展提供的 Node 内置模块；可打包的范围见
+[extensions.md](./extensions.md)。
+
+### ``CommonJS `require()` is not supported``
+
+改写为 ESM：`const fs = require("fs")` 变成 `import fs from "fs"`（并加
+`--ext node`）。`node_modules` 包内部的 `require` 由打包器处理；只有你自己的源码里
+会被拒绝。`require(<非常量表达式>)` 永远不支持。
+
+### `error TS4005: xbintsc does not yet support this <construct>`
+
+语法解析通过了，但代码生成没实现。查 [language-support.md](./language-support.md) 与
+[../../zh-CN/unimplemented.md](../../zh-CN/unimplemented.md)，然后改写该构造（或者
+贡献实现）。常见的是 `namespace` 声明与 `new.target`。
+
+### `error TS2xxx`（语法分析）或 `error TS1xxx`（词法分析）
+
+源码语法错误。诊断会打印文件、行、列、出错的那一行以及插入符。注意 xbintsc 的
+解析器接受绝大多数 TypeScript，所以语法错误通常意味着语法真的坏了，而不是"不支持"。
+
+### `error TS6001: Cannot resolve module './x' from '<file>'` / `Cannot find module`
+
+相对导入解析不到。`./helper.js` 说明符会映射到 `helper.ts`，所以要按你实际写的
+TypeScript 运行时路径导入。
+
+### `Cannot resolve module '…' required from '<file>'`
+
+被打包的 `node_modules` 包内部的 `require(...)` 无法解析。该包不能直接用；请优先
+使用内置模块或换一个依赖。
+
+### `xbintsc: <config path>: invalid JSON (…)` / `Unable to read …`
+
+项目配置或原生扩展清单格式错误或不存在。修好 JSON，或用 `--no-config` /
+`--config <path>` 绕开自动发现。
+
+### `error TS6003` / `Command failed (N): clang …`
+
+clang 自身失败。抛出的消息包含完整的 clang 命令与 stderr——请读 stderr，不要只看
+第一行。常见原因：
+
+- 工具链太旧（见上文）；
+- Windows 上 clang 因为环境没导入而找不到 MSVC/SDK 头文件或库。请在
+  **x64 Native Tools Command Prompt for VS 2022**（ARM64 机器上是 **ARM64 Native
+  Tools**）里运行，或先导入环境：
+  ```powershell
+  & "$env:ProgramFiles\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
+  ```
+- Linux 上链接器不对——设置 `xbintsc_CLANG`，并/或传
+  `xbintsc_LINKER_ARGS=-fuse-ld=lld`；
+- `No C compiler found. Set xbintsc_CLANG to a clang binary.` —— `PATH` 里完全没有
+  clang。
+
+### `GUI native library not found at …`
+
+`gui` 扩展需要各平台预编译的 `gui.a`/`gui.lib`，普通源码检出并没有构建它。去掉
+`--ext gui`，或按 [../../zh-CN/gui.md](../../zh-CN/gui.md) 构建该归档。
+
+### `Icon file not found` / 图标工具缺失
+
+`--icon`/`app.icon` 的路径相对配置文件目录解析。Windows 上嵌入 PE 图标需要
+`llvm-rc` 或 `windres`；`doctor` 会报告找到了哪个，只有在确实请求了图标时缺失才是
+致命错误。
+
+## 看起来不对、其实正常的构建行为
+
+### 构建打印了 `(cached)` 并什么都没做
+
+增量缓存命中了：源码哈希、编译器版本、选项、平台与扩展集合都没变，且所有产物都还在。
+这正是设计目标。要强制重建就用 `--force`。
+
+### 改了参数后产物是旧的
+
+对象缓存的键刻意不含编译参数，这正是那些会改参数的脚本（如运行时覆盖率）使用独立
+`xbintsc_CACHE_DIR` 的原因。如果怀疑产物过期，传 `--force` 或删掉 `.xbintsc/`。
+
+### `run` 返回非零但没有错误信息
+
+`run` 透传的是**被运行程序**的退出码，编译器本身成功了。直接跑 `./build/app` 看程序
+自己的输出。
+
+### `xbintsc: run requires --emit exe`
+
+`run` 只能执行可执行文件。要看 IR 请用 `build --emit ir` 或 `emit`。
+
+### 程序输出顺序出乎意料
+
+`async`/`await` 是同步微任务模型，且事件循环只在程序主体之后运行，所以定时器和套接字
+回调会晚触发；见 [language-support.md](./language-support.md)。
+
+## 该去源码哪里看
+
+| 症状 | 源码 |
+| --- | --- |
+| 某条诊断文本或代码 | [../../../src/diagnostics/diagnostic.ts](../../../src/diagnostics/diagnostic.ts)，以及 `src/` 下的发出点 |
+| 某个特性缺失 | [../../../src/codegen/](../../../src/codegen/) —— `UnsupportedFeature` 在那里抛出 |
+| 导入解析不了 | [../../../src/driver/bundler/](../../../src/driver/bundler/) |
+| clang 调用、链接参数 | [../../../src/driver/toolchain.ts](../../../src/driver/toolchain.ts)、[../../../src/driver/toolchain-provider.ts](../../../src/driver/toolchain-provider.ts) |
+| 缓存行为 | [../../../src/driver/cache.ts](../../../src/driver/cache.ts) |
+| 运行时崩溃、GC、值 | `runtime/*.c`、`runtime/rt.h` |
+
+如果你要改的是编译器本身而不是用它，接着读 [contributing.md](./contributing.md)。

package/doc/gui-scripts.md

@@ -0,0 +1,350 @@
+# GUI extension — DOM handles, events and AOT `<script>`
+
+Status: **design** — this document specifies how the `gui` extension grows from
+read-only HTML/CSS rendering (M7) into a small, *interactive* DOM with
+**compile-time (AOT) scripts**, without adding a JavaScript engine and without
+letting GUI concerns leak into the core compiler.
+
+It is the plan behind milestones **M8** (DOM object model + mutation + element
+events) and **M9** (AOT `<script>` pipeline). The locked decisions in
+`doc/gui.md` still hold; this document only refines what "no page JS" means.
+
+## Motivation
+
+Today the engine renders an HTML/CSS tree and exposes only *window-level*
+events (`win.on("click", …)`). The handler receives `e.target` as a CSS
+descriptor string (`div#main.card`), the DOM is read-only (diagnostics only),
+and the only way to change the UI is `win.loadHTML(...)`, which rebuilds
+everything.
+
+That is enough for static demos, but the obvious next question — "can I write
+`<script>` and react to clicks on a specific element?" — has no answer yet.
+xbintsc is a **pure AOT compiler** and has **no runtime interpreter/JIT**, so
+`eval`-style script execution is impossible. The only self-consistent way to
+run scripts is to **compile them ahead of time**.
+
+## Goals
+
+1. **Element handles** — `document.querySelector(...)` returns an object with
+   stable identity (`a === b` for the same element) and readable/writable DOM
+   properties (`id`, `className`, `textContent`, `innerHTML`, `style`,
+   `classList`, attributes, traversal, geometry).
+2. **Mutation** — `appendChild` / `removeChild` / `insertBefore` /
+   `replaceChild` / `textContent=` / `innerHTML=` / `classList.*` /
+   `style.setProperty` update the tree; the engine restyles + relayouts lazily
+   and repaints.
+3. **Element events** — `el.addEventListener(type, fn, options?)` with capture
+   and bubble phases, `removeEventListener`, `dispatchEvent`, `el.click()`,
+   event objects with `target` / `currentTarget` / `preventDefault` /
+   `stopPropagation`.
+4. **AOT `<script>`** — a `<script>` body written in TypeScript is extracted at
+   **compile time**, compiled by the *existing* xbintsc front-end as a normal
+   module, and invoked by the engine after the document is parsed.
+5. **Zero core-compiler coupling** — the lexer/parser/binder/codegen learn
+   nothing about HTML or the GUI. Extensions contribute only modules/objects
+   (and, new in M9, an **asset-loader hook**).
+6. **Backward compatibility** — existing programs and tests keep working:
+   `win.on(...)` handlers keep receiving a *string* `e.target`.
+
+## Non-goals
+
+- **A JS engine** (QuickJS/V8/…). Still explicitly out of scope. There is no
+  runtime `eval`, no interpreter, no JIT.
+- **Dynamic scripts at runtime.** Scripts are compile-time assets. HTML fetched
+  over the network or produced at runtime does **not** execute its scripts.
+- **A security sandbox / browser semantics.** There is no origin model; a
+  script is ordinary native TS and can `import` anything the compiler allows.
+  This is documented as "not a browser".
+- **Full DOM/BOM.** We implement the practical subset a UI needs.
+
+## Locked decisions (refined)
+
+| # | Decision |
+| --- | --- |
+| 1 | **No page JS engine.** Behaviour is native TS. `<script>` bodies are *AOT-compiled* to native code by xbintsc and invoked through `xt_call_with_this` — there is still no interpreter. |
+| 8 | **Scripts are compile-time assets.** The HTML asset loader transforms inline `<script>` bodies into compiled modules and replaces them with `data-xt-id` markers; the runtime only *invokes* already-compiled functions. |
+| 9 | **The DOM is owned by the engine; handles are engine objects.** Handles use the same shared-prototype object model as window handles; hidden fields carry a window reference, a document generation and a node index. |
+| 10 | **`window`/`document` are injected as parameters**, not globals, so no global-object machinery is added to the compiler. |
+
+## Architecture
+
+```
+     <script>…</script>            compile time (bundler)
+            │  gui .html asset loader
+            ▼
+   ┌──────────────────────┐        ┌───────────────────────────┐
+   │ transform the HTML   │        │ emit  __xt_script_<hash>  │  a normal
+   │ body → function      │        │       (window, document)  │  xbintsc
+   │ <script data-xt-id>  │        │ + __registerScript(hash)  │  module
+   └──────────────────────┘        └───────────────────────────┘
+            │                                   │
+            ▼                                   ▼
+     runtime HTML string              native code linked into the binary
+            │  win.loadHTML(html)
+            ▼
+   engine parses HTML, finds `data-xt-id` markers, looks each hash up in the
+   script registry and calls `fn(windowHandle, documentHandle)`
+```
+
+### 1. `Extension.assetLoaders` (the only new core hook)
+
+The core compiler currently has no way for an extension to influence *how a
+file is loaded*. M9 adds one generic hook to `src/extensions/registry.ts`:
+
+```ts
+interface AssetLoadResult {
+  /** Replaces the file contents as seen by the bundler. */
+  moduleSource: string;
+  /** Additional files this asset depends on (recompiled when they change). */
+  dependencies?: string[];
+}
+
+interface Extension {
+  // …existing fields…
+  /** Optional: rewrite an imported asset into a TS module. Keyed by extension. */
+  assetLoaders?(): Record<string, (path: string, source: string) => AssetLoadResult>;
+}
+```
+
+The bundler (`src/driver/bundler/graph.ts`) consults the registry immediately
+after `readFileSync`, *before* parsing. The core stays platform-agnostic: it
+only knows "an extension may transform the bytes of `*.foo` into TS".
+The `gui` extension registers an `.html` loader. A plain `import html from
+"./index.html"` therefore yields a **string constant** by default, and (when
+the file contains `<script>`) a **side-effecting module** that registers the
+compiled script bodies and default-exports the rewritten HTML.
+
+### 2. The `.html` transform
+
+Given:
+
+```html
+<button id="b">0</button>
+<script lang="ts">
+  const b = document.getElementById("b");
+  let n = 0;
+  b.addEventListener("click", () => { b.textContent = String(++n); });
+</script>
+```
+
+the loader emits a module shaped like:
+
+```ts
+// generated
+const __html = "<button id=\"b\">0</button>\n<script data-xt-id=\"a1b2…\"></script>";
+function __xt_script_a1b2(window: any, document: any): void {
+  const b = document.getElementById("b");
+  let n = 0;
+  b.addEventListener("click", () => { b.textContent = String(++n); });
+}
+__registerScript("a1b2…", __xt_script_a1b2);
+export default __html;
+```
+
+- The id is a content hash of the body (sha256, first 32 hex chars); the body is
+  replaced by an empty marker element so the engine can find it in document
+  order.
+- `window` and `document` are **function parameters**, so script globals resolve
+  as ordinary locals — **no compiler changes**, no global object.
+- `__registerScript(id, fn)` is a new runtime builtin that stores the closure in
+  a global `unordered_map<string, xt_value>`.
+- Deferred scripts (`<script defer>`, or all inline scripts, as decided in M9c)
+  run after the full document is parsed and the first layout is computed, in
+  document order. `DOMContentLoaded` then `load` are fired on `window`.
+
+### 2b. External `<script src>`
+
+`<script src="./app.ts">` is read relative to the HTML file, parsed, and split:
+its top-level `import`/`export … from` statements are **hoisted** to the
+generated module (with relative specifiers rewritten so they resolve from the
+HTML file's directory), and the remaining statements are wrapped in the script
+function. This is how an external script still runs at `loadHTML` time while
+being able to `import` other modules.
+
+Two limitations are enforced with clear errors rather than silent breakage:
+
+- a missing `src` file throws (turned into a bundler diagnostic), and
+- two `src` scripts that import the same local binding name collide; the user
+  must alias one of them. (Non-conflicting or identical imports are fine.)
+
+`src` URLs (`https://…`, `data:…`, `//host`) are left untouched — they are not
+compile-time assets and never run.
+
+```html
+<button id="b">0</button>
+<script src="./counter.ts"></script>
+```
+
+```ts
+// counter.ts
+import { double } from "./helper";
+const b = document.getElementById("b");
+let n = 0;
+b.addEventListener("click", () => { n = double(n) + 1; b.textContent = String(n); });
+```
+
+### 3. Runtime execution
+
+`win.loadHTML(html)`:
+
+1. parses the document as today,
+2. scans for `data-xt-id` markers,
+3. for each, calls `registry[id](winHandle, docHandle)`,
+4. triggers the first layout, then fires `DOMContentLoaded` and `load`.
+
+Because the calls happen after parsing, `document.getElementById(...)` inside a
+script always finds its element. `innerHTML = …` never executes embedded
+scripts (markers are inert).
+
+## Element handle object model (M8)
+
+Handles are plain runtime objects (`xt_object_new_with_proto`) sharing a
+prototype per kind, exactly like window handles:
+
+| Hidden field | Meaning |
+| --- | --- |
+| `__xt_gui_win` | owning window object (resolved by `xt_gui_window_from_this`) |
+| `__xt_gui_gen` | document generation the handle was created for |
+| `__xt_gui_node` | index into the window's node table (element/text handles) |
+| `__xt_gui_doc` | `true` for the singleton `document` handle |
+
+**Identity is stable**: the window keeps `node_order: vector<Node*>` plus
+`node_index`/`node_handles: map<Node*, …>`, so querying the same element twice
+returns the *same* object value (`a === b`).
+
+**Detached nodes** stay alive in the document pool, so a handle held across a
+`remove()` still resolves (tombstoned semantics); a generation mismatch makes a
+stale handle a no-op instead of a dangling pointer.
+
+### Accessors, not fields
+
+Read/write DOM properties are defined with `xt_object_define_getter` /
+`xt_object_define_setter`, which already support prototype inheritance with
+`this` = receiver. So `el.textContent = "x"` and `el.id = "y"` work while the
+values live in the C++ tree. `classList` and `style` are small objects that hold
+a back-reference to the element handle (no closures/env needed; the arena never
+frees, so cycles are harmless).
+
+### Implemented surface (M8)
+
+- `document`: `querySelector`, `querySelectorAll`, `getElementById`,
+  `createElement`, `createTextNode`, `body`, `documentElement`,
+  `addEventListener` / `removeEventListener` / `dispatchEvent`.
+- node (element/text/document): `tagName` / `nodeName` / `nodeType`, `id`,
+  `className`, `textContent` / `innerText`, `innerHTML`, `parentNode` /
+  `parentElement`, `children` / `childNodes` / `childElementCount`,
+  `firstElementChild` / `lastElementChild`, `nextElementSibling` /
+  `previousElementSibling`, `isConnected`, `classList`, `style`.
+- attributes: `getAttribute` / `setAttribute` / `hasAttribute` /
+  `removeAttribute`.
+- queries: `querySelector` / `querySelectorAll` / `matches` (subtree-scoped).
+- mutation: `appendChild` / `insertBefore` / `removeChild` / `replaceChild` /
+  `remove` / `cloneNode(deep?)`.
+- geometry/focus: `getBoundingClientRect`, `focus`, `blur`, `click`.
+- events: `addEventListener(type, fn, optionsOrCapture?)`,
+  `removeEventListener`, `dispatchEvent`.
+
+### Lazy restyle / relayout
+
+Every mutation calls `XtDocument::invalidate()` and sets `win->struct_dirty`.
+Before any synchronous read (`computedStyle`, `getBoundingClientRect`,
+`queryCount`, `layoutTree`, `paintList`, `hitTest`, …) and before each frame,
+`xt_gui_flush_dom()` restyles + relayouts **once** if anything is pending. This
+keeps mutations cheap and batched while making reads immediately consistent.
+
+## Events and bubbling
+
+Element listeners are stored on the window (`node_listeners`), keyed by node
+(not on `Node` itself, so the tree stays layout-focused).
+
+Dispatch:
+
+1. build the propagation path `target → … → root`,
+2. create an Event object (`type`, `target` = node handle, `currentTarget`,
+   `bubbles`, `defaultPrevented`, internal `__stop` / `__stopImmediate`),
+3. **capture** phase: root → target (listeners registered with `capture: true`),
+4. **bubble** phase: target → root,
+5. legacy window-level `win.on(type, fn)` handlers run **last**.
+
+`once` listeners are removed before being called; `stopPropagation` ends the
+current phase chain and `stopImmediatePropagation` also skips later listeners on
+the same node. `el.click()` synthesises `click` at that node (DOM only);
+real pointer/wheel/key input dispatches **both** the DOM event and the legacy
+window payload.
+
+### Backward compatibility
+
+The legacy window payload keeps its **string** `e.target`
+(`tests/e2e/gui-*.test.ts` asserts `e.target === "div#inner"`). Only the *element*
+Event's `target` is a handle, whose descriptor (`toString`) matches the same
+`div#id.class` string. `make_dom_event` deliberately does **not** copy the
+legacy `target` field over the handle.
+
+## Milestones
+
+- **M8 — DOM object model + mutation + element events** ✅
+  - `runtime/ext_gui/dom_api.{h,cpp}`, `document.{h,cpp}`, `dom.{h,cpp}`,
+    `gui_engine.h`, `gui.cpp`, `window.cpp`, e2e coverage.
+  - No compiler changes; independently testable.
+- **M9 — AOT `<script>`** ✅
+  - **M9a** ✅ — `Extension.assetLoaders` in `src/extensions/registry.ts` +
+    bundler integration in `src/driver/bundler/{graph,merge}.ts`; unit tests.
+  - **M9b** ✅ — gui `.html` loader (`src/extensions/gui/html.ts`), the
+    `__registerScript` builtin, the script registry (`runtime/ext_gui/script.cpp`),
+    `loadHTML` execution and `DOMContentLoaded`/`load`; e2e coverage.
+  - **M9c** ✅ — `<script src>` files are read, their top-level imports are
+    hoisted (specifiers rewritten to resolve from the HTML file) and their body
+    is wrapped and registered; missing files and import-binding collisions
+    surface as diagnostics. All scripts run in document order (effectively
+    deferred). e2e coverage.
+  - **M9d** *(optional)* — detect inline HTML in template literals passed to
+    `win.loadHTML(...)` and transform them too (fragile; deferred).
+- **M10 — polish** ✅ — `requestAnimationFrame`/`cancelAnimationFrame` on the
+  window, `offsetWidth`/`offsetHeight`/`contains` on elements, docs.
+
+### Landing order
+
+1. M8 (this branch) — pure engine work, no compiler impact.
+2. M9a — the generic hook + bundler wiring (unit-testable with a fake loader).
+3. M9b — the minimal end-to-end script path (inline `<script>` only).
+4. M9c — external `<script src>`.
+5. M10 — animation frames and helpers.
+
+## Open risks
+
+- **Handle lifetime.** Solved with a generation counter + detached pool; stale
+  handles no-op. `Node*` addresses are never exposed to TS.
+- **No sandbox.** A `<script>` can `import fs`. Documented as "not a browser";
+  a real origin/sandbox model is out of scope.
+- **Dynamic HTML scripts.** Scripts in runtime-created HTML (`innerHTML`,
+  network fetches) do not run. Documented.
+- **Template-literal HTML** passed to `win.loadHTML(…)` is not transformed in
+  M9b (only imported assets are). M9d addresses this if needed.
+- **Import-binding collisions** between external `<script src>` files. Detected
+  and reported (alias the import); a per-script rename with reference rewriting
+  is possible later.
+- **Assets.** `<script src>` is resolved relative to the HTML asset; URL `src`
+  values are ignored. There is no fetch/network loading.
+
+## Testing
+
+- **M8**: a new e2e case in `tests/e2e/gui-*.test.ts` covering handle identity,
+  traversal, attributes, `classList`, inline `style`, `createElement` +
+  `appendChild` + `removeChild`, `getBoundingClientRect`, element bubbling,
+  `stopPropagation`, `el.click()` and **window-level `e.target` compatibility**.
+- **M9a**: a unit test with a fake extension loader asserting the bundler
+  rewrites `*.foo` and records dependencies.
+- **M9b**: an e2e case with an inline `<script>` incrementing a counter on
+  click, asserted through `console.log` from the handler.
+- **M10**: e2e cases for `requestAnimationFrame` (runs each frame, re-queues,
+  receives a timestamp, honours `cancelAnimationFrame`) and for
+  `offsetWidth`/`offsetHeight`/`contains`.
+
+## Docs to update
+
+- `doc/gui.md` — Non-goals ("Executing page `<script>`" → "Executing *runtime*
+  page scripts; compile-time scripts are AOT-compiled"), locked decision #1,
+  TS-facing API, milestones, progress log.
+- `doc/implemented.md` / `doc/unimplemented.md` — move the new DOM/script
+  capabilities across.
+- `README.md` — mention the DOM API + AOT scripts.