xbintsc 0.5.52 → 0.6.9

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

@@ -6,8 +6,9 @@
 xbintsc doctor
 ```
 
-它会打印平台、将要使用的工具链（以及来源）、编译器版本、运行时目录、运行时库目录
-与图标资源编译器。绝大多数"跑不起来"的答案都在这里。
+它会打印平台、将要使用的工具链（以及来源）、编译器版本、运行时目录、运行时库目录、
+支持的平台下限与图标资源编译器；macOS 上还会打印交给 clang 的 SDK。绝大多数
+"跑不起来"的答案都在这里。
 
 ## 首先确认：clang 够新吗？
 
@@ -100,11 +101,35 @@ clang 自身失败。抛出的消息包含完整的 clang 命令与 stderr——
   ```
   该脚本会导入 `vcvarsall`，并把 `xbintsc_CLANG` 指向 Visual Studio 自带的
   LLVM。直接执行 `vcvarsall.bat x64` 也仍然可行。
+- macOS 上 clang 报标准头找不到——`fatal error: 'stdio.h' file not found`、
+  `'setjmp.h' file not found` 等。macOS 没有 `/usr/include`；这些头文件在 SDK
+  里，而 clang 只有拿到 sysroot（`/usr/bin/clang` 的 shim、`-isysroot` 或
+  `SDKROOT`）才会去搜索它。xbintsc 会用 `xcrun --show-sdk-path` 解析 SDK 并以
+  `-isysroot` 传给 clang（`SDKROOT` 已设置时不覆盖），因此出现这个错误说明
+  `xcrun` 无法为选中的 Xcode 解析出 SDK：检查 `xcode-select -p` 和
+  `DEVELOPER_DIR`，并确认该 Xcode 是完整安装。消息里出现的头文件名没有意义
+  ——运行时先 include 哪个系统头，报的就是哪个。同一个缺失的 sysroot 也会在链接
+  阶段表现为 `ld: library 'm' not found`。
 - Linux 上链接器不对——设置 `xbintsc_CLANG`，并/或传
   `xbintsc_LINKER_ARGS=-fuse-ld=lld`；
 - `No C compiler found. Set xbintsc_CLANG to a clang binary.` —— `PATH` 里完全没有
   clang。
 
+### `Undefined symbols` / `LNK2038` / `was built for newer macOS version`
+
+`@xbintsc/<os>-<arch>` 里的预编译归档由比本机更新的 Xcode Command Line
+Tools/SDK 或 Visual Studio C++ 生成工具构建，链接器无法把它与本机目标文件混用。
+驱动会自动改用包内自带的源码重新编译 `core`/`ext_node` 并重试一次链接，同时打印：
+
+```text
+xbintsc: the prebuilt runtime archive does not link with this toolchain (…); compiling the C runtime from source
+```
+
+首次重试会编译 C 运行时，所以较慢；之后的构建复用缓存的目标文件。如果仍然失败，
+冲突的就是 `gui.a`/`media.a`：它们内含 SDL3/FFmpeg，npm 包里没有这些源码，无法从
+包里重编。请改用与本机工具链匹配的发布包，或在源码检出中构建（`npm run gui`、
+`npm run media`）。设置 `xbintsc_PREFER_PREBUILT=0` 可以完全跳过这次重试。
+
 ### `GUI native library not found at …`
 
 `gui` 扩展需要各平台预编译的 `gui.a`/`gui.lib`。可选的 `@xbintsc/<os>-<arch>`

package/doc/gui/build.md

