xbintsc 0.5.20 → 0.5.22

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

@@ -10,7 +10,9 @@
 CSS 盒中。
 
 引擎侧的对象是 `xtgui::Canvas2D`（`runtime/ext_gui/canvas.{h,cpp}`）——一块 RGBA8 位图
-加上 2D 绘制状态。光栅器位于 `canvas_raster.cpp`；DOM 绑定位于 `dom_api_canvas.cpp`；
+加上 2D 绘制状态。光栅器位于 `canvas_raster.cpp`，描边几何（端点、连接、虚线）位于
+`canvas_stroke.cpp`，渐变位于 `canvas_gradient.cpp`，绘制状态解析位于
+`canvas_style.cpp`；DOM 绑定位于 `dom_api_canvas.cpp` / `dom_api_canvas_extra.cpp`；
 按窗口的生命周期位于 `gui_canvas.cpp`。
 
 ## 获取上下文
@@ -31,6 +33,11 @@ const ctx = canvas.getContext("2d"); // 其他上下文类型返回 null
 以相反方向环绕时能形成空洞）。轴对齐矩形（变换中 `b == 0 && c == 0`）走直接的覆盖率
 快速路径。混合为非预乘 source-over，并按 `globalAlpha` 缩放。
 
+填充或描边可以使用纯色，也可以使用 **`CanvasGradient`**。渐变的坐标属于用户空间，
+因此光栅器会先用当前变换的逆矩阵把每个设备像素映射回用户空间再采样——形状被平移、
+缩放或旋转时，渐变仍然贴在形状上。描边被展平为线段四边形，再按 `lineJoin`/`lineCap`
+补上连接/端点形状；虚线模式先把折线切成“实线”片段，然后用同样的端点规则描边。
+
 Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点为键（与
 `<video>`/`<audio>` 解码表结构相同）。当节点被丢弃（`loadHTML`、窗口关闭/退出，或丢弃
 子树的变更操作）时随之释放，并释放对应的 GPU 纹理。
@@ -39,21 +46,34 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 
 状态与变换：`save` / `restore`（会恢复变换、线宽、透明度、字体/文本设置**以及**
 填充/描边样式）、`translate`、`rotate`、`scale`、`transform(a,b,c,d,e,f)`、
-`setTransform`、`resetTransform`。
-
-样式与设置：`fillStyle` / `strokeStyle`（层叠所用的颜色解析器能识别的 CSS 颜色）、
-`lineWidth`、`globalAlpha`、`font`（CSS 字体简写，解析出字体族、字号与粗体/斜体——
-默认 `10px sans-serif`）、`textAlign`（`start`/`left`、`center`、`right`/`end`）与
-`textBaseline`（`alphabetic`、`top`、`middle`、`bottom`、`hanging`、`ideographic`）。
-读取属性返回上次赋予的值；赋予无法解析的颜色会保留原值。
-
-路径：`beginPath`、`closePath`、`moveTo`、`lineTo`、`rect`、`arc`、
-`quadraticCurveTo`、`bezierCurveTo`，然后 `fill`（多环、非零环绕）或 `stroke`。贝塞尔
-与二次曲线段会被展平为线段；弧线同样被展平，每条子路径按线段四边形描边，并在每个连接
-处补一个圆盘。
+`setTransform`、`resetTransform`、`getTransform`（返回带 `a`…`f` 与 `is2D` 的对象）。
+变换按 canvas 的顺序组合：`translate(x, y); rotate(a)` 围绕平移后的原点旋转。
+
+样式与设置：`fillStyle` / `strokeStyle`（层叠所用的颜色解析器能识别的 CSS 颜色，或
+`CanvasGradient`）、`lineWidth`、`globalAlpha`、`lineCap`（`butt`/`round`/`square`）、
+`lineJoin`（`miter`/`round`/`bevel`）、`miterLimit`、`lineDashOffset`、`font`
+（CSS 字体简写，解析出字体族、字号与粗体/斜体——默认 `10px sans-serif`）、
+`textAlign`（`start`/`left`、`center`、`right`/`end`）与 `textBaseline`
+（`alphabetic`、`top`、`middle`、`bottom`、`hanging`、`ideographic`）。读取属性返回
+上次赋予的值；赋予无法解析的颜色会保留原值。
+
+渐变：`createLinearGradient(x0, y0, x1, y1)` 与
+`createRadialGradient(x0, y0, r0, x1, y1, r1)` 返回带
+`addColorStop(offset, color)` 的 `CanvasGradient`。色标是**活的**：在
+`fillStyle = gradient` 之后追加的色标会影响后续填充，且 `fillStyle`/`strokeStyle`
+的读取返回同一个渐变句柄。径向渐变按到**外圆**圆心（`x1, y1`）的距离插值，因此目前
+会忽略 `x0`/`y0`——请使用同心圆（`x0 == x1`、`y0 == y1`）。
+
+路径：`beginPath`、`closePath`、`moveTo`、`lineTo`、`rect`、`roundRect`、`arc`、
+`ellipse`、`quadraticCurveTo`、`bezierCurveTo`，然后 `fill`（多环、非零环绕）或
+`stroke`。贝塞尔与二次曲线段会被展平为线段；弧线与椭圆同样被展平。`roundRect` 只接受
+单个圆角半径数字（数组形式尚未实现）。
 
 矩形：`clearRect`、`fillRect`、`strokeRect`。
 
