build.zig

const std = @import("std");
const vulkan_shaders = @import("build/vulkan_shaders.zig");
const slang_shaders = @import("build/slang_shaders.zig");

const version = "0.18.0";

// The module-creation layer lives in build/modules.zig; alias its public
// declarations so the step functions below read unqualified. build.zig stays
// the orchestrator: build steps, artifacts, and shader generation.
const build_mods = @import("build/modules.zig");
const DemoEntry = build_mods.DemoEntry;
const GlLibraries = build_mods.GlLibraries;
const BuildConfig = build_mods.BuildConfig;
const ProjectModules = build_mods.ProjectModules;
const selectDemoEntry = build_mods.selectDemoEntry;
const configureEglOffscreenModule = build_mods.configureEglOffscreenModule;
const createDemoVulkanPlatformModule = build_mods.createDemoVulkanPlatformModule;
const createEmbedVulkanModule = build_mods.createEmbedVulkanModule;
const createDemoVulkanTypesModule = build_mods.createDemoVulkanTypesModule;
const createEmbedGlModule = build_mods.createEmbedGlModule;
const createSupportModule = build_mods.createSupportModule;
const createSnailModuleFull = build_mods.createSnailModuleFull;
const createRasterModule = build_mods.createRasterModule;
const createSnailModule = build_mods.createSnailModule;
const parseBuildConfig = build_mods.parseBuildConfig;
const addSnailModule = build_mods.addSnailModule;
const addGameShaderSpirv = build_mods.addGameShaderSpirv;
const addGameShaderGl = build_mods.addGameShaderGl;

fn addCiCommandStep(
    b: *std.Build,
    name: []const u8,
    description: []const u8,
    mode: []const u8,
) void {
    const run = b.addSystemCommand(&.{"bash"});
    run.addFileArg(b.path("dev/ci.sh"));
    run.addArg(mode);
    run.has_side_effects = true;
    b.step(name, description).dependOn(&run.step);
}

fn addCiSteps(b: *std.Build) void {
    addCiCommandStep(b, "ci", "Run the complete Linux CI suite locally (enter nix-shell first)", "all");
    addCiCommandStep(b, "ci-tests", "Run formatting and public-module CI gates", "tests");
    addCiCommandStep(b, "ci-linux-gl", "Run GL, GLES, and CPU CI gates through llvmpipe", "linux-gl");
    addCiCommandStep(b, "ci-linux-vulkan", "Run Vulkan and game CI gates through lavapipe", "linux-vulkan");
    addCiCommandStep(b, "ci-linux-wgpu-wine", "Run WebGPU and Wine D3D11 CI gates", "linux-wgpu-wine");
    addCiCommandStep(b, "ci-windows-wine-smoke", "Smoke-test the prebuilt Windows CI artifacts under Wine", "windows-wine-smoke");
    addCiCommandStep(b, "ci-consumer-builds", "Build every release-mode consumer entry point", "consumer-builds");
    addCiCommandStep(b, "ci-cross", "Run cross-platform compile-only CI gates", "cross");
    addCiCommandStep(b, "ci-nix", "Build the Nix package CI derivation", "nix");
}

fn configureValgrindTest(test_exe: *std.Build.Step.Compile) void {
    test_exe.setExecCmd(&.{
        "valgrind",
        "--quiet",
        "--leak-check=full",
        "--show-leak-kinds=definite,possible",
        "--errors-for-leak-kinds=definite,possible",
        "--track-origins=yes",
        "--num-callers=32",
        "--suppressions=valgrind.supp",
        "--error-exitcode=99",
        null,
    });
}

fn addTestSteps(
    b: *std.Build,
    config: BuildConfig,
    modules: ProjectModules,
) void {
    const test_step = b.step("test", "Run the complete unit and shader-contract test suite");
    const core_test_step = b.step("test-core", "Run library and CPU-renderer tests without shader-generation tools");
    test_step.dependOn(core_test_step);

    // The committed src/snail/shader/reflection.zig is the toolchain-free
    // binding contract; this gate re-derives it from slangc and diffs, so it
    // cannot silently drift from the shaders. It needs slangc (already required
    // by `test`), so it hangs off `test`, never `test-core`. On drift, run
    // `zig build gen-shaders` and commit the updated reflection.zig.
    const check_reflection = b.addSystemCommand(&.{ "diff", "-u" });
    check_reflection.addFileArg(b.path("src/snail/shader/reflection.zig"));
    check_reflection.addFileArg(modules.reflection_generated);
    const check_reflection_step = b.step("check-reflection", "Verify the committed shader binding contract (src/snail/shader/reflection.zig) still matches slangc's reflection");
    check_reflection_step.dependOn(&check_reflection.step);
    test_step.dependOn(&check_reflection.step);
    const snail_tests = createSnailModuleFull(b, config.target, config.optimize, null, modules.assets, null);
    core_test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = snail_tests })).step);
    const raster_tests = createRasterModule(b, config.target, config.optimize, snail_tests, modules.assets, null, null);
    core_test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = raster_tests })).step);

    const public_api_tests = b.createModule(.{
        .root_source_file = b.path("dev/tests/public_renderer_api.zig"),
        .target = config.target,
        .optimize = config.optimize,
        .imports = &.{
            .{ .name = "snail", .module = snail_tests },
            .{ .name = "snail-raster", .module = raster_tests },
        },
    });
    core_test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = public_api_tests })).step);

    // The committed binding contract (`snail-shaders-reflection`) must compile
    // with NO shader toolchain, so this guard rides `test-core`, which runs
    // without slangc/naga. It regresses loudly if the reflection path ever
    // reacquires a shader-tool dependency.
    const reflection_contract_tests = b.createModule(.{
        .root_source_file = b.path("dev/tests/reflection_contract.zig"),
        .target = config.target,
        .optimize = config.optimize,
        .imports = &.{.{ .name = "snail_shaders", .module = modules.shaders_reflection }},
    });
    core_test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = reflection_contract_tests })).step);

    const public_shader_api_tests = b.createModule(.{
        .root_source_file = b.path("dev/tests/public_shader_api.zig"),
        .target = config.target,
        .optimize = config.optimize,
        .imports = &.{
            .{ .name = "snail", .module = snail_tests },
            .{ .name = "snail_shaders", .module = modules.shaders },
        },
    });
    test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = public_shader_api_tests })).step);

    // The generated-artifact contract tests live in the snail-shaders
    // module root (binding names, entry points, no #line leakage, ...).
    const shaders_tests = b.createModule(.{
        .root_source_file = modules.shaders_root,
        .target = config.target,
        .optimize = config.optimize,
    });
    test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = shaders_tests })).step);

    core_test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = modules.support })).step);

    // The dependency-free TGA pixel gate used by the Windows CI job.
    const pixelgate_tests = b.addTest(.{ .root_module = b.createModule(.{
        .root_source_file = b.path("dev/tools/pixelgate.zig"),
        .target = config.target,
        .optimize = config.optimize,
    }) });
    core_test_step.dependOn(&b.addRunArtifact(pixelgate_tests).step);

    const autohint_compare_test_module = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = config.optimize,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = modules.snail },
            .{ .name = "snail-raster", .module = modules.raster },
            .{ .name = "support", .module = modules.support },
        },
    });
    selectDemoEntry(b, autohint_compare_test_module, .autohint_compare);
    const autohint_compare_tests = b.addTest(.{ .root_module = autohint_compare_test_module });
    const run_autohint_compare_tests = b.addRunArtifact(autohint_compare_tests);
    core_test_step.dependOn(&run_autohint_compare_tests.step);

    const character_diff_test_module = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = config.optimize,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = modules.snail },
            .{ .name = "snail-raster", .module = modules.raster },
            .{ .name = "support", .module = modules.support },
        },
    });
    selectDemoEntry(b, character_diff_test_module, .autohint_character_diff);
    const character_diff_tests = b.addTest(.{ .root_module = character_diff_test_module });
    core_test_step.dependOn(&b.addRunArtifact(character_diff_tests).step);

    const test_valgrind_step = b.step("test-valgrind", "Run unit tests under Valgrind");
    const vg_snail = createSnailModuleFull(b, config.target, config.optimize, null, modules.assets, true);
    const vg_snail_tests = b.addTest(.{ .root_module = vg_snail });
    configureValgrindTest(vg_snail_tests);
    test_valgrind_step.dependOn(&b.addRunArtifact(vg_snail_tests).step);
    const vg_raster = createRasterModule(b, config.target, config.optimize, vg_snail, modules.assets, true, null);
    const vg_raster_tests = b.addTest(.{ .root_module = vg_raster });
    configureValgrindTest(vg_raster_tests);
    test_valgrind_step.dependOn(&b.addRunArtifact(vg_raster_tests).step);
}

