xbintsc 0.5.23 → 0.5.32

package/scripts/build-gui.ts

@@ -13,6 +13,8 @@
  *   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
+ *       (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).
@@ -28,6 +30,7 @@
  *   SDL3_TAG       SDL3 git tag to check out (default: release-3.2.10)
  *   FREETYPE_VERSION  FreeType version (default: 2.13.3)
  *   HARFBUZZ_VERSION  HarfBuzz version (default: 10.1.0)
+ *   SPIRV_CROSS_VERSION  SPIRV-Cross tag (default: vulkan-sdk-1.4.313.0)
  *
  * The C/C++ compiler is the same clang the driver resolves (see
  * `src/driver/toolchain-provider.ts`), so the archive always matches the ABI of
@@ -63,6 +66,17 @@ const freetypeSrc = join(vendorDir, "freetype");
 const freetypeBuild = join(vendorDir, "freetype-build");
 const harfbuzzSrc = join(vendorDir, "harfbuzz");
 const harfbuzzBuild = join(vendorDir, "harfbuzz-build");
+/* 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 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 objDir = join(root, "build", "gui-obj");
 const outDir = join(runtimeDir, "lib", platformSlug());
 
@@ -108,8 +122,14 @@ 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 GLSLANG_VERSION = process.env.GLSLANG_VERSION || "16.6.0";
+const SPIRV_HEADERS_VERSION = process.env.SPIRV_HEADERS_VERSION || "vulkan-sdk-1.4.363.0";
+const SPIRV_CROSS_VERSION = process.env.SPIRV_CROSS_VERSION || "vulkan-sdk-1.4.313.0";
 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 GLSLANG_URL = `https://codeload.github.com/KhronosGroup/glslang/tar.gz/refs/tags/${GLSLANG_VERSION}`;
+const SPIRV_HEADERS_URL = `https://codeload.github.com/KhronosGroup/SPIRV-Headers/tar.gz/refs/tags/${SPIRV_HEADERS_VERSION}`;
+const SPIRV_CROSS_URL = `https://codeload.github.com/KhronosGroup/SPIRV-Cross/tar.gz/refs/tags/${SPIRV_CROSS_VERSION}`;
 
 function fail(message: string): never {
   console.error(`xbintsc: ${message}`);
@@ -326,6 +346,17 @@ function freetypeArchive(): string | undefined {
 function harfbuzzArchive(): string | undefined {
   return builtLibrary(harfbuzzBuild, ["libharfbuzz.a", "harfbuzz.lib"], /^harfbuzz[-\d.]*\.lib$/);
 }
+function glslangArchive(): string | undefined {
+  return builtLibrary(join(glslangBuild, "glslang"), ["libglslang.a", "glslang.lib"]);
+}
+function glslangLimitsArchive(): string | undefined {
+  return builtLibrary(join(glslangBuild, "glslang"),
+    ["libglslang-default-resource-limits.a", "glslang-default-resource-limits.lib"]);
+}
+/* SPIRV-Cross's MSL target pulls in its GLSL base class and the core module. */
+function spirvCrossArchive(name: string): string | undefined {
+  return builtLibrary(spirvCrossBuild, [`lib${name}.a`, `${name}.lib`]);
+}
 
 /* -- 1. SDL3 source ------------------------------------------------------- */
 
@@ -434,6 +465,50 @@ if (!existsSync(harfbuzzArchive() ?? "")) {
   console.log(`xbintsc: reusing existing ${harfbuzzArchive()}`);
 }
 
+/* -- 2c. glslang (WebGL GLSL ES -> SPIR-V) -------------------------------- */
+
+ensureTarballSource("glslang", GLSLANG_URL, `glslang-${GLSLANG_VERSION}`);
+ensureTarballSource(join("glslang", "External", "spirv-headers"), SPIRV_HEADERS_URL,
+  `SPIRV-Headers-${SPIRV_HEADERS_VERSION}`);
+
+if (!existsSync(glslangArchive() ?? "")) {
+  const cmake = configureCmake("glslang", glslangSrc, glslangBuild, [
+    "-DCMAKE_BUILD_TYPE=Release",
+    "-DBUILD_SHARED_LIBS=OFF",
+    "-DENABLE_OPT=OFF",
+    "-DENABLE_HLSL=OFF",
+    "-DENABLE_GLSLANG_BINARIES=OFF",
+    "-DGLSLANG_TESTS=OFF",
+  ]);
+  console.log("xbintsc: building static glslang");
+  run(cmake, ["--build", glslangBuild, "--config", "Release", "--parallel"]);
+} else {
+  console.log(`xbintsc: reusing existing ${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")}`);
+}
+
 /* -- 3. engine objects ---------------------------------------------------- */
 
 mkdirSync(objDir, { recursive: true });
