Crafter.Build/implementations/Crafter.Build-Clang.cpp

// SPDX-License-Identifier: LGPL-3.0-only
// SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®

module;
#include <sys/socket.h>
#include <netinet/in.h>
#include <unistd.h>
export module Crafter.Build:Clang_impl;
import std;
import :Clang;
import :Platform;
import :Toolchain;
import :Test;
import :Lint;
import :Script;
import :Agents;
import :Progress;
import :Asset;
namespace fs = std::filesystem;
using namespace Crafter;


namespace {
    // Map one `import X;` name onto either a module this Configuration owns or
    // one exported by a Configuration reachable through its dependency DAG,
    // appending the matching staleness edge. False means nothing in reach
    // provides X — either it's supplied from outside the graph (`std`) or the
    // dependency isn't wired up *yet*, which is why callers remember the name.
    bool ResolveImportName(Configuration& cfg, const std::string& importName, std::vector<Module*>& localDeps, std::vector<std::pair<Module*, fs::path>>& externalDeps) {
        for(const std::unique_ptr<Module>& interface : cfg.interfaces) {
            if(interface->name == importName) {
                localDeps.push_back(interface.get());
                return true;
            }
        }

        std::unordered_set<Configuration*> seen;
        std::function<bool(Configuration*)> walk = [&](Configuration* depCfg) -> bool {
            if (!seen.insert(depCfg).second) return false;
            for(const std::unique_ptr<Module>& depInterface : depCfg->interfaces) {
                if(depInterface->name == importName) {
                    fs::path depPcmPath = std::format("{}.pcm", (depCfg->PcmDir() / depInterface->path.filename()).string());
                    externalDeps.emplace_back(depInterface.get(), std::move(depPcmPath));
                    return true;
                }
            }
            for(Configuration* sub : depCfg->dependencies) {
                if (walk(sub)) return true;
            }
            return false;
        };

        for(Configuration* depCfg : cfg.dependencies) {
            if (walk(depCfg)) return true;
        }
        return false;
    }
}

void Configuration::ResolvePendingImports() {
    // Same resolution the scan used, and against both dependency kinds — a
    // second GetInterfacesAndImplementations call can add interfaces that an
    // earlier batch's import was looking for, so a pending name may land on a
    // local module and not just an external one.
    auto sweep = [this](std::vector<std::string>& pending, std::vector<Module*>& localDeps, std::vector<std::pair<Module*, fs::path>>& externalDeps) {
        std::erase_if(pending, [&](const std::string& name) {
            return ResolveImportName(*this, name, localDeps, externalDeps);
        });
    };
    for(const std::unique_ptr<Module>& interface : interfaces) {
        sweep(interface->pendingImports, interface->moduleDependencies, interface->externalModuleDependencies);
        for(const std::unique_ptr<ModulePartition>& partition : interface->partitions) {
            sweep(partition->pendingImports, partition->moduleDependencies, partition->externalModuleDependencies);
        }
    }
    for(Implementation& implementation : implementations) {
        sweep(implementation.pendingImports, implementation.moduleDependencies, implementation.externalModuleDependencies);
    }
}

void Configuration::GetInterfacesAndImplementations(std::span<fs::path> interfaces, std::span<fs::path> implementations) {
    auto resolveImport = [this](const std::string& importName, std::vector<Module*>& localDeps, std::vector<std::pair<Module*, fs::path>>& externalDeps, std::vector<std::string>& pending) {
        if (!ResolveImportName(*this, importName, localDeps, externalDeps)) {
            pending.push_back(importName);
        }
    };

    std::vector<std::tuple<fs::path, std::string, ModulePartition*, Module*>> tempModulePaths = std::vector<std::tuple<fs::path, std::string, ModulePartition*, Module*>>(interfaces.size());
    for(std::uint16_t i = 0; i < interfaces.size(); i++){
        // Resolve to absolute now so the stored path survives cwd changes
        // (matters for GitProject deps loaded from a different working dir).
        fs::path file = fs::absolute(path / interfaces[i]).lexically_normal();
        file += ".cppm";
        std::ifstream t(file);
        std::stringstream buffer;
        buffer << t.rdbuf();
        std::string fileContent = buffer.str();
        fileContent = std::regex_replace(fileContent, std::regex(R"(//[^\n]*)"), "");
        fileContent = std::regex_replace(fileContent, std::regex(R"(/\*.*?\*/)"), "");
        tempModulePaths[i] = {file, fileContent, nullptr, nullptr};
    }

    // Primary interface units first, so the partition pass below can find their
    // parent Module. They stay in tempModulePaths — a primary unit's own
    // `import X;` lines are layout dependencies exactly like a partition's, and
    // dropping the entry here is what left them unrecorded (issue #26). Marked
    // by a null partition slot with the Module slot filled in.
    for(std::tuple<fs::path, std::string, ModulePartition*, Module*>& file : tempModulePaths) {
        std::smatch match;
        if (std::regex_search(std::get<1>(file), match, std::regex(R"(export module ([a-zA-Z0-9_\.\-]+);)"))) {
            fs::path pthCpy = std::get<0>(file);
            pthCpy.replace_extension("");
            this->interfaces.push_back(std::make_unique<Module>(std::move(match[1].str()), std::move(pthCpy)));
            std::get<3>(file) = this->interfaces.back().get();
        }
    }

        for(std::uint16_t i = 0; i < tempModulePaths.size(); i++) {
        std::smatch match;
        if (std::get<3>(tempModulePaths[i]) != nullptr) {
            continue;
        }
        if (std::regex_search(std::get<1>(tempModulePaths[i]), match, std::regex(R"(export module ([a-zA-Z_0-9\.\-]+):([a-zA-Z_0-9\.\-]+);)"))) {
            for(const std::unique_ptr<Module>& modulee : this->interfaces) {
                if(modulee->name == match[1]) {
                    std::string name = match[2].str();
                    fs::path pthCpy = std::get<0>(tempModulePaths[i]);
                    pthCpy.replace_extension("");
                    std::unique_ptr<ModulePartition> partition = std::make_unique<ModulePartition>(std::move(name), std::move(pthCpy));
                    std::get<2>(tempModulePaths[i]) = partition.get();
                    modulee->partitions.push_back(std::move(partition));
                    std::get<3>(tempModulePaths[i]) = modulee.get();
                    goto next;
                }
            }
            throw std::runtime_error(std::format("Module {} not found, referenced in {}", match[1].str(), std::get<0>(tempModulePaths[i]).string()));
        } else {
            throw std::runtime_error(std::format("No module declaration found in {}", std::get<0>(tempModulePaths[i]).string()));
        }
        next:;
    }

    for(std::tuple<fs::path, std::string, ModulePartition*, Module*>& file : tempModulePaths) {
        ModulePartition* partition = std::get<2>(file);
        Module* parentModule = std::get<3>(file);
        const std::string& fileContent = std::get<1>(file);

        // Primary interface unit: record only its module imports. Its
        // `[export] import :Part;` lines need no edge — Module::Check walks
        // every partition it owns and Module::Compile builds them all before
        // precompiling itself, so partitions are covered wholesale.
        if (partition == nullptr) {
            std::regex primaryPattern(R"(import ([a-zA-Z_0-9\.\-]+);)");
            std::sregex_iterator primaryCurrent(fileContent.begin(), fileContent.end(), primaryPattern);
            std::sregex_iterator primaryLast;
            while (primaryCurrent != primaryLast) {
                std::smatch match = *primaryCurrent;
                resolveImport(match[1].str(), parentModule->moduleDependencies, parentModule->externalModuleDependencies, parentModule->pendingImports);
                ++primaryCurrent;
            }
            continue;
        }

        std::regex partitionPattern(R"(import :([a-zA-Z_\-0-9\.]+);)");
        std::sregex_iterator currentMatch(fileContent.begin(), fileContent.end(), partitionPattern);
        std::sregex_iterator lastMatch;
        while (currentMatch != lastMatch) {
            std::smatch match = *currentMatch;
            for(std::unique_ptr<ModulePartition>& sibling : parentModule->partitions) {
                if(sibling->name == match[1]) {
                    partition->partitionDependencies.push_back(sibling.get());
                    goto next2;
                }
            }
            throw std::runtime_error(std::format("imported partition {}:{} not found, referenced in {}", parentModule->name, match[1].str(), std::get<0>(file).string()));
            next2: ++currentMatch;
        }

        std::regex modulePattern(R"(import ([a-zA-Z_0-9\.\-]+);)");
        std::sregex_iterator modCurrent(fileContent.begin(), fileContent.end(), modulePattern);
        while (modCurrent != lastMatch) {
            std::smatch match = *modCurrent;
            resolveImport(match[1].str(), partition->moduleDependencies, partition->externalModuleDependencies, partition->pendingImports);
            ++modCurrent;
        }
    }

    for(const fs::path& tempFile : implementations) {
        fs::path file = fs::absolute(path / tempFile).lexically_normal();
        file += ".cpp";
        std::ifstream t(file);
        std::stringstream buffer;
        buffer << t.rdbuf();
        std::string fileContent = buffer.str();
        fileContent = std::regex_replace(fileContent, std::regex(R"(//[^\n]*)"), "");
        fileContent = std::regex_replace(fileContent, std::regex(R"(/\*.*?\*/)"), "");
        std::smatch match;
        fs::path fileCopy = file;
        fileCopy.replace_extension("");
        Implementation& implementation = this->implementations.emplace_back(std::move(fileCopy));
        if (std::regex_search(fileContent, match, std::regex(R"(module ([a-zA-Z0-9_\.\-]+)(:[a-zA-Z0-9_\.\-]+)?\s*;)"))) {
            const bool isPartitionImpl = match[2].length() > 0;
            for(const std::unique_ptr<Module>& interface : this->interfaces) {
                if(interface->name == match[1]) {
                    if (!isPartitionImpl) {
                        implementation.moduleDependencies.push_back(interface.get());
                    }
                    std::regex partitionPattern(R"(import :([a-zA-Z_\-0-9\.]+);)");
                    std::sregex_iterator currentMatch(fileContent.begin(), fileContent.end(), partitionPattern);
                    std::sregex_iterator lastMatch;
                    while (currentMatch != lastMatch) {
                        std::smatch match2 = *currentMatch;
                        for(const std::unique_ptr<ModulePartition>& partition : interface->partitions) {
                            if(partition->name == match2[1]) {
                                implementation.partitionDependencies.push_back(partition.get());
                                goto next3;
                            }
                        }
                        throw std::runtime_error(std::format("imported partition {}:{} not found, referenced in {}", match[1].str(), match2[1].str(), file.string()));
                        next3: ++currentMatch;
                    }

                    std::regex modulePattern(R"(import ([a-zA-Z_0-9\.\-]+);)");
                    std::sregex_iterator modCurrent(fileContent.begin(), fileContent.end(), modulePattern);
                    while (modCurrent != lastMatch) {
                        std::smatch match2 = *modCurrent;
                        if (match2[1] != match[1]) {
                            resolveImport(match2[1].str(), implementation.moduleDependencies, implementation.externalModuleDependencies, implementation.pendingImports);
                        }
                        ++modCurrent;
                    }
                    goto next4;
                }
            }
            throw std::runtime_error(std::format("Module {} not found not found, referenced in {}", match[1].str(), file.string()));
            next4:;
        } else {
            std::regex pattern(R"(import ([a-zA-Z_\-0-9\.]+);)");
            std::sregex_iterator currentMatch(fileContent.begin(), fileContent.end(), pattern);
            std::sregex_iterator lastMatch;
            while (currentMatch != lastMatch) {
                std::smatch match2 = *currentMatch;
                resolveImport(match2[1].str(), implementation.moduleDependencies, implementation.externalModuleDependencies, implementation.pendingImports);
                ++currentMatch;
            }
        }
    }
}

fs::path Crafter::StdPcmDir(const Configuration& config) {
    // The std PCM is cached per target+march+toolchain: a PCM is only valid
    // for the exact clang that wrote it, so a compiler bump starts a cold
    // directory instead of handing the new clang a PCM it will crash on. A
    // wasm variant pass compiles it with extra codegen flags (e.g.
    // -mrelaxed-simd) — its BMI must not be shared with the baseline's, or
    // the consuming TUs see a target-feature mismatch. Suffix the cache dir
    // with the variant flags when present.
    std::string stdPcmKey = std::format("{}-{}-{}", config.target, config.march, GetToolchain().Key());
    // The flags every wasm unit gets are compiled into the std PCM as well,
    // and the importing units have to match them. Two releases that share a
    // cache and a compiler, as the Flatpak's branches do, would otherwise
    // take turns rebuilding this one std PCM, each time underneath the PCMs
    // built against the previous one, and clang crashes on those rather than
    // rejecting them.
    if (config.target.starts_with("wasm32")) {
        stdPcmKey += std::format("-{:08x}", static_cast<std::uint32_t>(std::hash<std::string_view>{}(WasmBaselineFlags)));
    }
    // The same goes for the mingw-w64 prefix the mingw std module is
    // compiled against: releases up to the fix for issue #43 gave clang the
    // prefix itself as the sysroot and the ones after give it a view of it,
    // and two prefixes are two sets of headers.
    if (config.target == "x86_64-w64-mingw32" && !GetToolchain().mingwPrefix.empty()) {
        stdPcmKey += std::format("-{:08x}", static_cast<std::uint32_t>(std::hash<std::string>{}(GetToolchain().mingwPrefix.string())));
    }
    for (const std::string& f : config.wasmVariantFlags) {
        stdPcmKey += "+";
        for (char c : f) stdPcmKey += (c == '/' || c == '\\') ? '_' : c;
    }
    return GetCacheDir()/stdPcmKey;
}

