xbintsc 0.5.45 → 0.5.52

package/dist/tests/e2e/gui-webgl-pipeline-cache.test.js

@@ -0,0 +1,120 @@
+/**
+ * End-to-end test for the `gui` extension — WebGL pipeline cache reuse.
+ *
+ * A pipeline is a function of the program, the vertex *layout* and the
+ * fixed-function state. It is not a function of which buffer currently holds
+ * the data, nor of the monotonic counters the engine bumps when a VAO is bound
+ * or a framebuffer is switched. Keying the pipeline cache on those counters
+ * made every draw create a fresh `SDL_GPUGraphicsPipeline` once a frame bound
+ * more than one layout (three.js binds one VAO per geometry): a measured
+ * ~250 pipeline creations per frame, which cost more than the whole rest of
+ * the frame.
+ *
+ * This program draws two triangles whose layouts are identical and whose
+ * buffers differ, alternating the bound buffer every frame. The layout never
+ * changes, so after the first frame the pipeline must come from the cache:
+ * `webglPipelineMisses` may not grow. Before the fix it grew by two per frame.
+ */
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createGuiHarness, guiAvailable } from "./gui-helpers.js";
+const harness = createGuiHarness();
+const PAGE = `
+<html><head><title>webgl pipeline cache</title></head>
+<body style="margin:0">
+  <canvas id="c" width="64" height="64"></canvas>
+</body></html>`;
+describe.skipIf(!guiAvailable)("gui extension — WebGL pipeline cache", () => {
+    beforeAll(() => harness.setup());
+    afterAll(() => harness.cleanup());
+    it("reuses the pipeline when only the bound buffers change", () => {
+        const { value } = harness.compileAndRun("webgl-pipeline-cache", `
+      import { createWindow } from "gui";
+      import page from "./page.html";
+
+      const win = createWindow({ title: "pipeline cache", width: 320, height: 240 });
+      win.loadHTML(page);
+      const out = (name: string, value: any): void => console.log(name + "=" + value);
+
+      let gl: any = null;
+      let position = 0;
+      let buffers: any[] = [];
+
+      /* A triangle in its own buffer: same layout, different data. */
+      const makeBuffer = (center: number): any => {
+        const buffer: any = gl.createBuffer();
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([
+          center - 0.4, -0.4, center + 0.4, -0.4, center, 0.5,
+        ]), gl.STATIC_DRAW);
+        return buffer;
+      };
+
+      let frame = 0;
+      let warm: any = null;
+
+      const tick = (): void => {
+        frame = frame + 1;
+        for (const buffer of buffers) {
+          gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+          gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);
+          gl.drawArrays(gl.TRIANGLES, 0, 3);
+        }
+        /* Frames 1-3 warm the cache (shader translation, the first pipelines and
+         * the one-time GPU setup). From there the layout never changes. */
+        if (frame === 3) warm = win.stats();
+        if (frame < 8) {
+          win.requestAnimationFrame(tick);
+          return;
+        }
+        const now: any = win.stats();
+        out("misses.warm", now.webglPipelineMisses - warm.webglPipelineMisses);
+        out("draws.warm", now.webglDraws - warm.webglDraws);
+        out("misses.total", now.webglPipelineMisses);
+        out("frames", frame);
+        win.close();
+      };
+
+      win.on("ready", () => {
+        const canvas: any = document.getElementById("c");
+        gl = canvas.getContext("webgl");
+        out("webgl", gl != null);
+        if (gl == null) {
+          win.close();
+          return;
+        }
+
+        const vs: any = gl.createShader(gl.VERTEX_SHADER);
+        gl.shaderSource(vs, "attribute vec2 a_pos;" +
+          "void main() { gl_Position = vec4(a_pos, 0.0, 1.0); }");
+        gl.compileShader(vs);
+        const fs: any = gl.createShader(gl.FRAGMENT_SHADER);
+        gl.shaderSource(fs, "precision mediump float;" +
+          "void main() { gl_FragColor = vec4(0.2, 0.6, 1.0, 1.0); }");
+        gl.compileShader(fs);
+
+        const program: any = gl.createProgram();
+        gl.attachShader(program, vs);
+        gl.attachShader(program, fs);
+        gl.linkProgram(program);
+        out("link", gl.getProgramParameter(program, gl.LINK_STATUS));
+        gl.useProgram(program);
+
+        position = gl.getAttribLocation(program, "a_pos");
+        gl.enableVertexAttribArray(position);
+        buffers = [makeBuffer(-0.4), makeBuffer(0.4)];
+        win.requestAnimationFrame(tick);
+      });
+      win.on("close", () => console.log("closed"));
+      `, { files: { "page.html": PAGE }, autocloseMs: 15000, console: true });
+        expect(value("webgl")).toBe("true");
+        expect(value("link")).toBe("true");
+        expect(value("frames")).toBe("8");
+        /* The draw calls really happened. */
+        expect(Number(value("draws.warm"))).toBeGreaterThan(0);
+        /* ... and none of them built a pipeline: the layout is unchanged. */
+        expect(Number(value("misses.warm"))).toBe(0);
+        /* The cache stays bounded: a handful for the whole program. */
+        expect(Number(value("misses.total"))).toBeLessThan(8);
+    });
+});
+//# sourceMappingURL=gui-webgl-pipeline-cache.test.js.map