@@ -443,6 +518,9 @@ const includeFlags = [
   "-I", join(freetypeSrc, "include"),
   "-I", join(freetypeBuild, "include"),
   "-I", join(harfbuzzSrc, "src"),
+  "-I", glslangSrc,
+  "-I", join(spirvHeadersSrc, "include"),
+  "-I", spirvCrossSrc,
 ];
 const sources = readdirSync(engineDir)
   .filter((entry) => entry.endsWith(".cpp"))
@@ -470,10 +548,19 @@ for (const source of sources) {
 const sdl = sdlArchive();
 const freetype = freetypeArchive();
 const harfbuzz = harfbuzzArchive();
-if (!sdl || !freetype || !harfbuzz) {
-  fail("one of the SDL3/FreeType/HarfBuzz archives was not found after building");
+const glslang = glslangArchive();
+const glslangLimits = glslangLimitsArchive();
+const spirvCrossCore = spirvCrossArchive("spirv-cross-core");
+const spirvCrossGlsl = spirvCrossArchive("spirv-cross-glsl");
+const spirvCrossMsl = spirvCrossArchive("spirv-cross-msl");
+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");
 }
-const libraries = [sdl, freetype, harfbuzz];
+const libraries = [
+  sdl, freetype, harfbuzz, glslang, glslangLimits,
+  spirvCrossCore, spirvCrossGlsl, spirvCrossMsl,
+];
 
 mkdirSync(outDir, { recursive: true });
 rmSync(output, { force: true });

package/scripts/build-media.ts

@@ -2,38 +2,53 @@
 /**
  * Build the media extension archive:
  *
- *   runtime/lib/<os>-<arch>/media.a
+ *   runtime/lib/<os>-<arch>/media.a     (POSIX: ELF/Mach-O objects)
+ *   runtime/lib/<os>-<arch>/media.lib   (Windows: MSVC/COFF objects)
  *
- * 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.
+ * The GUI engine (`gui.a` / `gui.lib`) 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).
+ *   4. merge the player object and the FFmpeg libraries into the archive
+ *      (libtool on macOS, `ar -M`/`llvm-ar -M` elsewhere).
+ *
+ * Windows uses FFmpeg's own MSVC toolchain mode: `configure --toolchain=msvc
+ * --cc=clang-cl` produces COFF objects compiled against the static MSVC CRT,
+ * which is the ABI `gui.lib`, the xbintsc runtime and the final link use. The
+ * compiler chain is entirely Visual Studio (clang-cl, cl.exe, lib.exe and
+ * llvm-ar); no additional C/C++ toolchain is involved.
+ *
+ * FFmpeg's `configure` is a POSIX shell script and its Makefiles require GNU
+ * make, so those two build drivers remain. The shell comes from Git for Windows
+ * (already required to clone SDL3), and make is a native GNU make on PATH or
+ * `xbintsc_MAKE`; no additional POSIX environment is required. Because native
+ * make cannot pass the MSVC `/showIncludes` awk pipeline through the Windows
+ * command line unchanged, the generated `SRC_PATH` is rewritten to a
+ * drive-letter path and dependency generation is skipped. Headers/libraries are
+ * copied into the prefix instead of running `make install`.
  *
  * Environment:
  *   xbintsc_CXX       C++ compiler override (default: clang++ next to clang)
  *   xbintsc_AR        archiver override (default: llvm-ar next to clang, then ar)
+ *   xbintsc_SHELL     POSIX shell override (Windows; default: Git for Windows bash)
+ *   xbintsc_MAKE      GNU make override (Windows; default: `make` on PATH)
  *   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 { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } 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 { isMsvcTarget, probeClang, realRunner } from "../src/driver/toolchain.js";
 import { resolveToolchain } from "../src/driver/toolchain-provider.js";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -41,11 +56,16 @@ 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 isWindows = process.platform === "win32";
+/* The MSVC configure/build tree is kept apart from the POSIX one: a shared tree
+ * would carry `CC=clang`/`CC=clang-cl` and a POSIX/Windows `SRC_PATH` from the
+ * other platform into the next configure. */
+const ffmpegBuild = join(vendorDir, isWindows ? "ffmpeg-build-msvc" : "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 output = join(outDir, isWindows ? "media.lib" : "media.a");
+const object = join(objDir, isWindows ? "media.obj" : "media.o");
 
 const FFMPEG_VERSION = process.env.FFMPEG_VERSION || "7.1";
 const FFMPEG_URL = `https://ffmpeg.org/releases/ffmpeg-${FFMPEG_VERSION}.tar.xz`;
@@ -74,7 +94,7 @@ function fail(message: string): never {
 function run(
   command: string,
   args: readonly string[],
-  options: { input?: string; quietStderr?: boolean; cwd?: string } = {},
+  options: { input?: string; quietStderr?: boolean; cwd?: string; env?: NodeJS.ProcessEnv } = {},
 ): SpawnSyncReturns<string> {
   const quiet = options.quietStderr === true;
   const result = spawnSync(command, args, {
@@ -82,6 +102,7 @@ function run(
     encoding: "utf8",
     input: options.input,
     cwd: options.cwd,
+    env: options.env,
   });
   if (result.status !== 0) {
     if (quiet && result.stderr) process.stderr.write(result.stderr);
@@ -104,7 +125,7 @@ function firstAvailable(candidates: readonly (string | undefined)[]): string | u
 /** 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`);
+  const candidate = join(dirname(clangPath), `${name}${isWindows ? ".exe" : ""}`);
   if (existsSync(candidate)) return candidate;
   const bare = join(dirname(clangPath), name);
   return existsSync(bare) ? bare : undefined;
@@ -116,6 +137,12 @@ function findClangxx(clangPath: string): string {
   if (override) {
     const probe = probeClang(realRunner, override);
     if (!probe.responds) fail(`xbintsc_CXX ${override} does not respond to --version`);
+    if (isWindows && (probe.version === undefined || (probe.target !== undefined && !isMsvcTarget(probe.target)))) {
+      fail(
+        `xbintsc_CXX ${override} is not an MSVC-targeting clang++ (target ${probe.target ?? "unknown"}); ` +
+          "the Windows media build requires one, for example x86_64-pc-windows-msvc.",
+      );
+    }
     return override;
   }
   const sibling = siblingTool(clangPath, "clang++");
@@ -128,7 +155,9 @@ function findClangxx(clangPath: string): string {
 /** 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"]);
+  /* Windows always uses llvm-ar: a non-LLVM `ar` there may write a different
+   * archive flavour than the COFF one the linker wants. */
+  const archiver = firstAvailable([process.env.xbintsc_AR, sibling, "llvm-ar", isWindows ? undefined : "ar"]);
   if (!archiver) fail("no archiver found; install llvm-ar or set xbintsc_AR");
   return archiver;
 }
@@ -161,47 +190,284 @@ function ffmpegStaticLibraries(): string[] | undefined {
   return libraries.every((library) => existsSync(library)) ? libraries : undefined;
 }
 
-if (process.platform === "win32") {
+/** True when `dist` holds both the libraries and the installed headers. */
+function ffmpegInstalled(): boolean {
+  return ffmpegStaticLibraries() !== undefined && existsSync(join(ffmpegInstall, "include", "libavutil", "avutil.h"));
+}
+
+/** Arguments shared by the POSIX and Windows FFmpeg configure runs. */
+function ffmpegConfigureArgs(): string[] {
+  const prefix = isWindows ? ffmpegInstall.replace(/\\/g, "/") : ffmpegInstall;
+  const args = [
+    `--prefix=${prefix}`,
+    "--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",
+    ...FFMPEG_COMPONENTS,
+  ];
+  /* `-fPIC` is meaningless to the MSVC ABI; FFmpeg's msvc flag filter drops it,
+   * but omitting it keeps the configuration honest. */
+  if (!isWindows) args.splice(2, 0, "--enable-pic");
+  return args;
+}
+
+/* -- Windows: a POSIX shell + GNU make driving clang-cl -------------------- */
+
+/** Drive-letter path in the `/d/dir/file` form the POSIX shell and configure use. */
+function toPosixPath(path: string): string {
+  const absolute = resolve(path);
+  const match = /^([A-Za-z]):[\\/](.*)$/.exec(absolute);
+  if (!match) return absolute.replace(/\\/g, "/");
+  return `/${match[1].toLowerCase()}/${match[2].replace(/\\/g, "/")}`;
+}
+
+/** `D:\dir` form for the native make parser (it does not understand `/d/dir`). */
+function toWindowsPath(path: string): string {
+  return resolve(path).replace(/\\/g, "/");
+}
+
+/** Quote one word for a POSIX shell command line built by hand. */
+function shellQuote(word: string): string {
+  return `'${word.replace(/'/g, `'\\''`)}'`;
+}
+
+/** Git for Windows' bash, which supplies the POSIX shell FFmpeg's configure needs. */
+function findPosixShell(): string {
+  const programFiles = process.env.ProgramFiles ?? "C:\\Program Files";
+  const localAppData = process.env.LOCALAPPDATA ?? "";
+  const git = resolveOnPath("git");
+  const candidates = [
+    process.env.xbintsc_SHELL,
+    git ? resolve(dirname(git), "..", "bin", "bash.exe") : undefined,
+    join(programFiles, "Git", "bin", "bash.exe"),
+    join(localAppData, "Programs", "Git", "bin", "bash.exe"),
+    join(programFiles, "Git", "usr", "bin", "bash.exe"),
+  ].filter((candidate): candidate is string => Boolean(candidate));
+  const shell = firstAvailable(candidates);
+  if (!shell) {
+    fail(
+      "the Windows media build needs a POSIX shell to run FFmpeg's configure; " +
+        "install Git for Windows (which also supplies git) or set xbintsc_SHELL.",
+    );
+  }
+  return shell;
+}
+
+/** First match for `name` on PATH, as an absolute path. */
+function resolveOnPath(name: string): string | undefined {
+  const result = spawnSync("where.exe", [name], { encoding: "utf8" });
+  if (result.status !== 0) return undefined;
+  return result.stdout.split(/\r?\n/).map((line) => line.trim()).find((line) => line.length > 0);
+}
+
+/** Native GNU make to drive the FFmpeg build. */
+function findWindowsMake(): string {
+  const candidates = [process.env.xbintsc_MAKE, resolveOnPath("make")].filter(
+    (candidate): candidate is string => Boolean(candidate),
+  );
+  for (const candidate of candidates) {
+    if (isRunnable(candidate)) return candidate;
+  }
+  fail(
+    "the Windows media build needs GNU make to run FFmpeg's Makefile; install it " +
+      "(`choco install make`) or set xbintsc_MAKE to a GNU make binary.",
+  );
+}
+
+/** Resolve `clang-cl` from the same LLVM as the driver's clang. */
+function findClangCl(clangPath: string): string {
+  const sibling = siblingTool(clangPath, "clang-cl");
+  if (sibling) return sibling;
+  const onPath = resolveOnPath("clang-cl");
+  if (onPath) return onPath;
+  fail(
+    `no clang-cl found next to ${clangPath} or on PATH; the Windows media build needs the LLVM bundled ` +
+      "with Visual Studio (VC\\Tools\\Llvm\\<arch>\\bin\\clang-cl.exe) so FFmpeg can use the MSVC ABI.",
+  );
+}
+
+/** Installation path reported by `vswhere`, when it is available. */
+function vswhereInstallation(): string | undefined {
+  const programFilesX86 = process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+  const vswhere = join(programFilesX86, "Microsoft Visual Studio", "Installer", "vswhere.exe");
+  if (!existsSync(vswhere)) return undefined;
+  const result = spawnSync(
+    vswhere,
+    [
+      "-latest", "-products", "*",
+      "-requires", "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
+      "-property", "installationPath",
+    ],
+    { encoding: "utf8" },
+  );
+  const root = result.status === 0 ? result.stdout.split(/\r?\n/)[0]?.trim() : undefined;
+  return root && existsSync(root) ? root : undefined;
+}
+
+/** Directory holding `cl.exe` (and `lib.exe`), which FFmpeg's msvc toolchain probes. */
+function findMsvcBin(clangPath: string): string {
+  const roots = [process.env.ProgramFiles, process.env["ProgramFiles(x86)"], process.env.ProgramW6432]
+    .filter((root): root is string => Boolean(root));
+  /* A clang from Visual Studio's own LLVM names the installation it belongs to;
+   * vswhere covers a clang from a separate LLVM when VS is installed elsewhere. */
+  const fromClang = /^(.*[\\/]Microsoft Visual Studio[\\/]\d{4}[\\/][^\\/]+)[\\/]VC[\\/]Tools[\\/]Llvm[\\/]/i.exec(
+    clangPath,
+  )?.[1];
+  const fromVswhere = vswhereInstallation();
+  const msvcDirs: string[] = [];
+  for (const extra of [fromClang, fromVswhere]) {
+    if (extra) msvcDirs.push(join(extra, "VC", "Tools", "MSVC"));
+  }
+  for (const root of roots) {
+    for (const year of ["2022", "2019"]) {
+      for (const edition of ["BuildTools", "Community", "Professional", "Enterprise"]) {
+        msvcDirs.push(join(root, "Microsoft Visual Studio", year, edition, "VC", "Tools", "MSVC"));
+      }
+    }
+  }
+  const host = process.arch === "arm64" ? "Hostarm64" : "Hostx64";
+  const target = process.arch === "arm64" ? "arm64" : "x64";
+  for (const msvc of msvcDirs) {
+    if (!existsSync(msvc)) continue;
+    const versions = readdirSync(msvc).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+    for (const version of versions) {
+      const bin = join(msvc, version, "bin", host, target);
+      if (existsSync(join(bin, "cl.exe"))) return bin;
+    }
+  }
   fail(
-    "the media extension is not available on Windows yet: FFmpeg needs a POSIX " +
-      "configure/make build (see doc/gui/known-issues.md)",
+    "the Windows media build needs the MSVC C++ toolchain (FFmpeg's configure probes cl.exe/lib.exe); " +
+      "install the 'Desktop development with C++' workload in Visual Studio or the Build Tools.",
   );
 }
 
+interface WindowsBuildTools {
+  readonly shell: string;
+  readonly make: string;
+  readonly env: NodeJS.ProcessEnv;
+}
+
+/** Environment for configure/make: the resolved clang-cl and MSVC tools first. */
+function windowsBuildEnv(shell: string, clangCl: string, msvcBin: string): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  const pathKey = Object.keys(env).find((key) => key.toUpperCase() === "PATH") ?? "Path";
+  const usrBin = resolve(dirname(shell), "..", "usr", "bin");
+  const parts = [dirname(clangCl), msvcBin, existsSync(usrBin) ? usrBin : "", env[pathKey] ?? ""];
+  env[pathKey] = parts.filter((part) => part.length > 0).join(";");
+  return env;
+}
+
+/** Rewrite the POSIX `SRC_PATH` configure wrote so a native make can parse it. */
+function patchNativeMakePaths(): void {
+  const posixSource = toPosixPath(ffmpegSrc);
+  const posixInstall = toPosixPath(ffmpegInstall);
+  for (const file of [join(ffmpegBuild, "Makefile"), join(ffmpegBuild, "ffbuild", "config.mak")]) {
+    if (!existsSync(file)) continue;
+    const patched = readFileSync(file, "utf8")
+      .split(posixSource).join(toWindowsPath(ffmpegSrc))
+      .split(posixInstall).join(toWindowsPath(ffmpegInstall));
+    writeFileSync(file, patched);
+  }
+}
+
+/** Copy every public `.h` under `source` into `destination`, recursively. */
+function copyHeaders(source: string, destination: string): void {
+  mkdirSync(destination, { recursive: true });
+  for (const entry of readdirSync(source, { withFileTypes: true })) {
+    const from = join(source, entry.name);
+    const to = join(destination, entry.name);
+    if (entry.isDirectory()) {
+      copyHeaders(from, to);
+    } else if (entry.isFile() && entry.name.endsWith(".h")) {
+      copyFileSync(from, to);
+    }
+  }
+}
+
+/** Copy FFmpeg headers and static libraries into the `dist` prefix. */
+function installFfmpegWindows(): void {
+  const includeDir = join(ffmpegInstall, "include");
+  for (const name of FFMPEG_LIBRARY_NAMES) {
+    const library = name.replace(/\.a$/, "");
+    copyHeaders(join(ffmpegSrc, library), join(includeDir, library));
+  }
+  /* Generated headers live in the build tree, not in the sources. */
+  for (const generated of ["avconfig.h", "ffversion.h"]) {
+    const from = join(ffmpegBuild, "libavutil", generated);
+    if (existsSync(from)) copyFileSync(from, join(includeDir, "libavutil", generated));
+  }
+  const libDir = join(ffmpegInstall, "lib");
+  mkdirSync(libDir, { recursive: true });
+  for (const name of FFMPEG_LIBRARY_NAMES) {
+    copyFileSync(join(ffmpegBuild, name.replace(/\.a$/, ""), name), join(libDir, name));
+  }
+}
+
+function buildFfmpegWindows(shell: string, clangCl: string, msvcBin: string): void {
+  const make = findWindowsMake();
+  const tools: WindowsBuildTools = {
+    shell,
+    make,
+    env: windowsBuildEnv(shell, clangCl, msvcBin),
+  };
+  console.log(`xbintsc: configuring FFmpeg ${FFMPEG_VERSION} for the MSVC ABI with clang-cl`);
+  mkdirSync(ffmpegBuild, { recursive: true });
+  run(tools.shell, [
+    toPosixPath(join(ffmpegSrc, "configure")),
+    "--toolchain=msvc",
+    "--cc=clang-cl", "--cxx=clang-cl", "--ld=clang-cl", "--ar=lib.exe",
+    ...ffmpegConfigureArgs(),
+  ], { cwd: ffmpegBuild, env: tools.env });
+
+  /* Native make cannot pass FFmpeg's `/showIncludes` awk pipeline (the MSVC
+   * backslash escapes are consumed by the Windows command line); the `.d` files
+   * only affect incremental rebuilds, so generation is skipped. The source path
+   * configure wrote is POSIX-shaped and is rewritten for native make. */
+  patchNativeMakePaths();
+  const depOverrides = " CCDEP=true CXXDEP=true ASDEP=true HOSTCCDEP=true";
+  console.log(`xbintsc: building minimal static FFmpeg ${FFMPEG_VERSION} with clang-cl`);
+  run(tools.shell, ["-lc", `${shellQuote(tools.make)} -j ${availableParallelism()}${depOverrides}`], {
+    cwd: ffmpegBuild,
+    env: tools.env,
+  });
+  installFfmpegWindows();
+}
+
+/* -- 1. FFmpeg source ------------------------------------------------------ */
+
+ensureFfmpegSource();
+
 /* 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();
+const windowsTools = isWindows
+  ? {
+      shell: findPosixShell(),
+      clangCl: findClangCl(clang),
+      msvcBin: findMsvcBin(clang),
+    }
+  : undefined;
 
 /* -- 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");
+if (!ffmpegInstalled()) {
+  if (windowsTools) {
+    buildFfmpegWindows(windowsTools.shell, windowsTools.clangCl, windowsTools.msvcBin);
+  } else {
+    console.log(`xbintsc: building minimal static FFmpeg ${FFMPEG_VERSION} with ${clang}`);
+    mkdirSync(ffmpegBuild, { recursive: true });
+    run(join(ffmpegSrc, "configure"), ffmpegConfigureArgs(), { cwd: ffmpegBuild });
+    run("make", ["-j", String(availableParallelism())], { cwd: ffmpegBuild });
+    run("make", ["install"], { cwd: ffmpegBuild });
+  }
+  if (!ffmpegInstalled()) fail("FFmpeg build did not produce the expected static libraries");
 } else {
   console.log(`xbintsc: reusing existing ${ffmpegInstall}/lib`);
 }
@@ -212,30 +478,29 @@ if (!ffmpegLibraries) {
  * 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,
-]);
+const cxxFlags = ["-std=c++17", "-O2", "-Wall", "-Wextra", "-I", runtimeDir, "-I", join(ffmpegInstall, "include")];
+/* The engine and the player are C++ with the static CRT (`libcpmt`), matching
+ * FFmpeg's clang-cl objects and the xbintsc runtime; see `scripts/build-gui.ts`. */
+if (isWindows) cxxFlags.push("-Xclang", "--dependent-lib=libcpmt");
+else cxxFlags.push("-fPIC");
+run(clangxx, [...cxxFlags, "-c", playerSource, "-o", object]);
 
-/* -- 4. merge into media.a ------------------------------------------------- */
+/* -- 4. merge into the archive -------------------------------------------- */
 
 mkdirSync(outDir, { recursive: true });
 rmSync(output, { force: true });
 if (process.platform === "darwin") {
-  run("libtool", ["-static", "-o", output, object, ...ffmpegLibraries], { quietStderr: true });
+  run("libtool", ["-static", "-o", output, object, ...ffmpegStaticLibraries()!], { quietStderr: true });
 } else {
-  /* `ar -M` (GNU/LLVM) merges archives through an MRI script. */
+  /* `ar -M` (GNU/LLVM) merges archives through an MRI script. Windows paths are
+   * normalised to `/` so the MRI parser does not read `\` as an escape. */
   const mri = (path: string): string => path.replace(/\\/g, "/");
   const script = [
     `create ${mri(output)}`,
     `addmod ${mri(object)}`,
-    ...ffmpegLibraries.map((library) => `addlib ${mri(library)}`),
+    ...ffmpegStaticLibraries()!.map((library) => `addlib ${mri(library)}`),
     "save",
     "end",
   ].join("\n");