fn addScreenshotSteps(
    b: *std.Build,
    config: BuildConfig,
    modules: ProjectModules,
) void {
    const release_snail_mod = createSnailModule(b, config.target, .ReleaseFast);
    const release_raster_mod = createRasterModule(b, config.target, .ReleaseFast, release_snail_mod, null, null, null);
    const release_support_mod = createSupportModule(b, config.target, .ReleaseFast, release_snail_mod, modules.assets);
    const embed_vulkan_mod = createEmbedVulkanModule(b, config.target, .ReleaseFast, release_snail_mod, modules.vk_shaders, modules.demo_vulkan_types, modules.shaders_reflection);
    const embed_gl_mod = createEmbedGlModule(b, config.target, .ReleaseFast, release_snail_mod, modules.shaders_gl);

    // CPU screenshot.
    const screenshot_cpu_mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = release_snail_mod },
            .{ .name = "snail-raster", .module = release_raster_mod },
            .{ .name = "support", .module = release_support_mod },
        },
    });
    selectDemoEntry(b, screenshot_cpu_mod, .screenshot_cpu);
    const screenshot_cpu_exe = b.addExecutable(.{ .name = "snail-screenshot", .root_module = screenshot_cpu_mod });
    const run_screenshot_cpu = b.addRunArtifact(screenshot_cpu_exe);
    const screenshot_cpu_step = b.step("run-screenshot", "Render the demo through the CPU backend and write zig-out/demo-screenshot.tga");
    screenshot_cpu_step.dependOn(&run_screenshot_cpu.step);

    // Bless step: re-render the deterministic CPU reference and copy it over
    // the committed golden. CI gates zig-out/demo-screenshot.tga byte-exact
    // against demo_cpu_reference.tga (dev/ci.sh `gate_exact`), so after an
    // intended render change this one command re-syncs it. The GPU gates diff
    // against this live CPU render, so they need no separate golden.
    const update_goldens_step = b.step("update-goldens", "Re-render and overwrite the committed CPU reference image (bless the golden)");
    const bless_cpu_reference = b.addSystemCommand(&.{
        "cp",                          "--",
        "zig-out/demo-screenshot.tga", "dev/demo/tools/screenshots/demo_cpu_reference.tga",
    });
    bless_cpu_reference.has_side_effects = true;
    bless_cpu_reference.step.dependOn(&run_screenshot_cpu.step);
    update_goldens_step.dependOn(&bless_cpu_reference.step);

    // CPU coverage-parity probe (affine twin of the composite probe).
    const coverage_parity_mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = release_snail_mod },
            .{ .name = "snail-raster", .module = release_raster_mod },
            .{ .name = "support", .module = release_support_mod },
        },
    });
    selectDemoEntry(b, coverage_parity_mod, .coverage_parity_probe);
    const coverage_parity_exe = b.addExecutable(.{ .name = "snail-coverage-parity", .root_module = coverage_parity_mod });
    const run_coverage_parity = b.addRunArtifact(coverage_parity_exe);
    const coverage_parity_step = b.step("run-coverage-parity", "Sweep the composite panel through hostile affine transforms on the CPU rasterizer and gate on interior coverage holes");
    coverage_parity_step.dependOn(&run_coverage_parity.step);

    // README banner and algorithm diagrams — CPU backend.
    const algorithm_diagrams_mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = release_snail_mod },
            .{ .name = "snail-raster", .module = release_raster_mod },
            .{ .name = "support", .module = release_support_mod },
        },
    });
    selectDemoEntry(b, algorithm_diagrams_mod, .algorithm_diagrams);
    const algorithm_diagrams_exe = b.addExecutable(.{ .name = "snail-algorithm-diagrams", .root_module = algorithm_diagrams_mod });
    const run_algorithm_diagrams = b.addRunArtifact(algorithm_diagrams_exe);
    const algorithm_diagrams_step = b.step("run-algorithm-diagrams", "Render the README banner and algorithm diagrams through the CPU backend into zig-out/banner.tga and zig-out/algorithm-*.tga");
    algorithm_diagrams_step.dependOn(&run_algorithm_diagrams.step);

    // Composable autohint policy comparison — CPU backend.
    const autohint_shot_mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = release_snail_mod },
            .{ .name = "snail-raster", .module = release_raster_mod },
            .{ .name = "support", .module = release_support_mod },
        },
    });
    selectDemoEntry(b, autohint_shot_mod, .autohint_screenshot);
    configureEglOffscreenModule(autohint_shot_mod, embed_gl_mod, .{ .desktop = true });
    const autohint_shot_exe = b.addExecutable(.{ .name = "snail-autohint-screenshot", .root_module = autohint_shot_mod });
    const run_autohint_shot = b.addRunArtifact(autohint_shot_exe);
    const autohint_shot_step = b.step("run-autohint-screenshot", "Render the composable autohint policy comparison through the CPU backend and write zig-out/autohint-screenshot.tga");
    autohint_shot_step.dependOn(&run_autohint_shot.step);

    // Autohint xy policy vs TT-hint agreement metric + overlay — CPU backend.
    const autohint_diff_mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = release_snail_mod },
            .{ .name = "snail-raster", .module = release_raster_mod },
            .{ .name = "support", .module = release_support_mod },
        },
    });
    selectDemoEntry(b, autohint_diff_mod, .autohint_diff);
    const autohint_diff_exe = b.addExecutable(.{ .name = "snail-autohint-diff", .root_module = autohint_diff_mod });
    const run_autohint_diff = b.addRunArtifact(autohint_diff_exe);
    const autohint_diff_step = b.step("run-autohint-diff", "Render the autohint xy policy vs TT hinting at every demo ppem, print a disagreement score and write zig-out/autohint-diff.tga");
    autohint_diff_step.dependOn(&run_autohint_diff.step);

    const character_diff_mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = release_snail_mod },
            .{ .name = "snail-raster", .module = release_raster_mod },
            .{ .name = "support", .module = release_support_mod },
        },
    });
    selectDemoEntry(b, character_diff_mod, .autohint_character_diff);
    const character_diff_exe = b.addExecutable(.{ .name = "snail-autohint-character-diff", .root_module = character_diff_mod });
    const run_character_diff = b.addRunArtifact(character_diff_exe);
    const character_diff_step = b.step("run-autohint-character-diff", "Write per-character TT/autohint contact sheets and metrics under zig-out/autohint-character-diff");
    character_diff_step.dependOn(&run_character_diff.step);

    // Proportional-face spot check — CPU backend.
    const prop_mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = release_snail_mod },
            .{ .name = "snail-raster", .module = release_raster_mod },
            .{ .name = "support", .module = release_support_mod },
        },
    });
    selectDemoEntry(b, prop_mod, .autohint_proportional);
    const prop_exe = b.addExecutable(.{ .name = "snail-autohint-prop", .root_module = prop_mod });
    const prop_step = b.step("run-autohint-prop", "Render the autohint policies on a proportional TT-hinted face → zig-out/autohint-prop.tga");
    prop_step.dependOn(&b.addRunArtifact(prop_exe).step);

    // RESEARCH PROBE: TT bytecode ppem-independence analysis (internal types).
    const tt_probe_internal_mod = b.createModule(.{
        .root_source_file = b.path("src/snail/tt_probe_internal.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{.{ .name = "assets", .module = modules.assets }},
    });
    const tt_probe_mod = b.createModule(.{
        .root_source_file = b.path("dev/tools/tt_ppem_probe.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail_tt_probe_internal", .module = tt_probe_internal_mod },
        },
    });
    const tt_probe_exe = b.addExecutable(.{ .name = "snail-tt-probe", .root_module = tt_probe_mod });
    const run_tt_probe = b.addRunArtifact(tt_probe_exe);
    const tt_probe_step = b.step("run-tt-probe", "Probe whether TT-hint output is a ppem-independent per-glyph function");
    tt_probe_step.dependOn(&run_tt_probe.step);

    // Banner screenshot — full interactive-demo scene through CPU backend.
    const banner_screenshot_mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = release_snail_mod },
            .{ .name = "snail-raster", .module = release_raster_mod },
            .{ .name = "support", .module = release_support_mod },
        },
    });
    selectDemoEntry(b, banner_screenshot_mod, .banner_screenshot_cpu);
    const banner_screenshot_exe = b.addExecutable(.{ .name = "snail-banner-screenshot", .root_module = banner_screenshot_mod });
    const run_banner_screenshot = b.addRunArtifact(banner_screenshot_exe);
    const banner_screenshot_step = b.step("run-banner-screenshot", "Render the full banner scene through the CPU backend and write zig-out/banner-screenshot.tga");
    banner_screenshot_step.dependOn(&run_banner_screenshot.step);

    // Banner screenshot — GL 3.3 offscreen.
    const banner_screenshot_gl_mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = release_snail_mod },
            .{ .name = "snail-raster", .module = release_raster_mod },
            .{ .name = "support", .module = release_support_mod },
        },
    });
    selectDemoEntry(b, banner_screenshot_gl_mod, .banner_screenshot_gl);
    configureEglOffscreenModule(banner_screenshot_gl_mod, embed_gl_mod, .{ .desktop = true });
    const banner_screenshot_gl_exe = b.addExecutable(.{ .name = "snail-banner-screenshot-gl", .root_module = banner_screenshot_gl_mod });
    const run_banner_screenshot_gl = b.addRunArtifact(banner_screenshot_gl_exe);
    const banner_screenshot_gl_step = b.step("run-banner-screenshot-gl", "Render the full banner scene through GL and write zig-out/banner-screenshot-gl.tga");
    banner_screenshot_gl_step.dependOn(&run_banner_screenshot_gl.step);

    // Banner screenshot — GLES 3.0 offscreen.
    const banner_screenshot_gles30_mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = release_snail_mod },
            .{ .name = "snail-raster", .module = release_raster_mod },
            .{ .name = "support", .module = release_support_mod },
        },
    });
    selectDemoEntry(b, banner_screenshot_gles30_mod, .banner_screenshot_gles30);
    configureEglOffscreenModule(banner_screenshot_gles30_mod, embed_gl_mod, .{ .es = true });
    const banner_screenshot_gles30_exe = b.addExecutable(.{ .name = "snail-banner-screenshot-gles30", .root_module = banner_screenshot_gles30_mod });
    const run_banner_screenshot_gles30 = b.addRunArtifact(banner_screenshot_gles30_exe);
    const banner_screenshot_gles30_step = b.step("run-banner-screenshot-gles30", "Render the full banner scene through GLES 3.0 and write zig-out/banner-screenshot-gles30.tga");
    banner_screenshot_gles30_step.dependOn(&run_banner_screenshot_gles30.step);

    // Banner screenshot — Vulkan offscreen.
    {
        const release_vk_platform_mod = createDemoVulkanPlatformModule(b, config.target, .ReleaseFast, release_snail_mod, modules.demo_vulkan_types);
        const banner_screenshot_vk_mod = b.createModule(.{
            .root_source_file = b.path("dev/demo/root.zig"),
            .target = config.target,
            .optimize = .ReleaseFast,
            .link_libc = true,
            .imports = &.{
                .{ .name = "assets", .module = modules.assets },
                .{ .name = "snail", .module = release_snail_mod },
                .{ .name = "snail-raster", .module = release_raster_mod },
                .{ .name = "support", .module = release_support_mod },
                .{ .name = "demo_platform_vulkan", .module = release_vk_platform_mod },
                .{ .name = "embed_vulkan", .module = embed_vulkan_mod },
            },
        });
        selectDemoEntry(b, banner_screenshot_vk_mod, .banner_screenshot_vulkan);
        const banner_screenshot_vk_exe = b.addExecutable(.{ .name = "snail-banner-screenshot-vulkan", .root_module = banner_screenshot_vk_mod });
        const run_banner_screenshot_vk = b.addRunArtifact(banner_screenshot_vk_exe);
        const banner_screenshot_vk_step = b.step("run-banner-screenshot-vulkan", "Render the full banner scene through Vulkan and write zig-out/banner-screenshot-vulkan.tga");
        banner_screenshot_vk_step.dependOn(&run_banner_screenshot_vk.step);
    }

    // GL screenshot.
    const screenshot_gl_mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = release_snail_mod },
            .{ .name = "snail-raster", .module = release_raster_mod },
            .{ .name = "support", .module = release_support_mod },
        },
    });
    selectDemoEntry(b, screenshot_gl_mod, .screenshot_gl);
    configureEglOffscreenModule(screenshot_gl_mod, embed_gl_mod, .{ .desktop = true });
    const screenshot_gl_exe = b.addExecutable(.{ .name = "snail-screenshot-gl", .root_module = screenshot_gl_mod });
    const run_screenshot_gl = b.addRunArtifact(screenshot_gl_exe);
    const screenshot_gl_step = b.step("run-screenshot-gl", "Render the demo through the GL backend and write zig-out/demo-screenshot-gl.tga");
    screenshot_gl_step.dependOn(&run_screenshot_gl.step);

    // Offscreen Vulkan game-scene screenshot (depth-tested) → zig-out/game-vulkan.tga.
    {
        const release_vk_platform_mod = createDemoVulkanPlatformModule(b, config.target, .ReleaseFast, release_snail_mod, modules.demo_vulkan_types);
        const game_shot_vk_mod = b.createModule(.{
            .root_source_file = b.path("dev/demo/root.zig"),
            .target = config.target,
            .optimize = .ReleaseFast,
            .link_libc = true,
            .imports = &.{
                .{ .name = "assets", .module = modules.assets },
                .{ .name = "snail", .module = release_snail_mod },
                .{ .name = "snail-raster", .module = release_raster_mod },
                .{ .name = "support", .module = release_support_mod },
                .{ .name = "demo_platform_vulkan", .module = release_vk_platform_mod },
                .{ .name = "embed_vulkan", .module = embed_vulkan_mod },
            },
        });
        selectDemoEntry(b, game_shot_vk_mod, .game_screenshot_vulkan);
        addGameShaderSpirv(b, game_shot_vk_mod);
        const game_shot_vk_exe = b.addExecutable(.{ .name = "snail-game-screenshot-vulkan", .root_module = game_shot_vk_mod });
        const run_game_shot_vk = b.addRunArtifact(game_shot_vk_exe);
        const game_shot_vk_step = b.step("run-game-screenshot-vulkan", "Render the game scene offscreen through Vulkan → zig-out/game-vulkan.tga");
        game_shot_vk_step.dependOn(&run_game_shot_vk.step);
    }

    // Offscreen (no-window) game-scene screenshot per GL backend — the game's
    // headless verification harness. Writes zig-out/game-<backend>.tga.
    {
        const game_shot_mod = b.createModule(.{
            .root_source_file = b.path("dev/demo/root.zig"),
            .target = config.target,
            .optimize = .ReleaseFast,
            .link_libc = true,
            .imports = &.{
                .{ .name = "assets", .module = modules.assets },
                .{ .name = "snail", .module = release_snail_mod },
                .{ .name = "snail-raster", .module = release_raster_mod },
                .{ .name = "support", .module = release_support_mod },
                .{ .name = "snail_shaders", .module = modules.shaders_gl },
            },
        });
        selectDemoEntry(b, game_shot_mod, .game_screenshot_gl);
        addGameShaderGl(b, game_shot_mod, modules.game_material_gl);
        configureEglOffscreenModule(game_shot_mod, embed_gl_mod, .{ .desktop = true, .es = true });
        const game_shot_exe = b.addExecutable(.{ .name = "snail-game-screenshot", .root_module = game_shot_mod });
        const run_game_shot = b.addRunArtifact(game_shot_exe);
        const game_shot_step = b.step("run-game-screenshot", "Render the game scene offscreen per GL backend → zig-out/game-<backend>.tga");
        game_shot_step.dependOn(&run_game_shot.step);
    }

    // Regression gate for the fill_stroke_inside composite: sweeps a rounded-rect
    // panel through perspective and fails if any interior coverage hole appears.
    {
        const comp_probe_mod = b.createModule(.{
            .root_source_file = b.path("dev/demo/root.zig"),
            .target = config.target,
            .optimize = .ReleaseFast,
            .link_libc = true,
            .imports = &.{
                .{ .name = "assets", .module = modules.assets },
                .{ .name = "snail", .module = release_snail_mod },
                .{ .name = "snail-raster", .module = release_raster_mod },
                .{ .name = "support", .module = release_support_mod },
            },
        });
        selectDemoEntry(b, comp_probe_mod, .composite_probe);
        configureEglOffscreenModule(comp_probe_mod, embed_gl_mod, .{ .desktop = true });
        const comp_probe_exe = b.addExecutable(.{ .name = "snail-composite-probe", .root_module = comp_probe_mod });
        const run_comp_probe = b.addRunArtifact(comp_probe_exe);
        const comp_probe_step = b.step("run-composite-probe", "Sweep a fill_stroke_inside panel through perspective and gate on interior coverage holes");
        comp_probe_step.dependOn(&run_comp_probe.step);
    }

    // CPU port of the path coverage evaluator to root-cause the conic
    // grazing-corner hole deterministically (both conic solvers, swept footprint).
    {
        const cov_probe_mod = b.createModule(.{
            .root_source_file = b.path("dev/demo/root.zig"),
            .target = config.target,
            .optimize = .ReleaseFast,
            .link_libc = true,
            .imports = &.{
                .{ .name = "snail", .module = release_snail_mod },
                .{ .name = "snail-raster", .module = release_raster_mod },
                .{ .name = "support", .module = release_support_mod },
            },
        });
        selectDemoEntry(b, cov_probe_mod, .coverage_probe);
        const cov_probe_exe = b.addExecutable(.{ .name = "snail-coverage-probe", .root_module = cov_probe_mod });
        const run_cov_probe = b.addRunArtifact(cov_probe_exe);
        const cov_probe_step = b.step("run-coverage-probe", "Sweep the conic coverage solver (deriv vs code) across grazing footprints and count holes");
        cov_probe_step.dependOn(&run_cov_probe.step);
    }

    // CPU-vs-GL pixel parity gate over the shared content scene.
    const backend_compare_mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = release_snail_mod },
            .{ .name = "snail-raster", .module = release_raster_mod },
            .{ .name = "support", .module = release_support_mod },
        },
    });
    selectDemoEntry(b, backend_compare_mod, .backend_compare);
    configureEglOffscreenModule(backend_compare_mod, embed_gl_mod, .{ .desktop = true });
    const backend_compare_exe = b.addExecutable(.{ .name = "snail-backend-compare", .root_module = backend_compare_mod });
    const run_backend_compare = b.addRunArtifact(backend_compare_exe);
    const backend_compare_step = b.step("run-backend-compare", "Render the content scene through CPU and GL and fail if they diverge beyond the AA tolerance");
    backend_compare_step.dependOn(&run_backend_compare.step);

    // Gamma conformance gate: interior (full-coverage) pixels of a controlled
    // solid scene, CPU vs GL33 vs GLES30, checked exactly against the analytic
    // encode. Immune to AA-edge differences that backend-compare tolerates.
    const gamma_probe_mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = release_snail_mod },
            .{ .name = "snail-raster", .module = release_raster_mod },
            .{ .name = "support", .module = release_support_mod },
        },
    });
    selectDemoEntry(b, gamma_probe_mod, .gamma_probe);
    configureEglOffscreenModule(gamma_probe_mod, embed_gl_mod, .{ .desktop = true, .es = true });
    const gamma_probe_exe = b.addExecutable(.{ .name = "snail-gamma-probe", .root_module = gamma_probe_mod });
    const run_gamma_probe = b.addRunArtifact(gamma_probe_exe);
    const gamma_probe_step = b.step("run-gamma-probe", "Check interior-pixel gamma (encode round-trip) across CPU/GL33/GLES30");
    gamma_probe_step.dependOn(&run_gamma_probe.step);

    // GLES screenshot.
    const screenshot_gles30_mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = release_snail_mod },
            .{ .name = "snail-raster", .module = release_raster_mod },
            .{ .name = "support", .module = release_support_mod },
        },
    });
    selectDemoEntry(b, screenshot_gles30_mod, .screenshot_gles30);
    configureEglOffscreenModule(screenshot_gles30_mod, embed_gl_mod, .{ .es = true });
    const screenshot_gles30_exe = b.addExecutable(.{ .name = "snail-screenshot-gles30", .root_module = screenshot_gles30_mod });
    const run_screenshot_gles30 = b.addRunArtifact(screenshot_gles30_exe);
    const screenshot_gles30_step = b.step("run-screenshot-gles30", "Render the demo through the GLES30 backend and write zig-out/demo-screenshot-gles30.tga");
    screenshot_gles30_step.dependOn(&run_screenshot_gles30.step);

    // Vulkan screenshot.
    {
        const vk_platform_mod = createDemoVulkanPlatformModule(b, config.target, .ReleaseFast, release_snail_mod, modules.demo_vulkan_types);
        const screenshot_vulkan_mod = b.createModule(.{
            .root_source_file = b.path("dev/demo/root.zig"),
            .target = config.target,
            .optimize = .ReleaseFast,
            .link_libc = true,
            .imports = &.{
                .{ .name = "assets", .module = modules.assets },
                .{ .name = "snail", .module = release_snail_mod },
                .{ .name = "snail-raster", .module = release_raster_mod },
                .{ .name = "support", .module = release_support_mod },
                .{ .name = "demo_platform_vulkan", .module = vk_platform_mod },
                .{ .name = "embed_vulkan", .module = embed_vulkan_mod },
            },
        });
        selectDemoEntry(b, screenshot_vulkan_mod, .screenshot_vulkan);
        const screenshot_vulkan_exe = b.addExecutable(.{ .name = "snail-screenshot-vulkan", .root_module = screenshot_vulkan_mod });
        const run_screenshot_vulkan = b.addRunArtifact(screenshot_vulkan_exe);
        const screenshot_vulkan_step = b.step("run-screenshot-vulkan", "Render the demo through the Vulkan backend and write zig-out/demo-screenshot-vulkan.tga");
        screenshot_vulkan_step.dependOn(&run_screenshot_vulkan.step);
    }
}

