xbintsc 0.5.20 → 0.5.22

package/doc/gui/canvas.md

@@ -13,8 +13,11 @@ video frames (`renderer_image.cpp`), so the GPU scales it into the CSS box.
 
 The engine-side object is `xtgui::Canvas2D`
 (`runtime/ext_gui/canvas.{h,cpp}`) — one RGBA8 bitmap plus the 2D drawing state.
-The rasteriser lives in `canvas_raster.cpp`; the DOM bindings live in
-`dom_api_canvas.cpp`, and the per-window lifetime in `gui_canvas.cpp`.
+The rasteriser lives in `canvas_raster.cpp`, stroke geometry (caps, joins,
+dashes) in `canvas_stroke.cpp`, gradients in `canvas_gradient.cpp`, and drawing
+state parsing in `canvas_style.cpp`; the DOM bindings live in
+`dom_api_canvas.cpp` / `dom_api_canvas_extra.cpp`, and the per-window lifetime in
+`gui_canvas.cpp`.
 
 ## Getting a context
 
@@ -37,6 +40,14 @@ horizontal coverage** pass, and fills paths with the **non-zero winding rule**
 (`b == 0 && c == 0` in the transform) takes a direct coverage fast path.
 Blending is non-premultiplied source-over, scaled by `globalAlpha`.
 
