xbintsc 0.5.21 → 0.5.23

package/doc/gui/canvas.md

@@ -13,8 +13,11 @@ video frames (`renderer_image.cpp`), so the GPU scales it into the CSS box.
 
 The engine-side object is `xtgui::Canvas2D`
 (`runtime/ext_gui/canvas.{h,cpp}`) — one RGBA8 bitmap plus the 2D drawing state.
-The rasteriser lives in `canvas_raster.cpp`; the DOM bindings live in
-`dom_api_canvas.cpp`, and the per-window lifetime in `gui_canvas.cpp`.
+The rasteriser lives in `canvas_raster.cpp`, stroke geometry (caps, joins,
+dashes) in `canvas_stroke.cpp`, gradients in `canvas_gradient.cpp`, and drawing
+state parsing in `canvas_style.cpp`; the DOM bindings live in
+`dom_api_canvas.cpp` / `dom_api_canvas_extra.cpp`, and the per-window lifetime in
+`gui_canvas.cpp`.
 
 ## Getting a context
 
@@ -37,6 +40,14 @@ horizontal coverage** pass, and fills paths with the **non-zero winding rule**
 (`b == 0 && c == 0` in the transform) takes a direct coverage fast path.
 Blending is non-premultiplied source-over, scaled by `globalAlpha`.
 
+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
+back through the inverse of the current transform before sampling; this keeps a
+gradient attached to the shape when the shape is translated, scaled or rotated.
+Strokes are flattened into segment quads plus the join/cap shapes selected by
+`lineJoin`/`lineCap`; a dash pattern first splits the polyline into its "on"
+pieces, then those pieces are stroked with the same caps.
+
 Canvas pixels are **not** touched by the garbage collector: a canvas is owned by
 the window, keyed by its DOM node (the same shape as the `<video>`/`<audio>`
 decode table). It is released when the node is dropped (`loadHTML`, window
@@ -48,24 +59,39 @@ matching GPU texture.
 State and transforms: `save` / `restore` (which restore the transform, line
 width, alpha, font/text settings **and** the fill/stroke styles),
 `translate`, `rotate`, `scale`, `transform(a,b,c,d,e,f)`, `setTransform`,
-`resetTransform`.
+`resetTransform`, `getTransform` (returns an object with `a`…`f` and `is2D`).
+Transforms compose in 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), `lineWidth`, `globalAlpha`, `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.
-
-Paths: `beginPath`, `closePath`, `moveTo`, `lineTo`, `rect`, `arc`,
-`quadraticCurveTo`, `bezierCurveTo`, then `fill` (multi-loop, non-zero winding)
-or `stroke`. Bezier and quadratic segments are flattened into line segments;
-arcs are flattened too and each subpath is stroked as segment quads plus a disc
-at each joint.
+cascade's color parser, or a `CanvasGradient`), `lineWidth`, `globalAlpha`,
+`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.
+
+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`).
+
+Paths: `beginPath`, `closePath`, `moveTo`, `lineTo`, `rect`, `roundRect`,
+`arc`, `ellipse`, `quadraticCurveTo`, `bezierCurveTo`, then `fill` (multi-loop,
+non-zero winding) or `stroke`. Bezier and quadratic segments are flattened into
+line segments; arcs and ellipses are flattened too. `roundRect` accepts one
+radius number (the array form is not implemented).
 
 Rectangles: `clearRect`, `fillRect`, `strokeRect`.
 
+Dashes: `setLineDash(segments)` / `getLineDash()` / `lineDashOffset` implement
+the standard pattern rules (an odd-length list is duplicated, negative or
+non-finite entries are ignored, an all-zero list means a solid line).
+
 Text: `measureText(text)` (returns `{ width }`), `fillText(text, x, y)` and
 `strokeText(text, x, y)`. Text is shaped with HarfBuzz and rasterised with
 FreeType (the same stack as HTML text) at the transform's approximate scale.
@@ -87,12 +113,12 @@ Out-of-bounds pixels are transparent.
 
 ## Not implemented
 
-Gradients and patterns, shadows, `clip()`, `globalCompositeOperation`, line
-joins/caps/dashes/mitre, `setLineDash`, `createLinearGradient`/`createPattern`,
-`putImageData`, `createImageData`, `isPointInPath`, `getTransform`,
-`setTransform` with a `DOMMatrix`, `drawImage` with an image smoothing toggle,
-`toDataURL`/`toBlob`, `<canvas>` as a CSS `background-image`, and offscreen
-canvases (`OffscreenCanvas`, `transferControlToOffscreen`).
+Patterns (`createPattern`), shadows, `clip()`, `globalCompositeOperation`,
+`putImageData`, `createImageData`, `isPointInPath`, `setTransform` with a
+`DOMMatrix`, `drawImage` with an image smoothing toggle, `toDataURL`/`toBlob`,
+`<canvas>` as a CSS `background-image`, and offscreen canvases
+(`OffscreenCanvas`, `transferControlToOffscreen`). `roundRect` takes a single
+radius, and radial gradients ignore the inner circle's offset.
 
 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

@@ -69,12 +69,13 @@
   (`win.driver()` reports `"vulkan"`), so the archive needs no DXIL/`dxc`
   toolchain; the hosted Windows runners have no GPU/Vulkan driver, which is why
   the CI run stays provisional.
-- **Media on Windows:** the media decoders (FFmpeg) are only built and merged
-  into the POSIX `gui.a`; the Windows `gui.lib` is produced without them, so
-  `<video>`/`<audio>` are inert there (failures fire `error`). Enabling it needs
-  an MSVC-compatible FFmpeg build and is deferred until the Windows GUI path
-  itself is validated. `<video controls>` is likewise deferred — the intended
-  pattern is TS + a CSS overlay, as in `examples/gui/media.ts`.
+- **Media on Windows:** the `media` extension is POSIX-only for now. The GUI
+  engine itself builds on Windows, but without the extension `<video>`/`<audio>`
+  are inert there (an open fails and fires `error`), and `--ext media` reports an
+  actionable error instead of linking. Enabling it needs an MSVC-compatible
+  FFmpeg build and is deferred until the Windows GUI path itself is validated.
+  `<video controls>` is likewise deferred — the intended pattern is TS + a CSS
+  overlay, as in `examples/gui/media.ts`.
 - **D3D12 shaders:** the SPIR-V (Vulkan) and DXIL (Direct3D 12) blobs are built
   and embedded, so the non-Metal path no longer skips geometry. DXIL remains
   unusable on **SDL 3.2.10**: its D3D12 backend rejects any graphics pipeline

package/doc/gui/media.md

@@ -65,17 +65,31 @@ clip paths are not rendered (see [Known issues](./known-issues.md)).
 
 ## Video & audio (M13)
 
-`runtime/ext_gui/media.{h,cpp}` wraps a statically vendored **FFmpeg** build and
-`runtime/ext_gui/gui_media.cpp` connects the DOM tree to it. `<video>` and
-`<audio>` really decode and play; there is no WebView and no platform media
-framework in the path.
+Media playback is split across two extensions so a GUI program does not pay for
+a decoder it never uses:
+
+- **`gui`** (`gui.a`) owns the `<video>`/`<audio>` elements, the DOM API, the
+  renderer integration and the SDL audio sink, but contains **no FFmpeg**.
+  `runtime/ext_gui/media.{h,cpp}` declares the player interface and dispatches
+  through a table the media backend installs at startup
+  (`runtime/ext_gui/media_api.h`).
+- **`media`** (`media.a`, `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.
+
+Without the `media` extension the element still exists and its DOM API is
+callable, but opening a source fails and fires `error`. That is also how Windows
+behaves today: the archive is POSIX-only. There is no WebView and no platform
+media framework in the path either way.
 
 - **Decoding.** `avformat_open_input` opens the `src` (a path — `file://` is
   accepted, but media paths are *not* percent-decoded, unlike images), the
   best stream is selected for each kind, and a software decoder yields
   `yuv/rgb` frames which `sws_scale` converts to RGBA8 at the coded size. The
   supported containers/codecs are the minimal FFmpeg configuration from