fn createInteractiveDemoModule(
    b: *std.Build,
    config: BuildConfig,
    modules: ProjectModules,
    demo_optimize: std.builtin.OptimizeMode,
    entry: DemoEntry,
) *std.Build.Module {
    const demo_embed_gl_mod = createEmbedGlModule(b, config.target, demo_optimize, modules.snail, modules.shaders_gl);
    const demo_embed_vulkan_mod = createEmbedVulkanModule(b, config.target, demo_optimize, modules.snail, modules.vk_shaders, modules.demo_vulkan_types, modules.shaders_reflection);
    const demo_mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = demo_optimize,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = modules.snail },
            .{ .name = "snail-raster", .module = modules.raster },
            .{ .name = "support", .module = modules.support },
            .{ .name = "embed_gl", .module = demo_embed_gl_mod },
            .{ .name = "embed_vulkan", .module = demo_embed_vulkan_mod },
            .{ .name = "vulkan_types", .module = modules.demo_vulkan_types },
        },
    });
    selectDemoEntry(b, demo_mod, entry);
    demo_mod.linkSystemLibrary("wayland-client", .{});
    demo_mod.addIncludePath(b.path("dev/demo/platform"));
    demo_mod.addCSourceFile(.{ .file = b.path("dev/demo/platform/xdg-shell-client-protocol.c") });
    demo_mod.addCSourceFile(.{ .file = b.path("dev/demo/platform/presentation-time-client-protocol.c") });
    demo_mod.linkSystemLibrary("EGL", .{});
    demo_mod.linkSystemLibrary("wayland-egl", .{});
    demo_mod.linkSystemLibrary("OpenGL", .{});
    demo_mod.linkSystemLibrary("GLESv2", .{});
    demo_mod.linkSystemLibrary("vulkan", .{});
    return demo_mod;
}

