xbintsc 0.5.45 → 0.5.52

package/scripts/build-gui.ts

@@ -12,16 +12,21 @@
  * Steps:
  *   1. fetch the pinned SDL3 source into `vendor/SDL` (gitignored),
  *   2. build `libSDL3.a` with CMake,
- *   2b. fetch + build static FreeType and HarfBuzz for text,
- *   2c. fetch + build static glslang (GLSL ES -> SPIR-V) and SPIRV-Cross
+ *   2a. fetch + build static HarfBuzz and FreeType for the optional `shaping`
+ *       feature; the default text path uses the bundled stb_truetype,
+ *   2b. fetch + build static glslang (GLSL ES -> SPIR-V) and SPIRV-Cross
  *       (SPIR-V -> Metal Shading Language),
  *   3. compile the engine translation units,
  *   4. merge everything into `gui.a` (libtool on macOS, `ar -M` elsewhere;
  *      `gui.lib` on Windows, built from MSVC-compatible COFF objects).
  *
- * Media decoding is *not* part of this archive: it lives in the separate
- * `media` extension (`npm run media`, `runtime/ext_media/`), so a program that
- * only renders HTML/CSS never links FFmpeg.
+ * Media decoding is *not* part of this archive: it is an optional link feature
+ * of the `gui` extension (`npm run media`, `runtime/ext_media/`), so a program
+ * that only renders HTML/CSS never links FFmpeg.
+ *
+ * Every library and every engine object is compiled with function/data sections;
+ * SDL is configured without the subsystems the engine never calls. The linker's
+ * dead-section pass can then drop whatever a particular program does not reach.
  *
  * Environment:
  *   xbintsc_CXX    C++ compiler override (default: clang++ next to the resolved clang)
@@ -46,14 +51,21 @@ import { fileURLToPath } from "node:url";
 import { platformSlug } from "../src/driver/paths.js";
 import { isMsvcTarget, probeClang, realRunner } from "../src/driver/toolchain.js";
 import { resolveToolchain } from "../src/driver/toolchain-provider.js";
+import {
+  cmakeToolchainArgs,
+  HB_LEAN_DEFINES,
+  LEAN_SDL_OPTIONS,
+  SECTION_CMAKE_FLAGS,
+  SECTION_FLAGS,
+} from "./gui-build-options.js";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const runtimeDir = join(root, "runtime");
 const engineDir = join(runtimeDir, "ext_gui");
 const vendorDir = join(root, "vendor");
 const sdlSrc = join(vendorDir, "SDL");
-/* SDL's build tree is a *sibling* of its source, like FreeType's and HarfBuzz's,
- * never inside it: the CI cache keyed on a vendored library ships the whole
+/* SDL's build tree is a *sibling* of its source, like glslang's, never inside
+ * it: the CI cache keyed on a vendored library ships the whole
  * `vendor/SDL` tree, and a CMake build tree is not relocatable across machines
  * or platforms. `CMakeCache.txt` records the host's compiler and probes, and
  * SDL's video options are `option()`s — the first configure to run wins, so a
@@ -61,22 +73,25 @@ const sdlSrc = join(vendorDir, "SDL");
  * default is OFF) survives into a Linux configure and SDL then aborts with
  * "SDL could not find X11 or Wayland development libraries". Keeping the build
  * tree out of the cached source path makes each machine configure its own. */
-const sdlBuild = join(vendorDir, "sdl-build");
+const sdlBuild = join(vendorDir, "sdl-build-lean");
+/* HarfBuzz + FreeType are only linked when the optional `shaping` feature is
+ * active; the archive is still built once so the default text path needs no
+ * external dependency. */
 const freetypeSrc = join(vendorDir, "freetype");
-const freetypeBuild = join(vendorDir, "freetype-build");
+const freetypeBuild = join(vendorDir, "freetype-build-lean");
 const harfbuzzSrc = join(vendorDir, "harfbuzz");