package/dist/tests/e2e/gui-webgl-pipeline-cache.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gui-webgl-pipeline-cache.test.js","sourceRoot":"","sources":["../../../tests/e2e/gui-webgl-pipeline-cache.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAElE,MAAM,OAAO,GAAG,gBAAgB,EAAE,CAAC;AAEnC,MAAM,IAAI,GAAG;;;;eAIE,CAAC;AAEhB,QAAQ,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC,sCAAsC,EAAE,GAAG,EAAE;IAC1E,SAAS,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAElC,EAAE,CAAC,wDAAwD,EAAE,GAAG,EAAE;QAChE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,aAAa,CACrC,sBAAsB,EACtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8EC,EACD,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CACpE,CAAC;QAEF,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACpC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClC,qCAAqC;QACrC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QACvD,qEAAqE;QACrE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7C,+DAA+D;QAC/D,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/tests/extensions/gui-features.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/extensions/gui-features.test.js

@@ -0,0 +1,175 @@
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+const mocks = vi.hoisted(() => ({ findRuntimeLibrary: vi.fn() }));
+/* Keep the archive lookup deterministic so both the success and the
+ * "not built yet" branches of `nativeObjects` can be exercised. */
+vi.mock("../../src/driver/runtime-lib.js", () => ({
+    findRuntimeLibrary: mocks.findRuntimeLibrary,
+    runtimeLibDir: () => "/tmp/runtime/lib/darwin-x64",
+}));
+vi.mock("../../src/driver/paths.js", () => ({
+    findRuntimeDir: () => "/tmp/runtime",
+    platformSlug: () => "darwin-x64",
+}));
+import { guiExtension } from "../../src/extensions/gui/index.js";
+import { guiLinkFeatures, hasGpuUsage, hasImageUsage, hasMediaUsage, hasShapingUsage, hasWebglUsage, } from "../../src/extensions/gui/features.js";
+afterEach(() => {
+    vi.restoreAllMocks();
+    mocks.findRuntimeLibrary.mockReset();
+});
+/** Build a usage record with the fields a matcher reads. */
+function usage(overrides = {}) {
+    return {
+        strings: [],
+        identifiers: new Set(),
+        getContext: [],
+        dynamicMarkup: false,
+        ...overrides,
+    };
+}
+/** The features in declaration order. */
+const media = guiLinkFeatures.find((feature) => feature.name === "media");
+const gpu = guiLinkFeatures.find((feature) => feature.name === "gpu");
+const images = guiLinkFeatures.find((feature) => feature.name === "images");
+const shaping = guiLinkFeatures.find((feature) => feature.name === "shaping");
+const webgl = guiLinkFeatures.find((feature) => feature.name === "webgl");
+describe("gui link features", () => {
+    it("declares media, gpu, images, shaping and webgl as optional halves of gui", () => {
+        expect(guiExtension.linkFeatures?.()).toBe(guiLinkFeatures);
+        expect(guiLinkFeatures.map((feature) => feature.name)).toEqual([
+            "media",
+            "gpu",
+            "images",
+            "shaping",
+            "webgl",
+        ]);
+        expect(media.description).toMatch(/FFmpeg/);
+        expect(gpu.description).toMatch(/glslang|GLSL/);
+        expect(images.description).toMatch(/stb_image|NanoSVG/);
+        expect(shaping.description).toMatch(/HarfBuzz|FreeType/);
+        expect(webgl.requires).toEqual(["gpu"]);
+    });
+    it("links the media bridge and the prebuilt archive", () => {
+        mocks.findRuntimeLibrary.mockReturnValue("/tmp/media.a");
+        expect(media.runtimeSources?.()).toEqual([join("/tmp/runtime", "ext_media", "media_bridge.c")]);
+        expect(media.nativeObjects?.()).toEqual(["/tmp/media.a"]);
+        expect(mocks.findRuntimeLibrary).toHaveBeenCalledWith("media");
+    });
+    it("links the gpu bridge without an archive (the code is in gui.a)", () => {
+        expect(gpu.runtimeSources?.()).toEqual([join("/tmp/runtime", "ext_gui", "gpu_bridge.c")]);
+        expect(gpu.nativeObjects?.()).toBeUndefined();
+    });
+    it("links the images bridge without an archive", () => {
+        expect(images.runtimeSources?.()).toEqual([join("/tmp/runtime", "ext_gui", "image_bridge.c")]);
+        expect(images.nativeObjects?.()).toBeUndefined();
+    });
+    it("links the shaping bridge without an archive", () => {
+        expect(shaping.runtimeSources?.()).toEqual([join("/tmp/runtime", "ext_gui", "text_bridge.c")]);
+        expect(shaping.nativeObjects?.()).toBeUndefined();
+    });
+    it("links the webgl bridge without an archive", () => {
+        expect(webgl.runtimeSources?.()).toEqual([join("/tmp/runtime", "ext_gui", "webgl_bridge.c")]);
+        expect(webgl.nativeObjects?.()).toBeUndefined();
+    });
+    it("fails with an actionable message when the media archive is missing", () => {
+        mocks.findRuntimeLibrary.mockReturnValue(undefined);
+        expect(() => media.nativeObjects?.()).toThrow(/media native library not found/);
+        expect(() => media.nativeObjects?.()).toThrow(/npm run media/);
+        expect(() => media.nativeObjects?.()).toThrow(/darwin-x64/);
+    });
+    it("adds FFmpeg's Win32 libraries on Windows only", () => {
+        vi.spyOn(process, "platform", "get").mockReturnValue("win32");
+        expect(media.linkerFlags?.()).toEqual(["-lbcrypt", "-lole32", "-luser32"]);
+        vi.restoreAllMocks();
+        vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
+        expect(media.linkerFlags?.()).toEqual(["-lm"]);
+    });
+});
+describe("media usage detection", () => {
+    it("recognises <video>/<audio> tags in HTML strings", () => {
+        expect(hasMediaUsage(usage({ strings: ['<html><video src="x.mp4"></video>'] }))).toBe(true);
+        expect(hasMediaUsage(usage({ strings: ["<audio controls></audio>"] }))).toBe(true);
+    });
+    it("recognises createElement tag names and the Audio constructor", () => {
+        expect(hasMediaUsage(usage({ strings: ["video"] }))).toBe(true);
+        expect(hasMediaUsage(usage({ identifiers: new Set(["Audio"]) }))).toBe(true);
+        expect(hasMediaUsage(usage({ identifiers: new Set(["HTMLVideoElement"]) }))).toBe(true);
+        expect(hasMediaUsage(usage({ identifiers: new Set(["decodeAudioData"]) }))).toBe(true);
+    });
+    it("stays off for a DOM-only page and turns on for dynamic markup", () => {
+        expect(hasMediaUsage(usage({ strings: ["<div>hi</div>"], identifiers: new Set(["document"]) }))).toBe(false);
+        expect(hasMediaUsage(usage({ dynamicMarkup: true }))).toBe(true);
+    });
+});
+describe("gpu usage detection", () => {
+    it("turns on for a WebGL context", () => {
+        expect(hasGpuUsage(usage({ getContext: ["webgl2"] }))).toBe(true);
+        expect(hasGpuUsage(usage({ getContext: ["experimental-webgl"] }))).toBe(true);
+    });
+    it("turns on for a context kind decided at run time", () => {
+        expect(hasGpuUsage(usage({ getContext: [undefined] }))).toBe(true);
+    });
+    it("turns on for mix-blend-mode/backdrop-filter in HTML/CSS or the style property", () => {
+        expect(hasGpuUsage(usage({ strings: ["style=\"mix-blend-mode: multiply\""] }))).toBe(true);
+        expect(hasGpuUsage(usage({ identifiers: new Set(["mixBlendMode"]) }))).toBe(true);
+        expect(hasGpuUsage(usage({ strings: ["backdrop-filter: blur(4px)"] }))).toBe(true);
+        expect(hasGpuUsage(usage({ identifiers: new Set(["backdropFilter"]) }))).toBe(true);
+    });
+    it("stays off for a 2D canvas and plain DOM", () => {
+        expect(hasGpuUsage(usage({ getContext: ["2d"] }))).toBe(false);
+        expect(hasGpuUsage(usage({ strings: ["<canvas id=c></canvas>"] }))).toBe(false);
+    });
+    it("turns on for dynamic markup", () => {
+        expect(hasGpuUsage(usage({ dynamicMarkup: true }))).toBe(true);
+    });
+});
+describe("webgl usage detection", () => {
+    it("turns on only for a WebGL context or a webgl string", () => {
+        expect(hasWebglUsage(usage({ getContext: ["webgl2"] }))).toBe(true);
+        expect(hasWebglUsage(usage({ strings: ["webgl2"] }))).toBe(true);
+        expect(hasWebglUsage(usage({ getContext: [undefined] }))).toBe(true);
+    });
+    it("stays off for a 2D canvas, blend-only CSS and plain DOM", () => {
+        expect(hasWebglUsage(usage({ getContext: ["2d"] }))).toBe(false);
+        expect(hasWebglUsage(usage({ strings: ["mix-blend-mode: multiply"] }))).toBe(false);
+        expect(hasWebglUsage(usage({ strings: ["<canvas id=c></canvas>"] }))).toBe(false);
+    });
+    it("turns on for dynamic markup", () => {
+        expect(hasWebglUsage(usage({ dynamicMarkup: true }))).toBe(true);
+    });
+});
+describe("image usage detection", () => {
+    it("turns on for <img>, CSS backgrounds, SVG and drawImage", () => {
+        expect(hasImageUsage(usage({ strings: ["<img src=a.png>"] }))).toBe(true);
+        expect(hasImageUsage(usage({ strings: ["background-image: url(a.png)"] }))).toBe(true);
+        expect(hasImageUsage(usage({ strings: ["<svg viewBox='0 0 10 10'></svg>"] }))).toBe(true);
+        expect(hasImageUsage(usage({ identifiers: new Set(["drawImage"]) }))).toBe(true);
+    });
+    it("stays off for text-only DOM", () => {
+        expect(hasImageUsage(usage({ strings: ["<div>Hello</div>"] }))).toBe(false);
+        expect(hasImageUsage(usage({ getContext: ["2d"] }))).toBe(false);
+    });
+    it("turns on for dynamic markup", () => {
+        expect(hasImageUsage(usage({ dynamicMarkup: true }))).toBe(true);
+    });
+});
+describe("shaping usage detection", () => {
+    it("turns on for non-ASCII text and escaped/encoded codepoints", () => {
+        expect(hasShapingUsage(usage({ strings: ["<p>中文测试</p>"] }))).toBe(true);
+        expect(hasShapingUsage(usage({ strings: ["café"] }))).toBe(true);
+        expect(hasShapingUsage(usage({ strings: ["\\u4e2d\\u6587"] }))).toBe(true);
+        expect(hasShapingUsage(usage({ strings: ["&#20013;&#25991;"] }))).toBe(true);
+    });
+    it("turns on for author @font-face rules (custom fonts may be CFF/OTF)", () => {
+        expect(hasShapingUsage(usage({
+            strings: ['@font-face { font-family: "X"; src: url("./x.otf"); }'],
+        }))).toBe(true);
+    });
+    it("stays off for ASCII-only text", () => {
+        expect(hasShapingUsage(usage({ strings: ["<div>Hello</div>"] }))).toBe(false);
+    });
+    it("turns on for dynamic markup", () => {
+        expect(hasShapingUsage(usage({ dynamicMarkup: true }))).toBe(true);
+    });
+});
+//# sourceMappingURL=gui-features.test.js.map

