xbintsc 0.5.21 → 0.5.23

package/runtime/ext_media/media_bridge.c

@@ -0,0 +1,35 @@
+/*
+ * xbintsc media extension — registration bridge.
+ *
+ * The decoders live in `media.a`, a prebuilt C++ archive. A static archive is
+ * only searched for members that satisfy an undefined symbol, so a backend that
+ * merely had a constructor would never be extracted. This tiny C translation
+ * unit is compiled and linked *directly* (it is the media extension's
+ * `runtimeSources()` entry): its constructor references every backend entry
+ * point, which pulls the archive member in, and installs the table into the GUI
+ * engine before `main` runs.
+ *
+ * The bridge is intentionally C-only and has no FFmpeg (or SDL) dependency. If
+ * the `gui` extension is not enabled, `xt_media_install` is unresolved; the
+ * registry rejects that combination first with a "media requires gui"
+ * diagnostic (see `src/extensions/registry.ts`).
+ */
+
+#include "../ext_gui/media_api.h"
+
+static const XtMediaApi kMediaApi = {
+    xt_media_backend_open,
+    xt_media_backend_by_id,
+    xt_media_backend_shutdown,
+};
+
+#if defined(__GNUC__) || defined(__clang__)
+__attribute__((constructor)) static void xt_media_register(void) {
+  xt_media_install(&kMediaApi);
+}
+#elif defined(_MSC_VER)
+/* COFF has no `constructor` attribute. `media.lib` is not produced on Windows
+ * yet; keep the table referenced so the translation unit is not empty. */
+void xt_media_register(void);
+void xt_media_register(void) { xt_media_install(&kMediaApi); }
+#endif

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}`);

package/src/cli/hints.ts

@@ -77,6 +77,17 @@ const THROWN_FAILURES: readonly ThrownFailure[] = [
       path: DOC_EXTENSIONS,
     },
   },
+  {
+    /* 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`. */
+    match: /requires the '.*' extension|native library not found/i,
+    code: DiagnosticCode.IOError,
+    pointer: {
+      text: "enable the extension's dependencies together, and build its prebuilt archive first",
+      path: DOC_EXTENSIONS,
+    },
+  },
   {
     match: /config|JSON/i,
     code: DiagnosticCode.IOError,

package/src/cli/main.ts

@@ -255,7 +255,7 @@ 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)
+      --ext <names>     Comma separated extensions (e.g. node,gui,media)
       --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/driver/compiler.ts