std::string Crafter::WasmCompileFlags(const Configuration& config) {
    std::string flags = std::format(" {}", WasmBaselineFlags);
    for (const std::string& f : config.wasmVariantFlags) flags += std::format(" {}", f);
    return flags;
}

fs::path Crafter::ExpectedOutput(const Configuration& config) {
    const fs::path dir = config.BinDir();
    const bool mingwTarget = config.target == "x86_64-w64-mingw32";
    if (config.type == ConfigurationType::Executable) {
        if (config.target.starts_with("wasm32")) return dir / std::format("{}.wasm", config.outputName);
        return mingwTarget ? dir / std::format("{}.exe", config.outputName) : dir / config.outputName;
    }
    if (config.type == ConfigurationType::LibraryStatic) {
        // The archive step writes lib<name>.a for every target, mingw included:
        // llvm-ar does not care about the object format.
        return dir / std::format("lib{}.a", config.outputName);
    }
    // LibraryDynamic — the .dll on the mingw target so an mtime check sees the
    // freshly linked library; on Unix the .so is that file.
    return mingwTarget ? dir / std::format("{}.dll", config.outputName) : dir / std::format("lib{}.so", config.outputName);
}

CompileCommand Crafter::GetCompileCommand(const Configuration& config) {
    CompileCommand out;
    out.stdPcmDir = StdPcmDir(config);
    out.pcmDir = config.PcmDir();

    std::string editedTarget = config.target;
    std::replace(editedTarget.begin(), editedTarget.end(), '-', '_');

    // wasm32 targets reject -march and silently ignore -mtune (clang errors on
    // the former). Skip both for any wasm32-* triple.
    const bool isWasm = config.target.starts_with("wasm32");
    std::string archFlags = isWasm
        ? std::string()
        : std::format(" -march={} -mtune={}", config.march, config.mtune);
    out.command = std::format("{} --target={}{} -std=c++26 -D CRAFTER_BUILD_CONFIGURATION_TARGET=\\\"{}\\\" -D CRAFTER_BUILD_CONFIGURATION_TARGET_{} -fprebuilt-module-path={} -fprebuilt-module-path={}", GetBaseCommand(config), config.target, archFlags, editedTarget, editedTarget, out.stdPcmDir.string(), out.pcmDir.string());

    if (!config.sysroot.empty()) {
        out.command += std::format(" --sysroot={}", config.sysroot);
        // Same reason as in BuildStdPcm: the driver ranks the host
        // toolchain's own libc++ headers (<install>/../include/c++/v1) above
        // --sysroot. A unit that only does `import std;` never notices, but
        // one that includes a standard header textually (vendored C++ such as
        // Crafter.Asset's gdeflate) would get host libc++ configured for the
        // host libc, which fails on a musl sysroot with "unknown rune table
        // for this platform". Force the sysroot's copy. -nostdinc++ leaves
        // -stdlib=libc++ unused on every compile ("argument unused during
        // compilation"), hence the silencer; the price is that it also hides
        // that diagnostic for a user's own misplaced flag (a -l or -Wl,
        // option in compileFlags) on sysroot builds. Not for mingw, which
        // uses libstdc++ and has no libc++ in its sysroot.
        if (!isWasm && config.target != "x86_64-w64-mingw32") {
            out.command += std::format(" -nostdinc++ -isystem {}/usr/include/c++/v1 -Wno-unused-command-line-argument", config.sysroot);
        }
    }
    if (isWasm) {
        // -mllvm is consumed by codegen but not the link driver, which is the
        // same command line; quiet the unused-flag warning rather than split
        // compile and link commands. An active variant pass (see the variant
        // driver at the end of Build) adds its codegen flags (e.g.
        // -mrelaxed-simd) to every TU; they are part of VariantId, so those
        // objects/PCMs land in their own dir.
        out.command += std::format("{} -Wno-unused-command-line-argument", WasmCompileFlags(config));
    }
    if (config.target == "x86_64-w64-mingw32") {
        // mingw libstdc++ defines TLS via __emutls_v.* (emulated TLS); without
        // -femulated-tls clang generates native-TLS references that don't
        // match. Symptom: undefined std::__once_callable / __once_call at
        // link time. Also -Wno-unused… because -femulated-tls is a codegen
        // flag the link driver doesn't consume.
        out.command += " -femulated-tls -Wno-unused-command-line-argument";
    }

    if(config.type == ConfigurationType::LibraryDynamic) {
        out.command += " -fPIC -D CRAFTER_BUILD_CONFIGURATION_TYPE_SHARED_LIBRARY";
    } else if(config.type == ConfigurationType::Executable) {
        out.command += " -D CRAFTER_BUILD_CONFIGURATION_TYPE_EXECUTABLE";
    } else {
        out.command += " -D CRAFTER_BUILD_CONFIGURATION_TYPE_LIBRARY";
    }

    // -I propagation that's valid for both C and C++ compiles. Module-only
    // bits (-fprebuilt-module-path) stay on `command` only.
    {
        std::unordered_set<Configuration*> seen;
        std::function<void(Configuration*)> addFlags = [&](Configuration* dep) {
            if (!seen.insert(dep).second) return;
            for (const auto& entry : fs::recursive_directory_iterator(dep->path)) {
                if (entry.is_directory() && entry.path().filename() == "include") {
                    out.includeFlags += std::format(" -I{}", entry.path().string());
                }
            }
            out.includeFlags += std::format(" -I{}", dep->path.string());
            out.command += std::format(" -fprebuilt-module-path={}", dep->PcmDir().string());
            for (Configuration* sub : dep->dependencies) {
                addFlags(sub);
            }
        };
        for (Configuration* dep : config.dependencies) {
            addFlags(dep);
        }
    }
    out.command += out.includeFlags;

    // External dependency includes, gathered transitively. Kept off `command`
    // so it stays exactly what it was before this was extracted.
    {
        std::unordered_set<const Configuration*> seen;
        std::function<void(const Configuration*)> addExternal = [&](const Configuration* cfg) {
            if (!seen.insert(cfg).second) return;
            for (const ExternalDependency& dep : cfg->externalDependencies) {
                for (const std::string& flag : ExternalIncludeFlags(dep, cfg->target)) {
                    out.externalIncludeFlags += std::format(" {}", flag);
                }
            }
            for (const Configuration* sub : cfg->dependencies) addExternal(sub);
        };
        addExternal(&config);
    }

    // Defines belong on both C and C++ compiles so vendored C dependencies
    // can see configuration-level macros consistently with module sources.
    for(const Define& define : config.defines) {
        if(define.value.empty()) {
            out.defineFlags += std::format(" -D {}", define.name);
        } else {
            out.defineFlags += std::format(" -D {}={}", define.name, define.value);
        }
    }
    out.command += out.defineFlags;

    // Track caller-provided compileFlags separately so the .c compile can
    // pick them up too (vendored C deps usually need -I from this set).
    for(const std::string& flag : config.compileFlags) {
        out.userFlags += std::format(" {}", flag);
    }
    out.command += out.userFlags;

    // Behaviour-neutral release performance for the binaries we emit: ThinLTO
    // (cross-TU inlining) plus dead-section GC and safe identical-code folding.
    // Default-on in Release, never Debug (keeps builds fast and debuggable).
    // Excluded for wasm32 — its -mllvm/sjlj codegen flags don't compose with
    // LTO here, and wasi-sdk lists exceptions under LTO as broken
    // (WebAssembly/wasi-sdk#629) — and for nvcc .cu objects below (they can't
    // emit LLVM bitcode, so they link in as ordinary objects alongside the
    // bitcode ones). ThinLTO rather than monolithic -flto so link time and
    // memory scale with arbitrary user project sizes. Compile-side flags
    // (-flto, -ffunction/-fdata-sections) ride on `command`, which is reused
    // as the link base; the link-only -Wl flags go on linkExtras so they
    // don't warn on each -c compile.
    out.useLto = !config.debug && !isWasm;
    out.ltoCompileFlags = out.useLto ? " -flto=thin -ffunction-sections -fdata-sections" : "";
    out.ltoLinkFlags = out.useLto ? " -flto=thin -Wl,--gc-sections -Wl,--icf=safe" : "";

    if(config.debug) {
        out.command += " -g -D CRAFTER_BUILD_CONFIGURATION_DEBUG";
    } else {
        out.command += " -O3";
    }
    out.command += out.ltoCompileFlags;
    return out;
}

namespace {
    // The outcome of `work` for `key` in this build pass. The first caller
    // runs it; every other caller, whether at the same time or later, waits
    // for that run and gets its result or its exception. The keys are the
    // directories the work writes, a configuration's PcmDir and an external
    // dependency's ExternalBuildDir, so the two kinds never collide.
    std::shared_future<BuildResult> OncePerPass(std::unordered_map<fs::path, std::shared_future<BuildResult>>& depResults, std::mutex& depMutex, const fs::path& key, const std::function<BuildResult()>& work) {
        std::promise<BuildResult> promise;
        std::shared_future<BuildResult> outcome = promise.get_future().share();
        {
            std::lock_guard lock(depMutex);
            if (auto [it, inserted] = depResults.try_emplace(key, outcome); !inserted) return it->second;
        }
        try {
            promise.set_value(work());
        } catch (...) {
            promise.set_exception(std::current_exception());
        }
        return outcome;
    }

    // Two configurations among `config` and its transitive dependencies that
    // export a module of the same name: the same project loaded along two
    // paths with different args, say, or from a checkout on one path and a
    // clone on the other. A program can hold one module of each name. Built
    // anyway, both PCM dirs went onto the consumer's -fprebuilt-module-path,
    // clang resolved the module by name to the first for every import, the
    // ones inside the other build's consumers included, and nothing checked
    // that it was the build they had been compiled against. The program then
    // linked code compiled against two layouts of the same types, and ran
    // (issue #41). Empty when the dependencies agree, otherwise the error,
    // naming the path to each of the two builds.
    std::string DuplicateModuleError(const Configuration& config) {
        struct Owner {
            const Configuration* cfg;
            std::string chain;
        };
        const auto describe = [](const Owner& owner) {
            return std::format("{} ({}, {}, project args {})", owner.chain, owner.cfg->path.string(), owner.cfg->VariantId(), owner.cfg->projectArgs);
        };
        std::unordered_map<std::string, Owner> owners;
        std::unordered_set<const Configuration*> visited;
        std::string error;
        std::function<void(const Configuration&, const std::string&)> walk = [&](const Configuration& c, const std::string& chain) {
            if (!error.empty() || !visited.insert(&c).second) return;
            for (const std::unique_ptr<Module>& iface : c.interfaces) {
                const auto [it, inserted] = owners.emplace(iface->name, Owner{ &c, chain });
                if (inserted || it->second.cfg == &c) continue;
                error = std::format("module {} is built twice for {}:\n  {}\n  {}\nA program can hold one build of each module: load {} with the same args, and from the same place, along every path.", iface->name, config.name, describe(it->second), describe(Owner{ &c, chain }), c.name);
                return;
            }
            for (const Configuration* dep : c.dependencies) walk(*dep, std::format("{} -> {}", chain, dep->name));
        };
        walk(config, config.name);
        return error;
    }

    // What a wasm32 configuration cannot be built with now that every unit
    // has C++ exceptions, and what its sysroot has to have for that; empty
    // for any other target and when nothing is wrong. Each would otherwise
    // fail at the first compile or link with a message that does not say
    // why, or not fail at all.
    std::string WasmBuildError(const Configuration& config) {
        if (!config.target.starts_with("wasm32")) return "";
        for (const std::vector<std::string>* flags : { &config.compileFlags, &config.linkFlags }) {
            for (const std::string& flag : *flags) {
                // The compile has the backend options that keep exception
                // handling; LTO code generation at the link does not, so it
                // drops every landing pad and the build succeeds with throws
                // that escape their catch blocks (WebAssembly/wasi-sdk#629).
                if (flag.starts_with("-flto")) {
                    return std::format("{}: {} is not supported on wasm32: LTO code generation drops C++ exception handling (WebAssembly/wasi-sdk#629), so every throw would escape its catch", config.name, flag);
                }
                // The std module is built with exceptions, and a unit built
                // without them cannot import it.
                if (flag == "-fno-exceptions" || flag == "-fno-cxx-exceptions") {
                    return std::format("{}: {} is not supported on wasm32: wasm builds have C++ exceptions, the std module included, and a unit compiled without them cannot import std", config.name, flag);
                }
            }
        }
        // wasi-sdk's exception support does not cover shared libraries: the
        // libc++ under lib/<triple>/eh is static archives built without -fPIC.
        if (config.type == ConfigurationType::LibraryDynamic) {
            return std::format("{}: wasm32 shared libraries are not supported: the exception-enabled libc++ they would link has static archives only", config.name);
        }
        const fs::path sysroot = config.sysroot;
        if (!fs::is_directory(sysroot)) {
            return std::format("no WASI sysroot at {}: the Flatpak bundles one, and CRAFTER_BUILD_WASI_SYSROOT selects another", sysroot.string());
        }
        const fs::path libDir = sysroot / "lib" / NormalizeTarget(config.target);
        if (!fs::is_directory(libDir)) {
            return std::format("the WASI sysroot at {} has nothing for {} (no {})", sysroot.string(), config.target, libDir.string());
        }
        // Only a link takes the exception-enabled libraries: a static
        // library's objects compile against the headers alone. The driver
        // looks in eh/ first and then in the triple's own directory, where a
        // sysroot built with exceptions only (WASI_SDK_EXCEPTIONS=ON) has them.
        // Without them the first link fails with "unable to find library
        // -lunwind", which says nothing about why it was asked for.
        if (config.type == ConfigurationType::Executable && !fs::exists(libDir / "eh" / "libunwind.a") && !fs::exists(libDir / "libunwind.a")) {
            return std::format("the WASI sysroot at {} has no C++ exception support (no {}): wasm builds use WebAssembly exception handling and need the exception-enabled libc++ and libunwind that wasi-sdk 33 and later ship. The Flatpak bundles such a sysroot; CRAFTER_BUILD_WASI_SYSROOT selects another", sysroot.string(), (libDir / "eh" / "libunwind.a").string());
        }
        return "";
    }
}