fn addInteractiveDemoStep(
    b: *std.Build,
    config: BuildConfig,
    modules: ProjectModules,
) void {
    // Interactive demos default to ReleaseFast unless the user explicitly
    // overrides via -Doptimize.
    const demo_optimize = if (b.user_input_options.contains("optimize")) config.optimize else .ReleaseFast;
    const demo_mod = createInteractiveDemoModule(b, config, modules, demo_optimize, .banner);
    const demo_exe = b.addExecutable(.{ .name = "snail-demo", .root_module = demo_mod });
    const install_demo_artifact = b.addInstallArtifact(demo_exe, .{});
    const install_demo_step = b.step("install-demo", "Install the interactive Wayland banner demo");
    install_demo_step.dependOn(&install_demo_artifact.step);
    const run_demo = b.addRunArtifact(demo_exe);
    if (b.args) |args| run_demo.addArgs(args);
    const run_step = b.step("run", "Run the interactive Wayland banner demo");
    run_step.dependOn(&run_demo.step);
}

fn addTerminalDemoStep(
    b: *std.Build,
    config: BuildConfig,
    modules: ProjectModules,
) void {
    const demo_optimize = if (b.user_input_options.contains("optimize")) config.optimize else .ReleaseFast;
    const demo_mod = createInteractiveDemoModule(b, config, modules, demo_optimize, .terminal);
    const demo_exe = b.addExecutable(.{
        .name = "snail-terminal-demo",
        .root_module = demo_mod,
    });

    const install_artifact = b.addInstallArtifact(demo_exe, .{});
    const install_step = b.step(
        "install-terminal-demo",
        "Install the interactive terminal text demo",
    );
    install_step.dependOn(&install_artifact.step);

    const run_artifact = b.addRunArtifact(demo_exe);
    if (b.args) |args| run_artifact.addArgs(args);
    const run_step = b.step(
        "run-terminal",
        "Run the interactive terminal text integration demo",
    );
    run_step.dependOn(&run_artifact.step);
}