@@ -69,6 +69,7 @@ function executableName(entry: string, outDir: string, explicit: string | undefi
 export function build(entryPath: string, options: BuildOptions = {}): BuildResult {
   const runner = options.runner ?? realRunner;
   const registry = options.extensions ?? createDefaultRegistry();
+  registry.validate();
   const outDir = resolve(options.outDir ?? join(process.cwd(), "build"));
   const cacheDir = resolve(options.cacheDir ?? defaultCacheDir());
   const emit: EmitKind = options.emit ?? "exe";

package/src/driver/version.ts

@@ -9,4 +9,4 @@
  * `main`/`master` only (see `.githooks/pre-commit`), so feature branches never
  * change this line and merging two of them cannot conflict here.
  */
-export const COMPILER_VERSION = "0.5.21";
+export const COMPILER_VERSION = "0.5.23";

package/src/extensions/catalog.ts

@@ -13,8 +13,9 @@
 import type { Extension } from "./registry.js";
 import { nodeExtension } from "./node/index.js";
 import { guiExtension } from "./gui/index.js";
+import { mediaExtension } from "./media/index.js";
 
 /** Every extension bundled with xbintsc, in registration order. */
 export function bundledExtensions(): readonly Extension[] {
-  return [nodeExtension, guiExtension];
+  return [nodeExtension, guiExtension, mediaExtension];
 }

package/src/extensions/media/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Media extension: `<video>` / `<audio>` decoding for the GUI engine.
+ *
+ * The GUI extension is deliberately decoder-free: it models media elements,
+ * renders their frames and routes the DOM API, but keeps FFmpeg out of `gui.a`
+ * so a program that only needs windows and HTML/CSS does not pay for a media
+ * stack it never uses. This extension supplies the decoding half:
+ *
+ *   - `media.a` (built by `npm run media`) contains the FFmpeg-linked player
+ *     from `runtime/ext_media/media.cpp` and the static FFmpeg libraries;
+ *   - `runtime/ext_media/media_bridge.c` is compiled and linked directly. Its
+ *     constructor installs the player table into the GUI engine and references
+ *     the backend entry points, which makes the linker extract the archive
+ *     member — a static archive whose only entry point is a constructor would
+ *     otherwise never be pulled in.
+ *
+ * There is no importable TypeScript module: the feature is the DOM media
+ * surface that the `gui` module already exposes. Enable both extensions:
+ *
+ *     xbintsc run app.ts --ext gui,media
+ *
+ * The archive is POSIX-only for now (the build needs FFmpeg's `configure` and
+ * an MSVC-compatible FFmpeg has not been built), so Windows reports an
+ * actionable error instead of linking an inert element.
+ */
+
+import { join } from "node:path";
+import type { Extension } from "../registry.js";
+import { findRuntimeDir, platformSlug } from "../../driver/paths.js";
+import { findRuntimeLibrary } from "../../driver/runtime-lib.js";
+
+/** Absolute path to the per-platform prebuilt media archive. */
+function mediaArchive(): string {
+  return join(findRuntimeDir(), "lib", platformSlug(), "media.a");
+}
+
+export const mediaExtension: Extension = {
+  name: "media",
+  description: "Video/audio decoding for <video>/<audio> (requires gui, links FFmpeg)",
+  requires: ["gui"],
+  /**
+   * The registration bridge is a tiny C file linked as a normal object, so its
+   * constructor always runs. Keeping it out of `media.a` is what guarantees the
+   * archive is searched (see the header comment).
+   */
+  runtimeSources: () => [join(findRuntimeDir(), "ext_media", "media_bridge.c")],
+  nativeObjects: () => {
+    if (process.platform === "win32") {
+      throw new Error(
+        "the media extension is not available on Windows yet: it needs an MSVC-compatible " +
+          "FFmpeg build (see doc/gui/known-issues.md). Build without --ext media; media " +
+          "elements then report an 'error' event.",
+      );
+    }
+    const archive = findRuntimeLibrary("media");
+    if (archive === undefined) {
+      throw new Error(
+        `media native library not found at ${mediaArchive()} (or media.lib).\n` +
+          `Build it for ${platformSlug()} first with \`npm run media\` (see doc/gui/build.md).`,
+      );
+    }
+    return [archive];
+  },
+  /** `media.a` is C++ and FFmpeg itself needs libm; the GUI extension already
+   * contributes the C++ runtime and the OS frameworks. */
+  linkerFlags: () => (process.platform === "win32" ? [] : ["-lm"]),
+};

package/src/extensions/registry.ts

@@ -74,6 +74,12 @@ export interface Extension {
   readonly name: string;
   /** Description shown by `xbintsc ext list`. */
   readonly description?: string;
+  /**
+   * Other extensions this one needs. The registry rejects a build that enables
+   * it without them, so a dependent extension fails with an actionable message
+   * instead of an unresolved symbol at link time (e.g. `media` needs `gui`).
+   */
+  readonly requires?: readonly string[];
   /** C/asm sources compiled and linked alongside the generated module. */
   runtimeSources?(): readonly string[];
   /**
@@ -145,6 +151,24 @@ export class ExtensionRegistry {
     return this.extensions.delete(name);
   }
 
+  /**
+   * Throw when a registered extension requires one that is not registered.
+   * Called before a build so `--ext media` without `--ext gui` reports which
+   * flags to pass instead of failing later with an unresolved symbol.
+   */
+  validate(): this {
+    for (const extension of this.extensions.values()) {
+      for (const dependency of extension.requires ?? []) {
+        if (this.extensions.has(dependency)) continue;
+        throw new Error(
+          `extension '${extension.name}' requires the '${dependency}' extension; ` +
+            `pass --ext ${dependency},${extension.name}`,
+        );
+      }
+    }
+    return this;
+  }
+
   get(name: string): Extension | undefined {
     return this.extensions.get(name);
   }

package/src/index.ts

@@ -32,6 +32,7 @@ export {
 export { ExtensionRegistry, createDefaultRegistry, coreExtension, type Extension, type ExtensionModule, type ModuleExport, type ModuleExports, type AssetLoader, type AssetLoadResult } from "./extensions/registry.js";
 export { bundledExtensions } from "./extensions/catalog.js";
 export { nodeExtension } from "./extensions/node/index.js";
+export { mediaExtension } from "./extensions/media/index.js";
 export type { NodeModule } from "./extensions/node/module.js";
 export {
   NativeExtensionError,