BuildResult Crafter::Build(Configuration& config, std::unordered_map<fs::path, std::shared_future<BuildResult>>& depResults, std::mutex& depMutex) {
    // Before anything is spawned: one message naming the missing compiler
    // beats a clang++-not-found per translation unit.
    if (const Toolchain& tc = GetToolchain(); !tc.error.empty()) {
        return {tc.error, false, {}};
    }
    // Before any directory is made or dependency built, so a refused graph
    // leaves nothing behind.
    if (std::string duplicate = DuplicateModuleError(config); !duplicate.empty()) {
        return {std::move(duplicate), false, {}};
    }
    // Reset per-build cached state on every Module/ModulePartition so that
    // successive Build() calls on the same Configuration re-evaluate mtimes
    // (incremental-rebuild test scenarios).
    //
    // Reset ONLY this configuration's own modules — never recurse into
    // dependencies. Configuration objects are shared across the dependency DAG
    // (diamond deps point at the same Configuration*), and every config in the
    // tree gets its own Build() call: the per-PcmDir builder registered in
    // depResults resets its own state here, at the top of its own Build(),
    // sequenced before that config's compile threads spawn. Recursing into
    // dependencies from here would re-clear a shared dependency's `compiled`
    // atomic from a parent/sibling thread *while that dependency's own Build()
    // is concurrently compiling it* — after its module-compile thread set the
    // flag true and exited but before its impl/partition waiter ran
    // compiled.wait(false). The waiter would then block forever on a flag
    // nothing re-signals: the build freezes mid-compile, idle, with no compiler
    // process alive (issue #16). Cross-config module state is consulted only via
    // PCM file mtimes and the depResults futures, never via these flags, so the
    // narrower reset is correct.
    for (auto& iface : config.interfaces) {
        iface->checked = false;
        iface->compiled.store(false);
        for (auto& part : iface->partitions) {
            part->checked = false;
            part->compiled.store(false);
        }
    }

    // Sources were scanned when they were declared, which for most callers is
    // before `dependencies` exists — AddTest resolves tests/<name>/main.cpp and
    // only then hands back a builder whose .Dependencies() supplies the library.
    // Any `import <DepModule>;` in such a TU resolved to nothing and so carried
    // no staleness edge, which meant a member added to a dependency's interface
    // rebuilt the library, relinked the consumer, and silently kept the
    // consumer's object compiled against the *old* class layout (issue #27).
    // Re-resolving here — the last point before mtimes are compared, with the
    // DAG fully wired — closes that window for every caller rather than for the
    // ones that remember to declare in the right order.
    config.ResolvePendingImports();

    // Auto-detect the WASI sysroot before any compile step runs so BuildStdPcm
    // and the main compile command see the same value. Covers all wasm32-*
    // triples (wasi, wasip1, wasip2, ...); the sysroot's per-triple subdirs
    // handle the differences.
    if (config.sysroot.empty() && config.target.starts_with("wasm32")) {
        config.sysroot = GetToolchain().wasiSysroot.string();
    }
    // As early as the duplicate-module check, so a refused build leaves no
    // directory behind and starts no thread, but after the sysroot is known.
    if (std::string refused = WasmBuildError(config); !refused.empty()) {
        return {std::move(refused), false, {}};
    }

    fs::path buildDir = config.BuildDir();
    fs::path outputDir = config.BinDir();

    if (!fs::exists(buildDir)) {
        fs::create_directories(buildDir);
    }

    if (!fs::exists(outputDir)) {
        fs::create_directories(outputDir);
    }

    BuildResult buildResult{};

    // glslang #include search paths for every shader compiled in this
    // configuration: each transitive (incl. self) buildFiles entry's parent
    // dir, or the entry itself if it points at a directory. Collected once
    // up front so the per-shader threads can capture the resulting span by
    // reference. No file copy involved — glslang reads the includes in
    // place from the dep's source tree.
    std::vector<fs::path> shaderIncludeDirs;
    {
        std::unordered_set<std::string> seenDirs;
        std::unordered_set<const Configuration*> seenCfg;
        std::function<void(const Configuration*)> collect = [&](const Configuration* c) {
            if (!seenCfg.insert(c).second) return;
            for (const fs::path& bf : c->buildFiles) {
                fs::path dir = fs::is_directory(bf) ? bf : bf.parent_path();
                if (seenDirs.insert(dir.string()).second) {
                    shaderIncludeDirs.push_back(std::move(dir));
                }
            }
            for (const Configuration* sub : c->dependencies) collect(sub);
        };
        collect(&config);
    }

    std::vector<std::thread> threads;
    threads.reserve(config.shaders.size() + 1 + config.interfaces.size() + config.implementations.size());

    std::string buildError;
    std::atomic<bool> buildCancelled{false};
    // Two entries with the same output name would compile in parallel into
    // one file: whichever finished last won, the build reported success, and
    // Check() then called both up to date. The usual way in is one source
    // registered twice with different defines and no variant; a.vert next to
    // a.frag is another.
    {
        std::unordered_map<std::string, const Shader*> outputs;
        for (const Shader& shader : config.shaders) {
            const auto [existing, inserted] = outputs.emplace(shader.OutputName().string(), &shader);
            if (inserted) continue;
            buildError = std::format("shaders {} and {} both compile to {}: give one of them a distinct Shader::variant", existing->second->path.string(), shader.path.string(), existing->first);
            buildCancelled.store(true);
            break;
        }
    }
    for (const Shader& shader : config.shaders) {
        if (buildCancelled.load(std::memory_order_relaxed)) break;
        if (shader.Check(outputDir, buildDir, shaderIncludeDirs)) continue;
        threads.emplace_back([&shader, &outputDir, &buildDir, &shaderIncludeDirs, &buildError, &buildCancelled]() {
            // A source registered more than once shows up once per variant;
            // name the variant so the lines can be told apart.
            Progress::Task task(shader.variant.empty() ? std::format("Compiling shader {}", shader.path.filename().string()) : std::format("Compiling shader {} ({})", shader.path.filename().string(), shader.variant));
            if (buildCancelled.load(std::memory_order_relaxed)) return;

            std::string result = shader.Compile(outputDir, buildDir, shaderIncludeDirs);
            if (result.empty()) return;

            bool expected = false;
            if (buildCancelled.compare_exchange_strong(expected, true)) {
                buildError = std::move(result);
            }
        });
    }

    // Asset compilation: each cfg.assets entry is either a single .png/.obj
    // file (flat output: outputDir/<filename>.ctex/cmesh — preserves the
    // original behavior) or a directory (recursed, with the relative tree
    // mirrored under outputDir/<dirname>/; .png/.obj are compressed, every
    // other file is copied through unchanged). Directory mode lets mod/map
    // trees keep their nested layout so mod.json paths like
    // "cannon/base.cmesh" resolve correctly at runtime.
    // Skipped per-file if the output is newer than the source. Each
    // compress runs in its own thread; passthrough copies are bundled into
    // a single thread to match the cfg.files pattern.
    auto compressedName = [](const fs::path& src) -> std::optional<fs::path> {
        std::string ext = src.extension().string();
        for (char& c : ext) c = static_cast<char>(std::tolower(static_cast<std::uint8_t>(c)));
        // stb_image (used by CompressAsset → TextureAsset::LoadPNG) handles
        // png/tga/jpg/bmp; all map to .ctex.
        if (ext == ".png" || ext == ".tga" || ext == ".jpg" || ext == ".jpeg" || ext == ".bmp") {
            return fs::path(src.filename()).replace_extension(".ctex");
        }
        if (ext == ".obj") return fs::path(src.filename()).replace_extension(".cmesh");
        return std::nullopt;
    };
    auto submitCompress = [&](fs::path sourcePath, fs::path outRelative) {
        fs::path out = outputDir / outRelative;
        if (fs::exists(out) && fs::exists(sourcePath) && fs::last_write_time(sourcePath) <= fs::last_write_time(out)) return;
        threads.emplace_back([sourcePath = std::move(sourcePath), out = std::move(out), &buildError, &buildCancelled]() {
            Progress::Task task(std::format("Compressing asset {}", sourcePath.filename().string()));
            if (buildCancelled.load(std::memory_order_relaxed)) return;
            std::error_code ec;
            fs::create_directories(out.parent_path(), ec);
            std::string result = CompressAsset(sourcePath, out);
            if (result.empty()) return;
            bool expected = false;
            if (buildCancelled.compare_exchange_strong(expected, true)) {
                buildError = std::move(result);
            }
        });
    };
    std::vector<std::pair<fs::path, fs::path>> assetPassthroughs;
    for (const fs::path& asset : config.assets) {
        if (fs::is_directory(asset)) {
            fs::path topName = asset.filename();
            for (const auto& entry : fs::recursive_directory_iterator(asset)) {
                if (!entry.is_regular_file()) continue;
                fs::path rel = fs::relative(entry.path(), asset);
                if (std::optional<fs::path> compName = compressedName(entry.path())) {
                    submitCompress(entry.path(), topName / rel.parent_path() / *compName);
                } else {
                    assetPassthroughs.emplace_back(entry.path(), topName / rel);
                }
            }
        } else {
            std::optional<fs::path> outName = compressedName(asset);
            if (!outName) {
                buildCancelled.store(true);
                buildError = std::format("{}: unsupported asset extension (expected .png/.tga/.jpg/.bmp/.obj, or a directory)", asset.string());
                break;
            }
            submitCompress(asset, *outName);
        }
    }
    if (!assetPassthroughs.empty()) {
        threads.emplace_back([passthroughs = std::move(assetPassthroughs), &outputDir, &buildCancelled, &buildError]() {
            Progress::Task task("Copying asset passthrough files");
            if (buildCancelled.load(std::memory_order_relaxed)) return;
            try {
                for (const auto& [src, rel] : passthroughs) {
                    fs::path dst = outputDir / rel;
                    fs::create_directories(dst.parent_path());
                    if (!fs::exists(dst)) {
                        fs::copy_file(src, dst);
                    } else if (fs::last_write_time(src) > fs::last_write_time(dst)) {
                        fs::copy_file(src, dst, fs::copy_options::overwrite_existing);
                    }
                }
            } catch (const std::exception& e) {
                bool expected = false;
                if (buildCancelled.compare_exchange_strong(expected, true)) {
                    buildError = e.what();
                }
            }
        });
    }

    threads.emplace_back([&config, &outputDir, &buildCancelled, &buildError]() {
        Progress::Task task(std::format("Copying files for {}", config.name));
        if (buildCancelled.load(std::memory_order_relaxed)) return;
        try {
            for (const fs::path& additionalFile : config.files) {
                fs::path destination = outputDir / additionalFile.filename();
                if (fs::is_directory(additionalFile)) {
                    for (const auto& entry : fs::recursive_directory_iterator(additionalFile)) {
                        const fs::path& sourcePath = entry.path();
                        fs::path relativePath = fs::relative(sourcePath, additionalFile);
                        fs::path destPath = destination / relativePath;
                        if (entry.is_directory()) {
                            if (!fs::exists(destPath)) fs::create_directories(destPath);
                        } else if (entry.is_regular_file()) {
                            fs::create_directories(destPath.parent_path());
                            if (!fs::exists(destPath)) {
                                fs::copy_file(sourcePath, destPath);
                            } else if (fs::last_write_time(sourcePath) > fs::last_write_time(destPath)) {
                                fs::copy_file(sourcePath, destPath, fs::copy_options::overwrite_existing);
                            }
                        }
                    }
                } else {
                    if (!fs::exists(destination)) {
                        fs::copy_file(additionalFile, destination);
                    } else if (fs::last_write_time(additionalFile) > fs::last_write_time(destination)) {
                        fs::copy_file(additionalFile, destination, fs::copy_options::overwrite_existing);
                    }
                }
            }
        } catch(std::exception& e) {
            bool expected = false;
            if (buildCancelled.compare_exchange_strong(expected, true)) {
                buildError = e.what();
            }
        }
    });

    std::vector<ExternalBuildResult> externalResults(config.externalDependencies.size());
    std::vector<std::thread> externalThreads;
    externalThreads.reserve(config.externalDependencies.size());
    for (std::size_t i = 0; i < config.externalDependencies.size(); ++i) {
        externalThreads.emplace_back([&, i]() {
            const ExternalDependency& dep = config.externalDependencies[i];
            Progress::Task task(std::format("Building external dep {}", dep.name));
            if (buildCancelled.load(std::memory_order_relaxed)) return;
            std::string error;
            try {
                // Every configuration of the pass that declares this
                // dependency shares one fetch and build of it. A project's
                // tests often each copy its externalDependencies, and RunTests
                // builds them side by side: each of them pulling the clone
                // cost a network round trip per test, and before the clone had
                // a lock, the simultaneous pulls broke its FETCH_HEAD and
                // failed every test (issue #34).
                const std::shared_future<BuildResult> built = OncePerPass(depResults, depMutex, ExternalBuildDir(dep, config.target), [&] {
                    return BuildResult{BuildExternal(dep, config.target), false, {}};
                });
                error = built.get().result;
                if (error.empty()) externalResults[i] = ExternalOutputs(dep, config.target);
            } catch (const std::exception& e) {
                error = std::format("external dep {} threw: {}", dep.name, e.what());
            }
            if (error.empty()) return;
            bool expected = false;
            if (buildCancelled.compare_exchange_strong(expected, true)) {
                buildError = std::move(error);
            }
        });
    }

    fs::path stdPcmDir = StdPcmDir(config);

    if (!fs::exists(stdPcmDir)) {
        fs::create_directories(stdPcmDir);
    }

    std::string stdPcmResult;
    {
        Progress::Task task(std::format("Building std PCM ({}-{})", config.target, config.march));
        // The shader and external threads are running: an exception leaving
        // here would destroy them joinable, which terminates the process.
        try {
            stdPcmResult = BuildStdPcm(config, stdPcmDir/"std.pcm");
        } catch (const std::exception& e) {
            stdPcmResult = std::format("building the std module for {}: {}", config.target, e.what());
        }
    }
    if(!stdPcmResult.empty()) {
        buildCancelled.store(true);
        for(std::thread& thread : threads) thread.join();
        for(std::thread& thread : externalThreads) thread.join();
        return {stdPcmResult, false, {}};
    }

    fs::path pcmDir = config.PcmDir();

    fs::copy_file(stdPcmDir/"std.pcm", pcmDir/"std.pcm", fs::copy_options::update_existing);

    // Everything about the compile command that is a pure function of the
    // Configuration is assembled by GetCompileCommand, so that anything which
    // needs to PARSE these sources with the same flags — the linter's AST
    // layer — cannot drift from what actually built the PCMs. Build appends
    // only what depends on work having happened: dependency public flags and
    // external dependency flags, further down.
    CompileCommand compile = GetCompileCommand(config);
    std::string command = compile.command;
    const std::string& includeFlags = compile.includeFlags;
    const std::string& defineFlags = compile.defineFlags;
    const std::string& userFlags = compile.userFlags;
    const std::string& ltoCompileFlags = compile.ltoCompileFlags;
    const std::string& ltoLinkFlags = compile.ltoLinkFlags;
    const bool isWasm = config.target.starts_with("wasm32");

    std::string files;
    std::set<std::string> libSet;
    std::set<std::string> publicFlagSet;
    std::mutex fileMutex;
    std::vector<std::thread> depThreads;
    depThreads.reserve(config.dependencies.size());
    std::atomic<bool> repack(false);

    for(Configuration* dep : config.dependencies) {
        depThreads.emplace_back([&, dep](){
            try {
                if (buildCancelled.load(std::memory_order_relaxed)) return;

                const std::shared_future<BuildResult> built = OncePerPass(depResults, depMutex, dep->PcmDir(), [&] { return Build(*dep, depResults, depMutex); });
                const BuildResult& result = built.get();
                fileMutex.lock();
                for (const std::string& lib : result.libs) libSet.insert(lib);
                for (const std::string& f : result.publicCompileFlags) publicFlagSet.insert(f);
                fileMutex.unlock();
                if (!result.result.empty()) {
                    bool expected = false;
                    if (buildCancelled.compare_exchange_strong(expected, true)) {
                        buildError = result.result;
                    }
                }
                if (result.repack) {
                    repack = true;
                }
            } catch (const std::exception& e) {
                bool expected = false;
                if (buildCancelled.compare_exchange_strong(expected, true)) {
                    buildError = std::format("dep build for {} threw: {}", dep->path.string(), e.what());
                }
            }
        });
    }

    // Only the CMake build type is still derived here; the compile flags it
    // used to sit alongside now come from GetCompileCommand.
    const std::string cmakeBuildType = config.debug ? "Debug" : "Release";

    // Same target-aware setup as the C++ compile path (line 459-): wasm32
    // rejects -march, silently ignores -mtune, and needs --sysroot to find
    // wasi-libc headers. Build the prefix once so all C compiles share it.
    std::string cArchFlags = isWasm
        ? std::string()
        : std::format(" -march={} -mtune={}", config.march, config.mtune);
    if (!config.sysroot.empty()) {
        cArchFlags += std::format(" --sysroot={}", config.sysroot);
    } else if (config.target == "x86_64-w64-mingw32") {
        // The C++ side gets it through GetBaseCommand.
        if (const fs::path& sysroot = MingwSysroot(); !sysroot.empty()) cArchFlags += std::format(" --sysroot={}", sysroot.string());
    }
    if (isWasm) {
        // The C++ path's wasm flags, all of them, a variant pass's included.
        // With only the signal.h define, wasi-libc's setjmp.h refused to
        // compile in C, and a C object given -wasm-enable-sjlj through
        // compileFlags used LLVM's legacy exception encoding next to C++
        // objects in the standard one, a mix engines refuse to load.
        cArchFlags += WasmCompileFlags(config);
    }
    for (const fs::path& cFile : config.cFiles) {
        files += std::format(" {}_source.o ", (buildDir / cFile.filename()).string());
        const std::string objPath = std::format("{}_source.o", (buildDir / cFile.filename()).string());
        const std::string srcPath = std::format("{}.c", cFile.string());
        // C sources carry their dependencies entirely in #includes, so the
        // depfile the compile below writes is the whole record of what this
        // object was built from beyond the .c itself.
        if (!fs::exists(objPath) || (fs::exists(srcPath) && fs::last_write_time(srcPath) > fs::last_write_time(objPath)) || NewestPrerequisite(std::format("{}.d", objPath)) > fs::last_write_time(objPath)) {
            threads.emplace_back([&cFile, &buildDir, &buildError, &buildCancelled, &config, &includeFlags, &defineFlags, &userFlags, &cArchFlags, &ltoCompileFlags]() {
                Progress::Task task(std::format("Compiling {}.c", cFile.filename().string()));
                if (buildCancelled.load(std::memory_order_relaxed)) return;

                std::string result = RunBuildCommand(std::format("{8} {0}.c --target={1}{2} -O3{3} -c{4}{5}{6} -MD -MF {7}_source.o.d -o {7}_source.o", cFile.string(), config.target, cArchFlags, ltoCompileFlags, includeFlags, defineFlags, userFlags, (buildDir / cFile.filename()).string(), GetToolchain().clang.string()));
                if (result.empty()) return;

                bool expected = false;
                if (buildCancelled.compare_exchange_strong(expected, true)) {
                    buildError = std::move(result);
                }
            });
        }
    }

    for (const fs::path& cFile : config.cuda) {
        files += std::format(" {}_source.o ", (buildDir / cFile.filename()).string());
        const std::string objPath = std::format("{}_source.o", (buildDir / cFile.filename()).string());
        const std::string srcPath = std::format("{}.cu", cFile.string());
        // Still .cu-mtime only: the header tracking the C and C++ paths get
        // comes from asking the compiler for a depfile, and nvcc's -MD/-MF are
        // untested here (no CUDA toolkit in CI), so a .cu that only sees a
        // changed header does not rebuild yet.
        if (!fs::exists(objPath) || (fs::exists(srcPath) && fs::last_write_time(srcPath) > fs::last_write_time(objPath))) {
            threads.emplace_back([&cFile, &buildDir, &buildError, &buildCancelled]() {
                Progress::Task task(std::format("Compiling {}.cu", cFile.filename().string()));
                if (buildCancelled.load(std::memory_order_relaxed)) return;

                std::string result = RunBuildCommand(std::format("nvcc {}.cu -c -o {}_source.o -O3 -arch=sm_89", cFile.string(), (buildDir / cFile.filename()).string()));
                if (result.empty()) return;

                bool expected = false;
                if (buildCancelled.compare_exchange_strong(expected, true)) {
                    buildError = std::move(result);
                }
            });
        }
    }

    for(std::thread& thread : depThreads) {
        thread.join();
    }
    for(std::thread& thread : externalThreads) {
        thread.join();
    }

    if(buildCancelled.load()) {
        for(std::thread& thread : threads) thread.join();
        return {buildError, false, {}};
    }

    // Ship runtime artifacts from transitive deps' bin dirs alongside the
    // executable: compiled .spv files (cfg.shaders) and asset files/dirs
    // (cfg.files). The lib already mirrored these into its own bin dir
    // during its build, but a consumer exe loads them from its own dir at
    // runtime. Only an exe is a deployment unit; intermediate libs don't
    // need to forward since the exe walks all transitive deps. Runs outside
    // the repack gate because the relink mtime check above only watches
    // .so/.dll/.a, so a shader/file-only change in a dep wouldn't trigger
    // repack but still needs the new artifact copied across.
    // (cfg.buildFiles use a different mechanism — they're exposed to shader
    // compiles as #include search paths in place, no copy.)
    if (config.type == ConfigurationType::Executable) {
        try {
            auto copyTree = [](const fs::path& src, const fs::path& dest) {
                if (fs::is_directory(src)) {
                    for (const auto& entry : fs::recursive_directory_iterator(src)) {
                        fs::path rel = fs::relative(entry.path(), src);
                        fs::path destPath = dest / rel;
                        if (entry.is_directory()) {
                            if (!fs::exists(destPath)) fs::create_directories(destPath);
                        } else if (entry.is_regular_file()) {
                            fs::create_directories(destPath.parent_path());
                            if (!fs::exists(destPath)) {
                                fs::copy_file(entry.path(), destPath);
                            } else if (fs::last_write_time(entry.path()) > fs::last_write_time(destPath)) {
                                fs::copy_file(entry.path(), destPath, fs::copy_options::overwrite_existing);
                            }
                        }
                    }
                } else {
                    if (!fs::exists(dest)) {
                        fs::copy_file(src, dest);
                    } else if (fs::last_write_time(src) > fs::last_write_time(dest)) {
                        fs::copy_file(src, dest, fs::copy_options::overwrite_existing);
                    }
                }
            };
            std::unordered_set<Configuration*> seen;
            std::function<void(Configuration*)> forwardDepArtifacts = [&](Configuration* dep) {
                if (!seen.insert(dep).second) return;
                fs::path depBinDir = dep->BinDir();
                for (const Shader& shader : dep->shaders) {
                    fs::path src = depBinDir / shader.OutputName();
                    if (!fs::exists(src)) continue;
                    copyTree(src, outputDir / src.filename());
                }
                for (const fs::path& additionalFile : dep->files) {
                    fs::path src = depBinDir / additionalFile.filename();
                    if (!fs::exists(src)) continue;
                    copyTree(src, outputDir / additionalFile.filename());
                }
                for (const fs::path& asset : dep->assets) {
                    // Directory entry: the dep already mirrored the
                    // (compressed + passthrough) tree under
                    // depBinDir/<asset.filename()>/. Forward it wholesale
                    // so our bin dir gets the same layout.
                    if (fs::is_directory(asset)) {
                        fs::path src = depBinDir / asset.filename();
                        if (!fs::exists(src)) continue;
                        copyTree(src, outputDir / asset.filename());
                        continue;
                    }
                    std::string ext = asset.extension().string();
                    for (char& c : ext) c = static_cast<char>(std::tolower(static_cast<std::uint8_t>(c)));
                    fs::path srcName = asset.filename();
                    if (ext == ".png" || ext == ".tga" || ext == ".jpg" || ext == ".jpeg" || ext == ".bmp") {
                        srcName.replace_extension(".ctex");
                    } else if (ext == ".obj") {
                        srcName.replace_extension(".cmesh");
                    } else {
                        continue;
                    }
                    fs::path src = depBinDir / srcName;
                    if (!fs::exists(src)) continue;
                    copyTree(src, outputDir / srcName);
                }
                for (Configuration* sub : dep->dependencies) forwardDepArtifacts(sub);
            };
            for (Configuration* dep : config.dependencies) forwardDepArtifacts(dep);
        } catch (const fs::filesystem_error& e) {
            for(std::thread& thread : threads) thread.join();
            return {e.what(), false, {}};
        }
    }

    if(repack.load()) {
        buildResult.repack = true;
    }
    buildResult.libs = std::move(libSet);
    for(const std::string& flag : config.linkFlags) {
        buildResult.libs.insert(flag);
    }
    // Public compile flags propagated from sub-deps. Add them to this build's
    // command so config sees the headers its deps expose, and re-publish them
    // so config's own consumers see them transitively.
    for (const std::string& flag : publicFlagSet) command += std::format(" {}", flag);
    buildResult.publicCompileFlags = std::move(publicFlagSet);
    fs::file_time_type externalFloor = fs::file_time_type::min();
    for(const ExternalBuildResult& ext : externalResults) {
        for(const std::string& flag : ext.compileFlags) {
            command += std::format(" {}", flag);
            // Headers a dep links via ExternalDependency are part of its
            // public surface (its modules can include them in declarations
            // visible to consumers), so propagate the -I to consumers.
            buildResult.publicCompileFlags.insert(flag);
        }
        for(const std::string& flag : ext.linkFlags) {
            buildResult.libs.insert(flag);
        }
        if (ext.latestArtifact > externalFloor) externalFloor = ext.latestArtifact;
    }

    // Check every interface before compiling any of them. Module::Compile waits
    // on the `compiled` flag of each sibling module it imports, and that flag is
    // set either by a Compile that runs or by the Check that decides none is
    // needed — so a Check still pending while another module's thread is already
    // waiting would block on a flag nothing goes on to raise.
    std::vector<Module*> staleInterfaces;
    for(std::unique_ptr<Module>& interface : config.interfaces) {
        if(interface->Check(pcmDir, externalFloor)) {
            staleInterfaces.push_back(interface.get());
            buildResult.repack = true;
        }
        files += std::format(" {}/{}.o", buildDir.string(),  interface->path.filename().string());
        for(std::unique_ptr<ModulePartition>& part : interface->partitions) {
            files += std::format(" {}/{}.o", buildDir.string(),  part->path.filename().string());
        }
    }

    for(Module* mod : staleInterfaces) {
        threads.emplace_back([mod, &command, &pcmDir, &buildDir, &buildCancelled, &buildError]() {
            Progress::Task task(std::format("Compiling interface {}", mod->path.filename().string()));
            try {
                mod->Compile(command, pcmDir, buildDir, buildCancelled, buildError);
            } catch (const std::exception& e) {
                bool expected = false;
                if (buildCancelled.compare_exchange_strong(expected, true)) {
                    buildError = std::format("Module::Compile threw: {}", e.what());
                }
            }
        });
    }

    for(Implementation& implementation : config.implementations) {
        if(implementation.Check(buildDir, pcmDir, externalFloor)) {
            buildResult.repack = true;
            Implementation* impl = &implementation;
            threads.emplace_back([impl, &command, &buildDir, &buildCancelled, &buildError]() {
                Progress::Task task(std::format("Compiling {}.cpp", impl->path.filename().string()));
                try {
                    impl->Compile(command, buildDir, buildCancelled, buildError);
                } catch (const std::exception& e) {
                    bool expected = false;
                    if (buildCancelled.compare_exchange_strong(expected, true)) {
                        buildError = std::format("Implementation::Compile threw: {}", e.what());
                    }
                }
            });
        }
        files += std::format(" {}/{}_impl.o", buildDir.string(),  implementation.path.filename().string());
    }

    for(std::thread& thread : threads) {
        thread.join();
    }

    if(buildCancelled.load()) {
        return {buildError, false, {}};
    }

    std::string linkExtras;
    for(const std::string& flag : buildResult.libs) {
        linkExtras += std::format(" {}", flag);
    }
    // Link-only LTO/section flags (empty in Debug and for wasm). Every exe/lib
    // link below ends with linkExtras, so this reaches them all; the static-lib
    // archive path uses ar instead and is handled separately.
    linkExtras += ltoLinkFlags;
    // Host links use the toolchain's own libc++. When the toolchain lives
    // outside /usr (a bundled one) the binary needs an rpath to find
    // libc++.so.1 at run time. mingw links libstdc++ and every sysroot build
    // (wasm included) brings its own libc++.
    if (config.target != "x86_64-w64-mingw32" && config.sysroot.empty()) {
        linkExtras += GetToolchain().LibcxxLinkFlags();
    }
    // mingw uses libstdc++; C++26 std::print/format extras live in libstdc++exp.
    // libstdc++ on mingw uses winpthreads for std::atomic_wait /
    // counting_semaphore / stop_token, so -lpthread is required as soon as
    // those primitives appear (they do, transitively, in any non-trivial std
    // import). -static-libstdc++ bundles libstdc++ into the exe so we don't
    // chase libstdc++-6.dll TLS symbol mismatches across mingw versions and
    // the resulting binary stands alone. Auto-link so user projects don't
    // carry boilerplate.
    if (config.target == "x86_64-w64-mingw32") {
        // Static-link libstdc++/libgcc/libwinpthread so the resulting .exe
        // or .dll doesn't depend on a specific runtime DLL being on the
        // consumer's PATH. The mingw runtime ABI varies subtly between
        // distributions (Arch UCRT vs msys2 UCRT vs msys2 MSVCRT) and
        // STATUS_ENTRYPOINT_NOT_FOUND at LoadLibrary time is the symptom
        // of a mismatch. Static linkage trades binary size for portability.
        // The -Bstatic/-Bdynamic bracketing forces -lpthread to resolve
        // against libwinpthread.a rather than the import lib; everything
        // else (KERNEL32, UCRT) stays dynamic. -lstdc++exp adds C++26
        // std::print/format extras. -femulated-tls is already on the
        // compile so __once_callable et al resolve in static libstdc++.
        linkExtras += " -lstdc++exp -static-libstdc++ -static-libgcc -Wl,-Bstatic -lpthread -Wl,-Bdynamic";
    }
    // Code built with -fwasm-exceptions calls into libunwind (the
    // __cpp_exception tag, the landing-pad context, _Unwind_RaiseException),
    // and -wasm-enable-sjlj turns setjmp and longjmp into calls into
    // wasi-libc's libsetjmp (__wasm_setjmp, __wasm_longjmp, the __c_longjmp
    // tag). The driver adds neither to the link the way it adds libc++. A
    // static archive contributes only what something references, so a
    // program without setjmp gets nothing from libsetjmp, and every sysroot
    // that passes WasmBuildError ships both.
    if (isWasm) {
        linkExtras += " -lunwind -lsetjmp";
    }

    // Force a relink if the expected output is missing or older than any dep
    // artifact. Missing covers: previous build produced a different outputName,
    // or the binary was deleted by hand. Older-than-dep covers: dep's library
    // was rebuilt by an earlier run (so dep.repack is false this time around)
    // but the consumer was never relinked against the new dep.
    {
        fs::path expected = ExpectedOutput(config);
        if (!fs::exists(expected)) {
            buildResult.repack = true;
        } else {
            auto consumerMtime = fs::last_write_time(expected);
            for (Configuration* dep : config.dependencies) {
                fs::path depArtifact = ExpectedOutput(*dep);
                if (fs::exists(depArtifact) && fs::last_write_time(depArtifact) > consumerMtime) {
                    buildResult.repack = true;
                    break;
                }
            }
            // Also relink if any .o this archive bundles is newer than the
            // archive itself. Covers a build that compiled the .o but never
            // reached the link step (interrupt, crash, or a source touched
            // after compile but before link): on the next run the .cpp is
            // already ≤ .o so Implementation/Module Check returns false and
            // nothing else would notice the archive is stale.
            if (!buildResult.repack) {
                auto objNewer = [&](const fs::path& obj) {
                    std::error_code ec;
                    auto t = fs::last_write_time(obj, ec);
                    return !ec && t > consumerMtime;
                };
                for (const std::unique_ptr<Module>& iface : config.interfaces) {
                    if (objNewer(buildDir / std::format("{}.o", iface->path.filename().string()))) {
                        buildResult.repack = true;
                        break;
                    }
                    bool partHit = false;
                    for (const std::unique_ptr<ModulePartition>& part : iface->partitions) {
                        if (objNewer(buildDir / std::format("{}.o", part->path.filename().string()))) {
                            partHit = true;
                            break;
                        }
                    }
                    if (partHit) { buildResult.repack = true; break; }
                }
                if (!buildResult.repack) {
                    for (const Implementation& impl : config.implementations) {
                        if (objNewer(buildDir / std::format("{}_impl.o", impl.path.filename().string()))) {
                            buildResult.repack = true;
                            break;
                        }
                    }
                }
                // C and CUDA objects are archive members too, and their compile
                // loop above is the only thing that knows it rebuilt one — it
                // sets no repack flag, so without this a .c edit recompiled the
                // object and then linked nothing.
                if (!buildResult.repack) {
                    auto sourceObjNewer = [&](const std::vector<fs::path>& sources) {
                        for (const fs::path& source : sources) {
                            if (objNewer(buildDir / std::format("{}_source.o", source.filename().string()))) return true;
                        }
                        return false;
                    };
                    if (sourceObjNewer(config.cFiles) || sourceObjNewer(config.cuda)) {
                        buildResult.repack = true;
                    }
                }
            }
        }
    }

    // The exact command the link (or archive) step runs, kept beside the
    // objects once it has succeeded. A different one relinks even with no
    // object newer than the output: a link flag changed in project.cpp, or a
    // dependency's library moved, as an ExternalDependency's does when its
    // options change and it is built into a new cache directory.
    std::string linkCommand;
    if (config.type == ConfigurationType::Executable) {
        if (config.target.starts_with("wasm32")) {
            linkCommand = std::format("{}{} -o {}.wasm -fuse-ld=lld{}", command, files, (outputDir/config.outputName).string(), linkExtras);
        } else {
            linkCommand = std::format("{}{} -o {} -fuse-ld=lld{}", command, files, (outputDir/config.outputName).string(), linkExtras);
        }
    } else if (config.type == ConfigurationType::LibraryStatic) {
        // ThinLTO emits LLVM bitcode objects; plain `ar` writes an archive
        // index that omits their symbols, so a consumer's lld link can't
        // pull the needed members. llvm-ar writes a bitcode-aware index
        // and handles plain ELF and COFF objects just as well, so every
        // build uses it.
        linkCommand = std::format("{} rcs {}.a {}", GetToolchain().llvmAr.string(), (outputDir/fs::path(std::string("lib")+config.outputName)).string(), files);
    } else if (config.target == "x86_64-w64-mingw32") {
        // LibraryDynamic. Output names follow each target's convention so
        // consumers can link via the standard linker search:
        //   mingw: <name>.dll + lib<name>.dll.a (lld --out-implib)
        //   unix:  lib<name>.so                (rpath $ORIGIN)
        fs::path dll = outputDir / std::format("{}.dll", config.outputName);
        fs::path implib = outputDir / std::format("lib{}.dll.a", config.outputName);
        linkCommand = std::format("{}{} -shared -o {} -Wl,--out-implib,{} -fuse-ld=lld{}", command, files, dll.string(), implib.string(), linkExtras);
    } else {
        linkCommand = std::format("{}{} -shared -o {}.so -Wl,-rpath,'$ORIGIN' -fuse-ld=lld{}", command, files, (outputDir/(std::string("lib")+config.outputName)).string(), linkExtras);
    }
    const fs::path linkRecord = buildDir / std::format("{}.link", config.outputName);
    if (!buildResult.repack) {
        std::ifstream recorded(linkRecord, std::ios::binary);
        const std::string previous((std::istreambuf_iterator<char>(recorded)), std::istreambuf_iterator<char>());
        if (previous != linkCommand) buildResult.repack = true;
    }

    if(buildResult.repack) {
        Progress::Task task(std::format("Linking {}", config.outputName));
        // The record goes first, so a link that fails leaves it stale.
        std::error_code removed;
        fs::remove(linkRecord, removed);
        if(config.type == ConfigurationType::Executable) {
            if(config.target == "x86_64-w64-mingw32") {
                try {
                    // Copy any LibraryDynamic dependency DLLs alongside
                    // the launcher exe — Windows resolves DLLs from the exe's
                    // own directory at load time, so this is the simplest
                    // equivalent of rpath $ORIGIN.
                    std::unordered_set<Configuration*> dllSeen;
                    std::function<void(Configuration*)> copyDepDlls = [&](Configuration* dep) {
                        if (!dllSeen.insert(dep).second) return;
                        if (dep->type == ConfigurationType::LibraryDynamic && dep->target == "x86_64-w64-mingw32") {
                            // Only the DLL: Windows resolves it from the exe's
                            // directory at load time. The import lib stays in
                            // the dependency's own bin dir, which is already
                            // on the link line through buildResult.libs.
                            fs::path src = dep->BinDir() / std::format("{}.dll", dep->outputName);
                            if (fs::exists(src)) {
                                fs::path dest = outputDir / src.filename();
                                if (!fs::exists(dest) || fs::last_write_time(src) > fs::last_write_time(dest)) {
                                    fs::copy(src, dest, fs::copy_options::overwrite_existing);
                                }
                            }
                        }
                        for (Configuration* sub : dep->dependencies) copyDepDlls(sub);
                    };
                    for (Configuration* dep : config.dependencies) copyDepDlls(dep);
                } catch (const fs::filesystem_error& e) {
                    return {e.what(), false, {}};
                }
            }
        }
        buildResult.result = RunBuildCommand(linkCommand);
        if (buildResult.result.empty()) {
            std::ofstream(linkRecord, std::ios::binary | std::ios::trunc) << linkCommand;
        }
    }

    if (config.type == ConfigurationType::LibraryStatic || config.type == ConfigurationType::LibraryDynamic) {
        buildResult.libs.insert(std::format("-L{}", outputDir.string()));
        buildResult.libs.insert(std::format("-l{}", config.outputName));
    }

    // Browser-wasm feature-detected variants. The baseline outputName.wasm is
    // now built (above). For each declared variant, recompile the entire build
    // graph with the variant's extra codegen flags and drop the result next to
    // the baseline as outputName.<label>.wasm. Relaxed-SIMD (and friends) is
    // per-translation-unit codegen, not a link switch, so a full rebuild — incl.
    // dep libs and the std PCM — is the only correct way to produce it.
    //
    // Guard: only fires on the top-level config that *declared* wasmVariants
    // (deps leave it empty) and never on a variant pass itself (those carry
    // wasmVariantFlags), so there's no recursion. Skipped on build error.
    if (buildResult.result.empty() && config.target.starts_with("wasm32") && config.type == ConfigurationType::Executable && !config.wasmVariants.empty() && config.wasmVariantFlags.empty()) {
        fs::path baselineBin = config.BinDir();

        // The whole transitive graph, so the variant flags reach every TU.
        std::vector<Configuration*> graph;
        {
            std::unordered_set<Configuration*> graphSeen;
            std::function<void(Configuration*)> collect = [&](Configuration* c) {
                if (!c || !graphSeen.insert(c).second) return;
                graph.push_back(c);
                for (Configuration* dep : c->dependencies) collect(dep);
            };
            collect(&config);
        }

        for (const WasmVariant& variant : config.wasmVariants) {
            // A labelless or flagless "variant" is just the baseline under
            // another name — nothing extra to compile.
            if (variant.label.empty() || variant.flags.empty()) continue;

            Progress::Task task(std::format("Building wasm variant {} ({})", variant.label, config.outputName));

            for (Configuration* c : graph) c->wasmVariantFlags = variant.flags;
            fs::path variantBin = config.BinDir();

            std::unordered_map<fs::path, std::shared_future<BuildResult>> variantDeps;
            std::mutex variantMutex;
            BuildResult vr = Build(config, variantDeps, variantMutex);

            for (Configuration* c : graph) c->wasmVariantFlags.clear();

            if (!vr.result.empty()) {
                buildResult.result = std::format("wasm variant '{}' build failed: {}", variant.label, vr.result);
                break;
            }

            std::error_code ec;
            fs::path src = variantBin / (std::format("{}.wasm", config.outputName));
            fs::path dst = baselineBin / std::format("{}.{}.wasm", config.outputName, variant.label);
            fs::copy_file(src, dst, fs::copy_options::overwrite_existing, ec);
            if (ec) {
                buildResult.result = std::format("copy wasm variant '{}' {} -> {}: {}", variant.label, src.string(), dst.string(), ec.message());
                break;
            }
        }
    }

    return buildResult;
}