fn addGameDemoStep(
    b: *std.Build,
    config: BuildConfig,
    modules: ProjectModules,
) void {
    // The game demo cycles Vulkan and the GL family (gl33/gl44/gles30) at
    // runtime — a 3D scene whose custom material shader samples snail glyph
    // coverage. It owns both window-system integrations and their API links.
    const game_optimize = if (b.user_input_options.contains("optimize")) config.optimize else .ReleaseFast;
    const game_embed_gl_mod = createEmbedGlModule(b, config.target, game_optimize, modules.snail, modules.shaders_gl);
    const game_mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/root.zig"),
        .target = config.target,
        .optimize = game_optimize,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = modules.snail },
            .{ .name = "snail-raster", .module = modules.raster },
            .{ .name = "support", .module = modules.support },
            .{ .name = "embed_gl", .module = game_embed_gl_mod },
            .{ .name = "snail_shaders", .module = modules.shaders_gl },
        },
    });
    selectDemoEntry(b, game_mod, .game);
    addGameShaderGl(b, game_mod, modules.game_material_gl);
    game_mod.linkSystemLibrary("wayland-client", .{});
    game_mod.addIncludePath(b.path("dev/demo/platform"));
    game_mod.addCSourceFile(.{ .file = b.path("dev/demo/platform/xdg-shell-client-protocol.c") });
    game_mod.addCSourceFile(.{ .file = b.path("dev/demo/platform/presentation-time-client-protocol.c") });
    game_mod.linkSystemLibrary("EGL", .{});
    game_mod.linkSystemLibrary("wayland-egl", .{});
    game_mod.linkSystemLibrary("OpenGL", .{});
    game_mod.linkSystemLibrary("GLESv2", .{});
    // vk_scene uses the reference caller renderer; the windowed Vulkan
    // platform is a relative file compiled into game_mod (its own vk cImport
    // via linkSystemLibrary). game/game_shaders.zig gets the material SPIR-V.
    game_mod.addImport("embed_vulkan", createEmbedVulkanModule(b, config.target, game_optimize, modules.snail, modules.vk_shaders, modules.demo_vulkan_types, modules.shaders_reflection));
    game_mod.addImport("vulkan_types", modules.demo_vulkan_types);
    addGameShaderSpirv(b, game_mod);
    game_mod.linkSystemLibrary("vulkan", .{});

    const game_exe = b.addExecutable(.{ .name = "snail-game-demo", .root_module = game_mod });
    const install_game_artifact = b.addInstallArtifact(game_exe, .{});
    const install_game_step = b.step("install-game", "Install the interactive Wayland 3D game demo");
    install_game_step.dependOn(&install_game_artifact.step);
    const run_game = b.addRunArtifact(game_exe);
    if (b.args) |args| run_game.addArgs(args);
    const run_step = b.step("run-game", "Run the interactive Wayland 3D game demo");
    run_step.dependOn(&run_game.step);
}

fn addMinimalGlStep(
    b: *std.Build,
    config: BuildConfig,
    modules: ProjectModules,
) void {
    const mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/app/minimal_gl.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = modules.snail },
            .{ .name = "snail_shaders", .module = modules.shaders_glsl330 },
        },
    });
    mod.linkSystemLibrary("EGL", .{});
    mod.linkSystemLibrary("OpenGL", .{});
    const exe = b.addExecutable(.{ .name = "snail-minimal-gl", .root_module = mod });
    const run = b.addRunArtifact(exe);
    const step = b.step("run-minimal-gl", "Render the one-file public-API GL example to zig-out/minimal-gl.tga");
    step.dependOn(&run.step);
}