-const harfbuzzBuild = join(vendorDir, "harfbuzz-build");
+const harfbuzzBuild = join(vendorDir, "harfbuzz-build-lean");
 /* glslang translates the GLSL ES that WebGL programs supply at run time; it is
  * built statically and merged into the archive, so a compiled binary needs no
  * Vulkan SDK. The SPIR-V headers are its only external dependency. */
 const glslangSrc = join(vendorDir, "glslang");
-const glslangBuild = join(vendorDir, "glslang-build");
+const glslangBuild = join(vendorDir, "glslang-build-lean");
 const spirvHeadersSrc = join(glslangSrc, "External", "spirv-headers");
 /* SPIRV-Cross turns the same SPIR-V into the Metal Shading Language that
  * SDL_GPU's Metal backend consumes at run time (macOS). It needs no external
  * headers: its own parser reads the module that glslang produced. */
 const spirvCrossSrc = join(vendorDir, "spirv-cross");
-const spirvCrossBuild = join(vendorDir, "spirv-cross-build");
+const spirvCrossBuild = join(vendorDir, "spirv-cross-build-lean");
 const objDir = join(root, "build", "gui-obj");
 const outDir = join(runtimeDir, "lib", platformSlug());
 
@@ -84,41 +99,6 @@ const isWindows = process.platform === "win32";
 const objectSuffix = isWindows ? ".obj" : ".o";
 const output = join(outDir, isWindows ? "gui.lib" : "gui.a");
 
-/* CMake generator and ABI settings used for every vendored library. Ninja is
- * selected on Windows because the Visual Studio generator imports the
- * machine-wide MSBuild/vcpkg integration, whose `LIBPATH` shadows the Windows
- * SDK and makes the compiler probe fail with
- * `LNK1104: cannot open file 'ucrtd.lib'`.
- *
- * `CMAKE_MSVC_RUNTIME_LIBRARY` is pinned to the *static* CRT (`MultiThreaded`),
- * which is clang's Windows default (`-defaultlib:libcmt`) and what xbintsc uses
- * for its own runtime objects. Building the vendored libraries against the DLL
- * CRT instead fails the final link with
- * `LNK2038: mismatch detected for 'RuntimeLibrary'`. The variable only takes
- * effect when policy CMP0091 is NEW, but FreeType and HarfBuzz declare
- * `cmake_minimum_required` below 3.15, which defaults the policy to OLD and
- * silently ignores it — hence `CMAKE_POLICY_DEFAULT_CMP0091`.
- *
- * The tool paths are absolute and come from the same clang the driver resolves
- * (on Windows, the LLVM bundled with Visual Studio when no newer one is on
- * `PATH`), so every object merged into the archive shares one ABI and one
- * optimization behaviour. Never leave these as bare `clang`/`clang++`: an older
- * compiler earlier on `PATH` may be picked up at build time. */
-function cmakeToolchainArgs(): string[] {
-  const compilers = [
-    `-DCMAKE_C_COMPILER=${clang}`,
-    `-DCMAKE_CXX_COMPILER=${clangxx}`,
-  ];
-  if (!isWindows) return compilers;
-  return [
-    "-G", "Ninja",
-    "-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded",
-    "-DCMAKE_POLICY_DEFAULT_CMP0091=NEW",
-    ...compilers,
-    `-DCMAKE_AR=${llvmAr}`,
-  ];
-}
-
 const SDL_TAG = process.env.SDL3_TAG || "release-3.2.10";
 const FREETYPE_VERSION = process.env.FREETYPE_VERSION || "2.13.3";
 const HARFBUZZ_VERSION = process.env.HARFBUZZ_VERSION || "10.1.0";
@@ -274,7 +254,7 @@ function configureCmake(
     rmSync(build, { recursive: true, force: true });
   }
   const cmake = findCmake();
-  run(cmake, ["-S", source, "-B", build, ...cmakeToolchainArgs(), ...extraArgs]);
+  run(cmake, ["-S", source, "-B", build, ...cmakeToolchainArgs({ clang, clangxx, llvmAr, isWindows }), ...extraArgs]);
   return cmake;
 }
 