+A fill or stroke paints with a solid colour **or a `CanvasGradient`**. Gradient
+coordinates are user-space coordinates, so the rasteriser maps each device pixel
+back through the inverse of the current transform before sampling; this keeps a
+gradient attached to the shape when the shape is translated, scaled or rotated.
+Strokes are flattened into segment quads plus the join/cap shapes selected by
+`lineJoin`/`lineCap`; a dash pattern first splits the polyline into its "on"
+pieces, then those pieces are stroked with the same caps.
+
 Canvas pixels are **not** touched by the garbage collector: a canvas is owned by
 the window, keyed by its DOM node (the same shape as the `<video>`/`<audio>`
 decode table). It is released when the node is dropped (`loadHTML`, window
@@ -48,24 +59,39 @@ matching GPU texture.
 State and transforms: `save` / `restore` (which restore the transform, line
 width, alpha, font/text settings **and** the fill/stroke styles),
 `translate`, `rotate`, `scale`, `transform(a,b,c,d,e,f)`, `setTransform`,
-`resetTransform`.
+`resetTransform`, `getTransform` (returns an object with `a`…`f` and `is2D`).
+Transforms compose in canvas order: `translate(x, y); rotate(a)` rotates around
+the translated origin.
 
 Styles and settings: `fillStyle` / `strokeStyle` (CSS colors understood by the
-cascade's color parser), `lineWidth`, `globalAlpha`, `font` (a CSS font
-shorthand resolving to family, size and bold/italic — default
-`10px sans-serif`), `textAlign` (`start`/`left`, `center`, `right`/`end`) and
-`textBaseline` (`alphabetic`, `top`, `middle`, `bottom`, `hanging`,
-`ideographic`). Reading a property returns the value last assigned; assigning an
-unparseable color keeps the previous one.
-
-Paths: `beginPath`, `closePath`, `moveTo`, `lineTo`, `rect`, `arc`,
-`quadraticCurveTo`, `bezierCurveTo`, then `fill` (multi-loop, non-zero winding)
-or `stroke`. Bezier and quadratic segments are flattened into line segments;
-arcs are flattened too and each subpath is stroked as segment quads plus a disc
-at each joint.
+cascade's color parser, or a `CanvasGradient`), `lineWidth`, `globalAlpha`,
+`lineCap` (`butt`/`round`/`square`), `lineJoin` (`miter`/`round`/`bevel`),
+`miterLimit`, `lineDashOffset`, `font` (a CSS font shorthand resolving to
+family, size and bold/italic — default `10px sans-serif`), `textAlign`
+(`start`/`left`, `center`, `right`/`end`) and `textBaseline` (`alphabetic`,
+`top`, `middle`, `bottom`, `hanging`, `ideographic`). Reading a property returns
+the value last assigned; assigning an unparseable color keeps the previous one.
+
+Gradients: `createLinearGradient(x0, y0, x1, y1)` and
+`createRadialGradient(x0, y0, r0, x1, y1, r1)` return a `CanvasGradient` with
+`addColorStop(offset, color)`. Stops stay live, so a stop added after
+`fillStyle = gradient` affects later fills, and the `fillStyle`/`strokeStyle`
+getter returns the same gradient handle. Radial gradients interpolate by
+distance from the **outer** circle's centre (`x1, y1`), so `x0`/`y0` are
+currently ignored: use concentric circles (`x0 == x1`, `y0 == y1`).
+
+Paths: `beginPath`, `closePath`, `moveTo`, `lineTo`, `rect`, `roundRect`,
+`arc`, `ellipse`, `quadraticCurveTo`, `bezierCurveTo`, then `fill` (multi-loop,
+non-zero winding) or `stroke`. Bezier and quadratic segments are flattened into
+line segments; arcs and ellipses are flattened too. `roundRect` accepts one
+radius number (the array form is not implemented).
 
 Rectangles: `clearRect`, `fillRect`, `strokeRect`.
 
+Dashes: `setLineDash(segments)` / `getLineDash()` / `lineDashOffset` implement
+the standard pattern rules (an odd-length list is duplicated, negative or
+non-finite entries are ignored, an all-zero list means a solid line).
+
 Text: `measureText(text)` (returns `{ width }`), `fillText(text, x, y)` and
 `strokeText(text, x, y)`. Text is shaped with HarfBuzz and rasterised with
 FreeType (the same stack as HTML text) at the transform's approximate scale.
@@ -87,12 +113,12 @@ Out-of-bounds pixels are transparent.
 
 ## Not implemented
 
-Gradients and patterns, shadows, `clip()`, `globalCompositeOperation`, line
-joins/caps/dashes/mitre, `setLineDash`, `createLinearGradient`/`createPattern`,
-`putImageData`, `createImageData`, `isPointInPath`, `getTransform`,
-`setTransform` with a `DOMMatrix`, `drawImage` with an image smoothing toggle,
-`toDataURL`/`toBlob`, `<canvas>` as a CSS `background-image`, and offscreen
-canvases (`OffscreenCanvas`, `transferControlToOffscreen`).
+Patterns (`createPattern`), shadows, `clip()`, `globalCompositeOperation`,
+`putImageData`, `createImageData`, `isPointInPath`, `setTransform` with a
+`DOMMatrix`, `drawImage` with an image smoothing toggle, `toDataURL`/`toBlob`,
+`<canvas>` as a CSS `background-image`, and offscreen canvases
+(`OffscreenCanvas`, `transferControlToOffscreen`). `roundRect` takes a single
+radius, and radial gradients ignore the inner circle's offset.
 
 See also [Media](./media.md) for the image/video/audio decode stack that
 `drawImage` and the texture upload share.

package/doc/gui/known-issues.md

@@ -34,20 +34,21 @@
   *class change* on a flex container has also been observed to crash the same
   way; `examples/gui/pelican-bike` reveals its game-over overlay with `opacity`
   instead.
+- **SVG is NanoSVG's subset.** SVG *files* (`<img src="logo.svg">`) and inline
+  `<svg>` trees share the vendored NanoSVG parser/rasteriser
+  (`runtime/ext_gui/svg.cpp`, `inline_svg.cpp`), which renders
+  `path`/`rect`/`circle`/`ellipse`/`line`/`polyline`/`polygon`, groups, `defs`
+  gradients and class-based `<style>` rules. `<text>`, `<use>`, filters, masks
+  and clip paths are not rendered, and CSS applied by the document cascade does
+  not reach inside the artwork (fill/stroke are SVG presentation attributes,
+  not CSS properties here). Vector art that needs those has to be rasterised
+  beforehand, drawn from boxes, or restricted to the supported syntax. See
+  [Media](./media.md#images-m6a).
 
 ## Open questions
 
 - Whether Linux ships X11, Wayland, or both in the first cut. (Decision:
   X11 first, Wayland later.)
-- **SVG:** SVG *files* are supported through the image loader
-  (`<img src="logo.svg">`): `runtime/ext_gui/svg.cpp` wraps the vendored
-  **NanoSVG** parser/rasteriser and `image.{h,cpp}` treats an SVG as a vector
-  image, rasterised at the drawn pixel size. Inline `<svg>` **trees** in a
-  document are still not supported: the HTML parser knows elements and
-  attributes, the layout engine knows boxes, and paint knows
-  rectangles/text/images, so `<svg>` subtrees would need a whole second
-  geometry+paint path. Vector art therefore has to arrive as an SVG/PNG file or
-  be drawn from boxes, as `examples/gui/pelican-bike` does.
 - **Windows: the C++ runtime must not be named on the link line.** `gui.lib` is
   built with the *static* CRT (`CMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded`) and
   every engine object records `libcpmt` as a dependent library, which is also

package/doc/gui/media.md

@@ -12,7 +12,9 @@ size cache (`stbi_info`). Paths accept a `file://` prefix and percent-encoding.
 library (parse + anti-aliased scanline rasteriser), detects an SVG by extension
 or by its contents, and produces the same RGBA8 `Image` the pipeline already
 consumes. `stb_image` cannot decode SVG, so this is what makes
-`<img src="logo.svg">` work.
+`<img src="logo.svg">` work. The same parser is used for an inline `<svg>`
+subtree, whose DOM nodes are serialized into a document first
+(`inline_svg.{h,cpp}`).
 
 - `<img>` is a replaced element (`display: inline-block`): layout gives it the
   CSS size when set, otherwise the intrinsic pixel size, and preserves the
@@ -27,12 +29,39 @@ consumes. `stb_image` cannot decode SVG, so this is what makes
   pixels (logical size × the window's pixel density), preserving the viewBox
   aspect ratio, and cached by that size, so scaling or a HiDPI display produces
   a crisp render instead of a magnified bitmap.
+- An **inline** `<svg>` element is a replaced element like `<img>`, but its
+  source is the DOM subtree itself. `runtime/ext_gui/inline_svg.{h,cpp}`
+  serializes that subtree back into a standalone SVG document, restoring the
+  case-sensitive spellings NanoSVG matches (`viewBox`, `preserveAspectRatio`,
+  `linearGradient`, `gradientUnits`, …) that the HTML parser lowercased. Layout
+  sizes the box from the `width`/`height` attributes, else the `viewBox`, else
+  300x150; paint carries the markup on its image op and the renderer parses and
+  rasterises it at the drawn device pixel size through the same NanoSVG cache as
+  an SVG file. A DOM mutation re-serializes the subtree on the next layout (so
+  `setAttribute` and `innerHTML` both repaint the artwork), and the markup cache
+  is bounded (least-recently-used) so an animated document cannot grow it
+  without limit.
 - The parse is cached per path; the parse and rasteriser state are released in
   `xt_svg_shutdown` (`xt_image_shutdown`).
 
+Document CSS styles the `<svg>` **box** — size, margins, background, borders,
+`transform`, opacity, `display` — exactly as it styles any other element. The
+artwork inside it keeps SVG semantics: presentation attributes and the
+`class`-based rules of an SVG `<style>` block are read by NanoSVG, not by the
+HTML cascade, so `fill`/`stroke` are not CSS properties here. For layout, paint,
+hit testing and events the whole `<svg>` is one replaced box: its children get no
+DOM boxes, so a click's `e.target` is the `<svg>` element, not a `<rect>`. The
+renderer caches one texture per markup-and-size pair, so a program that rewrites
+its artwork every frame keeps a texture per variant; prefer animating the box
+(`transform`, `opacity`) or swapping between a small set of documents.
+
 Still to do for images: CSS `background-image: url(...)`, `data:` URIs,
-`object-fit`, 9-slice borders and inline `<svg>` elements (only SVG *files* are
-supported; see [Open questions](./known-issues.md#open-questions)).
+`object-fit` and 9-slice borders.
+
+Both kinds of SVG share NanoSVG's subset: `path`, `rect`, `circle`, `ellipse`,
+`line`, `polyline`, `polygon`, groups (`g`), `defs` with linear/radial gradients
+and class-based `<style>` rules rasterise; `<text>`, `<use>`, filters, masks and
+clip paths are not rendered (see [Known issues](./known-issues.md)).
 
 ## Video & audio (M13)
 

package/doc/gui.md

@@ -1,6 +1,6 @@
 # xbintsc GUI extension (self-hosted HTML/CSS renderer)
 
-Status: **M15** — features (M1–M14) are complete: HTML parsing, CSS selector
+Status: **M16** — features (M1–M15) are complete: HTML parsing, CSS selector
 matching, the cascade, computed styles and layout (block, inline, Flexbox and
 CSS positioning) are
 in place, and the engine *paints*: it builds a display list of rectangles, images
@@ -9,7 +9,9 @@ tested and delivered to native TS handlers, `:hover`/`:focus` are matched
 dynamically, `<img>` is sized from its intrinsic dimensions and drawn from a
 texture — PNG/JPEG/… bitmaps and SVG files alike, the latter rasterised at the
 drawn size so vector art stays crisp — and CSS transitions animate paint
-properties. **M8** adds an interactive
+properties. **M16** gives inline `<svg>` trees the same treatment: the subtree is
+serialized back into an SVG document and rasterised at the drawn device size, so
+an icon needs no separate file. **M8** adds an interactive
 DOM: element handles with stable identity, mutation (`appendChild`, `textContent`,
 `classList`, `style`, …) and element-level events with capture/bubbling.
 **M9** compiles `<script>` bodies ahead of time (inline and `<script src>`) — see
@@ -257,6 +259,18 @@ engine were Rust.
       [Layout](./gui/layout.md#transforms-m15) and
       [Animation](./gui/animation.md#css-transforms-m15); e2e in
       `tests/e2e/gui-transform.test.ts` and `tests/e2e/gui-example-svg.test.ts`.
+16. **M16 — inline `<svg>`** ✅
+    - `<svg>` is a replaced element (`layout.*`): its intrinsic size comes from
+      the `width`/`height` attributes, else the `viewBox`, else 300x150, and the
+      normal box walk does not descend into its children.
+    - `inline_svg.{h,cpp}` serializes the subtree into a standalone SVG document,
+      restoring the case-sensitive names the HTML parser lowercased (`viewBox`,
+      `preserveAspectRatio`, `linearGradient`, `gradientUnits`, …).
+    - Paint carries the markup on its image op (`PaintImage::svg`) and the
+      renderer parses/rasterises it at the drawn device size through the same
+      NanoSVG cache as an SVG file (`svg.{h,cpp}`); the markup cache is bounded
+      and a DOM mutation re-serializes on the next layout. e2e in
+      `tests/e2e/gui-inline-svg.test.ts`.
 
 ## Progress log
 
@@ -340,7 +354,13 @@ engine were Rust.
   `getContext("2d")` handle and its API are bound in `dom_api_canvas.cpp`, and
   `gui_canvas.cpp` owns the per-window lifetime. The bitmap uploads through the
   image texture path (`renderer_image.cpp`) and the display list carries a
-  `canvas_id` (`paint.*`). See [Canvas](./gui/canvas.md); e2e in
+  `canvas_id` (`paint.*`). The drawing surface was later widened with linear /
+  radial gradients (`canvas_gradient.cpp`), `ellipse`/`roundRect`, line
+  caps/joins/miter limits and dash patterns (`canvas_style.cpp`,
+  `canvas_stroke.cpp`), and `getTransform`; `transform` now post-multiplies, so
+  `translate(x, y); rotate(a)` rotates around the translated origin, and
+  `examples/gui/pelican-canvas` draws an animated pelican on a bicycle entirely
+  with these APIs. See [Canvas](./gui/canvas.md); e2e in
   `tests/e2e/gui-canvas.test.ts`.
 - **M15** ✅ CSS `transform` / `transform-origin`. A new translation unit
   (`transform.{h,cpp}`) parses `translate`/`translateX`/`translateY`/`scale`/
@@ -355,4 +375,12 @@ engine were Rust.
   through the inverse, and `getBoundingClientRect` returns the transformed AABB.
   `examples/gui/pelican-svg` animates its artwork with it; e2e in
   `tests/e2e/gui-transform.test.ts` and `tests/e2e/gui-example-svg.test.ts`.
+- **M16** ✅ inline `<svg>`. `buildBoxTree` treats an `<svg>` element as a
+  replaced box (intrinsic size from `width`/`height`, then `viewBox`, then
+  300x150) and stops descending, `inline_svg.{h,cpp}` serializes the subtree with
+  canonical SVG casing, paint carries the markup on `PaintImage::svg`, and
+  `renderer_image.cpp` rasterises it at the drawn device pixel size through the
+  NanoSVG cache (`svg.{h,cpp}`, bounded LRU for markup). The `win.inlineSvg`
+  diagnostic exposes the serialized document, and `tests/e2e/gui-inline-svg.test.ts`
+  pins sizing, hit testing, gradients, CSS box styling and mutation.
 

package/doc/implemented/async.md

@@ -3,7 +3,8 @@
 > Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/async.md)
 
 Location: `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
 
@@ -11,7 +12,7 @@ Location: `runtime/xt_async.c`, `runtime/xt_coroutine.c`, `runtime/xt_promise.c`
 - The body runs synchronously until the first `await` of a pending promise, then suspends; settlement queues a microtask that resumes the coroutine.
 - An exception that escapes the body rejects that promise instead of throwing synchronously.
 - `await` on a non-promise or settled promise keeps the synchronous fast path and raises on rejection.
-- Each `async` call owns a private stack and swaps its `try` frame stack and GC stack region, so `await` survives `try`/`finally`, loops and closures. A promise settled from a timer, a socket callback or another coroutine resumes the suspended body on the microtask queue.
+- Each `async` call owns a private stack and swaps its `try` frame stack and GC stack region, so `await` survives `try`/`finally`, loops and closures. A promise settled from a timer, a socket callback, an offloaded file operation or another coroutine resumes the suspended body on the microtask queue.
 
 ## async generators
 
@@ -35,4 +36,16 @@ Location: `runtime/xt_async.c`, `runtime/xt_coroutine.c`, `runtime/xt_promise.c`
 - `setTimeout` / `clearTimeout` / `setInterval` / `clearInterval` / `setImmediate` / `clearImmediate` / `queueMicrotask` and `performance.now` (monotonic fractional milliseconds).
 - Timers use numeric ids; `Timeout` / `Immediate` objects are not implemented.
 - A promise settled from a timer can be awaited: the async body suspends on the pending promise and resumes when the timer fires. Sockets and servers (`net`, `http`, `dgram`) deliver their callbacks on the same loop.
-- `fetch` is blocking and `fs/promises` performs its I/O synchronously before settling — see [Runtime deviations](../unimplemented/deviations.md). Async generator cleanup limits are listed on the same page.
+- `fetch` and `fs/promises` are reactor-driven rather than blocking — see the next section.
+
+## Asynchronous I/O offload
+
+- `runtime/xt_async_io.c` owns a small pool of worker threads (four by default, created lazily). Jobs are split in two halves: a `run` function on a worker that may only touch plain C memory, and a `complete` function on the main thread that builds values and settles the promise. The split is what keeps the collector and the value model single-threaded.
+- A completed job wakes `select(2)` through a self-pipe (POSIX) or a loopback UDP socket (Windows); the reactor also polls the pool, so a failed wakeup degrades to a short wait instead of a hang.
+- While a job is queued or running, up to four values per job (its promise, and for `fetch` the headers object) are kept in the job's root slots and scanned by the collector.
+- `fetch` runs each request/redirect hop as a job; `fs/promises` runs every file and descriptor operation as a job. Neither blocks timers, sockets or other `await`s.
+- The event loop stays alive while jobs are outstanding (`xt_loop_has_work`), and exits once the pool is idle again.
+
+Known limits of the asynchronous surface (no TLS/streaming `fetch`, inert
+`fs.watch`, four-worker pool) are listed in
+[Runtime deviations](../unimplemented/deviations.md) and the Node pages.

package/doc/implemented/fetch.md

@@ -2,11 +2,43 @@
 
 > Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/fetch.md)
 
-Location: `runtime/xt_fetch.c`.
+Location: `runtime/xt_fetch.c`, `runtime/xt_fetch/async.inc`, `runtime/xt_async_io.c`.
 
-- Global `fetch(input, init)` is a blocking HTTP/1.1 client whose promise is already settled (the exchange happens synchronously; it is not scheduled on the reactor).
-- It accepts `http://` URLs only — `https://` rejects with a `TypeError` because no TLS backend is linked.
-- Options: `method`, `headers` (plain object or `Headers`), `body` and `redirect` (`follow` / `manual` / `error`); up to 20 redirects are followed, and a 301/302/303 switches POST to GET.
-- The resolved `Response`-shaped object exposes `ok` / `status` / `statusText` / `url` / `headers` plus `text()` / `json()` / `arrayBuffer()` / `bytes()` / `clone()`.
-- `Headers` is case-insensitive with `get` / `has` / `set` / `append` / `delete` / `keys` / `values` / `entries` / `forEach` / `getSetCookie`.
+- Global `fetch(input, init)` is an HTTP/1.1 client. The blocking socket exchange
+  (`getaddrinfo`, connect, send, receive) runs on the asynchronous I/O worker
+  pool, so a request in flight does **not** stall the event loop: timers, sockets
+  and other `await`s keep running and the promise settles when the reactor
+  dispatches the completed exchange.
+- Redirects are followed on the main thread: each hop is one offloaded
+  exchange, up to 20 redirects, and a 301/302/303 switches POST to GET.
+- It accepts `http://` URLs only — `https://` rejects with a `TypeError` because
+  no TLS backend is linked.
+- Options: `method`, `headers` (plain object or `Headers`), `body` and `redirect`
+  (`follow` / `manual` / `error`).
+- The resolved `Response`-shaped object exposes `ok` / `status` / `statusText` /
+  `url` / `headers` plus `text()` / `json()` / `arrayBuffer()` / `bytes()` /
+  `clone()`. The body is buffered before the promise settles; streaming bodies
+  are not implemented.
+- `Headers` is case-insensitive with `get` / `has` / `set` / `append` /
+  `delete` / `keys` / `values` / `entries` / `forEach` / `getSetCookie`.
 - Invalid URLs and network failures reject with a `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();
+```
+
+A timer scheduled before the request completes fires while the exchange is still
+in flight:
+
+```ts
+const pending = fetch("http://127.0.0.1:8080/slow");
+setTimeout(() => console.log("timer"), 10); // runs before the 150ms response
+await pending;
+```
+
+Known limits (only `http://`, no TLS, buffered body) are listed in
+[Runtime deviations](../unimplemented/deviations.md).

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

@@ -2,14 +2,20 @@
 
 > Part of [Node extension: implemented](../node.md) · [简体中文](../../zh-CN/implemented/node/fs-promises.md)
 
-Location: `src/extensions/node/fs-promises/index.ts`, `runtime/ext_node/fs/promises.c`
+Location: `src/extensions/node/fs-promises/index.ts`, `runtime/ext_node/fs/async_*.c`,
+`runtime/ext_node/fs/promises.c`.
 
-There is no asynchronous I/O scheduler, so each function wraps the corresponding
-synchronous `fs` implementation in an **already-settled Promise**. Failures
-**reject** with the same Node-shaped `Error` (with `code` / `errno` / `syscall` /
-`path`) that the synchronous form throws. `fs.promises` is also reachable from
-the `fs` module (`import { promises as fsp } from "fs"`), and both namespaces
-expose a `constants` object.
+Every function submits a job to the runtime's asynchronous I/O pool
+(`runtime/xt_async_io.c`): the blocking syscall runs on a worker thread and the
+promise settles on the event loop. `await` therefore yields while a large read,
+a slow network filesystem or a descriptor operation is in progress, and `then` /
+`catch` keep the usual Promise semantics. Failures **reject** with the same
+Node-shaped `Error` (with `code` / `errno` / `syscall` / `path`) that the
+synchronous form throws.
+
+`fs.promises` is also reachable from the `fs` module
+(`import { promises as fsp } from "fs"`), and both namespaces expose a
+`constants` object.
 
 Promise exports: `readFile`, `writeFile`, `appendFile`, `mkdir`, `readdir`,
 `rm`, `unlink`, `rmdir`, `rename`, `copyFile`, `cp`, `realpath`, `stat`,
@@ -19,7 +25,9 @@ Promise exports: `readFile`, `writeFile`, `appendFile`, `mkdir`, `readdir`,
 
 `open(...)` resolves to a **`FileHandle`** with:
 `read`, `write`, `readFile`, `writeFile`, `appendFile`, `close`, `stat`,
-`truncate`, `chmod`, `chown`, `utimes`, `sync`, `datasync`.
+`truncate`, `chmod`, `chown`, `utimes`, `sync`, `datasync`. Those methods are
+offloaded too; `read(buffer, …)` fills the caller's `Buffer` when the worker
+completes.
 
 ```ts
 import { readFile, writeFile, open } from "fs/promises";
@@ -34,5 +42,8 @@ async function main(): Promise<void> {
 main();
 ```
 
+Work runs on a small fixed pool (four workers) and completions are dispatched in
+submission order per worker; independent operations can overlap. A job never
+blocks another `await`, a timer or a socket callback.
 
 Known deviations are listed in [Unimplemented: `fs/promises`](../../unimplemented/node/fs-promises.md).

package/doc/implemented/node.md

@@ -19,7 +19,7 @@ work on another. Missing or different behaviour is recorded under
 | Module | Page | Notes |
 | --- | --- | --- |
 | `fs` | [fs](./node/fs.md) | synchronous API only |
-| `fs/promises` | [fs/promises](./node/fs-promises.md) | wraps the synchronous API in settled promises |
+| `fs/promises` | [fs/promises](./node/fs-promises.md) | reactor-driven file and `FileHandle` operations on the async I/O pool |
 | `path` | [path](./node/path.md) | `path.<name>(...)` namespace calls |
 | `os` | [os](./node/os.md) | `os.<name>(...)` namespace calls |
 | `process` | [process](./node/process.md) | object: methods and properties |

package/doc/implemented.md

@@ -37,7 +37,7 @@ small file instead of a single monolithic document.
 - [Collections](./implemented/collections.md) — Map, Set, WeakMap, WeakSet, WeakRef, iteration
 - [Typed arrays and binary data](./implemented/typed-arrays.md) — typed arrays, ArrayBuffer, DataView
 - [Async, promises and generators](./implemented/async.md) — async/await, async generators, promises, timers
-- [fetch](./implemented/fetch.md) — blocking HTTP/1.1 client and Headers
+- [fetch](./implemented/fetch.md) — reactor-driven HTTP/1.1 client and Headers
 
 ### Modules and tooling
 

package/doc/unimplemented/deviations.md

@@ -14,7 +14,7 @@ These features **compile and run**, but the result does not fully match ECMAScri
 | Array out-of-bounds / sparse | Out-of-bounds access returns `undefined`; assigning `arr.length` truncates / extends, but sparse holes are not tracked distinctly |
 | 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 | No argument count validation; `fn.length` reports the declared arity but calls are never checked against it |
-| `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` still performs the I/O synchronously before settling; `fetch` is blocking. Async generators suspend at both `await` and `yield`; `for await...of` awaits one step per iteration |
+| `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 |
 | 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(...)` takes the prototype of `this`'s prototype; single-level inheritance is correct, but depth > 1 may be inaccurate |
 | `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/unimplemented/node/async.md

@@ -5,13 +5,16 @@
 Implemented:
 
 - Core event loop `runtime/xt_loop.c` (a `select(2)` reactor); `net` / `dgram` / `http` are all built on it.
-- `Promise`, `async` / `await` are available (see the core documents); `fs/promises` returns Promises.
+- Async I/O offload `runtime/xt_async_io.c`: blocking file and HTTP-client work runs on four worker threads and completes on the reactor, so `fs/promises` and `fetch` do not stall timers or sockets.
+- `Promise`, `async` / `await` are available (see the core documents); `fs/promises` returns Promises that settle from the reactor.
 - Timers are available as globals: `setTimeout` / `clearTimeout` / `setInterval` / `clearInterval` run on the core reactor and keep the process alive until no timer remains.
 - A standalone `EventEmitter` is provided by the `events` module (also a global constructor); streams and sockets additionally carry internal emitter methods (`on` / `addListener` / `once` / `off` / `removeListener` / `emit`).
 
 Still unimplemented:
 
 - Node's `Timeout` object (`setTimeout` returns a numeric id; `setImmediate` and `queueMicrotask` exist as globals).
-- A real asynchronous I/O scheduler: `fs/promises` is essentially an immediate-settle wrapper around synchronous operations and does not yield while waiting for I/O.
+- File watching: `fs.watch` / `fs/promises.watch` return inert objects; there is no inotify/kqueue/ReadDirectoryChangesW backend.
+- `Dir.read` / `Dir.close` invoke their callbacks immediately, and callback-style `fs.readFile` / `fs.writeFile` / … are still unsupported (use `fs/promises` or the `*Sync` forms).
 - On streams and sockets the built-in `once` is equivalent to `on` (no "remove after firing once" semantics); the `events` module's `EventEmitter` does implement real `once`.
-- `net`'s `connect` is blocking; HTTP responses require `Connection: close`, with no keep-alive / chunked transfer / pipelining.
+- `net`'s `connect` is still a blocking `connect(2)` performed before the socket joins the reactor; HTTP responses require `Connection: close`, with no keep-alive / chunked transfer / pipelining. `fetch` has no TLS and buffers the whole body before resolving.
+- The offload pool is fixed at four workers; there is no thread-pool sizing option and no `AbortSignal` cancellation for queued jobs.

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）以及元素句柄表。稳定状态下它们都应保持常量——若