xbintsc 0.5.36 → 0.5.38

package/doc/gui/webgl.md

@@ -23,8 +23,11 @@ display.
 Both **WebGL 1.0** and **WebGL 2.0** are available. A canvas keeps the first
 context kind it asks for: after `getContext("webgl2")` a later
 `getContext("webgl")` answers `null`, and the other way round. A WebGL 2 context
-also satisfies `instanceof WebGLRenderingContext` (its prototype inherits the
-WebGL 1 one) and adds the WebGL 2 constants and methods.
+has its own `WebGL2RenderingContext` prototype (with a copy of the WebGL 1
+constants and methods), so `gl instanceof WebGL2RenderingContext` is true while
+`gl instanceof WebGLRenderingContext` is false, like a browser — libraries such
+as three.js use exactly that check to pick their WebGL 2 path. `gl.constructor.name`
+reports the type as well.
 
 ## How a frame reaches the screen
 
@@ -54,8 +57,9 @@ format, so the engine ships two statically linked translators:
 
 - **glslang** compiles the rewritten GLSL to SPIR-V, which the Vulkan backend
   consumes directly;
-- **SPIRV-Cross** cross-compiles that same SPIR-V to Metal Shading Language text,
-  which the Metal backend compiles at run time.
+- **SPIRV-Cross** cross-compiles that same SPIR-V to Metal Shading Language 2.0
+  text (needed for arrays of textures/samplers), which the Metal backend
+  compiles at run time.
 
 Both live in `gui.a` / `gui.lib`; the Metal path reuses the SPIR-V module rather
 than growing a second GLSL front end, so both backends accept exactly the same
@@ -96,9 +100,13 @@ reflected offsets; `uniform1i` on a sampler stores the texture unit. The block
 is pushed with the dynamic uniform-buffer API on every draw.
 
 Limits of the translator: struct-typed uniforms, user uniform blocks, uniform
-arrays whose size is not resolved by the preprocessor, sampler arrays are rejected (the link/shader info log says so). Shader code inside
-`#ifdef` is fine; non-sampler uniform declarations are moved to the enclosing
-top-level position so the block stays unconditional.
+arrays whose size is not resolved by the preprocessor, and a sampler array
+indexed by a non-constant expression are rejected (the link/shader info log
+says so). A `#pragma unroll_loop_start` loop is expanded before rewriting, so
+the `sampler2D shadowMap[ NUM_DIR_LIGHT_SHADOWS ]` / `shadowMap[ i ]` shape
+three.js emits becomes constant-indexed. Shader code inside `#ifdef` is fine;
+non-sampler uniform declarations are moved to the enclosing top-level position
+so the block stays unconditional.
 
 ### GLSL ES 3.00 (WebGL 2)
 
@@ -299,9 +307,11 @@ same assertions as the SPIR-V one.
 
 ## three.js
 
-The `.js` asset loader only patches three.js's shader unroller; `WebGLRenderer`
-runs unchanged on this engine's real WebGL 2 backend, so **no Canvas2D fallback
-is bundled any more**. Verified with three.js r160 through SDL_GPU:
+The shader rewriter expands three.js's `#pragma unroll_loop_start` loops into
+constant indices (its sampler arrays would otherwise fail Vulkan GLSL), and the
+`.js` asset loader keeps the renderer's own unroller out of the way.
+`WebGLRenderer` runs unchanged on this engine's real WebGL 2 backend, so **no
+Canvas2D fallback is bundled any more**. Verified with three.js r160 through SDL_GPU:
 `MeshBasicMaterial`, `MeshStandardMaterial` and `MeshPhongMaterial`,
 `CanvasTexture`, linear fog, ambient/directional/point/spot/hemisphere lights,
 `Sprite`, `Line`, `Points` and `InstancedMesh`.

package/doc/gui-scripts.md

@@ -155,17 +155,18 @@ export default __html;
 ### 2b. External `<script src>`
 
 `<script src="./app.ts">` is read relative to the HTML file, parsed, and split:
-its top-level `import`/`export … from` statements are **hoisted** to the
-generated module (with relative specifiers rewritten so they resolve from the
-HTML file's directory), and the remaining statements are wrapped in the script
-function. This is how an external script still runs at `loadHTML` time while
-being able to `import` other modules.
-
-Two limitations are enforced with clear errors rather than silent breakage:
-
-- a missing `src` file throws (turned into a bundler diagnostic), and
-- two `src` scripts that import the same local binding name collide; the user
-  must alias one of them. (Non-conflicting or identical imports are fine.)
+its top-level `import`/`export … from` statements are removed from the body, and
+the remaining statements are wrapped in the script function. Relative imports
+are **deferred**, like a browser module script: the loader emits a synthetic
+`__xt_deferred_module` marker and the generated script calls the module wrapper
+at `loadHTML` time. The bundler wraps the whole local import graph in functions
+that return their exports (memoised by `__xt_defer`), so top-level module code
+runs after the document exists and two scripts importing the same module share
+one instance. Bare specifiers (`gui`, a package) stay eager.
+
+A missing `src` file is still a clear error (turned into a bundler diagnostic),
+and `src` URLs (`https://…`, `data:…`, `//host`) are left untouched — they are
+not compile-time assets and never run.
 
 `src` URLs (`https://…`, `data:…`, `//host`) are left untouched — they are not
 compile-time assets and never run.
@@ -302,11 +303,11 @@ legacy `target` field over the handle.
   - **M9b** ✅ — gui `.html` loader (`src/extensions/gui/html.ts`), the
     `__registerScript` builtin, the script registry (`runtime/ext_gui/script.cpp`),
     `loadHTML` execution and `DOMContentLoaded`/`load`; e2e coverage.
-  - **M9c** ✅ — `<script src>` files are read, their top-level imports are
-    hoisted (specifiers rewritten to resolve from the HTML file) and their body
-    is wrapped and registered; missing files and import-binding collisions
-    surface as diagnostics. All scripts run in document order (effectively
-    deferred). e2e coverage.
+  - **M9c** ✅ — `<script src>` files are read and their body is wrapped and
+    registered; relative imports are deferred and evaluated by a memoised
+    module wrapper at `loadHTML` time, so the import graph sees a parsed
+    document and shares one instance per module. Missing files surface as
+    diagnostics. All scripts run in document order. e2e coverage.
   - **M9d** *(optional)* — detect inline HTML in template literals passed to
     `win.loadHTML(...)` and transform them too (fragile; deferred).
 - **M10 — polish** ✅ — `requestAnimationFrame`/`cancelAnimationFrame` on the
@@ -330,9 +331,8 @@ legacy `target` field over the handle.
   network fetches) do not run. Documented.
 - **Template-literal HTML** passed to `win.loadHTML(…)` is not transformed in
   M9b (only imported assets are). M9d addresses this if needed.
