xbintsc 0.5.45 → 0.5.51

package/doc/gui/build.md

@@ -8,13 +8,33 @@
   `runtime/ext_media/` and is built separately.
 - `npm run gui` (`scripts/build-gui.ts`) fetches a pinned SDL3 (`SDL3_TAG`,
   default `release-3.2.10`), builds a static SDL3, fetches and builds static
-  FreeType (`FREETYPE_VERSION`) and HarfBuzz (`HARFBUZZ_VERSION`), and fetches
-  and builds static **glslang** (`GLSLANG_VERSION`, default `16.6.0`) against
-  the pinned SPIR-V headers (`SPIRV_HEADERS_VERSION`), and **SPIRV-Cross**
-  (`SPIRV_CROSS_VERSION`, default `vulkan-sdk-1.4.313.0`). glslang is the
-  runtime GLSL ES compiler behind WebGL and SPIRV-Cross turns its SPIR-V into
-  MSL for the Metal backend (see [WebGL](./webgl.md)); both are merged into the
-  archive like the other libraries. The script then compiles the engine and
+  **FreeType** (`FREETYPE_VERSION`, default `2.13.3`) and **HarfBuzz**
+  (`HARFBUZZ_VERSION`, default `10.1.0`) for the optional `shaping` feature,
+  and fetches and builds static **glslang** (`GLSLANG_VERSION`, default
+  `16.6.0`) against the pinned SPIR-V headers (`SPIRV_HEADERS_VERSION`), and —
+  **on macOS only** — **SPIRV-Cross** (`SPIRV_CROSS_VERSION`, default
+  `vulkan-sdk-1.4.313.0`). glslang is the runtime GLSL ES compiler behind WebGL
+  and SPIRV-Cross turns its SPIR-V into MSL for the Metal backend (see
+  [WebGL](./webgl.md)); both are merged into the archive like the other
+  libraries. Metal is the only SDL_GPU backend that consumes MSL, so on
+  Windows/Linux the script neither fetches nor merges SPIRV-Cross:
+  `webgl_msl.cpp` compiles to nothing there and the ~2.5 MiB it contributes
+  would be unreachable. The default text path uses the bundled
+  **stb_truetype** (`runtime/ext_gui/stb_truetype.h`); HarfBuzz + FreeType are
+  only extracted when the `shaping` feature is active.
+  Every library (SDL3, FreeType, HarfBuzz, glslang, SPIRV-Cross and the engine)
+  is compiled with `-ffunction-sections -fdata-sections`, and SDL is configured
+  without the subsystems the engine never calls (`SDL_JOYSTICK`, `SDL_HAPTIC`,
+  `SDL_SENSOR`, `SDL_CAMERA`, `SDL_RENDER`, `SDL_OPENGL`/`SDL_OPENGLES`,
+  `SDL_OFFSCREEN`, `SDL_HIDAPI`). HarfBuzz omits the APIs the shaping backend
+  never uses (`HB_NO_DRAW`/`PAINT`/`COLOR`/`NAME`/`STYLE`/`METRICS`/…, while
+  keeping `CFF`/`OPEN`/`VAR` for OTF and variable fonts) and is built with
+  `HB_NO_PRAGMA_GCC_DIAGNOSTIC_ERROR`, because `src/hb.hh` raises its warning
+  set to errors and two lean defines leave macOS/CoreText helpers unreferenced
+  (`HB_NO_MMAP` and `HB_NO_OT_FONT_GLYPH_NAMES`). The linker then drops
+  the unreachable functions (`--gc-sections`, `-dead_strip`, or link.exe's
+  default `/OPT:REF`). The
+  script then compiles the engine and
   merges everything into `runtime/lib/<os>-<arch>/gui.a` (or
   `gui.lib` with the MSVC ABI on Windows), same convention as `core.a`,
   statically bundling all three. The merge uses `libtool` on macOS and