@@ -318,7 +298,7 @@ function firstExisting(candidates: readonly string[]): string | undefined {
 }
 
 /** Locate a library CMake produced, accepting the POSIX and MSVC names and
- * falling back to a version-suffixed MSVC name (e.g. `freetype-2.13.3.lib`). */
+ * falling back to a version-suffixed MSVC name. */
 function builtLibrary(buildDir: string, names: readonly string[], pattern?: RegExp): string | undefined {
   const candidates: string[] = [];
   for (const name of names) {
@@ -398,6 +378,8 @@ if (!existingSdlArchive) {
     "-DSDL_STATIC=ON",
     "-DSDL_TESTS=OFF",
     "-DSDL_EXAMPLES=OFF",
+    ...LEAN_SDL_OPTIONS,
+    ...SECTION_CMAKE_FLAGS,
   ]);
   console.log(`xbintsc: building static SDL3 with ${cmake}`);
   run(cmake, ["--build", sdlBuild, "--config", "Release", "--target", "SDL3-static", "--parallel"]);
@@ -405,27 +387,7 @@ if (!existingSdlArchive) {
   console.log(`xbintsc: reusing existing ${existingSdlArchive}`);
 }
 
-/* -- 2b. FreeType + HarfBuzz (text) --------------------------------------- */
-
-/** Download a release tarball into `vendor/` and extract it under `name`.
- * Release tarballs are used (not git clones) because they ship generated
- * sources, so no ragel/autotools step is needed. `marker` is a file that only
- * exists once the tarball has been extracted (e.g. `CMakeLists.txt`). */
-function ensureTarballSource(name: string, url: string, extractedName: string, marker = "CMakeLists.txt"): string {
-  const destination = join(vendorDir, name);
-  if (existsSync(join(destination, marker))) return destination;
-  const tarball = join(vendorDir, `${name}.tar.xz`);
-  console.log(`xbintsc: fetching ${name} from ${url}`);
-  mkdirSync(vendorDir, { recursive: true });
-  run("curl", ["-sL", "--fail", "-o", tarball, url]);
-  run("tar", ["-xf", tarball, "-C", vendorDir]);
-  const extracted = join(vendorDir, extractedName);
-  if (!existsSync(extracted)) fail(`expected ${extractedName} after extracting ${name}`);
-  rmSync(destination, { recursive: true, force: true });
-  renameSync(extracted, destination);
-  rmSync(tarball, { force: true });
-  return destination;
-}
+/* -- 2a. HarfBuzz + FreeType (optional `shaping` feature) ---------------- */
 
 ensureTarballSource("freetype", FREETYPE_URL, `freetype-${FREETYPE_VERSION}`);
 ensureTarballSource("harfbuzz", HARFBUZZ_URL, `harfbuzz-${HARFBUZZ_VERSION}`);
@@ -440,6 +402,7 @@ if (!existsSync(freetypeArchive() ?? "")) {
     "-DFT_DISABLE_PNG=TRUE",
     "-DFT_DISABLE_HARFBUZZ=TRUE",
     "-DFT_DISABLE_BROTLI=TRUE",
+    ...SECTION_CMAKE_FLAGS,
   ]);
   console.log("xbintsc: building static FreeType");
   run(cmake, ["--build", freetypeBuild, "--config", "Release", "--parallel"]);
@@ -458,6 +421,8 @@ if (!existsSync(harfbuzzArchive() ?? "")) {
     "-DHB_HAVE_GLIB=OFF",
     "-DHB_HAVE_ICU=OFF",
     "-DHB_HAVE_GRAPHITE2=OFF",
+    `-DCMAKE_C_FLAGS=${SECTION_FLAGS.join(" ")}`,
+    `-DCMAKE_CXX_FLAGS=${[...HB_LEAN_DEFINES, ...SECTION_FLAGS].join(" ")}`,
   ]);
   console.log("xbintsc: building static HarfBuzz");
   run(cmake, ["--build", harfbuzzBuild, "--config", "Release", "--parallel"]);
@@ -465,7 +430,27 @@ if (!existsSync(harfbuzzArchive() ?? "")) {
   console.log(`xbintsc: reusing existing ${harfbuzzArchive()}`);
 }
 