package/dist/tests/extensions/gui-features.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gui-features.test.js","sourceRoot":"","sources":["../../../tests/extensions/gui-features.test.ts"],"names":[],"mappings":"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"}

package/doc/ai/cli.md

@@ -47,7 +47,9 @@ so restart it after installing a dependency.
     --out <dir>       Output directory (default: build/)
     --emit <kind>     exe | obj | ir (default: exe)
 -O0 .. -O3            Optimization level passed to clang (default: -O2)
-    --ext <names>     Enable bundled extensions, comma separated (e.g. node,gui,media)
+    --ext <names>     Enable bundled extensions, comma separated (e.g. node,gui)
+    --feature <names> Force optional link features on (media,gpu,images,shaping,webgl,all)
+    --no-feature <n>  Keep optional link features out even when detected
     --ext-native <m>  Register a C++/Rust extension from a JSON manifest
                       (comma separated for several)
     --config <path>   Use this project config instead of discovering one
@@ -121,6 +123,8 @@ matching field. `--no-config` skips discovery entirely.
 | `pgoDir` | string | Profile directory (default `<outDir>/pgo`) |
 | `extensions` | string[] | Bundled extensions to enable, e.g. `["node"]` |
 | `extNative` | string[] | Native extension manifest paths |
+| `features` | string[] | Optional link features to force on, e.g. `["media"]` / `["all"]` |
+| `noFeatures` | string[] | Optional link features to keep out even when detected |
 | `force` | boolean | Ignore the incremental cache |
 | `app.name` / `app.icon` / `app.bundle` / `app.bundleId` | | Application metadata ([icon.md](../icon.md)) |
 

