xbintsc 0.5.20 → 0.5.21

package/doc/unimplemented/node/fs-promises.md

@@ -2,15 +2,19 @@
 
 > Part of [Node extension: unimplemented](../node.md) · [简体中文](../../zh-CN/unimplemented/node/fs-promises.md)
 
-`fs/promises` wraps each synchronous `fs` call in an already-settled promise
-(the implemented surface is in
-[implemented: `fs/promises`](../../implemented/node/fs-promises.md)).
+`fs/promises` now offloads its blocking I/O to the async I/O pool (the
+implemented surface is in
+[implemented: `fs/promises`](../../implemented/node/fs-promises.md)); the
+remaining differences are behavioural:
 
-- I/O is synchronous: the promise is settled before it is awaited, so awaiting
-  it does not yield to the event loop.
 - `FileHandle.appendFile` behaves like `writeFile` (it writes at the current
   file position instead of appending).
 - `FileHandle.readFile()` reads from the current file-descriptor offset.
-- `Dir.read` / `Dir.close` (sync and promise forms) complete immediately.
+- `Dir.read` / `Dir.close` (sync and promise forms) complete their callbacks
+  immediately; `Dir.readSync` / `closeSync` remain synchronous.
 - `watch` resolves to the same never-emitting watcher as `fs.watch`; there is no
   real file-watching backend.
+- Reads and writes are whole-file/one-shot operations; there are no streaming
+  `FileHandle` variants and no `AbortSignal` cancellation.
+- The pool has four workers; very many simultaneous operations queue behind
+  them (they still do not block the event loop).

package/doc/unimplemented/node/fs.md

@@ -2,14 +2,13 @@
 
 > Part of [Node extension: unimplemented](../node.md) · [简体中文](../../zh-CN/unimplemented/node/fs.md)
 
-`fs` now implements the **synchronous** API surface (files, directories,
-descriptors, metadata, links, `cp`, `glob`, `Dir`, `constants`) and
-`fs/promises` wraps each synchronous function in an already-settled Promise
+`fs` implements the **synchronous** API surface (files, directories,
+descriptors, metadata, links, `cp`, `glob`, `Dir`, `constants`), and
+`fs/promises` runs every file/descriptor operation on the asynchronous I/O pool
 (see [implemented: `fs`](../../implemented/node/fs.md) and
-[implemented: `fs/promises`](../../implemented/node/fs-promises.md)). The rest is still
-unimplemented because xbintsc has **no asynchronous I/O scheduler** for file
-operations (the `fs` module has no reactor backend; the core event loop does
-provide timers and sockets):
+[implemented: `fs/promises`](../../implemented/node/fs-promises.md)). What is
+still missing is mostly about APIs that need a different backend or callback
+plumbing:
 
 | Unimplemented API | Category |
 | --- | --- |
@@ -24,7 +23,7 @@ provide timers and sockets):
 - `readFileSync` supports encoding options (default/`utf8`/`ascii`/`latin1`/`binary`/ `hex`/`base64`/`base64url`), but **does not return a `Buffer`** by default: even though `Buffer` exists (simulated as a plain object), `readFileSync` still returns a string. Pass a `Buffer`-producing path or read raw bytes explicitly.
 - `utf16le` / `ucs2` decoding is not implemented (the bytes are returned as text).
 - `watch` / `watchFile` / `unwatchFile` return API-shaped emitter objects whose `.close()` / `.on()` methods exist but which **never fire** events.