void Crafter::EnableWasiBrowserRuntime(Configuration& cfg) {
    fs::path runtimeDir = GetCrafterBuildHome() / "wasi-runtime";
    fs::path runtimeJs = runtimeDir / "runtime.js";
    fs::path htmlTemplate = runtimeDir / "index.html.in";
    if (!fs::exists(runtimeJs) || !fs::exists(htmlTemplate)) {
        throw std::runtime_error(std::format("wasi-runtime assets missing under {} (set CRAFTER_BUILD_HOME or reinstall)", runtimeDir.string()));
    }

    fs::path htmlOutDir = cfg.path / "build" / "wasi-runtime" / cfg.name;
    fs::create_directories(htmlOutDir);
    fs::path htmlPath = htmlOutDir / "index.html";

    // Walk the dep graph for env-style JS bridges that need to load BEFORE
    // runtime.js so they can populate `window.crafter_webbuild_env`. Any
    // `*.js` entry in a (transitive) dep's `cfg.files` qualifies — the
    // file is already going to be copied into the consumer's bin dir, we
    // just need its basename for a `<script src=...>` tag.
    std::vector<std::string> envScripts;
    std::unordered_set<Configuration*> seen;
    std::function<void(Configuration*)> walk = [&](Configuration* c) {
        if (!c || !seen.insert(c).second) return;
        for (const fs::path& f : c->files) {
            if (f.extension() == ".js" && f.filename() != "runtime.js") {
                std::string name = f.filename().string();
                if (std::find(envScripts.begin(), envScripts.end(), name) == envScripts.end()) {
                    envScripts.push_back(std::move(name));
                }
            }
        }
        for (Configuration* dep : c->dependencies) walk(dep);
    };
    walk(&cfg);

    // Per-build cache-busting token. Stamped onto every script src + the
    // wasm URL so a regular browser reload sees fresh files even though
    // the dev server (python -m http.server) sends no Cache-Control
    // headers. Using ms-since-epoch is enough to be unique per build
    // without invoking any version-control machinery.
    const std::string buildId = std::to_string(std::chrono::duration_cast<std::chrono::milliseconds>(std::chrono::system_clock::now().time_since_epoch()).count());

    std::string envScriptTags;
    for (const std::string& name : envScripts) {
        envScriptTags += std::format("        <script src=\"{}?v={}\" type=\"module\"></script>\n", name, buildId);
    }

    // Walk the dep graph again for non-JS assets — these get pre-loaded by
    // runtime.js into an in-memory VFS so the wasm's std::ifstream et al.
    // can actually read them (the wasi-runtime in this repo otherwise
    // stubs every fd syscall to zero).
    //
    // The manifest lists *relative paths* (e.g. "assets/Inter.ttf") so
    // runtime.js's fetch() resolves against the bin-dir layout the asset
    // copy step actually emits. The VFS is keyed by basename — path_open
    // strips to basename on lookup, so subdir layouts collapse on the
    // wasm side. Basename collisions across subdirs aren't supported on
    // the wasi runtime today; if two assets share a basename, the last
    // one preloaded wins. Avoid collisions in the source tree.
    auto compressedExt = [](const fs::path& src) -> std::optional<std::string> {
        std::string ext = src.extension().string();
        for (char& c : ext) c = static_cast<char>(std::tolower(static_cast<std::uint8_t>(c)));
        if (ext == ".png" || ext == ".tga" || ext == ".jpg" || ext == ".jpeg" || ext == ".bmp") {
            return std::string(".ctex");
        }
        if (ext == ".obj") return std::string(".cmesh");
        return std::nullopt;
    };
    auto compressedRel = [&](const fs::path& rel) -> fs::path {
        if (auto ext = compressedExt(rel)) {
            fs::path out = rel;
            out.replace_extension(*ext);
            return out;
        }
        return rel;
    };
    std::vector<std::string> assetFiles;
    auto pushUnique = [&](std::string name) {
        if (name.empty()) return;
        if (std::find(assetFiles.begin(), assetFiles.end(), name) == assetFiles.end()) {
            assetFiles.push_back(std::move(name));
        }
    };
    seen.clear();
    std::function<void(Configuration*)> walkAssets = [&](Configuration* c) {
        if (!c || !seen.insert(c).second) return;
        for (const fs::path& f : c->files) {
            std::string ext = f.extension().string();
            if (ext == ".js" || ext == ".html") continue;
            if (f.filename() == "runtime.js") continue;
            // cfg.files lands flat next to the .wasm by `name = filename()`.
            pushUnique(f.filename().string());
        }
        // cfg.assets — mirror the bin-dir layout the build emits: a
        // directory entry becomes <topName>/<rel inside dir>, single
        // files land flat at the bin root. .png/.obj are compressed in
        // place; everything else passes through under its original name.
        for (const fs::path& a : c->assets) {
            if (fs::is_directory(a)) {
                const fs::path topName = a.filename();
                std::error_code ec;
                for (const auto& entry : fs::recursive_directory_iterator(a, ec)) {
                    if (ec) break;
                    if (!entry.is_regular_file()) continue;
                    fs::path rel = fs::relative(entry.path(), a);
                    pushUnique((topName / compressedRel(rel)).generic_string());
                }
            } else {
                pushUnique(compressedRel(a.filename()).generic_string());
            }
        }
        for (Configuration* dep : c->dependencies) walkAssets(dep);
    };
    walkAssets(&cfg);

    fs::path manifestPath = htmlOutDir / "files.json";
    {
        std::ofstream m(manifestPath);
        m << "[";
        for (std::size_t i = 0; i < assetFiles.size(); ++i) {
            if (i) m << ",";
            m << "\"" << assetFiles[i] << "\"";
        }
        m << "]";
    }

    // Variant manifest. runtime.js fetches this, runs each entry's probes in
    // order, and instantiates the first whose probes all pass — so the
    // preferred (most feature-rich) variants come first and the baseline last
    // as the fallback. Every entry carries WasmBaselineProbes besides its own:
    // every file is built with the baseline flags, so an engine without
    // exception handling can run none of them, and runtime.js tells it so
    // instead of failing to compile the module. A variant with a non-empty
    // label maps to outputName.<label>.wasm (produced by Build's variant
    // driver); the baseline maps to outputName.wasm. Even with no declared
    // variants we still emit a one-entry manifest so the runtime has a
    // single, uniform code path.
    auto jsonEscape = [](std::string_view s) {
        std::string out;
        for (char c : s) {
            if (c == '"' || c == '\\') out += '\\';
            out += c;
        }
        return out;
    };
    fs::path variantsPath = htmlOutDir / "variants.json";
    {
        std::ofstream v(variantsPath);
        v << "[";
        bool first = true;
        auto emit = [&](const std::string& label, const std::vector<std::string>& ownProbes) {
            if (!first) v << ",";
            first = false;
            std::string url = label.empty()
                ? std::format("{}.wasm", cfg.outputName)
                : std::format("{}.{}.wasm", cfg.outputName, label);
            std::vector<std::string> probes = ownProbes;
            probes.insert(probes.end(), WasmBaselineProbes.begin(), WasmBaselineProbes.end());
            v << "{\"label\":\"" << jsonEscape(label) << "\""
              << ",\"url\":\"" << jsonEscape(url) << "\""
              << ",\"probes\":[";
            for (std::size_t i = 0; i < probes.size(); ++i) {
                if (i) v << ",";
                v << "\"" << jsonEscape(probes[i]) << "\"";
            }
            v << "]}";
        };
        for (const WasmVariant& variant : cfg.wasmVariants) {
            if (variant.label.empty()) continue; // baseline emitted below
            emit(variant.label, variant.probes);
        }
        emit("", {}); // baseline fallback, always last
        v << "]";
    }

    std::ifstream in(htmlTemplate);
    std::stringstream buf;
    buf << in.rdbuf();
    std::string html = buf.str();
    html = std::regex_replace(html, std::regex(R"(\{\{WASM\}\})"), std::format("{}.wasm", cfg.outputName));
    html = std::regex_replace(html, std::regex(R"(\{\{ENV_SCRIPTS\}\})"), envScriptTags);
    html = std::regex_replace(html, std::regex(R"(\{\{BUILDID\}\})"), buildId);
    std::ofstream out(htmlPath);
    out << html;
    out.close();

    cfg.files.push_back(runtimeJs);
    cfg.files.push_back(htmlPath);
    cfg.files.push_back(manifestPath);
    cfg.files.push_back(variantsPath);
}