-/* -- 2c. glslang (WebGL GLSL ES -> SPIR-V) -------------------------------- */
+/** Download a release tarball into `vendor/` and extract it under `name`.
+ * Release tarballs are used (not git clones) because they ship generated
+ * sources, so no ragel/autotools step is needed. `marker` is a file that only
+ * exists once the tarball has been extracted (e.g. `CMakeLists.txt`). */
+function ensureTarballSource(name: string, url: string, extractedName: string, marker = "CMakeLists.txt"): string {
+  const destination = join(vendorDir, name);
+  if (existsSync(join(destination, marker))) return destination;
+  const tarball = join(vendorDir, `${name}.tar.xz`);
+  console.log(`xbintsc: fetching ${name} from ${url}`);
+  mkdirSync(vendorDir, { recursive: true });
+  run("curl", ["-sL", "--fail", "-o", tarball, url]);
+  run("tar", ["-xf", tarball, "-C", vendorDir]);
+  const extracted = join(vendorDir, extractedName);
+  if (!existsSync(extracted)) fail(`expected ${extractedName} after extracting ${name}`);
+  rmSync(destination, { recursive: true, force: true });
+  renameSync(extracted, destination);
+  rmSync(tarball, { force: true });
+  return destination;
+}
+
+/* -- 2b. glslang (WebGL GLSL ES -> SPIR-V) -------------------------------- */
 
 ensureTarballSource("glslang", GLSLANG_URL, `glslang-${GLSLANG_VERSION}`);
 ensureTarballSource(join("glslang", "External", "spirv-headers"), SPIRV_HEADERS_URL,
@@ -479,6 +464,7 @@ if (!existsSync(glslangArchive() ?? "")) {
     "-DENABLE_HLSL=OFF",
     "-DENABLE_GLSLANG_BINARIES=OFF",
     "-DGLSLANG_TESTS=OFF",
+    ...SECTION_CMAKE_FLAGS,
   ]);
   console.log("xbintsc: building static glslang");
   run(cmake, ["--build", glslangBuild, "--config", "Release", "--parallel"]);