@@ -25,13 +45,17 @@
   minimal static build with only the demuxers/parsers/decoders the media
   elements need, compiles `runtime/ext_media/media.cpp` against it and merges
   everything into `runtime/lib/<os>-<arch>/media.a` (`media.lib` with the MSVC
-  ABI on Windows). `gui.a` does **not** link FFmpeg: a program enables playback
-  explicitly with `--ext media`.
+  ABI on Windows). `gui.a` does **not** link FFmpeg: the compiler selects the
+  `media` link feature for a program that may play media and only then links
+  `media.a` (see [Link features](#link-features)).
 - `src/extensions/gui/index.ts` exposes the engine archive through
   `nativeObjects()` (via `findRuntimeLibrary`, so `.a`/`.lib` both work) and the
-  OS frameworks through `linkerFlags()`. `src/extensions/media/index.ts` does
-  the same for `media.a`/`media.lib` and compiles the registration bridge
-  (`runtime/ext_media/media_bridge.c`) as a normal runtime source.
+  OS frameworks through `linkerFlags()`. Its `linkFeatures()` (in
+  `src/extensions/gui/features.ts`) declares `media`, `gpu`, `images`, `shaping` and `webgl`; the driver
+  compiles their bridges only when a feature is active.
+- glslang (and SPIRV-Cross on macOS) is merged into `gui.a` like SDL3, but the
+  engine reaches it only through the `gpu` feature's dispatch table. A program
+  that never compiles GLSL does not extract those archive members.
 - `scripts/build-gui.ts` compiles with the *same* clang the driver resolves
   (`src/driver/toolchain-provider.ts`); on Windows that is the MSVC-targeting
   LLVM bundled with Visual Studio, and its sibling `clang++`/`llvm-ar` are used
@@ -59,11 +83,12 @@
 - CI builds `gui.a`/`gui.lib` and `media.a`/`media.lib` before assembling the
   release archive so they ship inside `runtime/lib/<slug>/` (the release tarball
   copies the whole `runtime/` tree). The same folders are packed into the
-  optional `@xbintsc/<slug>` npm package, so `--ext gui`/`--ext media` work from
+  optional `@xbintsc/<slug>` npm package, so `--ext gui` (with automatic
+  `media`/`gpu`/`images`/`shaping`/`webgl` selection) works from
   an npm install on the hosts the release builds for. The archives are built and
   the examples are run on Linux (under Xvfb, with the lavapipe software Vulkan
   driver) and macOS;
-  the Windows x64 job builds both archives and links a `gui,media` program, so
+  the Windows x64 job builds both archives and links a `gui` program, so
   the MSVC build is validated even though *running* the examples there stays
   provisional (the hosted runner has no GPU/Vulkan driver). The macOS run is
   provisional too: the Intel runner's virtualised GPU lacks
@@ -82,8 +107,9 @@
 - The existing cache fingerprint already hashes `nativeObjects()` contents and
   `runtimeSources()` content, so rebuilding either archive invalidates cached
   binaries automatically.
-- CMake build trees live *next to* their sources (`vendor/sdl-build`,
-  `vendor/freetype-build`, `vendor/harfbuzz-build`), never inside them: a
+- CMake build trees live *next to* their sources (`vendor/sdl-build-lean`,
+  `vendor/freetype-build-lean`, `vendor/harfbuzz-build-lean`,
+  `vendor/glslang-build-lean`, `vendor/spirv-cross-build-lean`), never inside them: a
   `CMakeCache.txt` records the machine it was configured on, and SDL's video
   backends are `option()`s, so the first configure to run wins. A cached
   `vendor/SDL` tree that also carried `build/` therefore restored one machine's
@@ -95,6 +121,96 @@
   `xbintsc_SKIP_HEADER_CHECK=1` when they live under a prefix that check does
   not know).
 
+## Link features
+
+`gui` is the only user-facing extension, but two heavy halves are **optional link
+features** selected per program:
+
+| Feature | What it links | Selected when the program may use it |
+| --- | --- | --- |
+| `media` | `media_bridge.c` + `media.a` (FFmpeg) | an HTML `<video>`/`<audio>` tag, `createElement("video"/"audio")`, `new Audio()`, `decodeAudioData`, or runtime-built markup |
+| `gpu` | `gpu_bridge.c` (the implementation is already in `gui.a`) | a `getContext("webgl"/"webgl2"/"experimental-webgl")` (or a kind decided at run time), any `webgl` string, `mix-blend-mode`/`mixBlendMode`, or runtime-built markup |
+| `images` | `image_bridge.c` (the implementation is already in `gui.a`) | `<img>`, inline `<svg>`, `background-image`/`url(...)`, a `.svg` path, `drawImage`/`createImageBitmap`/`Image`, or runtime-built markup |
+| `shaping` | `text_bridge.c` (the implementation is already in `gui.a`) | non-ASCII text (CJK/Cyrillic/Greek/…), an escaped/entity codepoint, or runtime-built markup |
+| `webgl` | `webgl_bridge.c` (the implementation is already in `gui.a`; requires `gpu`) | a WebGL `getContext(...)`, a `webgl` string, or runtime-built markup |
+
+The driver scans the bundled AST (`src/driver/usage.ts`): every string literal
+(including imported `.html` and the CSS inlined from it), identifiers and
+property names, each `getContext(...)` kind, and whether HTML/CSS can be built
+from data the compiler cannot see. Simple `const` aliases are resolved;
+anything unresolved makes the program “dynamic markup” and enables the optional
+features conservatively.
+
+When a feature is active, the driver compiles its C **bridge only for that
+build** and links it before `gui.a`:
+
+- `media` → `runtime/ext_media/media_bridge.c`; its constructor installs the
+  decoder table and references `xt_media_backend_*`, which is what extracts the
+  FFmpeg members from `media.a`.
+- `gpu` → `runtime/ext_gui/gpu_bridge.c`; its constructor calls
+  `xt_gpu_feature_register` in `gpu_feature.cpp`, which installs the
+  `XtGpuShaderApi` table and references `compile_glsl` / `cross_compile_msl` /
+  the reflection helpers, extracting glslang (and SPIRV-Cross on macOS).
+- `images` → `runtime/ext_gui/image_bridge.c`; its constructor installs
+  `XtImageApi` via `image_feature.cpp`, which references stb_image and NanoSVG.
+  Layout, paint, the canvas `drawImage` path and the app-icon path call through
+  that table, so a text-only page links neither decoder.
+- `shaping` → `runtime/ext_gui/text_bridge.c`; its constructor installs
+  `TextApi` via `text_hb.cpp`, which references HarfBuzz and FreeType. Without
+  it the engine uses the built-in stb_truetype backend, so a Latin-only page
+  links neither library.
+- `webgl` → `runtime/ext_gui/webgl_bridge.c`; its constructor installs
+  `XtWebglApi` via `webgl_feature.cpp`, which references the WebGL context and
+  DOM bindings. The core reaches `getContext`, the canvas width/height setters,
+  `createImageBitmap`, the host types and the renderer through that table, so a
+  page with no WebGL links none of `webgl_*`/`dom_api_webgl*`.
+
+A bridge is the “strong reference” that makes the linker search the archive; with
+no bridge, the engine's table stays null and the implementation members are never
+extracted. That is why the large libraries can stay in the existing archives
+without a new package layout.
+
+Overrides: `--feature media,gpu,images,shaping,webgl` (or `all`) forces a
+feature on; `--no-feature media` keeps it out even when detection finds a use.
+`webgl` requires `gpu`, and the resolver activates both together. An app icon
+forces `images` because the icon is decoded through the same pipeline. `--ext media`
+is a deprecated alias for `--ext gui --feature media`. If an auto-detected
+feature's archive is missing, the build warns and continues (the element/context
+degrades as documented); a forced feature makes it an error.
+
+> Detection is static by design. A page that builds HTML/CSS from `fetch`,
+> `readFileSync` or other runtime data should pass `--feature all` (or the
+> specific feature). `--verbose` prints the selected set, e.g.
+> `xbintsc: link features: none`.
+
+### Binary size
+
+The lean build is what makes a DOM-only program small. On Windows x64 a
+`hello`-sized program drops from roughly 6.4 MiB to about 3.1 MiB once SDL is
+configured as above, function/data sections let `/OPT:REF` discard what the page
+never reaches, the WebGL/images link features stay off, and text uses the
+bundled stb_truetype instead of HarfBuzz + FreeType. The remaining weight is
+mostly the static CRT, the lean SDL (~1 MiB), stb_truetype (~0.1 MiB), and the
+DOM/CSS/layout/paint engine itself (~1.2 MiB). Linux and macOS use their own
+linker sections (`--gc-sections`/`-dead_strip`) and differ somewhat, but the
+relative ranking is the same.
+
+WebGL and images/SVG are link features (roughly 0.4 MiB of WebGL context/DOM
+code and 0.23 MiB of stb_image/NanoSVG that a DOM-only page does not link).
+Canvas2D, Web Audio and the `mix-blend-mode` compositor are not gated yet; a
+program that uses none of them still pays for their API surface (roughly
+0.1–0.2 MiB each).
+
+The text trade-off is deliberate. The default backend is stb_truetype: only
+TrueType outlines and a per-codepoint mapping plus the font's `kern` table, so
+CFF/OTF and variable fonts, OpenType ligatures and complex-script shaping
+(Arabic/Indic/Thai) are not available. The fallback chain still selects another
+face for codepoints the primary lacks. Selecting the optional **`shaping`**
+feature (automatically for non-ASCII text, or with `--feature shaping`) links
+HarfBuzz + FreeType back in (~1.2 MiB) and restores full OpenType shaping and
+CFF/OTF/variable-font support. A Latin-only DOM page therefore stays near
+3.1 MiB; a Chinese/complex-script page is closer to 4.3 MiB.
+
 ## Running the example
 
 ```sh
@@ -133,10 +249,11 @@ its README for controls and the geometry report it prints.
 
 `media.ts` (with `media.html`) demonstrates `<video>`/`<audio>`: it overlays a
 CSS progress bar on the video and drives playback with `play()` / `pause()` /
-`currentTime` / `volume`. It needs the separate `media` extension, so build and
-enable both. Media `src` paths resolve relative to the process working
+`currentTime` / `volume`. The compiler sees the elements in `media.html` and
+links the `media` feature automatically; build `media.a` once with
+`npm run media`. Media `src` paths resolve relative to the process working
 directory, so run it from the repository root:
-`xbintsc run examples/gui/media.ts --ext gui,media`.
+`xbintsc run examples/gui/media.ts --ext gui`.
 
 Set `XT_GUI_AUTOCLOSE_MS=<n>` to close all windows after `n` milliseconds,
 which the e2e test (`tests/e2e/gui-*.test.ts`) uses to run headlessly.

package/doc/gui/canvas.md

@@ -191,7 +191,7 @@ non-finite entries are ignored, an all-zero list means a solid line).
 
 Text: `measureText(text)` (returns `{ width }`), `fillText(text, x, y,
 maxWidth?)` and `strokeText(text, x, y, maxWidth?)`. Text is shaped with
-HarfBuzz and rasterised with FreeType (the same stack as HTML text) at the
+stb_truetype (shaped and rasterised) (the same stack as HTML text) at the
 transform's approximate scale. A positive `maxWidth` condenses advances and
 glyph bitmaps horizontally so the run is at most that wide (as the canvas API
 specifies) instead of being ignored.

package/doc/gui/known-issues.md

@@ -22,6 +22,16 @@
   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.
+- **Comparative samplers can miscompile on Intel Macs.** On an Intel GPU (seen
+  on Intel Iris Plus Graphics with macOS 26), the Metal shader compiler drops a
+  fragment function that calls `sample_compare`: the draw produces no pixels at
+  all, so `texture(sampler2DShadow, …)` reads black and shadow maps disappear.
+  The MSL is correct (`depth2d<float>` + `sample_compare`), the sampler carries
+  the comparison op, and the same program renders correctly once Metal GPU
+  shader validation is enabled — running with `MTL_SHADER_VALIDATION=1` makes
+  `tests/e2e/gui-webgl2-shadow-sampler.test.ts` pass on such a machine. That
+  points at the driver's shader compiler rather than the engine, so the
+  workaround is the environment variable; other Apple GPUs may not show it.
 
 
 
@@ -111,6 +121,22 @@
   bottleneck. Inline `style="…"` attributes are re-parsed on each restyle of
   the element that carries them.
 
+- **Text shaping is a simple shaper.** stb_truetype handles Latin/CJK/Cyrillic/
+  Greek with basic `kern` and per-codepoint fallback, but it does not run
+  OpenType ligatures or complex-script shaping (Arabic/Indic/Thai), and it only
+  accepts TrueType outlines (no CFF/OTF or variable fonts). Colour emoji are not
+  rendered as colour. This is the price of the ~3 MiB DOM-only binary; the
+  optional `shaping` feature restores HarfBuzz + FreeType (and full
+  complex-script shaping).
+- **Link-feature detection is static.** `media`/`gpu`/`images`/`shaping`/`webgl` are selected from the
+  bundled HTML/CSS/TS (including imported `.html` and the CSS inlined from it).
+  A page that builds markup or CSS from runtime data (`fetch`, `readFileSync`,
+  a value returned by a function) cannot be seen; the scanner falls back to
+  enabling both when it can prove the sink is dynamic, but an opaque value that
+  it cannot classify needs an explicit `--feature media`/`gpu`/`images`/`shaping`/`webgl` (or `all`).
+  `--verbose` prints the selected set. See
+  [Link features](./build.md#link-features).
+
 ## Open questions
 
 - Whether Linux ships X11, Wayland, or both in the first cut. (Decision:
@@ -130,7 +156,8 @@
 - Windows: an MSVC-compatible `gui.lib` (COFF objects + `ar -M`/`llvm-ar`) is
   produced by `scripts/build-gui.ts`. The Windows x64 CI job builds it with the
   Visual Studio toolchain (`.github/actions/vs-toolchain` imports `vcvarsall`
-  and uses VS's bundled LLVM), links a `gui,media` program, and ships it in the
+  and uses VS's bundled LLVM), links a `gui` program that exercises the `media`
+  link feature, and ships it in the
   x64 release. *Running* the examples on the hosted runner stays provisional
   because it has no GPU/Vulkan driver (SDL_GPU selects the **Vulkan** backend
   there, so no DXIL/`dxc` toolchain is needed). Windows arm64 still skips both
@@ -139,12 +166,14 @@
 - **Windows: x64 builds in CI, arm64 and runtime validation stay provisional.**
   `media.lib` is produced by `scripts/build-media.ts` with FFmpeg's MSVC
   toolchain (`--toolchain=msvc --cc=clang-cl`) so its COFF objects and static CRT
-  match `gui.lib`, and `--ext media` links and plays there. Building it needs a
+  match `gui.lib`, and the auto-selected `media` feature links and plays there.
+  Building it needs a
   POSIX shell to run FFmpeg's `configure` and GNU make; the shell comes from Git
   for Windows (already needed to clone SDL3), and make is a native GNU make
   (Chocolatey's `make`, or `xbintsc_MAKE`). CI installs make explicitly,
   builds `gui.lib` + `media.lib` on Windows x64 (using the same Visual Studio
-  `vcvarsall` + bundled LLVM as a local build), links a `gui,media` program, and
+  `vcvarsall` + bundled LLVM as a local build), links a `gui` program that
+  exercises the feature, and
   ships both archives in the Windows x64 release; the example *run* remains
   provisional because hosted runners have no GPU/Vulkan driver. Windows arm64
   still skips both archives, and `<video controls>` is likewise deferred — the

package/doc/gui/layout.md

@@ -22,7 +22,7 @@ with absolute (viewport-relative) geometry:
   Each line shrinks to the band left free by any floats (`float: left|right`)
   that overlap it, so later lines wrap around them.
   Each text fragment remembers the run it covers, so paint can shape it. Text is
-  measured with the HarfBuzz/FreeType stack (see [Text stack](./rendering.md#text-stack-m4b)).
+  measured with the stb_truetype stack (see [Text stack](./rendering.md#text-stack-m4b)).
 - **Flexbox** — `row`/`column` (and the `-reverse` variants) with `gap`,
   `flex-basis`/`flex-grow`/`flex-shrink`, `justify-content` and `align-items`
   (including `stretch` when the cross size is definite). `flex-wrap: wrap`

package/doc/gui/media.md

@@ -74,8 +74,9 @@ clip paths are not rendered (see [Known issues](./known-issues.md)).
 
 ## Video & audio (M13)
 
-Media playback is split across two extensions so a GUI program does not pay for
-a decoder it never uses:
+Media playback is split inside the `gui` extension so a GUI program does not pay
+for a decoder it never uses. Decoding is an optional **`media` link feature**,
+not a separate extension:
 
 - **`gui`** (`gui.a`/`gui.lib`) owns the `<video>`/`<audio>` elements, the DOM
   API, the renderer integration and the SDL audio sink, but contains **no
@@ -85,13 +86,18 @@ a decoder it never uses:
 - **`media`** (`media.a`, or `media.lib` with the MSVC ABI on Windows;
   `runtime/ext_media/`) is the optional decoder backend:
   `runtime/ext_media/media.cpp` wraps a statically vendored **FFmpeg** build,
-  and `runtime/ext_media/media_bridge.c` registers it with the engine. Enable it
-  with `--ext media` (or `--ext gui,media`). `media` requires `gui`; the
-  registry rejects the combination in the wrong order.
+  and `runtime/ext_media/media_bridge.c` registers it with the engine. The
+  compiler selects the feature when the program may use it (a `<video>`/`<audio>`
+  element in imported HTML, `createElement("video"/"audio")`, `new Audio()`,
+  `decodeAudioData`, or runtime-built markup) and only then compiles the bridge
+  and links `media.a`. `--feature media` forces it and `--no-feature media`
+  keeps it out; see [Link features](./build.md#link-features).
 
-Without the `media` extension the element still exists and its DOM API is
+Without the feature the element still exists and its DOM API is
 callable, but opening a source fails and fires `error`. The same happens on any
-host where the archive has not been built (run `npm run media`); Windows is no
+host where the archive has not been built (run `npm run media`) — an
+auto-detected feature with no archive produces a build warning and degrades this
+way, while `--feature media` fails the build. Windows is no
 longer special: `media.lib` is FFmpeg compiled with clang-cl for the MSVC ABI,
 so it links against `gui.lib` and plays normally. There is no WebView and no
 platform media framework in the path either way.

package/doc/gui/rendering.md

@@ -153,33 +153,33 @@ compiler here — keep painting the group with ordinary source-over blending.
 
 ## Text stack (M4b)
 
-`runtime/ext_gui/text.{h,cpp}` wraps **HarfBuzz** (shaping) and **FreeType**
-(metrics + eventual rasterisation). Both are built statically and linked into
-`gui.a` by `scripts/build-gui.ts`.
+`runtime/ext_gui/text.{h,cpp}` is the front-end; it dispatches through a small
+backend table. The default backend is the bundled **stb_truetype**
+(`text_stb.cpp`, `runtime/ext_gui/stb_truetype.h`). The optional **`shaping`**
+link feature installs `text_hb.cpp`, a HarfBuzz + FreeType backend, and is
+selected automatically for non-ASCII text.
 
 - Fonts are resolved from well-known system paths (Helvetica/Arial on macOS,
   DejaVu/Liberation on Linux, Segoe UI/Arial on Windows), overridable with
   `XT_GUI_FONT` (and `XT_GUI_FONT_MONO`), and cached per `(family class, size)`.
   Only regular upright faces are used for now; weight/italic selection is a
   later refinement.
-- The default candidates prefer a **CJK-capable** face (Microsoft YaHei on
-  Windows, PingFang/STHeiti on macOS, Noto Sans CJK/WenQuanYi on Linux) before
-  the Latin-only ones. Setting `XT_GUI_FONT` to a Latin-only face gives its
-  Latin design instead (at the cost of CJK coverage).
+- The default candidates prefer a **CJK-capable TrueType/TTC** face (Microsoft
+  YaHei on Windows, PingFang/STHeiti on macOS, Noto Sans CJK/WenQuanYi on Linux)
+  before the Latin-only ones. A candidate that stb_truetype cannot parse (for
+  example a CFF/OTF collection) is skipped in favour of the next one.
 - **Codepoints the primary face lacks fall back to another face.** The engine
   keeps a small fallback chain — the platform's symbol face (Segoe UI Symbol,
   Apple Symbols, Noto Sans Symbols, DejaVu Sans) first, then the other family
   class — and resolves each codepoint to the first face in it that has the
   glyph. The run is shaped in segments, one per face, so a mixed run (Latin
   plus an arrow, box-drawing or geometric shape, or Latin inside CJK) draws
-  every glyph instead of dropping the missing ones as `.notdef`. This is what
-  makes a character such as `▮`/`▯` (U+25AE/U+25AF, used by the pelican-bike
-  speed bar) visible even when the CJK primary has no geometric shapes. Each
-  shaped glyph carries its face (`ShapedGlyph::font`) so the renderer rasterises
-  it from the right atlas entry; `xt_text_scale` maps a face to the display's
-  scale factor.
-- `xt_text_measure_width` shapes the run with HarfBuzz (so kerning and
-  ligatures are honoured), `xt_text_metrics` returns FreeType's ascent /
+  every glyph instead of dropping the missing ones as `.notdef`. Each shaped
+  glyph carries its face (`ShapedGlyph::font`) so the renderer rasterises it
+  from the right atlas entry; `xt_text_scale` maps a face to the display's scale
+  factor.
+- `xt_text_measure_width` maps each codepoint to a glyph and adds its advance
+  plus the font's `kern` table; `xt_text_metrics` returns stb_truetype's ascent /
   descent / normal line height. When no font file can be found the module falls
   back to a deterministic per-byte approximation, so layout still works.
 - `xt_text_shape_run` returns positioned glyphs and `xt_text_rasterize` renders
@@ -189,6 +189,15 @@ compiler here — keep painting the group with ordinary source-over blending.
 - Layout uses these real metrics for text widths, line breaking and
   `line-height: normal`; `measureText`/`fontMetrics` expose them to tests.
 
+Shape trade-off: the default is a simple shaper, not a full OpenType engine. It
+handles Latin/CJK/Cyrillic/Greek, basic kerning and per-codepoint fallback, but
+it does not run ligatures or complex-script shaping (Arabic/Indic/Thai), and
+stb_truetype only accepts TrueType outlines, not CFF/OTF or variable fonts. The
+choice keeps a DOM-only binary near 3 MiB. The optional **`shaping`** link
+feature installs the HarfBuzz + FreeType backend instead (about 1.2 MiB) and
+restores full OpenType shaping and CFF/OTF/variable-font support; it is selected
+automatically for non-ASCII text and can be forced with `--feature shaping`.
+
 ## Performance (M20)
 
 The engine is a retained-mode pipeline: a DOM mutation restyles the document,
@@ -211,6 +220,14 @@ is what `tests/e2e/gui-perf.test.ts` asserts on.
   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.
+- **No-op writes.** `textContent` and `style.<property>` do nothing when the
+  node already shows that value: the document is not dirtied, so no restyle,
+  relayout, repaint or upload follows. A HUD that assigns the same clock string,
+  the same bar width or the same transform every frame therefore costs nothing —
+  before this each assignment rebuilt a text node (an allocation, and one the
+  collector then had to sweep) or re-serialized the inline style, and dirtied
+  the document for a full restyle. `classList` and `removeAttribute` already
+  behaved this way; `setAttribute` still dirties unconditionally.
 - **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,

package/doc/gui/runtime.md

@@ -55,6 +55,11 @@ that case with a single 16 ms `xt_set_timeout` tick:
   queued animation-frame callbacks before layout, so a page can stop itself),
 - it re-arms **only while callbacks remain**, so an idle page lets the event
   loop drain and the process exit — the browser-tab lifecycle;
+- it schedules the next tick for *frame start + 16 ms*, not 16 ms after the
+  frame finished: the frame's own duration is not added to the interval, so a
+  10 ms frame runs at a 16 ms period instead of 26 ms, and a page slower than
+  16 ms runs as fast as it can instead of falling a frame's worth of time
+  further behind on every frame;
 - it stands aside while `xt_gui_run_active()` is set (the program called
   `run()`), so the same window is not rendered twice per tick;
 - `XT_GUI_AUTOCLOSE_MS=n` makes the pump quit after `n` milliseconds, which is

package/doc/gui/webgl.md

@@ -48,8 +48,19 @@ reports the type as well.
   `readPixels` flips rows back, and the compositor sees an upright texture.
 - A fixed-function state change (`blendFunc`, `depthFunc`, `cullFace`,
   `colorMask`, …) changes which `SDL_GPUGraphicsPipeline` is needed, so
-  pipelines are created lazily per (program, vertex layout, state) and cached on
-  the program.
+  pipelines are created lazily and cached on the program. The key is the
+  *content* of the draw: the program, the primitive mode, a hash of the vertex
+  layout (attribute locations, formats, offsets, buffer pitches and input rates),
+  the reflected fixed-function state and the attachment formats. It deliberately
+  excludes the context's monotonic version counters (`attribs_version_`,
+  `framebuffer_version_`) and the GPU buffer handles: those advance on every VAO
+  bind, framebuffer switch or buffer re-creation without changing the pipeline,
+  and keying on them re-created every pipeline once per frame in a scene that
+  binds several layouts per frame — three.js does, and measured 248
+  `SDL_CreateGPUGraphicsPipeline` calls per frame while the per-program cache
+  grew without bound. `tests/e2e/gui-webgl-pipeline-cache.test.ts` pins the
+  steady state: two draws with the same layout and different buffers create no
+  pipeline after the first frame.
 
 ## Shaders: GLSL ES to SPIR-V (and on to MSL)
 
@@ -283,9 +294,15 @@ format — Direct3D 12, which would need DXIL — `getContext("webgl")` and
 `getContext("webgl2")` both answer `null`; the 2D canvas and the rest of the page
 still work.
 
-glslang and SPIRV-Cross are fetched and built by `npm run gui` and merged into
-`gui.a` / `gui.lib` (see [Packaging and build](./build.md)); a program that only
-uses the 2D canvas or the DOM pays no run-time cost beyond the archive size.
+glslang is fetched and built by `npm run gui` and merged into `gui.a` /
+`gui.lib`; SPIRV-Cross is merged **on macOS only**, because no other SDL_GPU
+backend consumes MSL (see [Packaging and build](./build.md)). Both are reached
+through the optional **`gpu` link feature**: the compiler selects it when the
+program may call `getContext("webgl…")` or use `mix-blend-mode`, and only then
+does the feature bridge pull the translator members out of `gui.a`. The WebGL
+context and DOM bindings are the separate **`webgl` feature**, which requires
+`gpu`; a program that only uses the 2D canvas or the DOM links neither glslang,
+SPIRV-Cross, nor any `webgl_*` member (see [Link features](./build.md#link-features)).
 
 ## Testing
 
@@ -339,6 +356,7 @@ Canvas2D fallback is bundled any more**. Verified with three.js r160 through SDL
 Features outside this engine's subset still cannot be emulated: transform
 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
+three.js shadow maps can use the hardware depth compare on both backends (see
+[known issues](./known-issues.md) for an Intel-Mac driver caveat). A
 scene that needs transform feedback or MSAA will not render correctly;
 everything the previous Canvas2D fallback could show now goes through the GPU.