void Crafter::EnableWasiRelaxedSimdVariant(Configuration& cfg) {
    for (const WasmVariant& v : cfg.wasmVariants) {
        if (v.label == "relaxed-simd") return; // idempotent
    }
    cfg.wasmVariants.push_back(WasmVariant{
        .label = "relaxed-simd",
        .flags = {"-mrelaxed-simd"},
        .probes = {"relaxed-simd"},
    });
}

std::string Crafter::HostTarget() {
    return GetToolchain().hostTriple;
}

std::string Crafter::NormalizeTarget(std::string_view triple) {
    // <arch>-<vendor>-<os>-<env>: drop the vendor. A three-part triple only
    // carries one when its middle part is a vendor name rather than an OS
    // (x86_64-unknown-wasip1 yes, x86_64-linux-gnu no).
    std::vector<std::string_view> parts;
    for (std::size_t begin = 0;;) {
        std::size_t dash = triple.find('-', begin);
        parts.push_back(dash == std::string_view::npos ? triple.substr(begin) : triple.substr(begin, dash - begin));
        if (dash == std::string_view::npos) break;
        begin = dash + 1;
    }
    const bool hasVendor = parts.size() == 4 || (parts.size() == 3 && (parts[1] == "unknown" || parts[1] == "pc"));
    if (hasVendor) parts.erase(parts.begin() + 1);
    std::string out;
    for (std::string_view part : parts) {
        if (!out.empty()) out += '-';
        out += part;
    }
    return out;
}

