xbintsc 0.5.52 → 0.6.9

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) {

package/src/driver/compiler.ts

@@ -18,18 +18,20 @@ import { DiagnosticBag, DiagnosticCode } from "../diagnostics/diagnostic.js";
 import { generate } from "../codegen/llvm.js";
 import { createDefaultRegistry } from "../extensions/registry.js";
 import { BuildCache } from "./cache.js";
-import { findRuntimeDir } from "./paths.js";
-import { resolveToolchain } from "./toolchain-provider.js";
+import { findRuntimeDir, platformSlug } from "./paths.js";
+import { resolveToolchain, type ResolvedToolchain } from "./toolchain-provider.js";
 import { readIcon, IconError, type IconInfo } from "./icon.js";
 import { bundlePathFor, packageMacApp } from "./mac-bundle.js";
 import type { AppConfig } from "./config.js";
 import { compileIr, link, mergeProfileData, realRunner, ToolchainError } from "./toolchain.js";
 import { parseEntry } from "./frontend.js";
-import { ensureRuntimeObjects } from "./runtime-objects.js";
+import { ensureRuntimeObjects, type RuntimeObjects } from "./runtime-objects.js";
 import { ensureAppArtifacts } from "./app-artifacts.js";
 import { buildCacheKey } from "./build-key.js";
 import { collectUsage } from "./usage.js";
 import { resolveLinkFeatures, type ResolvedLinkFeature } from "./link-features.js";
+import { isPrebuiltArchivePath, firstFailureLine, looksLikePrebuiltLinkFailure } from "./prebuilt.js";
+import { runtimeLibDirs as defaultRuntimeLibDirs } from "./runtime-lib.js";
 import type { BuildOptions, BuildResult, EmitKind, PhaseTiming } from "./options.js";
 
 export { COMPILER_VERSION } from "./version.js";
@@ -68,6 +70,36 @@ function executableName(entry: string, outDir: string, explicit: string | undefi
   return resolve(outDir, base + suffix);
 }
 
+/**
+ * Explain a retry that still fails while prebuilt `gui`/`media` archives are in
+ * the link. Unlike `core`/`ext_node`, those bundle SDL3/FFmpeg/glslang and
+ * their sources are not part of the npm package, so the source fallback cannot
+ * replace them; only a release/toolchain match can.
+ */
+function prebuiltFallbackError(
+  error: unknown,
+  runtimeObjects: RuntimeObjects,
+  dirs: readonly string[] | undefined,
+): unknown {
+  if (!(error instanceof ToolchainError) || !looksLikePrebuiltLinkFailure(error.stderr)) return error;
+  const runtimeDirs = dirs ?? defaultRuntimeLibDirs();
+  const fixed = [...runtimeObjects.featureObjects, ...runtimeObjects.nativeObjects].filter((object) =>
+    isPrebuiltArchivePath(object, runtimeDirs),
+  );
+  if (fixed.length === 0) return error;
+  const archives = [...new Set(fixed.map((object) => basename(object)))].join(", ");
+  return new ToolchainError(
+    error.command,
+    error.status,
+    `${error.stderr}\n` +
+      `The remaining prebuilt archives (${archives}) come from the @xbintsc/${platformSlug()} ` +
+      "package. Unlike the C runtime, they bundle SDL3/FFmpeg, whose sources are not shipped " +
+      "in the npm package, so they cannot be rebuilt here.\n" +
+      "Build with the Xcode Command Line Tools / Visual Studio C++ toolset the release was built " +
+      "with, or use a release archive built for this machine.",
+  );
+}
+
 export function build(entryPath: string, options: BuildOptions = {}): BuildResult {
   const runner = options.runner ?? realRunner;
   const registry = options.extensions ?? createDefaultRegistry();
@@ -220,8 +252,8 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
 
   // -- toolchain -----------------------------------------------------------
   const clangStarted = Date.now();
-  const toolchain = options.clang
-    ? { clang: options.clang, linkerArgs: [] as string[], env: {} as Record<string, string> }
+  const toolchain: Pick<ResolvedToolchain, "clang" | "linkerArgs" | "env" | "sdkRoot"> = options.clang
+    ? { clang: options.clang, linkerArgs: [], env: {} }
     : resolveToolchain(runner);
   const clang = toolchain.clang;
   if (pgo === "use") {
@@ -244,6 +276,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     objectPath,
     optimize,
     env: toolchain.env,
+    sdkRoot: toolchain.sdkRoot,
     debug: options.debug === true,
     lto,
     ...(pgo ? { pgo, pgoDir } : {}),
@@ -256,21 +289,32 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     return { outputPath, irPath, cached: false, diagnostics: [], ir, timings };
   }
 
-  const runtimeStarted = Date.now();
-  const { runtimeObjects, extensionObjects, featureObjects, nativeObjects } = ensureRuntimeObjects({
-    runner,
-    clang,
-    runtimeDir,
-    cacheDir,
-    registry,
-    preferPrebuilt: resolvePreferPrebuilt(options.preferPrebuilt) && !lto && pgo === undefined,
-    env: toolchain.env,
-    lto,
-    pgo,
-    pgoDir,
-    features: linkFeatures,
-  });
-  timings.push({ phase: "runtime", ms: Date.now() - runtimeStarted });
+  /* The runtime is assembled before the app artifacts so a failed prebuilt
+   * link can be retried with the same artifact inputs. */
+  const runtimeLibDirs = options.runtimeLibDirs;
+  const preferPrebuilt = resolvePreferPrebuilt(options.preferPrebuilt) && !lto && pgo === undefined;
+  const assembleRuntime = (usePrebuilt: boolean): RuntimeObjects => {
+    const started = Date.now();
+    const assembled = ensureRuntimeObjects({
+      runner,
+      clang,
+      runtimeDir,
+      cacheDir,
+      registry,
+      preferPrebuilt: usePrebuilt,
+      env: toolchain.env,
+      sdkRoot: toolchain.sdkRoot,
+      lto,
+      pgo,
+      pgoDir,
+      features: linkFeatures,
+      ...(runtimeLibDirs !== undefined ? { runtimeLibDirs } : {}),
+    });
+    timings.push({ phase: "runtime", ms: Date.now() - started });
+    return assembled;
+  };
+
+  let assembled = assembleRuntime(preferPrebuilt);
 
   const artifacts = ensureAppArtifacts({
     runner,
@@ -280,6 +324,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     app,
     icon,
     env: toolchain.env,
+    sdkRoot: toolchain.sdkRoot,
     verbose: options.verbose,
   });
   if (artifacts.iconError !== undefined) {
@@ -287,42 +332,108 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     return { outputPath, irPath, cached: false, diagnostics: diagnostics.diagnostics, ir };
   }
 
-  const linkStarted = Date.now();
-  link(runner, {
-    clang,
-    objectPaths: [
-      objectPath,
-      /* Feature archives come after their bridges (which reference the
-       * implementation) and before the extensions' own archives (`gui.a`
-       * provides symbols the bridges call back into). `Set` keeps that order
-       * and drops an archive two features or an extension share. */
-      ...new Set([
-        ...runtimeObjects,
-        ...extensionObjects,
-        ...featureObjects,
-        ...nativeObjects,
-        ...(artifacts.entryObject !== undefined ? [artifacts.entryObject] : []),
-        ...artifacts.iconObjects,
-      ]),
-    ],
-    outputPath,
-    linkerFlags: [
-      ...toolchain.linkerArgs,
-      ...(process.platform === "win32" ? ["-lws2_32"] : ["-lm", "-pthread"]),
-      ...registry.linkerFlags(),
-      ...linkFeatures.flatMap((feature) => feature.linkerFlags),
-      /* A GUI program is a Windows-subsystem executable: no console window is
-       * created when it is launched. Console output (stdout/stderr) is lost in
-       * that subsystem, so a program that wants to report things opts back in
-       * with `app.console: true`. */
-      ...artifacts.linkerFlags,
-    ],
-    optimize,
-    env: toolchain.env,
-    lto,
-    ...(pgo ? { pgo, pgoDir } : {}),
-  });
-  timings.push({ phase: "link", ms: Date.now() - linkStarted });
+  const linkAssembled = (runtimeObjects: RuntimeObjects): string => {
+    const started = Date.now();
+    const result = link(runner, {
+      clang,
+      objectPaths: [
+        objectPath,
+        /* Feature archives come after their bridges (which reference the
+         * implementation) and before the extensions' own archives (`gui.a`
+         * provides symbols the bridges call back into). `Set` keeps that order
+         * and drops an archive two features or an extension share. */
+        ...new Set([
+          ...runtimeObjects.runtimeObjects,
+          ...runtimeObjects.extensionObjects,
+          ...runtimeObjects.featureObjects,
+          ...runtimeObjects.nativeObjects,
+          ...(artifacts.entryObject !== undefined ? [artifacts.entryObject] : []),
+          ...artifacts.iconObjects,
+        ]),
+      ],
+      outputPath,
+      linkerFlags: [
+        ...toolchain.linkerArgs,
+        ...(process.platform === "win32" ? ["-lws2_32"] : ["-lm", "-pthread"]),
+        ...registry.linkerFlags(),
+        ...linkFeatures.flatMap((feature) => feature.linkerFlags),
+        /* A GUI program is a Windows-subsystem executable: no console window is
+         * created when it is launched. Console output (stdout/stderr) is lost in
+         * that subsystem, so a program that wants to report things opts back in
+         * with `app.console: true`. */
+        ...artifacts.linkerFlags,
+      ],
+      optimize,
+      env: toolchain.env,
+      sdkRoot: toolchain.sdkRoot,
+      lto,
+      ...(pgo ? { pgo, pgoDir } : {}),
+    });
+    timings.push({ phase: "link", ms: Date.now() - started });
+    return result.stderr;
+  };
+
+  /**
+   * Retry once with the C runtime compiled from the sources shipped in the
+   * package. The failed attempt is not cached: a later toolchain upgrade can
+   * use the archive again.
+   */
+  const retryFromSource = (stderr: string): void => {
+    const reason = firstFailureLine(stderr);
+    process.stderr.write(
+      "xbintsc: the prebuilt runtime archive does not match this toolchain" +
+        (reason ? ` (${reason})` : "") +
+        "; compiling the C runtime from source\n",
+    );
+    assembled = assembleRuntime(false);
+    try {
+      linkAssembled(assembled);
+    } catch (retryError) {
+      throw prebuiltFallbackError(retryError, assembled, runtimeLibDirs);
+    }
+  };
+  const prebuiltInUse = (): boolean =>
+    preferPrebuilt && assembled.prebuiltArchives.length > 0;
+  /** Whether the linker talked about an archive the source fallback can replace. */
+  const mentionsRebuildableArchive = (stderr: string): boolean =>
+    assembled.prebuiltArchives.some((archive) => stderr.includes(basename(archive)));
+
+  /* One attempt, captured instead of thrown so the retry below is not itself
+   * caught by this decision block. `failed` is explicit because a thrown
+   * `undefined` must not look like a successful link. */
+  let failed = false;
+  let firstError: unknown;
+  let firstStderr = "";
+  try {
+    firstStderr = linkAssembled(assembled);
+  } catch (error) {
+    failed = true;
+    firstError = error;
+  }
+
+  if (failed) {
+    const error = firstError;
+    /* The release runner's Xcode/SDK or Visual Studio toolset can be newer
+     * than this machine's, and then the prebuilt archive cannot be linked
+     * (`LNK2038`, `LNK2019`, `Undefined symbols`, ...). The C runtime sources
+     * ship with the package, so retry once with them instead of failing on a
+     * linker message the user cannot act on. */
+    if (!prebuiltInUse() || !(error instanceof ToolchainError) || !looksLikePrebuiltLinkFailure(error.stderr)) {
+      throw error;
+    }
+    retryFromSource(error.stderr);
+  } else if (
+    prebuiltInUse() &&
+    mentionsRebuildableArchive(firstStderr) &&
+    looksLikePrebuiltLinkFailure(firstStderr)
+  ) {
+    /* A successful link can still warn that the archive was built for a newer
+     * macOS than the one being targeted: the binary would then claim the local
+     * deployment target while calling newer SDK symbols at run time, so rebuild
+     * it from source just like an outright failure. Only `core`/`ext_node` can
+     * be replaced this way; a warning about `gui.a`/`media.a` is left alone. */
+    retryFromSource(firstStderr);
+  }
 
   const bundlePath =
     bundle !== undefined

package/src/driver/icon.ts

@@ -16,7 +16,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { hashParts } from "./cache.js";
-import { compileC, type Runner } from "./toolchain.js";
+import { compileC, sysrootFlags, type Runner } from "./toolchain.js";
 
 export type IconFormat = "png" | "ico" | "icns";
 
@@ -144,6 +144,7 @@ export function ensureIconObject(
   cacheDir: string,
   icon: IconInfo,
   env?: Record<string, string>,
+  sdkRoot?: string,
 ): string {
   const key = hashParts(["icon", process.platform, Buffer.from(icon.bytes).toString("base64")]);
   const sourcePath = join(cacheDir, `icon-${key}.c`);
@@ -151,7 +152,7 @@ export function ensureIconObject(
   if (!existsSync(objectPath)) {
     mkdirSync(cacheDir, { recursive: true });
     writeFileSync(sourcePath, iconSource(icon));
-    compileC(runner, clang, sourcePath, objectPath, cacheDir, env);
+    compileC(runner, clang, sourcePath, objectPath, cacheDir, env, sysrootFlags(sdkRoot));
   }
   return objectPath;
 }

package/src/driver/macos-sdk.ts

@@ -0,0 +1,52 @@
+/**
+ * macOS SDK discovery.
+ *
+ * macOS has no `/usr/include`: every C standard header (`stdio.h`,
+ * `setjmp.h`, …) ships inside the SDK, and the linker's `libm`/`libSystem`
+ * stubs live there too. clang only searches the SDK when it has a sysroot,
+ * which comes from the `/usr/bin/clang` shim, an explicit `-isysroot`, or the
+ * `SDKROOT` environment variable.
+ *
+ * xbintsc invokes clang by absolute path (CI pins it to the oldest installed
+ * Xcode so released archives stay linkable by newer ones), which bypasses the
+ * shim. Without a sysroot that driver sees neither the SDK nor `/usr/include`,
+ * and the first runtime include fails with `'setjmp.h' file not found` — the
+ * header is irrelevant, any system header would do. The same gap makes the
+ * link fail later with `ld: library 'm' not found`.
+ *
+ * The SDK is therefore resolved once, with `xcrun`, and handed to clang as
+ * `-isysroot` on the command line rather than as `SDKROOT` in the environment:
+ * a self-hosted xbintsc binary runs the same driver, and its compiled
+ * `spawnSync` ignores `options.env`, so the variable would be lost exactly
+ * where the compiler rebuilds itself. An explicit `SDKROOT` in the environment
+ * always wins, so a developer can select an older SDK deliberately.
+ */
+
+import { existsSync } from "node:fs";
+import type { CommandResult, Runner } from "./toolchain.js";
+
+/**
+ * The macOS SDK `xcrun` reports, or `undefined` when the host is not macOS,
+ * the environment already names one, or no usable SDK can be resolved.
+ *
+ * A missing SDK is not an error here: the build still runs, and clang reports
+ * the real problem (or the driver never needed the SDK in the first place).
+ */
+export function macosSdkRoot(
+  runner: Runner,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): string | undefined {
+  if (platform !== "darwin") return undefined;
+  if (env.SDKROOT) return undefined;
+  let result: CommandResult;
+  try {
+    result = runner.run("xcrun", ["--show-sdk-path"]);
+  } catch {
+    /* A host without xcrun keeps the previous behaviour: let clang decide. */
+    return undefined;
+  }
+  if (result.status !== 0) return undefined;
+  const sdk = result.stdout.trim();
+  return sdk.length > 0 && existsSync(sdk) ? sdk : undefined;
+}

package/src/driver/options.ts

@@ -28,6 +28,12 @@ export interface BuildOptions {
   readonly clang?: string;
   /** Prefer a prebuilt `runtime/lib/<os>-<arch>/*.a` archive when present (default true). */
   readonly preferPrebuilt?: boolean;
+  /**
+   * Folders searched for the prebuilt `core`/`ext_<name>` archives, replacing
+   * the default (`runtime/lib/<os>-<arch>` plus the installed platform
+   * package). Mostly useful for tests and embedding tools.
+   */
+  readonly runtimeLibDirs?: readonly string[];
   readonly write?: boolean;
   /** Application icon embedded into the binary (shorthand for `app.icon`). */
   readonly icon?: string;

package/src/driver/platform-support.ts

@@ -0,0 +1,69 @@
+/**
+ * Oldest platform versions xbintsc supports, and the baseline every released
+ * artifact is built against.
+ *
+ * The prebuilt runtime archives (`core`, `ext_node`, `gui`, `media`) and the
+ * self-hosted compiler are built by CI with the **oldest toolchain each host
+ * still offers**, targeting the floors below. A newer Xcode/Visual Studio on a
+ * user's machine can link those older objects, but the reverse is what fails
+ * (`LNK2038`, `LNK2019`, `Undefined symbols`, `was built for newer macOS
+ * version`), which is why the direction matters.
+ *
+ * These values are the single source of truth for the archive build scripts,
+ * `xbintsc doctor` and `doc/requirements.md`.
+ */
+
+/** Deployment target for every macOS artifact (also the Apple Silicon floor). */
+export const MACOS_MINIMUM_VERSION = "11.0";
+
+/**
+ * Oldest Windows version the prebuilt objects and the compiler target.
+ *
+ * Windows 10 was the floor while the release jobs ran on `windows-2022`
+ * (VS 2022 / MSVC v143). Those images cannot assemble a release: their bundled
+ * `tar` has no built-in zstd, so `tar --zstd` hands compression to an external
+ * program the step waits on forever. The release jobs therefore run on
+ * `windows-2025`, whose toolset targets Windows 11, and the supported floor
+ * moved with them.
+ */
+export const WINDOWS_MINIMUM_VERSION = "11";
+
+/**
+ * glibc the release archives are built and tested against: the GitHub
+ * `ubuntu-24.04` image. Older distributions may link the npm package's
+ * archives, but only this floor is supported.
+ */
+export const LINUX_MINIMUM_GLIBC = "2.39";
+
+/** Human-readable support floor for the host running the compiler. */
+export function supportFloor(platform: NodeJS.Platform = process.platform): string {
+  switch (platform) {
+    case "darwin":
+      return `macOS ${MACOS_MINIMUM_VERSION}+`;
+    case "win32":
+      return `Windows ${WINDOWS_MINIMUM_VERSION}+`;
+    case "linux":
+      return `glibc ${LINUX_MINIMUM_GLIBC}+`;
+    default:
+      return `${platform} (unverified)`;
+  }
+}
+
+/**
+ * Make a macOS archive build target {@link MACOS_MINIMUM_VERSION}.
+ *
+ * Clang's Darwin driver reads `MACOSX_DEPLOYMENT_TARGET`, and CMake reads it as
+ * the default for `CMAKE_OSX_DEPLOYMENT_TARGET`; setting both keeps the direct
+ * engine compiles, the vendored CMake builds and FFmpeg's configure on the same
+ * floor. An explicit value in the environment still wins, so a developer can
+ * target an even older macOS deliberately. No-op on the other hosts.
+ */
+export function applyMacosDeploymentTarget(platform: NodeJS.Platform = process.platform): void {
+  if (platform !== "darwin") return;
+  if (!process.env.MACOSX_DEPLOYMENT_TARGET) {
+    process.env.MACOSX_DEPLOYMENT_TARGET = MACOS_MINIMUM_VERSION;
+  }
+  if (!process.env.CMAKE_OSX_DEPLOYMENT_TARGET) {
+    process.env.CMAKE_OSX_DEPLOYMENT_TARGET = MACOS_MINIMUM_VERSION;
+  }
+}

package/src/driver/prebuilt.ts

@@ -0,0 +1,61 @@
+/**
+ * Detecting a prebuilt runtime archive that this machine's toolchain cannot
+ * link.
+ *
+ * The optional `@xbintsc/<os>-<arch>` package carries archives compiled on the
+ * release runner (`core.a`, `ext_node.a`, `gui.a`, `media.a`). Its Xcode
+ * Command Line Tools or Visual Studio C++ toolset can be **newer** than the
+ * one on the machine that runs the build: a linker can then reject the archive
+ * with unresolved symbols (`LNK2038`/`LNK2019`, `Undefined symbols`,
+ * `undefined reference`) or `was built for newer macOS version`.
+ *
+ * The driver answers that with one automatic retry that compiles the runtime
+ * from the sources shipped in the npm package. Its decision is based on the
+ * linker's own output rather than a version comparison, because an archive does
+ * not record the toolset that produced it portably: Mach-O objects carry
+ * `LC_BUILD_VERSION`, COFF objects do not carry an MSVC toolset version.
+ *
+ * `gui.a`/`media.a` are exempt: they bundle SDL3/FFmpeg/glslang, whose sources
+ * are not part of the npm package, so they cannot be rebuilt from it.
+ */
+
+import { dirname, resolve } from "node:path";
+
+const ARCHIVE_SUFFIXES = [".a", ".lib"] as const;
+
+/** True when `candidate` is a static archive that sits in one of `dirs`. */
+export function isPrebuiltArchivePath(candidate: string, dirs: readonly string[]): boolean {
+  if (!ARCHIVE_SUFFIXES.some((suffix) => candidate.endsWith(suffix))) return false;
+  const parent = dirname(resolve(candidate));
+  return dirs.some((dir) => resolve(dir) === parent);
+}
+
+/**
+ * Linker messages that mean "these objects were produced by a different
+ * toolchain/SDK". Kept deliberately narrow: a missing file, a bad flag or a
+ * permission error must not trigger the (slow) source rebuild.
+ */
+const MISMATCH_PATTERNS = [
+  /LNK2038/i, // mismatch detected for 'RuntimeLibrary'/'_MSC_VER'
+  /LNK20(?:01|19)/i, // unresolved external symbol
+  /undefined symbols?/i, // ld64
+  /undefined reference/i, // GNU/LLD
+  /symbol\(s\) not found/i, // ld64 summary line
+  /was built for newer (?:macOS|iOS|tvOS|watchOS|visionOS)/i, // ld64 warning
+  /but linking in object file built for/i, // ld64 deployment-target error
+  /has an incompatible (?:architecture|platform)/i,
+] as const;
+
+/** Whether a failed link's stderr looks like a toolchain/archive mismatch. */
+export function looksLikePrebuiltLinkFailure(stderr: string): boolean {
+  return MISMATCH_PATTERNS.some((pattern) => pattern.test(stderr));
+}
+
+/** First non-empty line of a command's stderr, for a one-line build notice. */
+export function firstFailureLine(stderr: string): string {
+  for (const line of stderr.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.length > 0) return trimmed.length > 160 ? `${trimmed.slice(0, 157)}...` : trimmed;
+  }
+  return "";
+}