/// Cross-compiled Windows demo: `zig build run-minimal-d3d11` builds
/// dev/demo/app/minimal_d3d11.zig for x86_64-windows-gnu (zig's bundled
/// mingw provides d3d11.h/dxgi.h/d3dcompiler.h and the import libraries)
/// and runs it headless under Wine with a hermetic prefix in zig-out.
/// The one non-bundled dependency is HarfBuzz: the Windows snail module
/// compiles the upstream single-file amalgam (`src/harfbuzz.cc`) from the
/// nix-pinned source tree exported as `HARFBUZZ_SRC` (see shell.nix)
/// instead of linking the host system library.
fn addMinimalD3d11Step(
    b: *std.Build,
    modules: ProjectModules,
) void {
    const step = b.step("run-minimal-d3d11", "Render the one-file public-API D3D11 example under Wine to zig-out/minimal-d3d11.tga");
    const gates_step = b.step("install-windows-gates", "Install the cross-built D3D11 demo, pixelgate, and the reference TGA into zig-out/windows-gates for the Windows CI job");
    const hb_src = b.graph.environ_map.get("HARFBUZZ_SRC") orelse {
        const fail = b.addFail("run-minimal-d3d11 needs HARFBUZZ_SRC (enter nix-shell; see shell.nix)");
        step.dependOn(&fail.step);
        gates_step.dependOn(&fail.step);
        return;
    };
    const win_target = b.resolveTargetQuery(.{ .cpu_arch = .x86_64, .os_tag = .windows, .abi = .gnu });

    // The snail module for the Windows target: identical source, but
    // HarfBuzz is compiled in from the amalgam rather than system-linked.
    const snail_win = b.createModule(.{
        .root_source_file = b.path("src/snail/root.zig"),
        .target = win_target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .link_libcpp = true,
    });
    snail_win.addIncludePath(.{ .cwd_relative = b.pathJoin(&.{ hb_src, "src" }) });
    snail_win.addCSourceFile(.{
        .file = .{ .cwd_relative = b.pathJoin(&.{ hb_src, "src", "harfbuzz.cc" }) },
        .flags = &.{ "-std=c++17", "-fno-exceptions", "-fno-rtti" },
        .language = .cpp,
    });

    const mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/app/minimal_d3d11.zig"),
        .target = win_target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = snail_win },
            .{ .name = "snail_shaders", .module = modules.shaders_hlsl },
        },
    });
    mod.linkSystemLibrary("d3d11", .{ .use_pkg_config = .no });
    mod.linkSystemLibrary("dxgi", .{ .use_pkg_config = .no });
    mod.linkSystemLibrary("d3dcompiler_47", .{ .use_pkg_config = .no });
    const exe = b.addExecutable(.{ .name = "snail-minimal-d3d11", .root_module = mod });

    // Hermetic Wine prefix inside zig-out (first run pays one-time prefix
    // setup); `wine` comes from the nix shell. The exe writes
    // zig-out/minimal-d3d11.tga relative to the build root.
    b.build_root.handle.createDirPath(b.graph.io, "zig-out") catch {};
    const run = b.addSystemCommand(&.{"wine"});
    run.addArtifactArg(exe);
    run.setEnvironmentVariable("WINEPREFIX", b.pathFromRoot("zig-out/wineprefix"));
    run.setEnvironmentVariable("WINEDEBUG", "-all");
    // First-run prefix creation pops wine-mono/wine-gecko installer
    // dialogs, which hang a headless/CI run waiting for a click. Disable
    // the mscoree/mshtml loaders outright — the demo needs neither .NET
    // nor HTML — so prefix setup is fully non-interactive.
    run.setEnvironmentVariable("WINEDLLOVERRIDES", "mscoree=d;mshtml=d");
    // Rendering output changes with the shaders/scene, not just the exe.
    run.has_side_effects = true;
    step.dependOn(&run.step);

    // `install-windows-gates`: everything a bare Windows CI runner needs to
    // validate the render against real D3D11 — the demo exe, the pixelgate
    // comparison tool (the ImageMagick gate without ImageMagick), and the
    // checked-in reference TGA. The Windows runner only executes these
    // prebuilt artifacts; the one nix-pinned toolchain stays on Linux
    // (see the `windows` job in .github/workflows/ci.yml).
    const gates_dir: std.Build.InstallDir = .{ .custom = "windows-gates" };

    // Cross-built CPU-rasterizer screenshot (the `run-screenshot` demo-scene
    // tool): no GL, no display, no D3D — pure snail-raster float math, so the
    // Windows render is gated bit-identical (pixelgate threshold 0) against
    // the checked-in Linux CPU reference. Reuses the amalgam-HarfBuzz snail
    // module above.
    {
        const raster_win = createRasterModule(b, win_target, .ReleaseFast, snail_win, null, null, null);
        const support_win = createSupportModule(b, win_target, .ReleaseFast, snail_win, modules.assets);
        const screenshot_cpu_win_mod = b.createModule(.{
            .root_source_file = b.path("dev/demo/root.zig"),
            .target = win_target,
            .optimize = .ReleaseFast,
            .link_libc = true,
            .imports = &.{
                .{ .name = "assets", .module = modules.assets },
                .{ .name = "snail", .module = snail_win },
                .{ .name = "snail-raster", .module = raster_win },
                .{ .name = "support", .module = support_win },
            },
        });
        selectDemoEntry(b, screenshot_cpu_win_mod, .screenshot_cpu);
        const screenshot_cpu_win_exe = b.addExecutable(.{ .name = "snail-screenshot-cpu", .root_module = screenshot_cpu_win_mod });
        gates_step.dependOn(&b.addInstallArtifact(screenshot_cpu_win_exe, .{ .dest_dir = .{ .override = gates_dir } }).step);
        gates_step.dependOn(&b.addInstallFile(b.path("dev/demo/tools/screenshots/demo_cpu_reference.tga"), "windows-gates/demo_cpu_reference.tga").step);
    }

    // Cross-built WebGPU demo (wgpu-native's D3D12 backend on the Windows
    // runner): links the upstream wgpu-native Windows-gnu release import lib
    // pinned in shell.nix (SNAIL_WGPU_WINDOWS, version-matched to the nixpkgs
    // wgpu-native), ships wgpu_native.dll next to the exe.
    if (b.graph.environ_map.get("SNAIL_WGPU_WINDOWS")) |wgpu_win| {
        const wgpu_win_mod = b.createModule(.{
            .root_source_file = b.path("dev/demo/app/minimal_wgpu.zig"),
            .target = win_target,
            .optimize = .ReleaseFast,
            .link_libc = true,
            .imports = &.{
                .{ .name = "assets", .module = modules.assets },
                .{ .name = "snail", .module = snail_win },
                .{ .name = "snail_shaders", .module = modules.shaders_wgsl },
            },
        });
        wgpu_win_mod.addIncludePath(.{ .cwd_relative = b.pathJoin(&.{ wgpu_win, "include" }) });
        wgpu_win_mod.addLibraryPath(.{ .cwd_relative = b.pathJoin(&.{ wgpu_win, "lib" }) });
        wgpu_win_mod.linkSystemLibrary("wgpu_native", .{ .use_pkg_config = .no });
        const wgpu_win_exe = b.addExecutable(.{ .name = "snail-minimal-wgpu", .root_module = wgpu_win_mod });
        gates_step.dependOn(&b.addInstallArtifact(wgpu_win_exe, .{ .dest_dir = .{ .override = gates_dir } }).step);
        gates_step.dependOn(&b.addInstallFile(.{ .cwd_relative = b.pathJoin(&.{ wgpu_win, "lib", "wgpu_native.dll" }) }, "windows-gates/wgpu_native.dll").step);
    } else {
        gates_step.dependOn(&b.addFail("install-windows-gates needs SNAIL_WGPU_WINDOWS (enter nix-shell; see shell.nix)").step);
    }
    // DXC next to the exe (SNAIL_DXC_WINDOWS, pinned in shell.nix): wgpu's
    // D3D12 backend emits a naga sampler heap — an SM 5.1+ resource array
    // that FXC-class compilers reject (vkd3d-shader E5017; the runner's FXC
    // likewise fails the pipeline). The gate runs with
    // WGPU_DX12_COMPILER=dxc so shaders go through these dlls instead.
    if (b.graph.environ_map.get("SNAIL_DXC_WINDOWS")) |dxc_win| {
        gates_step.dependOn(&b.addInstallFile(.{ .cwd_relative = b.pathJoin(&.{ dxc_win, "bin", "x64", "dxcompiler.dll" }) }, "windows-gates/dxcompiler.dll").step);
        gates_step.dependOn(&b.addInstallFile(.{ .cwd_relative = b.pathJoin(&.{ dxc_win, "bin", "x64", "dxil.dll" }) }, "windows-gates/dxil.dll").step);
    } else {
        gates_step.dependOn(&b.addFail("install-windows-gates needs SNAIL_DXC_WINDOWS (enter nix-shell; see shell.nix)").step);
    }
    const pixelgate_win = b.addExecutable(.{
        .name = "pixelgate",
        .root_module = b.createModule(.{
            .root_source_file = b.path("dev/tools/pixelgate.zig"),
            .target = win_target,
            .optimize = .ReleaseFast,
        }),
    });
    gates_step.dependOn(&b.addInstallArtifact(exe, .{ .dest_dir = .{ .override = gates_dir } }).step);
    gates_step.dependOn(&b.addInstallArtifact(pixelgate_win, .{ .dest_dir = .{ .override = gates_dir } }).step);
    gates_step.dependOn(&b.addInstallFile(b.path("dev/demo/app/minimal_reference.tga"), "windows-gates/minimal_reference.tga").step);

    // A native pixelgate too (zig-out/bin), so the same gate is runnable
    // locally against Wine-produced TGAs.
    const pixelgate_native = b.addExecutable(.{
        .name = "pixelgate",
        .root_module = b.createModule(.{
            .root_source_file = b.path("dev/tools/pixelgate.zig"),
            .target = b.graph.host,
            .optimize = .ReleaseFast,
        }),
    });
    gates_step.dependOn(&b.addInstallArtifact(pixelgate_native, .{}).step);
}