bool Crafter::SameTarget(std::string_view a, std::string_view b) {
    return a == b || NormalizeTarget(a) == NormalizeTarget(b);
}

bool Crafter::ArgQuery::Has(std::string_view flag) const {
    for (std::string_view a : args) if (a == flag) return true;
    return false;
}

std::optional<std::string> Crafter::ArgQuery::Get(std::string_view prefix) const {
    for (std::string_view a : args) {
        if (a.starts_with(prefix)) return std::string(a.substr(prefix.size()));
    }
    return std::nullopt;
}

ArgQuery Crafter::ApplyStandardArgs(Configuration& cfg, std::span<const std::string_view> args) {
    if (const char* envMarch = std::getenv("CRAFTER_BUILD_MARCH"); envMarch && *envMarch) {
        cfg.march = envMarch;
    }
    if (const char* envMtune = std::getenv("CRAFTER_BUILD_MTUNE"); envMtune && *envMtune) {
        cfg.mtune = envMtune;
    }
    bool sawLib = false;
    bool sawShared = false;
    for (std::string_view a : args) {
        if (a == "--debug") cfg.debug = true;
        else if (a == "--lib") sawLib = true;
        else if (a == "--shared") sawShared = true;
        else if (a.starts_with("--target=")) cfg.target = std::string(a.substr(std::string_view("--target=").size()));
        else if (a.starts_with("--march=")) cfg.march = std::string(a.substr(std::string_view("--march=").size()));
        else if (a.starts_with("--mtune=")) cfg.mtune = std::string(a.substr(std::string_view("--mtune=").size()));
        else if (a.starts_with("--sysroot=")) cfg.sysroot = std::string(a.substr(std::string_view("--sysroot=").size()));
        // Anything else is the project's own flag. Its effect on the output is
        // opaque to the framework, so it has to key into VariantId or two flag
        // settings share a bin dir and leave a bundle matching neither.
        else cfg.projectArgs.emplace_back(a);
    }
    // Sorted and deduplicated so the identity depends on the set of flags, not
    // on how they were ordered or repeated.
    std::ranges::sort(cfg.projectArgs);
    cfg.projectArgs.erase(std::ranges::unique(cfg.projectArgs).begin(), cfg.projectArgs.end());
    if (sawLib && cfg.type == ConfigurationType::Executable) cfg.type = ConfigurationType::LibraryStatic;
    if (sawShared && cfg.type == ConfigurationType::LibraryStatic) cfg.type = ConfigurationType::LibraryDynamic;
    // WASI sysroot autodetect, applied at config-load time so the VariantId
    // includes it. (Build() also runs this once more for callers that bypassed
    // ApplyStandardArgs, but doing it here makes dep PcmDirs consistent
    // between the consumer's command-construction and the dep's own build.)
    if (cfg.sysroot.empty() && cfg.target.starts_with("wasm32")) {
        cfg.sysroot = GetToolchain().wasiSysroot.string();
    }
    return ArgQuery{args};
}

