xbintsc 0.5.22 → 0.5.23

package/doc/ai/troubleshooting.md

@@ -118,6 +118,15 @@ The `gui` extension needs its per-platform prebuilt `gui.a`/`gui.lib`, which is
 not built in a plain source checkout. Drop `--ext gui`, or build the archive as
 described in [../gui.md](../gui.md).
 
+### `media native library not found at …`
+
+`<video>`/`<audio>` playback needs the optional `media` archive (`media.a`),
+built separately with `npm run media`. Build it, or drop `--ext media`; a
+GUI-only build still links and media elements simply fire `error`. The `media`
+extension also requires `gui`, has no Windows archive yet, and `--ext media`
+alone is rejected with the flags to pass. See
+[../gui/build.md](../gui/build.md).
+
 ### `Icon file not found` / icon tools missing
 
 `--icon`/`app.icon` paths resolve against the config file's directory. On

package/doc/ai/zh-CN/cli.md

@@ -32,7 +32,7 @@
     --out <dir>       输出目录（默认 build/）
     --emit <kind>     exe | obj | ir（默认 exe）
 -O0 .. -O3            传给 clang 的优化级别（默认 -O2）
-    --ext <names>     开启内置扩展，逗号分隔（如 node,gui）
+    --ext <names>     开启内置扩展，逗号分隔（如 node,gui,media）
     --ext-native <m>  通过 JSON 清单注册 C++/Rust 扩展（多个用逗号分隔）
     --config <path>   使用指定项目配置，不做自动发现
     --no-config       完全不读取项目配置

package/doc/ai/zh-CN/extensions.md

@@ -1,4 +1,4 @@
-# 扩展：Node 模块、GUI、C++/Rust 库
+# 扩展：Node 模块、GUI、媒体、C++/Rust 库
 
 编译器核心与平台无关。任何与平台相关的东西——Node 的 `fs`、一个 HTML/CSS 渲染器、
 你自己的 C++ 库——都以**扩展**的形式接入：它既贡献模块绑定，也贡献要一起编译/链接的