@@ -488,25 +474,35 @@ if (!existsSync(glslangArchive() ?? "")) {
 
 /* -- 2d. SPIRV-Cross (SPIR-V -> Metal Shading Language) ------------------- */
 
-ensureTarballSource("spirv-cross", SPIRV_CROSS_URL, `SPIRV-Cross-${SPIRV_CROSS_VERSION}`);
-
-if (!existsSync(spirvCrossArchive("spirv-cross-msl") ?? "")) {
-  const cmake = configureCmake("SPIRV-Cross", spirvCrossSrc, spirvCrossBuild, [
-    "-DCMAKE_BUILD_TYPE=Release",
-    "-DSPIRV_CROSS_CLI=OFF",
-    "-DSPIRV_CROSS_ENABLE_TESTS=OFF",
-    /* Only the MSL target is used; skip the C++, HLSL, reflection and C APIs
-     * so the archive stays small. MSL links against the GLSL base class. */
-    "-DSPIRV_CROSS_ENABLE_HLSL=OFF",
-    "-DSPIRV_CROSS_ENABLE_CPP=OFF",
-    "-DSPIRV_CROSS_ENABLE_REFLECT=OFF",
-    "-DSPIRV_CROSS_ENABLE_UTIL=OFF",
-    "-DSPIRV_CROSS_ENABLE_C_API=OFF",
-  ]);
-  console.log("xbintsc: building static SPIRV-Cross");
-  run(cmake, ["--build", spirvCrossBuild, "--config", "Release", "--parallel"]);
-} else {
-  console.log(`xbintsc: reusing existing ${spirvCrossArchive("spirv-cross-msl")}`);
+/* Metal is the only SDL_GPU backend that consumes MSL; Vulkan takes the SPIR-V
+ * module directly and D3D12 falls back to the ordinary painter. A non-Apple
+ * build therefore never calls `cross_compile_msl` (`webgl_msl.cpp` compiles to
+ * nothing there), so fetching and merging the archive would only add ~2.5 MiB
+ * of unreachable code to every Windows/Linux product. */
+const metalBackend = process.platform === "darwin";
+
+if (metalBackend) {
+  ensureTarballSource("spirv-cross", SPIRV_CROSS_URL, `SPIRV-Cross-${SPIRV_CROSS_VERSION}`);
+
+  if (!existsSync(spirvCrossArchive("spirv-cross-msl") ?? "")) {
+    const cmake = configureCmake("SPIRV-Cross", spirvCrossSrc, spirvCrossBuild, [
+      "-DCMAKE_BUILD_TYPE=Release",
+      "-DSPIRV_CROSS_CLI=OFF",
+      "-DSPIRV_CROSS_ENABLE_TESTS=OFF",
+      /* Only the MSL target is used; skip the C++, HLSL, reflection and C APIs
+       * so the archive stays small. MSL links against the GLSL base class. */
+      "-DSPIRV_CROSS_ENABLE_HLSL=OFF",
+      "-DSPIRV_CROSS_ENABLE_CPP=OFF",
+      "-DSPIRV_CROSS_ENABLE_REFLECT=OFF",
+      "-DSPIRV_CROSS_ENABLE_UTIL=OFF",
+      "-DSPIRV_CROSS_ENABLE_C_API=OFF",
+      ...SECTION_CMAKE_FLAGS,
+    ]);
+    console.log("xbintsc: building static SPIRV-Cross");
+    run(cmake, ["--build", spirvCrossBuild, "--config", "Release", "--parallel"]);
+  } else {
+    console.log(`xbintsc: reusing existing ${spirvCrossArchive("spirv-cross-msl")}`);
+  }
 }
 
 /* -- 3. engine objects ---------------------------------------------------- */
@@ -520,14 +516,14 @@ const includeFlags = [
   "-I", join(harfbuzzSrc, "src"),
   "-I", glslangSrc,
   "-I", join(spirvHeadersSrc, "include"),
-  "-I", spirvCrossSrc,
+  ...(metalBackend ? ["-I", spirvCrossSrc] : []),
 ];
 const sources = readdirSync(engineDir)
   .filter((entry) => entry.endsWith(".cpp"))
   .sort();
 
 const objects: string[] = [];
-const cxxFlags = ["-std=c++17", "-O2", "-Wall", "-Wextra", ...includeFlags];
+const cxxFlags = ["-std=c++17", "-O2", "-Wall", "-Wextra", ...SECTION_FLAGS, ...includeFlags];
 /* The engine is C++ and the MSVC C++ runtime must match the static C CRT that
  * clang links by default, so let every engine object record `libcpmt` as a
  * default library. The extension itself only contributes the DLL import library
@@ -550,16 +546,19 @@ const freetype = freetypeArchive();
 const harfbuzz = harfbuzzArchive();
 const glslang = glslangArchive();
 const glslangLimits = glslangLimitsArchive();
-const spirvCrossCore = spirvCrossArchive("spirv-cross-core");
-const spirvCrossGlsl = spirvCrossArchive("spirv-cross-glsl");
-const spirvCrossMsl = spirvCrossArchive("spirv-cross-msl");
+const spirvCrossCore = metalBackend ? spirvCrossArchive("spirv-cross-core") : undefined;
+const spirvCrossGlsl = metalBackend ? spirvCrossArchive("spirv-cross-glsl") : undefined;
+const spirvCrossMsl = metalBackend ? spirvCrossArchive("spirv-cross-msl") : undefined;
 if (!sdl || !freetype || !harfbuzz || !glslang || !glslangLimits ||
-    !spirvCrossCore || !spirvCrossGlsl || !spirvCrossMsl) {
-  fail("one of the SDL3/FreeType/HarfBuzz/glslang/SPIRV-Cross archives was not found after building");
+    (metalBackend && (!spirvCrossCore || !spirvCrossGlsl || !spirvCrossMsl))) {
+  fail(`one of the SDL3/FreeType/HarfBuzz/glslang${metalBackend ? "/SPIRV-Cross" : ""} ` +
+    "archives was not found after building");
 }
 const libraries = [
   sdl, freetype, harfbuzz, glslang, glslangLimits,
-  spirvCrossCore, spirvCrossGlsl, spirvCrossMsl,
+  ...(spirvCrossCore && spirvCrossGlsl && spirvCrossMsl
+    ? [spirvCrossCore, spirvCrossGlsl, spirvCrossMsl]
+    : []),
 ];
 
 mkdirSync(outDir, { recursive: true });

package/scripts/check-file-length.ts

@@ -38,6 +38,7 @@ const IGNORED_DIRECTORIES = new Set([
 /** Vendored third-party sources that ship verbatim and are not ours to split. */
 const VENDORED_FILES = new Set([
   join("runtime", "ext_gui", "stb_image.h"),
+  join("runtime", "ext_gui", "stb_truetype.h"),
   join("runtime", "ext_gui", "nanosvg.h"),
   join("runtime", "ext_gui", "nanosvgrast.h"),
 ]);

package/scripts/gui-build-options.ts

@@ -0,0 +1,122 @@
+/**
+ * Size options shared by the GUI archive build.
+ *
+ * Kept apart from `build-gui.ts` so the orchestration stays under the
+ * repository's per-file line budget and the "what do we compile out?" policy is
+ * reviewable in one place.
+ */
+
+/**
+ * CMake generator and ABI settings used for every vendored library. Ninja is
+ * selected on Windows because the Visual Studio generator imports the
+ * machine-wide MSBuild/vcpkg integration, whose `LIBPATH` shadows the Windows
+ * SDK and makes the compiler probe fail with
+ * `LNK1104: cannot open file 'ucrtd.lib'`.
+ *
+ * `CMAKE_MSVC_RUNTIME_LIBRARY` is pinned to the *static* CRT (`MultiThreaded`),
+ * which is clang's Windows default (`-defaultlib:libcmt`) and what xbintsc uses
+ * for its own runtime objects. Building the vendored libraries against the DLL
+ * CRT instead fails the final link with
+ * `LNK2038: mismatch detected for 'RuntimeLibrary'`. The variable only takes
+ * effect when policy CMP0091 is NEW, but some vendored projects declare
+ * `cmake_minimum_required` below 3.15, which defaults the policy to OLD and
+ * silently ignores it — hence `CMAKE_POLICY_DEFAULT_CMP0091`.
+ *
+ * The tool paths are absolute and come from the same clang the driver resolves
+ * (on Windows, the LLVM bundled with Visual Studio when no newer one is on
+ * `PATH`), so every object merged into the archive shares one ABI and one
+ * optimization behaviour. Never leave these as bare `clang`/`clang++`: an older
+ * compiler earlier on `PATH` may be picked up at build time.
+ */
+export function cmakeToolchainArgs(toolchain: {
+  readonly clang: string;
+  readonly clangxx: string;
+  readonly llvmAr: string;
+  readonly isWindows: boolean;
+}): string[] {
+  const compilers = [
+    `-DCMAKE_C_COMPILER=${toolchain.clang}`,
+    `-DCMAKE_CXX_COMPILER=${toolchain.clangxx}`,
+  ];
+  if (!toolchain.isWindows) return compilers;
+  return [
+    "-G", "Ninja",
+    "-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded",
+    "-DCMAKE_POLICY_DEFAULT_CMP0091=NEW",
+    ...compilers,
+    `-DCMAKE_AR=${toolchain.llvmAr}`,
+  ];
+}
+
+/** One function/data item per section, so the linker can drop what a program
+ * never references (`--gc-sections`, `-dead_strip`, link.exe `/OPT:REF`). */
+export const SECTION_FLAGS = ["-ffunction-sections", "-fdata-sections"] as const;
+
+/** The same flags as CMake cache entries. */
+export const SECTION_CMAKE_FLAGS = [
+  `-DCMAKE_C_FLAGS=${SECTION_FLAGS.join(" ")}`,
+  `-DCMAKE_CXX_FLAGS=${SECTION_FLAGS.join(" ")}`,
+];
+
+/**
+ * HarfBuzz APIs the engine never uses (draw/paint/color/name/style/metrics/…).
+ * `HB_NO_CFF`, `HB_NO_OPEN`, `HB_NO_VAR` and `HB_NO_HINTING` are deliberately
+ * *not* set: the shaping backend must load files and keep CFF/OTF and
+ * variable-font shaping. `HB_NO_MT` is safe because text is shaped on the main
+ * thread.
+ *
+ * `HB_NO_PRAGMA_GCC_DIAGNOSTIC_ERROR` is needed because HarfBuzz raises its
+ * "should never happen" warning set to errors inside `src/hb.hh`, *after* the
+ * command line, so a lean define that leaves a helper unreferenced becomes a
+ * hard compile error. macOS is where that bites: `HB_NO_MMAP` leaves
+ * `_open_resource_fork` unused (`hb-blob.cc`) and `HB_NO_OT_FONT_GLYPH_NAMES`
+ * leaves the CoreText glyph-name helpers unused (`hb-coretext-font.cc`). With
+ * this define they are warnings again; every other lean define still applies.
+ */
+export const HB_LEAN_DEFINES = [
+  "-DHB_NO_PRAGMA_GCC_DIAGNOSTIC_ERROR",
+  "-DHB_NO_DRAW",
+  "-DHB_NO_PAINT",
+  "-DHB_NO_COLOR",
+  "-DHB_NO_NAME",
+  "-DHB_NO_STYLE",
+  "-DHB_NO_METRICS",
+  "-DHB_NO_MATH",
+  "-DHB_NO_META",
+  "-DHB_NO_BITMAP",
+  "-DHB_NO_VERTICAL",
+  "-DHB_NO_BUFFER_SERIALIZE",
+  "-DHB_NO_BUFFER_VERIFY",
+  "-DHB_NO_FACE_COLLECT_UNICODES",
+  "-DHB_NO_MMAP",
+  "-DHB_NO_OT_FONT_GLYPH_NAMES",
+  "-DHB_NO_LAYOUT_FEATURE_PARAMS",
+  "-DHB_NO_LAYOUT_COLLECT_GLYPHS",
+  "-DHB_NO_ERRNO",
+  "-DHB_NO_LANGUAGE_LONG",
+  "-DHB_NO_LANGUAGE_PRIVATE_SUBTAG",
+  "-DHB_NO_MT",
+  "-DHB_NO_ATEXIT",
+  "-DHB_NO_GETENV",
+  "-DHB_NO_SETLOCALE",
+];
+
+/**
+ * SDL subsystems the GUI engine never calls. Disabling them removes whole
+ * translation units (joystick/gamepad/HIDAPI, haptics, sensors, camera, the
+ * SDL_Render software blitter and the OpenGL/offscreen video drivers) from the
+ * static archive. Audio, video, events, dialogs and SDL_GPU stay enabled.
+ */
+export const LEAN_SDL_OPTIONS = [
+  "-DSDL_JOYSTICK=OFF",
+  "-DSDL_HAPTIC=OFF",
+  "-DSDL_SENSOR=OFF",
+  "-DSDL_CAMERA=OFF",
+  "-DSDL_RENDER=OFF",
+  "-DSDL_OPENGL=OFF",
+  "-DSDL_OPENGLES=OFF",
+  "-DSDL_OFFSCREEN=OFF",
+  "-DSDL_HIDAPI=OFF",
+  "-DSDL_DIALOG=ON",
+];
+

package/src/cli/extensions.ts

@@ -0,0 +1,72 @@
+/**
+ * Extension-set construction for the CLI.
+ *
+ * `buildRegistry` turns the `--ext` names into a registry; `normalizeExtensions`
+ * keeps the pre-link-feature spelling `--ext media` working by expanding it to
+ * `gui` plus a forced `media` feature. Both live here so `main.ts` stays under
+ * the repository's per-file line budget.
+ */
+
+import { bundledExtensions } from "../extensions/catalog.js";
+import { nativeExtensionFromManifest } from "../extensions/native.js";
+import { createDefaultRegistry, type ExtensionRegistry } from "../extensions/registry.js";
+
+/** Register the requested bundled extensions and every native manifest. */
+export function buildRegistry(
+  extNames: readonly string[],
+  nativeManifests: readonly string[],
+): ExtensionRegistry {
+  const registry = createDefaultRegistry();
+  const bundled = bundledExtensions();
+  for (const name of extNames) {
+    const extension = bundled.find((candidate) => candidate.name === name);
+    if (!extension) throw new Error(`Unknown extension '${name}'`);
+    registry.register(extension);
+  }
+  // Each manifest describes a pre-built C++ or Rust library.
+  for (const manifest of nativeManifests) {
+    registry.register(nativeExtensionFromManifest(manifest));
+  }
+  // Hint the extensions that ship with xbintsc but were not enabled, so a
+  // missing `import` of a known module points at the flag that enables it
+  // (`pass --ext node`) instead of failing later with a confusing error.
+  for (const extension of bundled) {
+    if (!registry.has(extension.name)) registry.hintExtension(extension);
+  }
+  return registry;
+}
+
+/** The part of the CLI IO a normalization warning needs. */
+export interface ExtensionWarningSink {
+  stderr(text: string): void;
+}
+
+/**
+ * `--ext media` predates link features: media is now an optional half of `gui`
+ * selected from the program. Keep the old spelling working for one release by
+ * expanding it to `gui` plus a forced `media` feature.
+ */
+export function normalizeExtensions(
+  extNames: readonly string[],
+  io: ExtensionWarningSink,
+): { extensions: string[]; features: string[] } {
+  const extensions: string[] = [];
+  const features: string[] = [];
+  let deprecatedMedia = false;
+  for (const name of extNames) {
+    if (name === "media") {
+      deprecatedMedia = true;
+      if (!features.includes("media")) features.push("media");
+      if (!extensions.includes("gui")) extensions.push("gui");
+      continue;
+    }
+    if (!extensions.includes(name)) extensions.push(name);
+  }
+  if (deprecatedMedia) {
+    io.stderr(
+      "xbintsc: warning: '--ext media' is deprecated; media is auto-detected with --ext gui " +
+        "(use --feature media to force it)\n",
+    );
+  }
+  return { extensions, features };
+}

package/src/cli/help.ts

@@ -25,7 +25,9 @@ Options:
       --out <dir>       Output directory (default: build/)
       --emit <kind>     exe | obj | ir (default: exe)
   -O0..-O3              Optimization level (default: -O2)
-      --ext <names>     Comma separated extensions (e.g. node,gui,media)
+      --ext <names>     Comma separated extensions (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 a project config (default: auto-detect

package/src/cli/hints.ts

@@ -78,9 +78,9 @@ const THROWN_FAILURES: readonly ThrownFailure[] = [
     },
   },
   {
-    /* A dependent extension (`media` needs `gui`) or a missing prebuilt archive
-     * (`gui.a`/`media.a`) both mean "the extension set is not ready", and the
-     * extensions guide explains both the flags and `npm run gui`/`media`. */
+    /* A dependent extension or a missing prebuilt archive (`gui.a`/`media.a`)
+     * both mean "the extension set is not ready", and the extensions guide
+     * explains both the flags and `npm run gui`/`media`. */
     match: /requires the '.*' extension|native library not found/i,
     code: DiagnosticCode.IOError,
     pointer: {
@@ -167,6 +167,12 @@ export function documentationFor(diagnostic: Diagnostic): DocumentationPointer |
         path: DOC_CLI,
       };
 
+    case DiagnosticCode.LinkFeatureUnavailable:
+      return {
+        text: "check the link-feature name, and build its prebuilt archive (`npm run gui` / `npm run media`) if it is missing; choose features with --feature / --no-feature",
+        path: DOC_EXTENSIONS,
+      };
+
     case DiagnosticCode.CircularDependency:
       return {
         text: "xbintsc does not support circular imports; move the shared binding into a third module",