xbintsc 0.5.37 → 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/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`。

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

@@ -8,6 +8,7 @@
 | --- | --- |
 | 正则按字节匹配 | 引擎按 UTF-8 字节匹配：多字节字面量仍可匹配，但 `.` 与字符类每次只消费一个字节（`\d`/`\w` 仍是 ASCII）。`exec` / `search` / 替换回调返回的偏移会转换为 UTF-16 码元 |
 | 全局正则 `lastIndex` | `/g`、`/y` 正则的 `test` / `exec` 不推进也不读取调用方设置的 `lastIndex` |
+| `URL` 解析器 | 只读 WHATWG 子集：未实现路径百分号编码、IDNA、setter 与 `searchParams` 实时联动；无协议引用按工作目录解析为 `file:` URL |
 | `String.normalize` | 未实现 |
 | 内置方法一等公民 | 以未绑定方法值实现（见[函数](./functions.md)）；`fn.toString()` 返回占位字符串而非源码文本 |
 | `for...in` | 枚举对象 / 数组 / 字符串的自身键；不含原型链属性 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xbintsc",
-  "version": "0.5.37",
+  "version": "0.5.38",
   "description": "xbintsc - a TypeScript binary compiler (TypeScript -> LLVM IR -> native binary)",
   "type": "module",
   "license": "MIT",
@@ -72,12 +72,12 @@
     "vitest": "^2.1.8"
   },
   "optionalDependencies": {
-    "@xbintsc/linux-x64": "0.5.37",
-    "@xbintsc/linux-arm64": "0.5.37",
-    "@xbintsc/darwin-x64": "0.5.37",
-    "@xbintsc/darwin-arm64": "0.5.37",
-    "@xbintsc/win32-x64": "0.5.37",
-    "@xbintsc/win32-arm64": "0.5.37"
+    "@xbintsc/linux-x64": "0.5.38",
+    "@xbintsc/linux-arm64": "0.5.38",
+    "@xbintsc/darwin-x64": "0.5.38",
+    "@xbintsc/darwin-arm64": "0.5.38",
+    "@xbintsc/win32-x64": "0.5.38",
+    "@xbintsc/win32-arm64": "0.5.38"
   },
   "engines": {
     "node": ">=22"

package/runtime/ext_gui/dom_api_webgl.cpp

@@ -223,6 +223,16 @@ xt_value webgl_proto() {
   define_getter(proto, "canvas", (void *)webgl_canvas_get);
   define_getter(proto, "drawingBufferWidth", (void *)webgl_drawing_buffer_width_get);
   define_getter(proto, "drawingBufferHeight", (void *)webgl_drawing_buffer_height_get);
+  /* `gl.constructor.name` is how three.js tells a WebGL 2 context from a
+   * WebGL 1 one. A host-type value from `xt_browser_type` later replaces this
+   * with the real constructor (and its `prototype`), but the context must
+   * answer the name even when the page never read the global. */
+  {
+    xt_value constructor = xt_object_new();
+    xt_object_set(constructor, xt_string_from_cstr("name"),
+                  xt_string_from_cstr("WebGLRenderingContext"));
+    xt_object_set(proto, xt_string_from_cstr("constructor"), constructor);
+  }
   g_webgl_proto = proto;
   return proto;
 }

package/runtime/ext_gui/dom_api_webgl2.cpp

@@ -121,12 +121,44 @@ xt_value uint_array(const unsigned int *values, int count) {
 xt_value webgl2_proto() {
   xt_gc_add_root(&g_webgl2_proto);
   if (XT_IS_OBJECT(g_webgl2_proto)) return g_webgl2_proto;
-  xt_value proto = xt_object_new_with_proto(webgl_proto());
+  /* WebGL 2 shares the WebGL 1 surface but not its prototype: in a browser
+   * `gl2 instanceof WebGLRenderingContext` is false, which is how three.js and
+   * other libraries detect WebGL 2. Copy the WebGL 1 members instead of
+   * inheriting the WebGL 1 prototype. */
+  xt_value webgl1 = webgl_proto();
+  xt_value proto = xt_object_new();
+  xt_value keys = xt_object_keys(webgl1);
+  const double count = xt_to_number(xt_array_length(keys));
+  for (int32_t i = 0; i < (int32_t)count; i++) {
+    xt_value key = xt_array_get(keys, xt_number((double)i));
+    const char *name = xt_string_data(key);
+    if (name == nullptr) continue;
+    /* `constructor` gets the WebGL 2 name below. The three host getters are
+     * accessors, not values: reading them here would run them against the
+     * WebGL 1 prototype and copy `undefined`. Reinstall them as accessors. */
+    if (strcmp(name, "constructor") == 0 || strcmp(name, "canvas") == 0 ||
+        strcmp(name, "drawingBufferWidth") == 0 || strcmp(name, "drawingBufferHeight") == 0) {
+      continue;
+    }
+    xt_object_set(proto, key, xt_object_get(webgl1, key));
+  }
+  xt_object_define_getter(proto, xt_string_from_cstr("canvas"),
+                          xt_closure_new((void *)webgl_canvas_get, 0, nullptr));
+  xt_object_define_getter(proto, xt_string_from_cstr("drawingBufferWidth"),
+                          xt_closure_new((void *)webgl_drawing_buffer_width_get, 0, nullptr));
+  xt_object_define_getter(proto, xt_string_from_cstr("drawingBufferHeight"),
+                          xt_closure_new((void *)webgl_drawing_buffer_height_get, 0, nullptr));
 #define XT_WEBGL2_CONSTANT(name, value) \
   xt_object_set(proto, xt_string_from_cstr(#name), xt_number((double)(value)));
   XT_WEBGL2_CONSTANTS(XT_WEBGL2_CONSTANT)
 #undef XT_WEBGL2_CONSTANT
   for (const MethodEntry &method : kMethods) define_method(proto, method.name, method.fn);
+  {
+    xt_value constructor = xt_object_new();
+    xt_object_set(constructor, xt_string_from_cstr("name"),
+                  xt_string_from_cstr("WebGL2RenderingContext"));
+    xt_object_set(proto, xt_string_from_cstr("constructor"), constructor);
+  }
   g_webgl2_proto = proto;
   return proto;
 }

package/runtime/ext_gui/gui_engine.h

@@ -24,6 +24,8 @@ xt_value xt_gui_run(int32_t argc, xt_value *argv);
 xt_value xt_gui_quit(int32_t argc, xt_value *argv);
 /** `__registerScript(id, fn)`: record an AOT-compiled `<script>` body. */
 xt_value xt_register_script(int32_t argc, xt_value *argv);
+/** `__xt_defer(id, init)`: evaluate a deferred module once and cache its exports. */
+xt_value xt_gui_defer_module(int32_t argc, xt_value *argv);
 /** Which SDL_GPU backend the device is using (`"vulkan"`, `"direct3d12"`,
  * `"metal"`, …), or `""` before the device exists. */
 const char *xt_gui_driver(void);

package/runtime/ext_gui/script.cpp

@@ -25,6 +25,14 @@ static std::unordered_map<std::string, xt_value> &script_registry() {
   return registry;
 }
 
+/** Deferred module id -> its exports object. A `<script src>`'s imports are
+ * evaluated on first use (after `loadHTML`) and then shared by every script
+ * that imports the same module. */
+static std::unordered_map<std::string, xt_value> &deferred_registry() {
+  static std::unordered_map<std::string, xt_value> registry;
+  return registry;
+}
+
 extern "C" xt_value xt_register_script(int32_t argc, xt_value *argv) {
   if (argc >= 2) {
     xt_value id_value = xt_to_string(xt_arg(argc, argv, 0));
@@ -42,6 +50,29 @@ extern "C" xt_value xt_register_script(int32_t argc, xt_value *argv) {
 
 void xt_gui_script_gc_scan(void) {
   for (const auto &entry : script_registry()) xt_gc_mark_value(entry.second);
+  for (const auto &entry : deferred_registry()) xt_gc_mark_value(entry.second);
+}
+
+/** `__xt_defer(id, init)`: evaluate `init` once and return its exports. The
+ * placeholder is published before the call so a cyclic import sees the same
+ * object instead of recursing. */
+extern "C" xt_value xt_gui_defer_module(int32_t argc, xt_value *argv) {
+  if (argc < 2) return XT_UNDEFINED;
+  xt_value id_value = xt_to_string(xt_arg(argc, argv, 0));
+  const char *id = xt_string_data(id_value);
+  if (id == nullptr) return XT_UNDEFINED;
+  std::unordered_map<std::string, xt_value> &registry = deferred_registry();
+  auto found = registry.find(std::string(id));
+  if (found != registry.end()) return found->second;
+  xt_gc_register_root_provider(xt_gui_script_gc_scan);
+  xt_value exports = xt_object_new();
+  registry[std::string(id)] = exports;
+  xt_value init = xt_arg(argc, argv, 1);
+  if (XT_IS_FUNCTION(init)) {
+    exports = xt_call_with_this(init, XT_UNDEFINED, 0, nullptr);
+    registry[std::string(id)] = exports;
+  }
+  return exports;
 }
 
 /** Collect `data-xt-id` markers from `<script>` elements, in document order. */

package/runtime/ext_gui/webgl_glsl.h

@@ -126,6 +126,9 @@ struct GlslLinkLayout {
   std::vector<GlslUniformDecl> block_members;
 };
 
+/** Expand three.js's `#pragma unroll_loop_start` loops into constant indices. */
+std::string unroll_glsl_pragmas(const std::string &source);
+
 /** Scan `source` for the declarations WebGL needs to know about. */
 void scan_glsl(const std::string &source, bool fragment, GlslShaderInfo *info);