xbintsc 0.5.20 → 0.5.21

package/dist/tests/e2e/gui-inline-svg.test.js

@@ -0,0 +1,160 @@
+/**
+ * End-to-end tests for the `gui` extension — inline `<svg>` elements.
+ *
+ * An inline `<svg>` tree is not an SVG *file*: the document already holds the
+ * nodes, so the engine serializes the subtree back into an SVG document and
+ * rasterises it exactly like `<img src="logo.svg">`. These tests pin the
+ * replaced-element sizing, the display-list entry, the serializer's canonical
+ * SVG names (the HTML parser lowercases `viewBox`/`linearGradient`) and the
+ * fact that a DOM mutation re-serializes the artwork.
+ */
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createGuiHarness, guiAvailable } from "./gui-helpers.js";
+const harness = createGuiHarness();
+describe.skipIf(!guiAvailable)("gui extension — inline svg", () => {
+    beforeAll(() => harness.setup());
+    afterAll(() => harness.cleanup());
+    it("sizes and paints an inline svg as a replaced element", () => {
+        const { stdout, stderr } = harness.compileAndRun("inline-svg", `
+      import { createWindow, run } from "gui";
+
+      const HTML = \`
+      <html><head><style>
+        body { margin: 0; }
+        #scaled { width: 64px; height: 48px; }
+      </style></head><body>
+        <svg id="natural" width="8" height="6" viewBox="0 0 8 6">
+          <rect width="8" height="6" fill="#ff0000"/>
+          <circle cx="4" cy="3" r="2" fill="#0000ff"/>
+        </svg>
+        <svg id="viewbox" viewBox="0 0 20 10">
+          <rect width="20" height="10" fill="#00ff00"/>
+        </svg>
+        <svg id="scaled" width="8" height="6" viewBox="0 0 8 6">
+          <rect width="8" height="6" fill="#ff0000"/>
+        </svg>
+      </body></html>
+      \`;
+
+      const win = createWindow({ title: "inline-svg", width: 400, height: 300 });
+      win.on("ready", () => {
+        const natural = win.getBoundingClientRect("#natural");
+        console.log("natural=" + natural.width + "x" + natural.height);
+        const viewbox = win.getBoundingClientRect("#viewbox");
+        console.log("viewbox=" + viewbox.width + "x" + viewbox.height);
+        const scaled = win.getBoundingClientRect("#scaled");
+        console.log("scaled=" + scaled.width + "x" + scaled.height);
+        console.log("display=" + win.computedStyle("#natural", "display"));
+        console.log("hit=" + win.hitTest(4, 3));
+        console.log("no-rects=" + (win.layoutTree().indexOf("<rect>") < 0));
+        console.log("paint-list-start");
+        console.log(win.paintList());
+        console.log("paint-list-end");
+        const info = win.inlineSvg("#natural");
+        console.log("markup=" + info.markup);
+        console.log("parsed=" + info.width + "x" + info.height + " shapes=" + info.shapes);
+      });
+      win.loadHTML(HTML);
+      run();
+      `);
+        // width/height attributes give the intrinsic size; a bare viewBox is the
+        // fallback; an explicit CSS size wins over both.
+        expect(stdout).toContain("natural=8x6");
+        expect(stdout).toContain("viewbox=20x10");
+        expect(stdout).toContain("scaled=64x48");
+        // The `<svg>` box itself is the hit-test target; its children are vector
+        // art, not HTML boxes, so the walk stays at the svg element.
+        expect(stdout).toContain("hit=svg#natural");
+        expect(stdout).toContain("display=inline-block");
+        // The svg subtree produces no HTML boxes: only the replaced box is laid out.
+        expect(stdout).toContain("no-rects=true");
+        // A source newline between two inline elements is a hard line break in this
+        // engine (like `<br>`), so the three boxes stack in document order.
+        const list = stdout.slice(stdout.indexOf("paint-list-start"), stdout.indexOf("paint-list-end"));
+        expect(list).toContain("image x=0.0 y=0.0 w=8.0 h=6.0 inline-svg=");
+        expect(list).toContain("image x=0.0 y=6.0 w=20.0 h=10.0 inline-svg=");
+        expect(list).toContain("image x=0.0 y=16.0 w=64.0 h=48.0 inline-svg=");
+        // The serialized document restores the case-sensitive SVG names the HTML
+        // parser lowercased, and only the svg subtree is included.
+        const markup = stdout
+            .split("\n")
+            .find((line) => line.startsWith("markup="))
+            .slice("markup=".length);
+        expect(markup.startsWith('<svg xmlns="http://www.w3.org/2000/svg" id="natural" width="8" height="6" viewBox="0 0 8 6">')).toBe(true);
+        expect(markup).toContain('<rect width="8" height="6" fill="#ff0000"></rect>');
+        expect(markup).toContain('<circle cx="4" cy="3" r="2" fill="#0000ff"></circle>');
+        expect(markup).not.toContain("viewbox=");
+        expect(stdout).toContain("parsed=8x6 shapes=2");
+        // Rasterising a parsed document must actually succeed.
+        expect(stderr).not.toContain("could not rasterise inline SVG");
+    });
+    it("parses gradients, re-serializes on mutation and restyles the box", () => {
+        const { stdout, stderr } = harness.compileAndRun("inline-svg-mutate", `
+      import { createWindow, run } from "gui";
+
+      const HTML = \`
+      <html><head><style>
+        body { margin: 0; }
+        #icon { background: #123456; border: 2px solid #00ff00; }
+      </style></head><body>
+        <svg id="icon" width="24" height="24" viewBox="0 0 24 24">
+          <defs>
+            <linearGradient id="grad" gradientUnits="userSpaceOnUse" x1="0" y1="0" x2="24" y2="24">
+              <stop offset="0%" stop-color="#ff0000"/>
+              <stop offset="100%" stop-color="#0000ff"/>
+            </linearGradient>
+          </defs>
+          <rect id="box" width="24" height="24" fill="url(#grad)"/>
+        </svg>
+      </body></html>
+      \`;
+
+      const win = createWindow({ title: "inline-svg-mutate", width: 400, height: 300 });
+      win.on("ready", () => {
+        const first = win.inlineSvg("#icon");
+        console.log("shapes=" + first.shapes);
+        console.log("gradient=" + (first.markup.indexOf("linearGradient") >= 0));
+        console.log("units=" + (first.markup.indexOf('gradientUnits="userSpaceOnUse"') >= 0));
+        console.log("stops=" + first.markup.split("<stop").length);
+
+        const icon = win.document.getElementById("icon");
+        icon.setAttribute("width", "48");
+        const rect = win.document.querySelector("rect");
+        rect.setAttribute("fill", "#00ff00");
+        const grown = win.getBoundingClientRect("#icon");
+        const second = win.inlineSvg("#icon");
+        console.log("grown=" + grown.width + "x" + grown.height);
+        console.log("moved=" + (second.markup.indexOf('fill="#00ff00"') >= 0));
+
+        icon.innerHTML = '<circle cx="12" cy="12" r="10" fill="#ffff00"/>';
+        const third = win.inlineSvg("#icon");
+        console.log("replaced=" + (third.markup.indexOf("<circle") >= 0) + " shapes=" + third.shapes);
+        console.log("paint-list-start");
+        console.log(win.paintList());
+        console.log("paint-list-end");
+      });
+      win.loadHTML(HTML);
+      run();
+      `);
+        expect(stdout).toContain("shapes=1");
+        // The HTML parser lowercases `linearGradient`; the serializer restores it,
+        // or NanoSVG would silently drop the gradient definition.
+        expect(stdout).toContain("gradient=true");
+        expect(stdout).toContain("units=true");
+        // start + two stops = three occurrences of "<stop".
+        expect(stdout).toContain("stops=3");
+        // A presentation-attribute mutation changes the intrinsic size, and a paint
+        // mutation changes the serialized document the renderer rasterises.
+        expect(stdout).toContain("grown=52x28");
+        expect(stdout).toContain("moved=true");
+        // `innerHTML` swaps the artwork for a new subtree.
+        expect(stdout).toContain("replaced=true shapes=1");
+        const list = stdout.slice(stdout.indexOf("paint-list-start"), stdout.indexOf("paint-list-end"));
+        // The svg element is still an ordinary styled box: background + 4 borders.
+        expect(list).toContain("color=#123456ff");
+        expect((list.match(/#00ff00ff/g) ?? []).length).toBe(4);
+        expect(list).toContain("w=48.0 h=24.0 inline-svg=");
+        expect(stderr).not.toContain("could not rasterise inline SVG");
+    });
+});
+//# sourceMappingURL=gui-inline-svg.test.js.map

package/dist/tests/e2e/gui-inline-svg.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gui-inline-svg.test.js","sourceRoot":"","sources":["../../../tests/e2e/gui-inline-svg.test.ts"],"names":[],"mappings":"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"}

package/doc/ai/contributing.md

@@ -110,7 +110,8 @@ diff scratch/ref.ll scratch/gen2.ll
   therefore never allocate per access.
 - The GC is a non-moving mark-sweep collector: new heap objects go through
   `xt_alloc`, and a value must be reachable from an explicit root slot, a
-  registered root provider (the event loop, the microtask queue) or the
+  registered root provider (the event loop, the microtask queue, the async I/O
+  job roots) or the
   conservative C-stack scan while it is live. A value held only in a C local that
   is not on the scanned stack is a bug.
 

package/doc/ai/extensions.md

@@ -36,7 +36,7 @@ resolve to the same implementation.
 | Module | Notes |
 | --- | --- |
 | `fs` | **synchronous API only** (`readFileSync`, `writeFileSync`, …); `fs/promises` is separate |
-| `fs/promises` | promise-based file APIs |
+| `fs/promises` | promise-based file APIs; the blocking I/O runs on the async I/O worker pool and settles on the reactor |
 | `path` | also hooks namespace dispatch, so `path.join(...)` works |
 | `os` | |
 | `process` | `process.cwd()`, `argv`, `env`, …; namespace dispatch too |
@@ -54,8 +54,9 @@ Coverage per module (exact functions and options) is in
 [../unimplemented/node.md](../unimplemented/node.md).
 
 Remember the runtime model before building on `net`/`http`: the event loop runs
-**after** the program body, but `async`/`await` now suspends on pending promises,
-so a promise settled from a socket callback can be awaited. See
+**after** the program body, but `async`/`await` suspends on pending promises, so a
+promise settled from a socket callback, a timer or an offloaded file/HTTP job can
+be awaited. `net.connect` itself is still blocking. See
 [language-support.md](./language-support.md).
 
 ### `gui` — HTML/CSS window

package/doc/ai/language-support.md

@@ -75,7 +75,8 @@ Canonical detail (always current, much longer):
 | `setTimeout` and callbacks | ✅ | timers run on the core event loop; `await new Promise(r => setTimeout(r, ms))` works |
 | `queueMicrotask` / `setImmediate` / `performance.now` | ✅ | microtasks share the promise FIFO queue; `setImmediate` is a zero-delay timer with numeric ids; `performance.now` is monotonic fractional milliseconds |
 | Sockets / servers (`http`, `net`, `dgram`) | ✅ | callbacks run on the event loop and can settle a promise you await (`net` / `http` examples included in the tests) |
-| `fs/promises` | ⚠️ | awaitable, but each call performs its I/O synchronously before settling, so it does not yield while the I/O runs |
+| `fs/promises` | ✅ | file, directory and `FileHandle` operations run on the async I/O worker pool and settle on the reactor, so timers and sockets keep running while they wait |
+| Global `fetch` | ✅ | HTTP/1.1 client whose connect/send/receive runs on the same worker pool; `await fetch(...)` yields and redirects are followed on the reactor. `http://` only (no TLS) and the body is buffered before resolving |
 | Worker threads | 🚫 | workers are child processes |
 | `async` generators | ✅ | suspend at `await` and `yield`; every `.next()` returns a promise; `for await...of` supported |
 

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

@@ -93,7 +93,7 @@ diff scratch/ref.ll scratch/gen2.ll
 - 字符串字面量会被驻留：每个不同字面量只在 `main` 中创建一次，存入 GC 根全局，
   每次使用只做一次 load；属性名因此不再逐次分配。
 - GC 是非移动标记清扫：新堆对象走 `xt_alloc`；值存活期间必须能从显式根槽、已注册的
-  根提供者（事件循环、微任务队列）或 C 栈保守扫描到达。只存在于未被扫描的 C 局部
+  根提供者（事件循环、微任务队列、异步 I/O job 根）或 C 栈保守扫描到达。只存在于未被扫描的 C 局部
   变量里的值就是 bug。
 
 ## 修改运行时

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

@@ -35,7 +35,7 @@ xbintsc run app.ts --ext node
 | 模块 | 说明 |
 | --- | --- |
 | `fs` | **仅同步 API**（`readFileSync`、`writeFileSync` 等）；`fs/promises` 是独立模块 |
-| `fs/promises` | 基于 Promise 的文件 API |
+| `fs/promises` | 基于 Promise 的文件 API；阻塞 I/O 跑在异步 I/O 线程池上并在 reactor 上 settle |
 | `path` | 同时接入命名空间分发，`path.join(...)` 可用 |
 | `os` | |
 | `process` | `process.cwd()`、`argv`、`env` 等；也接入命名空间分发 |
@@ -53,8 +53,9 @@ xbintsc run app.ts --ext node
 [../../zh-CN/unimplemented/node.md](../../zh-CN/unimplemented/node.md)。
 
 在 `net`/`http` 上搭东西之前，先记住运行时模型：事件循环在**程序主体之后**才运行，
-但 `async`/`await` 现在会在 pending Promise 上挂起，因此由套接字回调 settle 的 Promise
-可以被 await。见 [language-support.md](./language-support.md)。
+但 `async`/`await` 会在 pending Promise 上挂起，因此由套接字回调、定时器或 offload 的
+文件/HTTP job settle 的 Promise 都可以 await。`net.connect` 本身仍是阻塞的。见
+[language-support.md](./language-support.md)。
 
 ### `gui` —— HTML/CSS 窗口
 

package/doc/ai/zh-CN/language-support.md

@@ -72,7 +72,8 @@ xbintsc 编译 TypeScript 的一个**实用子集**。本页用来判断你能
 | `setTimeout` 与回调 | ✅ | 定时器运行在核心事件循环上；`await new Promise(r => setTimeout(r, ms))` 可用 |
 | `queueMicrotask` / `setImmediate` / `performance.now` | ✅ | 微任务与 Promise 共用 FIFO 队列；`setImmediate` 是零延迟定时器，返回数字 id；`performance.now` 返回单调递增的毫秒小数 |
 | 套接字/服务端（`http`、`net`、`dgram`） | ✅ | 回调在事件循环上执行，可以 settle 你正在 await 的 Promise（测试含 `net`/`http` 示例） |
-| `fs/promises` | ⚠️ | 可以 await，但每次调用仍先同步完成 I/O 再 settle，I/O 期间不会让出 |
+| `fs/promises` | ✅ | 文件、目录与 `FileHandle` 操作跑在异步 I/O 线程池上，并在 reactor 上 settle，等待期间定时器与套接字继续运行 |
+| 全局 `fetch` | ✅ | HTTP/1.1 客户端，connect/send/receive 跑在同一线程池；`await fetch(...)` 会让出，重定向在 reactor 上处理。仅 `http://`（无 TLS），resolve 前缓冲整个响应体 |
 | worker 线程 | 🚫 | worker 是子进程 |
 | `async` 生成器 | ✅ | 可在 `await` 与 `yield` 处挂起；每次 `.next()` 返回 Promise；支持 `for await...of` |
 

package/doc/gui/api.md

@@ -65,6 +65,7 @@ win.documentTree()                     // serialized DOM (debugging)
 win.layoutTree()                       // serialized layout boxes (debugging)
 win.paintCount()                       // number of shapes in the display list
 win.paintList()                        // serialized display list (debugging)
+win.inlineSvg(selector)                // serialized inline <svg>: { markup, width, height, shapes }
 win.measureText(text, fontSize?, family?)  // shaped advance width in pixels
 win.fontMetrics(fontSize?, family?)    // { ascent, descent, lineHeight, ready }
 win.hitTest(x, y)                      // deepest element descriptor, or ""
@@ -73,6 +74,13 @@ win.advance(ms)                        // step the CSS transition clock (testing
 win.stats()                            // engine/runtime counters (memory debugging)
 ```
 
+`win.inlineSvg(selector)` returns the standalone SVG document the engine builds
+from the first `<svg>` element matching `selector` (`markup`), together with the
+intrinsic size and shape count NanoSVG parses out of it; it is `undefined` when
+nothing matches or the element is not an `<svg>`. It makes the serializer's
+canonical casing (`viewBox`, `linearGradient`, `gradientUnits`, …) testable
+without a GPU — the HTML parser delivers those names lowercased.
+
 `win.stats()` returns `{ heapBytes, heapAllocations, treeNodes, detachedRoots,`
 `detachedNodes, handles, handleSlots, listeners }`: the live runtime heap, the
 size of the DOM tree, the detached-node pool, and the element-handle tables. In a

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
 
@@ -355,4 +369,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.