std::vector<fs::path> Crafter::CleanProject(const fs::path& projectFile) {
    fs::path projectDir = fs::absolute(projectFile).lexically_normal().parent_path();
    std::vector<fs::path> removed;
    for (std::string_view name : { "bin", "build" }) {
        fs::path dir = projectDir / name;
        std::error_code ec;
        if (!fs::is_directory(dir, ec)) continue;
        if (fs::remove_all(dir, ec) == static_cast<std::uintmax_t>(-1) || ec) {
            throw std::runtime_error(std::format("could not remove {}: {}", dir.string(), ec.message()));
        }
        removed.push_back(std::move(dir));
    }
    return removed;
}

static void PrintVersion() {
    std::println("crafter-build {}", CrafterBuildVersion());
    const Toolchain& tc = GetToolchain();
    if (!tc.error.empty()) {
        std::println("compiler: {}", tc.error);
        return;
    }
    std::println("compiler {} ({})", tc.clangVersion, tc.clangxx.string());
    if (tc.libcxxVersion != 0) {
        // A sysroot on another libc++ release builds only when its std
        // module source is in the sysroot or among these; printed here
        // because that is the first question when such a build fails.
        std::vector<std::string> shipped;
        std::error_code ec;
        for (const fs::directory_entry& entry : fs::directory_iterator(tc.stdModulesDir, ec)) {
            if (fs::exists(entry.path() / "std.cppm")) shipped.push_back(entry.path().filename().string());
        }
        std::ranges::sort(shipped);
        std::string also;
        for (const std::string& release : shipped) also += std::format(", {}", release);
        std::println("libc++ {}{}", LibcxxVersionString(tc.libcxxVersion), also.empty() ? std::string() : std::format(" (std module sources for sysroots also for{})", also.substr(1)));
    }
    std::println("host {}", tc.hostTriple);
}

static void PrintHelp(std::string_view argv0) {
    std::println(
R"(Usage:
  {0} [options] [-- project-args...]    Build the project in the current directory
  {0} test [test-options] [globs...]    Build and run the project's tests
  {0} lint [lint-options] [globs...]    Run the project's lint rules over its sources
  {0} format [format-options] [globs...]  Apply the project's transform rules (rewrites files)
  {0} run [script [args...]]            Run a script the project defines, or list them
  {0} clean                             Delete the project's bin/ and build/ trees
  {0} help | -h | --help                Show this help
  {0} --version                         Print the version and the compiler in use

Loads ./project.cpp (override with --project=<path>), compiles it to a shared
object, and invokes its CrafterBuildProject() to obtain a Configuration that
drives the build. Outputs land at bin/<name>-<target>-<march>/, intermediates
at build/<name>-<target>-<march>/.

Build options:
  -r                        Run the produced executable after a successful build
                            (host targets only; libraries cannot be run).
  -v, --verbose             Verbose progress output.
  -q, --quiet               Suppress progress output.
  --project=<path>          Path to the project file (default: ./project.cpp).
  --                        Ends this tool's options. Every later word is a
                            project arg, even one that looks like an option or
                            a verb; after test, lint or format, a glob; after
                            run, the script's name and then its args.

Test options (after the `test` subcommand):
  --list                    Enumerate matching tests without running them.
  --jobs=<N>                Parallel job count (default: hardware_concurrency).
  --timeout=<seconds>       Per-test timeout override.
  --runner=<spec>           Override the test runner for this run. Specs:
                              local
                              cmd:<command>             (e.g. cmd:wine)
  --target=<triple>         Filter to tests whose cfg.target matches. Default:
                            sweep across every distinct target declared by the
                            project's tests plus the host triple.
  <glob>                    One or more name globs to filter tests (e.g. 'Unit*').

Lint options (after the `lint` subcommand):
  --list                    Enumerate matching lint rules without running them.
  --no-ast                  Skip rules that need an AST instead of building the
                            module PCMs they require.
  <glob>                    One or more name globs to filter rules (e.g. 'spdx*').

  Lint rules are defined in project.cpp via cfg.AddLintRule(name, callback) —
  C++ callbacks run once per source file. No rules ship by default.

  cfg.AddAstLintRule registers a rule that reads ctx.Decls(), clang's view of
  the declarations in the file. Those need the module PCMs, which the run
  builds if they are missing; a file whose AST cannot be produced is an error,
  never a silent pass. --no-ast skips them instead.

Format options (after the `format` subcommand):
  --check                   Dry run: list files that would change, exit 1 if any.
  --list                    Enumerate matching rules without running them.
  --no-ast                  Skip rules that need an AST (see `lint --no-ast`).
  <glob>                    One or more name globs to filter rules.

  Rules are shared with lint — a rule that calls ctx.SetContent is a
  transform. `format` rewrites changed files in place; `lint` reports the
  same transforms as would-reformat findings without writing.

Run (after the `run` subcommand):
  <script> [args...]        Run the named script. Everything after the name is
                            handed to the script untouched, including what
                            looks like an option of crafter-build itself, so
                            -v, -q, --project= and project args go before it.
  --list                    List the project's scripts. A bare `run` does too.

  Scripts are defined in project.cpp, as entries of cfg.scripts:
    cfg.scripts.push_back({{"docs", [](Crafter::ScriptContext& ctx) {{
        return ctx.Run("python3 tools/gen-docs.py");
    }}}});
  The callback returns the exit status. ctx.Run runs a shell command with the
  terminal attached and returns its status; ctx.args holds the arguments and
  ctx.projectDir the project's directory. Commands run in the directory
  crafter-build was started from. Only the scripts of the project being run
  are available, never a dependency's.

Clean (after the `clean` subcommand):
  Removes bin/ and build/ next to the project file. Does not load project.cpp,
  so it works when the project itself no longer compiles. Every target, variant
  and dependency artifact under those trees goes with it.

AGENTS.md:
  When an AGENTS.template.md sits beside the project file, a build and a test
  run write AGENTS.md from it, with a section holding the AGENTS.consumer.md
  each dependency ships beside its project.cpp, and only when the text changes.
  Commit the template and keep AGENTS.md out of version control. An AGENTS.md
  no build wrote is never replaced, and without a template AGENTS.md is left
  alone. cfg.dependencyNotes picks the dependencies: Transitive (the default),
  Direct, or None.

Project args:
  Any flag not consumed above is forwarded verbatim to CrafterBuildProject as
  part of its `args` span. Project-specific flags (e.g. --target=, custom
  feature toggles) live there. Flags ApplyStandardArgs does not itself
  interpret are folded into the variant hash, so switching one lands in its own
  bin/ and build/ directory instead of overwriting the other setting's.

Environment:
  CRAFTER_BUILD_MARCH                  Override -march (default: native).
  CRAFTER_BUILD_MTUNE                  Override -mtune (default: native).
  CRAFTER_BUILD_RUNNER_<TARGET>        Default test runner for a target triple.
                                       Replace '-' and '.' with '_' in the
                                       triple. CLI --runner= overrides this.
  CRAFTER_BUILD_LLVM_DIR               LLVM prefix to use instead of a toolchain
                                       installed beside crafter-build or PATH.
  CRAFTER_BUILD_LIBCXX_DIR             libc++ install to compile and link against
                                       instead of the compiler's own.
  CRAFTER_BUILD_LIBCLANG               Exact libclang to load for lint.
  CRAFTER_BUILD_WASI_SYSROOT           WASI sysroot for wasm32 targets.
  CRAFTER_MINGW_DIR                    mingw-w64 prefix (holding x86_64-w64-mingw32/
                                       and lib/gcc/). Default: the mingw gcc on
                                       PATH; in the Flatpak, the host's /usr when
                                       it has mingw-w64. Of a prefix that holds a
                                       Linux system too, such as /usr, clang sees
                                       only those directories.
  CRAFTER_BUILD_HOME                   Directory holding the module sources.

Exit status:
  0  success / all non-skipped tests passed / lint clean / format applied
  1  build failure, one or more tests failed, lint findings, no rules defined,
     format write errors, or `format --check` found files that would change
  `run` exits with the status its script returned, and with 1 when there is no
  such script, when the script throws, or when it returns a value outside 0..255
)", argv0);
}

