xbintsc 0.5.37 → 0.5.41

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
 
@@ -33,9 +36,10 @@ WebGL 1 one) and adds the WebGL 2 constants and methods.
   `height` attributes. `canvas.width = …` recreates them and discards the
   contents, like the DOM rule.
 - The context records into its own SDL_GPU command buffer. `clear`/`draw*`
-  keep a render pass open; a buffer/texture upload or a framebuffer change ends
-  it and starts a new pass with `LOAD`, so the drawing buffer persists between
-  draws just like WebGL's.
+  keep a render pass open; only a buffer/texture upload or a framebuffer
+  change ends it and starts a new pass with `LOAD`, so the drawing buffer
+  persists between draws just like WebGL's and a draw that has nothing to
+  upload never breaks the pass.
 - Once per frame, before the page's own render pass, the engine submits every
   WebGL command buffer. The image pipeline then samples the colour texture as
   an ordinary `PaintImage`, with no CPU copy.
@@ -54,8 +58,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
@@ -85,6 +90,8 @@ The translator (`runtime/ext_gui/webgl_glsl*.cpp`) handles GLSL ES 1.00 and
 | non-sampler uniforms | one `layout(std140) uniform XtUniforms { … }` block |
 | `uniform sampler2D u_tex` | `layout(set = 2, binding = N) uniform sampler2D u_tex` (fragment) or set 0 (vertex) |
 | `gl_FragData[0]` | `xt_FragColor` |
+| `gl_FragDepth` / `gl_FragDepthEXT` | kept (SPIR-V `DepthReplacing`; MSL `[[depth(any)]]`) |
+| `sampler2DShadow` / `samplerCubeShadow` / `sampler2DArrayShadow` | kept; bound as an SDL_GPU comparison sampler |
 | a missing `#version` / `#version 100` | `#version 310 es` |
 
 Non-sampler uniforms are merged across both stages and emitted as one block in
@@ -96,9 +103,21 @@ 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.
+
+A fragment shader may write `gl_FragDepth`; glslang marks the SPIR-V module
+`DepthReplacing` and SPIRV-Cross emits `[[depth(any)]]`, so the write reaches the
+depth attachment on both backends. The comparative samplers
+(`sampler2DShadow`, `samplerCubeShadow`, `sampler2DArrayShadow`) use the same
+SDL_GPU sampler objects with `enable_compare` set; `TEXTURE_COMPARE_MODE` and
+`TEXTURE_COMPARE_FUNC` are read from the texture (or from a bound sampler
+object in WebGL 2).
 
 ### GLSL ES 3.00 (WebGL 2)
 
@@ -169,9 +188,10 @@ available from GLSL ES 3.00, which is what the instanced example uses.
   `framebufferTexture2D` (`COLOR_ATTACHMENT0`, `DEPTH_ATTACHMENT`,
   `DEPTH_STENCIL_ATTACHMENT`), `checkFramebufferStatus`, `createRenderbuffer`,
   `bindRenderbuffer`, `renderbufferStorage` (depth or depth-stencil),