+虚线：`setLineDash(segments)` / `getLineDash()` / `lineDashOffset` 实现标准规则
+（奇数长度列表会复制一遍，负数/非有限值会被忽略，全零列表表示实线）。
+
 文本：`measureText(text)`（返回 `{ width }`）、`fillText(text, x, y)` 与
 `strokeText(text, x, y)`。文本经 HarfBuzz 排版、FreeType 光栅化（与 HTML 文本相同的
 技术栈），按变换的近似缩放绘制。**仅支持平移与均匀缩放**——旋转或斜切变换仍会把每个
@@ -70,11 +90,10 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 
 ## 尚未实现
 
-渐变与图案、阴影、`clip()`、`globalCompositeOperation`、线段连接/端点/虚线/斜接、
-`setLineDash`、`createLinearGradient`/`createPattern`、`putImageData`、
-`createImageData`、`isPointInPath`、`getTransform`、以 `DOMMatrix` 调用的
+图案（`createPattern`）、阴影、`clip()`、`globalCompositeOperation`、
+`putImageData`、`createImageData`、`isPointInPath`、以 `DOMMatrix` 调用的
 `setTransform`、可切换图像平滑的 `drawImage`、`toDataURL`/`toBlob`、把 `<canvas>` 用作
 CSS `background-image`，以及离屏画布（`OffscreenCanvas`、
-`transferControlToOffscreen`）。
+`transferControlToOffscreen`）。`roundRect` 只接受单个半径，径向渐变会忽略内圆偏移。
 
 另见[媒体](./media.md)：`drawImage` 与纹理上传所共享的图像/视频/音频解码栈。

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`。
 
 ## 进度日志
 
@@ -286,8 +296,12 @@ FFmpeg `7.1`（可用 `SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION` /
   （4 条子扫描线 + 水平解析覆盖率、非零环绕），`getContext("2d")` 句柄及其 API
   在 `dom_api_canvas.cpp` 绑定，`gui_canvas.cpp` 持有按窗口的生命周期。位图经
   图像纹理路径上传（`renderer_image.cpp`），显示列表携带 `canvas_id`
-  （`paint.*`）。参见 [Canvas](./gui/canvas.md)；e2e 见
-  `tests/e2e/gui-canvas.test.ts`。
+  （`paint.*`）。此后绘制面又补齐了线性/径向渐变（`canvas_gradient.cpp`）、
+  `ellipse`/`roundRect`、线段端点/连接/斜接上限与虚线模式（`canvas_style.cpp`、
+  `canvas_stroke.cpp`）以及 `getTransform`；`transform` 改为后乘，因此
+  `translate(x, y); rotate(a)` 围绕平移后的原点旋转，而
+  `examples/gui/pelican-canvas` 完全用这些 API 画出会动的鹈鹕骑自行车。参见
+  [Canvas](./gui/canvas.md)；e2e 见 `tests/e2e/gui-canvas.test.ts`。
 - **M15** ✅ CSS `transform` / `transform-origin`。新的翻译单元
   （`transform.{h,cpp}`）把 `translate`/`translateX`/`translateY`/`scale`/
   `scaleX`/`scaleY`/`rotate`/`matrix`（以及 `translate3d`/`scale3d`，其 `z` 参数被丢弃）
@@ -299,4 +313,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.22",
   "description": "xbintsc - a TypeScript binary compiler (TypeScript -> LLVM IR -> native binary)",
   "type": "module",
   "license": "MIT",