@@ -45,9 +45,13 @@
   minimal static build with only the demuxers/parsers/decoders the media
   elements need, compiles `runtime/ext_media/media.cpp` against it and merges
   everything into `runtime/lib/<os>-<arch>/media.a` (`media.lib` with the MSVC
-  ABI on Windows). `gui.a` does **not** link FFmpeg: the compiler selects the
-  `media` link feature for a program that may play media and only then links
-  `media.a` (see [Link features](#link-features)).
+  ABI on Windows). The download retries the transient TLS failures the release
+  host is prone to, and the tarball is kept at
+  `vendor/ffmpeg-<version>.tar.xz` after extraction, so a rebuild (or CI, which
+  caches it by `FFMPEG_VERSION`) extracts the local copy instead of fetching it
+  again. `gui.a` does **not** link FFmpeg: the compiler selects the `media` link
+  feature for a program that may play media and only then links `media.a` (see
+  [Link features](#link-features)).
 - `src/extensions/gui/index.ts` exposes the engine archive through
   `nativeObjects()` (via `findRuntimeLibrary`, so `.a`/`.lib` both work) and the
   OS frameworks through `linkerFlags()`. Its `linkFeatures()` (in

package/doc/gui/dom.md

@@ -201,7 +201,9 @@ The two parameters (`window`, `document`) are ordinary function arguments, so
 script locals need no global-object machinery. External scripts work too:
 `<script src="./counter.ts">` is read at compile time, its imports are hoisted
 (rewritten to resolve from the HTML file) and its body is wrapped the same way —
-so a script module can `import` helpers and still see `document`. Scripts are
+so a script module can `import` helpers and still see `document`. An inline body
+goes through the same split, so `import` works identically there, `node:fs` and
+other `node:` built-ins included once the `node` extension is enabled. Scripts are
 **compile-time assets**: HTML created at runtime (`innerHTML`, fetched over the
 network) never executes, and `src` URLs (`https://…`, `data:…`) are ignored.
 Everything runs in document order after parsing (effectively deferred). See

package/doc/gui/webgl.md

@@ -337,6 +337,10 @@ SPIRV-Cross, nor any `webgl_*` member (see [Link features](./build.md#link-featu
 - `examples/gui/webgl2-cubes` draws 64 instanced cubes with one draw call,
   `#version 300 es` and a VAO; covered by
   `tests/e2e/gui-example-webgl2.test.ts`.
+- `examples/gui/pelican-3d` is a complete lit scene (procedural sky, fog,
+  instanced trees/clouds, a rigged pelican and bicycle) split across nine ES
+  modules with `AudioContext` sound; covered by
+  `tests/e2e/gui-example-pelican3d.test.ts`.
 
 These suites run against whichever backend the host selects: Vulkan on Linux
 (and Windows), Metal on macOS, so the SPIRV-Cross -> MSL path is covered by the

package/doc/gui-scripts.md

@@ -141,9 +141,10 @@ __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.
+- id is a content hash of the wrapped body (sha256, first 32 hex chars; a
+  deferred import's prelude is included, so two scripts with identical
+  statements but different imports stay distinct); 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
@@ -151,6 +152,13 @@ export default __html;
 - 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`.
+- An inline body is split into imports and statements by the **same** routine as
+  a `<script src>` file (below): top-level `import`/`export … from` statements
+  are hoisted into the generated module, relative specifiers resolve from the
+  HTML file, and `export` modifiers are stripped. `import { readFileSync } from
+  "node:fs"` inside an inline `<script>` therefore links exactly like the same
+  import in an external script — one has to enable the `node` extension, but not
+  rewrite the page.
 
 ### 2b. External `<script src>`
 
@@ -162,21 +170,21 @@ are **deferred**, like a browser module script: the loader emits a synthetic
 at `loadHTML` time. The bundler wraps the whole local import graph in functions
 that return their exports (memoised by `__xt_defer`), so top-level module code
 runs after the document exists and two scripts importing the same module share
-one instance. Bare specifiers (`gui`, a package) stay eager.
+one instance. Bare specifiers (`gui`, a package, `node:fs`) stay eager. An
+inline `<script>` body goes through the identical split, so an import behaves
+the same in both forms; the only difference is where the body comes from.
 
 A missing `src` file is still a clear error (turned into a bundler diagnostic),
 and `src` URLs (`https://…`, `data:…`, `//host`) are left untouched — they are
 not compile-time assets and never run.
 
-`src` URLs (`https://…`, `data:…`, `//host`) are left untouched — they are not
-compile-time assets and never run.
-
-A wrapped body keeps its own file as the origin of every statement in it (the
-loader reports the body's span in the generated module as a *source range*), so
-a diagnostic points at `app.js:12` rather than at a column of `index.html`, and
-a **plain-JavaScript** script stays untyped exactly like a `.js` module imported
-directly: `state.update = …` on an object literal is not a `TS4003`. A page can
-therefore ship its existing scripts unchanged.
+A wrapped `<script src>` body keeps its own file as the origin of every
+statement in it (the loader reports the body's span in the generated module as a
+*source range*), so a diagnostic points at `app.js:12` rather than at a column
+of `index.html`, and a **plain-JavaScript** script stays untyped exactly like a
+`.js` module imported directly: `state.update = …` on an object literal is not a
+`TS4003`. A page can therefore ship its existing scripts unchanged. An inline
+body's origin is the HTML page itself.
 
 ```html
 <button id="b">0</button>
@@ -308,6 +316,10 @@ legacy `target` field over the handle.
     module wrapper at `loadHTML` time, so the import graph sees a parsed
     document and shares one instance per module. Missing files surface as
     diagnostics. All scripts run in document order. e2e coverage.
+  - **M9c′** ✅ — an inline `<script>` body is split by the same routine, so an
+    `import` (a `node:`/bare specifier included) links exactly as it does in a
+    `<script src>` file. It used to be wrapped verbatim, leaving an inline
+    `import` inside the script function where codegen reported TS5001.
   - **M9d** *(optional)* — detect inline HTML in template literals passed to
     `win.loadHTML(...)` and transform them too (fragile; deferred).
 - **M10 — polish** ✅ — `requestAnimationFrame`/`cancelAnimationFrame` on the
@@ -331,11 +343,12 @@ legacy `target` field over the handle.
   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.
-- **Top-level `await`** inside a deferred `<script src>` module is not
+- **Top-level `await`** inside a deferred `<script src>` or inline script is not
   supported: the module body is wrapped in a synchronous init function.
-- **Assets.** `<script src>` is resolved relative to the HTML asset; URL `src`
-  values are ignored. The loader does not fetch network URLs; the runtime's
-  global `fetch` is a separate API.
+- **Assets.** `<script src>` is resolved relative to the HTML asset; an inline
+  body's imports resolve from the same place. URL `src` values are ignored. The
+  loader does not fetch network URLs; the runtime's global `fetch` is a separate
+  API.
 
 ## Testing
 
@@ -347,6 +360,9 @@ legacy `target` field over the handle.
   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.
+- **M9c′**: unit cases asserting an inline body's imports are hoisted (and its
+  relative ones deferred), plus an e2e case where an inline script reads a file
+  through `node:fs` and calls a deferred helper module.
 - **M10**: e2e cases for `requestAnimationFrame` (runs each frame, re-queues,
   receives a timestamp, honours `cancelAnimationFrame`) and for
   `offsetWidth`/`offsetHeight`/`contains`.

package/doc/gui.md

@@ -217,7 +217,16 @@ engine were Rust.
    - `vendor/` (SDL3/FreeType/HarfBuzz/glslang for the GUI archive, FFmpeg for `media`)
      is cached per OS/arch, keyed by `scripts/build-gui.ts` /
      `scripts/build-media.ts`. Windows x64 gets its own source cache plus the
-     installed `vendor/ffmpeg-build-msvc/dist` prefix.
+     installed `vendor/ffmpeg-build-msvc/dist` prefix. On Linux/macOS the
+     installed `vendor/ffmpeg-build/dist` prefix has its own cache, keyed by
+     `FFMPEG_VERSION` and `scripts/build-media.ts` (which owns the configure
+     flags), so a hit skips FFmpeg's configure/make instead of rebuilding it on
+     every run: `scripts/build-media.ts` stamps the prefix with the release it
+     built and discards it when either the release or the macOS deployment
+     target changes. The FFmpeg
+     release tarball additionally has a cache keyed only by `FFMPEG_VERSION` and
+     shared by every job, so ffmpeg.org's intermittent TLS handshake cannot fail
+     a run that already downloaded it once.
    - Windows x64 builds both archives in CI and links a `gui` program that
      exercises the `media` link feature (plus an explicit `--feature media`
      build), using the same Visual Studio `vcvarsall` + bundled LLVM toolchain
@@ -245,6 +254,10 @@ engine were Rust.
      through a memoised module wrapper, so imported modules see the parsed
      document and share state. Missing files become diagnostics. Everything
      runs in document order.
+   - **M9c′** ✅ — an inline `<script>` body is split by the same routine, so its
+     imports are hoisted (a `node:`/bare specifier links like any module import)
+     instead of staying inside the wrapped function, where codegen reported
+     TS5001. Inline and `<script src>` now behave identically.
 10. **M10 — polish** ✅
     - `win.requestAnimationFrame(fn)` / `win.cancelAnimationFrame(id)`; callbacks
       run at the top of each frame with the frame timestamp and may mutate the
@@ -454,6 +467,9 @@ engine were Rust.
   memoised module wrapper (so module-level DOM work sees the parsed document),
   while missing files are diagnostics. Loader errors are caught by `loadGraph`
   and reported as build errors.
+- **M9c′** ✅ inline `<script>` bodies are split by the same routine as external
+  ones, so an inline `import` is hoisted and links identically (including
+  `node:fs` with the `node` extension); only the body's origin differs.
 - **M10** ✅ `requestAnimationFrame`/`cancelAnimationFrame` on window handles
   (callbacks run with the frame timestamp before layout each frame) plus
   `offsetWidth`/`offsetHeight`/`contains` on element handles; e2e coverage in

package/doc/implemented/async.md

@@ -30,6 +30,7 @@ Location: `runtime/xt_async.c`, `runtime/xt_coroutine.c`, `runtime/xt_promise.c`
 - Microtask queue (`xt_microtasks`); `xt_promise_ctor/resolve/reject/static` (including `withResolvers`), instance `then` / `catch` / `finally`.
 - `xt_drain_microtasks` empties the queue at program exit, and the event loop drains it between callbacks.
 - `xt_await` queues a microtask for a non-promise or settled value, and suspends the running async coroutine on a pending promise until it settles.
+- Unhandled rejections are fatal, like Node's default `--unhandled-rejections=throw`. A promise that rejects and is never observed — no `.then` / `.catch`, no `await`, not adopted by another promise — is reported as `Unhandled promise rejection` on stderr once the event loop drains, and the process exits with status 1. The case this protects is the entry point: a program's `main()` is usually `async`, so an exception escaping it would otherwise reject an unobserved promise and the process would print nothing and exit 0. Attaching a handler later, even from a timer, still counts as observed.
 
 ## Timers and the event loop
 

package/doc/implemented/modules.md

@@ -21,12 +21,15 @@ Location: `src/parser/parser.ts` (syntax), `src/driver/modules.ts` (bundling),
 
 ## Deferred evaluation
 
-- The `gui` `.html` asset loader marks relative `<script src>` imports with a
-  synthetic `__xt_deferred_module` binding. The bundler then wraps that module
-  and its local import graph in functions that return their exports, and the
-  generated script calls them after `loadHTML` (`__xt_defer` memoises each
-  module). This matches a browser module script, where the graph is evaluated
-  once the document exists.
+- The `gui` `.html` asset loader marks relative imports of an inline `<script>`
+  body or a `<script src>` file with a synthetic `__xt_deferred_module` binding.
+  The bundler then wraps that module and its local import graph in functions that
+  return their exports, and the generated script calls them after `loadHTML`
+  (`__xt_defer` memoises each module). This matches a browser module script,
+  where the graph is evaluated once the document exists.
+- Both script forms are split the same way: top-level `import`/`export … from`
+  statements are hoisted into the generated module and `export` modifiers are
+  stripped, so a bare or `node:` specifier links like any ordinary module import.
 - Modules also reachable through a normal (non-marker) import stay eager and get
   a thin wrapper over their already-initialised exports.
 - The wrapper body is synchronous: top-level `await` inside a deferred script

package/doc/implemented/node/child-process.md

@@ -5,17 +5,25 @@
 Location: `src/extensions/node/child_process/index.ts`, `runtime/ext_node/child_process/child_process.c`
 
 `spawnSync(command, args[, options])` runs a program to completion and returns
-`{ status, stdout, stderr }`. `options.cwd` sets the working directory and
-`options.stdio: "inherit"` hands the child the parent's stdout/stderr (used by
-`xbintsc run`, so a compiled program's output streams live); otherwise
-stdout/stderr are captured as UTF-8 strings.
+`{ status, stdout, stderr }`. `options.cwd` sets the working directory,
+`options.env` replaces the child's environment, and `options.stdio: "inherit"`
+hands the child the parent's stdout/stderr (used by `xbintsc run`, so a
+compiled program's output streams live); otherwise stdout/stderr are captured
+as UTF-8 strings.
 
 | Option | Notes |
 | --- | --- |
 | `cwd` | working directory for the child |
+| `env` | the child's complete environment; omit it to inherit, spread `process.env` into it to extend |
 | `stdio: "inherit"` | share the parent's stdout/stderr instead of capturing |
 | `encoding` | accepted and ignored (output is always decoded as UTF-8) |
 
+`env` follows Node's replace semantics: a present object *is* the environment,
+so a variable the caller does not list is absent in the child. That is what lets
+a caller hand a toolchain a specific `SDKROOT`, `INCLUDE` or `LIB` without
+leaking its own shell setup — and what the macOS SDK fix relies on, because a
+self-hosted compiler runs this same code.
+
 On Windows the child is launched with `CreateProcess` and its stdout/stderr are
 drained through anonymous pipes by reader threads. No temporary files are used,
 so a locked-down `%TEMP%` cannot break `spawnSync`, and output larger than a pipe

package/doc/implemented/runtime-core.md

@@ -28,5 +28,5 @@ standard-library surface have their own pages:
 - 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.
+- 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. A promise rejection nobody observes is fatal too: `xt_promise_report_unhandled` runs once the event loop drains, prints `Unhandled promise rejection` plus the reason and exits with status 1 (see [Async](./async.md)). 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/npm-package.md

@@ -216,9 +216,29 @@ necessarily next to the config file); set `xbintsc_CACHE_DIR` to put it
 elsewhere. Expect that fallback build to take noticeably longer than the ones
 after it.
 
+The prebuilt archives are produced by the release runner's toolchain and target
+the floors in
+[requirements](./requirements.md#supported-platforms) (macOS 11.0, Windows 11,
+glibc 2.39). When that toolchain is newer than the one on this machine — a newer
+Xcode Command Line Tools/SDK or Visual Studio C++ toolset — the linker can
+reject the archive with unresolved symbols (`LNK2038`, `LNK2019`, `Undefined
+symbols`, `undefined reference`) or a `was built for newer macOS version`
+warning. The driver then retries the link **automatically** with
+`core`/`ext_node` compiled from the sources shipped in the package, so a
+mismatched archive costs time, not a failed build:
+
+```text
+xbintsc: the prebuilt runtime archive does not match this toolchain (…); compiling the C runtime from source
+```
+
+The retry is not remembered: after a toolchain upgrade a later build links the
+archive again. The bundled `gui.a`/`media.a` are the exception — they contain
+SDL3/FFmpeg, whose sources are not part of the npm package, so they cannot be
+rebuilt this way. If they are the incompatible archive, use a release built for
+this toolchain or a source checkout.
+
 To ignore the platform archive on purpose and compile the runtime from the
-sources shipped in the package — for example after patching `runtime/`, or when
-the prebuilt archive does not match the environment — set:
+sources shipped in the package — for example after patching `runtime/` — set:
 
 ```bash
 xbintsc_PREFER_PREBUILT=0 npx xbintsc build src/main.ts --out build
@@ -439,6 +459,7 @@ the same file under `node_modules/xbintsc/doc/ai/`.
 | The first build takes a long time | The optional `@xbintsc/<os>-<arch>` package was skipped (or this host has no prebuilt package), so the runtime C sources are compiled and cached. Check `npm ls @xbintsc/<os>-<arch>` and reinstall without `--omit=optional`; `--time` confirms. |
 | Permission errors writing `.xbintsc/` | Set `xbintsc_CACHE_DIR` to a writable directory, or run from a writable working directory. |
 | `module 'fs' is provided by the 'node' extension` | Add `--ext node`, or `"extensions": ["node"]` in the config. |
+| Link fails with `LNK2038`, `LNK2019`, `Undefined symbols` or `was built for newer macOS version` | The prebuilt archive was built by a newer Xcode/Visual Studio toolchain. The driver retries automatically with the runtime's C sources; if the error persists it is `gui.a`/`media.a`, which cannot be rebuilt from the npm package — use a matching release or a source checkout. |
 | `GUI native library not found` / `media native library not found` | The optional platform package that ships `gui.a`/`gui.lib` or `media.a`/`media.lib` was skipped, or this host has no prebuilt GUI/media archive (Windows arm64). Reinstall without `--omit=optional`, use a Linux/macOS/Windows x64 release archive, or build the archive from a source checkout. An auto-detected `media` feature with a missing archive only warns; `--feature media` makes it an error. |
 | `require("xbintsc")` fails | The package is ESM-only; use `import` (or dynamic `import()`). |
 | Windows link errors about missing MSVC libraries | Run from a Native Tools prompt, install the VS C++ build tools, and check `npx xbintsc doctor`. |

package/doc/post/make-js-great-again.md

@@ -0,0 +1,30 @@
+# This Might Be the Most Exciting Thing for JS Developers This Year
+
+![3D pelican riding a bicycle](../../examples/gui/pelican-3d/preview.png)
+
+The image above is a 3D pelican riding a bicycle that I built with JS + HTML + WebGL2, and the framerate is excellent too.
+
+You might say, "Isn't that just a matter of having hands and an AI these days?"
+
+But what if I told you that I compiled that very thing into a native binary with xbintsc — under 10 MB, able to run with no WebView environment at all, and able to mix Node.js and HTML in a single file, like this:
+
+```html
+<html>
+    <body>
+    <div id="out">loading...</div>
+    <script lang="ts">
+        import { readFileSync } from "fs";
+
+        const out = document.getElementById("out");
+        const world = readFileSync("data.txt", "utf8");
+        out.textContent = "hello " + world;
+    </script>
+    </body>
+</html>
+```
+
+Keep in mind that Chrome alone used to take at least 100 MB. The xbintsc build is 10 MB and doesn't need a WebView environment — and that means far more than just a massive reduction in the footprint of desktop development, or a more correct implementation path.
+
+What is truly epoch-making is this: it is now possible for JS developers to run the applications they want to build on embedded devices.
+
+[xbintsc on GitHub](https://github.com/zy445566/xbintsc)

package/doc/requirements.md

@@ -15,6 +15,32 @@ no requirements on any platform.
 Installing the compiler from npm instead of using a release archive? Node.js 22+
 then runs the compiler itself; see [Using xbintsc from npm](./npm-package.md).
 
+## Supported platforms
+
+Release binaries and the prebuilt runtime archives target the oldest platform
+versions xbintsc supports. CI builds them with the **oldest toolchain that can
+still assemble a release for each host**, so a newer Xcode or Visual Studio on
+your machine can link them — the reverse direction is what fails with `LNK2038`,
+`Undefined symbols` or `was built for newer macOS version`.
+
+| Platform | Produced binaries run on | Build baseline (CI) |
+| --- | --- | --- |
+| macOS x64 / arm64 | **macOS 11.0** (Big Sur) and newer | the oldest installed Xcode with clang 16+, `MACOSX_DEPLOYMENT_TARGET=11.0` |
+| Windows x64 | **Windows 11** and newer | the `windows-2025` image's toolset (VS 2026) |
+| Windows arm64 | **Windows 11** | the `windows-11-arm` image's toolset (currently VS 2026; no older arm64 image exists) |
+| Linux x64 / arm64 | **glibc 2.39** (Ubuntu 24.04) and newer | clang 16 + lld 16 on `ubuntu-24.04` |
+
+The compiler toolchain floors are Xcode 16 (Apple clang 16) on macOS, the
+`windows-2025` image's Visual Studio (currently VS 2026) on Windows and clang 16
+on Linux. Building therefore needs a newer host than the produced binary does:
+Xcode 16 itself requires macOS 14.5+, so a macOS 11–14 build machine needs a
+standalone LLVM 16+ (for example Homebrew's `llvm`). `xbintsc doctor` prints the
+floor for the host it runs on. If the archives were built with a
+newer toolchain than yours, `build` retries with the C runtime's shipped
+sources (see [the npm package guide](./npm-package.md#the-first-build-and-the-cache));
+the bundled `gui.a`/`media.a` cannot be rebuilt that way, because SDL3/FFmpeg
+sources are not part of the package.
+
 clang 15 and older fail on the first string literal in any program, with:
 
 ```
@@ -112,6 +138,11 @@ xcode-select -p            # prints the active developer directory
 xcrun --show-sdk-path      # prints the SDK path
 ```
 
+xbintsc runs the command in the second line itself and passes the result to
+clang as `-isysroot`, so a clang selected by absolute path (the CI baseline, or
+`xbintsc_CLANG`) still finds the SDK's C headers and link stubs. Setting
+`SDKROOT` yourself takes precedence and pins a specific SDK.
+
 ## Linux — install clang and lld
 
 A normal glibc-based distribution plus `clang` and `lld` is enough:
@@ -139,9 +170,11 @@ winget install -e --id Microsoft.VisualStudio.2022.BuildTools `
   --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.VC.Llvm.Clang --includeRecommended"
 ```
 
-The LLVM bundled with Visual Studio 2022
-(`VC\Tools\Llvm\x64\bin\clang.exe`, version 19.1.5 in current installs) is what
-`scripts/setup-vs-toolchain.ps1` selects. A standalone LLVM also works for
+The LLVM bundled with Visual Studio (`VC\Tools\Llvm\x64\bin\clang.exe`) is what
+`scripts/setup-vs-toolchain.ps1` selects. `xbintsc` probes both install layouts —
+the year-named one (`2019`, `2022`) and the version-numbered one used by Visual
+Studio 2026 and later (`18\Community`, `18\Insiders`, …) — so a newer installation
+is found without setting `xbintsc_CLANG`. A standalone LLVM also works for
 `xbintsc` itself (`winget install -e --id LLVM.LLVM`), but the GUI/media archive
 builds and the CI setup use the Visual Studio one so one toolchain produces the
 runtime, the archives and the final binary. Either way the compiler must target

package/doc/unimplemented/deviations.md

@@ -16,6 +16,7 @@ These features **compile and run**, but the result does not fully match ECMAScri
 | Memory management | Non-moving mark-sweep collector behind `xt_alloc`: explicit roots, subsystem root providers and a conservative C-stack scan. Single-threaded and stop-the-world; no moving/compaction or generational mode |
 | Function `arity` / argument count | Direct calls to a locally visible function are checked by the default [semantic checker](../implemented/checker.md) (`TS4004`); calls through properties, imports, spread arguments or a reassigned binding are not. `fn.length` reports the declared arity |
 | `async` / `await` | Real suspension on a stackful coroutine; `await` always queues a microtask (non-promises and already-settled promises included), so interleaving with pending `.then` callbacks matches the specification. Top-level `await` blocks on the event loop rather than yielding the module body. `fs/promises` and `fetch` offload their blocking work to a four-worker pool and settle on the reactor. Async generators suspend at both `await` and `yield`; `for await...of` awaits one step per iteration |
+| Unhandled rejections | Reported when the program ends rather than at the end of the tick: a rejection no handler observed is printed and makes the process exit 1 once the event loop drains, so a long-running process (a server) keeps running until it exits, and a handler attached later still suppresses the report. Node raises the fatal error right after the microtask queue drains |
 | Async generator cleanup | `for await...of` does not call the iterator's `return()` when the loop exits early. `yield*` inside an async generator delegates to synchronous iterables only. `.return()` at a suspended `yield` completes without running `finally` (the same limitation as synchronous generators) |
 | `super` | `super.x` / `super[x]` read from the parent holder of the class whose body is running (in an instance method: the parent prototype; in a `static` method or static block: the parent constructor), so any inheritance depth is correct |
 | `Error.stack` | Function-level frames only: each frame is `at name (file:line)` with the function's declaration line (updated to the construction line for the innermost frame); no column numbers and no frames for generator / `async` bodies (they switch stacks) |

package/doc/zh-CN/gui/build.md

@@ -39,8 +39,10 @@
   demuxer/parser/decoder 的最小静态构建，用它编译
   `runtime/ext_media/media.cpp`，并把所有内容合并到
   `runtime/lib/<os>-<arch>/media.a`（Windows 上 MSVC ABI 则为 `media.lib`）。
-  `gui.a` **不会**链接 FFmpeg：编译器为可能播放媒体的程序选中 `media` 链接特性后
-  才链接 `media.a`（见[链接特性](#链接特性)）。
+  下载会重试发布主机常见的瞬时 TLS 故障；解压后 tarball 保留为
+  `vendor/ffmpeg-<version>.tar.xz`，因此重建（或按 `FFMPEG_VERSION` 缓存它的
+  CI）会解压本地副本而不再下载。`gui.a` **不会**链接 FFmpeg：编译器为可能播放
+  媒体的程序选中 `media` 链接特性后才链接 `media.a`（见[链接特性](#链接特性)）。
 - `src/extensions/gui/index.ts` 通过 `nativeObjects()` 暴露引擎归档（经由
   `findRuntimeLibrary`，因此 `.a`/`.lib` 都可用），并通过 `linkerFlags()`
   暴露操作系统框架。它的 `linkFeatures()`（位于

package/doc/zh-CN/gui/dom.md

@@ -182,7 +182,9 @@ run();
 这两个参数（`window`、`document`）只是普通的函数参数，因此脚本的局部变量
 无需任何全局对象机制。外部脚本同样可用：`<script src="./counter.ts">` 会在
 编译期读取，其 import 会被提升（重写为从 HTML 文件解析），其主体以同样方式
-包装——因此脚本模块可以 `import` 辅助函数，同时仍能看到 `document`。脚本是
+包装——因此脚本模块可以 `import` 辅助函数，同时仍能看到 `document`。内联主体
+走同一套拆分，因此 `import` 在两种写法中行为一致；开启 `node` 扩展后，
+`node:fs` 等其他 `node:` 内置模块同样可用。脚本是
 **编译期资产**：运行时创建的 HTML（`innerHTML`、网络获取）永不执行，`src`
 URL（`https://…`、`data:…`）会被忽略。一切都按文档顺序在解析后运行（实际上
 是 deferred）。完整设计参见 `gui-scripts.md`。

package/doc/zh-CN/gui/webgl.md

@@ -133,6 +133,7 @@ transform feedback（入口为空操作：SDL_GPU 没有 transform feedback 阶
 - `tests/e2e/gui-media.test.ts` 还会把 `<video>` 的最新解码帧上传为纹理并读回像素。
 - `examples/gui/webgl-cube` 是一个旋转、受光、带纹理的立方体；它在浏览器中原样运行，并由 `tests/e2e/gui-example-webgl.test.ts` 覆盖。
 - `examples/gui/webgl2-cubes` 用一次绘制调用画出 64 个实例化立方体，使用 `#version 300 es` 与 VAO；由 `tests/e2e/gui-example-webgl2.test.ts` 覆盖。
+- `examples/gui/pelican-3d` 是一个完整的光照场景（程序化天空、雾、实例化树木/云、带关节动画的鹈鹕和自行车），拆成九个 ES module，并用 `AudioContext` 合成音效；由 `tests/e2e/gui-example-pelican3d.test.ts` 覆盖。
 
 这些用例会在宿主选择的后端上运行：Linux（与 Windows）上是 Vulkan，macOS 上是 Metal，因此 SPIRV-Cross → MSL 路径与 SPIR-V 路径受同一组断言保护。
 

package/doc/zh-CN/gui-scripts.md

@@ -133,8 +133,9 @@ __registerScript("a1b2…", __xt_script_a1b2);
 export default __html;
 ```
 
-- id 是主体内容的哈希（sha256，前 32 个十六进制字符）；主体被替换为一个空的
-  标记元素，以便引擎能按文档顺序找到它。
+- id 是包装后主体内容的哈希（sha256，前 32 个十六进制字符；包含延迟 import 的
+  prelude，因此语句相同但 import 不同的两个脚本不会合并为同一条注册表记录）；
+  主体被替换为一个空的标记元素，以便引擎能按文档顺序找到它。
 - `window` 与 `document` 是**函数参数**，因此脚本的全局变量会作为普通局部
   变量解析 —— **无需编译器改动**，也没有全局对象。
 - `__registerScript(id, fn)` 是一个新的运行时内置函数，它把闭包存进全局的
@@ -142,6 +143,11 @@ export default __html;
 - 延迟脚本（`<script defer>`，或 M9c 中决定的所有内联脚本）在完整文档解析
   并计算首次布局之后按文档顺序运行。然后在 `window` 上依次触发
   `DOMContentLoaded` 再 `load`。
+- 内联主体与 `<script src>` 文件走**同一套**拆分逻辑（见下）：顶层
+  `import`/`export … from` 语句被提升进生成模块，相对说明符相对 HTML 文件
+  解析，`export` 修饰符被去掉。因此内联 `<script>` 里的
+  `import { readFileSync } from "node:fs"` 与外链脚本里的同一条 import 链接
+  方式完全一致 —— 需要开启 `node` 扩展，但不需要改写页面。
 
 ### 2b. 外部 `<script src>`
 
@@ -151,19 +157,19 @@ import 会像浏览器的模块脚本一样**延迟**：loader 生成一个合
 `__xt_deferred_module` 标记，生成的脚本在 `loadHTML` 时调用模块包装函数。
 bundler 把整个本地 import 图包装成返回各自导出的函数（由 `__xt_defer`
 记忆化），因此模块顶层代码在文档就绪后才运行，且两个脚本导入同一模块时共享
-同一个实例。裸说明符（`gui`、npm 包）仍然立即加载。
+同一个实例。裸说明符（`gui`、npm 包、`node:fs`）仍然立即加载。内联
+`<script>` 主体走完全相同的拆分，因此两种写法里的 import 行为一致；唯一区别
+是主体的来源。
 
 缺失的 `src` 文件仍会抛出清晰的错误（被转换为 bundler 诊断）；
 `src` URL（`https://…`、`data:…`、`//host`）保持原样 —— 它们不是编译期资产，
 永不运行。
 
-`src` URL（`https://…`、`data:…`、`//host`）保持原样 —— 它们不是编译期资产，
-永不运行。
-
-被包装的脚本体以**它自己的文件**作为其中每条语句的来源（loader 会把该脚本体在生成模块中的
+被包装的 `<script src>` 主体以**它自己的文件**作为其中每条语句的来源（loader 会把该脚本体在生成模块中的
 区间作为 source range 上报），因此诊断会指向 `app.js:12`，而不是 `index.html` 的某一列；
 同时**纯 JavaScript** 脚本与直接 import 的 `.js` 模块一样不做类型检查：在对象字面量上写
-`state.update = …` 不会再报 `TS4003`。页面因此可以原样携带已有的脚本。
+`state.update = …` 不会再报 `TS4003`。页面因此可以原样携带已有的脚本。内联主体的
+来源就是 HTML 页面本身。
 
 ```html
 <button id="b">0</button>
@@ -288,6 +294,9 @@ Event 的 `target` 是句柄，其描述符（`toString`）与同一 `div#id.cla
     通过带记忆化的模块包装函数延迟到 `loadHTML` 求值，因此 import 图能看到
     已解析的文档，且同一模块只实例化一次。缺失文件作为诊断浮现。所有脚本按
     文档顺序运行。e2e 覆盖。
+  - **M9c′** ✅ —— 内联 `<script>` 主体走同一套拆分逻辑，因此 `import`（包括
+    `node:`/裸说明符）与外链脚本里的链接方式完全一致。此前内联主体被原样包装，
+    其 `import` 留在脚本函数体内，codegen 会报 TS5001。
   - **M9d** *(可选)* —— 检测传给 `win.loadHTML(...)` 的模板字面量中的内联
     HTML 并同样转换它们（脆弱；推迟）。
 - **M10 — 打磨** ✅ —— 窗口上的
@@ -312,10 +321,11 @@ Event 的 `target` 是句柄，其描述符（`toString`）与同一 `div#id.cla
   不会运行。已记录。
 - **模板字面量 HTML** 传给 `win.loadHTML(…)` 时在 M9b 中不会被转换（只有
   导入的资产会）。如有需要，M9d 会处理。
-- **外部 `<script src>` 文件之间的 import 绑定冲突。** 会被检测并报告
+- **外部 `<script src>` 与内联脚本之间的 import 绑定冲突。** 会被检测并报告
   （给 import 起别名）；之后可以做到带引用重写的按脚本重命名。
-- **资产。** `<script src>` 相对 HTML 资产解析；URL `src` 值被忽略。
-  加载器不会请求网络 URL；运行时全局 `fetch` 是另一套 API。
+- **资产。** `<script src>` 相对 HTML 资产解析；内联主体的 import 也从同一位置
+  解析。URL `src` 值被忽略。加载器不会请求网络 URL；运行时全局 `fetch` 是
+  另一套 API。
 
 ## 测试
 
@@ -326,6 +336,8 @@ Event 的 `target` 是句柄，其描述符（`toString`）与同一 `div#id.cla
 - **M9a**：一个假扩展加载器的单元测试，断言 bundler 重写 `*.foo` 并记录依赖。
 - **M9b**：一个带内联 `<script>`、点击时递增计数器的 e2e 用例，通过处理器的
   `console.log` 断言。
+- **M9c′**：单元用例断言内联主体的 import 被提升（相对 import 被延迟），外加
+  一个 e2e 用例：内联脚本通过 `node:fs` 读取文件并调用被延迟的辅助模块。
 - **M10**：`requestAnimationFrame`（每帧运行、重新排队、接收时间戳、遵守
   `cancelAnimationFrame`）与 `offsetWidth`/`offsetHeight`/`contains` 的 e2e
   用例。

package/doc/zh-CN/gui.md

@@ -157,7 +157,12 @@
    - `vendor/`（GUI 归档的 SDL3/FreeType/HarfBuzz/glslang，以及 `media` 的 FFmpeg，
      缓慢的部分）按 OS/arch 缓存，以 `scripts/build-gui.ts` /
      `scripts/build-media.ts` 为键。Windows x64 有独立的源码 + FFmpeg 安装前缀
-     缓存。
+     缓存；Linux/macOS 上安装前缀 `vendor/ffmpeg-build/dist` 另有以
+     `FFMPEG_VERSION` 和 `scripts/build-media.ts`（决定 configure 参数）为键的
+     缓存，命中后跳过 FFmpeg 的 configure/make，不必每次重编：脚本会在前缀里
+     记录构建它的发布版本，版本或 macOS 部署目标变化时丢弃重建。FFmpeg 发布
+     tarball 另有只以 `FFMPEG_VERSION` 为键、所有 job 共享的缓存：即使
+     ffmpeg.org 的 TLS 握手不稳定，也不会让已经下载过它的运行失败。
    - Windows x64 在 CI 中构建两个归档并链接一个会触发 `media` 链接特性的 `gui`
      程序（另有一条显式 `--feature media` 的构建）；托管 runner
      没有 GPU/Vulkan 驱动，因此 GUI/媒体示例的*运行*仍为试验性（失败只记录
@@ -182,6 +187,9 @@
      相对 import 通过带记忆化的模块包装函数延迟到 `loadHTML` 求值，因此被导入
      模块能看到已解析的文档并共享状态。缺失文件会成为诊断。一切都按文档顺序
      运行。
+   - **M9c′** ✅ —— 内联 `<script>` 主体走同一套拆分逻辑，其 import 被提升
+     （`node:`/裸说明符像普通模块 import 一样链接），而不是留在被包装的函数
+     体内、由 codegen 报 TS5001。内联与外链现在行为一致。
 10. **M10 — 打磨** ✅
     - `win.requestAnimationFrame(fn)` / `win.cancelAnimationFrame(id)`；回调
       在每帧顶部以帧时间戳运行，并可修改 DOM
@@ -366,6 +374,8 @@
 - **M9c** ✅ 外部 `<script src>` 文件被读取，其主体被包装/注册；相对 import
   通过带记忆化的模块包装函数延迟到 `loadHTML`（模块级 DOM 工作因此能看到已解析
   文档）；缺失文件会成为诊断。加载器错误被 `loadGraph` 捕获并报告为构建错误。
+- **M9c′** ✅ 内联 `<script>` 主体与外链主体走同一套拆分逻辑，因此内联 `import`
+  被提升并同样链接（开启 `node` 扩展后包括 `node:fs`）；只有主体来源不同。
 - **M10** ✅ 窗口句柄上的 `requestAnimationFrame`/`cancelAnimationFrame`
   （回调在每帧布局之前以帧时间戳运行），以及元素句柄上的
   `offsetWidth`/`offsetHeight`/`contains`；e2e 覆盖在

package/doc/zh-CN/implemented/async.md

@@ -30,6 +30,7 @@
 - 微任务队列（`xt_microtasks`）；`xt_promise_ctor/resolve/reject/static`（含 `withResolvers`）、实例 `then` / `catch` / `finally`。
 - `xt_drain_microtasks` 在程序结束时清空队列，事件循环也会在回调之间清空它。
 - `xt_await` 对非 Promise / 已 settle 值排入一次微任务，对 pending promise 则挂起当前 async 协程直到 settle。
+- 未处理的 rejection 是致命错误，与 Node 默认的 `--unhandled-rejections=throw` 一致。一个 reject 后始终无人观察的 promise——没有 `.then` / `.catch`、没有被 `await`、也没有被另一个 promise 采纳——会在事件循环排空后向 stderr 打印 `Unhandled promise rejection`，并以状态码 1 退出。它主要保护入口函数：程序的 `main()` 通常是 `async`，从其中逃出的异常原本只是 reject 一个无人观察的 promise，进程会静默退出 0。即使在定时器里稍后才挂上处理函数，也算已观察。
 
 ## 定时器与事件循环