-- **Import-binding collisions** between external `<script src>` files. Detected
-  and reported (alias the import); a per-script rename with reference rewriting
-  is possible later.
+- **Top-level `await`** inside a deferred `<script src>` module is not
+  supported: the module body is wrapped in a synchronous init function.
 - **Assets.** `<script src>` is resolved relative to the HTML asset; URL `src`
   values are ignored. There is no fetch/network loading.
 

package/doc/gui.md

@@ -219,10 +219,11 @@ engine were Rust.
      registered through the `__registerScript` builtin and replaced by
      `<script data-xt-id="<hash>">` markers; `win.loadHTML` runs the matching
      functions after parsing and fires `DOMContentLoaded` then `load`.
-   - **M9c** ✅ — `<script src>` files are read relative to the HTML, their
-     top-level imports are hoisted (specifiers rewritten from the HTML dir) and
-     their body is wrapped/registered; missing files and import-binding
-     collisions become diagnostics. Everything runs in document order.
+   - **M9c** ✅ — `<script src>` files are read relative to the HTML and their
+     body is wrapped/registered; relative imports are deferred to `loadHTML`
+     through a memoised module wrapper, so imported modules see the parsed
+     document and share state. Missing files become diagnostics. Everything
+     runs in document order.
 10. **M10 — polish** ✅
     - `win.requestAnimationFrame(fn)` / `win.cancelAnimationFrame(id)`; callbacks
       run at the top of each frame with the frame timestamp and may mutate the
@@ -387,10 +388,11 @@ engine were Rust.
   bodies into AOT functions registered at startup and run by `win.loadHTML`
   (before first layout; `DOMContentLoaded` then `load`). Unit tests in
   `tests/extensions/gui.test.ts`, e2e in `tests/e2e/gui-*.test.ts`.
-- **M9c** ✅ external `<script src>` files are read, their imports hoisted
-  (specifiers rewritten from the HTML dir) and their body wrapped/registered;
-  missing files and import-binding collisions are diagnostics. Loader errors are
-  caught by `loadGraph` and reported as build errors.
+- **M9c** ✅ external `<script src>` files are read and their body
+  wrapped/registered; relative imports are deferred to `loadHTML` through a
+  memoised module wrapper (so module-level DOM work sees the parsed document),
+  while missing files are diagnostics. Loader errors are caught by `loadGraph`
+  and reported as build errors.
 - **M10** ✅ `requestAnimationFrame`/`cancelAnimationFrame` on window handles
   (callbacks run with the frame timestamp before layout each frame) plus
   `offsetWidth`/`offsetHeight`/`contains` on element handles; e2e coverage in

package/doc/implemented/fetch.md

@@ -13,6 +13,11 @@ Location: `runtime/xt_fetch.c`, `runtime/xt_fetch/async.inc`, `runtime/xt_async_
   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.
+- A reference with **no scheme** (a relative path) and `file://` URLs read a
+  local file, so a compiled program can load an asset from disk without an HTTP
+  server. Relative paths resolve against the working directory; `GET` / `HEAD`
+  are supported. On Windows the standard `file:///C:/dir/file` spelling and
+  `file://C:/dir/file` / `file://C:\dir\file` all name the same file.
 - Options: `method`, `headers` (plain object or `Headers`), `body` and `redirect`
   (`follow` / `manual` / `error`).
 - The resolved `Response`-shaped object exposes `ok` / `status` / `statusText` /

package/doc/implemented/modules.md

@@ -19,6 +19,19 @@ Location: `src/parser/parser.ts` (syntax), `src/driver/modules.ts` (bundling),
 - Imported bindings and namespace members are snapshots at module-evaluation time (no live bindings) — see [Unimplemented: module system](../unimplemented/modules.md).
 - Type-only imports and re-exports (`import type { T } from "..."`, `import { type T } from "..."`, `export type { T } from "..."`) are erased. They are **not** module edges: the target is not loaded or bundled, and a type-only cycle between modules is not a circular dependency. Use a side-effect import (`import "./mod"`) when a module must be evaluated without binding a name.
 
+## Deferred evaluation
+
+- The `gui` `.html` asset loader marks relative `<script src>` imports with a
+  synthetic `__xt_deferred_module` binding. The bundler then wraps that module
+  and its local import graph in functions that return their exports, and the
+  generated script calls them after `loadHTML` (`__xt_defer` memoises each
+  module). This matches a browser module script, where the graph is evaluated
+  once the document exists.
+- Modules also reachable through a normal (non-marker) import stay eager and get
+  a thin wrapper over their already-initialised exports.
+- The wrapper body is synchronous: top-level `await` inside a deferred script
+  module is not supported.
+
 ## import.meta
 
 - `import.meta.url` / `.dirname` / `.filename`, resolved from the running executable's path.

package/doc/implemented/stdlib.md