/// Best-effort Metal demo (see dev/demo/app/minimal_metal.zig and
/// src/snail/shader/slang/README.md "Metal"). Two steps:
///
///  - `check-metal-demo` (any host): cross-compiles the demo and its snail
///    module (HarfBuzz amalgam included) for aarch64-macos into a static
///    library — full semantic analysis + machine code generation with
///    zig's bundled macOS libc/libc++ headers, forced through
///    `comptime { _ = &main; }` in the demo file. What this does NOT
///    verify: linking against the Apple frameworks (needs an SDK), the
///    Objective-C selector spellings/enum values (runtime-checked only),
///    and any Metal runtime behavior.
///  - `run-minimal-metal` (macOS host only): native build linking
///    Metal/Foundation/CoreGraphics (CoreGraphics is required for
///    MTLCreateSystemDefaultDevice in a command-line tool), then runs it
///    to produce zig-out/minimal-metal.tga.
fn addMinimalMetalStep(
    b: *std.Build,
    modules: ProjectModules,
) void {
    const check_step = b.step("check-metal-demo", "Cross-compile the one-file Metal example for aarch64-macos (analysis+codegen only; no SDK link, no Metal runtime on this host)");
    const run_step = b.step("run-minimal-metal", "Render the one-file public-API Metal example to zig-out/minimal-metal.tga (macOS hosts only)");
    const hb_src = b.graph.environ_map.get("HARFBUZZ_SRC") orelse {
        const fail = b.addFail("check-metal-demo / run-minimal-metal need HARFBUZZ_SRC (enter nix-shell; see shell.nix)");
        check_step.dependOn(&fail.step);
        run_step.dependOn(&fail.step);
        return;
    };

    // The snail module for a macOS target: identical source, HarfBuzz
    // compiled in from the amalgam (same pattern as the Windows/D3D11
    // demo; zig bundles the macOS libc/libc++ headers, so this
    // cross-compiles without an SDK).
    const makeModule = struct {
        fn make(bb: *std.Build, mods: ProjectModules, hb: []const u8, target: std.Build.ResolvedTarget) *std.Build.Module {
            const snail_mac = bb.createModule(.{
                .root_source_file = bb.path("src/snail/root.zig"),
                .target = target,
                .optimize = .ReleaseFast,
                .link_libc = true,
                .link_libcpp = true,
            });
            snail_mac.addIncludePath(.{ .cwd_relative = bb.pathJoin(&.{ hb, "src" }) });
            snail_mac.addCSourceFile(.{
                .file = .{ .cwd_relative = bb.pathJoin(&.{ hb, "src", "harfbuzz.cc" }) },
                .flags = &.{ "-std=c++17", "-fno-exceptions", "-fno-rtti" },
                .language = .cpp,
            });
            const mod = bb.createModule(.{
                .root_source_file = bb.path("dev/demo/app/minimal_metal.zig"),
                .target = target,
                .optimize = .ReleaseFast,
                .link_libc = true,
                .imports = &.{
                    .{ .name = "assets", .module = mods.assets },
                    .{ .name = "snail", .module = snail_mac },
                    .{ .name = "snail_shaders", .module = mods.shaders_msl },
                },
            });
            return mod;
        }
    }.make;

    // Compile check: a static library needs no linker pass against the
    // (absent) Apple SDK, but still compiles every Zig and C++ input.
    const check_target = b.resolveTargetQuery(.{ .cpu_arch = .aarch64, .os_tag = .macos });
    const check_lib = b.addLibrary(.{
        .name = "snail-minimal-metal-check",
        .linkage = .static,
        .root_module = makeModule(b, modules, hb_src, check_target),
    });
    // Installing the archive forces real machine-code emission (a bare
    // dependency would run analysis-only via -fno-emit-bin).
    check_step.dependOn(&b.addInstallArtifact(check_lib, .{}).step);

    if (b.graph.host.result.os.tag == .macos) {
        const mod = makeModule(b, modules, hb_src, b.resolveTargetQuery(.{}));
        // nix's hermetic zig does not autodetect the Apple SDK ("unable to
        // find framework ... searched paths: none"), so resolve it the way
        // a system zig would: honor SDKROOT when the caller set it, else
        // ask xcrun. Without either, linking fails with the same message
        // as before — plus this comment to explain it.
        const sdk: ?[]const u8 = b.graph.environ_map.get("SDKROOT") orelse blk: {
            var code: u8 = 0;
            const out = b.runAllowFail(&.{ "/usr/bin/xcrun", "--show-sdk-path" }, &code, .ignore) catch break :blk null;
            if (code != 0) break :blk null;
            const trimmed = std.mem.trim(u8, out, " \t\r\n");
            break :blk if (trimmed.len == 0) null else trimmed;
        };
        if (sdk) |s| {
            mod.addFrameworkPath(.{ .cwd_relative = b.pathJoin(&.{ s, "System", "Library", "Frameworks" }) });
            mod.addLibraryPath(.{ .cwd_relative = b.pathJoin(&.{ s, "usr", "lib" }) });
        }
        mod.linkFramework("Metal", .{});
        mod.linkFramework("Foundation", .{});
        mod.linkFramework("CoreGraphics", .{});
        const exe = b.addExecutable(.{ .name = "snail-minimal-metal", .root_module = mod });
        const run = b.addRunArtifact(exe);
        // Rendering output changes with the shaders/scene, not just the exe.
        run.has_side_effects = true;
        run_step.dependOn(&run.step);
    } else {
        const fail = b.addFail("run-minimal-metal needs a macOS host (this build has no Metal runtime); on this host use `zig build check-metal-demo`");
        run_step.dependOn(&fail.step);
    }
}