package/doc/ai/extensions.md

@@ -1,8 +1,10 @@
-# Extensions: Node modules, GUI, media, C++/Rust libraries
+# Extensions: Node modules, GUI, link features, C++/Rust libraries
 
 The compiler core is platform-agnostic. Anything platform-specific — Node's
 `fs`, an HTML/CSS renderer, your own C++ library — arrives as an **extension**
 that contributes module bindings plus the C/C++ sources or objects to link.
+Heavy optional halves of an extension (FFmpeg, glslang) are **link features**
+selected from the program instead of separate extension flags.
 
 ## The rule that trips people up
 
@@ -74,8 +76,9 @@ blocks, because the runtime parser only reads inline `<style>`; and it rewrites
 a bundled three.js module's `WebGLRenderer` to use the real WebGL 2 backend:
 only its shader unroller is patched, and no Canvas2D fallback is bundled. It
 ships as a per-platform prebuilt `gui.a`/`gui.lib` because it is C++. `<img>` decodes through the engine
-itself; `<video>`/`<audio>` do **not** work with `gui` alone — they need the
-separate [`media`](#media--videoaudio-decoding) extension. `<canvas>` is
+itself; `<video>`/`<audio>` decoding (FFmpeg) and GLSL translation (glslang) are
+**optional link features** selected from the program — see
+[Optional link features](#optional-link-features-media-gpu-images-shaping-webgl). `<canvas>` is
 supported too: `getContext("2d")` returns a context whose fills, paths,
 gradients, text and `drawImage` are rasterised by a self-written CPU rasteriser
 (plus line caps/joins, dashed strokes, `ellipse` and `roundRect`), and element
@@ -85,9 +88,13 @@ text, images and children in it) can be translated, scaled and rotated without
 reflowing anything — animate it per frame from `requestAnimationFrame` or with
 `transition: transform` (see `examples/gui/pelican-svg`). The CSS subset also
 covers `@media`, `::before`/`::after` generated content, multi-layer linear/radial
-backgrounds, `text-shadow`, `clip-path` and `filter` colour/shadow effects;
-`backdrop-filter` and true group blur are documented approximations or
-unsupported. If the archive is
+backgrounds, `calc()`, `text-shadow`/`box-shadow` with a true Gaussian blur,
+`clip-path`, `filter` colour effects, `backdrop-filter` compositing,
+`@keyframes` and `transition`/`animation` timing functions, `letter-spacing`,
+`text-transform`, inline-level `flex`/`grid`, `grid-area`, `aspect-ratio`, auto
+margins, percentage `border-radius`, `outline`, tiled `background-size` for
+`url()` layers, document CSS on SVG children and text-only vertical writing
+mode. `filter: blur()` is still a documented approximation. If the archive is
 missing for your platform, the build fails with an actionable message; design
 and roadmap live in [../gui.md](../gui.md) (overview; the engine is documented by
 function under [`doc/gui/`](../gui/)), and the scripting surface in
@@ -101,7 +108,7 @@ Pages written for the browser also get the browser globals they reach for —
 (`AudioContext` with gain, oscillator, buffer-source, biquad, compressor,
 stereo-panner, constant-source and delay nodes, a real 48 kHz mixer, per-sample
 AudioParam automation, and `decodeAudioData` for WAV in-engine plus compressed
-formats through `media`) — plus a frame pump that
+formats through the `media` feature) — plus a frame pump that
 starts at `loadHTML` and re-arms only while animation-frame callbacks remain, so
 a page that never calls `run()` still paints and then exits. **WebGL 1.0 and 2.0 are implemented**: `canvas.getContext("webgl")` /
 `"webgl2"` return a GPU context whose GLSL ES shaders are compiled to SPIR-V by
