xbintsc 0.5.38 → 0.5.41

package/doc/gui/canvas.md

@@ -36,6 +36,16 @@ a shared prototype. The handle is cached on the element, so every call returns
 the **same** object and the drawing state (transform, styles, path) is per
 canvas, not per call. `ctx.canvas` is the owning element handle.
 
+`OffscreenCanvas` has the same 2D surface without a DOM element:
+`new OffscreenCanvas(width, height)` allocates a bitmap owned by the window,
+`getContext("2d")` returns a context whose `canvas` is the offscreen object, and
+`canvas.transferControlToOffscreen()` hands a live element's bitmap to one
+(`element.getContext(…)` then answers `null`). `drawImage`, `createPattern`,
+`createImageBitmap` and `texImage2D` accept an `OffscreenCanvas` as a source.
+`transferToImageBitmap()` returns an `ImageBitmap` and `convertToBlob()`
+resolves to the same PNG blob shape as `toBlob` (there is no worker or
+`OffscreenCanvas` WebGL context in this runtime).
+
 `getContext("2d", attributes)` honours `alpha` on the first call: with
 `{ alpha: false }` the bitmap starts (and clears) opaque black. The other
 attributes are reported by `getContextAttributes()` at their specification
@@ -51,7 +61,36 @@ horizontal coverage** pass, and fills paths with the **non-zero winding rule**
 (so `arc`-shaped holes work when wound the other way) unless
 `fill("evenodd")` selects the even-odd rule. An axis-aligned rectangle
 (`b == 0 && c == 0` in the transform) takes a direct coverage fast path.
-Blending is non-premultiplied source-over, scaled by `globalAlpha`.
+Blending uses non-premultiplied source-over by default. `globalCompositeOperation`
+selects the full canvas set: the Porter-Duff operators (`source-over`,
+`source-in`, `source-out`, `source-atop`, `destination-over`,
+`destination-in`, `destination-out`, `destination-atop`, `lighter`, `copy`,
+`xor`) and the separable/non-separable blend modes (`multiply`, `screen`,
+`overlay`, `darken`, `lighten`, `color-dodge`, `color-burn`, `hard-light`,
+`soft-light`, `difference`, `exclusion`, `hue`, `saturation`, `color`,
+`luminosity`). Coverage from anti-aliasing and the clip region interpolates
+between the untouched destination and the composited result, so a partially
+covered pixel is correct for every operator.
+
+`clip()` intersects the current clip region with the current path (or a
+`Path2D` and an optional `"nonzero"`/`"evenodd"` rule). The region is stored as
+a device-space coverage mask, so it follows the transform in effect when
+`clip()` was called; `save`/`restore` restore it and resizing the bitmap clears
+it. Every fill, stroke, text run, image draw and `clearRect` honours the mask.
+
+Shadows (`shadowColor`, `shadowBlur`, `shadowOffsetX`, `shadowOffsetY`) are
+painted from the operation's own alpha: the draw is first rendered into a
+scratch layer, its alpha is offset and box-blurred (three separable passes),
+tinted with `shadowColor`, composited, and the unfiltered layer is drawn over
+it. The offset and blur are in canvas (device) units and are not affected by
+the transform, as the API specifies. `clearRect` and `putImageData` never cast
+a shadow.
+
+`isPointInPath(x, y[, fillRule])`, `isPointInPath(path, x, y[, fillRule])`,
+`isPointInStroke(x, y)` and `isPointInStroke(path, x, y)` hit-test the current
+path (or the supplied `Path2D`) under the current transform; stroke hit testing
+uses the device-space distance to each flattened segment and the current line
+width.
 
 A fill or stroke paints with a solid colour **or a `CanvasGradient`**. Gradient
 coordinates are user-space coordinates, so the rasteriser maps each device pixel
@@ -67,6 +106,33 @@ decode table). It is released when the node is dropped (`loadHTML`, window
 close/quit, or a mutation that discards the subtree), which also releases the
 matching GPU texture.
 
