xbintsc 0.3.14 → 0.3.16

package/scripts/build-gui.ts

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+/**
+ * Build the GUI extension archive:
+ *
+ *   runtime/lib/<os>-<arch>/gui.a
+ *
+ * The archive bundles the engine (`runtime/ext_gui/*.cpp`) together with a
+ * statically built SDL3, so a released compiler links GUI programs with no
+ * external dependency beyond the OS frameworks declared by
+ * `src/extensions/gui/index.ts`.
+ *
+ * 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,
+ *   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).
+ *
+ * Environment:
+ *   xbintsc_CXX    C++ compiler override (default: clang++/c++/g++)
+ *   xbintsc_CMAKE  CMake override (default: a vendored CMake, then `cmake`)
+ *   xbintsc_AR     archiver override (default: llvm-ar, then ar)
+ *   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)
+ *
+ * On Windows the engine is compiled with `clang++` against the MSVC ABI (run
+ * from a Visual Studio developer prompt so `INCLUDE`/`LIB` are set) and merged
+ * into a COFF `gui.lib` with `llvm-ar`.
+ */
+
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
+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";
+
+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");
+const sdlBuild = join(sdlSrc, "build");
+const freetypeSrc = join(vendorDir, "freetype");
+const freetypeBuild = join(vendorDir, "freetype-build");
+const harfbuzzSrc = join(vendorDir, "harfbuzz");
+const harfbuzzBuild = join(vendorDir, "harfbuzz-build");
+const objDir = join(root, "build", "gui-obj");
+const outDir = join(runtimeDir, "lib", platformSlug());
+
+const isWindows = process.platform === "win32";
+const objectSuffix = isWindows ? ".obj" : ".o";
+const output = join(outDir, isWindows ? "gui.lib" : "gui.a");
+
+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 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`;
+
+function fail(message: string): never {
+  console.error(`xbintsc: ${message}`);
+  process.exit(1);
+}
+
+function run(
+  command: string,
+  args: readonly string[],
+  options: { input?: string; quietStderr?: boolean } = {},
+): 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,
+  });
+  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;
+}
+
+/** Vendored CMake from `vendor/tools`, then `cmake` on PATH. */
+function findCmake(): string {
+  const candidates: string[] = [];
+  if (process.env.xbintsc_CMAKE) candidates.push(process.env.xbintsc_CMAKE);
+  if (existsSync(join(vendorDir, "tools"))) {
+    for (const entry of readdirSync(join(vendorDir, "tools"))) {
+      if (!entry.startsWith("cmake-")) continue;
+      candidates.push(join(vendorDir, "tools", entry, "CMake.app", "Contents", "bin", "cmake"));
+      candidates.push(join(vendorDir, "tools", entry, "bin", "cmake"));
+    }
+  }
+  candidates.push("cmake");
+  const cmake = firstAvailable(candidates);
+  if (!cmake) fail("no CMake found; install it or set xbintsc_CMAKE");
+  return cmake;
+}
+
+function findCxx(): string {
+  const cxx = firstAvailable([process.env.xbintsc_CXX, "clang++", "c++", "g++"]);
+  if (!cxx) fail("no C++ compiler found; install clang++ or set xbintsc_CXX");
+  return cxx;
+}
+
+function findArchiver(): string {
+  const ar = firstAvailable([process.env.xbintsc_AR, "llvm-ar", "ar"]);
+  if (!ar) fail("no archiver found; set xbintsc_AR to llvm-ar or ar");
+  return ar;
+}
+
+/** First of `candidates` that exists on disk (CMake generators place static
+ * libraries either at the build root or under `Release/`). */
+function firstExisting(candidates: readonly string[]): string | undefined {
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return 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`). */
+function builtLibrary(buildDir: string, names: readonly string[], pattern?: RegExp): string | undefined {
+  const candidates: string[] = [];
+  for (const name of names) {
+    candidates.push(join(buildDir, name));
+    candidates.push(join(buildDir, "Release", name));
+    candidates.push(join(buildDir, "Debug", name));
+  }
+  const exact = firstExisting(candidates);
+  if (exact || !pattern) return exact;
+  for (const dir of [buildDir, join(buildDir, "Release"), join(buildDir, "Debug")]) {
+    if (!existsSync(dir)) continue;
+    for (const entry of readdirSync(dir)) {
+      if (pattern.test(entry)) return join(dir, entry);
+    }
+  }
+  return undefined;
+}
+
+function sdlArchive(): string | undefined {
+  return builtLibrary(sdlBuild, ["libSDL3.a", "SDL3-static.lib", "SDL3.lib"], /^SDL3[-\w.]*\.lib$/);
+}
+function freetypeArchive(): string | undefined {
+  return builtLibrary(freetypeBuild, ["libfreetype.a", "freetype.lib"], /^freetype[-\d.]*\.lib$/);
+}
+function harfbuzzArchive(): string | undefined {
+  return builtLibrary(harfbuzzBuild, ["libharfbuzz.a", "harfbuzz.lib"], /^harfbuzz[-\d.]*\.lib$/);
+}
+
+/* -- 1. SDL3 source ------------------------------------------------------- */
+
+if (!existsSync(join(sdlSrc, "CMakeLists.txt"))) {
+  console.log(`xbintsc: fetching SDL3 ${SDL_TAG} into vendor/SDL`);
+  mkdirSync(vendorDir, { recursive: true });
+  run("git", ["clone", "--depth", "1", "--branch", SDL_TAG, "https://github.com/libsdl-org/SDL.git", sdlSrc]);
+}
+
+/* -- 2. static SDL3 ------------------------------------------------------- */
+
+const existingSdlArchive = sdlArchive();
+if (!existingSdlArchive) {
+  const cmake = findCmake();
+  console.log(`xbintsc: building static SDL3 with ${cmake}`);
+  const configureArgs = [
+    "-S", sdlSrc,
+    "-B", sdlBuild,
+    "-DCMAKE_BUILD_TYPE=Release",
+    "-DSDL_SHARED=OFF",
+    "-DSDL_STATIC=ON",
+    "-DSDL_TESTS=OFF",
+    "-DSDL_EXAMPLES=OFF",
+  ];
+  run(cmake, configureArgs);
+  run(cmake, ["--build", sdlBuild, "--config", "Release", "--target", "SDL3-static", "--parallel"]);
+} else {
+  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. */
+function ensureTarballSource(name: string, url: string, extractedName: string): string {
+  const destination = join(vendorDir, name);
+  if (existsSync(join(destination, "CMakeLists.txt"))) 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;
+}
+
+ensureTarballSource("freetype", FREETYPE_URL, `freetype-${FREETYPE_VERSION}`);
+ensureTarballSource("harfbuzz", HARFBUZZ_URL, `harfbuzz-${HARFBUZZ_VERSION}`);
+
+if (!existsSync(freetypeArchive() ?? "")) {
+  const cmake = findCmake();
+  console.log("xbintsc: building static FreeType");
+  run(cmake, [
+    "-S", freetypeSrc,
+    "-B", freetypeBuild,
+    "-DCMAKE_BUILD_TYPE=Release",
+    "-DBUILD_SHARED_LIBS=OFF",
+    /* We only need TrueType/OpenType outlines; skip the optional codecs. */
+    "-DFT_DISABLE_ZLIB=TRUE",
+    "-DFT_DISABLE_BZIP2=TRUE",
+    "-DFT_DISABLE_PNG=TRUE",
+    "-DFT_DISABLE_HARFBUZZ=TRUE",
+    "-DFT_DISABLE_BROTLI=TRUE",
+  ]);
+  run(cmake, ["--build", freetypeBuild, "--config", "Release", "--parallel"]);
+} else {
+  console.log(`xbintsc: reusing existing ${freetypeArchive()}`);
+}
+
+if (!existsSync(harfbuzzArchive() ?? "")) {
+  const cmake = findCmake();
+  console.log("xbintsc: building static HarfBuzz");
+  run(cmake, [
+    "-S", harfbuzzSrc,
+    "-B", harfbuzzBuild,
+    "-DCMAKE_BUILD_TYPE=Release",
+    "-DBUILD_SHARED_LIBS=OFF",
+    "-DHB_BUILD_UTILS=OFF",
+    "-DHB_BUILD_TESTS=OFF",
+    "-DHB_BUILD_SUBSET=OFF",
+    "-DHB_HAVE_FREETYPE=OFF",
+    "-DHB_HAVE_GLIB=OFF",
+    "-DHB_HAVE_ICU=OFF",
+    "-DHB_HAVE_GRAPHITE2=OFF",
+  ]);
+  run(cmake, ["--build", harfbuzzBuild, "--config", "Release", "--parallel"]);
+} else {
+  console.log(`xbintsc: reusing existing ${harfbuzzArchive()}`);
+}
+
+/* -- 3. engine objects ---------------------------------------------------- */
+
+const cxx = findCxx();
+mkdirSync(objDir, { recursive: true });
+const includeFlags = [
+  "-I", runtimeDir,
+  "-I", join(sdlSrc, "include"),
+  "-I", join(freetypeSrc, "include"),
+  "-I", join(freetypeBuild, "include"),
+  "-I", join(harfbuzzSrc, "src"),
+];
+const sources = readdirSync(engineDir)
+  .filter((entry) => entry.endsWith(".cpp"))
+  .sort();
+
+const objects: string[] = [];
+const cxxFlags = ["-std=c++17", "-O2", "-Wall", "-Wextra", ...includeFlags];
+/* The MSVC ABI rejects `-fPIC`; position independence is the default elsewhere. */
+if (!isWindows) cxxFlags.splice(3, 0, "-fPIC");
+for (const source of sources) {
+  const object = join(objDir, source.replace(/\.cpp$/, objectSuffix));
+  console.log(`xbintsc: compiling ${source}`);
+  run(cxx, [...cxxFlags, "-c", join(engineDir, source), "-o", object]);
+  objects.push(object);
+}
+
+/* -- 4. merge into gui.a / gui.lib ---------------------------------------- */
+
+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 libraries = [sdl, freetype, harfbuzz];
+
+mkdirSync(outDir, { recursive: true });
+rmSync(output, { force: true });
+if (process.platform === "darwin") {
+  /* libtool warns about the empty object files SDL3's archive carries; hide it
+   * unless the merge actually fails. */
+  run("libtool", ["-static", "-o", output, ...objects, ...libraries], {
+    quietStderr: true,
+  });
+} else {
+  /* `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 ar = findArchiver();
+  const script = [
+    `create ${mri(output)}`,
+    ...objects.map((object) => `addmod ${mri(object)}`),
+    ...libraries.map((library) => `addlib ${mri(library)}`),
+    "save",
+    "end",
+  ].join("\n");
+  run(ar, ["-M"], { input: script });
+}
+
+console.log(`xbintsc: wrote ${output}`);

package/scripts/build-runtime.ts

@@ -29,16 +29,15 @@ const outDir = join(runtimeDir, "lib", platformSlug());
 const objDir = join(root, "build", "runtime-obj");
 
 if (process.platform === "win32") {
-  // The Windows release ships no prebuilt archives yet: the current MSVC CI
-  // cannot produce MinGW-compatible objects, so the driver compiles the C
-  // sources on demand. Revisit once the bundled MinGW-w64 ABI lands.
-  // See doc/self-contained-roadmap.md.
-  console.log("xbintsc: skipped runtime archives on Windows until the MinGW-w64 toolchain lands");
+  // The driver links with the MSVC ABI on Windows, where the prebuilt archives
+  // are unnecessary: `build` compiles the runtime C sources on demand with the
+  // user's clang. (Producing MSVC-compatible COFF `.lib` archives is possible
+  // but not worth the extra step.)
+  console.log("xbintsc: skipping runtime archives on Windows; the driver compiles the C sources on demand");
   process.exit(0);
 }
 
-// Use the same toolchain the driver will: a bundled clang when present, with its
-// `LD_LIBRARY_PATH` (the legacy `libtinfo.so.5` on Linux) threaded through.
+// Use the same toolchain the driver will.
 const toolchain = resolveToolchain();
 const clang = toolchain.clang;
 const childEnv = Object.assign({}, process.env, toolchain.env);
@@ -54,7 +53,7 @@ function findArchiver(clangPath: string): string {
   const exe = process.platform === "win32" ? ".exe" : "";
   const candidates = [
     process.env.xbintsc_AR,
-    // A bundled toolchain ships `llvm-ar` next to clang.
+    // A clang install usually ships `llvm-ar` next to the driver.
     dir === "." ? undefined : join(dir, `llvm-ar${exe}`),
     "llvm-ar",
     "ar",

package/scripts/coverage-runtime.ts

@@ -160,9 +160,9 @@ function runs(command: string): boolean {
 
 /**
  * Locate the LLVM tool `name` (`llvm-profdata`/`llvm-cov`) that matches the
- * clang the driver resolved. The bundled toolchains ship the tools next to
- * clang and cover the versioned system installs, so search there first: mixing
- * versions makes `llvm-profdata` reject the profile format.
+ * clang the driver resolved. Prefer the tool next to clang, then the
+ * version-suffixed system installs: mixing versions makes `llvm-profdata`
+ * reject the profile format.
  */
 function findTool(clang: string, name: string): string | undefined {
   const exe = process.platform === "win32" ? ".exe" : "";
@@ -282,7 +282,7 @@ function main(): void {
       profdataTool ? undefined : "llvm-profdata",
       covTool ? undefined : "llvm-cov",
     ].filter(Boolean).join(", ");
-    skip(`${missing} not found for ${clang}; install LLVM or use the bundled toolchain`, options.strict);
+    skip(`${missing} not found for ${clang}; install the LLVM tools (llvm-profdata, llvm-cov)`, options.strict);
   }
 
   if (!options.reportOnly) runTests(options);

package/scripts/package-release.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Assemble a self-contained release archive for the current platform:
+ * Assemble a release archive for the current platform:
  *
  *   dist/release/xbintsc-<version>-<os>-<arch>.tar.gz        (or .tar.zst)
  *   dist/release/xbintsc-<version>-<os>-<arch>.tar.gz.sha256
@@ -10,23 +10,24 @@
  *
  * The unpacked staging tree is built under `build/release-stage/`, never under
  * `dist/release/`, so an upload glob over `dist/release/*` cannot accidentally
- * ship the (multi-GB) tree alongside the archive.
+ * ship the (large) tree alongside the archive.
+ *
+ * xbintsc does not bundle a compiler: the archive holds only the self-hosted
+ * binary and the C runtime sources plus prebuilt archives. Users provide the
+ * toolchain themselves (see `doc/requirements.md`).
  *
  * Layout inside the archive:
  *
  *   xbintsc-<os>-<arch>/
  *     bin/xbintsc[.exe]     the self-hosted compiler
  *     runtime/              C runtime sources + prebuilt runtime/lib/<slug>
- *     vendor/<slug>/        the bundled clang+lld toolchain (Linux/Windows)
  *     README.md
  *
- * The compiler locates `runtime/` and `vendor/` relative to its own executable
- * (see `findRuntimeDir`/`findVendorDir`), so this tree runs with no system
- * toolchain installed.
+ * The compiler locates `runtime/` relative to its own executable (see
+ * `findRuntimeDir`), so this tree runs without any bundled toolchain.
  *
  * Inputs:
  *   - the self-hosted binary staged at `dist/xbintsc[.exe]` (CI copies it there)
- *   - `vendor/<slug>/`, fetched by `scripts/fetch-toolchain.ts`
  *   - `runtime/lib/<slug>/`, built by `scripts/build-runtime.ts`
  */
 
@@ -37,9 +38,7 @@ import {
   chmodSync,
   existsSync,
   mkdirSync,
-  readdirSync,
   readFileSync,
-  realpathSync,
   rmSync,
   statSync,
   writeFileSync,
@@ -49,14 +48,12 @@ import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   findRuntimeDir,
-  platformSlug,
   releaseArchiveBase,
   releaseArchiveExtension,
   releaseArchiveFileName,
 } from "../src/driver/paths.js";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const slug = platformSlug();
 const base = releaseArchiveBase();
 const version = (
   JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as { version: string }
@@ -77,55 +74,6 @@ function firstExisting(candidates: readonly string[]): string | undefined {
   return undefined;
 }
 
-/**
- * Copy only the parts of the fetched toolchain that xbintsc actually runs.
- *
- * The official LLVM release unpacks to ~7 GB: every MLIR/Flang/lldb tool, the
- * static archives and the full C++ headers. The compiler only shells out to the
- * clang driver, the lld linker and llvm-ar, and clang additionally needs its own
- * resource directory (`lib/clang/<version>`, the builtin headers and
- * compiler-rt). Copying just those keeps the archive ~100x smaller.
- */
-function stageToolchain(vendor: string, dest: string): void {
-  const exe = process.platform === "win32" ? ".exe" : "";
-  mkdirSync(join(dest, "bin"), { recursive: true });
-
-  const real = (...candidates: readonly string[]): string | undefined => {
-    const found = firstExisting(candidates.map((candidate) => join(vendor, candidate)));
-    return found ? realpathSync(found) : undefined;
-  };
-  const copyAs = (source: string | undefined, name: string): void => {
-    if (!source) return;
-    const target = join(dest, "bin", name);
-    copyFileSync(source, target);
-    if (process.platform !== "win32") chmodSync(target, 0o755);
-  };
-
-  // In the official release `clang`/`ld.lld` are symlinks into the bin/ dir;
-  // copy the resolved targets under the names the toolchain provider (and
-  // clang's `-fuse-ld=lld`) expect next to `bin/clang`.
-  copyAs(real(`bin/clang${exe}`, `bin/clang-18${exe}`), `clang${exe}`);
-  copyAs(real(`bin/ld.lld${exe}`, `bin/lld${exe}`), `ld.lld${exe}`);
-  copyAs(real(`bin/llvm-ar${exe}`, "bin/llvm-ar"), `llvm-ar${exe}`);
-
-  // clang's resource directory: builtin headers + compiler-rt archives.
-  const resourceDir = join(vendor, "lib", "clang");
-  if (existsSync(resourceDir)) {
-    cpSync(resourceDir, join(dest, "lib", "clang"), { recursive: true });
-  }
-
-  // Shared libraries the fetch placed next to the toolchain (on Linux that is
-  // the legacy `libtinfo.so.5` the official build still links).
-  const libDir = join(vendor, "lib");
-  if (existsSync(libDir)) {
-    for (const entry of readdirSync(libDir, { withFileTypes: true })) {
-      if (/^(.*\.so(\.\d+)*|.*\.dylib|.*\.dll)$/.test(entry.name)) {
-        cpSync(join(libDir, entry.name), join(dest, "lib", entry.name), { recursive: true });
-      }
-    }
-  }
-}
-
 const distDir = join(root, "dist");
 const binary = firstExisting([
   join(distDir, `xbintsc${exeSuffix}`),
@@ -138,7 +86,7 @@ if (!binary) {
 
 // Archives go to `dist/release/`; the unpacked staging tree goes to
 // `build/release-stage/` so the upload glob over `dist/release/*` cannot pick up
-// the raw tree (which would ship the toolchain twice, and uncompressed).
+// the raw tree.
 const releaseRoot = join(distDir, "release");
 const stageRoot = join(root, "build", "release-stage");
 const stage = join(stageRoot, base);
@@ -156,33 +104,13 @@ console.log(`xbintsc: packaged binary ${basename(binary)} (${statSync(binary).si
 cpSync(findRuntimeDir(), join(stage, "runtime"), { recursive: true });
 console.log("xbintsc: packaged runtime/");
 
-// 3. The bundled toolchain, when one was fetched for this platform.
-const vendor = join(root, "vendor", slug);
-if (existsSync(join(vendor, "bin"))) {
-  if (process.platform === "win32") {
-    // llvm-mingw spreads its MinGW-w64 CRT/import libraries across the tree, so
-    // bundling it whole is the safe default there for now.
-    cpSync(vendor, join(stage, "vendor", slug), { recursive: true });
-  } else {
-    stageToolchain(vendor, join(stage, "vendor", slug));
-  }
-  console.log(`xbintsc: packaged vendor/${slug}/`);
-} else if (process.platform === "linux" || process.platform === "win32") {
-  console.warn(
-    `xbintsc: warning: no vendor/${slug}/ found; the release will rely on a system toolchain. ` +
-      "Run `npm run fetch-toolchain` first for a self-contained archive.",
-  );
-} else {
-  console.log(`xbintsc: no bundled toolchain for ${slug}; relying on the system SDK (macOS)`);
-}
-
-// 4. Human-facing notes.
+// 3. Human-facing notes.
 for (const name of ["README.md", "LICENSE"]) {
   const source = join(root, name);
   if (existsSync(source)) copyFileSync(source, join(stage, name));
 }
 
-// 5. Archive it. Prefer zstd when available, otherwise gzip.
+// 4. Archive it. Prefer zstd when available, otherwise gzip.
 const hasZstd = !spawnSync("zstd", ["--version"], { stdio: "ignore" }).error;
 const extension = releaseArchiveExtension(hasZstd);
 const archive = join(releaseRoot, `${archiveBase}${extension}`);
@@ -192,7 +120,7 @@ const tar = spawnSync("tar", tarArgs, { stdio: "inherit" });
 if (tar.error) fail(`failed to run tar: ${tar.error.message}`);
 if (tar.status !== 0) fail(`tar exited with ${tar.status}`);
 
-// 6. Checksum, so users can verify the download.
+// 5. Checksum, so users can verify the download.
 const digest = createHash("sha256").update(readFileSync(archive)).digest("hex");
 writeFileSync(`${archive}.sha256`, `${digest}  ${basename(archive)}\n`);
 

package/src/cli/main.ts

@@ -24,7 +24,6 @@ import { resolveToolchain } from "../driver/toolchain-provider.js";
 import { realRunner } from "../driver/toolchain.js";
 import { createDefaultRegistry, type ExtensionRegistry } from "../extensions/registry.js";
 import { bundledExtensions } from "../extensions/catalog.js";
-import { nodeExtension } from "../extensions/node/index.js";
 import { nativeExtensionFromManifest } from "../extensions/native.js";
 
 export interface CliIo {
@@ -100,9 +99,11 @@ function buildRegistry(flags: Map<string, string | boolean>): ExtensionRegistry
   const registry = createDefaultRegistry();
   const requested = flags.get("ext");
   if (typeof requested === "string") {
+    const bundled = bundledExtensions();
     for (const name of requested.split(",").map((n) => n.trim()).filter(Boolean)) {
-      if (name === "node") registry.register(nodeExtension);
-      else throw new Error(`Unknown extension '${name}'`);
+      const extension = bundled.find((candidate) => candidate.name === name);
+      if (!extension) throw new Error(`Unknown extension '${name}'`);
+      registry.register(extension);
     }
   }
   // Each `--ext-native` value is a manifest path describing a pre-built C++ or
@@ -172,7 +173,10 @@ function doctor(io: CliIo): number {
     io.stdout(`toolchain  : ${toolchain.clang} (${toolchain.source})\n`);
     io.stdout(`compiler   : ${firstLine(version) || "unknown"}\n`);
   } catch {
-    io.stdout("toolchain  : not found (install the Xcode Command Line Tools or set xbintsc_CLANG)\n");
+    io.stdout("toolchain  : not found\n");
+    io.stdout("  install one of: Xcode Command Line Tools (`xcode-select --install`) on macOS,\n");
+    io.stdout("  clang+lld (apt/dnf/pacman) on Linux, or LLVM + Visual Studio C++ build tools on Windows,\n");
+    io.stdout("  then re-run; or set xbintsc_CLANG to a clang binary. See doc/requirements.md.\n");
   }
 
   try {

package/src/codegen/generator/state.ts

@@ -215,6 +215,10 @@ export const RUNTIME_DECLARATIONS: readonly string[] = [
   "declare i64 @xt_decode_uri(i32, i64*)",
   "declare i64 @xt_btoa(i32, i64*)",
   "declare i64 @xt_atob(i32, i64*)",
+  "declare i64 @xt_set_timeout(i32, i64*)",
+  "declare i64 @xt_clear_timeout(i32, i64*)",
+  "declare i64 @xt_set_interval(i32, i64*)",
+  "declare i64 @xt_clear_interval(i32, i64*)",
   "declare i64 @xt_number_ctor(i32, i64*)",
   "declare i64 @xt_bigint_ctor(i32, i64*)",
   "declare i64 @xt_bigint_static(i64, i32, i64*)",
@@ -246,6 +250,10 @@ export const RUNTIME_DECLARATIONS: readonly string[] = [
   "declare i64 @xt_builtin_value_encodeURI(i64, i64, i32, i64*)",
   "declare i64 @xt_builtin_value_decodeURIComponent(i64, i64, i32, i64*)",
   "declare i64 @xt_builtin_value_decodeURI(i64, i64, i32, i64*)",
+  "declare i64 @xt_builtin_value_setTimeout(i64, i64, i32, i64*)",
+  "declare i64 @xt_builtin_value_clearTimeout(i64, i64, i32, i64*)",
+  "declare i64 @xt_builtin_value_setInterval(i64, i64, i32, i64*)",
+  "declare i64 @xt_builtin_value_clearInterval(i64, i64, i32, i64*)",
   "declare i64 @xt_builtin_value_number(i64, i64, i32, i64*)",
   "declare i64 @xt_builtin_value_string(i64, i64, i32, i64*)",
   "declare i64 @xt_builtin_value_boolean(i64, i64, i32, i64*)",

package/src/codegen/generator/tables.ts

@@ -12,12 +12,11 @@ import {
 /**
  * True when a `try` frame must be saved with `_setjmpex` rather than `_setjmp`.
  *
- * 64-bit Windows on ARM has no `_setjmp`: both the UCRT and MinGW-w64 declare
- * `setjmp` as `_setjmpex(buf, sponentry)` there, so the linker expects
- * `_setjmpex` (with the caller's stack pointer at entry, `llvm.sponentry`,
- * instead of its frame pointer). clang lowers a C `setjmp` on this target to
- * exactly that pair. Checked at code-generation time because xbintsc builds for
- * its own host.
+ * 64-bit Windows on ARM has no `_setjmp`: the UCRT declares `setjmp` as
+ * `_setjmpex(buf, sponentry)` there, so the linker expects `_setjmpex` (with the
+ * caller's stack pointer at entry, `llvm.sponentry`, instead of its frame
+ * pointer). clang lowers a C `setjmp` on this target to exactly that pair.
+ * Checked at code-generation time because xbintsc builds for its own host.
  */
 export function requiresSetjmpex(platform: string, arch: string): boolean {
   return platform === "win32" && arch === "arm64";
@@ -124,6 +123,10 @@ export const GLOBAL_FUNCTIONS: Record<string, string> = {
   decodeURI: "xt_decode_uri",
   btoa: "xt_btoa",
   atob: "xt_atob",
+  setTimeout: "xt_set_timeout",
+  clearTimeout: "xt_clear_timeout",
+  setInterval: "xt_set_interval",
+  clearInterval: "xt_clear_interval",
   Number: "xt_number_ctor",
   String: "xt_string_ctor",
   Boolean: "xt_boolean_ctor",
@@ -143,6 +146,10 @@ export const BUILTIN_FUNCTION_VALUES: Record<string, string> = {
   encodeURI: "xt_builtin_value_encodeURI",
   decodeURIComponent: "xt_builtin_value_decodeURIComponent",
   decodeURI: "xt_builtin_value_decodeURI",
+  setTimeout: "xt_builtin_value_setTimeout",
+  clearTimeout: "xt_builtin_value_clearTimeout",
+  setInterval: "xt_builtin_value_setInterval",
+  clearInterval: "xt_builtin_value_clearInterval",
   Number: "xt_builtin_value_number",
   String: "xt_builtin_value_string",
   Boolean: "xt_builtin_value_boolean",