fn addMinimalWgpuStep(
    b: *std.Build,
    config: BuildConfig,
    modules: ProjectModules,
) void {
    const mod = b.createModule(.{
        .root_source_file = b.path("dev/demo/app/minimal_wgpu.zig"),
        .target = config.target,
        .optimize = .ReleaseFast,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = modules.snail },
            .{ .name = "snail_shaders", .module = modules.shaders_wgsl },
        },
    });
    // wgpu-native ships no pkg-config file; the nix shell exports the split
    // dev/lib outputs (see shell.nix). Fall back to plain system linking when
    // the variables are absent.
    if (b.graph.environ_map.get("WGPU_NATIVE_INCLUDE")) |include_dir| {
        mod.addIncludePath(.{ .cwd_relative = include_dir });
    }
    if (b.graph.environ_map.get("WGPU_NATIVE_LIB")) |lib_dir| {
        mod.addLibraryPath(.{ .cwd_relative = lib_dir });
        // macOS: no LD_LIBRARY_PATH analog survives into the child process
        // (SIP scrubs DYLD_*), so bake the nix store lib dir into the rpath.
        mod.addRPath(.{ .cwd_relative = lib_dir });
    }
    mod.linkSystemLibrary("wgpu_native", .{ .use_pkg_config = .no });
    const exe = b.addExecutable(.{ .name = "snail-minimal-wgpu", .root_module = mod });
    const run = b.addRunArtifact(exe);
    const step = b.step("run-minimal-wgpu", "Render the one-file public-API WebGPU example to zig-out/minimal-wgpu.tga");
    step.dependOn(&run.step);
}

pub fn build(b: *std.Build) void {
    const config = parseBuildConfig(b);
    // The native-Slang module catalog. Callers authoring their own Slang
    // families `import` snail's caller-facing modules (see the "Custom
    // families" section of src/snail/shader/slang/README.md for the
    // public module list and the pattern) and pass this path to slangc via
    // `-I`; the in-tree reference is the game demo's material family
    // (dev/demo/game/slang/game_material.slang).
    b.addNamedLazyPath("snail_slang", b.path(slang_shaders.module_dir));
    const assets_mod = b.createModule(.{ .root_source_file = b.path("assets/assets.zig") });
    const snail_mod = addSnailModule(b, config);
    const raster_mod = createRasterModule(b, config.target, config.optimize, snail_mod, null, null, "snail-raster");
    const support_mod = createSupportModule(b, config.target, config.optimize, snail_mod, assets_mod);
    const vk_shaders_mod = vulkan_shaders.createModule(b);
    const demo_vulkan_types_mod = createDemoVulkanTypesModule(b, config.target, config.optimize);
    // The whole generated-shader matrix as lazy Run steps; only consumers
    // of a generated-shaders module (or the demo Vulkan/game SPIR-V legs)
    // depend on them, so `zig build` targets that never touch generated
    // shaders never need slangc. Each module scopes the one
    // accessor API to a target subset, so every consumer generates only
    // the targets it embeds (the aggregate stays the published
    // `snail-shaders` module and the test root).
    const shader_artifacts = slang_shaders.collectArtifacts(b);
    // The aggregate module (contract tests) runs the artifact validations
    // (naga over the subpixel WGSL); consumer scopes below do not.
    const generated_shaders = slang_shaders.createGeneratedModuleOpts(b, "snail-shaders", shader_artifacts, &.{ .spirv, .wgsl, .hlsl, .msl, .glsl330, .gles300 }, true);

    // Vulkan/SPIR-V-only scope for consumers that render exclusively through
    // SPIR-V (e.g. a Vulkan backend). It generates only the SPIR-V artifacts
    // and skips validation, so such consumers never pull in WGSL/GL/HLSL/MSL
    // generation or the `naga` toolchain requirement. Same accessor API +
    // reflection as every other scope.
    _ = slang_shaders.createGeneratedModule(b, "snail-shaders-vk", shader_artifacts, &.{.spirv});

    const modules = ProjectModules{
        .assets = assets_mod,
        .support = support_mod,
        .vk_shaders = vk_shaders_mod,
        .demo_vulkan_types = demo_vulkan_types_mod,
        .snail = snail_mod,
        .raster = raster_mod,
        .shaders = generated_shaders.module,
        .shaders_root = generated_shaders.root,
        .shaders_gl = slang_shaders.createGeneratedModule(b, "snail-shaders-gl", shader_artifacts, &.{ .glsl330, .gles300 }).module,
        .shaders_glsl330 = slang_shaders.createGeneratedModule(b, "snail-shaders-glsl330", shader_artifacts, &.{.glsl330}).module,
        .shaders_wgsl = slang_shaders.createGeneratedModule(b, "snail-shaders-wgsl", shader_artifacts, &.{.wgsl}).module,
        .shaders_hlsl = slang_shaders.createGeneratedModule(b, "snail-shaders-hlsl", shader_artifacts, &.{.hlsl}).module,
        .shaders_msl = slang_shaders.createGeneratedModule(b, "snail-shaders-msl", shader_artifacts, &.{.msl}).module,
        .shaders_reflection = slang_shaders.createGeneratedModule(b, "snail-shaders-reflection", shader_artifacts, &.{}).module,
        .reflection_generated = shader_artifacts.reflection_generated,
        .game_material_gl = shader_artifacts.game,
    };

    addTestSteps(b, config, modules);
    addScreenshotSteps(b, config, modules);
    addInteractiveDemoStep(b, config, modules);
    addTerminalDemoStep(b, config, modules);
    addGameDemoStep(b, config, modules);
    addMinimalGlStep(b, config, modules);
    addMinimalWgpuStep(b, config, modules);
    addMinimalD3d11Step(b, modules);
    addMinimalMetalStep(b, modules);
    addPerfSteps(b, config, modules);
    slang_shaders.addGenShadersStep(b, shader_artifacts);
    addCiSteps(b);
}

fn addPerfSteps(b: *std.Build, config: BuildConfig, modules: ProjectModules) void {
    const prep_mod = b.createModule(.{
        .root_source_file = b.path("dev/tools/perf/prep.zig"),
        .target = config.target,
        .optimize = config.optimize,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = modules.snail },
        },
    });
    const prep_exe = b.addExecutable(.{ .name = "snail-perf-prep", .root_module = prep_mod });

    const raster_perf_mod = b.createModule(.{
        .root_source_file = b.path("dev/tools/perf/raster.zig"),
        .target = config.target,
        .optimize = config.optimize,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = modules.snail },
            .{ .name = "snail-raster", .module = modules.raster },
        },
    });
    const raster_perf_exe = b.addExecutable(.{ .name = "snail-perf-raster", .root_module = raster_perf_mod });

    const glsl_perf_mod = b.createModule(.{
        .root_source_file = b.path("dev/tools/perf/glsl.zig"),
        .target = config.target,
        .optimize = config.optimize,
        .link_libc = true,
        .imports = &.{
            .{ .name = "assets", .module = modules.assets },
            .{ .name = "snail", .module = modules.snail },
            .{ .name = "snail_shaders", .module = modules.shaders_glsl330 },
        },
    });
    glsl_perf_mod.linkSystemLibrary("EGL", .{});
    glsl_perf_mod.linkSystemLibrary("OpenGL", .{});
    const glsl_perf_exe = b.addExecutable(.{ .name = "snail-perf-glsl", .root_module = glsl_perf_mod });

    const install_perf = b.step("install-perf", "Install the consumer-facing performance regression runners");
    install_perf.dependOn(&b.addInstallArtifact(prep_exe, .{}).step);
    install_perf.dependOn(&b.addInstallArtifact(raster_perf_exe, .{}).step);
    install_perf.dependOn(&b.addInstallArtifact(glsl_perf_exe, .{}).step);
}