+## Performance
+
+A canvas is redrawn by the script, not by the engine, so its cost is per drawing
+call. With many elements the hot paths are deliberately branch-light:
+
+- a solid, opaque `fillRect` is a byte store into the bitmap (fractional edges
+  still take the anti-aliased path), and `clearRect` over the whole bitmap is a
+  single `memset`;
+- path coverage is rasterised with a per-row **active-edge list**, and only the
+  **covered span of each row** is materialised — a thin diagonal stroke costs
+  its own pixels, not its bounding box;
+- one `stroke()` batches all of its segment quads, joins and caps into a single
+  non-zero fill instead of one coverage pass per piece (each piece's winding is
+  normalised first, so overlapping pieces cover rather than cancel);
+- `fillText` shares the shaped-run cache with layout (`text_cache.cpp`) and uses
+  a bounded two-generation glyph bitmap cache (`text_glyph_cache.cpp`);
+- `drawImage` at integer offsets with no scaling copies one texel per pixel
+  instead of running the bilinear sampler.
+
+The bitmap reaches the screen through a **dirty rectangle**: every draw unions
+its device-space bounds, and the renderer copies only that region into the
+canvas texture. All of a frame's canvas and video uploads share the frame's one
+upload command buffer, so K animated canvases cost one submit rather than K.
+`getImageData` always reads the CPU bitmap, so it is unaffected.
+`tests/e2e/gui-draw-perf.test.ts` measures the multi-element paths and pins the
+counter behaviour (one upload per frame, only the dirty bytes).
+
 ## Supported API
 
 State and transforms: `save` / `restore` (which restore the transform, line
@@ -79,34 +145,43 @@ canvas order: `translate(x, y); rotate(a)` rotates around the translated origin.
 
 Styles and settings: `fillStyle` / `strokeStyle` (CSS colors understood by the
 cascade's color parser, or a `CanvasGradient`), `lineWidth`, `globalAlpha`,
+`globalCompositeOperation`, `shadowColor` / `shadowBlur` / `shadowOffsetX` /
+`shadowOffsetY`, `imageSmoothingEnabled` / `imageSmoothingQuality`,
 `lineCap` (`butt`/`round`/`square`), `lineJoin` (`miter`/`round`/`bevel`),
 `miterLimit`, `lineDashOffset`, `font` (a CSS font shorthand resolving to
 family, size and bold/italic — default `10px sans-serif`), `textAlign`
 (`start`/`left`, `center`, `right`/`end`) and `textBaseline` (`alphabetic`,
 `top`, `middle`, `bottom`, `hanging`, `ideographic`). Reading a property returns
 the value last assigned; assigning an unparseable color keeps the previous one.
+`imageSmoothingEnabled` defaults to `true` (bilinear sampling);
+`imageSmoothingQuality` reports `low`, `medium` or `high` and selects the same
+bilinear filter in this backend.
 
 Gradients: `createLinearGradient(x0, y0, x1, y1)` and
 `createRadialGradient(x0, y0, r0, x1, y1, r1)` return a `CanvasGradient` with
 `addColorStop(offset, color)`. Stops stay live, so a stop added after
 `fillStyle = gradient` affects later fills, and the `fillStyle`/`strokeStyle`
-getter returns the same gradient handle. Radial gradients interpolate by
-distance from the **outer** circle's centre (`x1, y1`), so `x0`/`y0` are
-currently ignored: use concentric circles (`x0 == x1`, `y0 == y1`).
+getter returns the same gradient handle. A radial gradient is the general
+two-circle cone: the colour at a point is resolved from the interpolated circle
+(`centre = c0 + t·(c1 − c0)`, `radius = r0 + t·(r1 − r0)`), so an offset inner
+circle and different radii behave like a browser's. A point inside the inner
+circle samples stop 0.
 
 Paths: `beginPath`, `closePath`, `moveTo`, `lineTo`, `rect`, `roundRect`,
 `arc`, `ellipse`, `quadraticCurveTo`, `bezierCurveTo`, then
 `fill(fillRule?)` / `fill(path, fillRule?)` (multi-loop; `"nonzero"` or
-`"evenodd"`) or `stroke(path?)`. Bezier and quadratic segments are flattened
-into line segments; arcs and ellipses are flattened too. `roundRect` accepts a
-single radius number or the CSS radius list (`[all]`, `[tl, br]`,
+`"evenodd"`), `stroke(path?)`, `clip(path?, fillRule?)` and the
+`isPointInPath`/`isPointInStroke` hit tests. Bezier and quadratic segments are
+flattened into line segments; arcs and ellipses are flattened too. `roundRect`
+accepts a single radius number or the CSS radius list (`[all]`, `[tl, br]`,
 `[tl, tr, br]`, `[tl, tr, br, bl]`, numbers or `{ x, y }` pairs; corners are
 drawn circular).
 
 `Path2D` is implemented with the same path commands (`moveTo`, `lineTo`,
 `closePath`, `rect`, `roundRect`, `arc`, `ellipse`, `quadraticCurveTo`,
-`bezierCurveTo`, `addPath`) and can be passed to `fill`/`stroke`, so a path can
-be built once and replayed under different transforms.
+`bezierCurveTo`, `addPath`) and can be passed to `fill`/`stroke`/`clip` and the
+`isPointIn*` hit tests, so a path can be built once and replayed under different
+transforms.
 
 Rectangles: `clearRect`, `fillRect`, `strokeRect`.
 
@@ -129,35 +204,43 @@ Images: `drawImage(source, …)` in the 3-argument (`dx, dy`), 5-argument
 (`dx, dy, dw, dh`) and 9-argument (`dx, dy, dw, dh, sx, sy, sw, sh`; this
 engine's 9-argument form is destination-first) forms. A full affine transform
 (rotation/skew/scale) is honoured: the destination rectangle becomes a
-parallelogram and every device pixel is inverse-mapped to the source rectangle
-(nearest-neighbour). `source` may be an `<img>` element (decoded through the image module) or another
-`<canvas>` element (its current bitmap). Sampling is nearest-neighbour, so a
-large upscale of a small source is blocky — fine for icons and pixel art, not a
-photo pipeline.
+parallelogram and every device pixel is inverse-mapped to the source rectangle.
+`source` may be an `<img>` element (decoded through the image module), another
+`<canvas>`, an `OffscreenCanvas`, or an `ImageBitmap`. Sampling is bilinear when
+`imageSmoothingEnabled` is `true` (the default) and nearest-neighbour when it is
+`false`.
 
 Test hook: `getImageData(x, y, w, h)` copies a region to
 `{ width, height, data }` where `data` is a row-major RGBA8 byte array.
 Out-of-bounds pixels are transparent.
 
-Patterns: `createPattern(source, repetition?)` accepts an `<img>` or another
-`<canvas>` and tiles it in user space (`repeat`, `repeat-x`, `repeat-y`,
-`no-repeat`), so the tiles follow the current transform. Assign the result to
-`fillStyle`/`strokeStyle`; assigning a colour replaces it.
+Patterns: `createPattern(source, repetition?)` accepts an `<img>`,
+`<canvas>`, `OffscreenCanvas` or `ImageBitmap` and tiles it in user space
+(`repeat`, `repeat-x`, `repeat-y`, `no-repeat`), so the tiles follow the
+current transform. Assign the result to `fillStyle`/`strokeStyle`; assigning a
+colour replaces it.
 
 Image data and export: `createImageData(width, height)` allocates a blank
 `{ width, height, data }`, and `putImageData(imageData, dx, dy[, dirtyX, dirtyY,
 dirtyWidth, dirtyHeight])` copies bytes straight into the bitmap (no transform,
-blending or `globalAlpha`). `canvas.toDataURL(type?)` exports a PNG data URL and
-`canvas.toBlob(callback, type?)` delivers a Blob-shaped `{ type, size }` from a
-microtask (the bytes are on `__xt_gui_blob_data`; there is no
-`URL.createObjectURL`).
+blending, clip or `globalAlpha`). `canvas.toDataURL(type?)` exports a PNG data
+URL and `canvas.toBlob(callback, type?)` delivers a Blob-shaped `{ type, size }`
+from a microtask (the bytes are on `__xt_gui_blob_data`; there is no
+`URL.createObjectURL`). `OffscreenCanvas.convertToBlob()` resolves to the same
+shape and `transferToImageBitmap()` snapshots the bitmap.
+
+CSS backgrounds: `background-image: url(...)` accepts a file path or a `data:`
+URL, so a canvas can be used as a CSS background by exporting it first
+(`element.style.backgroundImage = "url(" + canvas.toDataURL() + ")"`). An image
+layer is stretched to the element's border box; `background-size`,
+`background-position` and tiling are not modelled.
 
 ## Not implemented
 
-Shadows, `clip()`, `globalCompositeOperation`, `isPointInPath`, `drawImage` with
-an image smoothing toggle, `<canvas>` as a CSS `background-image`, and offscreen
-canvases (`OffscreenCanvas`, `transferControlToOffscreen`).
-Radial gradients ignore the inner circle's offset.
-
+Smoothing quality has one filter (bilinear) on this backend. Offscreen canvases
+support the 2D context only (a WebGL context needs a DOM element for its
+texture table). Text under a rotated or skewed transform places glyphs on the
+transformed baseline but does not rotate the glyph bitmaps, and `strokeText`
+fills with the stroke style rather than outlining.
 See also [Media](./media.md) for the image/video/audio decode stack that
 `drawImage` and the texture upload share.

package/doc/gui/known-issues.md

@@ -11,16 +11,17 @@
   glslang — consumed directly by the Vulkan backend, or cross-compiled to MSL by
   the bundled SPIRV-Cross for Metal — and the drawing buffer is an offscreen
   colour texture that the page composites without a readback. WebGL 2 adds VAOs,
-  instancing, integer attributes, sampler objects, `texStorage2D` and buffer
-  copies. Uniform blocks, transform feedback, cube maps, 3D textures,
-  float/depth textures, compressed textures, multiple render targets,
-  `blitFramebuffer`, MSAA and stencil operations are not implemented; `clear`
-  ignores the scissor rectangle. On an SDL_GPU backend that accepts neither
-  SPIR-V nor MSL (Direct3D 12, which would need DXIL) both context kinds are
-  `null`. The `.js` asset loader now patches only three.js's shader unroller;
-  `WebGLRenderer` runs on the real backend and there is no Canvas2D fallback.
-  Shadow maps (depth textures), cube textures/environment maps and HDR render
-  targets remain unsupported.
+  instancing, integer attributes, sampler objects, `texStorage2D`, buffer copies,
+  uniform blocks, cube/3D/array textures, float/depth/compressed textures,
+  multiple render targets and scissored clears. `blitFramebuffer` copies colour
+  and depth; transform feedback, MSAA and stencil blits are not implemented
+  (SDL_GPU has no transform-feedback stage, its Metal multisample resolve is
+  unreliable, and a stencil attachment is not sampleable). On an SDL_GPU backend
+  that accepts neither SPIR-V nor MSL (Direct3D 12, which would need DXIL) both
+  context kinds are `null`. The `.js` asset loader now patches only three.js's
+  shader unroller; `WebGLRenderer` runs on the real backend and there is no
+  Canvas2D fallback. Shadow maps (comparative `sampler2DShadow` targeting depth
+  textures), cube textures/environment maps and HDR render targets are supported.
 
 
 
@@ -80,6 +81,27 @@
   not CSS properties here). Vector art that needs those has to be rasterised
   beforehand, drawn from boxes, or restricted to the supported syntax. See
   [Media](./media.md#images-m6a).
+- **Rendering is still whole-document per change.** A DOM mutation recomputes
+  the cascade and lays out the complete document again (there is no incremental
+  subtree invalidation), and a change that only affects paint (a hover colour,
+  for example) reflows too. Documents with generated content
+  (`::before`/`::after`) are not special-cased. The measured cost of each stage
+  is exposed by `win.stats()`/`XT_GUI_PERF`, which is what a follow-up would be
+  keyed off; see [Performance](./rendering.md#performance-m20).
+- **Draw calls follow painter order.** Runs only merge when they are
+  consecutive in painter order and share pipeline, clip and texture, so a list
+  whose rows alternate a background and text costs one shape run and one text
+  run per row (`drawCalls` in `win.stats()`). Reordering for fewer draw calls
+  needs an overlap-aware batcher (text may be covered by a later background) and
+  is not implemented. Measured: the 200-row perf page issues 400 draw calls and
+  spends about 0.4 ms in the draw phase, so this is a follow-up for
+  draw-call-dominated pages rather than the current bottleneck.
+- **The text shaping cache is bounded.** Two generations of up to 2 MiB of
+  glyphs / 8,192 entries hold `(face, text) -> glyphs`. A document with more
+  distinct words than that re-shapes some of them after a cache rotation;
+  `textCacheBytes`/`textShapeHits` in `win.stats()` show whether it is the
+  bottleneck. Inline `style="…"` attributes are re-parsed on each restyle of
+  the element that carries them.
 
 ## Open questions
 

package/doc/gui/rendering.md

@@ -160,3 +160,80 @@ cascades but paints nothing.
 - Layout uses these real metrics for text widths, line breaking and
   `line-height: normal`; `measureText`/`fontMetrics` expose them to tests.
 
+## Performance (M20)
+
+The engine is a retained-mode pipeline: a DOM mutation restyles the document,
+lays it out, rebuilds the display list and uploads vertex arrays; a frame that
+changes nothing does no CPU or GPU work. A document with thousands of elements
+is kept interactive by budgeting each stage, and every stage is measured. Set
+`XT_GUI_PERF=1` to print one line per frame (or `XT_GUI_PERF=<N>` for an
+aggregated line every N frames); `win.stats()` returns the same counters, which
+is what `tests/e2e/gui-perf.test.ts` asserts on.
+
+- **Cascade.** An `@media` prelude is evaluated **once per rule** per restyle
+  (it used to be parsed once per rule *and* node, which was the largest cost on
+  a large document). A sheet without `::before`/`::after` rules skips generated
+  content entirely, the declaration candidate list is reused across the
+  depth-first walk instead of allocated per element, and `:hover`/`:focus` only
+  restyle when the sheet actually has such a rule.
+- **Text.** Layout and paint share a bounded shaping cache (`text_cache.cpp`):
+  `(face, text) -> glyphs + advance`. It uses two generations of up to 2 MiB of
+  glyphs / 8,192 entries; when a generation is full the *spare* one is dropped
+  and becomes current, so the hot path has no LRU bookkeeping. A word is shaped
+  once and reused by every later layout pass and repaint that draws it. Primary
+  face lookups are cached by (family class, size) as well.
+- **Frame loop.** The media/canvas tables are reconciled with the DOM only when
+  the document changed (or on the first frame) instead of walking the tree every
+  frame. A frame presents only when something happened — a mutation, a scroll,
+  an animation frame, a transition, a new video/canvas frame, an expose/resize
+  event — so a static page performs no swapchain acquire and no draw at all.
+  An expose is the one present the window system asks for rather than the page,
+  and `exposes` counts those frames, so `presents - exposes - deferred` stays
+  the document's own work even when a window server maps the window late.
+  A frame that cannot get a swapchain image (SDL's non-blocking acquire skips a
+  frame while the GPU still holds the image, and a minimized window has none)
+  keeps its invalidation pending instead of dropping it, so the paint is
+  presented on the next frame; those presents are counted as `deferred`.
+  `XT_GUI_ALWAYS_PRESENT=1` restores the old always-present behaviour when
+  debugging a missed invalidation.
+- **Paint and upload.** The display list and the vertex staging arrays are kept
+  on the window and cleared per repaint, so their capacity survives. All of a
+  dirty frame's vertex/atlas uploads share one command buffer (one submit),
+  the geometry's staging transfer buffer is reused (cycled while the previous
+  copy may still be in flight), and paint skips the z-index sort and temporary
+  vector when no child stacks.
+- **Draw.** Consecutive ops with the same pipeline, clip and texture still merge
+  into one run, and the renderer now only re-binds a pipeline/vertex
+  buffer/scissor when it actually changes. `drawCalls`/`drawMs` in `win.stats()`
+  report the run count and its cost; they are the metric for the remaining
+  follow-up (an overlap-aware batching pass) — painter order requires
+  alternating background and text runs to stay separate until that lands.
+- **Immediate-mode surfaces.** `<canvas>` 2D and WebGL draws are script-driven,
+  so their cost is per call rather than per document change; the counters above
+  cover the retained pipeline only. `tests/e2e/gui-draw-perf.test.ts` measures
+  them: on the reference Windows x64/Vulkan machine a 1280×720 frame with 5,000
+  solid `fillRect`s, 200 eight-point strokes, 300 `fillText` runs and 200 1:1
+  `drawImage`s fell from 231ms to 158ms (fill 4.3ms, stroke 151ms, text 1.4ms,
+  image 1.6ms), and 2,000 WebGL `drawElements` calls with a per-draw matrix went
+  from 38.6ms to 27.5ms while the render passes opened per frame dropped from
+  2,001 to 1 and a 64 KiB `bufferSubData` into a 4 MiB buffer stopped
+  re-uploading the whole buffer. A 100×100 canvas redraw now uploads 40 KB
+  rather than the whole 1.2 MB bitmap. The suite asserts the counters (one
+  upload per frame, no steady-state pipeline creation, only the dirty bytes), so
+  the wall-clock numbers stay informational and a software GPU in CI is not
+  penalised.
+
+Known limits: a mutation still restyles and relayouts the **whole** document
+(there is no incremental subtree invalidation), and a paint-only change (for
+example a hover colour) currently reflows too; `win.stats()` is what a follow-up
+would be keyed off. Inline `style="…"` attributes are re-parsed on every restyle
+of the element that carries them.
+
+As a reference point, `tests/e2e/gui-perf.test.ts` builds a 200-row list (about
+1,000 elements, 400 draw runs) and prints the numbers it measured, e.g.
+`textFrame=5.2ms restyle=3.6ms layout=1.7ms paint=1.0ms upload=0.8ms draw=0.4ms`
+for a one-field `textContent` change on a Windows x64/Vulkan machine. The
+absolute values are host-specific; the test asserts the *counters* (one restyle,
+one layout, cache hits instead of shapes, no work on an idle frame), which are
+what a regression would change.
+

package/doc/gui/runtime.md

@@ -18,11 +18,26 @@ expose an explicit `run()`; **M2 uses the explicit `run()`** so the window is a
 plain native call the TypeScript program controls. Each tick it:
 
 1. pumps SDL window/input events for every window,
-2. builds/uploads the display list when it changed and renders every open
+2. reconciles the decoder/canvas tables with the DOM **only when the document
+   changed** (or on the first frame),
+3. builds/uploads the display list when it changed and renders every open
    window (clear pass + shape geometry + text geometry),
-3. calls `xt_loop_poll(0)` and `xt_drain_microtasks()` so sockets/timers and
+4. calls `xt_loop_poll(0)` and `xt_drain_microtasks()` so sockets/timers and
    `await` continuations keep making progress,
-4. repeats until all windows close or `quit()` is called.
+5. repeats until all windows close or `quit()` is called.
+
+A frame **presents only when something happened**: a DOM mutation, a scroll, a
+queued animation frame, a running transition, a new video/canvas frame, an
+expose/resize event, or the first frame. A static document therefore performs no
+swapchain acquire and no draw while the loop keeps servicing events, timers and
+promises; `XT_GUI_ALWAYS_PRESENT=1` restores the old always-present behaviour
+when debugging a missed invalidation. An expose/shown/restore event is the one
+present the *window system* asks for rather than the document, so it is counted
+as `exposes` in `win.stats()`; a present a starved frame had to postpone (no
+swapchain image was available) is counted as `deferred`, and
+`presents - exposes - deferred` is the work the page caused. `XT_GUI_PERF=1`
+prints what each frame did (see
+[Performance](./rendering.md#performance-m20)).
 
 The `xt_loop_set_main` hook remains available for hosts that want to own the
 loop themselves.

package/doc/gui/webgl.md

@@ -36,9 +36,10 @@ reports the type as well.
   `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.
@@ -89,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
@@ -108,6 +111,14 @@ 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)
 
 A `#version 300 es` source is accepted as-is apart from the version bump:
@@ -177,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
@@ -248,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
 
@@ -275,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
@@ -317,9 +337,8 @@ Canvas2D fallback is bundled any more**. Verified with three.js r160 through SDL
 `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.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.
@@ -342,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
 
@@ -490,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/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` 与布局几何。它们在之后仍可用于调试。