// lint-disable-next-line no-char-pointer
std::int32_t Crafter::Run(std::int32_t argc, char** argv) {
    try {
        std::string_view argv0 = argc > 0 ? argv[0] : "crafter-build";
        fs::path projectFile = "./project.cpp";
        std::vector<std::string_view> projectArgs;
        projectArgs.reserve(argc);

        bool runTests = false;
        bool runLint = false;
        bool runFormat = false;
        bool runClean = false;
        bool runScript = false;
        bool runAfterBuild = false;
        RunTestsOptions testOpts;
        RunLintOptions lintOpts;
        RunScriptOptions scriptOpts;
        Progress::Verbosity verbosity = Progress::Verbosity::Default;
        // Set by `--`: every later word is an operand of the verb, never an
        // option or a verb of this tool.
        bool operandsOnly = false;

        for (std::int32_t i = 1; i < argc; ++i) {
            std::string_view arg = argv[i];
            // The two `run` branches come before everything else on purpose.
            // What follows a script's name belongs to the script, whatever
            // it looks like: `run package --help` must not print this
            // tool's help, `run package clean` must not delete build/, and
            // none of it may reach projectArgs, where it would change the
            // variant hash and so the directory the project builds into.
            if (scriptOpts.named) {
                scriptOpts.args.emplace_back(arg);
            } else if (runScript && (operandsOnly || !arg.starts_with("-"))) {
                // The first word after `run`, even one that is a verb
                // elsewhere. Options before it keep their usual meaning.
                scriptOpts.name = arg;
                scriptOpts.named = true;
            } else if (operandsOnly) {
                if (runTests) {
                    testOpts.globs.emplace_back(arg);
                } else if (runLint || runFormat) {
                    lintOpts.globs.emplace_back(arg);
                } else {
                    projectArgs.push_back(arg);
                }
            } else if (arg == "--") {
                // Ends this tool's options and is never forwarded itself. It
                // used to land in projectArgs as a word of its own, giving the
                // project a variant hash of its own, and every sibling project
                // that inherits the args one as well.
                operandsOnly = true;
            } else if (arg == "--version") {
                // Answered here, before the project file is looked for, so
                // it works in any directory and is never forwarded to
                // project.cpp as an unknown argument.
                PrintVersion();
                return 0;
            } else if (arg == "-h" || arg == "--help" || (!runTests && !runLint && !runFormat && arg == "help")) {
                PrintHelp(argv0);
                return 0;
            } else if (!runLint && !runFormat && !runClean && arg == "test") {
                runTests = true;
            } else if (!runTests && !runFormat && !runClean && arg == "lint") {
                runLint = true;
            } else if (!runTests && !runLint && !runFormat && arg == "clean") {
                runClean = true;
            } else if (!runTests && !runLint && !runClean && arg == "format") {
                runFormat = true;
                lintOpts.mode = LintMode::Apply;
            } else if (!runTests && !runLint && !runFormat && !runClean && arg == "run") {
                runScript = true;
            } else if (runScript && arg == "--list") {
                scriptOpts.listOnly = true;
            } else if (runFormat && arg == "--check") {
                lintOpts.mode = LintMode::Check;
            } else if (arg == "-r") {
                runAfterBuild = true;
            } else if (arg == "-v" || arg == "--verbose") {
                verbosity = Progress::Verbosity::Verbose;
            } else if (arg == "-q" || arg == "--quiet") {
                verbosity = Progress::Verbosity::Quiet;
            } else if (arg.starts_with("--project=")) {
                projectFile = arg.substr(std::string_view("--project=").size());
            } else if (runTests && arg.starts_with("--jobs=")) {
                testOpts.jobs = std::stoi(std::string(arg.substr(std::string_view("--jobs=").size())));
            } else if (runTests && arg.starts_with("--timeout=")) {
                testOpts.timeoutOverride = std::chrono::seconds(std::stoi(std::string(arg.substr(std::string_view("--timeout=").size()))));
            } else if (runTests && arg == "--list") {
                testOpts.listOnly = true;
            } else if (runTests && arg.starts_with("--runner=")) {
                testOpts.runnerOverride = std::string(arg.substr(std::string_view("--runner=").size()));
            } else if (runTests && !arg.starts_with("-")) {
                testOpts.globs.emplace_back(arg);
            } else if ((runLint || runFormat) && arg == "--list") {
                lintOpts.listOnly = true;
            } else if ((runLint || runFormat) && arg == "--no-ast") {
                lintOpts.noAst = true;
            } else if ((runLint || runFormat) && !arg.starts_with("-")) {
                lintOpts.globs.emplace_back(arg);
            } else {
                projectArgs.push_back(arg);
            }
        }

        Progress::SetVerbosity(verbosity);

        // The test run is target-scoped: only tests whose cfg.target equals
        // testOpts.targetFilter are included. Default = host triple, so a
        // bare `crafter-build test` runs everything that targets host.
        for (auto& a : projectArgs) {
            if (a.starts_with("--target=")) {
                testOpts.targetFilter = std::string(a.substr(std::string_view("--target=").size()));
            }
        }

        if (!fs::exists(projectFile)) {
            std::println(std::cerr, "No project file at {}", projectFile.string());
            return 1;
        }

        // Ahead of LoadProject on purpose — see CleanProject.
        if (runClean) {
            std::vector<fs::path> removed = CleanProject(projectFile);
            if (removed.empty()) {
                std::println("Nothing to clean");
            } else {
                for (const fs::path& dir : removed) std::println("Removed {}", dir.string());
            }
            return 0;
        }

        Configuration config = LoadProject(projectFile, projectArgs);
        SetParentProject(&config);

        if (runScript) {
            scriptOpts.projectFile = fs::absolute(projectFile).lexically_normal();
            return RunScript(config, scriptOpts);
        }

        if (runLint || runFormat) {
            // lexically_normal: fs::absolute keeps a "./" component, which
            // would leak into displayed paths and the project-root derivation.
            lintOpts.projectFile = fs::absolute(projectFile).lexically_normal();
            LintSummary lintSummary = RunLint(config, lintOpts);
            if (!runFormat) return lintSummary.Clean() ? 0 : 1;
            if (lintSummary.noRulesDefined || lintSummary.errors > 0) return 1;
            // Apply: formatting files is success (gofmt convention).
            // Check: a would-change file is the CI failure signal.
            return lintOpts.mode == LintMode::Check && !lintSummary.changedFiles.empty() ? 1 : 0;
        }

        // Builds and test runs only: lint and `format --check` promise to
        // write nothing, `format` rewrites the project's sources and nothing
        // else, `run` is for chores and `test --list` only lists. Here,
        // before compiling, because loading has just fetched every
        // dependency, so the notes are current, and an agent fixing a build
        // that fails needs them.
        if (!testOpts.listOnly) UpdateAgentsMd(config, projectFile);

        if (runTests) {
            TestSummary summary = RunTests(config, testOpts, projectArgs);
            return summary.AllPassed() ? 0 : 1;
        }

        std::unordered_map<fs::path, std::shared_future<BuildResult>> depResults;
        std::mutex depMutex;
        BuildResult result = Build(config, depResults, depMutex);

        if (!result.result.empty()) {
            Progress::Clear();
            std::println(std::cerr, "{}", result.result);
            return 1;
        }

        Progress::Finalize();

        if (runAfterBuild) {
            if (config.type != ConfigurationType::Executable) {
                std::println(std::cerr, "-r: cannot run a library");
                return 1;
            }
            fs::path dir = config.BinDir();
            fs::path artifact = fs::absolute(ExpectedOutput(config));
            fs::path absDir = fs::absolute(dir);

            // wasm targets need either a wasm runtime (wasi-cli) or an HTTP
            // server (browser build with index.html). std::system on the
            // .wasm path goes nowhere useful — replace with detection.
            if (config.target.starts_with("wasm32")) {
                const bool browserBuild = fs::exists(absDir / "index.html");
                auto have = [](std::string_view exe) {
                    std::string probe = std::format("command -v {} > /dev/null 2>&1", exe);
                    return std::system(probe.c_str()) == 0;
                };
                if (browserBuild) {
                    // Probe-bind to find a free port starting at 8080 — if the
                    // user has another dev server running we shift up rather
                    // than letting caddy/python exit with EADDRINUSE.
                    auto findFreePort = [](std::int32_t basePort, std::int32_t span) -> std::int32_t {
                        using Sock = std::int32_t;
                        const Sock invalid = -1;
                        auto closesock = [](Sock s){ ::close(s); };
                        for (std::int32_t p = basePort; p < basePort + span; ++p) {
                            Sock s = ::socket(AF_INET, SOCK_STREAM, 0);
                            if (s == invalid) return basePort;
                            sockaddr_in addr{};
                            addr.sin_family = AF_INET;
                            addr.sin_addr.s_addr = htonl(INADDR_ANY);
                            addr.sin_port = htons(static_cast<std::uint16_t>(p));
                            bool ok = ::bind(s, reinterpret_cast<sockaddr*>(&addr), sizeof(addr)) == 0;
                            closesock(s);
                            if (ok) return p;
                        }
                        return basePort;
                    };
                    const std::int32_t port = findFreePort(8080, 16);
                    // Cross-origin isolation: the browser coarsens
                    // performance.now() (and chrono::steady_clock under wasi)
                    // to ~0.1ms unless the response carries COOP/COEP, which
                    // floors the --timing overlay's sub-ms phase counters to
                    // zero. Emitting same-origin / require-corp drops the
                    // resolution to ~5µs and also unlocks SharedArrayBuffer
                    // for any future threading work. CORP keeps the local
                    // asset fetches passing under require-corp.
                    auto writeFile = [](const fs::path& p, std::string_view contents) {
                        std::ofstream f(p, std::ios::binary | std::ios::trunc);
                        f.write(contents.data(), static_cast<std::streamsize>(contents.size()));
                    };
                    std::string cmd;
                    std::string_view picked;
                    bool isolated = false;
                    if (have("caddy")) {
                        picked = "caddy";
                        isolated = true;
                        // caddy file-server has no --header flag; write a
                        // Caddyfile next to the build output. Adapter is
                        // inferred from the .caddyfile extension when run
                        // via `caddy run`.
                        fs::path cf = absDir / "Caddyfile.coi";
                        writeFile(cf, std::format(
                            ":{} {{\n"
                            "    root * {}\n"
                            "    header Cross-Origin-Opener-Policy   \"same-origin\"\n"
                            "    header Cross-Origin-Embedder-Policy \"require-corp\"\n"
                            "    header Cross-Origin-Resource-Policy \"same-origin\"\n"
                            "    header Cache-Control                \"no-store\"\n"
                            // Every EnableWasiBrowserRuntime consumer is a
                            // single-page wasm app by construction: the
                            // generated index.html ships an empty <body> and
                            // the module builds the DOM at runtime. So an app
                            // that routes on window.location has no file on
                            // disk for any path but "/", and a bare
                            // file_server 404s every deep link, refresh and
                            // shared URL during development.
                            //
                            // try_files falls through to index.html only for
                            // paths that are not real files, so static assets
                            // still serve normally and a genuinely missing
                            // asset becomes a visible wrong-content-type
                            // rather than a silent 404 the app can't see.
                            "    try_files {{path}} /index.html\n"
                            "    file_server\n"
                            "}}\n",
                            port, absDir.string()));
                        cmd = std::format("caddy run --config {} --adapter caddyfile", cf.string());
                    } else if (have("python3") || have("python")) {
                        std::string_view py = have("python3") ? "python3" : "python";
                        picked = py;
                        isolated = true;
                        // Inline a tiny SimpleHTTPRequestHandler subclass
                        // that appends the COI headers on every response.
                        // Lives in absDir so the user can re-run it manually
                        // (`python3 absDir/.serve-coi.py 8080`).
                        fs::path sp = absDir / ".serve-coi.py";
                        writeFile(sp,
                            "import http.server, socketserver, sys, os\n"
                            "class H(http.server.SimpleHTTPRequestHandler):\n"
                            "    def end_headers(self):\n"
                            "        self.send_header('Cross-Origin-Opener-Policy', 'same-origin')\n"
                            "        self.send_header('Cross-Origin-Embedder-Policy', 'require-corp')\n"
                            "        self.send_header('Cross-Origin-Resource-Policy', 'same-origin')\n"
                            "        self.send_header('Cache-Control', 'no-store')\n"
                            "        super().end_headers()\n"
                            "socketserver.TCPServer.allow_reuse_address = True\n"
                            "port = int(sys.argv[1]) if len(sys.argv) > 1 else 8080\n"
                            "os.chdir(os.path.dirname(os.path.abspath(__file__)))\n"
                            "with socketserver.TCPServer(('', port), H) as s:\n"
                            "    s.serve_forever()\n");
                        cmd = std::format("{} {} {}", py, sp.string(), port);
                    } else if (have("php")) {
                        picked = "php";
                        // php -S supports a router script — emit one that
                        // sets COI headers then delegates to the built-in
                        // static-file handler by returning false.
                        fs::path rp = absDir / ".serve-coi.php";
                        writeFile(rp,
                            "<?php\n"
                            "header('Cross-Origin-Opener-Policy: same-origin');\n"
                            "header('Cross-Origin-Embedder-Policy: require-corp');\n"
                            "header('Cross-Origin-Resource-Policy: same-origin');\n"
                            "header('Cache-Control: no-store');\n"
                            "return false;\n");
                        isolated = true;
                        cmd = std::format("php -S 0.0.0.0:{} -t {} {}", port, absDir.string(), rp.string());
                    } else if (have("ruby")) {
                        picked = "ruby";
                        cmd = std::format("ruby -run -e httpd {} -p{}", absDir.string(), port);
                    } else if (have("busybox")) {
                        picked = "busybox httpd";
                        cmd = std::format("busybox httpd -f -p {} -h {}", port, absDir.string());
                    } else if (have("npx")) {
                        picked = "npx http-server";
                        cmd = std::format("npx --yes http-server {} -p {} --silent", absDir.string(), port);
                    } else {
                        std::println(std::cerr, "-r wasm: no HTTP server found in PATH. Install one of: " "caddy, python3, python, php, ruby, busybox, npx (Node.js).");
                        return 1;
                    }
                    std::println("listening on port :{}", port);
                    if (!isolated) {
                        std::println(std::cerr, "warning: {} does not emit COOP/COEP — performance.now() will be coarse " "(~0.1ms). Install caddy, python3, or php for cross-origin isolation.", picked);
                    }
                    // Silence the backend's own banner/request logs so the
                    // experience is identical regardless of which server is
                    // picked — the line above is the only output.
                    cmd += " > /dev/null 2>&1";
                    return std::system(cmd.c_str()) == 0 ? 0 : 1;
                }
                // wasi-cli wasm — needs a standalone runtime.
                if (have("wasmtime")) {
                    return std::system(std::format("wasmtime {}", artifact.string()).c_str()) == 0 ? 0 : 1;
                }
                if (have("wasmer")) {
                    return std::system(std::format("wasmer run {}", artifact.string()).c_str()) == 0 ? 0 : 1;
                }
                std::println(std::cerr, "-r wasm: no wasm runtime found in PATH. Install wasmtime or wasmer, " "or call EnableWasiBrowserRuntime(cfg) in project.cpp for a browser build.");
                return 1;
            }

            // Run from the artifact's own directory so relative file opens
            // (shaders, assets copied alongside the exe via cfg.files) resolve
            // against the bin dir rather than the user's cwd. We exit the
            // process immediately after, so no cwd restore needed.
            fs::current_path(dir);
            return std::system(artifact.string().c_str()) == 0 ? 0 : 1;
        }

        return 0;
    } catch (const std::exception& e) {
        Progress::Clear();
        std::println(std::cerr, "{}", e.what());
        return 1;
    }
}