-  `framebufferRenderbuffer`, `delete*`, and `blitFramebuffer` (colour
-  attachment; depth/stencil bits are accepted but not copied). This is enough
-  for render-to-texture, shadow maps and post-processing passes.
+  `framebufferRenderbuffer`, `delete*`, and `blitFramebuffer` (colour through
+  SDL's blit; depth through a sampling pass that writes `gl_FragDepth`; stencil
+  bits are accepted but not copied). This is enough for render-to-texture,
+  shadow maps and post-processing passes.
 - **State**: `enable`/`disable`/`isEnabled` for `BLEND`, `DEPTH_TEST`,
   `CULL_FACE`, `SCISSOR_TEST` and `STENCIL_TEST`,
   `clearColor`/`clearDepth`/`clearStencil`, `clear` (with `SCISSOR_TEST` it
@@ -240,12 +260,17 @@ backend's `[0, 1]` clip space rather than GL's `[-1, 1] → [0, 1]` remap:
 
 ## Not implemented
 
-Transform feedback (the entry points are no-ops) and MSAA/sample buffers
-(SDL_GPU's Metal multisample resolve returns undefined pixels with scissor
-tests and instanced draws, so contexts stay single-sampled). `blitFramebuffer`
-copies the colour attachment only; depth/stencil bits are accepted but not
-copied. Shaders that use built-in blocks or `gl_FragDepth` are rejected with a
-compile/link log.
+Transform feedback (the entry points are no-ops: SDL_GPU has no transform
+feedback stage) and MSAA/sample buffers (SDL_GPU 3.2 can resolve multisampled
+colour targets, but its Metal resolve returns undefined pixels with scissor
+tests and instanced draws, so contexts stay single-sampled and `SAMPLE_BUFFERS`
+reports 0). `blitFramebuffer` copies colour and depth; stencil bits are accepted
+but not copied because SDL_GPU cannot sample a stencil attachment.
+
+Shader limitations that remain: struct-typed uniforms and user uniform blocks
+are flattened, but built-in interface blocks (`gl_PerVertex` redeclarations) are
+not part of the translated subset. A shader that uses one still fails with a
+compile/link log rather than silently misbehaving.
 
 ## Platform
 
@@ -267,7 +292,10 @@ uses the 2D canvas or the DOM pays no run-time cost beyond the archive size.
 - `tests/e2e/gui-webgl.test.ts` compiles GLSL, draws a textured and a
   depth-tested quad, checks face culling and reads the pixels back; it also
   covers blend constants, dynamic buffer usage, vertex-shader texture sampling,
-  `gl_FragDepth` diagnostics, context loss/restore and cube maps.
+  `gl_FragDepth`, context loss/restore and cube maps.
+- `tests/e2e/gui-webgl2-shadow-sampler.test.ts` covers hardware
+  `sampler2DShadow` comparisons, a shader-written `gl_FragDepth` that occludes a
+  later draw, and a partial `blitFramebuffer` depth copy.
 - `tests/e2e/gui-webgl2.test.ts` covers the WebGL 2 shader/state additions:
   `#version 300 es` shaders, a VAO round trip, instanced draws with a divisor,
   `texStorage2D`, `clearBufferfv`, buffer copies, sampler objects, struct-uniform
@@ -299,17 +327,18 @@ 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`.
 
 Features outside this engine's subset still cannot be emulated: transform
-feedback and MSAA.
-Depth textures, float render targets and compressed textures are available, but
-three.js shadow maps still need comparative `sampler2DShadow` sampling, which
-is not translated yet. A scene that needs one of those will not render
-correctly; everything the previous Canvas2D fallback could show now goes
-through the GPU.
+feedback and MSAA. Depth textures, float render targets and compressed textures
+are available, and comparative `sampler2DShadow` sampling is translated, so
+three.js shadow maps can use the hardware depth compare on both backends. A
+scene that needs transform feedback or MSAA will not render correctly;
+everything the previous Canvas2D fallback could show now goes through the GPU.

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

@@ -1,6 +1,6 @@
 # xbintsc GUI extension (self-hosted HTML/CSS renderer)
 
-Status: **M19** — features (M1–M15) are complete: HTML parsing, CSS selector
+Status: **M20** — 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
@@ -44,6 +44,10 @@ them) can be translated, scaled and rotated without reflowing anything — and
 `clip-path` and the `filter` colour/shadow effects. `backdrop-filter` and true
 group blur need an offscreen compositor and remain documented approximations or
 unsupported — see [Rendering](./gui/rendering.md#backgrounds-generated-content-and-effects-m19).
+**M20** makes large documents interactive: `@media` is evaluated once per rule,
+layout and paint share a bounded shaping cache, and a frame only does (and
+presents) the work a change requires — see
+[Performance](./gui/rendering.md#performance-m20).
 This overview records the locked decisions, the architecture, the milestone plan
 and the current progress; the engine itself is documented by function in the
 pages above.
@@ -219,10 +223,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
@@ -341,6 +346,18 @@ engine were Rust.
       offscreen backdrop pass (see [Known issues](./gui/known-issues.md)).
     - E2E coverage in `tests/e2e/gui-effects.test.ts`; see
       [Rendering](./gui/rendering.md#backgrounds-generated-content-and-effects-m19).
+20. **M20 — rendering performance** ✅
+    - `@media` evaluated once per rule per restyle, generated content skipped for
+      sheets without pseudo-elements, and `:hover`/`:focus` restyle only when
+      the sheet tracks them.
+    - Bounded two-generation shaping cache shared by layout and paint, plus a
+      primary-face cache.
+    - Frame loop: reconcile media/canvas only when the document changed, present
+      only when something happened, and gate the whole pass behind it.
+    - Reused display list/vertex staging/transfer buffers, one upload submit per
+      dirty frame, and redundant render-state binds removed.
+    - `win.stats()`/`XT_GUI_PERF` counters and `tests/e2e/gui-perf.test.ts`; see
+      [Performance](./gui/rendering.md#performance-m20).
 
 ## Progress log
 
@@ -387,10 +404,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
@@ -488,4 +506,20 @@ engine were Rust.
   functions plus nine-tap blur/drop-shadow and emits `text-shadow` runs, and
   `paint_clip.cpp`/`renderer_clip.cpp` clip geometry against triangulated
   `clip-path` polygons. E2E: `tests/e2e/gui-effects.test.ts`.
+- **M20** ✅ rendering performance. `@media` is evaluated once per rule per
+  restyle, generated content is skipped for sheets without `::before`/`::after`,
+  and `:hover`/`:focus` only restyle when the sheet tracks them
+  (`style.cpp`, `css_sheet.cpp`). A bounded two-generation shaping cache
+  (`text_cache.cpp`) serves layout and paint, so a word is shaped once instead
+  of on every layout pass and repaint; primary faces are cached by
+  (class, size) too. The frame loop reconciles decoders/canvases only when the
+  document changed and presents only when something happened
+  (`gui_events.cpp`), so a static page does no GPU work
+  (`XT_GUI_ALWAYS_PRESENT=1` restores the old behaviour for debugging). The
+  display list, vertex staging and transfer buffers are reused, a dirty frame's
+  uploads share one command buffer, and the renderer only re-binds state that
+  changed (`renderer*.cpp`, `gui_engine.h`). `win.stats()` reports per-frame
+  timings and cumulative work counters and `XT_GUI_PERF` prints them
+  (`perf.{h,cpp}`); `tests/e2e/gui-perf.test.ts` pins a 200-row list. See
+  [Performance](./gui/rendering.md#performance-m20).
 

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

@@ -91,8 +91,9 @@ requestAnimationFrame(frame);
 | `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)）。 |