@@ -55,6 +55,23 @@ own pages: [Collections](./collections.md), [Typed arrays and binary data](./typ
 - `Symbol(description)` primitives (`XT_OBJECT_KIND_SYMBOL`), the 13 well-known symbols (`Symbol.iterator`, `Symbol.asyncIterator`, `Symbol.match`, ...), `Symbol.for` / `Symbol.keyFor` global registry, `symbol.description` / `toString()` / `valueOf()`.
 - Symbols are valid property keys (`Object.getOwnPropertySymbols`, symbol keyed `get`/`set`/`in`/`delete`), are skipped by `Object.keys` / `values` / `entries` / `for...in` / `JSON.stringify`, and print as `Symbol(desc)`.
 
+## URL
+
+- `URL` is implemented in `runtime/xt_url_object.c`: `new URL(input)` and
+  `new URL(input, base)` (the base may be another `URL`), resolving relative
+  references against a hierarchical `scheme://authority/path` base.
+- A reference with **no scheme is a filesystem path**: `new URL("./model.glb")`
+  resolves against the working directory and yields a `file:` URL (an explicit
+  base is still honoured, so `new URL("./x", import.meta.url)` works too).
+- Read-only `href`, `protocol`, `origin`, `host`, `hostname`, `port`,
+  `pathname`, `search`, `hash`, `searchParams` and `toString()` / `toJSON()`;
+  absolute inputs are kept as written, except that the Windows spellings of a
+  `file:` URL (`file://C:/dir` and `file://C:\dir`) are canonicalized to
+  `file:///C:/dir`, matching Node.
+- Not a full WHATWG parser: path percent-encoding, IDNA, setters and live
+  `searchParams` synchronisation are not implemented — see
+  [Runtime deviations](../unimplemented/deviations.md).
+
 ## URLSearchParams
 
 - `URLSearchParams` is implemented in `runtime/xt_url.c`.

package/doc/unimplemented/deviations.md

@@ -8,6 +8,7 @@ These features **compile and run**, but the result does not fully match ECMAScri
 | --- | --- |
 | RegExp byte-oriented matching | The engine matches UTF-8 bytes: literal multi-byte text works, but `.` and character classes consume one byte per repetition (`\d` / `\w` stay ASCII). Offsets returned by `exec` / `search` / replacement callbacks are converted to UTF-16 code units |
 | Global RegExp `lastIndex` | `test` / `exec` do not advance or honour a caller-set `lastIndex` for `/g` / `/y` regexes |
+| `URL` parser | Read-only WHATWG subset: no path percent-encoding, IDNA, setters or live `searchParams`; a reference with no scheme resolves against the working directory as a `file:` URL |
 | String `normalize` | Not implemented |
 | First-class built-in methods | Implemented as unbound method values (see [Functions](./functions.md)); `fn.toString()` returns a placeholder rather than source text |
 | `for...in` | Enumerates own keys of objects / arrays / strings; does not include prototype-chain properties |

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

@@ -22,10 +22,38 @@ run();                                 // 驱动主循环，直到所有窗口
 `getHTML` / `setBackground` / `close` / `isOpen` / `on` / `off`，以及
 `driver()`——它报告当前使用的 SDL_GPU 后端（`"vulkan"`、`"direct3d12"`、
 `"metal"` 等，由 SDL 挑选设备支持的最佳后端）。同时也提供 Web 写法：
-`addEventListener` / `removeEventListener` 是 `on` / `off` 的别名（其
-`options` 参数会被接受并忽略），`closed` getter 对应 `isOpen()`，因此按浏览器
+`addEventListener` / `removeEventListener` 接受标准的选项对象（`capture`、
+`once`、`passive`、`signal`），`closed` getter 对应 `isOpen()`，因此按浏览器
 API 编写的文档可以原样运行。
 
+元素监听器支持同一组选项：`{ once }` 在首次调用后移除监听器，`{ passive: true }`
+使 `preventDefault()` 变成无操作，`{ signal }`（来自 `new AbortController()` 的
+`AbortSignal`）在 abort 时移除监听器，包括添加时就已经 abort 的信号。
+`element.dispatchEvent(event)` 派发的就是**同一个**事件对象（身份可观察），并填充
+`target` / `currentTarget` / `eventPhase`、记录路径供 `event.composedPath()` 使用。
+`new Event(...)`、`new CustomEvent(...)`、`new MouseEvent(...)`、
+`new KeyboardEvent(...)`、`new PointerEvent(...)`、`new WheelEvent(...)`、
+`new FocusEvent(...)`、`new InputEvent(...)` 与 `new SubmitEvent(...)` 会保留 `init`
+对象的全部字段（`detail`、`composed`、鼠标/键盘成员等）。窗口监听器接受同一组
+选项（`capture` 参与监听器身份匹配；窗口投递没有捕获阶段）。
+
+窗口导航是真实实现的：`scrollTo(x, y)` / `scrollTo({ left, top })` /
+`scrollBy(...)` 移动页面视口（会按内容边界夹取，绘制与命中测试随之偏移），
+`scrollX` / `scrollY` / `pageXOffset` / `pageYOffset` 报告偏移量。`focus()`
+提升操作系统窗口并置位 `document.hasFocus()`，`blur()` 清除它。事件：
+`ready`（首帧呈现后）、`load`、`close`、`resize`、`scroll`、`focus`、`blur`，
+以及输入事件 `mousemove`、`mousedown`、`mouseup`、`click`、`wheel`、
+`keydown`、`keyup`。
+
+`createWindow(options)` 除标题与尺寸外还支持：`{ title, width, height,
+highDensity, resizable, borderless, alwaysOnTop, hidden, fullscreen, x, y,
+opacity, maximized, minimized }`，它们会映射到对应的 SDL 窗口标志/调用，而不是
+被忽略。
+
+`window.confirm(message)` / `window.prompt(message, defaultValue)` 不会再丢弃
+参数：设置 `XT_GUI_DIALOGS=1` 且存在窗口时显示原生消息框；否则把消息写到 stderr
+并返回文档化的默认值（`confirm` → `false`，`prompt` → `defaultValue` 或 `""`）。
+
 在 Windows 上，GUI 程序会被链接为 **Windows 子系统**可执行文件，因此启动时不会闪出控制台
 窗口；这也意味着从资源管理器启动时 stdout/stderr 无处可去，调试时可在
 `xbintsc.config.json` 里设置 `app.console: true` 保留控制台子系统。
@@ -60,12 +88,13 @@ requestAnimationFrame(frame);
 | `navigator` | `userAgent`（以 `xbintsc` 结尾的桌面 Chrome 字符串）、`platform`、`vendor`、`language(s)`、`hardwareConcurrency`、`maxTouchPoints`、`onLine`、`vibrate()` |
 | `localStorage` | 内存中的 `getItem` / `setItem` / `removeItem` / `clear` / `key` / `length` |
 | `AudioContext`、`webkitAudioContext` | 带真实混音器与解码器的 Web Audio 图（见下） |
-| `Event`、`CustomEvent`、`ProgressEvent` 等 | 事件构造器 |
+| `Event`、`CustomEvent`、`ProgressEvent`、`MouseEvent`、`KeyboardEvent`、`PointerEvent`、`WheelEvent`、`FocusEvent`、`InputEvent`、`SubmitEvent` | 事件构造器；`init` 参数按原样保留（`detail`、`composed`、鼠标/键盘字段等） |
+| `AbortController`、`AbortSignal` | 真实的 controller/signal 对，用于 `{ signal }` 移除监听器，支持 `abort()`、`aborted`、`reason`、`onabort` 与 `throwIfAborted()` |
 | `HTMLCanvasElement`、`HTMLImageElement`、`WebGLRenderingContext`、`WebGL2RenderingContext`、`WebGLBuffer`/`WebGLTexture`/`WebGLShader`/`WebGLProgram`/`WebGLFramebuffer`/`WebGLRenderbuffer`/`WebGLUniformLocation`/`WebGLActiveInfo`/`WebGLVertexArrayObject`/`WebGLSampler`/`WebGLQuery`/`WebGLSync`/`WebGLTransformFeedback` | 真实的构造函数值。`canvas.getContext("webgl")` 与 `getContext("webgl2")` 返回 GPU 上下文（见 [WebGL](./webgl.md)）。 |
 | `ImageBitmap`、`createImageBitmap(source)` | 由已解码像素支撑的不可变位图（`<img>`、`<canvas>`、`<video>` 帧与 `ImageData` 形状）；promise 立即 settle，`texImage2D` 可直接接受该对象 |
 | `ImageData`、`OffscreenCanvas`、`XRWebGL*`、`Request`、`Headers`、`Response`、`ReadableStream`、`DOMParser` | `typeof` 探测返回 `"undefined"`（没有 XR/fetch/流式后端），让页面走自己的“不支持”分支，而不是调用空壳。Three.js 页面在本后端上使用真实渲染器（见[已知问题](./known-issues.md)）。 |
 | `requestAnimationFrame` / `cancelAnimationFrame` | 排入窗口的动画帧列表，见[运行时集成](./runtime.md) |
-| `alert` / `confirm` / `prompt`、`matchMedia`、`getComputedStyle`、`escape` | 宿主实现（Annex B `escape` 按 UTF-16 码元编码，与 `decodeURIComponent(escape(bytes))` 一致） |
+| `alert` / `confirm` / `prompt`、`matchMedia`、`getComputedStyle`、`escape` | 宿主实现。`matchMedia` 返回**实时**列表（按查询缓存）：`matches` 在窗口尺寸变化时重新求值，翻转时触发 `change` 监听器。`confirm`/`prompt` 仅在 `XT_GUI_DIALOGS=1` 时使用原生对话框，否则把消息写到 stderr 并返回文档化的默认值（Annex B `escape` 按 UTF-16 码元编码，与 `decodeURIComponent(escape(bytes))` 一致） |
 
 `getElementById` / `querySelector` 在 `loadHTML` 之前也能回答：此时得到的是**挂起**句柄，
 首次使用时才绑定到真实节点，因此在模块初始化阶段缓存 `document.querySelector("#id")`

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

@@ -31,12 +31,19 @@ const ctx = canvas.getContext("2d"); // 或 "webgl" 取得 GPU 上下文
 元素上，因此每次都返回**同一个**对象，绘制状态（变换、样式、路径）按 canvas 而非按调用
 保存。`ctx.canvas` 是所属元素的句柄。
 
+`getContext("2d", attributes)` 在首次调用时会尊重 `alpha`：传入 `{ alpha: false }`
+时位图以不透明黑色初始化（清除也回到不透明黑）。其余属性由
+`getContextAttributes()` 按规范默认值报告（`antialias: true`、`depth: true`、
+`stencil: false`、`premultipliedAlpha: true`、`preserveDrawingBuffer: false`、
+`colorSpace: "srgb"` 等），特性探测因此能得到诚实的答案。
+
 ## 绘制模型
 
 光栅器刻意保持精简且为自研（不依赖 Skia/Cairo）。它按每条像素行 **4 条垂直子扫描线**
-进行抗锯齿，并做一次**水平解析覆盖率**计算；路径采用**非零环绕规则**填充（因此当弧线
-以相反方向环绕时能形成空洞）。轴对齐矩形（变换中 `b == 0 && c == 0`）走直接的覆盖率
-快速路径。混合为非预乘 source-over，并按 `globalAlpha` 缩放。
+进行抗锯齿，并做一次**水平解析覆盖率**计算；路径默认采用**非零环绕规则**填充（因此当弧线
+以相反方向环绕时能形成空洞），`fill("evenodd")` 则改用奇偶规则。轴对齐矩形（变换中
+`b == 0 && c == 0`）走直接的覆盖率快速路径。混合为非预乘 source-over，并按
+`globalAlpha` 缩放。
 
 填充或描边可以使用纯色，也可以使用 **`CanvasGradient`**。渐变的坐标属于用户空间，
 因此光栅器会先用当前变换的逆矩阵把每个设备像素映射回用户空间再采样——形状被平移、
@@ -50,9 +57,11 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 ## 支持的 API
 
 状态与变换：`save` / `restore`（会恢复变换、线宽、透明度、字体/文本设置**以及**
-填充/描边样式）、`translate`、`rotate`、`scale`、`transform(a,b,c,d,e,f)`、
-`setTransform`、`resetTransform`、`getTransform`（返回带 `a`…`f` 与 `is2D` 的对象）。
-变换按 canvas 的顺序组合：`translate(x, y); rotate(a)` 围绕平移后的原点旋转。
+填充/描边样式）、`translate`、`rotate`、`scale`、`transform(a,b,c,d,e,f)` /
+`transform(matrix)`、`setTransform(a,b,c,d,e,f)` / `setTransform(matrix)`、
+`resetTransform`、`getTransform`（返回带 `a`…`f` 与 `is2D` 的对象）。矩阵可以是
+`{ a, b, c, d, e, f }` 对象或六元素数组。变换按 canvas 的顺序组合：
+`translate(x, y); rotate(a)` 围绕平移后的原点旋转。
 
 样式与设置：`fillStyle` / `strokeStyle`（层叠所用的颜色解析器能识别的 CSS 颜色，或
 `CanvasGradient`）、`lineWidth`、`globalAlpha`、`lineCap`（`butt`/`round`/`square`）、
@@ -70,20 +79,27 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 会忽略 `x0`/`y0`——请使用同心圆（`x0 == x1`、`y0 == y1`）。
 
 路径：`beginPath`、`closePath`、`moveTo`、`lineTo`、`rect`、`roundRect`、`arc`、
-`ellipse`、`quadraticCurveTo`、`bezierCurveTo`，然后 `fill`（多环、非零环绕）或
-`stroke`。贝塞尔与二次曲线段会被展平为线段；弧线与椭圆同样被展平。`roundRect` 只接受
-单个圆角半径数字（数组形式尚未实现）。
+`ellipse`、`quadraticCurveTo`、`bezierCurveTo`，然后
+`fill(fillRule?)` / `fill(path, fillRule?)`（多环；`"nonzero"` 或 `"evenodd"`）或
+`stroke(path?)`。贝塞尔与二次曲线段会被展平为线段；弧线与椭圆同样被展平。
+`roundRect` 接受单个半径数字，或 CSS 半径列表（`[all]`、`[tl, br]`、
+`[tl, tr, br]`、`[tl, tr, br, bl]`，元素为数字或 `{ x, y }` 对；圆角按圆弧绘制）。
+
+`Path2D` 支持同一组路径命令（`moveTo`、`lineTo`、`closePath`、`rect`、
+`roundRect`、`arc`、`ellipse`、`quadraticCurveTo`、`bezierCurveTo`、`addPath`），
+并可传给 `fill`/`stroke`，因此一次构建的路径可以在不同变换下重复使用。
 
 矩形：`clearRect`、`fillRect`、`strokeRect`。
 
 虚线：`setLineDash(segments)` / `getLineDash()` / `lineDashOffset` 实现标准规则
 （奇数长度列表会复制一遍，负数/非有限值会被忽略，全零列表表示实线）。
 
-文本：`measureText(text)`（返回 `{ width }`）、`fillText(text, x, y)` 与
-`strokeText(text, x, y)`。文本经 HarfBuzz 排版、FreeType 光栅化（与 HTML 文本相同的
-技术栈），按变换的近似缩放绘制。**仅支持平移与均匀缩放**——旋转或斜切变换仍会把每个
-字形放到其变换后的基线点，但不会旋转字形位图。`strokeText` 目前用描边样式执行填充，
-而非生成轮廓。
+文本：`measureText(text)`（返回 `{ width }`）、`fillText(text, x, y, maxWidth?)` 与
+`strokeText(text, x, y, maxWidth?)`。文本经 HarfBuzz 排版、FreeType 光栅化（与 HTML
+文本相同的技术栈），按变换的近似缩放绘制。正的 `maxWidth` 会按比例压缩步进与字形位图，
+使文本宽度不超过该值（与 canvas API 一致），而不是忽略该参数。**仅支持平移与均匀
+缩放**——旋转或斜切变换仍会把每个字形放到其变换后的基线点，但不会旋转字形位图。
+`strokeText` 目前用描边样式执行填充，而非生成轮廓。
 
 图像：`drawImage(source, …)` 支持 3 参数（`dx, dy`）、5 参数（`dx, dy, dw, dh`）与
 9 参数（本引擎为**目标优先**：`dx, dy, dw, dh, sx, sy, sw, sh`）。完整的仿射变换
@@ -95,12 +111,21 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 测试钩子：`getImageData(x, y, w, h)` 把区域复制为 `{ width, height, data }`，其中
 `data` 是按行主序的 RGBA8 字节数组。越界像素为透明。
 
+图案：`createPattern(source, repetition?)` 接受 `<img>` 或另一个 `<canvas>`，在用户
+空间中平铺（`repeat`、`repeat-x`、`repeat-y`、`no-repeat`），因此平铺会跟随当前
+变换。把结果赋给 `fillStyle`/`strokeStyle`；重新赋颜色会替换掉图案。
+
+图像数据与导出：`createImageData(width, height)` 分配一个空的
+`{ width, height, data }`，`putImageData(imageData, dx, dy[, dirtyX, dirtyY,
+dirtyWidth, dirtyHeight])` 直接把字节写入位图（不受变换、混合或 `globalAlpha`
+影响）。`canvas.toDataURL(type?)` 导出 PNG data URL，`canvas.toBlob(callback,
+type?)` 从微任务中交付 Blob 形状的 `{ type, size }`（字节在
+`__xt_gui_blob_data` 上；本运行时没有 `URL.createObjectURL`）。
+
 ## 尚未实现
 
-图案（`createPattern`）、阴影、`clip()`、`globalCompositeOperation`、
-`putImageData`、`createImageData`、`isPointInPath`、以 `DOMMatrix` 调用的
-`setTransform`、可切换图像平滑的 `drawImage`、`toDataURL`/`toBlob`、把 `<canvas>` 用作
-CSS `background-image`，以及离屏画布（`OffscreenCanvas`、
-`transferControlToOffscreen`）。`roundRect` 只接受单个半径，径向渐变会忽略内圆偏移。
+阴影、`clip()`、`globalCompositeOperation`、`isPointInPath`、可切换图像平滑的
+`drawImage`、把 `<canvas>` 用作 CSS `background-image`，以及离屏画布
+（`OffscreenCanvas`、`transferControlToOffscreen`）。径向渐变会忽略内圆偏移。
 
 另见[媒体](./media.md)：`drawImage` 与纹理上传所共享的图像/视频/音频解码栈。

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

@@ -68,17 +68,59 @@ created.textContent = "added";
 box.appendChild(created);
 box.removeChild(created);
 
+// 父子变更辅助方法可在同一次调用中混用节点与字符串。
+box.append("text", doc.createElement("span"));
+box.prepend(doc.createElement("b"));
+box.insertAdjacentHTML("beforeend", "<i>tail</i>"); // beforebegin/afterbegin/beforeend/afterend
+box.replaceChildren("fresh", doc.createElement("em"));
+
+// 命名空间会被记录；外部（SVG）元素名保留大小写。
+const gradient = doc.createElementNS("http://www.w3.org/2000/svg", "svg:linearGradient");
+console.log(gradient.namespaceURI, gradient.localName, gradient.prefix);
+
 inner.addEventListener("click", (e) => console.log(e.target.id, e.currentTarget.id));
 inner.click();                          // 在该元素处合成一次点击
 console.log(box.offsetWidth, box.offsetHeight);   // 取整后的边框盒
 console.log(box.contains(inner));                 // 后代判断
 ```
 
+### style 属性、dataset、计算样式与几何
+
+内联 `style` 对象是一个 CSSOM 声明块。以属性名赋值/读取的是与 `setProperty`
+相同的声明块（`el.style.display = "none"`、`el.style.backgroundColor = "#f00"`，
+驼峰名会映射到 CSS 拼写，`el.style["--accent"]` 用于自定义属性）；
+`setProperty(name, value, priority)` 在 `priority` 为 `"important"` 时以
+`!important` 保存该声明（其他优先级值会让本次调用成为无操作，空值则移除该属性）。
+`getPropertyValue` / `getPropertyPriority` 读回声明，`removeProperty` 返回旧值，
+`cssText` 读取或整体替换声明块，`style.length` / `style.item(i)` 枚举声明块，
+未设置的属性返回 `""`。
+
+`el.dataset` 是元素 `data-*` 属性之上的实时 `DOMStringMap`：
+`dataset.fooBar` 读取 `data-foo-bar`，赋值写入属性，`delete` 移除属性，
+`Object.keys(dataset)` / `for...in` 只列出 data 键。
+
+`getComputedStyle(el, pseudoElt)` 从**层叠结果**读取——UA 样式表、作者规则、
+继承和内联声明——而不是回显内联块，因此写在样式表里的规则同样可见。它支持
+`getPropertyValue`、`getPropertyPriority` 与命名属性（`cs.width`、
+`cs.backgroundColor`、`cs["--accent"]`）。传入 `"::before"` 或 `"::after"`
+可读取生成内容盒；其他伪元素返回空值。每次读取都会先结算待处理的重新样式，
+因此早先创建的句柄在后续变更后仍然有效。
+
+`getBoundingClientRect()` 在 `x` / `y` / `width` / `height` 之外还带有旧式的
+`top` / `right` / `bottom` / `left` 成员；`document.title = …` 写入文档的
+`<title>`（页面没有该元素时会创建它以及 `<head>`）。
+
 变更操作会把文档标记为脏；引擎会延迟地（在下一次读取或下一帧之前）重新计算
 样式并重新布局。`inner = …`/`innerHTML = …` **不会**执行脚本。元素事件支持
-捕获与冒泡阶段、`stopPropagation`、`once`，并向上冒泡到 `document`/`window`。
-旧式 `win.on(type, fn)` 负载保留其**字符串** `e.target`（`div#id.class`）；
-元素 `Event.target` 是一个句柄，其描述符与同一字符串匹配。
+捕获与冒泡阶段、`stopPropagation`、`once`、`passive` 与 `signal`（`AbortController`
+的信号会在 abort 时移除监听器），并向上冒泡到 `document`/`window`。
+`dispatchEvent` 派发同一个事件对象，并填充 `target`/`currentTarget`/`eventPhase`/
+`composedPath()`。旧式 `win.on(type, fn)` 负载保留其**字符串** `e.target`
+（`div#id.class`）；元素 `Event.target` 是一个句柄，其描述符与同一字符串匹配。
+
+`element.focus()` 会把元素滚动到可见区域（传入 `{ preventScroll: true }` 则保持
+当前页面偏移）；`document.hasFocus()` 报告由 `window.focus()` / `window.blur()`
+切换的窗口焦点状态。
 
 ### 节点生命周期
 

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

@@ -16,7 +16,7 @@ if (gl == null) {
 
 2D 上下文把图形光栅化到 CPU 位图再上传为纹理；WebGL 上下文则**在 GPU 上渲染**：顶点变换、光照、纹理采样、深度测试与混合全部在 SDL_GPU 管线中执行（Windows/Linux 上是 Vulkan，macOS 上是 Metal）。页面直接合成该上下文的颜色纹理，因此显示时不需要把像素读回 CPU。
 
-同时提供 **WebGL 1.0** 与 **WebGL 2.0**。一个 canvas 会固定为它第一次申请的上下文类型：先调用 `getContext("webgl2")` 之后，`getContext("webgl")` 返回 `null`，反之亦然。WebGL 2 上下文也满足 `instanceof WebGLRenderingContext`（其原型继承 WebGL 1 原型），并在其上增加 WebGL 2 的常量与方法。
+同时提供 **WebGL 1.0** 与 **WebGL 2.0**。一个 canvas 会固定为它第一次申请的上下文类型：先调用 `getContext("webgl2")` 之后，`getContext("webgl")` 返回 `null`，反之亦然。WebGL 2 上下文拥有自己的 `WebGL2RenderingContext` 原型（其中复制了 WebGL 1 的常量与方法），因此 `gl instanceof WebGL2RenderingContext` 为真，而 `gl instanceof WebGLRenderingContext` 为假，与浏览器一致——three.js 等库正是据此选择 WebGL 2 路径。`gl.constructor.name` 也会报告对应类型名。
 
 ## 一帧如何到达屏幕
 
@@ -53,7 +53,7 @@ SDL_GPU 不能在运行时编译 GLSL，且每个后端只消费自己的格式
 | `gl_FragData[0]` | `xt_FragColor` |
 | 缺少 `#version` / `#version 100` | `#version 310 es` |
 
-两个阶段的非采样器 uniform 会合并成同一个块，并在每个阶段各声明一次（顶点 set 1、片元 set 3），与 SDL_GPU 的 Vulkan 描述符布局一致。在 Metal 上同一批声明会变成 `[[buffer(0)]]` 与 `[[texture(N)]]`/`[[sampler(N)]]`，正是 SDL_GPU Metal 后端绑定的槽位。`uniformMatrix4fv` 按列主序写入反射出的偏移；对采样器调用 `uniform1i` 时记录纹理单元。每次绘制都用动态 uniform 缓冲接口推送该块。
+实现限制：结构体 uniform、用户 uniform 块、预处理阶段无法确定长度的 uniform 数组，以及用非常量表达式索引的采样器数组会被拒绝（shader/link info log 会说明）。`#pragma unroll_loop_start` 循环会在改写前展开，因此 three.js 生成的 `sampler2D shadowMap[ NUM_DIR_LIGHT_SHADOWS ]` / `shadowMap[ i ]` 会变成常量索引。`#ifdef` 内的着色器代码可用；非采样器 uniform 声明会被移动到顶层，保证块保持无条件。两个阶段的非采样器 uniform 会合并成同一个块，并在每个阶段各声明一次（顶点 set 1、片元 set 3），与 SDL_GPU 的 Vulkan 描述符布局一致。在 Metal 上同一批声明会变成 `[[buffer(0)]]` 与 `[[texture(N)]]`/`[[sampler(N)]]`，正是 SDL_GPU Metal 后端绑定的槽位。`uniformMatrix4fv` 按列主序写入反射出的偏移；对采样器调用 `uniform1i` 时记录纹理单元。每次绘制都用动态 uniform 缓冲接口推送该块。
 
 翻译器的限制：结构体 uniform、用户 uniform 块、预处理后仍无法确定长度的 uniform 数组、采样器数组与采样器类型不匹配的声明会被拒绝（着色器/链接日志会说明）。`#ifdef` 内的代码没问题；非采样器 uniform 声明会被移到外层顶层位置，保证块是无条件的。
 
@@ -116,6 +116,6 @@ transform feedback（入口为空操作）与 MSAA/采样缓冲（SDL_GPU 的 Me
 
 ## three.js
 
-`.js` 资源加载器现在只修补 three.js 的着色器循环展开；`WebGLRenderer` 在本引擎真正的 WebGL 2 后端上原样运行，**不再打包 Canvas2D 回退**。已用 three.js r160 通过 SDL_GPU 验证：`MeshBasicMaterial`、`MeshStandardMaterial`、`MeshPhongMaterial`、`CanvasTexture`、线性雾、环境光/平行光/点光/聚光/半球光、`Sprite`、`Line`、`Points` 与 `InstancedMesh`。
+着色器改写器会把 three.js 的 `#pragma unroll_loop_start` 循环展开为常量索引（否则其采样器数组无法通过 Vulkan GLSL），`.js` 资源加载器则避免渲染器自带的展开器重复处理。`WebGLRenderer` 在本引擎真正的 WebGL 2 后端上原样运行，**不再打包 Canvas2D 回退**。已用 three.js r160 通过 SDL_GPU 验证：`MeshBasicMaterial`、`MeshStandardMaterial`、`MeshPhongMaterial`、`CanvasTexture`、线性雾、环境光/平行光/点光/聚光/半球光、`Sprite`、`Line`、`Points` 与 `InstancedMesh`。
 
 本引擎子集之外的能力仍无法模拟：transform feedback 与 MSAA；立方体贴图/环境贴图、深度纹理、HDR/浮点渲染目标与压缩纹理已经可用。需要这些能力的场景无法正确渲染；此前 Canvas2D 回退能显示的内容现在全部走 GPU。

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

@@ -146,15 +146,16 @@ export default __html;
 ### 2b. 外部 `<script src>`
 
 `<script src="./app.ts">` 相对 HTML 文件读取、解析并拆分：其顶层
-`import`/`export … from` 语句被**提升**到生成的模块（相对说明符被重写以便
-从 HTML 文件所在目录解析），其余语句被包装进脚本函数。这样外部脚本既能在
-`loadHTML` 时运行，又能 `import` 其他模块。
-
-两个限制被强制执行并以清晰的错误报告，而不是悄悄出错：
-
-- 缺失的 `src` 文件会抛错（被转换为 bundler 诊断），并且
-- 两个 `src` 脚本导入同一个本地绑定名会冲突；用户必须给其中一个起别名。
-  （不冲突或完全相同的导入没问题。）
+`import`/`export … from` 语句从主体中移除，其余语句被包装进脚本函数。相对
+import 会像浏览器的模块脚本一样**延迟**：loader 生成一个合成的
+`__xt_deferred_module` 标记，生成的脚本在 `loadHTML` 时调用模块包装函数。
+bundler 把整个本地 import 图包装成返回各自导出的函数（由 `__xt_defer`
+记忆化），因此模块顶层代码在文档就绪后才运行，且两个脚本导入同一模块时共享
+同一个实例。裸说明符（`gui`、npm 包）仍然立即加载。
+
+缺失的 `src` 文件仍会抛出清晰的错误（被转换为 bundler 诊断）；
+`src` URL（`https://…`、`data:…`、`//host`）保持原样 —— 它们不是编译期资产，
+永不运行。
 
 `src` URL（`https://…`、`data:…`、`//host`）保持原样 —— 它们不是编译期资产，
 永不运行。
@@ -283,10 +284,10 @@ Event 的 `target` 是句柄，其描述符（`toString`）与同一 `div#id.cla
   - **M9b** ✅ —— gui `.html` 加载器（`src/extensions/gui/html.ts`）、
     `__registerScript` 内置函数、脚本注册表（`runtime/ext_gui/script.cpp`）、
     `loadHTML` 执行与 `DOMContentLoaded`/`load`；e2e 覆盖。
-  - **M9c** ✅ —— 读取 `<script src>` 文件，其顶层 import 被提升（说明符被
-    重写以便从 HTML 文件解析），其主体被包装并注册；缺失文件与 import 绑定
-    冲突作为诊断浮现。所有脚本按文档顺序运行（实际上是 deferred）。e2e
-    覆盖。
+  - **M9c** ✅ —— 读取 `<script src>` 文件，其主体被包装并注册；相对 import
+    通过带记忆化的模块包装函数延迟到 `loadHTML` 求值，因此 import 图能看到
+    已解析的文档，且同一模块只实例化一次。缺失文件作为诊断浮现。所有脚本按
+    文档顺序运行。e2e 覆盖。
   - **M9d** *(可选)* —— 检测传给 `win.loadHTML(...)` 的模板字面量中的内联
     HTML 并同样转换它们（脆弱；推迟）。
 - **M10 — 打磨** ✅ —— 窗口上的

package/doc/zh-CN/gui.md

@@ -167,9 +167,10 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
      `__registerScript` 内置函数注册，并替换为
      `<script data-xt-id="<hash>">` 标记；`win.loadHTML` 在解析后运行匹配的
      函数并触发 `DOMContentLoaded` 然后是 `load`。
-   - **M9c** ✅ —— `<script src>` 文件相对 HTML 读取，其顶层 import 被提升
-     （说明符从 HTML 目录重写），其主体被包装/注册；缺失文件与 import 绑定
-     冲突会成为诊断。一切都按文档顺序运行。
+   - **M9c** ✅ —— `<script src>` 文件相对 HTML 读取，其主体被包装/注册；
+     相对 import 通过带记忆化的模块包装函数延迟到 `loadHTML` 求值，因此被导入
+     模块能看到已解析的文档并共享状态。缺失文件会成为诊断。一切都按文档顺序
+     运行。
 10. **M10 — 打磨** ✅
     - `win.requestAnimationFrame(fn)` / `win.cancelAnimationFrame(id)`；回调
       在每帧顶部以帧时间戳运行，并可修改 DOM
@@ -317,9 +318,9 @@ FFmpeg `7.1`（供可选的 `media` 归档使用；可用 `SDL3_TAG` /
   编译为启动时注册、由 `win.loadHTML` 运行的 AOT 函数（在首次布局之前；
   `DOMContentLoaded` 然后是 `load`）。`tests/extensions/gui.test.ts` 中的单元
   测试，`tests/e2e/gui-*.test.ts` 中的 e2e。
-- **M9c** ✅ 外部 `<script src>` 文件被读取，其 import 被提升（说明符从 HTML
-  目录重写），其主体被包装/注册；缺失文件与 import 绑定冲突会成为诊断。
-  加载器错误被 `loadGraph` 捕获并报告为构建错误。
+- **M9c** ✅ 外部 `<script src>` 文件被读取，其主体被包装/注册；相对 import
+  通过带记忆化的模块包装函数延迟到 `loadHTML`（模块级 DOM 工作因此能看到已解析
+  文档）；缺失文件会成为诊断。加载器错误被 `loadGraph` 捕获并报告为构建错误。
 - **M10** ✅ 窗口句柄上的 `requestAnimationFrame`/`cancelAnimationFrame`
   （回调在每帧布局之前以帧时间戳运行），以及元素句柄上的
   `offsetWidth`/`offsetHeight`/`contains`；e2e 覆盖在

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

@@ -7,6 +7,10 @@
 - 全局 `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` 拒绝。
+- **没有协议的引用**（相对路径）与 `file://` URL 会读取本地文件，因此编译后的程序
+  无需 HTTP 服务即可加载磁盘资源。相对路径相对工作目录解析；支持 `GET` / `HEAD`。
+  在 Windows 上，标准写法 `file:///C:/dir/file` 与 `file://C:/dir/file` /
+  `file://C:\dir\file` 都指向同一个文件。
 - 选项：`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`。

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

@@ -19,6 +19,16 @@
 - 导入绑定与命名空间成员是模块求值时的快照（无实时绑定）—— 见[未实现：模块系统](../unimplemented/modules.md)。
 - 纯类型导入与再导出（`import type { T } from "..."`、`import { type T } from "..."`、`export type { T } from "..."`）会被擦除，**不构成模块依赖边**：目标模块不会被加载或打包，模块之间的纯类型循环也不属于循环依赖。若需要仅求值一个模块而不绑定名字，请使用副作用导入（`import "./mod"`）。
 
+## 延迟求值
+
+- `gui` 的 `.html` 资产加载器用合成的 `__xt_deferred_module` 绑定标记相对的
+  `<script src>` import。bundler 会把该模块及其本地 import 图包装成返回各自
+  导出的函数，生成的脚本在 `loadHTML` 之后调用它们（`__xt_defer` 对每个模块
+  做记忆化）。这与浏览器的模块脚本一致：文档就绪后才求值 import 图。
+- 同时被普通（非标记）import 引用的模块保持立即求值，并获得一个返回已初始化
+  导出的薄包装。
+- 包装体是同步的：延迟脚本模块中的顶层 `await` 不受支持。
+
 ## import.meta
 
 - `import.meta.url` / `.dirname` / `.filename`，由正在运行的可执行文件路径解析。

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

@@ -53,6 +53,21 @@
 - `Symbol(description)` 原始值（`XT_OBJECT_KIND_SYMBOL`）、13 个著名符号（`Symbol.iterator`、`Symbol.asyncIterator`、`Symbol.match` 等）、`Symbol.for` / `Symbol.keyFor` 全局注册表、`symbol.description` / `toString()` / `valueOf()`。
 - symbol 可作为属性键（`Object.getOwnPropertySymbols`，symbol 键的 `get`/`set`/`in`/`delete`），会被 `Object.keys` / `values` / `entries` / `for...in` / `JSON.stringify` 跳过，打印为 `Symbol(desc)`。
 
+## URL
+
+- `URL` 实现在 `runtime/xt_url_object.c`：支持 `new URL(input)` 与
+  `new URL(input, base)`（base 也可以是另一个 `URL`），并按层级式
+  `scheme://authority/path` base 解析相对引用。
+- **没有协议的引用按文件路径处理**：`new URL("./model.glb")` 相对工作目录解析，
+  得到 `file:` URL（显式 base 仍然生效，因此 `new URL("./x", import.meta.url)`
+  也可用）。
+- 只读属性 `href`、`protocol`、`origin`、`host`、`hostname`、`port`、
+  `pathname`、`search`、`hash`、`searchParams` 以及 `toString()` / `toJSON()`；
+  绝对输入按原样保留，但 `file:` URL 的 Windows 写法（`file://C:/dir` 与
+  `file://C:\dir`）会规范化为 `file:///C:/dir`，与 Node 一致。
+- 不是完整的 WHATWG 解析器：未实现路径百分号编码、IDNA、setter 与
+  `searchParams` 的实时同步 —— 见[运行时偏差](../unimplemented/deviations.md)。
+
 ## URLSearchParams
 
 - `URLSearchParams` 实现在 `runtime/xt_url.c`。