xbintsc 0.5.22 → 0.5.31

package/runtime/xt_containers/objects.inc

@@ -301,12 +301,32 @@ xt_value xt_object_get(xt_value value, xt_value key) {
       if (prop->getter != XT_UNDEFINED) return XT_UNDEFINED;
       return prop->value;
     }
+    /* `class Dog extends Animal` links Dog's property bag to the Animal
+       *constructor*, not to an object prototype, so a lookup of `Dog.kind`
+       must be able to continue through a function value. */
+    if (XT_IS_FUNCTION(cur->prototype)) {
+      xt_object *next = xt_as_object(cur->prototype);
+      if (!next || next == cur) break;
+      cur = next;
+      continue;
+    }
     if (!XT_IS_OBJECT(cur->prototype)) break;
     cur = (xt_object *)XT_GET_PTR(cur->prototype);
   }
   return XT_UNDEFINED;
 }
 
+/* The next link of a prototype chain, or NULL at the end. `class B extends A`
+ * links B's property bag to the *constructor value* A, so the walk has to
+ * continue through a function just like through a plain object. */
+static xt_object *xt_object_prototype_of(xt_value prototype, xt_object *current) {
+  xt_object *next = xt_as_object(prototype);
+  if (!next || next == current) return NULL;
+  if (next->header.kind != XT_OBJECT_KIND_OBJECT && next->header.kind != XT_OBJECT_KIND_ERROR)
+    return NULL;
+  return next;
+}
+
 xt_value xt_object_set(xt_value value, xt_value key, xt_value newValue) {
   if (XT_IS_FUNCTION(value) && xt_key_is_prototype(key)) {
     return xt_function_set_prototype(value, newValue);
@@ -332,7 +352,7 @@ xt_value xt_object_set(xt_value value, xt_value key, xt_value newValue) {
   }
   /* No own property: an inherited accessor still intercepts the assignment
      (JavaScript assigns through prototype setters instead of shadowing). */
-  xt_object *ancestor = XT_IS_OBJECT(obj->prototype) ? (xt_object *)XT_GET_PTR(obj->prototype) : NULL;
+  xt_object *ancestor = xt_object_prototype_of(obj->prototype, obj);
   while (ancestor) {
     xt_property *inherited = xt_object_find(ancestor, k);
     if (inherited) {
@@ -346,7 +366,7 @@ xt_value xt_object_set(xt_value value, xt_value key, xt_value newValue) {
       if (inherited->getter != XT_UNDEFINED) return newValue; /* getter-only accessor */
       break; /* plain inherited data property: create an own shadowing property */
     }
-    ancestor = XT_IS_OBJECT(ancestor->prototype) ? (xt_object *)XT_GET_PTR(ancestor->prototype) : NULL;
+    ancestor = xt_object_prototype_of(ancestor->prototype, ancestor);
   }
   xt_property *inserted = xt_object_insert_property(obj, k);
   inserted->value = newValue;

package/runtime/xt_io/exception.inc

@@ -217,9 +217,11 @@ static xt_value xt_file_url(const char *path) {
   const char *prefix = "file://";
   for (; *prefix; prefix++) url[j++] = *prefix;
 #if defined(_WIN32)
-  url[j++] = '/';
+  url[j++] = XT_ARTIFACT_PATH_SEPARATOR;
 #endif
-  for (const char *p = path; *p && j < sizeof(url) - 1; p++) url[j++] = (*p == '\\') ? '/' : *p;
+  for (const char *p = path; *p && j < sizeof(url) - 1; p++) {
+    url[j++] = (*p == '\\') ? XT_ARTIFACT_PATH_SEPARATOR : *p;
+  }
   url[j] = 0;
   return xt_string_from_cstr(url);
 }

package/runtime/xt_stdlib/math.inc

@@ -70,3 +70,65 @@ xt_value xt_math_call(xt_value name, int32_t argc, xt_value *argv) {
   return xt_number(NAN);
 }
 
+
+/* -- first-class Math ------------------------------------------------------ */
+
+/* `Math` is lowered to `xt_math_call` at call sites, but it is also an object
+ * in JavaScript: `const cos = Math.cos`, `[1, 2].map(Math.max)` and
+ * `const { sqrt, PI } = Math` all read members as values. The singleton below
+ * holds one native closure per function, plus the constants. */
+
+/* `M_PI` and friends are not portable: MSVC's `<math.h>` only defines them
+ * when `_USE_MATH_DEFINES` is set before the include, and strict-ANSI libcs
+ * hide them as well. Each literal below is the correctly rounded double of the
+ * mathematical constant, so it is bit-identical to the `M_*` macro on hosts
+ * that do provide one. */
+static const double XT_MATH_PI = 3.14159265358979323846;
+static const double XT_MATH_E = 2.71828182845904523536;
+static const double XT_MATH_LN2 = 0.69314718055994530942;
+static const double XT_MATH_LN10 = 2.30258509299404568402;
+static const double XT_MATH_LOG2E = 1.44269504088896340736;
+static const double XT_MATH_LOG10E = 0.43429448190325182765;
+static const double XT_MATH_SQRT2 = 1.41421356237309504880;
+static const double XT_MATH_SQRT1_2 = 0.70710678118654752440;
+
+static const char *const XT_MATH_FUNCTIONS[] = {
+    "abs",    "floor",  "ceil",    "round", "trunc", "sqrt",  "cbrt",  "pow",
+    "exp",    "log",    "log2",    "log10", "log1p", "expm1", "sinh",  "cosh",
+    "tanh",   "asinh",  "acosh",   "atanh", "fround", "imul", "clz32", "sin",
+    "cos",    "tan",    "asin",    "acos",  "atan",  "atan2", "hypot", "sign",
+    "random", "min",    "max",
+};
+
+static xt_value g_math_object;
+
+static xt_value xt_math_bridge(xt_value thisValue, xt_value env, int32_t argc, xt_value *argv) {
+  (void)thisValue;
+  return xt_math_call(xt_closure_env(env, 0), argc, argv);
+}
+
+xt_value xt_math_object(int32_t argc, xt_value *argv) {
+  (void)argc;
+  (void)argv;
+  if (g_math_object != 0) return g_math_object;
+  xt_value object = xt_object_new();
+  for (size_t i = 0; i < sizeof(XT_MATH_FUNCTIONS) / sizeof(XT_MATH_FUNCTIONS[0]); i++) {
+    /* The closure environment owns its own copy: the string is stored by the
+     * object, but a rooted value is cheap and keeps the lifetime obvious. */
+    xt_value name = xt_string_from_cstr(XT_MATH_FUNCTIONS[i]);
+    xt_value closure = xt_closure_new((void *)xt_math_bridge, 1, &name);
+    xt_function_set_metadata(closure, name, 1);
+    xt_object_set(object, name, closure);
+  }
+  xt_object_set(object, xt_string_from_cstr("PI"), xt_number(XT_MATH_PI));
+  xt_object_set(object, xt_string_from_cstr("E"), xt_number(XT_MATH_E));
+  xt_object_set(object, xt_string_from_cstr("LN2"), xt_number(XT_MATH_LN2));
+  xt_object_set(object, xt_string_from_cstr("LN10"), xt_number(XT_MATH_LN10));
+  xt_object_set(object, xt_string_from_cstr("LOG2E"), xt_number(XT_MATH_LOG2E));
+  xt_object_set(object, xt_string_from_cstr("LOG10E"), xt_number(XT_MATH_LOG10E));
+  xt_object_set(object, xt_string_from_cstr("SQRT2"), xt_number(XT_MATH_SQRT2));
+  xt_object_set(object, xt_string_from_cstr("SQRT1_2"), xt_number(XT_MATH_SQRT1_2));
+  g_math_object = object;
+  xt_gc_add_root(&g_math_object);
+  return object;
+}

package/runtime/xt_stdlib2/date.inc

@@ -138,7 +138,13 @@ xt_value xt_date_static(xt_value name, int32_t argc, xt_value *argv) {
     tm.tm_year = xt_to_int32(xt_arg_at(argc, argv, 0)) - 1900;
     tm.tm_mon = xt_to_int32(xt_arg_at(argc, argv, 1));
     tm.tm_mday = argc > 2 ? xt_to_int32(xt_arg_at(argc, argv, 2)) : 1;
-    return xt_number((double)xt_timegm(&tm) * 1000.0);
+    /* Date.UTC(year, month[, day[, hour[, minute[, second[, ms]]]]]). The time
+     * fields used to be dropped, so every UTC date came back at midnight. */
+    tm.tm_hour = argc > 3 ? xt_to_int32(xt_arg_at(argc, argv, 3)) : 0;
+    tm.tm_min = argc > 4 ? xt_to_int32(xt_arg_at(argc, argv, 4)) : 0;
+    tm.tm_sec = argc > 5 ? xt_to_int32(xt_arg_at(argc, argv, 5)) : 0;
+    double millis = argc > 6 ? xt_to_int32(xt_arg_at(argc, argv, 6)) : 0;
+    return xt_number((double)xt_timegm(&tm) * 1000.0 + millis);
   }
   return XT_UNDEFINED;
 }

package/runtime/xt_stdlib2/objects.inc

@@ -135,6 +135,17 @@ static xt_value xt_object_define_property(xt_value target, xt_value key, xt_valu
   return target;
 }
 
+static xt_value xt_object_define_properties(xt_value target, xt_value descriptors) {
+  xt_value names = xt_object_own_property_names(descriptors);
+  xt_array *keys = xt_as_array(names);
+  if (!keys) return target;
+  for (uint32_t i = 0; i < keys->length; i++) {
+    xt_value key = keys->items[i];
+    xt_object_define_property(target, key, xt_object_get(descriptors, key));
+  }
+  return target;
+}
+
 static xt_value xt_object_get_own_property_descriptors(xt_value target) {
   xt_value result = xt_object_new();
   xt_value names = xt_object_own_property_names(target);
@@ -160,6 +171,9 @@ xt_value xt_object_static(xt_value name, int32_t argc, xt_value *argv) {
     return xt_object_define_property(xt_arg_at(argc, argv, 0), xt_arg_at(argc, argv, 1),
                                       xt_arg_at(argc, argv, 2));
   }
+  if (strcmp(fn, "defineProperties") == 0) {
+    return xt_object_define_properties(xt_arg_at(argc, argv, 0), xt_arg_at(argc, argv, 1));
+  }
   if (strcmp(fn, "keys") == 0) return xt_object_keys(xt_arg_at(argc, argv, 0));
   if (strcmp(fn, "getOwnPropertyNames") == 0) return xt_object_own_property_names(xt_arg_at(argc, argv, 0));
   if (strcmp(fn, "getOwnPropertySymbols") == 0) return xt_object_own_property_symbols(xt_arg_at(argc, argv, 0));

package/scripts/build-gui.ts

@@ -13,12 +13,14 @@
  *   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 a minimal static FFmpeg for `<video>`/`<audio>`
- *       (skipped on Windows, where media support is compiled out),
  *   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.
+ *
  * Environment:
  *   xbintsc_CXX    C++ compiler override (default: clang++ next to the resolved clang)
  *   xbintsc_CMAKE  CMake override (default: a vendored CMake, then `cmake`)
@@ -35,7 +37,6 @@
  */
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
-import { availableParallelism } from "node:os";
 import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -62,9 +63,6 @@ const freetypeSrc = join(vendorDir, "freetype");
 const freetypeBuild = join(vendorDir, "freetype-build");
 const harfbuzzSrc = join(vendorDir, "harfbuzz");
 const harfbuzzBuild = join(vendorDir, "harfbuzz-build");
-const ffmpegSrc = join(vendorDir, "ffmpeg");
-const ffmpegBuild = join(vendorDir, "ffmpeg-build");
-const ffmpegInstall = join(ffmpegBuild, "dist");
 const objDir = join(root, "build", "gui-obj");
 const outDir = join(runtimeDir, "lib", platformSlug());
 
@@ -110,24 +108,8 @@ function cmakeToolchainArgs(): string[] {
 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";
-const FFMPEG_VERSION = process.env.FFMPEG_VERSION || "7.1";
 const FREETYPE_URL = `https://download.savannah.gnu.org/releases/freetype/freetype-${FREETYPE_VERSION}.tar.xz`;
 const HARFBUZZ_URL = `https://github.com/harfbuzz/harfbuzz/releases/download/${HARFBUZZ_VERSION}/harfbuzz-${HARFBUZZ_VERSION}.tar.xz`;
-const FFMPEG_URL = `https://ffmpeg.org/releases/ffmpeg-${FFMPEG_VERSION}.tar.xz`;
-
-/* A deliberately minimal FFmpeg: containers and decoders for the common web
- * media formats, file access only, no network, no encoder, no filter graph.
- * Disabling everything first keeps the static libraries small and the build
- * short. `--disable-x86asm` drops the nasm/yasm build dependency (the C
- * fallbacks are plenty for playback). This configuration is LGPL-only, so the
- * resulting `gui.a` stays redistributable under the engine's terms. */
-const FFMPEG_COMPONENTS: readonly string[] = [
-  "--enable-protocol=file",
-  "--enable-demuxer=mov,matroska,avi,flv,mpegts,mp3,ogg,wav,flac,aac,m4v,asf,mpeg,mpegvideo,h264,hevc,vc1",
-  "--enable-decoder=h264,hevc,vp8,vp9,av1,aac,aac_latm,mp3,mp3float,opus,vorbis,flac,alac,pcm_s16le,pcm_s24le,pcm_s32le,pcm_u8,pcm_f32le,pcm_alaw,pcm_mulaw,ac3,eac3,wmav2,mjpeg",
-  "--enable-parser=h264,hevc,vp8,vp9,av1,aac,aac_latm,mpegaudio,opus,vorbis,mpeg4video,mjpeg,flac",
-  "--enable-bsf=h264_mp4toannexb,hevc_mp4toannexb,aac_adtstoasc,vp9_superframe,vp9_superframe_split,extract_extradata",
-];
 
 function fail(message: string): never {
   console.error(`xbintsc: ${message}`);
@@ -345,16 +327,6 @@ function harfbuzzArchive(): string | undefined {
   return builtLibrary(harfbuzzBuild, ["libharfbuzz.a", "harfbuzz.lib"], /^harfbuzz[-\d.]*\.lib$/);
 }
 
-/* FFmpeg's release tarball has no CMake build, so it uses its own configure +
- * make. It also installs its headers under a prefix (rather than in the source
- * tree) because the *source* root contains a file literally named `version`
- * that would shadow the C++ standard header for any `.cpp` that includes it. */
-const FFMPEG_LIBRARY_NAMES = ["libavformat.a", "libavcodec.a", "libswscale.a", "libswresample.a", "libavutil.a"];
-function ffmpegStaticLibraries(): string[] | undefined {
-  const libraries = FFMPEG_LIBRARY_NAMES.map((name) => join(ffmpegInstall, "lib", name));
-  return libraries.every((library) => existsSync(library)) ? libraries : undefined;
-}
-
 /* -- 1. SDL3 source ------------------------------------------------------- */
 
 if (!existsSync(join(sdlSrc, "CMakeLists.txt"))) {
@@ -407,8 +379,7 @@ if (!existingSdlArchive) {
 /** 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 (CMake projects ship
- * `CMakeLists.txt`; FFmpeg ships `configure`). */
+ * 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;
@@ -463,41 +434,6 @@ if (!existsSync(harfbuzzArchive() ?? "")) {
   console.log(`xbintsc: reusing existing ${harfbuzzArchive()}`);
 }
 
-/* -- 2c. FFmpeg (media decoding) ------------------------------------------ */
-
-/* Windows builds have no `configure`/`make`, so media support is compiled out
- * there; the element still works and reports an `error` event. */
-let ffmpegLibraries: string[] | undefined;
-if (isWindows) {
-  console.log("xbintsc: skipping FFmpeg on Windows; <video>/<audio> will report an error");
-} else {
-  ensureTarballSource("ffmpeg", FFMPEG_URL, `ffmpeg-${FFMPEG_VERSION}`, "configure");
-  ffmpegLibraries = ffmpegStaticLibraries();
-  if (!ffmpegLibraries) {
-    console.log(`xbintsc: building minimal static FFmpeg ${FFMPEG_VERSION} with ${clang}`);
-    mkdirSync(ffmpegBuild, { recursive: true });
-    run(join(ffmpegSrc, "configure"), [
-      `--prefix=${ffmpegInstall}`,
-      "--enable-static", "--disable-shared",
-      "--disable-programs", "--disable-doc",
-      "--disable-htmlpages", "--disable-manpages", "--disable-podpages", "--disable-txtpages",
-      "--disable-avdevice", "--disable-avfilter", "--disable-postproc",
-      "--disable-everything",
-      "--enable-avformat", "--enable-avcodec", "--enable-avutil", "--enable-swscale", "--enable-swresample",
-      "--disable-network", "--disable-autodetect", "--disable-x86asm", "--disable-debug", "--enable-pic",
-      `--cc=${clang}`,
-      `--cxx=${clangxx}`,
-      ...FFMPEG_COMPONENTS,
-    ], { cwd: ffmpegBuild });
-    run("make", ["-j", String(availableParallelism())], { cwd: ffmpegBuild });
-    run("make", ["install"], { cwd: ffmpegBuild });
-    ffmpegLibraries = ffmpegStaticLibraries();
-  } else {
-    console.log(`xbintsc: reusing existing ${ffmpegInstall}/lib`);
-  }
-  if (!ffmpegLibraries) fail("FFmpeg build did not produce the expected static libraries");
-}
-
 /* -- 3. engine objects ---------------------------------------------------- */
 
 mkdirSync(objDir, { recursive: true });
@@ -508,14 +444,12 @@ const includeFlags = [
   "-I", join(freetypeBuild, "include"),
   "-I", join(harfbuzzSrc, "src"),
 ];
-if (ffmpegLibraries) includeFlags.push("-I", join(ffmpegInstall, "include"));
 const sources = readdirSync(engineDir)
   .filter((entry) => entry.endsWith(".cpp"))
   .sort();
 
 const objects: string[] = [];
 const cxxFlags = ["-std=c++17", "-O2", "-Wall", "-Wextra", ...includeFlags];
-if (ffmpegLibraries) cxxFlags.push("-DXT_GUI_WITH_FFMPEG=1");
 /* 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
@@ -539,7 +473,7 @@ const harfbuzz = harfbuzzArchive();
 if (!sdl || !freetype || !harfbuzz) {
   fail("one of the SDL3/FreeType/HarfBuzz archives was not found after building");
 }
-const libraries = [sdl, freetype, harfbuzz, ...(ffmpegLibraries ?? [])];
+const libraries = [sdl, freetype, harfbuzz];
 
 mkdirSync(outDir, { recursive: true });
 rmSync(output, { force: true });

package/scripts/build-media.ts

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/**
+ * Build the media extension archive:
+ *
+ *   runtime/lib/<os>-<arch>/media.a
+ *
+ * The GUI engine (`gui.a`) deliberately contains no decoder. This archive adds
+ * `<video>`/`<audio>` support: it bundles the FFmpeg-backed player from
+ * `runtime/ext_media/media.cpp` together with a minimal static FFmpeg, and the
+ * `media` extension links it only when the program asks for it. A program built
+ * with `--ext gui` alone therefore stays FFmpeg-free.
+ *
+ * Steps:
+ *   1. fetch the pinned FFmpeg release tarball into `vendor/ffmpeg`,
+ *   2. configure and build a minimal static FFmpeg into
+ *      `vendor/ffmpeg-build/dist` (reused on later runs),
+ *   3. compile the player against those headers,
+ *   4. merge the player object and the FFmpeg libraries into `media.a`
+ *      (libtool on macOS, `ar -M` elsewhere).
+ *
+ * Environment:
+ *   xbintsc_CXX       C++ compiler override (default: clang++ next to clang)
+ *   xbintsc_AR        archiver override (default: llvm-ar next to clang, then ar)
+ *   FFMPEG_VERSION    FFmpeg release (default: 7.1)
+ *
+ * Windows is not supported yet: FFmpeg needs its own `configure`/`make`, and an
+ * MSVC-compatible build has not been produced (see `doc/gui/known-issues.md`).
+ */
+
+import { existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { availableParallelism } from "node:os";
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { platformSlug } from "../src/driver/paths.js";
+import { probeClang, realRunner } from "../src/driver/toolchain.js";
+import { resolveToolchain } from "../src/driver/toolchain-provider.js";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const runtimeDir = join(root, "runtime");
+const sourceDir = join(runtimeDir, "ext_media");
+const vendorDir = join(root, "vendor");
+const ffmpegSrc = join(vendorDir, "ffmpeg");
+const ffmpegBuild = join(vendorDir, "ffmpeg-build");
+const ffmpegInstall = join(ffmpegBuild, "dist");
+const objDir = join(root, "build", "media-obj");
+const outDir = join(runtimeDir, "lib", platformSlug());
+const output = join(outDir, "media.a");
+
+const FFMPEG_VERSION = process.env.FFMPEG_VERSION || "7.1";
+const FFMPEG_URL = `https://ffmpeg.org/releases/ffmpeg-${FFMPEG_VERSION}.tar.xz`;
+
+/* A deliberately minimal FFmpeg: containers and decoders for the common web
+ * media formats, file access only, no network, no encoder, no filter graph.
+ * Disabling everything first keeps the static libraries small and the build
+ * short. `--disable-x86asm` drops the nasm/yasm build dependency (the C
+ * fallbacks are plenty for playback). This configuration is LGPL-only, so the
+ * resulting archive stays redistributable. */
+const FFMPEG_COMPONENTS: readonly string[] = [
+  "--enable-protocol=file",
+  "--enable-demuxer=mov,matroska,avi,flv,mpegts,mp3,ogg,wav,flac,aac,m4v,asf,mpeg,mpegvideo,h264,hevc,vc1",
+  "--enable-decoder=h264,hevc,vp8,vp9,av1,aac,aac_latm,mp3,mp3float,opus,vorbis,flac,alac,pcm_s16le,pcm_s24le,pcm_s32le,pcm_u8,pcm_f32le,pcm_alaw,pcm_mulaw,ac3,eac3,wmav2,mjpeg",
+  "--enable-parser=h264,hevc,vp8,vp9,av1,aac,aac_latm,mpegaudio,opus,vorbis,mpeg4video,mjpeg,flac",
+  "--enable-bsf=h264_mp4toannexb,hevc_mp4toannexb,aac_adtstoasc,vp9_superframe,vp9_superframe_split,extract_extradata",
+];
+
+const FFMPEG_LIBRARY_NAMES = ["libavformat.a", "libavcodec.a", "libswscale.a", "libswresample.a", "libavutil.a"];
+
+function fail(message: string): never {
+  console.error(`xbintsc: ${message}`);
+  process.exit(1);
+}
+
+function run(
+  command: string,
+  args: readonly string[],
+  options: { input?: string; quietStderr?: boolean; cwd?: string } = {},
+): SpawnSyncReturns<string> {
+  const quiet = options.quietStderr === true;
+  const result = spawnSync(command, args, {
+    stdio: options.input !== undefined ? ["pipe", "inherit", "inherit"] : quiet ? ["ignore", "inherit", "pipe"] : "inherit",
+    encoding: "utf8",
+    input: options.input,
+    cwd: options.cwd,
+  });
+  if (result.status !== 0) {
+    if (quiet && result.stderr) process.stderr.write(result.stderr);
+    fail(`${command} ${args.join(" ")} failed with status ${result.status ?? "?"}`);
+  }
+  return result;
+}
+
+function isRunnable(candidate: string): boolean {
+  return !spawnSync(candidate, ["--version"], { encoding: "utf8" }).error;
+}
+
+function firstAvailable(candidates: readonly (string | undefined)[]): string | undefined {
+  for (const candidate of candidates) {
+    if (candidate && isRunnable(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+/** The tool that sits next to `clang` in the same LLVM installation. */
+function siblingTool(clangPath: string, name: string): string | undefined {
+  if (!clangPath.includes("/") && !clangPath.includes("\\")) return undefined;
+  const candidate = join(dirname(clangPath), `${name}.exe`);
+  if (existsSync(candidate)) return candidate;
+  const bare = join(dirname(clangPath), name);
+  return existsSync(bare) ? bare : undefined;
+}
+
+/** Resolve `clang++` from the same LLVM as the driver's clang. */
+function findClangxx(clangPath: string): string {
+  const override = process.env.xbintsc_CXX;
+  if (override) {
+    const probe = probeClang(realRunner, override);
+    if (!probe.responds) fail(`xbintsc_CXX ${override} does not respond to --version`);
+    return override;
+  }
+  const sibling = siblingTool(clangPath, "clang++");
+  if (sibling) return sibling;
+  const onPath = firstAvailable(["clang++"]);
+  if (onPath) return onPath;
+  fail("no clang++ found next to the resolved clang or on PATH; install LLVM or set xbintsc_CXX");
+}
+
+/** Resolve the archiver that matches the compiler, preferring LLVM's own. */
+function findArchiver(clangPath: string): string {
+  const sibling = siblingTool(clangPath, "llvm-ar");
+  const archiver = firstAvailable([process.env.xbintsc_AR, sibling, "llvm-ar", "ar"]);
+  if (!archiver) fail("no archiver found; install llvm-ar or set xbintsc_AR");
+  return archiver;
+}
+
+function driverClang(): string {
+  try {
+    return resolveToolchain().clang;
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+}
+
+/** Download the FFmpeg release tarball and extract it under `vendor/ffmpeg`. */
+function ensureFfmpegSource(): void {
+  if (existsSync(join(ffmpegSrc, "configure"))) return;
+  const tarball = join(vendorDir, "ffmpeg.tar.xz");
+  console.log(`xbintsc: fetching FFmpeg ${FFMPEG_VERSION} from ${FFMPEG_URL}`);
+  mkdirSync(vendorDir, { recursive: true });
+  run("curl", ["-sL", "--fail", "-o", tarball, FFMPEG_URL]);
+  run("tar", ["-xf", tarball, "-C", vendorDir]);
+  const extracted = join(vendorDir, `ffmpeg-${FFMPEG_VERSION}`);
+  if (!existsSync(extracted)) fail(`expected ffmpeg-${FFMPEG_VERSION} after extracting`);
+  rmSync(ffmpegSrc, { recursive: true, force: true });
+  renameSync(extracted, ffmpegSrc);
+  rmSync(tarball, { force: true });
+}
+
+function ffmpegStaticLibraries(): string[] | undefined {
+  const libraries = FFMPEG_LIBRARY_NAMES.map((name) => join(ffmpegInstall, "lib", name));
+  return libraries.every((library) => existsSync(library)) ? libraries : undefined;
+}
+
+if (process.platform === "win32") {
+  fail(
+    "the media extension is not available on Windows yet: FFmpeg needs a POSIX " +
+      "configure/make build (see doc/gui/known-issues.md)",
+  );
+}
+
+/* One toolchain for the player and FFmpeg: the same clang the driver uses, its
+ * sibling clang++, and the matching llvm-ar. Mixing another C++ runtime or
+ * object format would break the final link. */
+const clang = driverClang();
+const clangxx = findClangxx(clang);
+const archiver = findArchiver(clang);
+
+/* -- 1. FFmpeg source ------------------------------------------------------ */
+
+ensureFfmpegSource();
+
+/* -- 2. minimal static FFmpeg --------------------------------------------- */
+
+let ffmpegLibraries = ffmpegStaticLibraries();
+if (!ffmpegLibraries) {
+  console.log(`xbintsc: building minimal static FFmpeg ${FFMPEG_VERSION} with ${clang}`);
+  mkdirSync(ffmpegBuild, { recursive: true });
+  run(join(ffmpegSrc, "configure"), [
+    `--prefix=${ffmpegInstall}`,
+    "--enable-static", "--disable-shared",
+    "--disable-programs", "--disable-doc",
+    "--disable-htmlpages", "--disable-manpages", "--disable-podpages", "--disable-txtpages",
+    "--disable-avdevice", "--disable-avfilter", "--disable-postproc",
+    "--disable-everything",
+    "--enable-avformat", "--enable-avcodec", "--enable-avutil", "--enable-swscale", "--enable-swresample",
+    "--disable-network", "--disable-autodetect", "--disable-x86asm", "--disable-debug", "--enable-pic",
+    `--cc=${clang}`,
+    `--cxx=${clangxx}`,
+    ...FFMPEG_COMPONENTS,
+  ], { cwd: ffmpegBuild });
+  run("make", ["-j", String(availableParallelism())], { cwd: ffmpegBuild });
+  run("make", ["install"], { cwd: ffmpegBuild });
+  ffmpegLibraries = ffmpegStaticLibraries();
+  if (!ffmpegLibraries) fail("FFmpeg build did not produce the expected static libraries");
+} else {
+  console.log(`xbintsc: reusing existing ${ffmpegInstall}/lib`);
+}
+
+/* -- 3. player object ------------------------------------------------------ */
+
+/* FFmpeg installs its headers under a prefix (rather than in the source tree)
+ * because the *source* root contains a file literally named `version` that
+ * would shadow the C++ standard header for any `.cpp` that includes it. */
+mkdirSync(objDir, { recursive: true });
+const object = join(objDir, "media.o");
+const playerSource = join(sourceDir, "media.cpp");
+console.log("xbintsc: compiling media.cpp");
+run(clangxx, [
+  "-std=c++17", "-O2", "-Wall", "-Wextra", "-fPIC",
+  "-I", runtimeDir,
+  "-I", join(ffmpegInstall, "include"),
+  "-c", playerSource,
+  "-o", object,
+]);
+
+/* -- 4. merge into media.a ------------------------------------------------- */
+
+mkdirSync(outDir, { recursive: true });
+rmSync(output, { force: true });
+if (process.platform === "darwin") {
+  run("libtool", ["-static", "-o", output, object, ...ffmpegLibraries], { quietStderr: true });
+} else {
+  /* `ar -M` (GNU/LLVM) merges archives through an MRI script. */
+  const mri = (path: string): string => path.replace(/\\/g, "/");
+  const script = [
+    `create ${mri(output)}`,
+    `addmod ${mri(object)}`,
+    ...ffmpegLibraries.map((library) => `addlib ${mri(library)}`),
+    "save",
+    "end",
+  ].join("\n");
+  run(archiver, ["-M"], { input: script });
+}
+
+console.log(`xbintsc: wrote ${output}`);