+| `ImageBitmap`、`createImageBitmap(source)` | 由已解码像素支撑的不可变位图（`<img>`、`<canvas>`、`<video>` 帧、`OffscreenCanvas` 与 `ImageData` 形状）；promise 立即 settle，`texImage2D` 可直接接受该对象 |
+| `OffscreenCanvas` | 真正的 2D 离屏位图，带 `getContext("2d")`、`width`/`height`、`transferToImageBitmap()` 与 `convertToBlob()`；`canvas.transferControlToOffscreen()` 会把元素位图交给它（见 [Canvas](./canvas.md)）。离屏 WebGL 上下文不提供。 |
+| `ImageData`、`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` | 宿主实现。`matchMedia` 返回**实时**列表（按查询缓存）：`matches` 在窗口尺寸变化时重新求值，翻转时触发 `change` 监听器。`confirm`/`prompt` 仅在 `XT_GUI_DIALOGS=1` 时使用原生对话框，否则把消息写到 stderr 并返回文档化的默认值（Annex B `escape` 按 UTF-16 码元编码，与 `decodeURIComponent(escape(bytes))` 一致） |
 
@@ -197,6 +198,28 @@ win.stats()                            // 引擎/运行时计数器（内存排
 `detachedNodes` 或 `handles` 持续上升，说明程序移除节点的速度快于释放速度
 （见[节点生命周期](./dom.md)）。
 
