xbintsc 0.5.52 → 0.6.8

package/scripts/build-gui.ts

@@ -49,15 +49,18 @@ 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 { applyMacosDeploymentTarget } from "../src/driver/platform-support.js";
 import { isMsvcTarget, probeClang, realRunner } from "../src/driver/toolchain.js";
 import { resolveToolchain } from "../src/driver/toolchain-provider.js";
 import {
   cmakeToolchainArgs,
+  cxxCompileFlags,
   HB_LEAN_DEFINES,
   LEAN_SDL_OPTIONS,
   SECTION_CMAKE_FLAGS,
   SECTION_FLAGS,
 } from "./gui-build-options.js";
+import { ensureDeploymentTarget } from "./gui-build-cache.js";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const runtimeDir = join(root, "runtime");
@@ -99,6 +102,10 @@ const isWindows = process.platform === "win32";
 const objectSuffix = isWindows ? ".obj" : ".o";
 const output = join(outDir, isWindows ? "gui.lib" : "gui.a");
 
+/* The vendored CMake builds and the direct engine compiles must target the
+ * oldest supported macOS, not the build machine's version. */
+applyMacosDeploymentTarget();
+
 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";
@@ -204,19 +211,19 @@ function findArchiver(clangPath: string): string {
  * sibling clang++, and the matching llvm-ar. No `gcc`/`g++` fallbacks, and
  * Windows never falls back to a non-LLVM archiver — mixing another C++ runtime
  * or object format would break the final link. */
-function driverClang(): string {
+function driverToolchain(): ReturnType<typeof resolveToolchain> {
   try {
-    return resolveToolchain().clang;
+    return resolveToolchain();
   } catch (error) {
     fail(error instanceof Error ? error.message : String(error));
   }
 }
 
-const clang = driverClang();
+const toolchain = driverToolchain();
+const clang = toolchain.clang;
 const clangxx = findClangxx(clang);
 const llvmAr = findArchiver(clang);
 
-
 /** The compiler a previous CMake configure recorded for `buildDir`. */
 function cachedCompiler(buildDir: string, variable: string): string | undefined {
   const cache = join(buildDir, "CMakeCache.txt");
@@ -348,6 +355,7 @@ if (!existsSync(join(sdlSrc, "CMakeLists.txt"))) {
 
 /* -- 2. static SDL3 ------------------------------------------------------- */
 
+ensureDeploymentTarget("SDL3", sdlBuild);
 const existingSdlArchive = sdlArchive();
 if (!existingSdlArchive) {
   /* Older trees configured SDL inside its source (`vendor/SDL/build`) and a
@@ -392,6 +400,7 @@ if (!existingSdlArchive) {
 ensureTarballSource("freetype", FREETYPE_URL, `freetype-${FREETYPE_VERSION}`);
 ensureTarballSource("harfbuzz", HARFBUZZ_URL, `harfbuzz-${HARFBUZZ_VERSION}`);
 
+ensureDeploymentTarget("FreeType", freetypeBuild);
 if (!existsSync(freetypeArchive() ?? "")) {
   const cmake = configureCmake("FreeType", freetypeSrc, freetypeBuild, [
     "-DCMAKE_BUILD_TYPE=Release",
@@ -410,6 +419,7 @@ if (!existsSync(freetypeArchive() ?? "")) {
   console.log(`xbintsc: reusing existing ${freetypeArchive()}`);
 }
 
+ensureDeploymentTarget("HarfBuzz", harfbuzzBuild);
 if (!existsSync(harfbuzzArchive() ?? "")) {
   const cmake = configureCmake("HarfBuzz", harfbuzzSrc, harfbuzzBuild, [
     "-DCMAKE_BUILD_TYPE=Release",
@@ -456,6 +466,7 @@ ensureTarballSource("glslang", GLSLANG_URL, `glslang-${GLSLANG_VERSION}`);
 ensureTarballSource(join("glslang", "External", "spirv-headers"), SPIRV_HEADERS_URL,
   `SPIRV-Headers-${SPIRV_HEADERS_VERSION}`);
 
+ensureDeploymentTarget("glslang", glslangBuild);
 if (!existsSync(glslangArchive() ?? "")) {
   const cmake = configureCmake("glslang", glslangSrc, glslangBuild, [
     "-DCMAKE_BUILD_TYPE=Release",
@@ -484,6 +495,7 @@ const metalBackend = process.platform === "darwin";
 if (metalBackend) {
   ensureTarballSource("spirv-cross", SPIRV_CROSS_URL, `SPIRV-Cross-${SPIRV_CROSS_VERSION}`);
 
+  ensureDeploymentTarget("SPIRV-Cross", spirvCrossBuild);
   if (!existsSync(spirvCrossArchive("spirv-cross-msl") ?? "")) {
     const cmake = configureCmake("SPIRV-Cross", spirvCrossSrc, spirvCrossBuild, [
       "-DCMAKE_BUILD_TYPE=Release",
@@ -523,7 +535,7 @@ const sources = readdirSync(engineDir)
   .sort();
 
 const objects: string[] = [];
-const cxxFlags = ["-std=c++17", "-O2", "-Wall", "-Wextra", ...SECTION_FLAGS, ...includeFlags];
+const cxxFlags = cxxCompileFlags(toolchain.sdkRoot, includeFlags);
 /* The engine is C++ and the MSVC C++ runtime must match the static C CRT that
  * clang links by default, so let every engine object record `libcpmt` as a
  * default library. The extension itself only contributes the DLL import library

package/scripts/build-media.ts

@@ -48,8 +48,11 @@ 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 { applyMacosDeploymentTarget } from "../src/driver/platform-support.js";
 import { isMsvcTarget, probeClang, realRunner } from "../src/driver/toolchain.js";
 import { resolveToolchain } from "../src/driver/toolchain-provider.js";
+import { downloadTarball } from "./fetch-tarball.js";
+import { cxxCompileFlags } from "./gui-build-options.js";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const runtimeDir = join(root, "runtime");
@@ -66,6 +69,10 @@ const objDir = join(root, "build", "media-obj");
 const outDir = join(runtimeDir, "lib", platformSlug());
 const output = join(outDir, isWindows ? "media.lib" : "media.a");
 
+/* FFmpeg and the player object must target the oldest supported macOS. Clang's
+ * Darwin driver and FFmpeg's configure both read the environment variable. */
+applyMacosDeploymentTarget();
+
 const FFMPEG_VERSION = process.env.FFMPEG_VERSION || "7.1";
 const FFMPEG_URL = `https://ffmpeg.org/releases/ffmpeg-${FFMPEG_VERSION}.tar.xz`;
 
@@ -161,27 +168,49 @@ function findArchiver(clangPath: string): string {
   return archiver;
 }
 
-function driverClang(): string {
+function driverToolchain(): ReturnType<typeof resolveToolchain> {
   try {
-    return resolveToolchain().clang;
+    return resolveToolchain();
   } catch (error) {
     fail(error instanceof Error ? error.message : String(error));
   }
 }
 
-/** Download the FFmpeg release tarball and extract it under `vendor/ffmpeg`. */
+/** Fetch and extract the FFmpeg release tarball under `vendor/ffmpeg`.
+ *
+ * The tarball is kept (`vendor/ffmpeg-<version>.tar.xz`) so CI can cache it by
+ * `FFMPEG_VERSION`, and `downloadTarball` retries the transient TLS failures the
+ * release host throws; the release marker re-extracts a tree of another release. */
 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}`);
+  if (existsSync(join(ffmpegSrc, "configure")) && recordedRelease(ffmpegSrc) === FFMPEG_VERSION) return;
+  const tarball = join(vendorDir, `ffmpeg-${FFMPEG_VERSION}.tar.xz`);
   mkdirSync(vendorDir, { recursive: true });
-  run("curl", ["-sL", "--fail", "-o", tarball, FFMPEG_URL]);
+  if (existsSync(tarball)) {
+    console.log(`xbintsc: extracting cached ${tarball}`);
+  } else {
+    try {
+      downloadTarball(tarball, FFMPEG_URL, `FFmpeg ${FFMPEG_VERSION}`);
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error));
+    }
+  }
   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 });
+  writeFileSync(releaseStamp(ffmpegSrc), `${FFMPEG_VERSION}\n`);
+}
+
+/** Marker recording the FFmpeg release a source tree or installed prefix holds. */
+function releaseStamp(directory: string): string {
+  return join(directory, ".xbintsc-ffmpeg-version");
+}
+
+/** The release recorded in `directory`, or "" when it predates the marker. */
+function recordedRelease(directory: string): string {
+  const stamp = releaseStamp(directory);
+  return existsSync(stamp) ? readFileSync(stamp, "utf8").trim() : "";
 }
 
 function ffmpegStaticLibraries(): string[] | undefined {
@@ -194,6 +223,44 @@ function ffmpegInstalled(): boolean {
   return ffmpegStaticLibraries() !== undefined && existsSync(join(ffmpegInstall, "include", "libavutil", "avutil.h"));
 }
 
+/** Marker recording the deployment target `dist` was built for (macOS). */
+function deploymentStamp(): string {
+  return join(ffmpegInstall, ".xbintsc-deployment-target");
+}
+
+/**
+ * Drop a cached FFmpeg build tree that was configured for another macOS
+ * deployment target. `dist` is reused when it already holds the libraries, and
+ * FFmpeg's Makefile does not notice a changed `MACOSX_DEPLOYMENT_TARGET`; a
+ * tree from an earlier checkout would keep 15.5 objects in `media.a`. A tree
+ * without the marker predates this check and is rebuilt once.
+ */
+function ensureDeploymentTarget(): void {
+  if (process.platform !== "darwin") return;
+  const wanted = process.env.MACOSX_DEPLOYMENT_TARGET ?? "";
+  const stamp = deploymentStamp();
+  const recorded = existsSync(stamp) ? readFileSync(stamp, "utf8").trim() : "";
+  if (recorded === wanted) return;
+  if (existsSync(ffmpegBuild)) {
+    console.log(`xbintsc: FFmpeg was built for macOS '${recorded}'; rebuilding for '${wanted}'`);
+    rmSync(ffmpegBuild, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Drop a cached FFmpeg build tree from another release: neither the Makefile nor
+ * `dist` is keyed by `FFMPEG_VERSION`, so reusing it would link the previous
+ * release's libraries. A `dist` without the marker predates this check and is
+ * rebuilt once.
+ */
+function ensureBuildRelease(): void {
+  if (!ffmpegInstalled()) return;
+  const recorded = recordedRelease(ffmpegInstall);
+  if (recorded === FFMPEG_VERSION) return;
+  console.log(`xbintsc: FFmpeg was built as '${recorded || "unknown"}'; rebuilding for '${FFMPEG_VERSION}'`);
+  rmSync(ffmpegBuild, { recursive: true, force: true });
+}
+
 /** Arguments shared by the POSIX and Windows FFmpeg configure runs. */
 function ffmpegConfigureArgs(): string[] {
   const prefix = isWindows ? ffmpegInstall.replace(/\\/g, "/") : ffmpegInstall;
@@ -443,7 +510,8 @@ 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 toolchain = driverToolchain();
+const clang = toolchain.clang;
 const clangxx = findClangxx(clang);
 const archiver = findArchiver(clang);
 const windowsTools = isWindows
@@ -456,6 +524,8 @@ const windowsTools = isWindows
 
 /* -- 2. minimal static FFmpeg --------------------------------------------- */
 
+ensureDeploymentTarget();
+ensureBuildRelease();
 if (!ffmpegInstalled()) {
   if (windowsTools) {
     buildFfmpegWindows(windowsTools.shell, windowsTools.clangCl, windowsTools.msvcBin);
@@ -470,6 +540,12 @@ if (!ffmpegInstalled()) {
 } else {
   console.log(`xbintsc: reusing existing ${ffmpegInstall}/lib`);
 }
+/* Record the target and release for the next run, built or reused. */
+if (process.platform === "darwin") {
+  mkdirSync(ffmpegInstall, { recursive: true });
+  writeFileSync(deploymentStamp(), process.env.MACOSX_DEPLOYMENT_TARGET ?? "");
+}
+writeFileSync(releaseStamp(ffmpegInstall), `${FFMPEG_VERSION}\n`);
 
 /* -- 3. player object ------------------------------------------------------ */
 
@@ -482,7 +558,10 @@ mkdirSync(objDir, { recursive: true });
  * references every entry point, so each member is extracted on demand. */
 const playerSources = ["media.cpp", "decode_audio.cpp"];
 const playerObjects: string[] = [];
-const cxxFlags = ["-std=c++17", "-O2", "-Wall", "-Wextra", "-I", runtimeDir, "-I", join(ffmpegInstall, "include")];
+const cxxFlags = cxxCompileFlags(toolchain.sdkRoot, [
+  "-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");

package/scripts/build-runtime.ts

@@ -26,8 +26,9 @@ import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { RUNTIME_SOURCES } from "../src/driver/compiler.js";
 import { platformSlug } from "../src/driver/paths.js";
+import { applyMacosDeploymentTarget } from "../src/driver/platform-support.js";
 import { resolveToolchain } from "../src/driver/toolchain-provider.js";
-import { RUNTIME_CFLAGS } from "../src/driver/toolchain.js";
+import { RUNTIME_CFLAGS, sysrootFlags } from "../src/driver/toolchain.js";
 import { nodeExtension } from "../src/extensions/node/index.js";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -37,6 +38,10 @@ const objDir = join(root, "build", "runtime-obj");
 const isWindows = process.platform === "win32";
 const archiveSuffix = isWindows ? ".lib" : ".a";
 
+/* Every archive targets the oldest supported macOS, not the build machine's
+ * version: a newer Xcode must not raise the deployment target of the objects. */
+applyMacosDeploymentTarget();
+
 // Use the same toolchain the driver will.
 const toolchain = resolveToolchain();
 const clang = toolchain.clang;
@@ -78,7 +83,7 @@ function compile(sources: readonly string[], extension: string): string[] {
     const object = join(objDir, `${extension}_${index}_${basename(source, ".c")}.o`);
     const result = spawnSync(
       clang,
-      [...RUNTIME_CFLAGS, "-c", source, "-o", object, `-I${runtimeDir}`],
+      [...RUNTIME_CFLAGS, ...sysrootFlags(toolchain.sdkRoot), "-c", source, "-o", object, `-I${runtimeDir}`],
       { stdio: "inherit", env: childEnv },
     );
     if (result.status !== 0) {

package/scripts/fetch-tarball.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Fetch a pinned release tarball for the vendored toolchain.
+ *
+ * `scripts/build-media.ts` (FFmpeg) and `scripts/build-gui.ts` (SDL3, FreeType,
+ * HarfBuzz, glslang, SPIRV-Cross) build from release tarballs downloaded at
+ * build time. A single `curl` is not reliable enough for that: hosted CI
+ * runners and some networks intermittently fail the TLS handshake with the
+ * release hosts — `curl: (35) SSL connect error` — and the next attempt
+ * usually succeeds. CI also caches the tarball by version, so with a retry here
+ * the download happens at most once per release rather than once per run.
+ *
+ * The bytes are written to `<destination>.part` and renamed only after curl
+ * reports success: an interrupted transfer can then never be mistaken for a
+ * complete tarball, neither by this run nor by a later one that restores the
+ * directory from `actions/cache`.
+ */
+
+import { spawnSync } from "node:child_process";
+import { renameSync, rmSync } from "node:fs";
+
+/** curl exit codes of transfers that may succeed when repeated: name
+ * resolution (6), connect timeout (28), TLS handshake (35), empty reply (52),
+ * send failure (55) and connection reset (56). Everything else — a 404, a
+ * permission error — is reported immediately. */
+const TRANSIENT_STATUSES = new Set([6, 28, 35, 52, 55, 56]);
+
+export interface DownloadOptions {
+  /** Total attempts, including the first. */
+  attempts?: number;
+  /** Base backoff in milliseconds; attempt n waits `retryDelayMs * n`. */
+  retryDelayMs?: number;
+}
+
+/** Block the single-threaded build long enough for a fresh TLS handshake. */
+function pause(ms: number): void {
+  if (ms <= 0) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Download `url` to `destination`, retrying the transient failures above.
+ * Throws when the transfer still fails, leaving no `.part` file behind.
+ */
+export function downloadTarball(
+  destination: string,
+  url: string,
+  label: string,
+  options: DownloadOptions = {},
+): void {
+  const attempts = options.attempts ?? 6;
+  const retryDelayMs = options.retryDelayMs ?? 3_000;
+  const partial = `${destination}.part`;
+  rmSync(partial, { force: true });
+  for (let attempt = 1; ; attempt += 1) {
+    const note = attempt === 1 ? "" : ` (attempt ${attempt}/${attempts})`;
+    console.log(`xbintsc: fetching ${label} from ${url}${note}`);
+    const { status } = spawnSync("curl", ["-sL", "--fail", "--connect-timeout", "30", "-o", partial, url], {
+      stdio: ["ignore", "inherit", "inherit"],
+    });
+    if (status === 0) {
+      renameSync(partial, destination);
+      return;
+    }
+    if (status === null || !TRANSIENT_STATUSES.has(status) || attempt >= attempts) {
+      rmSync(partial, { force: true });
+      throw new Error(`${label}: curl ${url} failed with status ${status ?? "?"}`);
+    }
+    pause(retryDelayMs * attempt);
+  }
+}

package/scripts/gui-build-cache.ts

@@ -0,0 +1,28 @@
+/**
+ * Cache invalidation for the vendored GUI build trees.
+ *
+ * `build-gui.ts` reuses `vendor/*-build-lean` when the archive it produced is
+ * already there, which is what makes a second `npm run gui` fast. CMake records
+ * the compiler in its cache, but the macOS deployment target is only a cache
+ * entry: a tree configured by an earlier checkout (or before the baseline was
+ * pinned) keeps its old objects inside an archive that is supposed to target
+ * the oldest supported macOS. This drops such a tree once, so the next
+ * configure builds it for the current target.
+ */
+
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+/** Remove `buildDir` when its CMake cache targets a different macOS version. */
+export function ensureDeploymentTarget(name: string, buildDir: string): void {
+  if (process.platform !== "darwin") return;
+  const cache = join(buildDir, "CMakeCache.txt");
+  if (!existsSync(cache)) return;
+  const configured = /^CMAKE_OSX_DEPLOYMENT_TARGET:STRING=(.*)$/m.exec(readFileSync(cache, "utf8"))?.[1]?.trim();
+  const wanted = process.env.MACOSX_DEPLOYMENT_TARGET ?? "";
+  if ((configured ?? "") === wanted) return;
+  console.log(
+    `xbintsc: ${name} was built for macOS '${configured ?? ""}'; rebuilding for '${wanted}'`,
+  );
+  rmSync(buildDir, { recursive: true, force: true });
+}

package/scripts/gui-build-options.ts

@@ -1,11 +1,14 @@
 /**
- * Size options shared by the GUI archive build.
+ * Build options shared by the GUI and media archive builds.
  *
  * Kept apart from `build-gui.ts` so the orchestration stays under the
  * repository's per-file line budget and the "what do we compile out?" policy is
  * reviewable in one place.
  */
 
+import { MACOS_MINIMUM_VERSION } from "../src/driver/platform-support.js";
+import { sysrootFlags } from "../src/driver/toolchain.js";
+
 /**
  * CMake generator and ABI settings used for every vendored library. Ninja is
  * selected on Windows because the Visual Studio generator imports the
@@ -22,6 +25,10 @@
  * `cmake_minimum_required` below 3.15, which defaults the policy to OLD and
  * silently ignores it — hence `CMAKE_POLICY_DEFAULT_CMP0091`.
  *
+ * On macOS every vendored library targets the oldest supported deployment
+ * target (`MACOSX_DEPLOYMENT_TARGET`, default 11.0), so a newer SDK on the
+ * build machine cannot raise the floor of the archive.
+ *
  * The tool paths are absolute and come from the same clang the driver resolves
  * (on Windows, the LLVM bundled with Visual Studio when no newer one is on
  * `PATH`), so every object merged into the archive shares one ABI and one
@@ -38,7 +45,11 @@ export function cmakeToolchainArgs(toolchain: {
     `-DCMAKE_C_COMPILER=${toolchain.clang}`,
     `-DCMAKE_CXX_COMPILER=${toolchain.clangxx}`,
   ];
-  if (!toolchain.isWindows) return compilers;
+  const macos =
+    process.platform === "darwin"
+      ? [`-DCMAKE_OSX_DEPLOYMENT_TARGET=${process.env.CMAKE_OSX_DEPLOYMENT_TARGET ?? MACOS_MINIMUM_VERSION}`]
+      : [];
+  if (!toolchain.isWindows) return [...compilers, ...macos];
   return [
     "-G", "Ninja",
     "-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded",
@@ -52,6 +63,19 @@ export function cmakeToolchainArgs(toolchain: {
  * never references (`--gc-sections`, `-dead_strip`, link.exe `/OPT:REF`). */
 export const SECTION_FLAGS = ["-ffunction-sections", "-fdata-sections"] as const;
 
+/**
+ * Flags for the C++ translation units merged into the GUI and media archives.
+ *
+ * `sdkRoot` must be passed as `-isysroot`: an Apple clang invoked by absolute
+ * path never infers its sysroot, and macOS keeps every standard header —
+ * libc++'s `<string>` included — inside the SDK rather than in `/usr/include`
+ * or the toolchain. Without it the first translation unit fails with
+ * `'string' file not found`.
+ */
+export function cxxCompileFlags(sdkRoot: string | undefined, includeFlags: readonly string[]): string[] {
+  return ["-std=c++17", "-O2", "-Wall", "-Wextra", ...SECTION_FLAGS, ...sysrootFlags(sdkRoot), ...includeFlags];
+}
+
 /** The same flags as CMake cache entries. */
 export const SECTION_CMAKE_FLAGS = [
   `-DCMAKE_C_FLAGS=${SECTION_FLAGS.join(" ")}`,

package/scripts/package-release.ts

@@ -101,6 +101,10 @@ if (process.platform !== "win32") chmodSync(stagedBinary, 0o755);
 console.log(`xbintsc: packaged binary ${basename(binary)} (${statSync(binary).size} bytes)`);
 
 // 2. The C runtime (sources fallback + prebuilt archives) next to the binary.
+// The copy is bracketed with its own messages so a stalled packaging step can be
+// attributed: this tree carries the freshly built gui/media archives, and a copy
+// blocked on one of them looks exactly like a hang in the `tar` call below.
+console.log("xbintsc: copying runtime/ into the staging tree");
 cpSync(findRuntimeDir(), join(stage, "runtime"), { recursive: true });
 console.log("xbintsc: packaged runtime/");
 
@@ -116,6 +120,10 @@ const extension = releaseArchiveExtension(hasZstd);
 const archive = join(releaseRoot, `${archiveBase}${extension}`);
 rmSync(archive, { force: true });
 const tarArgs = ["-c", hasZstd ? "--zstd" : "-z", "-f", archive, "-C", stageRoot, base];
+// Log the exact command before running it: `tar` prints nothing on success, so
+// this line is what tells a stuck step apart from a stuck filesystem copy above,
+// and it records which compression filter this runner chose (`--zstd` vs `-z`).
+console.log(`xbintsc: running tar ${tarArgs.join(" ")}`);
 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}`);

package/src/cli/hints.ts

@@ -36,10 +36,27 @@ const REQUIREMENT_HINT: DocumentationPointer = {
   path: DOC_REQUIREMENTS,
 };
 
-/** Hint for a clang failure: a missing or too-old clang has a specific answer. */
-export function toolchainPointer(message: string): DocumentationPointer {
+/**
+ * Hint for a clang failure: a missing or too-old clang has a specific answer.
+ *
+ * `platform` is a parameter so the macOS branch can be tested from any host.
+ */
+export function toolchainPointer(
+  message: string,
+  platform: NodeJS.Platform = process.platform,
+): DocumentationPointer {
   const usesTypedPointers = /defined with type '\[.*i8\]\*' but expected 'i8\*'/.test(message);
   if (usesTypedPointers || /No C compiler found/i.test(message)) return REQUIREMENT_HINT;
+  /* On macOS a C standard header lives in the SDK, so "'<header>' file not
+   * found" means the driver never got a sysroot — the header itself is fine.
+   * The driver resolves the SDK with `xcrun` and passes `-isysroot`, which
+   * makes the selected Xcode the thing to check. */
+  if (platform === "darwin" && /fatal error: '.+' file not found/.test(message)) {
+    return {
+      text: "clang cannot see the macOS SDK headers; `xcrun --show-sdk-path` must resolve for the selected Xcode, or set SDKROOT yourself",
+      path: DOC_TROUBLESHOOTING,
+    };
+  }
   return {
     text: "read the clang output above, then the toolchain section of the troubleshooting guide",
     path: DOC_TROUBLESHOOTING,

package/src/cli/main.ts

@@ -20,9 +20,11 @@ import { formatDiagnostic, type Diagnostic } from "../diagnostics/diagnostic.js"
 import { SourceFile } from "../diagnostics/source.js";
 import { build, compileEntry, COMPILER_VERSION, type EmitKind, type PhaseTiming } from "../driver/compiler.js";
 import { findRuntimeDir, platformSlug } from "../driver/paths.js";
+import { supportFloor } from "../driver/platform-support.js";
 import { findRuntimeLibrary, runtimeLibDir } from "../driver/runtime-lib.js";
 import { resolveToolchain, type ResolvedToolchain } from "../driver/toolchain-provider.js";
 import { MINIMUM_CLANG_MAJOR, probeClang, realRunner, ToolchainError } from "../driver/toolchain.js";
+import { macosSdkRoot } from "../driver/macos-sdk.js";
 import {
   DOC_CLI,
   DOC_TROUBLESHOOTING,
@@ -277,6 +279,15 @@ function doctor(io: CliIo): number {
     io.stdout("runtime lib: unavailable\n");
   }
 
+  io.stdout(`support    : ${supportFloor()} (release artifacts target this floor)\n`);
+
+  if (process.platform === "darwin") {
+    /* macOS keeps the C headers in the SDK; without one, no header the runtime
+     * includes resolves. Report the sysroot the driver hands to clang. */
+    const sdk = toolchain?.sdkRoot ?? process.env.SDKROOT ?? macosSdkRoot(realRunner);
+    io.stdout(`sdk        : ${sdk ?? "unresolved (xcrun --show-sdk-path failed)"}\n`);
+  }
+
   try {
     if (!toolchain) throw new Error("no toolchain");
     const resource = resolveResourceCompiler(realRunner, toolchain.clang);

package/src/driver/app-artifacts.ts

@@ -22,6 +22,8 @@ export interface AppArtifactRequest {
   readonly app: AppConfig;
   readonly icon: IconInfo | undefined;
   readonly env: Record<string, string>;
+  /** macOS SDK for `-isysroot`; see `sysrootFlags`. */
+  readonly sdkRoot?: string;
   readonly verbose: boolean | undefined;
 }
 
@@ -46,11 +48,11 @@ export interface AppArtifacts {
  * no equivalent.
  */
 export function ensureAppArtifacts(request: AppArtifactRequest): AppArtifacts {
-  const { runner, clang, cacheDir, registry, app, icon, env, verbose } = request;
+  const { runner, clang, cacheDir, registry, app, icon, env, sdkRoot, verbose } = request;
   const windowsSubsystem = process.platform === "win32" && registry.has("gui") && app.console !== true;
   const linkerFlags = windowsSubsystem ? ["-Wl,/SUBSYSTEM:WINDOWS"] : [];
   const entryObject = windowsSubsystem
-    ? ensureWindowsEntryObject(runner, clang, cacheDir, env)
+    ? ensureWindowsEntryObject(runner, clang, cacheDir, env, sdkRoot)
     : undefined;
 
   const iconObjects: string[] = [];
@@ -58,7 +60,7 @@ export function ensureAppArtifacts(request: AppArtifactRequest): AppArtifacts {
   // program gets an (empty) icon object even with no icon configured.
   if (icon !== undefined || registry.has("gui")) {
     try {
-      iconObjects.push(ensureIconObject(runner, clang, cacheDir, icon ?? EMPTY_ICON, env));
+      iconObjects.push(ensureIconObject(runner, clang, cacheDir, icon ?? EMPTY_ICON, env, sdkRoot));
       if (icon && process.platform === "win32") {
         const resourceCompiler = resolveResourceCompiler(runner, clang);
         if (resourceCompiler) {