@@ -66,11 +66,9 @@ import { createWindow, run } from "gui";
 ```
 
 它是自带渲染引擎的 GPU 加速实现（自己的 HTML 解析器、CSS 级联、布局与合成器），不是
-系统 WebView。`<img>`、`<video>`、`<audio>` 都是真正解码：归档内打入一个最小化的
-静态 FFmpeg，DOM 媒体 API（`play`/`pause`/`currentTime`/`volume`/…）与
-`loadedmetadata`/`play`/`pause`/`ended`/`timeupdate`/`error` 事件可让程序驱动播放。
-没有内置控件——用元素和 CSS 自绘控件（见 `examples/gui/media.ts`）；视频帧与音频 PCM
-都在主线程解码。也支持 `<canvas>`：`getContext("2d")` 返回的上下文，其填充、路径、
+系统 WebView。`<img>` 由引擎自身解码；而 `<video>`/`<audio>` 在只启用 `gui` 时**不可用**
+——它们需要单独的 [`media`](#media--视频音频解码) 扩展。也支持 `<canvas>`：
+`getContext("2d")` 返回的上下文，其填充、路径、
 渐变、文本与 `drawImage` 由自研 CPU 光栅器处理（另有线段端点/连接、虚线描边、
 `ellipse` 与 `roundRect`），元素句柄还暴露 `width`/`height`。CSS
 `transform`/`transform-origin` 作为绘制期效果可用，因此一个盒子（以及其中的文本、
@@ -78,10 +76,24 @@ import { createWindow, run } from "gui";
 `requestAnimationFrame` 逐帧驱动，或写成 `transition: transform`（见
 `examples/gui/pelican-svg`）。因为主体是 C++，它以各平台预编译的 `gui.a`/`gui.lib` 形式分发。如果该
 平台的归档不存在，构建会以明确的提示失败；设计与路线图见 [../../zh-CN/gui.md](../../zh-CN/gui.md)（总览；引擎按功能拆分在 [`doc/zh-CN/gui/`](../../zh-CN/gui/) 下），
-脚本接口见 [../../zh-CN/gui-scripts.md](../../zh-CN/gui-scripts.md)。媒体播放是
-Windows 唯一不支持的：Windows 的 `gui.a` 不构建 FFmpeg，媒体槽位为空操作。Canvas API
+脚本接口见 [../../zh-CN/gui-scripts.md](../../zh-CN/gui-scripts.md)。Canvas API
 及其限制见 [../../zh-CN/gui/canvas.md](../../zh-CN/gui/canvas.md)。
 
+### `media` —— 视频/音频解码
+
+用 `--ext media` **与 `gui` 一起**开启（`--ext gui,media`；注册表会拒绝单独启用
+`media`）。它链接单独的 FFmpeg 后端 `media.a`，因此加入 `<video>`/`<audio>` 播放
+不会让只做界面的二进制变大。
+
+DOM API 与普通 HTML 媒体元素一致：`play()` / `pause()` / `load()`，以及
+`paused` / `ended` / `duration` / `currentTime` / `volume` / `muted` / `loop` /
+`autoplay` / `videoWidth` / `videoHeight` / `readyState` / `src` 属性，还有
+`loadedmetadata`/`play`/`pause`/`ended`/`timeupdate`/`error` 事件。没有内置
+控件——用元素和 CSS 自绘控件（见 `examples/gui/media.ts`）。视频帧与音频 PCM
+都在主线程解码；视频走图像纹理路径。没有该扩展时，打开媒体源会失败并触发
+`error`（元素与 API 仍然存在）。该归档目前仅支持 POSIX，因此 Windows 也只会触发
+同样的 `error`；见 [../../zh-CN/gui/known-issues.md](../../zh-CN/gui/known-issues.md)。
+
 ## 第三方 npm 包
 
 没有被已启用扩展认领的裸说明符，会在 `node_modules` 里查找并**作为源码**打包，

package/doc/ai/zh-CN/troubleshooting.md

@@ -108,6 +108,14 @@ clang 自身失败。抛出的消息包含完整的 clang 命令与 stderr——
 `gui` 扩展需要各平台预编译的 `gui.a`/`gui.lib`，普通源码检出并没有构建它。去掉
 `--ext gui`，或按 [../../zh-CN/gui.md](../../zh-CN/gui.md) 构建该归档。
 
+### `media native library not found at …`
+
+`<video>`/`<audio>` 播放需要可选的 `media` 归档（`media.a`），用
+`npm run media` 单独构建。构建它，或去掉 `--ext media`；仅启用 `gui` 的构建仍可
+链接，媒体元素只会触发 `error`。`media` 扩展还依赖 `gui`，目前没有 Windows
+归档，单独 `--ext media` 会被拒绝并提示应传的 flag。见
+[../../zh-CN/gui/build.md](../../zh-CN/gui/build.md)。
+
 ### `Icon file not found` / 图标工具缺失
 
 `--icon`/`app.icon` 的路径相对配置文件目录解析。Windows 上嵌入 PE 图标需要

package/doc/gui/build.md

@@ -4,21 +4,27 @@
 > decisions and roadmap live there.
 
 - Sources live in `runtime/ext_gui/` (C/C++) plus vendored libs under `vendor/`
-  (gitignored; fetched on demand).
+  (gitignored; fetched on demand). Media decoding lives in
+  `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`), 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. It also fetches, configures and builds a
-  minimal static **FFmpeg** (`FFMPEG_VERSION`, default `7.1`) with only the
-  demuxers/parsers/decoders the media elements need and merges those archives
-  into `gui.a`, defining `XT_GUI_WITH_FFMPEG` for the engine. The merge uses
-  `libtool` on macOS and `ar -M` (GNU/LLVM) elsewhere; CMake archives are
-  discovered under the build root or `Release/` for either generator style.
-- `src/extensions/gui/index.ts` exposes the archive through `nativeObjects()`
-  (via `findRuntimeLibrary`, so `.a`/`.lib` both work) and the OS frameworks
-  through `linkerFlags()`.
+  statically bundling all three. The merge uses `libtool` on macOS and
+  `ar -M` (GNU/LLVM) elsewhere; CMake archives are discovered under the build
+  root or `Release/` for either generator style.
+- `npm run media` (`scripts/build-media.ts`) builds the optional **FFmpeg**
+  backend. It fetches FFmpeg (`FFMPEG_VERSION`, default `7.1`), configures a
+  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`. `gui.a` does **not** link
+  FFmpeg: a program enables playback explicitly with `--ext media`.
+- `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` and compiles the registration bridge
+  (`runtime/ext_media/media_bridge.c`) as a normal runtime source.
 - `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
@@ -26,14 +32,17 @@
   fallbacks, and Windows always uses `llvm-ar`, so the archive cannot mix object
   formats or C++ runtimes. The Visual Studio toolchain is found by absolute
   path, so no developer prompt is required. On Windows SDL_GPU selects the
-  Vulkan backend; no DXIL/`dxc` toolchain is needed.
-- CI builds `gui.a` before assembling the release archive so it ships inside
-  `runtime/lib/<slug>/` (the release tarball copies the whole `runtime/` tree).
-  The archive is built and the example is run on Linux (under Xvfb, with the
-  lavapipe software Vulkan driver) and macOS; Windows is provisional because the
-  hosted runners have no GPU/Vulkan driver.
-- The existing cache fingerprint already hashes `nativeObjects()` contents, so
-  rebuilding `gui.a` invalidates cached binaries automatically.
+  Vulkan backend; no DXIL/`dxc` toolchain is needed. `scripts/build-media.ts`
+  uses the same resolved toolchain for FFmpeg and the player.
+- CI builds `gui.a` and `media.a` before assembling the release archive so they
+  ship inside `runtime/lib/<slug>/` (the release tarball copies the whole
+  `runtime/` tree). The archives are built and the examples are run on Linux
+  (under Xvfb, with the lavapipe software Vulkan driver) and macOS; Windows is
+  provisional because the hosted runners have no GPU/Vulkan driver, and the
+  media archive is POSIX-only.
+- 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
   `CMakeCache.txt` records the machine it was configured on, and SDL's video
@@ -52,6 +61,7 @@
 ```sh
 npm run runtime      # rebuild core.a after a runtime change
 npm run gui          # build runtime/lib/<os>-<arch>/gui.a (fetches SDL3 once)
+npm run media        # optional: build media.a (fetches and builds FFmpeg once)
 xbintsc run examples/gui/hello.ts --ext gui
 ```
 
@@ -62,9 +72,10 @@ 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`. 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`.
+`currentTime` / `volume`. It needs the separate `media` extension, so build and
+enable both. 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`.
 
 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.
@@ -84,10 +95,15 @@ software Vulkan driver:
 ```sh
 sudo sh scripts/install-gui-deps.sh   # clang, cmake, X11/Wayland headers, Vulkan, Xvfb
 npm run runtime && npm run gui
+npm run media                         # optional: <video>/<audio> playback
 xvfb-run -a --server-args="-screen 0 1280x720x24" \
   npx tsx src/cli/main.ts run examples/gui/hello.ts --ext gui
 ```
 
+The media e2e suite (`tests/e2e/gui-media.test.ts`) skips itself unless both
+`gui.a` and `media.a` exist; `tests/e2e/gui-media-disabled.test.ts` covers the
+GUI-only build and runs with `gui.a` alone.
+
 `scripts/install-gui-deps.sh` holds the package list (`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

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,

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/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。** 元素句柄直接暴露媒体接口（见