+同一个对象还报告上一帧做了什么以及程序累计做了多少工作，渲染开销就是靠它度量
+（见[性能](./rendering.md#性能m20)）：
+
+| 字段 | 含义 |
+| --- | --- |
+| `frameMs`、`restyleMs`、`layoutMs`、`paintMs`、`uploadMs`、`drawMs` | 上一帧各阶段耗时（毫秒） |
+| `frames`、`presents`、`exposes`、`deferred`、`skippedFrames`、`starvedFrames`、`transitionFrames` | 帧循环活动：`presents` 是提交呈现的帧数，`exposes` 是窗口系统用 expose/shown/restore 事件要求的呈现帧数，`deferred` 是取不到可绘制目标而被推迟的呈现帧数，`skippedFrames` 是无需提交的帧数，`starvedFrames` 是要求呈现却拿不到可绘制目标的帧数 |
+| `restyles`、`restyleNodes`、`rulesEvaluated`、`mediaEvaluated`、`layouts`、`layoutBoxes` | 层叠与布局的工作量 |
+| `textShapeCalls`、`textShapeHits`、`textCacheBytes`、`textCacheEntries` | 整形缓存的未命中/命中与占用 |
+| `paints`、`paintOps`、`drawRuns`、`drawCalls`、`uploadSubmits`、`vertices`、`syncNodes` | 显示列表、绘制调用与上传的工作量 |
+| `canvasDraws`、`canvasUploads`、`canvasUploadBytes` | Canvas 2D 绘制次数、纹理上传次数与拷贝字节数（局部重绘只上传脏矩形） |
+| `webglDraws`、`webglPasses`、`webglPipelineMisses`、`webglBufferUploadBytes` | WebGL 绘制次数、打开的渲染 pass 数、新建管线数与缓冲拷贝字节数 |
+
+除 `*Ms` 时间外，所有字段都是累计值，因此两次快照相减即得到一帧的工作量。
+`restyleMs` 覆盖层叠**以及**它触发的布局过程（布局过程本身也单独报告为
+`layoutMs`）。`presents - exposes - deferred` 才是仅由页面要求的呈现帧数：
+expose/shown/restore 事件表示窗口内容已丢失、必须重绘，而具体时机由窗口服务器
+决定；deferred 呈现则是重放某一帧在取不到交换链图像时已经构建好的内容，
+`starvedFrames` 统计这些帧（该值持续增长说明窗口完全没有被更新）。
+`XT_GUI_PERF=1` 会把同样的数字打印到 stderr（逐帧一行；`XT_GUI_PERF=<N>` 则每
+N 帧取平均）。
+
 它们被 `tests/e2e/gui-*.test.ts` 用来断言解析、选择器匹配、特异性、继承、
 `!important` 与布局几何。它们在之后仍可用于调试。
 

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

@@ -11,9 +11,11 @@ CSS 盒中。
 
 引擎侧的对象是 `xtgui::Canvas2D`（`runtime/ext_gui/canvas.{h,cpp}`）——一块 RGBA8 位图
 加上 2D 绘制状态。光栅器位于 `canvas_raster.cpp`，描边几何（端点、连接、虚线）位于
-`canvas_stroke.cpp`，渐变位于 `canvas_gradient.cpp`，绘制状态解析位于
-`canvas_style.cpp`；DOM 绑定位于 `dom_api_canvas.cpp` / `dom_api_canvas_extra.cpp`；
-按窗口的生命周期位于 `gui_canvas.cpp`。
+`canvas_stroke.cpp`，渐变位于 `canvas_gradient.cpp`，合成模式位于
+`canvas_composite.cpp`，裁剪与命中测试位于 `canvas_clip.cpp`，阴影位于
+`canvas_shadow.cpp`，绘制状态解析位于 `canvas_style.cpp`；DOM 绑定位于
+`dom_api_canvas*.cpp` / `dom_api_offscreen.cpp`；按窗口的生命周期位于
+`gui_canvas.cpp`。
 
 ## 获取上下文
 
@@ -31,6 +33,15 @@ const ctx = canvas.getContext("2d"); // 或 "webgl" 取得 GPU 上下文
 元素上，因此每次都返回**同一个**对象，绘制状态（变换、样式、路径）按 canvas 而非按调用
 保存。`ctx.canvas` 是所属元素的句柄。
 
+`OffscreenCanvas` 提供同样的 2D 接口，但没有 DOM 元素：
+`new OffscreenCanvas(width, height)` 分配一块由窗口拥有的位图，`getContext("2d")`
+返回的上下文其 `canvas` 指向离屏对象；`canvas.transferControlToOffscreen()` 会把一个
+活动元素的位图交给离屏对象（此后元素的 `getContext(…)` 返回 `null`）。
+`drawImage`、`createPattern`、`createImageBitmap` 与 `texImage2D` 都接受
+`OffscreenCanvas` 作为源。`transferToImageBitmap()` 返回 `ImageBitmap`，
+`convertToBlob()` 解析为与 `toBlob` 相同的 PNG blob 形状（本运行时没有 worker，
+离屏画布也不提供 WebGL 上下文）。
+
 `getContext("2d", attributes)` 在首次调用时会尊重 `alpha`：传入 `{ alpha: false }`
 时位图以不透明黑色初始化（清除也回到不透明黑）。其余属性由
 `getContextAttributes()` 按规范默认值报告（`antialias: true`、`depth: true`、
@@ -42,8 +53,30 @@ const ctx = canvas.getContext("2d"); // 或 "webgl" 取得 GPU 上下文
 光栅器刻意保持精简且为自研（不依赖 Skia/Cairo）。它按每条像素行 **4 条垂直子扫描线**
 进行抗锯齿，并做一次**水平解析覆盖率**计算；路径默认采用**非零环绕规则**填充（因此当弧线
 以相反方向环绕时能形成空洞），`fill("evenodd")` 则改用奇偶规则。轴对齐矩形（变换中
-`b == 0 && c == 0`）走直接的覆盖率快速路径。混合为非预乘 source-over，并按
-`globalAlpha` 缩放。
+`b == 0 && c == 0`）走直接的覆盖率快速路径。
+
+混合默认是非预乘 source-over。`globalCompositeOperation` 支持完整的 canvas 集合：
+Porter-Duff 算子（`source-over`、`source-in`、`source-out`、`source-atop`、
+`destination-over`、`destination-in`、`destination-out`、`destination-atop`、
+`lighter`、`copy`、`xor`）以及可分离/不可分离混合模式（`multiply`、`screen`、
+`overlay`、`darken`、`lighten`、`color-dodge`、`color-burn`、`hard-light`、
+`soft-light`、`difference`、`exclusion`、`hue`、`saturation`、`color`、
+`luminosity`）。抗锯齿与裁剪区域产生的部分覆盖率会在“未改动的目标”与“完整合成结果”
+之间插值，因此每个算子在部分覆盖的像素上都正确。
+
+`clip()` 用当前路径（或 `Path2D` 加可选的 `"nonzero"`/`"evenodd"` 规则）与当前裁剪区
+求交。区域以设备空间覆盖率掩码保存，因此它固定在调用 `clip()` 时的变换下；
+`save`/`restore` 会一并恢复，位图尺寸变化会清空它。所有填充、描边、文本、图像绘制与
+`clearRect` 都遵守该掩码。
+
+阴影（`shadowColor`、`shadowBlur`、`shadowOffsetX`、`shadowOffsetY`）由绘制操作自身的
+alpha 生成：先把操作渲染到临时图层，对其 alpha 做偏移与盒式模糊（三次可分离模糊），用
+`shadowColor` 着色后合成，最后把未处理的图层画在其上。偏移与模糊使用画布（设备）单位，
+不受变换影响，符合 API 规定。`clearRect` 与 `putImageData` 从不产生阴影。
+
+`isPointInPath(x, y[, fillRule])`、`isPointInPath(path, x, y[, fillRule])`、
+`isPointInStroke(x, y)` 与 `isPointInStroke(path, x, y)` 在当前变换下对当前路径（或
+传入的 `Path2D`）做命中测试；描边命中测试使用到各展平线段的设备空间距离与当前线宽。
 
 填充或描边可以使用纯色，也可以使用 **`CanvasGradient`**。渐变的坐标属于用户空间，
 因此光栅器会先用当前变换的逆矩阵把每个设备像素映射回用户空间再采样——形状被平移、
@@ -54,6 +87,27 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 `<video>`/`<audio>` 解码表结构相同）。当节点被丢弃（`loadHTML`、窗口关闭/退出，或丢弃
 子树的变更操作）时随之释放，并释放对应的 GPU 纹理。
 
+## 性能
+
+canvas 由脚本重绘而不是引擎重绘，因此开销按绘制调用计。多元素场景下的热路径刻意
+保持少分支：
+
+- 纯色不透明的 `fillRect` 直接按字节写入位图（小数边缘仍走抗锯齿路径），覆盖整张
+  位图的 `clearRect` 退化为一次 `memset`；
+- 路径覆盖率使用逐行**活动边表**光栅化，并且只物化每一行**实际覆盖的区间**——一条
+  细对角线描边只花它自己的像素，而不是整个包围盒；
+- 一次 `stroke()` 把所有线段四边形、连接与端点合并成一次非零环绕填充，而不是每段
+  各做一次覆盖率计算（先统一每个多边形的绕向，重叠处才能覆盖而不是抵消）；
+- `fillText` 与布局共享整形缓存（`text_cache.cpp`），并使用有界两代字形位图缓存
+  （`text_glyph_cache.cpp`）；
+- 整数偏移、无缩放的 `drawImage` 逐像素只取一个纹素，不再跑双线性采样器。
+
+位图通过**脏矩形**到达屏幕：每次绘制把它的设备空间包围盒并入待上传区域，渲染器只
+拷贝该区域到 canvas 纹理。一帧内所有 canvas 与视频上传共用帧的唯一上传命令缓冲，
+因此 K 张动画 canvas 只需一次提交而不是 K 次。`getImageData` 始终读取 CPU 位图，
+不受影响。`tests/e2e/gui-draw-perf.test.ts` 测量这些多元素路径并固定计数器行为
+（每帧一次上传、只传脏字节）。
+
 ## 支持的 API
 
 状态与变换：`save` / `restore`（会恢复变换、线宽、透明度、字体/文本设置**以及**
@@ -64,30 +118,37 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 `translate(x, y); rotate(a)` 围绕平移后的原点旋转。
 
 样式与设置：`fillStyle` / `strokeStyle`（层叠所用的颜色解析器能识别的 CSS 颜色，或
-`CanvasGradient`）、`lineWidth`、`globalAlpha`、`lineCap`（`butt`/`round`/`square`）、
+`CanvasGradient`）、`lineWidth`、`globalAlpha`、`globalCompositeOperation`、
+`shadowColor` / `shadowBlur` / `shadowOffsetX` / `shadowOffsetY`、
+`imageSmoothingEnabled` / `imageSmoothingQuality`、`lineCap`（`butt`/`round`/`square`）、
 `lineJoin`（`miter`/`round`/`bevel`）、`miterLimit`、`lineDashOffset`、`font`
 （CSS 字体简写，解析出字体族、字号与粗体/斜体——默认 `10px sans-serif`）、
 `textAlign`（`start`/`left`、`center`、`right`/`end`）与 `textBaseline`
 （`alphabetic`、`top`、`middle`、`bottom`、`hanging`、`ideographic`）。读取属性返回
-上次赋予的值；赋予无法解析的颜色会保留原值。
+上次赋予的值；赋予无法解析的颜色会保留原值。`imageSmoothingEnabled` 默认为 `true`
+（双线性采样）；`imageSmoothingQuality` 报告 `low`、`medium` 或 `high`，本后端都使用
+同一种双线性过滤。
 
 渐变：`createLinearGradient(x0, y0, x1, y1)` 与
 `createRadialGradient(x0, y0, r0, x1, y1, r1)` 返回带
 `addColorStop(offset, color)` 的 `CanvasGradient`。色标是**活的**：在
 `fillStyle = gradient` 之后追加的色标会影响后续填充，且 `fillStyle`/`strokeStyle`
-的读取返回同一个渐变句柄。径向渐变按到**外圆**圆心（`x1, y1`）的距离插值，因此目前
-会忽略 `x0`/`y0`——请使用同心圆（`x0 == x1`、`y0 == y1`）。
+的读取返回同一个渐变句柄。径向渐变是通用的双圆锥：点上的颜色由插值圆
+（`圆心 = c0 + t·(c1 − c0)`、`半径 = r0 + t·(r1 − r0)`）解出，因此内圆有偏移、两圆
+半径不同时都与浏览器一致。内圆内部的点采样色标 0。
 
 路径：`beginPath`、`closePath`、`moveTo`、`lineTo`、`rect`、`roundRect`、`arc`、
 `ellipse`、`quadraticCurveTo`、`bezierCurveTo`，然后
-`fill(fillRule?)` / `fill(path, fillRule?)`（多环；`"nonzero"` 或 `"evenodd"`）或
-`stroke(path?)`。贝塞尔与二次曲线段会被展平为线段；弧线与椭圆同样被展平。
+`fill(fillRule?)` / `fill(path, fillRule?)`（多环；`"nonzero"` 或 `"evenodd"`）、
+`stroke(path?)`、`clip(path?, fillRule?)` 以及 `isPointInPath`/`isPointInStroke`
+命中测试。贝塞尔与二次曲线段会被展平为线段；弧线与椭圆同样被展平。
 `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`，因此一次构建的路径可以在不同变换下重复使用。
+并可传给 `fill`/`stroke`/`clip` 以及 `isPointIn*` 命中测试，因此一次构建的路径可以在
+不同变换下重复使用。
 
 矩形：`clearRect`、`fillRect`、`strokeRect`。
 
@@ -103,29 +164,37 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 
 图像：`drawImage(source, …)` 支持 3 参数（`dx, dy`）、5 参数（`dx, dy, dw, dh`）与
 9 参数（本引擎为**目标优先**：`dx, dy, dw, dh, sx, sy, sw, sh`）。完整的仿射变换
-（旋转/斜切/缩放）会被应用：目标矩形变为平行四边形，每个设备像素反查到源矩形
-（最近邻采样）。`source` 可以是 `<img>` 元素（经图像
-模块解码）或另一个 `<canvas>` 元素（取其当前位图）。采样为最近邻，因此把小图大幅放大
-会有块状感——适合图标与像素画，不适合照片管线。
+（旋转/斜切/缩放）会被应用：目标矩形变为平行四边形，每个设备像素反查到源矩形。
+`source` 可以是 `<img>` 元素（经图像模块解码）、另一个 `<canvas>`、
+`OffscreenCanvas` 或 `ImageBitmap`。`imageSmoothingEnabled` 为 `true`（默认）时使用
+双线性采样，为 `false` 时使用最近邻。
 
 测试钩子：`getImageData(x, y, w, h)` 把区域复制为 `{ width, height, data }`，其中
 `data` 是按行主序的 RGBA8 字节数组。越界像素为透明。
 
-图案：`createPattern(source, repetition?)` 接受 `<img>` 或另一个 `<canvas>`，在用户
-空间中平铺（`repeat`、`repeat-x`、`repeat-y`、`no-repeat`），因此平铺会跟随当前
-变换。把结果赋给 `fillStyle`/`strokeStyle`；重新赋颜色会替换掉图案。
+图案：`createPattern(source, repetition?)` 接受 `<img>`、`<canvas>`、
+`OffscreenCanvas` 或 `ImageBitmap`，在用户空间中平铺（`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`）。
+dirtyWidth, dirtyHeight])` 直接把字节写入位图（不受变换、混合、裁剪或
+`globalAlpha` 影响）。`canvas.toDataURL(type?)` 导出 PNG data URL，
+`canvas.toBlob(callback, type?)` 从微任务中交付 Blob 形状的 `{ type, size }`
+（字节在 `__xt_gui_blob_data` 上；本运行时没有 `URL.createObjectURL`）。
+`OffscreenCanvas.convertToBlob()` 解析为同一形状，`transferToImageBitmap()` 对位图
+做快照。
+
+CSS 背景：`background-image: url(...)` 接受文件路径或 `data:` URL，因此可以先把
+canvas 导出再作为 CSS 背景使用
+（`element.style.backgroundImage = "url(" + canvas.toDataURL() + ")"`）。图像层会拉伸
+到元素的边框盒；`background-size`、`background-position` 与平铺尚未建模。
 
 ## 尚未实现
 
-阴影、`clip()`、`globalCompositeOperation`、`isPointInPath`、可切换图像平滑的
-`drawImage`、把 `<canvas>` 用作 CSS `background-image`，以及离屏画布
-（`OffscreenCanvas`、`transferControlToOffscreen`）。径向渐变会忽略内圆偏移。
+本后端的平滑质量只有一种过滤（双线性）。离屏画布只支持 2D 上下文（WebGL 上下文需要
+DOM 元素来维护纹理表）。旋转的字形位图仍不会随变换旋转，`strokeText` 仍用描边样式
+填充而非生成轮廓。
 
 另见[媒体](./media.md)：`drawImage` 与纹理上传所共享的图像/视频/音频解码栈。