@@ -109,19 +116,47 @@ a bundled glslang — consumed by Vulkan, or cross-compiled to MSL by bundled
 SPIRV-Cross on Metal — and drawn through SDL_GPU; the page composites the colour
 texture without a CPU readback, and WebGL 2 adds VAOs, instancing, integer
 attributes, sampler objects, `texStorage2D` and buffer copies (see
-[../gui/webgl.md](../gui/webgl.md)). WebXR, `<video>`/`<audio>` without
-`media`, and streaming are **not** implemented:
-`typeof` answers `"undefined"` so a page takes its own fallback branch. `fetch`
+[../gui/webgl.md](../gui/webgl.md)). WebXR and streaming are **not**
+implemented: `typeof` answers `"undefined"` so a page takes its own fallback
+branch. `fetch`
 is **not** a GUI extension feature: the core runtime provides it (`http://`,
 plus local `file://` and relative paths; no HTTPS or streaming), so GUI
 programs can use it too. See [../implemented/fetch.md](../implemented/fetch.md).
 
-### `media` — video/audio decoding
-
-Enable with `--ext media` **together with** `gui` (`--ext gui,media`; the
-registry rejects `media` on its own). It links a separate FFmpeg-backed
-`media.a`/`media.lib`, so adding `<video>`/`<audio>` playback does not make a
-GUI-only binary any larger.
+### Optional link features (`media`, `gpu`, `images`, `shaping`, `webgl`)
+
+`gui` is one extension, but its heavy halves are optional **link features**. The
+compiler scans the bundled HTML/CSS/TS (imported `.html` assets and their inlined
+CSS are part of the bundle) and selects them per program; you do not pass an
+extension flag:
+
+- **`media`** — FFmpeg decoding for `<video>`/`<audio>` and compressed
+  `decodeAudioData`. Selected by a `<video>`/`<audio>` element,
+  `createElement("video"/"audio")`, `new Audio()`, `decodeAudioData`, or markup
+  built at run time. Links the FFmpeg-backed `media.a`/`media.lib`.
+- **`gpu`** — the glslang/SPIRV-Cross GLSL translator shared by WebGL and
+  `mix-blend-mode`. Selected by `getContext("webgl"/"webgl2"/…)` (or a context
+  kind decided at run time), any `webgl` string, or `mix-blend-mode`.
+- **`images`** — stb_image/NanoSVG decoding for `<img>`, inline `<svg>`, CSS
+  `background-image`/`url(...)`, `drawImage`/`createImageBitmap`/`Image`, and an
+  app icon. A text-only page links neither decoder.
+- **`shaping`** — HarfBuzz + FreeType for full OpenType shaping (ligatures,
+  complex scripts) and CFF/OTF/variable fonts. Selected automatically for
+  non-ASCII text (or an escaped/entity codepoint) or an author `@font-face`
+  rule; a Latin-only page keeps the stb_truetype backend and links neither
+  library.
+- **`webgl`** — the WebGL context and DOM bindings. Selected by a WebGL
+  `getContext(...)` or a `webgl` string; it requires `gpu`, so both activate
+  together. A page that never asks for WebGL links neither.
+
+Override the scan with `--feature media,gpu,images,shaping,webgl` (or `all`) and keep a
+feature out with `--no-feature media`. `--verbose` prints the selected set. A
+program that only renders HTML/CSS/2D canvas links no FFmpeg, glslang, image
+decoder, HarfBuzz/FreeType or WebGL context; a page that
+builds HTML/CSS from runtime data should pass `--feature all` because the scan
+cannot see it. If an auto-detected feature's archive is missing, the build warns
+and the capability degrades at run time (media elements fire `error`); a forced
+feature makes it an error.
 
 The DOM API is the same as for any HTML media element: `play()` / `pause()` /
 `load()`, the `paused` / `ended` / `duration` / `currentTime` / `volume` /