-  `scripts/build-gui.ts`: MP4/MOV/MKV/AVI/FLV/MPEG-TS/M4V/ASF, MP3/OGG/WAV/FLAC/
+  `scripts/build-media.ts`: MP4/MOV/MKV/AVI/FLV/MPEG-TS/M4V/ASF, MP3/OGG/WAV/FLAC/
   AAC; H.264, HEVC, VP8, VP9, AV1, MPEG-4, MJPEG video; AAC, MP3, Opus, Vorbis,
   FLAC, ALAC, AC3/E-AC3, WMAv2 and the raw PCM formats audio.
 - **Video.** `<video>` is a replaced element like `<img>` (UA default
@@ -83,13 +97,14 @@ framework in the path.
   same `PaintImage` as an image; the renderer uploads each new decoded frame to
   an RGBA texture (`ensureMediaTexture`) and draws a textured quad, so the GPU
   scales it to the CSS box instead of the CPU resizing. Playback timing is the
-  wall clock (`SDL_GetTicks`), not the frame delta.
+  process monotonic clock, not the frame delta.
 - **Audio.** There is no audio callback: the decoder is pushed on the main
-  thread as it is ticked and the PCM is queued with
-  `SDL_OpenAudioDeviceStream` in push mode (`NULL` callback), buffering about
-  0.25 s ahead at 48 kHz stereo `SDL_AUDIO_F32`. `volume` maps to
-  `SDL_SetAudioStreamGain`; audio is best-effort and is skipped when no device
-  is available (headless CI).
+  thread as it is ticked and writes into an `xtgui::AudioSink`. The GUI
+  implements that sink in `gui_media.cpp` with `SDL_OpenAudioDeviceStream` in
+  push mode (`NULL` callback), buffering about 0.25 s ahead at 48 kHz stereo
+  `SDL_AUDIO_F32`. `volume` maps to `SDL_SetAudioStreamGain`; audio is
+  best-effort and is skipped when no device is available (headless CI). Keeping
+  the sink in `gui.a` means `media.a` depends only on FFmpeg.
 - **Threading.** The engine is single-threaded and not thread-aware, so all
   decoding happens on the main thread inside `xt_gui_media_tick` — no decode
   thread, no cross-thread GC exposure.

package/doc/gui.md

@@ -21,9 +21,11 @@ what `examples/gui/pelican-bike` — a playable 2D game — is built on. **M12**
 DOM node lifetime explicit (what a mutation releases, what it keeps) and gives the
 engine bounded memory: see [Node lifetime](./gui/dom.md#node-lifetime) and
 [Memory & GC](./gui/runtime.md#memory--gc). **M13** plays real
-`<video>`/`<audio>` — a vendored minimal FFmpeg decodes them on the main thread,
-video frames go through the image texture path and audio to an SDL stream, with
-the DOM media API exposing `play`/`pause`/`currentTime`/… and media events.
+`<video>`/`<audio>` — the optional `media` extension decodes them on the main
+thread with a vendored minimal FFmpeg, video frames go through the image texture
+path and audio to an SDL stream, with the DOM media API exposing
+`play`/`pause`/`currentTime`/… and media events. Enabling `gui` alone does not
+link FFmpeg.
 **M14** adds `<canvas>` with a self-written 2D software rasteriser (anti-aliased
 fills, paths, text and `drawImage`) uploaded through the image texture path —
 see [Canvas](./gui/canvas.md). **M15** adds CSS `transform` /
@@ -84,7 +86,7 @@ pages above.
 | 4 | The engine is **not self-hosted** (it is C/C++, not TS), but must not affect the compiler's platform-agnostic design. Delivered as a per-platform prebuilt archive linked via `nativeObjects`. |
 | 5 | The **event loop is generic**: the runtime exposes a generic main-loop hook and a poll primitive; nothing GUI-specific enters `runtime/`. |
 | 6 | **Multiple windows** are supported by the core object model. |
-| 7 | Third-party low-level libs are **statically linked into `gui.a`** so releases stay self-contained; only OS frameworks are added at link time. |
+| 7 | Third-party low-level libs are **statically linked into the extension archives** so releases stay self-contained; only OS frameworks are added at link time. `gui.a` carries SDL3/FreeType/HarfBuzz, and the optional `media.a` carries FFmpeg and is linked only with `--ext media`. |
 
 ## Architecture
 
@@ -106,6 +108,7 @@ pages above.
         windowing + input (SDL3) ── multiple windows
         text (HarfBuzz + FreeType) ── glyph atlas / SDF
         images (stb_image; SVG via NanoSVG)
+        media DOM + audio sink ── optional media.a (FFmpeg) installs the decoder
 ```
 
 The engine never talks to the compiler. The compiler only sees an `Extension`
@@ -120,18 +123,18 @@ with `nativeObjects()`, `linkerFlags()` and `modules()`.
 | Text shaping | **HarfBuzz** | correct complex-script shaping |
 | Glyph raster | **FreeType** | glyph outlines → GPU atlas / SDF |
 | Images | **stb_image** (vendored header) for bitmaps, **NanoSVG** (vendored headers) for SVG | single headers to start; SVG files rasterise on demand |
-| Video + audio | **FFmpeg** (statically vendored, minimal build) | decodes the common container/codec set; no WebView or platform media framework |
+| Video + audio | **FFmpeg** (statically vendored, minimal build, optional `media` extension) | decodes the common container/codec set; no WebView or platform media framework |
 
 Pinned versions: SDL3 `release-3.2.10`, FreeType `2.13.3`, HarfBuzz `10.1.0`,
-FFmpeg `7.1` (overridable with `SDL3_TAG` / `FREETYPE_VERSION` /
-`HARFBUZZ_VERSION` / `FFMPEG_VERSION`).
+FFmpeg `7.1` for the optional `media` archive (overridable with `SDL3_TAG` /
+`FREETYPE_VERSION` / `HARFBUZZ_VERSION` / `FFMPEG_VERSION`).
 
 Alternative if SDL3 is rejected: **GLFW + OpenGL 3.3** (simpler, but OpenGL is
 deprecated on macOS and gives no modern GPU abstraction). **wgpu-native** if the
 engine were Rust.
 
-> These vendored libraries are linked **statically into `gui.a`** so a released
-> xbintsc stays "download and run"; only OS frameworks are added by
+> These vendored libraries are linked **statically into `gui.a` / `media.a`** so
+> a released xbintsc stays "download and run"; only OS frameworks are added by
 > `linkerFlags()`.
 
 ## Milestones
@@ -172,15 +175,16 @@ engine were Rust.
      animated `background-color`/`color`/`border-color`/`border-radius`, retargeting
      and `win.advance(ms)`. `@keyframes` remain.
 7. **M7 — CI & releases** ✅ (Linux/macOS build) / 🚧 (run + Windows)
-   - `compile-examples` builds `gui.a` on Linux and macOS (required), then runs
-     the example and `tests/e2e/gui-*.test.ts` under Xvfb + lavapipe on Linux
-     (required). The macOS run is provisional until a WindowServer is confirmed;
-     it is guarded so a failure is logged without annotating the run.
-   - The `package` job builds `gui.a` before assembling the release, so it ships
-     inside the existing runtime archive (`package-release` copies all of
-     `runtime/`).
-   - `vendor/` (SDL3/FreeType/HarfBuzz, the slow part) is cached per OS/arch,
-     keyed by `scripts/build-gui.ts`.
+   - `compile-examples` builds `gui.a` and `media.a` on Linux and macOS
+     (required), then runs the examples and `tests/e2e/gui-*.test.ts` under
+     Xvfb + lavapipe on Linux (required). The macOS run is provisional until a
+     WindowServer is confirmed; it is guarded so a failure is logged without
+     annotating the run.
+   - The `package` job builds `gui.a` and `media.a` before assembling the
+     release, so both ship inside the existing runtime archive
+     (`package-release` copies all of `runtime/`).
+   - `vendor/` (SDL3/FreeType/HarfBuzz for `gui.a`, FFmpeg for `media.a`) is
+     cached per OS/arch, keyed by `scripts/build-gui.ts` / `scripts/build-media.ts`.
    - Windows (build + run) stays provisional in CI: the MSVC-compatible
      `gui.lib` builds and runs locally through SDL_GPU's Vulkan backend, but the
      hosted runners have no GPU/Vulkan driver. A failure is logged without
@@ -234,13 +238,15 @@ engine were Rust.
       `tests/e2e/gui-retention.test.ts` (see [Memory & GC](./gui/runtime.md#memory--gc)).
 13. **M13 — video & audio** ✅
     - `<video>` / `<audio>` decode through a statically vendored minimal FFmpeg
-      (`media.*`, `gui_media.cpp`), frames upload to GPU textures through the
-      existing image pipeline, audio is pushed to an SDL stream on the main
-      thread, and the DOM media API plus `loadedmetadata`/`play`/`pause`/
-      `ended`/`timeupdate`/`error` events are exposed on element handles
+      in the optional `media` extension (`runtime/ext_media/media.cpp`), frames
+      upload to GPU textures through the existing image pipeline, audio is
+      pushed to an SDL stream on the main thread by the GUI's audio sink, and
+      the DOM media API plus `loadedmetadata`/`play`/`pause`/`ended`/
+      `timeupdate`/`error` events are exposed on element handles
       (`dom_api_media.cpp`, `dom_api_proto.cpp`). Controlled from TS + CSS;
       there are no built-in controls. Example in `examples/gui/media.*`, e2e in
-      `tests/e2e/gui-media.test.ts`.
+      `tests/e2e/gui-media.test.ts` (with the `media` extension) and
+      `tests/e2e/gui-media-disabled.test.ts` (without it).
 14. **M14 — `<canvas>` 2D** ✅
     - `<canvas>` is a replaced element (`xtgui::Canvas2D`, `layout.*`), the
       `getContext("2d")` handle and drawing API live in `dom_api_canvas.cpp`,
@@ -300,10 +306,11 @@ engine were Rust.
   pixel size and cached by that size, so scaling and HiDPI stay crisp.
 - **M6b** ✅ CSS transitions (parsing in `style.*`, an animation clock and
   transition state in `document.*`, `advance`/`advance(ms)` hooks, e2e coverage).
-- **M7** ✅ builds `gui.a` in CI on Linux and macOS (required) and runs the
-  example plus the GUI e2e suite under Xvfb on Linux; `package` ships `gui.a`,
-  `vendor/` is cached, and the `ar -M` merge works on GNU/Linux and macOS.
-  macOS runs and all of Windows remain provisional in CI.
+- **M7** ✅ builds `gui.a` (and the optional `media.a`) in CI on Linux and macOS
+  (required) and runs the example plus the GUI e2e suite under Xvfb on Linux;
+  `package` ships both archives, `vendor/` is cached, and the `ar -M` merge
+  works on GNU/Linux and macOS. macOS runs and all of Windows remain provisional
+  in CI.
 - **M8** ✅ element/document handles (`dom_api.*`), DOM mutation with lazy
   restyle/relayout (`document.*`, `xt_gui_flush_dom`), element event dispatch
   with capture/bubble and `stopPropagation` (`dom_api.*`, `gui.cpp`), and e2e
@@ -338,14 +345,17 @@ engine were Rust.
   ratcheting upwards. `win.stats()` exposes the engine counters and
   `tests/e2e/gui-retention.test.ts` pins them; a game loop rewriting its sprite
   every frame now runs in constant memory (see [Memory & GC](./gui/runtime.md#memory--gc)).
-- **M13** ✅ `<video>` / `<audio>` support. A minimal static FFmpeg is vendored
-  and merged into `gui.a` (`scripts/build-gui.ts`), `media.*` decodes video to
-  RGBA frames and audio to 48 kHz stereo PCM on the main thread, `gui_media.cpp`
-  owns the players and pumps the media clock and events each frame,
+- **M13** ✅ `<video>` / `<audio>` support. The optional `media` extension
+  vendors and builds a minimal static FFmpeg (`scripts/build-media.ts`) and
+  merges it into `media.a`; `runtime/ext_media/media.cpp` decodes video to RGBA
+  frames and audio to 48 kHz stereo PCM on the main thread,
+  `runtime/ext_gui/gui_media.cpp` owns the players, implements the SDL audio
+  sink and pumps the media clock and events each frame,
   `renderer_image.cpp` uploads each new video frame through the image texture
   path, and `dom_api_media.cpp` exposes `play`/`pause`/`load` plus the media
-  properties on element handles. `examples/gui/media.*` demonstrates the
-  TS-plus-CSS-controls pattern and `tests/e2e/gui-media.test.ts` pins it.
+  properties on element handles. `gui.a` stays FFmpeg-free; enabling `media`
+  without `gui` is rejected by the registry. `examples/gui/media.*` demonstrates
+  the TS-plus-CSS-controls pattern and `tests/e2e/gui-media.test.ts` pins it.
 - **M14** ✅ `<canvas>` support. A new replaced element (`layout.*`) carries an
   intrinsic size from its `width`/`height` attributes (default `300x150`),
   `xtgui::Canvas2D` (`canvas.{h,cpp}`) owns the RGBA8 bitmap and drawing state,
@@ -354,7 +364,13 @@ engine were Rust.
   `getContext("2d")` handle and its API are bound in `dom_api_canvas.cpp`, and
   `gui_canvas.cpp` owns the per-window lifetime. The bitmap uploads through the
   image texture path (`renderer_image.cpp`) and the display list carries a
-  `canvas_id` (`paint.*`). See [Canvas](./gui/canvas.md); e2e in
+  `canvas_id` (`paint.*`). The drawing surface was later widened with linear /
+  radial gradients (`canvas_gradient.cpp`), `ellipse`/`roundRect`, line
+  caps/joins/miter limits and dash patterns (`canvas_style.cpp`,
+  `canvas_stroke.cpp`), and `getTransform`; `transform` now post-multiplies, so
+  `translate(x, y); rotate(a)` rotates around the translated origin, and
+  `examples/gui/pelican-canvas` draws an animated pelican on a bicycle entirely
+  with these APIs. See [Canvas](./gui/canvas.md); e2e in
   `tests/e2e/gui-canvas.test.ts`.
 - **M15** ✅ CSS `transform` / `transform-origin`. A new translation unit
   (`transform.{h,cpp}`) parses `translate`/`translateX`/`translateY`/`scale`/

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

@@ -5,33 +5,39 @@
 > 属于 [GUI 扩展](../gui.md) 的一部分；引擎总览、锁定决策与路线图在那里。
 
 - 源码位于 `runtime/ext_gui/`（C/C++），外加 `vendor/` 下的 vendored 库
-  （被 gitignore；按需获取）。
+  （被 gitignore；按需获取）。媒体解码位于 `runtime/ext_media/`，单独构建。
 - `npm run gui`（`scripts/build-gui.ts`）获取固定版本的 SDL3（`SDL3_TAG`，
   默认 `release-3.2.10`），构建静态 SDL3，获取并构建静态 FreeType
   （`FREETYPE_VERSION`）与 HarfBuzz（`HARFBUZZ_VERSION`），编译引擎，并把
   所有内容合并到 `runtime/lib/<os>-<arch>/gui.a`（Windows 上 MSVC ABI 则为
-  `gui.lib`），与 `core.a` 采用相同约定，静态打包三者。它还会获取、配置并构建
-  一个最小化的静态 **FFmpeg**（`FFMPEG_VERSION`，默认 `7.1`），只启用媒体元素
-  所需的 demuxer/parser/decoder，并把那些归档合并进 `gui.a`，同时为引擎定义
-  `XT_GUI_WITH_FFMPEG`。合并使用 macOS 上的
+  `gui.lib`），与 `core.a` 采用相同约定，静态打包三者。合并使用 macOS 上的
   `libtool` 与其他平台上的 `ar -M`（GNU/LLVM）；CMake 归档会在构建根目录或
   `Release/` 下按任一生成器风格被发现。
-- `src/extensions/gui/index.ts` 通过 `nativeObjects()` 暴露该归档（经由
+- `npm run media`（`scripts/build-media.ts`）构建可选的 **FFmpeg** 后端。它获取
+  FFmpeg（`FFMPEG_VERSION`，默认 `7.1`），配置一个只启用媒体元素所需
+  demuxer/parser/decoder 的最小静态构建，用它编译
+  `runtime/ext_media/media.cpp`，并把所有内容合并到
+  `runtime/lib/<os>-<arch>/media.a`。`gui.a` **不会**链接 FFmpeg：程序通过
+  `--ext media` 显式启用播放能力。
+- `src/extensions/gui/index.ts` 通过 `nativeObjects()` 暴露引擎归档（经由
   `findRuntimeLibrary`，因此 `.a`/`.lib` 都可用），并通过 `linkerFlags()`
-  暴露操作系统框架。
+  暴露操作系统框架。`src/extensions/media/index.ts` 对 `media.a` 做同样的暴露，
+  并把注册桥（`runtime/ext_media/media_bridge.c`）作为普通 runtime 源编译。
 - `scripts/build-gui.ts` 使用与驱动**相同**的 clang
   （`src/driver/toolchain-provider.ts`）；Windows 上就是 Visual Studio 自带的、
   面向 MSVC 的 LLVM，并配套使用其同目录下的 `clang++`/`llvm-ar` 来配置 CMake、
   编译引擎和合并归档。脚本不提供 `gcc`/`g++` 回退，Windows 上也始终使用
   `llvm-ar`，因此归档不会混入其他目标文件格式或 C++ 运行时。Visual Studio
   工具链按绝对路径查找，无需开发者命令提示符。Windows 上 SDL_GPU 会选择 Vulkan
-  后端，不需要 DXIL/`dxc` 工具链。
-- CI 在组装发布归档之前构建 `gui.a`，因此它会随 `runtime/lib/<slug>/` 一起
-  发布（发布 tarball 会复制整个 `runtime/` 树）。归档在 Linux（Xvfb 下，
-  使用 lavapipe 软件 Vulkan 驱动）与 macOS 上构建并运行示例；Windows 为
-  试验性，因为托管 runner 没有 GPU/Vulkan 驱动。
-- 现有的缓存指纹已经会对 `nativeObjects()` 的内容做哈希，因此重建 `gui.a`
-  会自动使缓存二进制失效。
+  后端，不需要 DXIL/`dxc` 工具链。`scripts/build-media.ts` 对 FFmpeg 与播放器
+  使用同一套已解析的工具链。
+- CI 在组装发布归档之前构建 `gui.a` 与 `media.a`，因此它们会随
+  `runtime/lib/<slug>/` 一起发布（发布 tarball 会复制整个 `runtime/` 树）。
+  归档在 Linux（Xvfb 下，使用 lavapipe 软件 Vulkan 驱动）与 macOS 上构建并运行
+  示例；Windows 为试验性，因为托管 runner 没有 GPU/Vulkan 驱动，且 media 归档
+  目前仅支持 POSIX。
+- 现有的缓存指纹已经会对 `nativeObjects()` 的内容与 `runtimeSources()` 的内容
+  做哈希，因此重建任一归档都会自动使缓存二进制失效。
 - CMake 构建树位于其源码**旁边**（`vendor/sdl-build`、`vendor/freetype-build`、
   `vendor/harfbuzz-build`），绝不放在源码内部：`CMakeCache.txt` 记录的是配置它
   的那台机器，而 SDL 的视频后端是 `option()`，因此先运行的那次配置会一直生效。
@@ -47,6 +53,7 @@
 ```sh
 npm run runtime      # runtime 改动后重建 core.a
 npm run gui          # 构建 runtime/lib/<os>-<arch>/gui.a（首次会获取 SDL3）
+npm run media        # 可选：构建 media.a（首次会获取并构建 FFmpeg）
 xbintsc run examples/gui/hello.ts --ext gui
 ```
 
@@ -59,8 +66,9 @@ xbintsc run examples/gui/hello.ts --ext gui
 
 `examples/gui/media.ts`（配合 `media.html`）演示 `<video>`/`<audio>`：它在
 `<video>` 上叠一个 CSS 进度条，并用 `play()`/`pause()`/`currentTime`/
-`volume` 驱动播放。媒体 `src` 相对于进程工作目录解析，因此从仓库根目录运行：
-`xbintsc run examples/gui/media.ts --ext gui`。几何报告见该目录的 README。
+`volume` 驱动播放。它需要单独的可选 `media` 扩展，因此要构建并同时启用两者。
+媒体 `src` 相对于进程工作目录解析，因此从仓库根目录运行：
+`xbintsc run examples/gui/media.ts --ext gui,media`。几何报告见该目录的 README。
 
 这些测试套件在 Windows 上默认跳过（归档可以在本机通过 Vulkan 运行，但 CI
 runner 没有可用的 GPU 驱动）。如果本机有 `gui.lib` 与可用的 GPU，可用
@@ -77,10 +85,14 @@ npx vitest run tests/e2e/gui-layout.test.ts tests/e2e/gui-example.test.ts
 ```sh
 sudo sh scripts/install-gui-deps.sh   # clang、cmake、X11/Wayland 头文件、Vulkan、Xvfb
 npm run runtime && npm run gui
+npm run media                         # 可选：<video>/<audio> 播放
 xvfb-run -a --server-args="-screen 0 1280x720x24" \
   npx tsx src/cli/main.ts run examples/gui/hello.ts --ext gui
 ```
 
+媒体 e2e 套件（`tests/e2e/gui-media.test.ts`）只有在 `gui.a` 与 `media.a` 都
+存在时才会运行；`tests/e2e/gui-media-disabled.test.ts` 覆盖仅 `gui.a` 的构建。
+
 包清单集中在 `scripts/install-gui-deps.sh`（`apt-get install -y clang cmake
 libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev libxinerama-dev
 libxfixes-dev libxkbcommon-dev libwayland-dev wayland-protocols libdecor-0-dev

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

@@ -10,7 +10,9 @@
 CSS 盒中。
 
 引擎侧的对象是 `xtgui::Canvas2D`（`runtime/ext_gui/canvas.{h,cpp}`）——一块 RGBA8 位图
-加上 2D 绘制状态。光栅器位于 `canvas_raster.cpp`；DOM 绑定位于 `dom_api_canvas.cpp`；
+加上 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`。
 
 ## 获取上下文
@@ -31,6 +33,11 @@ const ctx = canvas.getContext("2d"); // 其他上下文类型返回 null
 以相反方向环绕时能形成空洞）。轴对齐矩形（变换中 `b == 0 && c == 0`）走直接的覆盖率
 快速路径。混合为非预乘 source-over，并按 `globalAlpha` 缩放。
 
+填充或描边可以使用纯色，也可以使用 **`CanvasGradient`**。渐变的坐标属于用户空间，
+因此光栅器会先用当前变换的逆矩阵把每个设备像素映射回用户空间再采样——形状被平移、
+缩放或旋转时，渐变仍然贴在形状上。描边被展平为线段四边形，再按 `lineJoin`/`lineCap`
+补上连接/端点形状；虚线模式先把折线切成“实线”片段，然后用同样的端点规则描边。
+
 Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点为键（与
 `<video>`/`<audio>` 解码表结构相同）。当节点被丢弃（`loadHTML`、窗口关闭/退出，或丢弃
 子树的变更操作）时随之释放，并释放对应的 GPU 纹理。
@@ -39,21 +46,34 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 
 状态与变换：`save` / `restore`（会恢复变换、线宽、透明度、字体/文本设置**以及**
 填充/描边样式）、`translate`、`rotate`、`scale`、`transform(a,b,c,d,e,f)`、
-`setTransform`、`resetTransform`。
-
-样式与设置：`fillStyle` / `strokeStyle`（层叠所用的颜色解析器能识别的 CSS 颜色）、
-`lineWidth`、`globalAlpha`、`font`（CSS 字体简写，解析出字体族、字号与粗体/斜体——
-默认 `10px sans-serif`）、`textAlign`（`start`/`left`、`center`、`right`/`end`）与
-`textBaseline`（`alphabetic`、`top`、`middle`、`bottom`、`hanging`、`ideographic`）。
-读取属性返回上次赋予的值；赋予无法解析的颜色会保留原值。
-
-路径：`beginPath`、`closePath`、`moveTo`、`lineTo`、`rect`、`arc`、
-`quadraticCurveTo`、`bezierCurveTo`，然后 `fill`（多环、非零环绕）或 `stroke`。贝塞尔
-与二次曲线段会被展平为线段；弧线同样被展平，每条子路径按线段四边形描边，并在每个连接
-处补一个圆盘。
+`setTransform`、`resetTransform`、`getTransform`（返回带 `a`…`f` 与 `is2D` 的对象）。
+变换按 canvas 的顺序组合：`translate(x, y); rotate(a)` 围绕平移后的原点旋转。
+
+样式与设置：`fillStyle` / `strokeStyle`（层叠所用的颜色解析器能识别的 CSS 颜色，或
+`CanvasGradient`）、`lineWidth`、`globalAlpha`、`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`）。读取属性返回
+上次赋予的值；赋予无法解析的颜色会保留原值。
+
+渐变：`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`）。
+
+路径：`beginPath`、`closePath`、`moveTo`、`lineTo`、`rect`、`roundRect`、`arc`、
+`ellipse`、`quadraticCurveTo`、`bezierCurveTo`，然后 `fill`（多环、非零环绕）或
+`stroke`。贝塞尔与二次曲线段会被展平为线段；弧线与椭圆同样被展平。`roundRect` 只接受
+单个圆角半径数字（数组形式尚未实现）。
 
 矩形：`clearRect`、`fillRect`、`strokeRect`。
 
+虚线：`setLineDash(segments)` / `getLineDash()` / `lineDashOffset` 实现标准规则
+（奇数长度列表会复制一遍，负数/非有限值会被忽略，全零列表表示实线）。
+
 文本：`measureText(text)`（返回 `{ width }`）、`fillText(text, x, y)` 与
 `strokeText(text, x, y)`。文本经 HarfBuzz 排版、FreeType 光栅化（与 HTML 文本相同的
 技术栈），按变换的近似缩放绘制。**仅支持平移与均匀缩放**——旋转或斜切变换仍会把每个
@@ -70,11 +90,10 @@ Canvas 像素**不参与垃圾回收**：canvas 由窗口拥有、以 DOM 节点
 
 ## 尚未实现
 
-渐变与图案、阴影、`clip()`、`globalCompositeOperation`、线段连接/端点/虚线/斜接、
-`setLineDash`、`createLinearGradient`/`createPattern`、`putImageData`、
-`createImageData`、`isPointInPath`、`getTransform`、以 `DOMMatrix` 调用的
+图案（`createPattern`）、阴影、`clip()`、`globalCompositeOperation`、
+`putImageData`、`createImageData`、`isPointInPath`、以 `DOMMatrix` 调用的
 `setTransform`、可切换图像平滑的 `drawImage`、`toDataURL`/`toBlob`、把 `<canvas>` 用作
 CSS `background-image`，以及离屏画布（`OffscreenCanvas`、
-`transferControlToOffscreen`）。
+`transferControlToOffscreen`）。`roundRect` 只接受单个半径，径向渐变会忽略内圆偏移。
 
 另见[媒体](./media.md)：`drawImage` 与纹理上传所共享的图像/视频/音频解码栈。

package/doc/zh-CN/gui/known-issues.md

@@ -54,11 +54,12 @@
   SDL_GPU 会选择 **Vulkan** 后端（`win.driver()` 返回 `"vulkan"`），因此归档
   不需要 DXIL/`dxc` 工具链；托管 Windows runner 没有 GPU/Vulkan 驱动，这才是
   CI 运行仍为试验性的原因。
-- **Windows 上的媒体：** 媒体解码器（FFmpeg）只构建并合并进 POSIX 的
-  `gui.a`；Windows 的 `gui.lib` 不含它们，因此那里的 `<video>`/`<audio>` 为空
-  操作（失败会触发 `error`）。启用它需要 MSVC 兼容的 FFmpeg 构建，推迟到
-  Windows GUI 路径本身验证之后。`<video controls>` 同样推迟——预期模式是 TS +
-  CSS 叠层，如 `examples/gui/media.ts`。
+- **Windows 上的媒体：** `media` 扩展目前仅支持 POSIX。GUI 引擎本身可在
+  Windows 上构建，但没有该扩展时 `<video>`/`<audio>` 为空操作（打开失败并触发
+  `error`），`--ext media` 会给出可操作的错误而不是继续链接。启用它需要
+  MSVC 兼容的 FFmpeg 构建，推迟到 Windows GUI 路径本身验证之后。
+  `<video controls>` 同样推迟——预期模式是 TS + CSS 叠层，如
+  `examples/gui/media.ts`。
 - **D3D12 着色器：** SPIR-V（Vulkan）与 DXIL（Direct3D 12）二进制块均已构建并
   内嵌，非 Metal 路径不再跳过几何绘制。但在 **SDL 3.2.10** 上 DXIL 仍不可用：
   其 D3D12 后端会拒绝任何着色器中声明了 uniform buffer 的图形管线，而引擎正是

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

@@ -55,25 +55,36 @@ opacity、`display`——与任何其他元素一样。盒子内部的艺术内
 
 ## 视频与音频（M13）
 
-`runtime/ext_gui/media.{h,cpp}` 封装一个静态 vendored 的 **FFmpeg** 构建，
-`runtime/ext_gui/gui_media.cpp` 把 DOM 树接到它上面。`<video>` 与 `<audio>`
-真正解码并播放；路径中没有 WebView，也没有平台媒体框架。
+媒体播放横跨两个扩展，因此只做界面的 GUI 程序不必为用不到的解码器付出体积：
+
+- **`gui`**（`gui.a`）负责 `<video>`/`<audio>` 元素、DOM API、渲染器集成与 SDL
+  音频 sink，但**不含 FFmpeg**。`runtime/ext_gui/media.{h,cpp}` 声明播放器接口，
+  并通过媒体后端在启动时安装的函数表分发（`runtime/ext_gui/media_api.h`）。
+- **`media`**（`media.a`、`runtime/ext_media/`）是可选的解码后端：
+  `runtime/ext_media/media.cpp` 封装静态 vendored 的 **FFmpeg** 构建，
+  `runtime/ext_media/media_bridge.c` 把它注册进引擎。用 `--ext media`（或
+  `--ext gui,media`）启用。`media` 依赖 `gui`；注册表会拒绝错误的组合。
+
+没有 `media` 扩展时，元素仍然存在、DOM API 仍可调用，但打开源会失败并触发
+`error`。Windows 目前也是如此：该归档仅支持 POSIX。两条路径都没有 WebView，也
+没有平台媒体框架。
 
 - **解码。** `avformat_open_input` 打开 `src`（是路径——接受 `file://`，但与
   图像不同，媒体路径*不做*百分号解码），为每种媒体选取最佳流，软件解码器
   产出 `yuv/rgb` 帧，`sws_scale` 按编码尺寸转换为 RGBA8。支持的容器/编码即
-  `scripts/build-gui.ts` 的最小 FFmpeg 配置：MP4/MOV/MKV/AVI/FLV/MPEG-TS/M4V/
+  `scripts/build-media.ts` 的最小 FFmpeg 配置：MP4/MOV/MKV/AVI/FLV/MPEG-TS/M4V/
   ASF，MP3/OGG/WAV/FLAC/AAC；视频 H.264、HEVC、VP8、VP9、AV1、MPEG-4、MJPEG；
   音频 AAC、MP3、Opus、Vorbis、FLAC、ALAC、AC3/E-AC3、WMAv2 及原始 PCM 格式。
 - **视频。** `<video>` 与 `<img>` 一样是替换元素（UA 默认 `300x150`，解码
   尺寸通过 `setMediaSize` 覆盖）。绘制产出与图像相同的 `PaintImage`；渲染器把
   每个新解码帧上传到 RGBA 纹理（`ensureMediaTexture`）并绘制带纹理四边形，
-  因此由 GPU 缩放到 CSS 盒，而非 CPU 缩放。播放计时基于墙钟
-  （`SDL_GetTicks`），不是帧间隔。
-- **音频。** 没有音频回调：解码器随主线程 tick 被推送，PCM 以 push 模式
-  （`NULL` 回调）通过 `SDL_OpenAudioDeviceStream` 排队，在前方缓冲约 0.25 秒，
-  格式为 48 kHz 立体声 `SDL_AUDIO_F32`。`volume` 映射到
-  `SDL_SetAudioStreamGain`；音频是尽力而为，无设备时（无头 CI）跳过。
+  因此由 GPU 缩放到 CSS 盒，而非 CPU 缩放。播放计时基于进程单调时钟，不是帧间隔。
+- **音频。** 没有音频回调：解码器随主线程 tick 被推送，并写入
+  `xtgui::AudioSink`。GUI 在 `gui_media.cpp` 中用 push 模式（`NULL` 回调）的
+  `SDL_OpenAudioDeviceStream` 实现该 sink，在前方缓冲约 0.25 秒，格式为
+  48 kHz 立体声 `SDL_AUDIO_F32`。`volume` 映射到 `SDL_SetAudioStreamGain`；
+  音频是尽力而为，无设备时（无头 CI）跳过。把 sink 留在 `gui.a` 中意味着
+  `media.a` 只依赖 FFmpeg。
 - **线程。** 引擎是单线程且非线程感知，因此所有解码都在主线程的
   `xt_gui_media_tick` 内完成——没有解码线程，也没有跨线程 GC 暴露。
 - **DOM API。** 元素句柄直接暴露媒体接口（见