-- `Dir.read(cb)` / `Dir.close(cb)` and the async form of `FileHandle` methods complete **synchronously** (the callback/Promise is invoked immediately).
+- `Dir.read(cb)` / `Dir.close(cb)` complete **synchronously** (the callback is invoked immediately); `FileHandle` methods do return real promises now.
 - `mkdtempSync` always appends 6 random characters to the prefix (it does not require a trailing `XXXXXX`).
 - `globSync` supports `*`, `?`, `[...]` and `**` but not the `exclude` callback or `follow`; `**` does not descend through symlinks (matching Node's default).
 - `cpSync` symlink handling follows Node for the common cases but `verbatimSymlinks` is not supported.

package/doc/unimplemented/node.md

@@ -10,10 +10,10 @@ is missing or differs from Node.
 ## Contents
 
 - [`fs`](./node/fs.md) — callback-style async operations, real file watching, option callbacks
-- [`fs/promises`](./node/fs-promises.md) — synchronous I/O behind a settled promise, `FileHandle` deviations
+- [`fs/promises`](./node/fs-promises.md) — `FileHandle` append/read offsets, immediate `Dir` callbacks, inert `watch`, no cancellation
 - [Fully unimplemented modules](./node/modules.md) — `https`, `readline`, `tls`, `cluster`, `vm`, ...
 - [Global objects and namespaces](./node/globals.md) — `global`, `__dirname`, `require` outside `node_modules`
-- [Async and the event-loop model](./node/async.md) — no asynchronous I/O scheduler, blocking `connect`, no keep-alive
+- [Async and the event-loop model](./node/async.md) — blocked file watching, blocking `net.connect`, no keep-alive, fixed-size offload pool
 - [The Bun extension](./node/bun.md) — design example only
 
 A module's implemented page links to its limitation page; when a limitation is

package/doc/unimplemented/toolchain.md

@@ -9,6 +9,6 @@
 | Type checker | ✗ only diagnostic codes are defined; no checker |
 | Full standard library | partial: Math / JSON / Date / Map / Set / RegExp / `Error` / `BigInt` / `Symbol` / `structuredClone` implemented; String.normalize missing |
 | Multi-file module bundling | partial: relative-path `.ts` bundling, ESM `node_modules` packages, namespace imports and bare-specifier extension module imports implemented; CommonJS is handled only inside `node_modules`; circular dependencies / live bindings are not implemented |
-| Real async runtime | ✓ `async`/`await` suspends on pending promises on the `select(2)` reactor: timers, TCP sockets and promise callbacks resume the coroutine. Still missing: truly asynchronous I/O scheduling (`fs/promises` blocks before settling), a non-blocking `fetch` and worker threads (workers are child processes) |
+| Real async runtime | ✓ `async`/`await` suspends on pending promises on the `select(2)` reactor: timers, TCP sockets, offloaded file/HTTP work and promise callbacks resume the coroutine. Still missing: real OS-level file watching, non-blocking `net.connect`, TLS for `fetch`, and user-visible worker threads (`worker_threads` uses child processes) |
 | Windows binary artifact verification | adapted at the build layer (`.exe` suffix, link flag branch), verified in CI |
 | Precise ECMAScript number / string / comparison semantics | partial, see [Runtime deviations](./deviations.md) |

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

@@ -64,6 +64,7 @@ win.documentTree()                     // 序列化的 DOM（调试用）
 win.layoutTree()                       // 序列化的布局盒（调试用）
 win.paintCount()                       // 显示列表中图形的数量
 win.paintList()                        // 序列化的显示列表（调试用）
+win.inlineSvg(selector)                // 序列化的内联 <svg>：{ markup, width, height, shapes }
 win.measureText(text, fontSize?, family?)  // 整形后的推进宽度（像素）
 win.fontMetrics(fontSize?, family?)    // { ascent, descent, lineHeight, ready }
 win.hitTest(x, y)                      // 最深的元素描述符，或 ""
@@ -72,6 +73,12 @@ win.advance(ms)                        // 推进 CSS transition 时钟（测试
 win.stats()                            // 引擎/运行时计数器（内存排查用）
 ```
 
+`win.inlineSvg(selector)` 返回引擎为第一个匹配 `selector` 的 `<svg>` 元素构建的
+独立 SVG 文档（`markup`），以及 NanoSVG 从它解析出的固有尺寸与图形数量；没有
+匹配或元素不是 `<svg>` 时返回 `undefined`。它让序列化器的规范大小写
+（`viewBox`、`linearGradient`、`gradientUnits` 等）无需 GPU 即可测试——HTML
+解析器会把它们全部小写化。
+
 `win.stats()` 返回 `{ heapBytes, heapAllocations, treeNodes, detachedRoots,`
 `detachedNodes, handles, handleSlots, listeners }`：运行时存活堆、DOM 树规模、
 分离节点池（detached pool）以及元素句柄表。稳定状态下它们都应保持常量——若

package/doc/zh-CN/gui/known-issues.md

@@ -23,13 +23,14 @@
   `tests/e2e/gui-example-browser.test.ts` 中。
 - **`display: none -> flex` 的重排。** 通过类名切换让隐藏元素显示在 flex 容器上时，也曾观察
   到同样的崩溃；`examples/gui/pelican-bike` 改用 `opacity` 显示游戏结束遮罩。
-- **SVG：** 支持 SVG *文件*，经图像加载器处理（`<img src="logo.svg">`）：
-  `runtime/ext_gui/svg.cpp` 封装 vendored **NanoSVG** 解析/光栅化器，
-  `image.{h,cpp}` 把 SVG 视为矢量图像并按绘制像素尺寸光栅化。文档中的内联
-  `<svg>` **子树**仍不支持：HTML 解析器只认识元素与属性，布局只认识盒子，
-  绘制只认识矩形/文本/图像；`<svg>` 子树需要另一套几何与绘制路径。因此矢量
-  美术要么以 SVG/PNG 文件形式提供，要么像 `examples/gui/pelican-bike` 那样用
-  盒子绘制。
+- **SVG 是 NanoSVG 的子集。** SVG *文件*（`<img src="logo.svg">`）与内联
+  `<svg>` 子树共用 vendored 的 NanoSVG 解析/光栅化器（`runtime/ext_gui/svg.cpp`、
+  `inline_svg.cpp`），它会渲染 `path`/`rect`/`circle`/`ellipse`/`line`/
+  `polyline`/`polygon`、组、`defs` 渐变以及基于 `class` 的 `<style>` 规则。
+  `<text>`、`<use>`、滤镜、遮罩与裁剪路径不会渲染，文档层叠的 CSS 也不会进入
+  图像内部（这里的 `fill`/`stroke` 是 SVG 表现属性，不是 CSS 属性）。需要这些
+  能力的矢量美术必须预先光栅化、用盒子绘制，或限制在受支持的语法内。参见
+  [媒体](./media.md#图像m6a)。
 
 ## 待决问题
 

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

@@ -12,7 +12,8 @@ PNG/JPEG/BMP/GIF/TGA 解码为 RGBA8，并带有解码缓存与仅头文件的
 `runtime/ext_gui/svg.{h,cpp}` 在其上增加 SVG：它封装 vendored **NanoSVG**
 库（解析 + 抗锯齿扫描线光栅化），按扩展名或内容识别 SVG，并产出与既有管线
 相同的 RGBA8 `Image`。`stb_image` 无法解码 SVG，这正是
-`<img src="logo.svg">` 能工作的原因。
+`<img src="logo.svg">` 能工作的原因。内联 `<svg>` 子树会先被序列化成一个
+独立文档（`inline_svg.{h,cpp}`），再交给同一个解析器。
 
 - `<img>` 是一个替换元素（`display: inline-block`）：设置了 CSS 尺寸时布局
   采用该尺寸，否则采用固有像素尺寸；当只约束一个轴时保持宽高比。构建盒树时
@@ -23,11 +24,34 @@ PNG/JPEG/BMP/GIF/TGA 解码为 RGBA8，并带有解码缓存与仅头文件的
   **位图**按固有分辨率解码并按路径缓存；**矢量图**（SVG）按设备像素下的绘制
   尺寸（逻辑尺寸 × 窗口像素密度）光栅化并保持 viewBox 宽高比，再按该尺寸缓存，
   因此缩放或 HiDPI 得到的是清晰渲染而非放大的位图。
+- **内联** `<svg>` 元素与 `<img>` 一样是替换元素，但它的来源就是 DOM 子树
+  本身。`runtime/ext_gui/inline_svg.{h,cpp}` 把该子树序列化回独立 SVG 文档，
+  还原 HTML 解析器会小写掉的、NanoSVG 又按大小写精确匹配的拼写（`viewBox`、
+  `preserveAspectRatio`、`linearGradient`、`gradientUnits` 等）。布局先取
+  `width`/`height` 属性、其次 `viewBox`、最后 300x150 作为固有尺寸；绘制把
+  markup 挂在图像 op 上，渲染器按绘制设备像素尺寸，通过与 SVG 文件相同的
+  NanoSVG 缓存解析并光栅化。DOM 变更会在下一次布局时重新序列化（因此
+  `setAttribute` 与 `innerHTML` 都会重绘图像），markup 缓存有界
+  （最近最少使用），动画文档不会让它无限增长。
 - 解析结果按路径缓存；解析与光栅化器状态在 `xt_svg_shutdown`
   （`xt_image_shutdown`）中释放。
 
+文档 CSS 只作用于 `<svg>` **盒子**——尺寸、外边距、背景、边框、`transform`、
+opacity、`display`——与任何其他元素一样。盒子内部的艺术内容保持 SVG 语义：
+表现属性与 SVG `<style>` 中基于 `class` 的规则由 NanoSVG 读取，而不是 HTML
+层叠，所以这里的 `fill`/`stroke` 不是 CSS 属性。对布局、绘制、命中测试与事件
+而言整个 `<svg>` 就是一个替换盒：其子元素没有 DOM 盒，因此点击的 `e.target`
+是 `<svg>` 元素而不是某个 `<rect>`。渲染器按 markup 与尺寸缓存纹理，所以每帧
+重写艺术内容的程序会为每个变体保留一张纹理；更好的做法是用 `transform`、
+`opacity` 给盒子做动画，或在一小组文档之间切换。
+
 图像仍需完成：CSS `background-image: url(...)`、`data:` URI、`object-fit`、
-九宫格边框与内联 `<svg>` 元素（仅支持 SVG *文件*，参见[待决问题](./known-issues.md)）。
+九宫格边框。
+
+两种 SVG 都受限于 NanoSVG 的子集：`path`、`rect`、`circle`、`ellipse`、
+`line`、`polyline`、`polygon`、组（`g`）、带线性/径向渐变的 `defs` 以及基于
+`class` 的 `<style>` 规则会被光栅化；`<text>`、`<use>`、滤镜、遮罩与裁剪路径
+不会渲染（见[已知问题](./known-issues.md)）。
 
 ## 视频与音频（M13）
 

package/doc/zh-CN/gui.md

@@ -2,7 +2,7 @@
 
 > 语言 / Language：[English](../gui.md) | **简体中文**
 
-状态：**M15** —— 功能（M1–M14）已全部完成：HTML 解析、CSS 选择器匹配、层叠（cascade）、计算样式与布局（块级、行内、Flexbox 与 CSS 定位）均已就位，引擎还会**绘制**：它构建一个由矩形、图像与排版后的文本 run 组成的显示列表，并通过 SDL_GPU 渲染。输入事件会经过命中测试并投递给原生 TS 处理器，`:hover`/`:focus` 会被动态匹配，`<img>` 依据其固有尺寸确定大小并从纹理绘制——位图（PNG/JPEG/…）与 SVG 文件皆可，后者按绘制尺寸光栅化，因此矢量图保持清晰——CSS transition 会为绘制属性做动画。**M8** 增加了交互式 DOM：具有稳定标识的元素句柄、变更操作（`appendChild`、`textContent`、`classList`、`style` 等）以及支持捕获/冒泡的元素级事件。**M9** 会提前编译 `<script>` 主体（内联与 `<script src>`）——参见 `gui-scripts.md`。**M10** 增加 `requestAnimationFrame` 以及若干 DOM 辅助方法。**M11** 增加 `position: relative`/`absolute`/`fixed` 及其偏移，`examples/gui/pelican-bike`（一个可玩的 2D 游戏）就构建在它之上。**M12** 明确了 DOM 节点生命周期（哪些变更释放、哪些保留），并让引擎内存有界：参见[节点生命周期](./gui/dom.md)与[内存与 GC](./gui/runtime.md)。**M13** 真正播放
+状态：**M16** —— 功能（M1–M15）已全部完成：HTML 解析、CSS 选择器匹配、层叠（cascade）、计算样式与布局（块级、行内、Flexbox 与 CSS 定位）均已就位，引擎还会**绘制**：它构建一个由矩形、图像与排版后的文本 run 组成的显示列表，并通过 SDL_GPU 渲染。输入事件会经过命中测试并投递给原生 TS 处理器，`:hover`/`:focus` 会被动态匹配，`<img>` 依据其固有尺寸确定大小并从纹理绘制——位图（PNG/JPEG/…）与 SVG 文件皆可，后者按绘制尺寸光栅化，因此矢量图保持清晰——CSS transition 会为绘制属性做动画。**M16** 让内联 `<svg>` 子树获得同样的处理：子树被序列化回 SVG 文档，并按绘制设备尺寸光栅化，因此图标不再需要单独的文件。**M8** 增加了交互式 DOM：具有稳定标识的元素句柄、变更操作（`appendChild`、`textContent`、`classList`、`style` 等）以及支持捕获/冒泡的元素级事件。**M9** 会提前编译 `<script>` 主体（内联与 `<script src>`）——参见 `gui-scripts.md`。**M10** 增加 `requestAnimationFrame` 以及若干 DOM 辅助方法。**M11** 增加 `position: relative`/`absolute`/`fixed` 及其偏移，`examples/gui/pelican-bike`（一个可玩的 2D 游戏）就构建在它之上。**M12** 明确了 DOM 节点生命周期（哪些变更释放、哪些保留），并让引擎内存有界：参见[节点生命周期](./gui/dom.md)与[内存与 GC](./gui/runtime.md)。**M13** 真正播放
 `<video>`/`<audio>`——一个 vendored 的最小 FFmpeg 在主线程解码，视频帧走图像
 纹理路径、音频进入 SDL 流，DOM 媒体 API 暴露 `play`/`pause`/`currentTime`/…
 与媒体事件。**M14** 增加了 `<canvas>`，配一个自研的 2D 软件光栅器（抗锯齿
@@ -212,6 +212,16 @@ FFmpeg `7.1`（可用 `SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION` /
       [布局](./gui/layout.md#变换m15)与[动画](./gui/animation.md#css-transformm15)；
       e2e 见 `tests/e2e/gui-transform.test.ts` 与
       `tests/e2e/gui-example-svg.test.ts`。
+16. **M16 — 内联 `<svg>`** ✅
+    - `<svg>` 是替换元素（`layout.*`）：固有尺寸先取 `width`/`height` 属性，
+      其次 `viewBox`，最后 300x150；常规盒树遍历不再进入其子元素。
+    - `inline_svg.{h,cpp}` 把子树序列化为独立 SVG 文档，并还原 HTML 解析器
+      小写掉的、区分大小写的名称（`viewBox`、`preserveAspectRatio`、
+      `linearGradient`、`gradientUnits` 等）。
+    - 绘制把 markup 挂在图像 op 上（`PaintImage::svg`），渲染器按绘制设备尺寸、
+      通过与 SVG 文件相同的 NanoSVG 缓存（`svg.{h,cpp}`）解析并光栅化；markup
+      缓存有界，DOM 变更会在下一次布局时重新序列化。e2e 见
+      `tests/e2e/gui-inline-svg.test.ts`。
 
 ## 进度日志
 
@@ -299,4 +309,11 @@ FFmpeg `7.1`（可用 `SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION` /
   `getBoundingClientRect` 返回变换后的包围盒。`examples/gui/pelican-svg` 用它
   为自己的画做动画；e2e 见 `tests/e2e/gui-transform.test.ts` 与
   `tests/e2e/gui-example-svg.test.ts`。
+- **M16** ✅ 内联 `<svg>`。`buildBoxTree` 把 `<svg>` 元素当作替换盒（固有尺寸
+  依次取 `width`/`height`、`viewBox`、300x150）并停止下探，
+  `inline_svg.{h,cpp}` 以规范 SVG 大小写序列化子树，绘制把 markup 放进
+  `PaintImage::svg`，`renderer_image.cpp` 通过 NanoSVG 缓存（`svg.{h,cpp}`，
+  markup 采用有界 LRU）按绘制设备像素尺寸光栅化。`win.inlineSvg` 诊断钩子
+  暴露序列化文档，`tests/e2e/gui-inline-svg.test.ts` 固定了尺寸、命中测试、
+  渐变、CSS 盒样式与 DOM 变更。
 

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

@@ -3,7 +3,8 @@
 > 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/async.md)
 
 实现位置：`runtime/xt_async.c`、`runtime/xt_coroutine.c`、`runtime/xt_promise.c`、
-`runtime/xt_generator.c`、`runtime/xt_loop.c`、`runtime/xt_performance.c`。
+`runtime/xt_generator.c`、`runtime/xt_loop.c`、`runtime/xt_async_io.c`、
+`runtime/xt_performance.c`。
 
 ## async / await
 
@@ -35,4 +36,14 @@
 - `setTimeout` / `clearTimeout` / `setInterval` / `clearInterval` / `setImmediate` / `clearImmediate` / `queueMicrotask` 与 `performance.now`（单调递增的小数毫秒）。
 - 定时器使用数字 id；未实现 `Timeout` / `Immediate` 对象。
 - 定时器 settle 的 promise 可以被 await：async 函数体在 pending promise 上挂起，定时器触发时恢复。套接字与服务端（`net`、`http`、`dgram`）的回调在同一事件循环上投递。
-- `fetch` 是阻塞的，`fs/promises` 在 settle 前同步完成 I/O —— 见[运行时偏差](../unimplemented/deviations.md)。异步生成器清理限制也在同一页列出。
+- `fetch` 与 `fs/promises` 由 reactor 驱动而不是阻塞 —— 见下一节。
+
+## 异步 I/O offload
+
+- `runtime/xt_async_io.c` 维护一个小型工作线程池（默认 4 个，惰性创建）。每个 job 分成两半：worker 上的 `run` 只能访问纯 C 内存；主线程上的 `complete` 才构造值并 settle promise。这个拆分让回收器与值模型保持单线程。
+- job 完成后通过自管道（POSIX）或回环 UDP 套接字（Windows）唤醒 `select(2)`；reactor 也会轮询线程池，因此唤醒失败只会退化为短暂等待，而不会挂起。
+- job 排队或运行期间，每个 job 最多四个值（promise；对 `fetch` 还有 headers 对象）保存在 job 的 root 槽中，由回收器扫描。
+- `fetch` 把每一跳请求/重定向作为 job 执行；`fs/promises` 把每个文件与描述符操作作为 job 执行。两者都不会阻塞定时器、套接字或其他 `await`。
+- 仍有 job 未完成时事件循环保持存活（`xt_loop_has_work`），线程池空闲后退出。
+
+异步表面的已知限制（`fetch` 无 TLS/流式、`fs.watch` 不触发、线程池固定 4 个 worker）列在[运行时偏差](../unimplemented/deviations.md)与各 Node 页面。

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

@@ -2,11 +2,30 @@
 
 > 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/fetch.md)
 
-实现位置：`runtime/xt_fetch.c`。
+实现位置：`runtime/xt_fetch.c`、`runtime/xt_fetch/async.inc`、`runtime/xt_async_io.c`。
 
-- 全局 `fetch(input, init)` 是阻塞式 HTTP/1.1 客户端，返回的 promise 已经 settle（交换同步完成，不经过 reactor 调度）。
+- 全局 `fetch(input, init)` 是 HTTP/1.1 客户端。阻塞的套接字交换（`getaddrinfo`、connect、send、receive）运行在异步 I/O 工作线程池上，因此进行中的请求**不会**卡住事件循环：定时器、套接字与其他 `await` 继续运行，promise 在 reactor 派发完成结果时 settle。
+- 重定向在主线程上处理：每一跳是一次 offload 交换，最多 20 次；301/302/303 会把 POST 改成 GET。
 - 只接受 `http://` URL —— 由于未链接 TLS 后端，`https://` 会以 `TypeError` 拒绝。
-- 选项：`method`、`headers`（普通对象或 `Headers`）、`body` 与 `redirect`（`follow` / `manual` / `error`）；最多跟随 20 次重定向，并在 301/302/303 时将 POST 改为 GET。
-- 解析出的 `Response` 形状对象暴露 `ok` / `status` / `statusText` / `url` / `headers` 以及 `text()` / `json()` / `arrayBuffer()` / `bytes()` / `clone()`。
+- 选项：`method`、`headers`（普通对象或 `Headers`）、`body` 与 `redirect`（`follow` / `manual` / `error`）。
+- 解析出的 `Response` 形状对象暴露 `ok` / `status` / `statusText` / `url` / `headers` 以及 `text()` / `json()` / `arrayBuffer()` / `bytes()` / `clone()`。响应体在 promise settle 前已完整缓冲；不支持流式响应体。
 - `Headers` 大小写不敏感，提供 `get` / `has` / `set` / `append` / `delete` / `keys` / `values` / `entries` / `forEach` / `getSetCookie`。
 - 非法 URL 与网络失败会以 `TypeError` 拒绝。
+
+```ts
+async function main(): Promise<void> {
+  const response = await fetch("http://127.0.0.1:8080/status");
+  console.log(response.status, await response.text());
+}
+main();
+```
+
+在请求完成前安排的定时器会在交换仍在进行时触发：
+
+```ts
+const pending = fetch("http://127.0.0.1:8080/slow");
+setTimeout(() => console.log("timer"), 10); // 会在 150ms 的响应之前运行
+await pending;
+```
+
+已知限制（仅 `http://`、无 TLS、响应体整体缓冲）列在[运行时偏差](../unimplemented/deviations.md)。

package/doc/zh-CN/implemented/node/fs-promises.md

@@ -2,13 +2,15 @@
 
 > 属于[Node 扩展：已实现](../node.md) · [English](../../../implemented/node/fs-promises.md)
 
-实现位置：`src/extensions/node/fs-promises/index.ts`、`runtime/ext_node/fs/promises.c`
+实现位置：`src/extensions/node/fs-promises/index.ts`、`runtime/ext_node/fs/async_*.c`、`runtime/ext_node/fs/promises.c`
 
-无异步 I/O 调度器，故每个函数把对应的同步 `fs` 实现包进**已 settle 的 Promise**。失败时会以同步形式抛出的同构 Node `Error`（含 `code` / `errno` / `syscall` / `path`）**reject**。`fs.promises` 也可从 `fs` 模块访问（`import { promises as fsp } from "fs"`），两个命名空间都暴露 `constants` 对象。
+每个函数都会向运行时的异步 I/O 线程池（`runtime/xt_async_io.c`）提交一个 job：阻塞的系统调用在 worker 线程上执行，promise 在事件循环上 settle。因此 `await` 在大文件读取、慢速网络文件系统或描述符操作进行期间会让出，`then` / `catch` 保持标准 Promise 语义。失败时会以与同步形式相同的 Node `Error`（含 `code` / `errno` / `syscall` / `path`）**reject**。
+
+`fs.promises` 也可从 `fs` 模块访问（`import { promises as fsp } from "fs"`），两个命名空间都暴露 `constants` 对象。
 
 Promise 导出：`readFile`、`writeFile`、`appendFile`、`mkdir`、`readdir`、`rm`、`unlink`、`rmdir`、`rename`、`copyFile`、`cp`、`realpath`、`stat`、`lstat`、`statfs`、`access`、`open`、`chmod`、`lchmod`、`chown`、`lchown`、`truncate`、`utimes`、`lutimes`、`link`、`symlink`、`readlink`、`mkdtemp`、`opendir`、`glob`、`watch`。
 
-`open(...)` 解析为 **`FileHandle`**，带有：`read`、`write`、`readFile`、`writeFile`、`appendFile`、`close`、`stat`、`truncate`、`chmod`、`chown`、`utimes`、`sync`、`datasync`。
+`open(...)` 解析为 **`FileHandle`**，带有：`read`、`write`、`readFile`、`writeFile`、`appendFile`、`close`、`stat`、`truncate`、`chmod`、`chown`、`utimes`、`sync`、`datasync`。这些方法同样会 offload；`read(buffer, …)` 会在 worker 完成后填充调用方的 `Buffer`。
 
 ```ts
 import { readFile, writeFile, open } from "fs/promises";
@@ -23,5 +25,6 @@ async function main(): Promise<void> {
 main();
 ```
 
+工作由固定的小型线程池（4 个 worker）执行，完成结果按每个 worker 的提交顺序派发；相互独立的操作可以重叠。任何 job 都不会阻塞其他 `await`、定时器或套接字回调。
 
 已知偏差见[未实现：`fs/promises`](../../unimplemented/node/fs-promises.md)。

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

@@ -17,7 +17,7 @@ TypeScript 导出与 C 实现一一对应。新增模块不需要改动核心编
 | 模块 | 页面 | 说明 |
 | --- | --- | --- |
 | `fs` | [fs](./node/fs.md) | 仅同步 API |
-| `fs/promises` | [fs/promises](./node/fs-promises.md) | 把同步 API 包进已 settle 的 Promise |
+| `fs/promises` | [fs/promises](./node/fs-promises.md) | 由 reactor 驱动、跑在异步 I/O 线程池上的文件与 `FileHandle` 操作 |
 | `path` | [path](./node/path.md) | `path.<name>(...)` 命名空间调用 |
 | `os` | [os](./node/os.md) | `os.<name>(...)` 命名空间调用 |
 | `process` | [process](./node/process.md) | 对象：方法与属性 |

package/doc/zh-CN/implemented.md

@@ -31,7 +31,7 @@
 - [集合](./implemented/collections.md) —— Map、Set、WeakMap、WeakSet、WeakRef、迭代
 - [类型化数组与二进制数据](./implemented/typed-arrays.md) —— 类型化数组、ArrayBuffer、DataView
 - [异步、Promise 与生成器](./implemented/async.md) —— async/await、异步生成器、Promise、定时器
-- [fetch](./implemented/fetch.md) —— 阻塞式 HTTP/1.1 客户端与 Headers
+- [fetch](./implemented/fetch.md) —— 由 reactor 驱动的 HTTP/1.1 客户端与 Headers
 
 ### 模块与工具
 

package/doc/zh-CN/unimplemented/deviations.md

@@ -14,7 +14,7 @@
 | 数组越界 / 稀疏 | 越界访问返回 `undefined`；对 `arr.length` 赋值会截断 / 扩展，但不区分稀疏空洞 |
 | 内存管理 | 非移动标记-清扫回收器（在 `xt_alloc` 之后）：显式根、子系统根提供者与保守 C 栈扫描。单线程、stop-the-world；无移动/压缩与分代 |
 | 函数 `arity` / 调用参数个数 | 无参数个数校验；`fn.length` 报告声明的 arity，但调用不做校验 |
-| `async` / `await` | 已在栈式协程上真实挂起；`await` 总会排入一次微任务（非 Promise 与已 settle 的 Promise 也一样），因此与 pending `.then` 回调的交错顺序符合规范。顶层 `await` 会阻塞事件循环等待，而不是让出模块主体。`fs/promises` 仍在 settle 前同步完成 I/O；`fetch` 是阻塞的。异步生成器可在 `await` 与 `yield` 处挂起，`for await...of` 每次迭代等待一步 |
+| `async` / `await` | 已在栈式协程上真实挂起；`await` 总会排入一次微任务（非 Promise 与已 settle 的 Promise 也一样），因此与 pending `.then` 回调的交错顺序符合规范。顶层 `await` 会阻塞事件循环等待，而不是让出模块主体。`fs/promises` 与 `fetch` 把阻塞工作 offload 到 4 线程池并在 reactor 上 settle。异步生成器可在 `await` 与 `yield` 处挂起，`for await...of` 每次迭代等待一步 |
 | 异步生成器清理 | `for await...of` 提前退出时不会调用迭代器的 `return()`。异步生成器中的 `yield*` 只委托同步可迭代对象。在挂起的 `yield` 处调用 `.return()` 会直接完成而不执行 `finally`（与同步生成器相同的限制） |
 | `super` | `super.x` / `super(...)` 取 `this` 原型的原型；单级继承正确，继承深度 > 1 时可能不准确 |
 | `Error.stack` | 仅函数级帧：每帧为 `at 名称 (文件:行)`，行号取自函数声明（最内层帧会更新为错误构造处）；没有列号，生成器 / `async` 函数体不产生帧（它们会切换栈） |

package/doc/zh-CN/unimplemented/node/async.md

@@ -5,13 +5,16 @@
 已实现部分：
 
 - 核心事件循环 `runtime/xt_loop.c`（`select(2)` 反应堆），`net` / `dgram` / `http` 均构建于其上。
-- `Promise`、`async` / `await` 已可用（见核心文档），`fs/promises` 返回 Promise。
+- 异步 I/O offload `runtime/xt_async_io.c`：阻塞的文件与 HTTP 客户端工作在 4 个工作线程上执行，并在 reactor 上完成，因此 `fs/promises` 与 `fetch` 不会卡住定时器或套接字。
+- `Promise`、`async` / `await` 已可用（见核心文档），`fs/promises` 返回从 reactor settle 的 Promise。
 - 定时器已作为全局函数提供：`setTimeout` / `clearTimeout` / `setInterval` / `clearInterval` 运行在核心反应堆上，并在仍有定时器时保持进程存活。
 - 提供独立的 `EventEmitter`（`events` 模块，同时也是全局构造函数）；流与套接字额外具备内部发射器方法（`on` / `addListener` / `once` / `off` / `removeListener` / `emit`）。
 
 仍未实现：
 
 - Node 的 `Timeout` 对象（`setTimeout` 返回数字 id；`setImmediate` 与 `queueMicrotask` 已作为全局函数提供）。
-- 真正的异步 I/O 调度：`fs/promises` 实质是同步操作的即时 settle 包装，不会在等待 I/O 时让出。
+- 文件监听：`fs.watch` / `fs/promises.watch` 返回惰性对象；没有 inotify/kqueue/ReadDirectoryChangesW 后端。
+- `Dir.read` / `Dir.close` 立即调用回调，回调式 `fs.readFile` / `fs.writeFile` / … 仍不支持（请用 `fs/promises` 或 `*Sync` 形式）。
 - 流与套接字的内置 `once` 等同 `on`（不具「触发一次后移除」语义）；`events` 模块的 `EventEmitter` 实现了真正的 `once`。
-- `net` 的 `connect` 为阻塞式；HTTP 响应要求 `Connection: close`，不做 keep-alive / 分块传输 / 流水线复用。
+- `net` 的 `connect` 仍是在套接字加入 reactor 之前执行的阻塞 `connect(2)`；HTTP 响应要求 `Connection: close`，不做 keep-alive / 分块传输 / 流水线复用。`fetch` 没有 TLS，且在 resolve 前缓冲整个响应体。
+- offload 线程池固定为 4 个 worker；没有线程池大小选项，也不支持对排队 job 的 `AbortSignal` 取消。

package/doc/zh-CN/unimplemented/node/fs-promises.md

@@ -2,11 +2,11 @@
 
 > 属于[Node 扩展：未实现](../node.md) · [English](../../../unimplemented/node/fs-promises.md)
 
-`fs/promises` 把每个同步 `fs` 调用包进一个已 settle 的 Promise（已实现表面见
-[已实现：`fs/promises`](../../implemented/node/fs-promises.md)）。
+`fs/promises` 现在把阻塞 I/O offload 到异步 I/O 线程池（已实现表面见[已实现：`fs/promises`](../../implemented/node/fs-promises.md)）；剩余差异主要是行为层面的：
 
-- I/O 是同步的：Promise 在 `await` 之前就已 settle，因此 await 它不会让出事件循环。
 - `FileHandle.appendFile` 行为等同 `writeFile`（按当前文件位置写入，而不是追加）。
 - `FileHandle.readFile()` 从当前描述符偏移读取。
-- `Dir.read` / `Dir.close`（同步与 Promise 形式）立即完成。
+- `Dir.read` / `Dir.close`（同步与 Promise 形式）立即调用回调；`Dir.readSync` / `closeSync` 仍是同步的。
 - `watch` resolve 为与 `fs.watch` 相同的、永不触发的 watcher；没有真正的文件监听后端。
+- 读写是一次性整体操作；没有流式 `FileHandle` 变体，也不支持 `AbortSignal` 取消。
+- 线程池固定为 4 个 worker；大量并发操作会排队（但仍不会阻塞事件循环）。

package/doc/zh-CN/unimplemented/node/fs.md

@@ -2,7 +2,7 @@
 
 > 属于[Node 扩展：未实现](../node.md) · [English](../../../unimplemented/node/fs.md)
 
-`fs` 现在实现了**同步** API 表面（文件、目录、描述符、元数据、链接、`cp`、`glob`、`Dir`、`constants`），`fs/promises` 将每个同步函数包进已 settle 的 Promise（见[已实现：`fs`](../../implemented/node/fs.md)与[已实现：`fs/promises`](../../implemented/node/fs-promises.md)）。其余仍未实现，因为 xbintsc 的 `fs` **没有异步 I/O 调度器后端**（核心事件循环已提供定时器与套接字）：
+`fs` 实现了**同步** API 表面（文件、目录、描述符、元数据、链接、`cp`、`glob`、`Dir`、`constants`），`fs/promises` 则把每个文件/描述符操作跑在异步 I/O 线程池上（见[已实现：`fs`](../../implemented/node/fs.md)与[已实现：`fs/promises`](../../implemented/node/fs-promises.md)）。仍缺少的主要是需要不同后端或回调管线的 API：
 
 | 未实现 API | 类别 |
 | --- | --- |
@@ -17,7 +17,7 @@
 - `readFileSync` 支持编码选项（默认/`utf8`/`ascii`/`latin1`/`binary`/`hex`/`base64`/`base64url`），但默认**不返回 `Buffer`**：即使提供了 `Buffer`（以普通对象模拟），`readFileSync` 仍以字符串返回。要读取原始字节请显式指定。
 - 未实现 `utf16le` / `ucs2` 解码（按文本返回字节）。
 - `watch` / `watchFile` / `unwatchFile` 返回 API 形态的发射器对象，`.close()` / `.on()` 方法存在但**不会触发**事件。
-- `Dir.read(cb)` / `Dir.close(cb)` 与 `FileHandle` 异步方法都会**同步**完成（回调/Promise 立即被调用）。
+- `Dir.read(cb)` / `Dir.close(cb)` 会**同步**完成（回调立即被调用）；`FileHandle` 方法现在返回真正的 Promise。
 - `mkdtempSync` 总是向前缀追加 6 个随机字符（不要求以 `XXXXXX` 结尾）。
 - `globSync` 支持 `*`、`?`、`[...]`、`**`，但不支持 `exclude` 回调与 `follow`；`**` 不跟随符号链接（与 Node 默认一致）。
 - `cpSync` 的符号链接处理在常见场景下与 Node 一致，但不支持 `verbatimSymlinks`。

package/doc/zh-CN/unimplemented/node.md

@@ -8,10 +8,10 @@ Node 扩展实现了 21 个模块以及事件循环集成；已实现表面按
 ## 目录
 
 - [`fs`](./node/fs.md) —— 回调式异步操作、真正的文件监听、选项回调
-- [`fs/promises`](./node/fs-promises.md) —— 已 settle 的 Promise 背后仍是同步 I/O、`FileHandle` 偏差
+- [`fs/promises`](./node/fs-promises.md) —— `FileHandle` 追加/读取偏移、`Dir` 回调立即完成、`watch` 不触发、无取消
 - [完全未实现的模块](./node/modules.md) —— `https`、`readline`、`tls`、`cluster`、`vm` 等
 - [全局对象与命名空间](./node/globals.md) —— `global`、`__dirname`、`node_modules` 之外的 `require`
-- [异步与事件循环模型](./node/async.md) —— 无异步 I/O 调度、阻塞式 `connect`、无 keep-alive
+- [异步与事件循环模型](./node/async.md) —— 文件监听缺失、阻塞式 `net.connect`、无 keep-alive、固定大小线程池
 - [Bun 扩展](./node/bun.md) —— 仅为设计示例
 
 模块的已实现页面会链接到对应限制页；限制解除后，把条目移到

package/doc/zh-CN/unimplemented/toolchain.md

@@ -9,6 +9,6 @@
 | 类型检查器 | ✗ 仅定义诊断码，无 checker |
 | 完整标准库 | 部分：Math / JSON / Date / Map / Set / RegExp / `Error` / `BigInt` / `Symbol` / `structuredClone` 已实现；String.normalize 缺失 |
 | 多文件模块打包 | 部分：相对路径 `.ts` 打包、ESM `node_modules` 包、命名空间导入、裸说明符扩展模块导入已实现；CommonJS 仅在 `node_modules` 内处理；循环依赖 / 实时绑定未实现 |
-| 异步运行时 | ✓ `async`/`await` 在 `select(2)` reactor 上对 pending promise 挂起：定时器、TCP 套接字与 promise 回调都能恢复协程。仍缺：真正的异步 I/O 调度（`fs/promises` 会先阻塞完成 I/O 再 settle）、非阻塞 `fetch` 与 worker 线程（worker 是子进程） |
+| 异步运行时 | ✓ `async`/`await` 在 `select(2)` reactor 上对 pending promise 挂起：定时器、TCP 套接字、offload 的文件/HTTP 工作与 promise 回调都能恢复协程。仍缺：真正的 OS 级文件监听、非阻塞 `net.connect`、`fetch` 的 TLS，以及用户可见的 worker 线程（`worker_threads` 仍用子进程） |
 | Windows 二进制产物验证 | 构建层已适配（`.exe` 后缀、链接参数分支），并在 CI 中验证 |
 | 精确的 ECMAScript 数值 / 字符串 / 比较语义 | 部分，见[运行时偏差](./deviations.md) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xbintsc",
-  "version": "0.5.20",
+  "version": "0.5.21",
   "description": "xbintsc - a TypeScript binary compiler (TypeScript -> LLVM IR -> native binary)",
   "type": "module",
   "license": "MIT",