@@ -129,16 +164,11 @@ The DOM API is the same as for any HTML media element: `play()` / `pause()` /
 `src` properties, and `loadedmetadata`/`play`/`pause`/`ended`/`timeupdate`/
 `error` events. There are no built-in controls — draw your own chrome with
 elements and CSS (see `examples/gui/media.ts`). Video frames and audio PCM are
-decoded on the main thread; video goes through the image texture path. Without
-the extension, opening a media source fails and fires `error` (the element and
-its API still exist). The archive is built for every host: POSIX produces
-`media.a`, while Windows produces `media.lib` from FFmpeg compiled with the
-MSVC-targeting `clang-cl`, so it links with `gui.lib`. Building it on Windows
-needs a POSIX shell (Git for Windows' bundled bash) and a native GNU make
-(Chocolatey `make`, or `xbintsc_MAKE`). See
-[../gui/build.md](../gui/build.md). Without the archive, or on a host where
-`npm run media` has not run, media elements report `error`; see
-[../gui/known-issues.md](../gui/known-issues.md).
+decoded on the main thread; video goes through the image texture path. Building
+the archive on Windows needs a POSIX shell (Git for Windows' bundled bash) and a
+native GNU make (Chocolatey `make`, or `xbintsc_MAKE`). See
+[../gui/build.md](../gui/build.md) and
+[../gui/media.md](../gui/media.md).
 
 ## Third-party npm packages
 

package/doc/ai/troubleshooting.md

@@ -123,15 +123,18 @@ optional `@xbintsc/<os>-<arch>` npm package ships it (reinstall without
 
 ### `media native library not found at …`
 
-`<video>`/`<audio>` playback needs the optional `media` archive (`media.a`, or
-`media.lib` on Windows). The `@xbintsc/<os>-<arch>` npm package ships it where
-the release builds it; otherwise build it 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`, and `--ext media` alone is
-rejected with the flags to pass. On Windows the FFmpeg build additionally needs
+`<video>`/`<audio>` decoding needs the optional `media` link feature and its
+archive (`media.a`, or `media.lib` on Windows). The `@xbintsc/<os>-<arch>` npm
+package ships it where the release builds it; otherwise build it with
+`npm run media`. When the feature is selected automatically and the archive is
+missing, the build prints a **warning** and continues; media elements then simply
+fire `error`. An explicit `--feature media` (or the deprecated `--ext media`)
+makes it a hard error instead. Use `--no-feature media` to opt out on purpose.
+On Windows the FFmpeg build additionally needs
 a POSIX shell (Git for Windows' bash) and a native GNU make (Chocolatey `make`,
 or `xbintsc_MAKE`). The script names whichever is missing. See
-[../gui/build.md](../gui/build.md).
+[../gui/build.md](../gui/build.md) and
+[../gui/build.md#link-features](../gui/build.md#link-features).
 
 ### `Icon file not found` / icon tools missing
 

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

@@ -40,7 +40,9 @@
     --out <dir>       输出目录（默认 build/）
     --emit <kind>     exe | obj | ir（默认 exe）
 -O0 .. -O3            传给 clang 的优化级别（默认 -O2）
-    --ext <names>     开启内置扩展，逗号分隔（如 node,gui,media）
+    --ext <names>     开启内置扩展，逗号分隔（如 node,gui）
+    --feature <names> 强制开启可选链接特性（media,gpu,images,shaping,webgl,all）
+    --no-feature <n>  即使检测到也不链接该可选特性
     --ext-native <m>  通过 JSON 清单注册 C++/Rust 扩展（多个用逗号分隔）
     --config <path>   使用指定项目配置，不做自动发现
     --no-config       完全不读取项目配置
@@ -102,6 +104,8 @@ profile 数据可能独立于源码变化。
 | `pgoDir` | string | Profile 目录（默认 `<outDir>/pgo`） |
 | `extensions` | string[] | 开启的内置扩展，如 `["node"]` |
 | `extNative` | string[] | 原生扩展清单路径 |
+| `features` | string[] | 强制开启的可选链接特性，如 `["media"]` / `["all"]` |
+| `noFeatures` | string[] | 即使检测到也保持关闭的可选链接特性 |
 | `force` | boolean | 忽略增量缓存 |
 | `app.name` / `app.icon` / `app.bundle` / `app.bundleId` | | 应用元信息（[icon.md](../../zh-CN/icon.md)） |