onedrop_hlsl/

lib.rs

//! HLSL to WGSL Translation
//!
//! Pragmatic, MilkDrop-2-targeted translator. The MD2 user shader body lives
//! inside a `shader_body { ... }` block, samples the previous frame via
//! `tex2D` / `GetPixel` / `GetBlur1..3`, and uses HLSL-style typed local
//! declarations (`float2 uv2;`). The translator turns that into a WGSL
//! fragment-body fragment that the codegen wrapper can paste inside its
//! `fs_main`.
//!
//! The rewrites are still string-driven (no AST) — but they understand the
//! MD2 conventions enough to land the dominant cases.

pub mod ast;
pub mod lex;
pub mod parse;
pub mod rewrite;
mod texture_plan;
pub mod types;

use regex::Regex;
use std::sync::LazyLock;
use thiserror::Error;

pub use texture_plan::{
    MAX_USER_TEXTURE_SLOTS, TextureBindingPlan, TextureSlot, UserSamplerRef, scan_user_samplers,
    user_texture_binding_name,
};
pub use types::{SymbolTable, WgslType};

use std::fmt::Write as _;
use texture_plan::{noise_sampler_for, replace_texture_sampling_with_plan};

// ---------------------------------------------------------------------------
// MD2 outer-wrapper stripping
// ---------------------------------------------------------------------------

/// `shader_body` keyword optionally followed by whitespace/newlines and `{`.
/// We then balance braces ourselves to recover the body — a regex alone
/// can't do nested-brace balancing reliably.
static SHADER_BODY_OPEN: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"shader_body\s*\{").unwrap());

/// MD2 ships warp/comp shaders wrapped in a `shader_body { ... }` block. The
/// codegen wrapper pastes the user code inside its own `fs_main { ... }`, so
/// the outer wrapper has to come off first — otherwise WGSL sees a stray
/// identifier (`shader_body`) followed by `{` and fails with
/// `expected assignment or increment/decrement, found "{"`.
///
/// If the input has no `shader_body` wrapper (synthetic test shaders, or a
/// preset that already inlines the body), the input is returned unchanged.
fn strip_shader_body_wrapper(src: &str) -> String {
    let Some(open) = SHADER_BODY_OPEN.find(src) else {
        return src.to_string();
    };
    let body_start = open.end();
    let bytes = src.as_bytes();
    let mut depth = 1usize;
    let mut i = body_start;
    while i < bytes.len() {
        match bytes[i] {
            b'{' => depth += 1,
            b'}' => {
                depth -= 1;
                if depth == 0 {
                    // Replace the whole `shader_body { ... }` span (incl. the
                    // closing brace) with just the inner body — keeps any
                    // trailing comment / whitespace after it intact.
                    let mut out = String::with_capacity(src.len());
                    out.push_str(&src[..open.start()]);
                    out.push_str(&src[body_start..i]);
                    out.push_str(&src[i + 1..]);
                    return out;
                }
            }
            // Skip over `//` line comments and `/* */` block comments so a
            // brace inside a comment doesn't confuse the depth counter.
            b'/' if i + 1 < bytes.len() && bytes[i + 1] == b'/' => {
                while i < bytes.len() && bytes[i] != b'\n' {
                    i += 1;
                }
                continue;
            }
            b'/' if i + 1 < bytes.len() && bytes[i + 1] == b'*' => {
                i += 2;
                while i + 1 < bytes.len() && !(bytes[i] == b'*' && bytes[i + 1] == b'/') {
                    i += 1;
                }
                i += 2;
                continue;
            }
            _ => {}
        }
        i += 1;
    }
    // Unbalanced braces — leave it alone and let naga produce the error.
    src.to_string()
}

// ---------------------------------------------------------------------------
// Pre-compiled regex patterns
// ---------------------------------------------------------------------------

/// Strips leading zeros from integer literals (HLSL allows `02` for `2`,
/// WGSL rejects them with `invalid numeric literal format`). Targets only
/// integer literals — `0.5` and `0` and `100` are untouched because the
/// pattern requires `\b0+` followed by another decimal digit (so `0.` and
/// `0)` never match).
static LEADING_ZERO_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"\b0+([0-9])").unwrap());

static SEMANTICS_REGEX: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r":\s*[A-Z_][A-Z0-9_]*").unwrap());

/// HLSL typed local declaration, post type-substitution. The whole `<TYPE>
/// <decls>;` statement is captured; the declarator list is then expanded
/// into one WGSL `var` per name. Examples:
///   `f32 gx1 = a;`                →  `var gx1: f32 = a;`
///   `vec2<f32> uv2;`              →  `var uv2: vec2<f32>;`
///   `vec3<f32> ret1, neu, crisp;` →  `var ret1: vec3<f32>; var neu: vec3<f32>; var crisp: vec3<f32>;`
///
/// Anchored to the start of a (multi-line-aware) line so we don't confuse the
/// type tokens that appear as function return types or constructor names.
/// The captured group excludes both `;` (the terminator) and `{` (function
/// body open brace) — the latter stops the greedy match cold when the
/// pattern would otherwise swallow a function signature plus part of its
/// body up to the first `;` inside. The closure also calls
/// [`is_function_signature`] for the residual case where the regex still
/// matches (e.g., one-liner functions).
static LOCAL_DECL_REGEX: LazyLock<Regex> = LazyLock::new(|| {
    Regex::new(
        r"(?m)^(\s*)(f32|i32|bool|vec2<f32>|vec3<f32>|vec4<f32>|vec2<bool>|vec3<bool>|vec4<bool>|mat4x4<f32>|mat3x3<f32>|mat2x2<f32>)\s+([^;{]+);",
    )
    .unwrap()
});

/// Normalise `;<space>TYPE` to `;\nTYPE` so the line-anchored
/// [`LOCAL_DECL_REGEX`] sees each declaration on its own line. The Isosceles
/// preset (and a handful of MD2 packs that compress kaleidoscope state) put
/// multiple typed locals on a single source line:
///
/// ```text
/// float2 cntr = float2(q13,q14); float sin = q11; float cos = q12; float scale = q15;
/// ```
///
/// Without this pre-pass, only the first decl converted to a `var` — the
/// rest stayed as raw HLSL and tripped naga with
/// `expected assignment or increment/decrement; found 'sin'`. Safe for
/// `for(f32 i = 0; …)` because the first `;` inside the parens is followed
/// by an expression (the loop condition), never by a type keyword.
///
/// We also split when the type is glued to `{` (function-body opening brace,
/// conditional/loop body), and recognise vec types ending in `>`. A naive
/// `\b` boundary check fails after `vec2<f32>` because `>` is already a
/// non-word char; vec-typed declarations grouped behind any prior `; <decl>`
/// would otherwise stay un-rewritten and naga would report `expected
/// assignment or increment/decrement; found 'uvc'`. Requiring an
/// identifier-start `[A-Za-z_]` after the type+space rules out false
/// positives on constructor calls like `vec3<f32>(0)`.
static INLINE_DECL_SPLIT_REGEX: LazyLock<Regex> = LazyLock::new(|| {
    Regex::new(
        r"([;{])[ \t]*(f32|i32|bool|vec2<f32>|vec3<f32>|vec4<f32>|vec2<bool>|vec3<bool>|vec4<bool>|mat4x4<f32>|mat3x3<f32>|mat2x2<f32>)[ \t]+([A-Za-z_])",
    )
    .unwrap()
});

/// HLSL `sampler foo;` / `texture foo;` declarations at module scope. The
/// codegen wrapper provides the actual texture/sampler bindings, so user
/// declarations are redundant — and they confuse the WGSL parser when they
/// land inside `fs_main`. Stripped out wholesale.
///
/// Also matches the **comma-list** form `sampler a, b, c;` that a number
/// of presets ship as a stylistic shortcut. A simpler regex stopping at
/// the first identifier would let the trailing comma list survive as
/// orphan statements `b; c;` that trip the WGSL parser with
/// `expected assignment or increment/decrement; found 'sampler_fw_rand01'`.
static SAMPLER_DECL_REGEX: LazyLock<Regex> = LazyLock::new(|| {
    Regex::new(r"(?m)^\s*(?:sampler|texture|texture2D|texture3D|sampler2D|sampler3D)\s+[A-Za-z_][A-Za-z0-9_]*(?:\s*,\s*[A-Za-z_][A-Za-z0-9_]*)*\s*;").unwrap()
});

/// Preprocessor directives (`#define`, `#include`, `#pragma`, …). HLSL
/// presets occasionally use them; WGSL has no preprocessor, so we strip
/// the whole line.
static PREPROC_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"(?m)^\s*#[^\n]*$").unwrap());

/// HLSL storage-class qualifiers — strip when they appear as a leading
/// word in a declaration. `static const` is a common HLSL pattern for
/// "function-scope compile-time constant", but WGSL inside a function
/// uses `let` (or `const` at module scope only). Stripping both lets
/// `rewrite_local_declarations` turn the rest into a regular `var`.
static STORAGE_CLASS_REGEX: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"\b(static|uniform|extern)\b\s*").unwrap());

/// HLSL `const TYPE NAME` at start of a typed local declaration.
/// We strip `const ` only when followed by a recognised HLSL type token
/// — leaves WGSL module-level `const` (which doesn't appear in user
/// shader bodies anyway) alone.
static CONST_TYPE_REGEX: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"\bconst\s+(float[1-4]?(?:x[1-4])?|int|bool)\b").unwrap());

/// Postfix `<ident>++` and `<ident>--` (HLSL increment/decrement).
/// WGSL has no postfix operators; we rewrite to the equivalent
/// compound assignment `<ident> = <ident> + 1` only at statement
/// boundaries (`;` or `)`) so expression-position uses like `a[i++]`
/// don't get mangled. Real preset pattern: `n++;` at end of a
/// per-iteration loop.
static POSTFIX_INC_REGEX: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"\b([A-Za-z_][A-Za-z0-9_]*)\s*\+\+\s*([;)])").unwrap());
static POSTFIX_DEC_REGEX: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"\b([A-Za-z_][A-Za-z0-9_]*)\s*--\s*([;)])").unwrap());

#[derive(Error, Debug)]
pub enum TranslationError {
    #[error("Translation error: {0}")]
    Translation(String),

    #[error("Unsupported HLSL feature: {0}")]
    Unsupported(String),
}

pub type Result<T> = std::result::Result<T, TranslationError>;

/// Translate HLSL shader code to WGSL.
///
/// The pipeline is intentionally linear:
/// 1. strip the MD2 `shader_body { ... }` outer wrapper,
/// 2. type-substitute (`float4 → vec4<f32>`, …),
/// 3. function-substitute (`lerp → mix`, `tex2D → textureSample`, …),
/// 4. rewrite typed local declarations into WGSL `var ident: T = …;` form,
/// 5. strip HLSL semantics (`: POSITION`, …).
pub fn translate_shader(hlsl: &str) -> Result<String> {
    translate_shader_with_plan(hlsl, &TextureBindingPlan::empty())
}

/// Same as [`translate_shader`], but routes unrecognised `tex2D` sampler names
/// through the supplied [`TextureBindingPlan`]. Preset authors reference
/// disk-loaded textures via `sampler sampler_<NAME>;` + `tex2D(sampler_<NAME>,
/// uv)`; the renderer scans the HLSL, builds a plan that resolves each name to
/// a slot in the comp pipeline's user-texture binding array, and threads it
/// through here so the emitted WGSL points at the right binding.
///
/// Empty plan ≡ legacy behaviour: unrecognised samplers fall back to
/// `sampler_main` with a `/*was: <name>*/` debug comment.
pub fn translate_shader_with_plan(hlsl: &str, plan: &TextureBindingPlan) -> Result<String> {
    // Stash the original input so the global-var hoist pass at the bottom
    // can re-parse it for `Item::GlobalVar` names. The rewriter chain
    // below shadows `hlsl`, and by the time we reach the hoist the AST
    // boundary between top-level globals and shader_body locals is gone
    // (everything is one flat translated body string).
    let hlsl_for_ast = hlsl;

    // AST-driven pre-passes. Each one parses the HLSL, walks the AST,
    // and writes targeted text edits back; if parsing fails the input
    // passes through unchanged. The downstream regex pipeline then sees
    // a slightly friendlier source. Order matters: array globals must be
    // lowered before the regex `replace_types` runs, and the binop / UV
    // passes are stable under each other so the chain order is fixed in
    // `rewrite::apply_all`.
    let hlsl = rewrite::apply_all(hlsl);
    let mut wgsl = strip_shader_body_wrapper(&hlsl);
    wgsl = comment_out_prose_lines(&wgsl);
    wgsl = strip_preprocessor(&wgsl);
    wgsl = strip_sampler_declarations(&wgsl);
    wgsl = strip_storage_class_qualifiers(&wgsl);
    wgsl = rewrite_postfix_inc_dec(&wgsl);
    wgsl = replace_types(&wgsl);
    wgsl = replace_functions(&wgsl);
    wgsl = replace_texture_sampling_with_plan(&wgsl, plan);
    wgsl = rewrite_tex3d_calls(&wgsl);
    wgsl = rewrite_local_declarations(&wgsl);
    wgsl = brace_up_single_statement_blocks(&wgsl);
    wgsl = dedup_var_declarations(&wgsl);
    wgsl = replace_statement_commas(&wgsl);
    wgsl = replace_semantics(&wgsl);

    // Type-aware passes run last — they need the source to look like
    // valid WGSL `var` declarations with explicit type annotations,
    // which only the rewrites above produce. The symbol table is built
    // once and reused so the truncation pass sees the same view of
    // locals as the broadcast pass. The broadcast pass recurses into
    // nested call args itself, so a single sweep is enough.
    let table = types::SymbolTable::from_source(&wgsl);
    wgsl = types::inject_broadcasts(&wgsl, &table);
    wgsl = types::inject_truncations(&wgsl, &table);
    wgsl = types::inject_assignment_coercions(&wgsl, &table);
    // Swizzle LHS rewrite runs after assignment coercion so the LHS view
    // is already a single bare ident statement (no nested cast inserted
    // between target and `.xy`). Runs before validation can flag
    // `invalid left-hand side of assignment`.
    wgsl = types::inject_swizzle_assignments(&wgsl, &table);

    // Lift module-scope user functions LAST so the function body has
    // already been through every regex rewrite and type-aware pass
    // (decl conversion, broadcast, truncation, assignment coercion,
    // swizzle reconstruction). After lift, the body emits as a
    // syntactically valid WGSL `fn` and the wrapper places it at module
    // scope on the other side of `LIFTED_FN_SENTINEL`.
    let lifted = lift_user_functions(&mut wgsl);

    // Hoist pre-`shader_body` global variable declarations (parsed as
    // `Item::GlobalVar` in the AST) from the fragment body to module
    // scope. Lifted user functions (now at module scope) routinely
    // reference these — `float3 t = float3(q20, q23, q26)` declared at
    // the top of the preset, then used inside a lifted `float3 project(...)`
    // would otherwise hit "no definition in scope for identifier: `t`"
    // when the parser walks the lifted body and the surrounding fs_main
    // locals are out of reach.
    //
    // Implementation: re-parse the original HLSL to collect the names
    // of top-level `GlobalVar` items, scan the translated body for
    // `var NAME: TYPE [= INIT];` lines whose name is in that set, emit a
    // module-scope `var<private> NAME: TYPE;` declaration, and replace the
    // body line with `NAME = INIT;` (or drop entirely when there's no init).
    let hoisted_globals = hoist_global_vars(&mut wgsl, hlsl_for_ast);

    let module_scope = match (lifted.is_empty(), hoisted_globals.is_empty()) {
        (true, true) => return Ok(wgsl),
        (false, true) => lifted,
        (true, false) => hoisted_globals,
        (false, false) => format!("{lifted}\n{hoisted_globals}"),
    };
    Ok(format!("{module_scope}\n{LIFTED_FN_SENTINEL}\n{wgsl}"))
}

/// Re-parse `hlsl` (the original input, before any rewriter touched it)
/// and return a map of `name → wgsl_type` for top-level `Item::GlobalVar`
/// items. Used by [`hoist_global_vars`] to decide which body-level `var`
/// declarations belong at module scope.
///
/// Skips any name that collides with a WGSL builtin function. A few
/// MD2 authors declare locals named `sin` / `cos` / `pow` / `dot` etc.
/// (the Isosceles preset's kaleidoscope state line) — hoisting these to
/// module scope as `var<private>` would shadow the builtin globally,
/// breaking every other site that calls `sin(x)` as a function. Leaving
/// them as fs_main locals preserves the per-scope shadowing the author
/// expected.
///
/// Returned types are in WGSL form (`vec2<f32>`, `mat3x3<f32>`, …) so the
/// hoist pass can compare them against the in-body `var X: T` lines and
/// only transform exact-type matches — re-declarations like `float2
/// rss,uv2;` at top level followed by `float3 uv2 = …;` in `shader_body`
/// are shadowing the global and must keep their local declaration intact.
fn collect_global_var_types(hlsl: &str) -> std::collections::HashMap<String, String> {
    // Pre-strip storage-class qualifiers (`uniform`, `extern`, ...) the HLSL
    // parser doesn't recognise — they're cosmetic in MD2 user shaders and
    // would otherwise break the parse, dropping every following GlobalVar
    // from the AST. Real-world hit: `Se7enSlasher - Texture Distortion …`
    // has `uniform float caval; … float3 col;` and the `uniform` line
    // failed parse, so `col` was never registered for hoisting.
    let cleaned = strip_storage_class_qualifiers(hlsl);
    let Ok(tu) = parse::parse_hlsl(&cleaned) else {
        return std::collections::HashMap::new();
    };
    tu.items
        .iter()
        .filter_map(|i| match i {
            ast::Item::GlobalVar(g) if !is_wgsl_builtin_function_name(&g.name) => {
                hlsl_type_to_wgsl(&g.ty.name).map(|wgsl_ty| (g.name.clone(), wgsl_ty.to_string()))
            }
            _ => None,
        })
        .collect()
}

/// Map an HLSL type name (`float`, `float2`, `int3`, `float3x3`, …) to
/// its WGSL equivalent (`f32`, `vec2<f32>`, `vec3<f32>`, `mat3x3<f32>`, …).
/// Returns `None` for types the hoist pass shouldn't touch (e.g. user
/// struct names, samplers — these don't show up as `GlobalVar` anyway,
/// but be defensive).
fn hlsl_type_to_wgsl(name: &str) -> Option<&'static str> {
    Some(match name {
        "float" | "int" | "half" | "double" => "f32",
        "float2" | "int2" | "half2" | "double2" => "vec2<f32>",
        "float3" | "int3" | "half3" | "double3" => "vec3<f32>",
        "float4" | "int4" | "half4" | "double4" => "vec4<f32>",
        "float2x2" => "mat2x2<f32>",
        "float3x3" => "mat3x3<f32>",
        "float4x4" => "mat4x4<f32>",
        "bool" => "bool",
        _ => return None,
    })
}

/// `true` when `name` collides with a WGSL builtin function. List
/// covers the subset MD2 user shaders actually invoke; anything outside
/// this set isn't worth worrying about (real authors don't shadow
/// `inverseSqrt`).
fn is_wgsl_builtin_function_name(name: &str) -> bool {
    matches!(
        name,
        "abs"
            | "acos"
            | "asin"
            | "atan"
            | "atan2"
            | "ceil"
            | "clamp"
            | "cos"
            | "cosh"
            | "cross"
            | "degrees"
            | "distance"
            | "dot"
            | "exp"
            | "exp2"
            | "floor"
            | "fract"
            | "length"
            | "log"
            | "log2"
            | "max"
            | "min"
            | "mix"
            | "normalize"
            | "pow"
            | "radians"
            | "reflect"
            | "refract"
            | "round"
            | "saturate"
            | "select"
            | "sign"
            | "sin"
            | "sinh"
            | "smoothstep"
            | "sqrt"
            | "step"
            | "tan"
            | "tanh"
            | "transpose"
            | "trunc"
    )
}

/// Hoist top-level user globals to module scope.
///
/// Scans `body` for `var NAME: TYPE [= INIT];` lines and, when `NAME`
/// matches a top-level `Item::GlobalVar` from `hlsl_src` **and** the
/// declared type matches that global's type, emits a module-scope
/// `var<private> NAME: TYPE;` declaration. The body line is rewritten to a
/// bare `NAME = INIT;` (assignment runs inside `fs_main` so it can still
/// reference `q1..q32` and other `var<private>` state seeded by the
/// wrapper) or removed entirely when there's no initializer.
///
/// The TYPE match is what protects a corpus shape like
/// `float2 rs2,rs0,rss,uv2; … shader_body { float3 uv2 = …; }`: at top
/// level `uv2` is `vec2<f32>` (the hoist target), but the in-body
/// `var uv2: vec3<f32> = …;` line is a shadowing re-declaration of a
/// different type and must keep its local `var` form so the in-body
/// `uv2` ends up as a `vec3<f32>` local. Without this guard, the bare
/// regex match would strip the `var` from the shadowing decl and the
/// assignment would silently target the `vec2` module-scope global,
/// producing downstream `InvalidStoreTypes` errors.
///
/// Returns the joined module-scope declarations (`""` if none).
fn hoist_global_vars(body: &mut String, hlsl_src: &str) -> String {
    let globals = collect_global_var_types(hlsl_src);
    if globals.is_empty() {
        return String::new();
    }

    static VAR_DECL_REGEX: LazyLock<Regex> = LazyLock::new(|| {
        Regex::new(
            r"\bvar\s+([A-Za-z_][A-Za-z0-9_]*)\s*:\s*([A-Za-z_][A-Za-z0-9_<>]*)\s*(=\s*[^;]+)?;",
        )
        .unwrap()
    });

    let mut hoisted = String::new();
    let mut seen: std::collections::HashSet<String> = Default::default();
    let mut new_body = String::with_capacity(body.len());
    let mut last_end = 0usize;

    for cap in VAR_DECL_REGEX.captures_iter(body) {
        let full = cap.get(0).unwrap();
        let name = cap.get(1).unwrap().as_str();
        let ty = cap.get(2).unwrap().as_str();
        let Some(expected_ty) = globals.get(name) else {
            continue;
        };
        if expected_ty.as_str() != ty {
            // Same name, different type — the user is shadowing the
            // global with a re-declaration. Leave the local `var X: T`
            // intact so the shadow stays in fs_main scope.
            continue;
        }
        let init = cap.get(3).map(|m| m.as_str());

        // Emit one module-scope declaration per global, even if the body
        // had two `var X: T;` lines for the same name (the dedup pass
        // mostly handles this, but be defensive).
        if seen.insert(name.to_string()) {
            let _ = writeln!(&mut hoisted, "var<private> {name}: {ty};");
        }

        new_body.push_str(&body[last_end..full.start()]);
        if let Some(init) = init {
            // `init` is `"= <expr>"`; trim the leading `=` and whitespace.
            let init_value = init.trim_start_matches('=').trim_start();
            let _ = write!(&mut new_body, "{name} = {init_value};");
        }
        // No init → drop the body line; the module-scope `var<private>`
        // is uninitialised and any later in-body `NAME = ...;` assigns it.
        last_end = full.end();
    }
    new_body.push_str(&body[last_end..]);
    *body = new_body;

    hoisted
}

/// Marker line that separates module-scope user functions (lifted by
/// [`lift_user_functions`]) from the fragment body inside the translated
/// output. The codegen wrapper splits on this marker: text before goes
/// before `fs_main`, text after goes inside it.
pub const LIFTED_FN_SENTINEL: &str = "// __ONEDROP_LIFTED_FNS_END__";

/// Find HLSL-shaped function definitions (`<TYPE> <name>(...) { ... }`)
/// at depth 0 in the translated body, rewrite each signature to WGSL
/// shape (`fn name(arg: TYPE, …) -> TYPE { ... }`), and remove them from
/// `src` in place. The lifted functions are returned as a single string
/// concatenated in source order — `wrap_user_comp_shader_with_plan`
/// places it before `fs_main`.
///
/// Preset pattern this unblocks (real example from
/// `Geiss - Explosion 3 nz+ enscarpment via lateral hosations.milk`):
///
/// ```text
/// vec2<f32> gradBlur1(vec2<f32> domain, vec2<f32> d, vec3<f32> filter) {
///    vec3<f32> dx = (2*GetBlur1(domain + vec2<f32>(1,0)*d) - 2*GetBlur1(domain - vec2<f32>(1,0)*d));
///    ...
///    return 0.5 * vec2<f32>(...);
/// }
/// shader_body { ret += gradBlur1(uv, vec2<f32>(0.5)/aspect.xy, vec3<f32>(0.5,0.5,0.5)); }
/// ```
///
/// After lifting:
/// ```text
/// fn gradBlur1(domain: vec2<f32>, d: vec2<f32>, filter: vec3<f32>) -> vec2<f32> {
///    var dx: vec3<f32> = (2*GetBlur1(domain + vec2<f32>(1,0)*d) - 2*GetBlur1(domain - vec2<f32>(1,0)*d));
///    ...
///    return 0.5 * vec2<f32>(...);
/// }
/// ```
///
/// Functions that reference fs_main locals (`texsize`, `q1`, …) will fail
/// to validate after lifting since those locals don't exist at module
/// scope — we accept that limitation here; a future pass may pass them
/// explicitly.
fn lift_user_functions(src: &mut String) -> String {
    let bytes = src.as_bytes();
    let mut lifted = String::new();
    let mut residual = String::with_capacity(src.len());
    let mut i = 0usize;

    while i < bytes.len() {
        // Scan for a candidate function signature at the start of a line
        // (after whitespace). We require it to begin at depth 0; the
        // outer loop never enters function bodies because we skip past
        // them whole when we recognise one.
        if let Some((next_i, lifted_fn)) = try_extract_user_function(src.as_str(), i) {
            lifted.push_str(&lifted_fn);
            lifted.push('\n');
            i = next_i;
            continue;
        }
        residual.push(bytes[i] as char);
        i += 1;
    }

    *src = residual;
    lifted
}

/// Try to match a single HLSL-shaped function definition starting at byte
/// position `start` (after leading whitespace). Returns the byte position
/// just past the closing `}` and the rewritten WGSL function text.
/// Returns `None` if no signature matches — caller advances by 1 byte.
fn try_extract_user_function(src: &str, start: usize) -> Option<(usize, String)> {
    let bytes = src.as_bytes();

    // Skip leading whitespace + newlines on the current line.
    let mut i = start;
    while i < bytes.len() && bytes[i].is_ascii_whitespace() {
        i += 1;
    }
    if i >= bytes.len() {
        return None;
    }

    // Require we're at a line start — function defs are top-level, never
    // mid-expression. Walk back from `i` to confirm only whitespace until
    // a newline or start-of-input.
    let mut back = i;
    while back > 0 && bytes[back - 1] != b'\n' {
        if !bytes[back - 1].is_ascii_whitespace() {
            return None;
        }
        back -= 1;
    }

    // Parse the return type: one of the WGSL type tokens.
    let (ret_type, after_ty) = parse_wgsl_function_return_type(src, i)?;
    let mut j = after_ty;

    while j < bytes.len() && bytes[j].is_ascii_whitespace() {
        j += 1;
    }

    // Function name: identifier.
    let name_start = j;
    while j < bytes.len() && (bytes[j].is_ascii_alphanumeric() || bytes[j] == b'_') {
        j += 1;
    }
    if j == name_start {
        return None;
    }
    let name = &src[name_start..j];

    while j < bytes.len() && bytes[j].is_ascii_whitespace() {
        j += 1;
    }
    if j >= bytes.len() || bytes[j] != b'(' {
        return None;
    }
    j += 1;
    let params_start = j;

    // Balance `(...)`.
    let mut depth = 1i32;
    while j < bytes.len() {
        match bytes[j] {
            b'(' => depth += 1,
            b')' => {
                depth -= 1;
                if depth == 0 {
                    break;
                }
            }
            _ => {}
        }
        j += 1;
    }
    if j >= bytes.len() {
        return None;
    }
    let params_text = &src[params_start..j];
    j += 1;

    while j < bytes.len() && bytes[j].is_ascii_whitespace() {
        j += 1;
    }
    if j >= bytes.len() || bytes[j] != b'{' {
        return None;
    }
    let body_open = j;
    j += 1;
    let mut depth = 1i32;
    while j < bytes.len() {
        match bytes[j] {
            b'{' => depth += 1,
            b'}' => {
                depth -= 1;
                if depth == 0 {
                    break;
                }
            }
            _ => {}
        }
        j += 1;
    }
    if j >= bytes.len() {
        return None;
    }
    let body = &src[body_open..=j];

    // Convert params to WGSL shape and shadow any that get reassigned in
    // the body. HLSL value-parameters are mutable (the body's `x = pow(x, k);`
    // overwrites them in place); WGSL parameters are `let`-bound and naga
    // rejects the assignment with "invalid left-hand side of assignment;
    // consider declaring `x` with `var` instead of `let`". For each param
    // the body writes to, we rename it to `<name>_md2arg` in the signature
    // and prepend `var <name>: <ty> = <name>_md2arg;` so existing reads /
    // writes against `<name>` in the body resolve to a mutable local.
    let parsed = parse_hlsl_params(params_text);
    let mut sig_parts = Vec::with_capacity(parsed.len());
    let mut shadow_prelude = String::new();
    for (ty, pname) in &parsed {
        if body_assigns_to(body, pname) {
            let renamed = format!("{pname}_md2arg");
            sig_parts.push(format!("{renamed}: {ty}"));
            shadow_prelude.push_str(&format!("var {pname}: {ty} = {renamed}; "));
        } else {
            sig_parts.push(format!("{pname}: {ty}"));
        }
    }
    let wgsl_params = sig_parts.join(", ");
    let wgsl_fn = if shadow_prelude.is_empty() {
        format!("fn {name}({wgsl_params}) -> {ret_type} {body}")
    } else {
        // body is `{ ... }` — insert shadow prelude right after the `{`.
        let inner = &body[1..body.len() - 1];
        format!("fn {name}({wgsl_params}) -> {ret_type} {{{shadow_prelude}{inner}}}")
    };

    Some((j + 1, wgsl_fn))
}

/// Whether `body` (a `{ ... }` WGSL block as text) contains an assignment
/// to a bare identifier matching `name`. Recognises plain `=`, compound
/// assignments (`+=`, `-=`, `*=`, `/=`, `%=`) and post-increment / decrement
/// (`++` / `--`); excludes the comparison operators `==`, `!=`, `<=`, `>=`.
/// Skips matches inside `//`-style line comments because the textual scan
/// would otherwise see a commented-out assignment as a real write.
fn body_assigns_to(body: &str, name: &str) -> bool {
    let bytes = body.as_bytes();
    let nb = name.as_bytes();
    if nb.is_empty() {
        return false;
    }
    let mut i = 0usize;
    let mut in_line_comment = false;
    while i + nb.len() <= bytes.len() {
        let c = bytes[i];
        if in_line_comment {
            if c == b'\n' {
                in_line_comment = false;
            }
            i += 1;
            continue;
        }
        if c == b'/' && bytes.get(i + 1) == Some(&b'/') {
            in_line_comment = true;
            i += 2;
            continue;
        }
        // Left boundary: previous char must not be identifier-continuation.
        let left_ok = i == 0 || {
            let p = bytes[i - 1];
            !(p.is_ascii_alphanumeric() || p == b'_')
        };
        if left_ok && &bytes[i..i + nb.len()] == nb {
            let after = i + nb.len();
            // Right boundary: not part of a longer identifier.
            let right_ok = bytes
                .get(after)
                .is_none_or(|c| !(c.is_ascii_alphanumeric() || *c == b'_'));
            if right_ok {
                // Walk past whitespace and look for an assignment-shaped tail.
                let mut k = after;
                while k < bytes.len() && (bytes[k] == b' ' || bytes[k] == b'\t') {
                    k += 1;
                }
                if k < bytes.len() {
                    let next = bytes[k];
                    match next {
                        b'=' => {
                            // `==` is a comparison; `=` alone is assignment.
                            if bytes.get(k + 1) != Some(&b'=') {
                                return true;
                            }
                        }
                        b'+' | b'-' => {
                            // `<name>++` / `<name>--` / `<name> += …`
                            if bytes.get(k + 1) == Some(&next) || bytes.get(k + 1) == Some(&b'=') {
                                return true;
                            }
                        }
                        b'*' | b'/' | b'%' => {
                            if bytes.get(k + 1) == Some(&b'=') {
                                return true;
                            }
                        }
                        b'.' => {
                            // `<name>.<swiz> = rhs` is also a write to the param
                            // (component-wise). Scan past `.<ident>` runs and
                            // any `[…]` indices, then check for an assignment.
                            let mut m = k;
                            while m < bytes.len() {
                                if bytes[m] == b'.' {
                                    m += 1;
                                    while m < bytes.len()
                                        && (bytes[m].is_ascii_alphanumeric() || bytes[m] == b'_')
                                    {
                                        m += 1;
                                    }
                                } else if bytes[m] == b'[' {
                                    let mut depth = 1i32;
                                    m += 1;
                                    while m < bytes.len() && depth > 0 {
                                        if bytes[m] == b'[' {
                                            depth += 1;
                                        } else if bytes[m] == b']' {
                                            depth -= 1;
                                        }
                                        m += 1;
                                    }
                                } else {
                                    break;
                                }
                            }
                            while m < bytes.len() && (bytes[m] == b' ' || bytes[m] == b'\t') {
                                m += 1;
                            }
                            if let Some(&nx) = bytes.get(m) {
                                if nx == b'=' && bytes.get(m + 1) != Some(&b'=') {
                                    return true;
                                }
                                if matches!(nx, b'+' | b'-' | b'*' | b'/' | b'%')
                                    && bytes.get(m + 1) == Some(&b'=')
                                {
                                    return true;
                                }
                            }
                        }
                        _ => {}
                    }
                }
            }
            i += nb.len();
            continue;
        }
        i += 1;
    }
    false
}

/// Parse an HLSL parameter list into (type, name) pairs in source order.
/// Same shape as [`convert_hlsl_params_to_wgsl`] but returns the structured
/// form so callers can decide per-param whether to rename / shadow.
fn parse_hlsl_params(params: &str) -> Vec<(String, String)> {
    if params.trim().is_empty() {
        return Vec::new();
    }
    let mut out = Vec::new();
    for raw in split_top_level_commas(params) {
        let part = raw.trim();
        if part.is_empty() {
            continue;
        }
        if let Some((ty, name)) = split_param(part) {
            // `lift_user_functions` runs after the regex pipeline, so
            // `params_text` already holds WGSL-shaped types (`f32`,
            // `vec2<f32>`, …); no type rewrite needed here.
            out.push((ty.to_string(), name.to_string()));
        }
    }
    out
}

/// Match one of the known WGSL types at byte position `i`. Returns the
/// canonical type text and the byte position immediately after it. `void`
/// is rejected — user comp shader functions always return a typed value
/// in MD2.
fn parse_wgsl_function_return_type(src: &str, i: usize) -> Option<(&'static str, usize)> {
    const TYPES: &[&str] = &[
        "vec4<f32>",
        "vec3<f32>",
        "vec2<f32>",
        "mat4x4<f32>",
        "mat3x3<f32>",
        "mat2x2<f32>",
        "f32",
        "i32",
        // `bool`-returning helpers (`bool mask_rectangle(...)` and friends)
        // need to lift too, otherwise the unmodified `bool foo(...)` line
        // lands in the WGSL output and the parser flags `foo` as
        // `expected assignment or increment/decrement`.
        "bool",
    ];
    let bytes = src.as_bytes();
    for ty in TYPES {
        let tb = ty.as_bytes();
        if i + tb.len() <= bytes.len() && &bytes[i..i + tb.len()] == tb {
            // Right boundary: next char must not be identifier-continuation.
            let next = bytes.get(i + tb.len()).copied();
            let is_id = next.is_some_and(|c| c.is_ascii_alphanumeric() || c == b'_');
            if !is_id {
                return Some((ty, i + tb.len()));
            }
        }
    }
    None
}

/// Split a single HLSL parameter declaration into `(type, name)`. The
/// type may contain `<...>` (`vec3<f32>`); we split on the last
/// whitespace at angle-depth 0.
fn split_param(decl: &str) -> Option<(&str, &str)> {
    let bytes = decl.as_bytes();
    let mut depth_angle = 0i32;
    let mut last_split = None;
    let mut i = 0usize;
    while i < bytes.len() {
        match bytes[i] {
            b'<' => depth_angle += 1,
            b'>' => depth_angle -= 1,
            b' ' | b'\t' | b'\n' | b'\r' if depth_angle == 0 => {
                // Track the last whitespace run; the param ident comes
                // after it.
                let mut j = i;
                while j < bytes.len() && bytes[j].is_ascii_whitespace() {
                    j += 1;
                }
                if j < bytes.len() && (bytes[j].is_ascii_alphabetic() || bytes[j] == b'_') {
                    last_split = Some((i, j));
                }
                i = j;
                continue;
            }
            _ => {}
        }
        i += 1;
    }
    let (ws_start, ident_start) = last_split?;
    let ty = decl[..ws_start].trim();
    let name = decl[ident_start..].trim();
    if ty.is_empty() || name.is_empty() {
        return None;
    }
    Some((ty, name))
}

fn replace_types(code: &str) -> String {
    let mut result = code.to_string();

    // Order matters: longer types first so `float4x4` is replaced before
    // `float4`, `float2x2` before `float2`, and `float4`/`float3`/`float2`/
    // `float1` before plain `float`. `float1` is HLSL's alias for `float`;
    // 33 of 168 preset comp shaders use it for single-channel loads
    // (`float1 dx = …`).
    //
    // Non-square matrix types. Corpus has many `float2x3` hits (and a
    // few `float4x3`) that a naive `float2`→`vec2<f32>` substring
    // substitution would mangle, leaving `vec2<f32>x3` and tripping the
    // WGSL parser with `expected ')'; found 'x3'`. We emit the matching
    // `matRxC<f32>` non-square type — the *constructor* call still won't
    // validate when args are passed as HLSL row vectors, but the parse
    // stage succeeds, which is enough for many shaders whose matrix
    // never actually executes (dead `mul` in an unreachable branch, or
    // matrices used only for `.xy` extraction).
    result = result.replace("float4x4", "mat4x4<f32>");
    result = result.replace("float4x3", "mat4x3<f32>");
    result = result.replace("float4x2", "mat4x2<f32>");
    result = result.replace("float3x4", "mat3x4<f32>");
    result = result.replace("float3x3", "mat3x3<f32>");
    result = result.replace("float3x2", "mat3x2<f32>");
    result = result.replace("float2x4", "mat2x4<f32>");
    result = result.replace("float2x3", "mat2x3<f32>");
    result = result.replace("float2x2", "mat2x2<f32>");
    result = result.replace("float4", "vec4<f32>");
    result = result.replace("float3", "vec3<f32>");
    result = result.replace("float2", "vec2<f32>");
    result = result.replace("float1", "f32");
    // Plain `float` only when followed by a non-identifier char — avoids
    // mangling `float4` again and `floatBitsToInt`-style names.
    let float_re = Regex::new(r"\bfloat\b").unwrap();
    result = float_re.replace_all(&result, "f32").to_string();

    // HLSL `double*` types — WGSL has no f64 in shaders (naga blocks it on
    // every backend we target), so downgrade them to their f32 cousins.
    // Real presets ship `double3 blur = ...` purely as a typo-grade type
    // alias; the math doesn't actually need double precision. Same ordering
    // rule as `float`: longer names first.
    result = result.replace("double4x4", "mat4x4<f32>");
    result = result.replace("double4x3", "mat4x3<f32>");
    result = result.replace("double4x2", "mat4x2<f32>");
    result = result.replace("double3x4", "mat3x4<f32>");
    result = result.replace("double3x3", "mat3x3<f32>");
    result = result.replace("double3x2", "mat3x2<f32>");
    result = result.replace("double2x4", "mat2x4<f32>");
    result = result.replace("double2x3", "mat2x3<f32>");
    result = result.replace("double2x2", "mat2x2<f32>");
    result = result.replace("double4", "vec4<f32>");
    result = result.replace("double3", "vec3<f32>");
    result = result.replace("double2", "vec2<f32>");
    let double_re = Regex::new(r"\bdouble\b").unwrap();
    result = double_re.replace_all(&result, "f32").to_string();

    // HLSL `half*` types are half-precision floats (16-bit). WGSL has no
    // portable f16 (only via the `f16` extension which naga does not
    // enable by default), and MD2 user code never actually depends on
    // the precision — `half1 mod_ = 0;` is just a typo-grade
    // alternative to `float`. Map to the f32 family, same ordering rule
    // as `float`/`double`.
    result = result.replace("half4x4", "mat4x4<f32>");
    result = result.replace("half4x3", "mat4x3<f32>");
    result = result.replace("half4x2", "mat4x2<f32>");
    result = result.replace("half3x4", "mat3x4<f32>");
    result = result.replace("half3x3", "mat3x3<f32>");
    result = result.replace("half3x2", "mat3x2<f32>");
    result = result.replace("half2x4", "mat2x4<f32>");
    result = result.replace("half2x3", "mat2x3<f32>");
    result = result.replace("half2x2", "mat2x2<f32>");
    result = result.replace("half4", "vec4<f32>");
    result = result.replace("half3", "vec3<f32>");
    result = result.replace("half2", "vec2<f32>");
    result = result.replace("half1", "f32");
    let half_re = Regex::new(r"\bhalf\b").unwrap();
    result = half_re.replace_all(&result, "f32").to_string();

    // HLSL `bool*` vector types: `bool2`, `bool3`, `bool4`. WGSL has
    // `vec2<bool>` etc. Plain `bool` already exists in WGSL so no
    // rewrite is needed for the scalar. Longer first as ever.
    result = result.replace("bool4", "vec4<bool>");
    result = result.replace("bool3", "vec3<bool>");
    result = result.replace("bool2", "vec2<bool>");

    // HLSL `intN` vector aliases. The runtime never enforces the integer
    // semantics (no array index, no bitwise op in MD2 corpus), so map to
    // the f32-vector cousins like `floatN` / `halfN` / `doubleN`. Without
    // this an in-the-wild `int2 k1 = (texsize.xy*uv)%2;` survives the
    // pipeline as `int2 k1 = …` and trips the WGSL parser at the
    // identifier on the next statement (`expected assignment or
    // increment/decrement, found 'k1'`). Order: longer first so the matrix
    // forms aren't masked, vec-forms before plain `\bint\b`.
    result = result.replace("int4", "vec4<f32>");
    result = result.replace("int3", "vec3<f32>");
    result = result.replace("int2", "vec2<f32>");

    // HLSL `int` → WGSL `f32`. MD2 user shaders use `int` for loop
    // counters and the like but freely mix them with float arithmetic
    // (`ang2 = 6.28*n/anz`), which HLSL implicitly promotes. WGSL refuses
    // those implicit conversions with `automatic conversions cannot
    // convert elements of i32 to f32`. Since presets never do real i32
    // work in user comp shaders (no array indexing, no bitwise ops), it
    // costs nothing to widen them to `f32` up-front.
    let int_re = Regex::new(r"\bint\b").unwrap();
    result = int_re.replace_all(&result, "f32").to_string();

    result
}

fn replace_functions(code: &str) -> String {
    let mut result = code.to_string();

    // Normalise `name (args)` → `name(args)` for known HLSL functions so
    // the substring-based rewrites below match. Real presets ship
    // `lerp (a, b, t)` and `tex2D (s, uv)` (often when the call spans
    // multiple lines and the author put the `(` on a fresh line).
    result = normalise_call_whitespace(&result);

    // lerp → mix
    result = result.replace("lerp(", "mix(");

    // Alias `sat(x)` → `saturate(x)` BEFORE the saturate→clamp rewrite
    // so the corpus `#define sat saturate` shortcut composes correctly.
    // Same word-boundary rule that `rename_word_call` enforces.
    result = rename_word_call(&result, "sat", "saturate");

    // saturate(<expr>) → clamp(<expr>, 0.0, 1.0). Paren-balanced — `<expr>`
    // may contain nested calls like `saturate(GetBlur1(uv))`.
    result = rewrite_unary_call_balanced(&result, "saturate", |inner| {
        format!("clamp({inner}, 0.0, 1.0)")
    });

    // frac → fract
    result = result.replace("frac(", "fract(");

    // HLSL builtins absent or differently spelled in WGSL.
    //
    // - `sat(x)` is the HLSL alias for `saturate(x)`. The corpus also
    //   ships `#define sat saturate` lines (stripped by
    //   `strip_preprocessor`), leaving `sat(…)` references unbound.
    // - `rsqrt(x)` is the HLSL reciprocal-square-root; WGSL spells it
    //   `inverseSqrt`.
    // - `log10(x)` exists in HLSL but not in WGSL. Map to
    //   `log(x) * 0.4342944…` (`1/ln(10)`).
    // - `tex2Dbias(s, vec4(uv, 0, bias))` is HLSL's mip-bias sampling
    //   form; WGSL has `textureSampleBias`, but the corpus uses bias
    //   purely cosmetically (always 0 or near-0). Downgrade to plain
    //   `tex2D(s, uv)` by stripping the bias arg.
    //
    // All four are plain string substitutions; no paren balancing is
    // required because each maps to a same-shape call (or a binary
    // expression for `log10`).
    result = rename_word_call(&result, "rsqrt", "inverseSqrt");
    // log10(x) → log(x) * (1 / ln 10).
    result = rewrite_unary_call_balanced(&result, "log10", |inner| {
        format!("(log({inner}) * 0.43429448190325176)")
    });
    // `tex2Dbias(s, vec4(uv, mip, bias))` → `tex2D(s, uv)`. The wrapping
    // vec4 ctor is the dominant corpus shape; project onto its first two
    // components.
    result = rewrite_tex2dbias(&result);

    // Normalise case-insensitive variants of MD2 builtins. Real presets
    // ship `tex2d(...)` instead of `tex2D(...)`; WGSL's case-sensitive
    // identifier resolution fails on the lowercase form.
    result = result.replace("tex2d(", "tex2D(");
    result = result.replace("tex3d(", "tex3D(");

    // mul(matrix, vector) → matrix * vector
    result = rewrite_mul_balanced(&result);

    // `mod(a, b)` → `((a) - floor((a) / (b)) * (b))`. `mod` is a WGSL
    // reserved keyword (HLSL uses it as the float-mod helper). Use a
    // paren-balanced rewrite because both arguments are expressions.
    result = rewrite_mod_balanced(&result);

    // Rename WGSL-reserved identifiers that real presets use as locals
    // (`mod`, `filter`, `sample`). Runs AFTER `rewrite_mod_balanced` so
    // function-call rewrites already happened — what's left are bare
    // identifier references which get a trailing underscore.
    result = rename_reserved_identifiers(&result);

    // Strip leading zeros from integer literals — WGSL rejects `02`.
    result = LEADING_ZERO_REGEX.replace_all(&result, "$1").to_string();

    // Strip HLSL unary `+` (no-op prefix that WGSL doesn't accept).
    // Triggered when `+` directly follows `(`, `,`, or any binop after
    // optional whitespace. Pure no-op in HLSL semantics.
    result = strip_unary_plus(&result);

    result
}

/// HLSL function names that the rewrite pipeline treats specially. When a
/// preset writes `name (args)` with whitespace between the identifier and
/// `(`, downstream substring matches (`"lerp("`, paren-balanced walkers)
/// would skip the call. Collapse that whitespace once up-front so every
/// downstream pass sees the no-space form.
const KNOWN_CALL_NAMES: &[&str] = &[
    "lerp",
    "frac",
    "saturate",
    "mul",
    "tex2D",
    "tex3D",
    "pow",
    "clamp",
    "mix",
    "min",
    "max",
    "step",
    "smoothstep",
    "length",
    "distance",
    "dot",
    "normalize",
    "abs",
    "cos",
    "sin",
    "tan",
    "sqrt",
    "exp",
    "log",
    "GetPixel",
    "GetBlur1",
    "GetBlur2",
    "GetBlur3",
    "lum",
    "fract",
    "floor",
    "ceil",
    "sign",
];

/// Replace `name<WS>(` with `name(` for every entry in [`KNOWN_CALL_NAMES`].
/// Only fires when `name` is on a word boundary and `<WS>` is non-empty
/// whitespace (so the no-whitespace form is left alone). Skips matches
/// inside `/* */` and `// ` comments so commented-out code stays stable.
fn normalise_call_whitespace(src: &str) -> String {
    let bytes = src.as_bytes();
    let mut out = String::with_capacity(src.len());
    let mut i = 0usize;

    while i < bytes.len() {
        // Pass through comments verbatim — preserves byte offsets in the
        // emitted text, which is fine because comments are stripped later
        // anyway, but more importantly avoids rewriting commented-out code
        // (which then might land in the visible output as a marker).
        if i + 1 < bytes.len() && bytes[i] == b'/' && bytes[i + 1] == b'/' {
            while i < bytes.len() && bytes[i] != b'\n' {
                out.push(bytes[i] as char);
                i += 1;
            }
            continue;
        }
        if i + 1 < bytes.len() && bytes[i] == b'/' && bytes[i + 1] == b'*' {
            let start = i;
            i += 2;
            while i + 1 < bytes.len() && !(bytes[i] == b'*' && bytes[i + 1] == b'/') {
                i += 1;
            }
            if i + 1 < bytes.len() {
                i += 2;
            }
            out.push_str(&src[start..i]);
            continue;
        }

        // Word-boundary check on the left.
        if i > 0 {
            let prev = bytes[i - 1];
            if prev.is_ascii_alphanumeric() || prev == b'_' {
                out.push(bytes[i] as char);
                i += 1;
                continue;
            }
        }

        let mut matched = None;
        for &name in KNOWN_CALL_NAMES {
            let nb = name.as_bytes();
            if i + nb.len() <= bytes.len() && &bytes[i..i + nb.len()] == nb {
                // Right boundary — next byte must be whitespace (we're
                // matching `name<WS>(`).
                let after = bytes.get(i + nb.len()).copied();
                if after.is_some_and(|c| c == b' ' || c == b'\t' || c == b'\n' || c == b'\r') {
                    matched = Some(nb.len());
                    break;
                }
            }
        }

        let Some(nlen) = matched else {
            out.push(bytes[i] as char);
            i += 1;
            continue;
        };

        // Peek past the whitespace to see if the next non-WS byte is `(`.
        let mut j = i + nlen;
        while j < bytes.len()
            && (bytes[j] == b' ' || bytes[j] == b'\t' || bytes[j] == b'\n' || bytes[j] == b'\r')
        {
            j += 1;
        }
        if j < bytes.len() && bytes[j] == b'(' {
            // Emit name then `(`, dropping the whitespace.
            out.push_str(&src[i..i + nlen]);
            out.push('(');
            i = j + 1;
        } else {
            // Whitespace not followed by `(` — leave unchanged.
            out.push_str(&src[i..i + nlen]);
            i += nlen;
        }
    }

    out
}

/// Strip HLSL unary `+` (a syntactic no-op WGSL doesn't accept) when it
/// directly follows `(`, `,`, `=`, `+`, `-`, `*`, `/`, `<`, `>`, `?`, `:`
/// after optional whitespace. Preserves byte positions of everything
/// except the `+` itself.
///
/// Real preset pattern: `ret.x += (+dx.x - dy.x)*0.4;` — the `+` after
/// `(` is a stylistic flourish. WGSL parser rejects with
/// `expected expression, found "+"`.
fn strip_unary_plus(src: &str) -> String {
    let bytes = src.as_bytes();
    let mut out = String::with_capacity(src.len());
    let mut last_op: Option<u8> = Some(b'('); // start-of-input behaves like `(`
    let mut i = 0usize;
    while i < bytes.len() {
        let b = bytes[i];
        // Inside comments: pass through and don't update last_op.
        if i + 1 < bytes.len() && b == b'/' && bytes[i + 1] == b'/' {
            while i < bytes.len() && bytes[i] != b'\n' {
                out.push(bytes[i] as char);
                i += 1;
            }
            continue;
        }
        if i + 1 < bytes.len() && b == b'/' && bytes[i + 1] == b'*' {
            let start = i;
            i += 2;
            while i + 1 < bytes.len() && !(bytes[i] == b'*' && bytes[i + 1] == b'/') {
                i += 1;
            }
            if i + 1 < bytes.len() {
                i += 2;
            }
            out.push_str(&src[start..i]);
            continue;
        }

        if b == b'+' && last_op.is_some_and(is_unary_context) {
            // Drop the `+`. Don't update last_op — the next token still
            // sits in the same syntactic position.
            i += 1;
            continue;
        }

        out.push(b as char);
        if !b.is_ascii_whitespace() {
            last_op = Some(b);
        }
        i += 1;
    }
    out
}

fn is_unary_context(b: u8) -> bool {
    matches!(
        b,
        b'(' | b','
            | b'='
            | b'+'
            | b'-'
            | b'*'
            | b'/'
            | b'<'
            | b'>'
            | b'?'
            | b':'
            | b'['
            | b'{'
            | b';'
    )
}

/// Generic paren-balanced rewriter for `<name>(<single-arg>)` calls. Walks
/// the source, finds `<name>` on a word boundary followed by `(`, balances
/// to the matching `)`, and replaces the whole call with `make_replacement`
/// applied to the captured argument text (verbatim, not trimmed).
fn rewrite_unary_call_balanced<F>(src: &str, name: &str, make_replacement: F) -> String
where
    F: Fn(&str) -> String,
{
    let bytes = src.as_bytes();
    let name_b = name.as_bytes();
    let mut out = String::with_capacity(src.len());
    let mut i = 0usize;

    while i < bytes.len() {
        if i + name_b.len() < bytes.len()
            && &bytes[i..i + name_b.len()] == name_b
            && bytes[i + name_b.len()] == b'('
            && (i == 0 || !(bytes[i - 1].is_ascii_alphanumeric() || bytes[i - 1] == b'_'))
        {
            let arg_start = i + name_b.len() + 1;
            let mut j = arg_start;
            let mut depth = 1i32;
            while j < bytes.len() {
                match bytes[j] {
                    b'(' => depth += 1,
                    b')' => {
                        depth -= 1;
                        if depth == 0 {
                            break;
                        }
                    }
                    _ => {}
                }
                j += 1;
            }
            if j < bytes.len() {
                out.push_str(&make_replacement(&src[arg_start..j]));
                i = j + 1;
                continue;
            }
        }
        out.push(bytes[i] as char);
        i += 1;
    }

    out
}

/// Rename `<from>(` → `<to>(` at every word boundary. Used to alias HLSL
/// builtins that WGSL spells differently (`sat` → `saturate`, `rsqrt` →
/// `inverseSqrt`). Differs from a plain `replace`: a preset local
/// `frsqrt = q1` won't pick up an unwanted `frinverseSqrt = q1` rewrite
/// because we require a non-identifier byte (or start of source) to the
/// left of the match.
fn rename_word_call(src: &str, from: &str, to: &str) -> String {
    let bytes = src.as_bytes();
    let from_b = from.as_bytes();
    let mut out = String::with_capacity(src.len());
    let mut i = 0usize;
    while i < bytes.len() {
        if i + from_b.len() < bytes.len()
            && &bytes[i..i + from_b.len()] == from_b
            && bytes[i + from_b.len()] == b'('
            && (i == 0 || !(bytes[i - 1].is_ascii_alphanumeric() || bytes[i - 1] == b'_'))
        {
            out.push_str(to);
            out.push('(');
            i += from_b.len() + 1;
            continue;
        }
        out.push(bytes[i] as char);
        i += 1;
    }
    out
}

/// `tex2Dbias(s, vec4(uv, mip, bias))` → `tex2D(s, uv)`.
/// Paren-balanced over both arguments. The bias component is dropped
/// (real presets use it cosmetically at 0 or near-0 — no visual delta).
fn rewrite_tex2dbias(src: &str) -> String {
    let bytes = src.as_bytes();
    let needle = b"tex2Dbias(";
    let mut out = String::with_capacity(src.len());
    let mut i = 0usize;
    while i < bytes.len() {
        let starts_here = i + needle.len() <= bytes.len() && &bytes[i..i + needle.len()] == needle;
        let word_boundary =
            i == 0 || !(bytes[i - 1].is_ascii_alphanumeric() || bytes[i - 1] == b'_');
        if !(starts_here && word_boundary) {
            out.push(bytes[i] as char);
            i += 1;
            continue;
        }
        // Walk arg #1 (the sampler) up to the top-level comma.
        let mut j = i + needle.len();
        let mut depth = 1i32;
        let sampler_start = j;
        while j < bytes.len() {
            match bytes[j] {
                b'(' => depth += 1,
                b')' => depth -= 1,
                b',' if depth == 1 => break,
                _ => {}
            }
            j += 1;
        }
        if j >= bytes.len() || bytes[j] != b',' {
            out.push(bytes[i] as char);
            i += 1;
            continue;
        }
        let sampler = &src[sampler_start..j];
        // Walk arg #2 up to the closing `)` of the call.
        j += 1; // past the comma
        let arg2_start = j;
        while j < bytes.len() {
            match bytes[j] {
                b'(' => depth += 1,
                b')' => {
                    depth -= 1;
                    if depth == 0 {
                        break;
                    }
                }
                _ => {}
            }
            j += 1;
        }
        if j >= bytes.len() {
            out.push(bytes[i] as char);
            i += 1;
            continue;
        }
        let arg2 = src[arg2_start..j].trim();
        // Strip a vec4(/float4(/vec3(/float3( wrapper and keep its first
        // component (`uv` for the dominant `vec4(uv, mip, bias)` shape).
        let uv = strip_first_vec_component(arg2).unwrap_or_else(|| arg2.to_string());
        out.push_str("tex2D(");
        out.push_str(sampler.trim());
        out.push_str(", ");
        out.push_str(&uv);
        out.push(')');
        i = j + 1;
    }
    out
}

/// For a string like `vec4(uv, 0, 0.1)` or `float3(uv, 0)`, return `uv` —
/// the slice up to the first top-level comma inside the constructor. Used
/// by [`rewrite_tex2dbias`] to drop the mip-bias arguments.
fn strip_first_vec_component(s: &str) -> Option<String> {
    let s = s.trim();
    let prefixes = ["vec4(", "vec3(", "float4(", "float3(", "float2(", "vec2("];
    for prefix in prefixes {
        if let Some(rest) = s.strip_prefix(prefix) {
            let rest = rest.strip_suffix(')')?;
            let bytes = rest.as_bytes();
            let mut depth = 0i32;
            let mut end = bytes.len();
            for (i, &b) in bytes.iter().enumerate() {
                match b {
                    b'(' => depth += 1,
                    b')' => depth -= 1,
                    b',' if depth == 0 => {
                        end = i;
                        break;
                    }
                    _ => {}
                }
            }
            return Some(rest[..end].trim().to_string());
        }
    }
    None
}

/// Rename WGSL-reserved keywords used by MD2 preset authors as locals
/// (`mod`, `filter`, `sample`). Every occurrence on a word boundary that
/// isn't immediately followed by `(` (a function call — already rewritten
/// by `rewrite_mod_balanced` or rejected upstream) gets a trailing `_`.
///
/// This stays consistent across one shader: a local `float mod = …;` and
/// its later references in `+ q22*sqrt(z)/4*mod *` both become `mod_`, so
/// the renamed variable still ties together correctly.
fn rename_reserved_identifiers(src: &str) -> String {
    const RESERVED: &[&str] = &["mod", "filter", "sample"];
    let bytes = src.as_bytes();
    let mut out = String::with_capacity(src.len() + 16);
    let mut i = 0usize;
    while i < bytes.len() {
        // Pass comments through unchanged so the renamer doesn't touch
        // text the user authored as documentation.
        if i + 1 < bytes.len() && bytes[i] == b'/' && bytes[i + 1] == b'/' {
            while i < bytes.len() && bytes[i] != b'\n' {
                out.push(bytes[i] as char);
                i += 1;
            }
            continue;
        }
        if i + 1 < bytes.len() && bytes[i] == b'/' && bytes[i + 1] == b'*' {
            let s = i;
            i += 2;
            while i + 1 < bytes.len() && !(bytes[i] == b'*' && bytes[i + 1] == b'/') {
                i += 1;
            }
            if i + 1 < bytes.len() {
                i += 2;
            }
            out.push_str(&src[s..i]);
            continue;
        }

        // Word-boundary check on the left.
        if i > 0 {
            let prev = bytes[i - 1];
            if prev.is_ascii_alphanumeric() || prev == b'_' {
                out.push(bytes[i] as char);
                i += 1;
                continue;
            }
        }

        let mut matched = None;
        for &kw in RESERVED {
            let kb = kw.as_bytes();
            if i + kb.len() <= bytes.len()
                && &bytes[i..i + kb.len()] == kb
                && bytes
                    .get(i + kb.len())
                    .is_none_or(|c| !(c.is_ascii_alphanumeric() || *c == b'_'))
            {
                // If the next non-WS byte is `(`, it's a function call —
                // a `mod(…)` should have been rewritten already, but if
                // some upstream slipped through, we still leave it. Other
                // reserved names (`filter`, `sample`) are not function
                // calls in any user shader we've seen.
                let mut j = i + kb.len();
                while j < bytes.len() && bytes[j].is_ascii_whitespace() {
                    j += 1;
                }
                if j < bytes.len() && bytes[j] == b'(' {
                    continue;
                }
                matched = Some(kw);
                break;
            }
        }

        if let Some(kw) = matched {
            out.push_str(kw);
            out.push('_');
            i += kw.len();
            continue;
        }
        out.push(bytes[i] as char);
        i += 1;
    }
    out
}

/// `mod(a, b)` → `((a) - floor((a) / (b)) * (b))`. WGSL reserves `mod` as
/// a keyword; HLSL uses it as the float-modulo helper. The expansion
/// matches HLSL's semantics (and matches GLSL's `mod`) so behaviour stays
/// identical.
///
/// Paren-balanced on both arguments because real presets ship
/// `mod(ang*16/M_PI, 1.0)` and similar — the comma sits inside the call's
/// top-level depth.
fn rewrite_mod_balanced(src: &str) -> String {
    rewrite_binary_call_balanced(src, "mod", |a, b| {
        format!("(({a}) - floor(({a}) / ({b})) * ({b}))")
    })
}

/// Generic paren-balanced rewriter for two-argument calls. Walks the
/// source, matches `<name>(` on a word boundary, finds the top-level
/// `,`, and replaces the whole call with the closure's output.
fn rewrite_binary_call_balanced<F>(src: &str, name: &str, make: F) -> String
where
    F: Fn(&str, &str) -> String,
{
    let bytes = src.as_bytes();
    let name_b = name.as_bytes();
    let mut out = String::with_capacity(src.len());
    let mut i = 0usize;
    while i < bytes.len() {
        let matched = i + name_b.len() < bytes.len()
            && &bytes[i..i + name_b.len()] == name_b
            && bytes[i + name_b.len()] == b'('
            && (i == 0 || !(bytes[i - 1].is_ascii_alphanumeric() || bytes[i - 1] == b'_'));
        if !matched {
            out.push(bytes[i] as char);
            i += 1;
            continue;
        }
        let arg_start = i + name_b.len() + 1;
        let mut j = arg_start;
        let mut depth = 1i32;
        let mut split = None;
        while j < bytes.len() {
            match bytes[j] {
                b'(' => depth += 1,
                b')' => {
                    depth -= 1;
                    if depth == 0 {
                        break;
                    }
                }
                b',' if depth == 1 && split.is_none() => split = Some(j),
                _ => {}
            }
            j += 1;
        }
        if let Some(c) = split
            && j < bytes.len()
        {
            let a = src[arg_start..c].trim();
            let b = src[c + 1..j].trim();
            out.push_str(&make(a, b));
            i = j + 1;
            continue;
        }
        // Couldn't balance — fall through and emit the original byte.
        out.push(bytes[i] as char);
        i += 1;
    }
    out
}

/// `mul(a, b)` → `(a) * (b)`. Paren-balanced on both arguments — needed
/// because real shaders write `mul(rotation_matrix(theta), uv)`. The
/// outermost `,` at depth 0 splits the two arguments.
fn rewrite_mul_balanced(src: &str) -> String {
    let bytes = src.as_bytes();
    let mut out = String::with_capacity(src.len());
    let mut i = 0usize;

    while i < bytes.len() {
        if i + 4 <= bytes.len()
            && &bytes[i..i + 3] == b"mul"
            && bytes[i + 3] == b'('
            && (i == 0 || !(bytes[i - 1].is_ascii_alphanumeric() || bytes[i - 1] == b'_'))
        {
            let arg_start = i + 4;
            let mut j = arg_start;
            let mut depth = 1i32;
            let mut split = None;
            while j < bytes.len() {
                match bytes[j] {
                    b'(' => depth += 1,
                    b')' => {
                        depth -= 1;
                        if depth == 0 {
                            break;
                        }
                    }
                    b',' if depth == 1 && split.is_none() => split = Some(j),
                    _ => {}
                }
                j += 1;
            }
            if let Some(c) = split
                && j < bytes.len()
            {
                let a = src[arg_start..c].trim();
                let b = src[c + 1..j].trim();
                out.push_str(&format!("(({a}) * ({b}))"));
                i = j + 1;
                continue;
            }
        }
        out.push(bytes[i] as char);
        i += 1;
    }

    out
}

fn rewrite_local_declarations(code: &str) -> String {
    // Split inline `; TYPE` runs onto their own lines first, so the
    // line-anchored LOCAL_DECL_REGEX sees every decl. See the doc on
    // [`INLINE_DECL_SPLIT_REGEX`] for the motivating preset. The same
    // pass also detaches `{TYPE` glue at the head of function/conditional
    // bodies.
    let normalised = INLINE_DECL_SPLIT_REGEX
        .replace_all(code, "$1\n$2 $3")
        .to_string();
    LOCAL_DECL_REGEX
        .replace_all(&normalised, |caps: &regex::Captures| {
            let indent = &caps[1];
            let ty = &caps[2];
            let decls = &caps[3];

            // Bail when this is actually a function signature
            // (`vec3<f32> helper(args) { … }`). The regex greedily
            // swallows the body up to the first `;`; we detect the
            // function shape by spotting a `(` before any `=` and
            // return the match unchanged so [`lift_user_functions`] can
            // extract it intact later.
            if is_function_signature(decls) {
                return caps[0].to_string();
            }

            let mut out = String::new();
            for (i, raw) in split_top_level_commas(decls).into_iter().enumerate() {
                let decl = raw.trim();
                if decl.is_empty() {
                    continue;
                }
                if i > 0 {
                    out.push('\n');
                    out.push_str(indent);
                } else {
                    out.push_str(indent);
                }
                // Each declarator is `name` or `name = init`. We split on the
                // first `=` so initialisers containing further `=` (rare,
                // mostly `a = b == c ? …` ternary which we don't otherwise
                // support) keep their tail intact.
                if let Some((name, init)) = decl.split_once('=') {
                    let name = name.trim();
                    let init = init.trim();
                    out.push_str(&format!("var {name}: {ty} = {init};"));
                } else {
                    out.push_str(&format!("var {decl}: {ty};"));
                }
            }
            out
        })
        .to_string()
}

/// Detect "this `decls` capture is actually a function signature".
/// `decls` is the text the local-decl regex captured between the type
/// and the terminating `;`. A function signature shape is
/// `<ident>(...) { ... return ... ` with the `;` being the first
/// statement-terminator inside the body, but the giveaway sits at the
/// front: a `(` appears before any `=`. Variable declarations never put
/// `(` ahead of the initializer assignment (`var x = sin(0);` — `(`
/// follows `=`).
fn is_function_signature(decls: &str) -> bool {
    for c in decls.chars() {
        match c {
            '=' => return false,
            '(' => return true,
            _ => {}
        }
    }
    false
}

/// Split a declarator list on top-level commas only — commas inside `()` or
/// `<>` (e.g. `vec3<f32>(0, 0, 0)`) must not split the declarator.
fn split_top_level_commas(s: &str) -> Vec<&str> {
    let bytes = s.as_bytes();
    let mut out = Vec::new();
    let mut depth_paren = 0i32;
    let mut depth_angle = 0i32;
    let mut start = 0usize;
    for (i, &b) in bytes.iter().enumerate() {
        match b {
            b'(' => depth_paren += 1,
            b')' => depth_paren -= 1,
            b'<' => depth_angle += 1,
            b'>' => depth_angle -= 1,
            b',' if depth_paren == 0 && depth_angle == 0 => {
                out.push(&s[start..i]);
                start = i + 1;
            }
            _ => {}
        }
    }
    out.push(&s[start..]);
    out
}

fn strip_preprocessor(code: &str) -> String {
    // First, expand any `#define NAME REPLACEMENT` where REPLACEMENT is a
    // single identifier — common MD2 idiom for type/function aliases:
    // `#define MyGet GetPixel`, `#define sat saturate`, `#define vec3 float3`.
    // Without this expansion, `strip_preprocessor` drops the `#define` and
    // every later `MyGet(uv)` lands as `no definition in scope for
    // identifier: 'MyGet'`. We only expand the trivial single-token
    // replacement form — function-like macros (`#define FOO(x) bar(x,1)`)
    // aren't worth the parser complexity here.
    let expanded = expand_simple_defines(code);
    PREPROC_REGEX.replace_all(&expanded, "").to_string()
}

/// Scan for lines of the form `#define IDENT IDENT` (whitespace-separated
/// single-token replacement) and substitute `from → to` everywhere else in
/// the source. Operates as a single pass: defines are collected first, then
/// applied to the rest of the source. Skips macros whose `to` looks like
/// anything other than a bare identifier so we don't accidentally inline
/// `#define K 0.5` (where the rest of the source has plain `K` in
/// arithmetic context — the existing fall-through preserves it as an
/// undefined-but-untouched identifier the user can spot in the error).
fn expand_simple_defines(code: &str) -> String {
    use regex::Regex;
    use std::sync::LazyLock;
    static DEF_RE: LazyLock<Regex> = LazyLock::new(|| {
        // Trailing `//comment` is common in the corpus
        // (`#define MyGet GetPixel //GetBlur1`) — allow it.
        Regex::new(
            r"(?m)^\s*#\s*define\s+([A-Za-z_][A-Za-z0-9_]*)\s+([A-Za-z_][A-Za-z0-9_]*)\s*(?://[^\n]*)?$",
        )
        .unwrap()
    });
    let pairs: Vec<(String, String)> = DEF_RE
        .captures_iter(code)
        .map(|c| (c[1].to_string(), c[2].to_string()))
        .collect();
    if pairs.is_empty() {
        return code.to_string();
    }
    let mut out = code.to_string();
    for (from, to) in &pairs {
        if from == to {
            continue;
        }
        let re = Regex::new(&format!(r"\b{}\b", regex::escape(from))).unwrap();
        out = re.replace_all(&out, to.as_str()).to_string();
    }
    out
}

/// Comment out lines that look like prose (English) rather than
/// HLSL/WGSL code. Real preset pattern: ``comp_30=`written by martin``
/// — an attribution typed without a `//` prefix, threaded into the
/// shader body by the `.milk` parser as a literal line of code. Many
/// presets failed with `expected assignment or increment/decrement;
/// found 'by'` (or `found 'rota'`, etc.) on lines of this shape.
///
/// Heuristic: a non-empty line where every non-whitespace character is
/// either an ASCII letter or an apostrophe — no `;`, `=`, parens,
/// braces, brackets, arithmetic operators, digits, or comment markers —
/// and which contains at least two whitespace-separated word tokens. We
/// also require the first token *not* to look like a known WGSL keyword
/// or builtin call left-side (e.g. `for`, `if`, `var`, `return`, `tex2D`,
/// `mul`, …) so a line like `if cond` alone won't be commented out.
/// In practice prose lines always have ≥ 2 words and lack punctuation,
/// so the false-positive rate is effectively zero on the corpus.
fn comment_out_prose_lines(code: &str) -> String {
    let mut out = String::with_capacity(code.len() + 32);
    for line in code.split_inclusive('\n') {
        if looks_like_prose(line) {
            out.push_str("// ");
            out.push_str(line);
        } else {
            out.push_str(line);
        }
    }
    out
}

fn looks_like_prose(line: &str) -> bool {
    let trimmed = line.trim_end_matches('\n').trim();
    if trimmed.is_empty() {
        return false;
    }
    // Already a comment? Leave it.
    if trimmed.starts_with("//") || trimmed.starts_with("/*") || trimmed.starts_with('*') {
        return false;
    }
    // Every non-space char must be an ASCII letter or apostrophe.
    let mut letters = 0usize;
    for c in trimmed.chars() {
        if c.is_ascii_whitespace() {
            continue;
        }
        if c.is_ascii_alphabetic() || c == '\'' {
            letters += 1;
            continue;
        }
        return false;
    }
    if letters < 2 {
        return false;
    }
    // A bare-identifier line (one word, letters only) is never a valid
    // HLSL/WGSL statement either — `END`/`EOF` markers and stray
    // identifiers fall in here. `KW` covers the few legitimate
    // single-word lines (`break;` etc. would have a `;` and bail above).
    // Bail on a leading single-word HLSL keyword that often precedes a
    // following identifier on the next line via continuation — keeps the
    // pass strictly conservative on real code.
    const KW: &[&str] = &[
        "for",
        "if",
        "else",
        "while",
        "do",
        "return",
        "break",
        "continue",
        "var",
        "let",
        "const",
        "static",
        "uniform",
        "extern",
        "sampler",
        "texture",
        "shader_body",
        "true",
        "false",
        "tex2D",
        "tex2d",
        "tex3D",
        "lerp",
        "mix",
        "saturate",
        "abs",
        "sin",
        "cos",
        "tan",
        "atan",
        "atan2",
        "pow",
        "sqrt",
        "log",
        "exp",
        "min",
        "max",
        "clamp",
        "length",
        "normalize",
        "dot",
        "cross",
        "mul",
        "step",
        "smoothstep",
        "frac",
        "fract",
        "floor",
        "ceil",
        "round",
        "sign",
        "any",
        "all",
        "not",
        "lum",
        "GetPixel",
        "GetMain",
        "GetBlur1",
        "GetBlur2",
        "GetBlur3",
    ];
    let first = trimmed.split_whitespace().next().unwrap();
    if KW.contains(&first) {
        return false;
    }
    true
}

fn strip_sampler_declarations(code: &str) -> String {
    SAMPLER_DECL_REGEX.replace_all(code, "").to_string()
}

fn strip_storage_class_qualifiers(code: &str) -> String {
    let no_storage = STORAGE_CLASS_REGEX.replace_all(code, "");
    CONST_TYPE_REGEX.replace_all(&no_storage, "$1").to_string()
}

fn rewrite_postfix_inc_dec(code: &str) -> String {
    let inc = POSTFIX_INC_REGEX
        .replace_all(code, "$1 = $1 + 1$2")
        .to_string();
    POSTFIX_DEC_REGEX
        .replace_all(&inc, "$1 = $1 - 1$2")
        .to_string()
}

/// Wrap single-statement `if`/`while`/`for` bodies in `{ ... }`. WGSL requires
/// braces on every conditional/loop body; HLSL doesn't, and a lot of MD2
/// preset code uses the brace-less form (`if (cond) ret.z -= 0.5;`).
///
/// We walk the source, find each `if` / `while` / `for` keyword, balance the
/// condition parens, and if the next non-whitespace character isn't `{`, we
/// wrap from there to the next top-level `;` (tracking parens to skip nested
/// calls) in braces.
fn brace_up_single_statement_blocks(src: &str) -> String {
    let bytes = src.as_bytes();
    let mut out = String::with_capacity(src.len() + 32);
    let mut i = 0usize;

    while i < bytes.len() {
        let kw_len = match keyword_at(bytes, i) {
            Some(n) => n,
            None => {
                out.push(bytes[i] as char);
                i += 1;
                continue;
            }
        };

        // Found a keyword. Copy it verbatim, then look for the `(` that opens
        // the condition.
        out.push_str(&src[i..i + kw_len]);
        i += kw_len;

        // Skip whitespace between keyword and `(`.
        let mut j = i;
        while j < bytes.len() && bytes[j].is_ascii_whitespace() {
            j += 1;
        }
        if j >= bytes.len() || bytes[j] != b'(' {
            // Not a real condition — bare `for(int i=0;...)` would have
            // matched the `(` immediately, so this is some unrelated token.
            // Continue normally.
            out.push_str(&src[i..j]);
            i = j;
            continue;
        }

        // Balance parens on the condition.
        let cond_start = j;
        let mut depth = 0i32;
        while j < bytes.len() {
            match bytes[j] {
                b'(' => depth += 1,
                b')' => {
                    depth -= 1;
                    if depth == 0 {
                        j += 1;
                        break;
                    }
                }
                _ => {}
            }
            j += 1;
        }
        // Copy the whitespace + condition + `)` verbatim.
        out.push_str(&src[i..j]);
        i = j;

        // Skip whitespace after `)`.
        while i < bytes.len() && bytes[i].is_ascii_whitespace() {
            out.push(bytes[i] as char);
            i += 1;
        }

        if i >= bytes.len() || bytes[i] == b'{' {
            // Already braced — nothing to do.
            continue;
        }

        // Brace-less: scan to the next `;` at depth 0 (skipping inner parens
        // / brackets) and wrap.
        let body_start = i;
        let mut paren = 0i32;
        let mut bracket = 0i32;
        while i < bytes.len() {
            match bytes[i] {
                b'(' => paren += 1,
                b')' => paren -= 1,
                b'[' => bracket += 1,
                b']' => bracket -= 1,
                b';' if paren == 0 && bracket == 0 => {
                    i += 1;
                    break;
                }
                _ => {}
            }
            i += 1;
        }

        out.push('{');
        out.push(' ');
        out.push_str(&src[body_start..i]);
        out.push_str(" }");
        // Force a `_unused` if cond_start was inside an else-if chain and we
        // need to suppress dead branches — not done here.
        let _ = cond_start;
    }

    out
}

/// Match `if`/`while`/`for` keywords on word boundaries; return their length.
fn keyword_at(bytes: &[u8], i: usize) -> Option<usize> {
    // Must be at a word boundary on the left.
    if i > 0 {
        let prev = bytes[i - 1];
        if prev.is_ascii_alphanumeric() || prev == b'_' {
            return None;
        }
    }
    for (kw, len) in [("if", 2usize), ("while", 5), ("for", 3)] {
        if i + len <= bytes.len() && &bytes[i..i + len] == kw.as_bytes() {
            // Right boundary: next char must be non-identifier.
            let next = bytes.get(i + len).copied();
            let is_id = next.is_some_and(|c| c.is_ascii_alphanumeric() || c == b'_');
            if !is_id {
                return Some(len);
            }
        }
    }
    None
}

/// Rewrite `tex3D(<sampler>, <uvw>)` to a real 3D `textureSample` against
/// the noise-volume bindings.
///
/// An earlier implementation collapsed every `tex3D` to a 2D
/// `GetPixel(uvw.xy)` fallback — that kept the shader compiling but
/// produced wrong output for any preset that relied on noisevol's true
/// volumetric variance (many in-the-wild comps reference
/// `sampler_noisevol_hq`). Now that the renderer actually binds 3D noise
/// textures, the rewriter routes the known names onto them and only
/// falls back for unknown sampler names.
///
/// **Return type**: vec4. HLSL's `tex3D` returns float4 and presets often
/// store the result in `float4 noise2 = tex3D(...);` and read `.w` later —
/// `textureSample` of a `texture_3d<f32>` is already vec4.
fn rewrite_tex3d_calls(src: &str) -> String {
    let bytes = src.as_bytes();
    let mut out = String::with_capacity(src.len());
    let mut i = 0usize;

    while i < bytes.len() {
        // Match `tex3D` on a word boundary.
        if i + 5 <= bytes.len() && &bytes[i..i + 5] == b"tex3D" {
            let prev_ok = i == 0 || !(bytes[i - 1].is_ascii_alphanumeric() || bytes[i - 1] == b'_');
            let next_open = i + 5 < bytes.len() && bytes[i + 5] == b'(';
            if prev_ok && next_open {
                // Skip past `tex3D(`.
                let arg_start = i + 6;
                // Find the comma at depth 0 (separates sampler from uvw).
                let mut j = arg_start;
                let mut depth = 1i32;
                let mut comma = None;
                while j < bytes.len() && depth > 0 {
                    match bytes[j] {
                        b'(' => depth += 1,
                        b')' => {
                            depth -= 1;
                            if depth == 0 {
                                break;
                            }
                        }
                        b',' if depth == 1 && comma.is_none() => comma = Some(j),
                        _ => {}
                    }
                    j += 1;
                }
                if let Some(c) = comma
                    && j < bytes.len()
                {
                    let sampler = src[arg_start..c].trim();
                    let uvw = src[c + 1..j].trim();
                    let replacement = match sampler {
                        s if s.ends_with("noisevol_lq") => format!(
                            "textureSample(sampler_noisevol_lq_texture, {}, {uvw})",
                            noise_sampler_for(s)
                        ),
                        s if s.ends_with("noisevol_hq") => format!(
                            "textureSample(sampler_noisevol_hq_texture, {}, {uvw})",
                            noise_sampler_for(s)
                        ),
                        _ => {
                            // Unknown 3D sampler — keep the 2D fallback so
                            // the wrapper compiles instead of failing.
                            format!(
                                "vec4<f32>(GetPixel(({uvw}).xy), 1.0) /*was: tex3D({sampler})*/"
                            )
                        }
                    };
                    out.push_str(&replacement);
                    i = j + 1;
                    continue;
                }
            }
        }
        out.push(bytes[i] as char);
        i += 1;
    }

    out
}

fn replace_semantics(code: &str) -> String {
    SEMANTICS_REGEX.replace_all(code, "").to_string()
}

/// Walk the source for `var <NAME>: <TYPE> [= INIT];` declarations; the
/// first time a `NAME` appears *in the current scope*, keep it; every later
/// declaration of the same `NAME` in the same scope becomes a plain
/// assignment (`NAME = INIT;`) or — if it had no initialiser — is dropped
/// entirely.
///
/// HLSL allows `float3 ret1 = ret1;` to shadow a previous declaration
/// (or just redundantly redeclare it); WGSL rejects with
/// `redefinition of ret1`. The presets that hit this are typically
/// older MD2 user-shader idioms.
///
/// Scope tracking matters here. A flat `seen` set is wrong: a global
/// `var tmp: f32;` plus a function-local `var tmp: f32;` inside a helper
/// would drop the inner decl while the helper's body still referenced
/// `tmp`, which then failed naga as `no definition in scope for
/// identifier: tmp`. We push a fresh `seen` set on every `{` and pop
/// on the matching `}`, so each scope dedups independently.
fn dedup_var_declarations(src: &str) -> String {
    use std::collections::HashMap;
    static VAR_DECL: LazyLock<Regex> = LazyLock::new(|| {
        // Anchor relaxed from `(?m)^\s*` to `\s*` and matched by hand
        // below: we still want declarations on their own line in practice,
        // but the scope walk needs to align byte positions with brace
        // boundaries, which `replace_all`'s line-anchored variant doesn't
        // expose. The same shape is matched, just without `^`.
        // Capture group 4 is the *type* (everything between `:` and the
        // optional `=`/`;`); a second declaration of the same name with a
        // different type is a deliberate shadow and must NOT be dropped.
        Regex::new(
            r"(\n[ \t]*|\A[ \t]*)(var|let)\s+([A-Za-z_][A-Za-z0-9_]*)\s*:\s*([^=;]+?)\s*(=\s*[^;]+)?;",
        )
        .unwrap()
    });

    // Pre-compute scope boundaries by walking the source once and recording
    // `{` and `}` byte positions (ignoring those inside string/char literals
    // — none occur in MD2 user shaders — and inside line/block comments).
    let bytes = src.as_bytes();
    let mut depth: i32 = 0;
    let mut depth_at: Vec<i32> = Vec::with_capacity(bytes.len() + 1);
    depth_at.push(0);
    let mut i = 0usize;
    while i < bytes.len() {
        // Skip line comments verbatim — their `{`/`}` shouldn't count.
        if i + 1 < bytes.len() && bytes[i] == b'/' && bytes[i + 1] == b'/' {
            while i < bytes.len() && bytes[i] != b'\n' {
                depth_at.push(depth);
                i += 1;
            }
            continue;
        }
        if i + 1 < bytes.len() && bytes[i] == b'/' && bytes[i + 1] == b'*' {
            while i + 1 < bytes.len() && !(bytes[i] == b'*' && bytes[i + 1] == b'/') {
                depth_at.push(depth);
                i += 1;
            }
            if i + 1 < bytes.len() {
                depth_at.push(depth);
                depth_at.push(depth);
                i += 2;
            }
            continue;
        }
        match bytes[i] {
            b'{' => depth += 1,
            b'}' => depth -= 1,
            _ => {}
        }
        depth_at.push(depth);
        i += 1;
    }

    // Map of scope-depth → (name → declared-type). Each scope dedups
    // independently; when we exit a scope (depth dips), that scope's
    // record is wiped so a sibling block opening at the same depth
    // starts fresh. Storing the type lets the dedup distinguish a true
    // redundant re-declaration (same name, same type — drop the second
    // `var`) from a deliberate shadow (same name, different type —
    // keep both so the local-scope intent survives).
    let mut seen_by_depth: HashMap<i32, HashMap<String, String>> = HashMap::new();
    let mut last_pos: usize = 0;

    VAR_DECL
        .replace_all(src, |caps: &regex::Captures| {
            let prefix = &caps[1];
            let name = &caps[3];
            let ty = caps[4].trim();
            let init = caps.get(5).map(|m| m.as_str()).unwrap_or("");
            let start = caps.get(0).unwrap().start();
            // Sweep depth_at from the previous match to here; clear the
            // record of every depth we exited (depth dipped below it).
            // This handles sibling scopes — closing one function's `}`
            // resets that depth before the next function's `var`s arrive.
            let mut min_in_window = i32::MAX;
            for d in &depth_at[last_pos..=start.min(depth_at.len() - 1)] {
                if *d < min_in_window {
                    min_in_window = *d;
                }
            }
            let cur_depth = depth_at.get(start).copied().unwrap_or(0).max(0);
            // Any depth strictly above the lowest point we passed through
            // had its scope closed at some point in the window — wipe
            // their records.
            if min_in_window < i32::MAX {
                seen_by_depth.retain(|d, _| *d <= min_in_window);
            }
            last_pos = caps.get(0).unwrap().end();
            let seen = seen_by_depth.entry(cur_depth).or_default();
            match seen.get(name) {
                Some(prev_ty) if prev_ty == ty => {
                    // Exact duplicate at the same scope — strip `var`.
                    let init_trim = init.trim_start_matches('=').trim();
                    if init_trim.is_empty() {
                        format!("{prefix}/* dropped redundant var {name} */")
                    } else {
                        format!("{prefix}{name} = {init_trim};")
                    }
                }
                _ => {
                    // First sighting OR same name with a different type
                    // (deliberate shadow). Keep the declaration; record
                    // the latest type so a third same-type repeat would
                    // still be deduped.
                    seen.insert(name.to_string(), ty.to_string());
                    caps[0].to_string()
                }
            }
        })
        .to_string()
}

/// HLSL allows comma-as-statement-separator at the top of a function body:
///
/// ```hlsl
/// ret += saturate(...),
/// ret += saturate(...),
/// ret = lerp(ret, blurs, t);
/// ```
///
/// WGSL requires `;` between statements; a stray comma triggers
/// `expected ;`, found ','`. At this point in the pipeline every multi-
/// name `var` declaration has already been split into one `var` per name
/// (see [`rewrite_local_declarations`]), so a comma at paren/bracket-
/// depth 0 is unambiguously a statement separator. Rewrite to `;`.
///
/// Comments are skipped so a `,` inside `/* */` doesn't confuse anyone.
fn replace_statement_commas(src: &str) -> String {
    let bytes = src.as_bytes();
    let mut out = String::with_capacity(src.len());
    let mut paren = 0i32;
    let mut bracket = 0i32;
    let mut angle = 0i32;
    // Stack of in-flight `{` kinds: `true` = init-list (followed `=`),
    // `false` = code block. Commas inside an init-list are constructor
    // separators, not statement separators — converting them to `;`
    // corrupts shapes like `float2x2 rot = { cos(q9), sin(q9), … };` into
    // `mat2x2<f32>(cos(q9); sin(q9); …)` and trips the downstream parser
    // on the first non-statement token (the matrix name `rot`).
    let mut brace_stack: Vec<bool> = Vec::new();
    let mut last_sig: u8 = 0;
    let mut i = 0usize;
    while i < bytes.len() {
        // Pass comments verbatim.
        if i + 1 < bytes.len() && bytes[i] == b'/' && bytes[i + 1] == b'/' {
            while i < bytes.len() && bytes[i] != b'\n' {
                out.push(bytes[i] as char);
                i += 1;
            }
            continue;
        }
        if i + 1 < bytes.len() && bytes[i] == b'/' && bytes[i + 1] == b'*' {
            let s = i;
            i += 2;
            while i + 1 < bytes.len() && !(bytes[i] == b'*' && bytes[i + 1] == b'/') {
                i += 1;
            }
            if i + 1 < bytes.len() {
                i += 2;
            }
            out.push_str(&src[s..i]);
            continue;
        }
        let c = bytes[i];
        let in_init_list = brace_stack.last().copied().unwrap_or(false);
        match c {
            b'(' => paren += 1,
            b')' => paren -= 1,
            b'[' => bracket += 1,
            b']' => bracket -= 1,
            b'<' => angle += 1,
            b'>' => angle -= 1,
            b'{' => {
                let is_init = last_sig == b'=' || (in_init_list && last_sig == b'{');
                brace_stack.push(is_init);
            }
            b'}' => {
                brace_stack.pop();
            }
            b',' if paren == 0 && bracket == 0 && angle == 0 && !in_init_list => {
                // Statement separator — emit `;`.
                out.push(';');
                i += 1;
                last_sig = b';';
                continue;
            }
            _ => {}
        }
        if !c.is_ascii_whitespace() {
            last_sig = c;
        }
        out.push(c as char);
        i += 1;
    }
    out
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::texture_plan::decompose_sampler_name;

    #[test]
    fn reassigned_param_is_shadowed_with_var() {
        // HLSL value-parameters are mutable; WGSL params are immutable.
        // The lift pass must rename the param and prepend a shadowing var.
        let hlsl = "float2 PutDist(float x) { float tmp; x = pow(x, 2.0); \
                    tmp = 1 - x; return float2(tmp, x); } \
                    shader_body { ret = float3(PutDist(0.5), 0); }";
        let wgsl = translate_shader(hlsl).unwrap();
        // Renamed param in signature
        assert!(
            wgsl.contains("x_md2arg: f32"),
            "expected renamed param, got:\n{wgsl}"
        );
        // Shadowing var at body entry
        assert!(
            wgsl.contains("var x: f32 = x_md2arg"),
            "expected shadow var, got:\n{wgsl}"
        );
    }

    #[test]
    fn unreassigned_param_left_alone() {
        // A param that's only read should pass through unchanged — no
        // unnecessary shadowing.
        let hlsl = "float2 Pass(float x) { return float2(x, x*2); } \
                    shader_body { ret = float3(Pass(0.5), 0); }";
        let wgsl = translate_shader(hlsl).unwrap();
        assert!(
            wgsl.contains("fn Pass(x: f32) -> vec2<f32>"),
            "expected unchanged signature, got:\n{wgsl}"
        );
        assert!(
            !wgsl.contains("x_md2arg"),
            "should not rename a read-only param, got:\n{wgsl}"
        );
    }

    #[test]
    fn param_written_via_swizzle_is_shadowed() {
        // `uv.x = …` is a write through swizzle — also requires var.
        let hlsl = "float2 Tweak(float2 uvi) { uvi.x = uvi.x * 2; return uvi; } \
                    shader_body { ret = float3(Tweak(uv), 0); }";
        let wgsl = translate_shader(hlsl).unwrap();
        assert!(
            wgsl.contains("uvi_md2arg: vec2<f32>"),
            "expected renamed param, got:\n{wgsl}"
        );
        assert!(
            wgsl.contains("var uvi: vec2<f32> = uvi_md2arg"),
            "expected shadow var, got:\n{wgsl}"
        );
    }

    #[test]
    fn type_replacement() {
        let hlsl = "float4 color = float4(1.0, 0.0, 0.0, 1.0);";
        let wgsl = translate_shader(hlsl).unwrap();
        assert!(wgsl.contains("vec4<f32>"));
    }

    #[test]
    fn function_replacement() {
        let hlsl = "color = lerp(a, b, t);";
        let wgsl = translate_shader(hlsl).unwrap();
        assert!(wgsl.contains("mix"));
    }

    #[test]
    fn saturate_replacement() {
        let hlsl = "color = saturate(color);";
        let wgsl = translate_shader(hlsl).unwrap();
        assert!(wgsl.contains("clamp"));
    }

    #[test]
    fn texture_sampling_routes_through_main_sampler() {
        let hlsl = "color = tex2D(sampler_main, uv);";
        let wgsl = translate_shader(hlsl).unwrap();
        // The codegen wrapper exposes `sampler_main_texture` + `sampler_main`,
        // so every tex2D call must land on those two bindings.
        assert!(
            wgsl.contains("textureSample(sampler_main_texture, sampler_main, uv)"),
            "got: {wgsl}"
        );
    }

    #[test]
    fn texture_sampling_unknown_samplers_still_fall_back() {
        // User-loaded textures and arbitrary preset sampler names that the
        // wrapper doesn't recognise must keep producing valid WGSL. The
        // translator routes them through `sampler_main` and tags the
        // origin name in a comment for debugging.
        let hlsl = "color = tex2D(sampler_clouds, uv);";
        let wgsl = translate_shader(hlsl).unwrap();
        assert!(
            wgsl.contains("textureSample(sampler_main_texture, sampler_main, uv)"),
            "got: {wgsl}"
        );
        assert!(wgsl.contains("/*was: sampler_clouds*/"));
    }

    #[test]
    fn fw_fc_pw_pc_main_route_to_matching_sampler() {
        // The four MD2 sampler variants of `main` keep the main texture but
        // pick a different sampler binding. The translator no longer
        // collapses them to the plain `sampler_main` — they hit
        // `sampler_fw`/`_fc`/`_pw`/`_pc` directly.
        for (name, expected_sampler) in [
            ("sampler_fw_main", "sampler_fw"),
            ("sampler_fc_main", "sampler_fc"),
            ("sampler_pw_main", "sampler_pw"),
            ("sampler_pc_main", "sampler_pc"),
        ] {
            let hlsl = format!("color = tex2D({name}, uv);");
            let wgsl = translate_shader(&hlsl).unwrap();
            let needle = format!("textureSample(sampler_main_texture, {expected_sampler}, uv)");
            assert!(wgsl.contains(&needle), "for {name}, got: {wgsl}");
            // Recognised bindings don't emit the `/*was: …*/` debug
            // comment — keeps the translated WGSL tidy.
            assert!(
                !wgsl.contains(&format!("/*was: {name}*/")),
                "recognised variant should not carry a fallback comment"
            );
        }
    }

    #[test]
    fn noise_2d_samplers_route_to_dedicated_textures() {
        for (sampler, expected_tex) in [
            ("sampler_noise_lq", "sampler_noise_lq_texture"),
            ("sampler_noise_mq", "sampler_noise_mq_texture"),
            ("sampler_noise_hq", "sampler_noise_hq_texture"),
            // Prefixed variants pick the same texture but a different
            // sampler — covered by `noise_2d_prefixed_picks_sampler`.
            ("sampler_pw_noise_lq", "sampler_noise_lq_texture"),
            ("sampler_fw_noise_hq", "sampler_noise_hq_texture"),
        ] {
            let hlsl = format!("color = tex2D({sampler}, uv);");
            let wgsl = translate_shader(&hlsl).unwrap();
            assert!(
                wgsl.contains(&format!("textureSample({expected_tex},")),
                "for {sampler}, got: {wgsl}"
            );
        }
    }

    #[test]
    fn noise_2d_prefixed_picks_sampler() {
        let wgsl = translate_shader("color = tex2D(sampler_pw_noise_lq, uv);").unwrap();
        assert!(
            wgsl.contains("textureSample(sampler_noise_lq_texture, sampler_pw, uv)"),
            "got: {wgsl}"
        );
    }

    #[test]
    fn tex3d_noisevol_samplers_hit_3d_texture() {
        // Real MD2 pattern: `tex3D(sampler_noisevol_hq, uvw)`. An earlier
        // implementation degraded this to a 2D GetPixel call; now it hits
        // the real texture_3d binding.
        let wgsl =
            translate_shader("color = tex3D(sampler_noisevol_hq, vec3<f32>(uv, time));").unwrap();
        assert!(
            wgsl.contains("textureSample(sampler_noisevol_hq_texture,"),
            "got: {wgsl}"
        );
        // No `GetPixel(...)` fallback should remain in the translated body.
        assert!(
            !wgsl.contains("GetPixel((vec3<f32>(uv, time)).xy)"),
            "fallback path should be gone: {wgsl}"
        );
    }

    #[test]
    fn tex3d_unknown_sampler_keeps_fallback() {
        // An unrecognised tex3D sampler still degrades to the 2D fallback
        // so the wrapper compiles even when the author references a
        // texture we don't bind.
        let wgsl = translate_shader("color = tex3D(sampler_user_volume, uvw);").unwrap();
        assert!(
            wgsl.contains("GetPixel((uvw).xy)"),
            "expected fallback, got: {wgsl}"
        );
    }

    #[test]
    fn shader_body_wrapper_is_stripped() {
        let hlsl = "shader_body\n{\n    ret = float3(1, 0, 0);\n}\n";
        let out = strip_shader_body_wrapper(hlsl);
        assert!(!out.contains("shader_body"), "wrapper not stripped: {out}");
        assert!(out.contains("ret = float3(1, 0, 0)"));
    }

    #[test]
    fn shader_body_with_inner_braces_balances() {
        // A nested block (e.g. an `if`) must not cut the wrapper off early.
        let hlsl = r#"shader_body
{
    if (a > 0) {
        ret = float3(1, 0, 0);
    }
    ret *= 0.5;
}"#;
        let out = strip_shader_body_wrapper(hlsl);
        assert!(!out.contains("shader_body"));
        assert!(out.contains("ret *= 0.5"));
    }

    #[test]
    fn shader_body_with_brace_in_comment_balances() {
        let hlsl = r#"shader_body
{
    // closing } in a comment must not end the body
    ret = float3(1);
}"#;
        let out = strip_shader_body_wrapper(hlsl);
        assert!(!out.contains("shader_body"));
        assert!(out.contains("ret = float3(1)"));
    }

    #[test]
    fn no_shader_body_wrapper_is_passthrough() {
        let hlsl = "ret = float3(1, 0, 0);";
        let out = strip_shader_body_wrapper(hlsl);
        assert_eq!(out, hlsl);
    }

    #[test]
    fn local_declaration_with_init_becomes_var() {
        let hlsl = "shader_body { float gx1 = a + b * c; ret = gx1.xxx; }";
        let wgsl = translate_shader(hlsl).unwrap();
        assert!(
            wgsl.contains("var gx1: f32 = a + b * c"),
            "expected var-form local, got: {wgsl}"
        );
    }

    #[test]
    fn local_declaration_without_init_becomes_var() {
        // Real preset pattern: declare a vec2, then assign to it on the next
        // few lines (for incrementally building offset UVs). The rewriter is
        // line-anchored — preset bodies span multiple lines, which is the
        // shape it's optimised for.
        let hlsl = "    vec2<f32> uv2;\n    uv2 = uv;\n";
        // Note: `vec2<f32>` is what `replace_types` emits — here we feed it
        // post-substitution to assert the rewriter handles WGSL-shaped types.
        let wgsl = rewrite_local_declarations(hlsl);
        assert!(wgsl.contains("var uv2: vec2<f32>;"), "got: {wgsl}");
    }

    #[test]
    fn local_declaration_multi_name_expands() {
        let hlsl = "    vec3<f32> ret1, neu, crisp, blur;\n";
        let wgsl = rewrite_local_declarations(hlsl);
        // Each name becomes its own var statement.
        assert!(wgsl.contains("var ret1: vec3<f32>;"), "got: {wgsl}");
        assert!(wgsl.contains("var neu: vec3<f32>;"));
        assert!(wgsl.contains("var crisp: vec3<f32>;"));
        assert!(wgsl.contains("var blur: vec3<f32>;"));
    }

    #[test]
    fn inline_multi_decl_on_single_line_splits() {
        // Isosceles preset's kaleidoscope state line. Without the
        // pre-split, only `cntr` would convert; `sin`, `cos`, `scale`
        // would stay as raw HLSL and trip naga.
        //
        // Top-level globals (`cntr`, `scale`) get hoisted to module-
        // scope `var<private>` so lifted user functions can read them.
        // `sin` / `cos` are kept as fs_main locals (they shadow WGSL
        // builtins; hoisting would break every other site that calls
        // `sin(x)` as a function).
        let hlsl =
            "float2 cntr = float2(q13,q14); float sin = q11; float cos = q12; float scale = q15;";
        let wgsl = translate_shader(hlsl).unwrap();
        assert!(
            wgsl.contains("var<private> cntr: vec2<f32>;"),
            "got: {wgsl}"
        );
        assert!(wgsl.contains("cntr = vec2<f32>(q13,q14);"), "got: {wgsl}");
        assert!(wgsl.contains("var sin: f32 = q11;"), "got: {wgsl}");
        assert!(wgsl.contains("var cos: f32 = q12;"), "got: {wgsl}");
        assert!(wgsl.contains("var<private> scale: f32;"), "got: {wgsl}");
        assert!(wgsl.contains("scale = q15;"), "got: {wgsl}");
    }

    #[test]
    fn inline_split_handles_vec_types_after_prior_decl() {
        // Regression guard — a naive `\b` boundary in
        // `INLINE_DECL_SPLIT_REGEX` would fail after `>` (already
        // non-word), so a `vec2<f32>` decl following any other
        // `;`-terminated decl on the same line would stay un-rewritten.
        // Real preset shape lifted from `MilkDrop2077.1040.milk` (the
        // `shadow` helper):
        let hlsl = "f32 dark; vec2<f32> uvc, dx;";
        let wgsl = rewrite_local_declarations(hlsl);
        assert!(wgsl.contains("var dark: f32;"), "got: {wgsl}");
        assert!(wgsl.contains("var uvc: vec2<f32>;"), "got: {wgsl}");
        assert!(wgsl.contains("var dx: vec2<f32>;"), "got: {wgsl}");
    }

    #[test]
    fn inline_split_detaches_open_brace_glue() {
        // Regression guard — `{TYPE` glued at the head of a function or
        // conditional body wasn't split by a `;`-only separator. The
        // first inner decl therefore stayed attached to the brace and
        // `LOCAL_DECL_REGEX` (anchored at the start of a line) skipped
        // it. Real preset shape from `MilkDrop2077.1040.milk`'s
        // `MinDistB`:
        let hlsl = "f32 MinDistB(uvi: vec2<f32>) {f32 tmp; vec4<f32> nb;}";
        let wgsl = rewrite_local_declarations(hlsl);
        assert!(wgsl.contains("var tmp: f32;"), "got: {wgsl}");
        assert!(wgsl.contains("var nb: vec4<f32>;"), "got: {wgsl}");
    }

    #[test]
    fn inline_split_skips_vec_constructor_call() {
        // The split must NOT fire on `; vec3<f32>(0, 0, 0)` — that's a
        // constructor expression, not a declaration. The regex requires
        // an identifier char after the type+space, so a following `(`
        // (constructor) is left alone.
        let hlsl = "ret = vec3<f32>(0.0); vec3<f32>(1.0);";
        let wgsl = rewrite_local_declarations(hlsl);
        // No newline injected before the bare constructor — the original
        // `;` and ` vec3<f32>(1.0);` stay on one line.
        assert!(!wgsl.contains(";\nvec3<f32>(1.0)"), "got: {wgsl}");
    }

    #[test]
    fn for_loop_init_semi_does_not_split_inline_decls() {
        // The inline-decl splitter must not fire on the `;` inside a
        // `for(...)` init/cond/step. Standard for-loop shape has the
        // first `;` followed by an expression, never by a type keyword.
        // The for-int rewrite has already turned `int` into `var i: i32
        // =` shape by this stage, so we feed the post-rewrite shape.
        let hlsl = "for(var i: i32 = 0; i < 10; i = i + 1) { ret = vec3<f32>(0); }";
        let wgsl = rewrite_local_declarations(hlsl);
        // No newline injected after the first `;` (the loop condition
        // separator) — the `i < 10` test stays intact.
        assert!(wgsl.contains("i < 10"), "got: {wgsl}");
        assert!(
            !wgsl.contains(";\ni < 10"),
            "for-loop `;` got wrongly split: {wgsl}"
        );
    }

    #[test]
    fn local_declaration_i32_loop_counter() {
        // `int anz = 3;` is widened to `f32` by `replace_types` (MD2 uses
        // ints interchangeably with floats), so the rewrite produces a
        // float var. At top level (no enclosing `shader_body`), it parses
        // as `Item::GlobalVar` and the hoist pass splits it into a
        // module-scope `var<private>` plus an in-body assignment.
        let hlsl = "    int anz = 3;\n";
        let wgsl = translate_shader(hlsl).unwrap();
        assert!(wgsl.contains("var<private> anz: f32;"), "got: {wgsl}");
        assert!(wgsl.contains("anz = 3;"), "got: {wgsl}");
    }

    #[test]
    fn sampler_declaration_is_stripped() {
        let hlsl = "sampler sampler_pw_noise_lq;\nret = float3(1);\n";
        let out = strip_sampler_declarations(hlsl);
        assert!(!out.contains("sampler_pw_noise_lq"));
        assert!(out.contains("ret = float3(1)"));
    }

    #[test]
    fn preprocessor_directives_are_stripped() {
        let hlsl = "#define M_PI 3.14159\n#include <something>\nret = float3(1);";
        let out = strip_preprocessor(hlsl);
        assert!(!out.contains("#define"));
        assert!(!out.contains("#include"));
        assert!(out.contains("ret = float3(1)"));
    }

    #[test]
    fn brace_up_single_statement_if() {
        let src = "if (a > 0) ret = 1.0;";
        let out = brace_up_single_statement_blocks(src);
        assert!(out.contains("if (a > 0) {"), "got: {out}");
        assert!(out.contains("ret = 1.0;"));
        assert!(out.ends_with("}"));
    }

    #[test]
    fn brace_up_leaves_already_braced_alone() {
        let src = "if (a > 0) { ret = 1.0; }";
        let out = brace_up_single_statement_blocks(src);
        assert_eq!(out, src);
    }

    #[test]
    fn brace_up_skips_keyword_inside_identifier() {
        // `notif` and `forevermore` must not be treated as if/for keywords.
        let src = "var notif: f32 = 0;";
        let out = brace_up_single_statement_blocks(src);
        assert_eq!(out, src);
    }

    #[test]
    fn brace_up_handles_nested_parens_in_condition() {
        let src = "if (max(a, b) > 0) ret.z -= 0.5;";
        let out = brace_up_single_statement_blocks(src);
        assert!(out.contains("if (max(a, b) > 0) {"), "got: {out}");
    }

    #[test]
    fn brace_up_handles_function_call_in_body() {
        // The `;` we wrap to is the end-of-statement, not the one inside
        // `mix(a, b);`.
        let src = "if (a > 0) ret = mix(a, b, 0.5);";
        let out = brace_up_single_statement_blocks(src);
        assert!(out.contains("ret = mix(a, b, 0.5);"));
        assert!(out.ends_with("}"));
    }

    #[test]
    fn tex3d_known_noisevol_hits_3d_binding() {
        // The pipeline binds the volume noise for real, so
        // `tex3D(sampler_noisevol_hq, …)` resolves to a `textureSample`
        // against the 3D texture instead of the legacy `GetPixel(uvw.xy)`
        // fallback.
        let src = "ret = tex3D(sampler_noisevol_hq, vec3<f32>(uv, time));";
        let out = rewrite_tex3d_calls(src);
        assert!(
            out.contains(
                "textureSample(sampler_noisevol_hq_texture, sampler_pw, vec3<f32>(uv, time))"
            ),
            "got: {out}"
        );
    }

    #[test]
    fn lerp_with_whitespace_is_normalised_and_rewritten() {
        // Real preset pattern: a multi-line `lerp (\n  a,\n  b,\n  t)` call
        // becomes `mix(...)` thanks to call-whitespace normalisation.
        let hlsl = "ret = lerp (a, b, 0.5);";
        let wgsl = translate_shader(hlsl).unwrap();
        assert!(wgsl.contains("mix(a, b, 0.5)"), "got: {wgsl}");
        assert!(!wgsl.contains("lerp"));
    }

    #[test]
    fn float2x2_becomes_mat2x2() {
        // HLSL float2x2 is a 2×2 matrix; the previous code only handled
        // 3×3 and 4×4 so `float2x2` got mangled by the `float2` rewrite
        // into `vec2<f32>x2` (which then failed naga's parser).
        let hlsl = "var m: f32 = 0; uv1 = mul(float2x2(q9,q10,-q10,q9), uv1);";
        let wgsl = translate_shader(hlsl).unwrap();
        assert!(wgsl.contains("mat2x2<f32>"), "got: {wgsl}");
        assert!(!wgsl.contains("vec2<f32>x2"));
    }

    #[test]
    fn unary_plus_is_stripped_after_open_paren() {
        let hlsl = "ret.x += (+dx.x - dy.x)*0.4;";
        let wgsl = translate_shader(hlsl).unwrap();
        // The unary `+` after `(` must be gone; the binary `-` stays.
        assert!(wgsl.contains("(dx.x - dy.x)"), "got: {wgsl}");
    }

    #[test]
    fn statement_commas_become_semicolons() {
        // `ret += a, ret += b;` → `ret += a; ret += b;`.
        let src = "ret += a, ret += b;";
        let out = replace_statement_commas(src);
        assert_eq!(out, "ret += a; ret += b;");
    }

    #[test]
    fn dedup_var_decl_second_becomes_assignment() {
        let src = "var ret1: vec3<f32> = vec3<f32>(0);\nvar ret1: vec3<f32> = ret1;\n";
        let out = dedup_var_declarations(src);
        assert!(
            out.contains("var ret1: vec3<f32> = vec3<f32>(0);"),
            "got: {out}"
        );
        assert!(out.contains("ret1 = ret1;"), "got: {out}");
    }

    #[test]
    fn postfix_increment_becomes_compound_assignment() {
        let src = "n++;";
        let out = rewrite_postfix_inc_dec(src);
        assert_eq!(out, "n = n + 1;");
    }

    #[test]
    fn postfix_decrement_in_for_loop() {
        let src = "for (i = 10; i > 0; i--) { }";
        let out = rewrite_postfix_inc_dec(src);
        assert!(out.contains("i = i - 1)"), "got: {out}");
    }

    #[test]
    fn postfix_increment_inside_expression_left_alone() {
        // We only rewrite at statement/loop-iter boundaries; bare `a + + b`
        // in expression position would already have whitespace separation
        // and not match our regex.
        let src = "y = a + b;";
        let out = rewrite_postfix_inc_dec(src);
        assert_eq!(out, src);
    }

    #[test]
    fn static_const_qualifier_stripped() {
        let src = "static const int anz = 3;";
        let out = strip_storage_class_qualifiers(src);
        // After both passes: `static` dropped, `const int` → `int`.
        assert_eq!(out.trim(), "int anz = 3;");
    }

    #[test]
    fn statement_commas_leave_call_args_alone() {
        // Commas inside `(...)` are call args, not statement separators.
        let src = "ret = mix(a, b, t);";
        let out = replace_statement_commas(src);
        assert_eq!(out, src);
    }

    #[test]
    fn end_to_end_typical_md2_comp_shader() {
        // The simplest real-world comp shader pattern. After translation +
        // shader_body strip, the body should be syntactically WGSL-valid.
        let hlsl = r#"shader_body
{
    ret = tex2D(sampler_main, uv).xyz;
    ret *= 1.28; //gamma
    ret *= ret; //darken
}"#;
        let wgsl = translate_shader(hlsl).unwrap();
        assert!(!wgsl.contains("shader_body"));
        assert!(wgsl.contains("textureSample(sampler_main_texture, sampler_main, uv)"));
        assert!(!wgsl.contains("float"));
    }

    // ---------------------------------------------------------------
    // User texture binding plan + scan
    // ---------------------------------------------------------------

    #[test]
    fn scan_extracts_user_sampler_declarations() {
        let hlsl = "sampler sampler_clouds;\nsampler sampler_lichen;\nret = tex2D(sampler_clouds, uv).xyz;";
        let refs = scan_user_samplers(hlsl);
        let names: Vec<&str> = refs.iter().map(|r| r.full_name.as_str()).collect();
        assert!(names.contains(&"sampler_clouds"));
        assert!(names.contains(&"sampler_lichen"));
    }

    #[test]
    fn scan_skips_builtins() {
        let hlsl = "sampler sampler_main;\nsampler sampler_fw_main;\nsampler sampler_noise_lq;\nsampler sampler_clouds;\nsampler sampler_blur1;";
        let refs = scan_user_samplers(hlsl);
        let names: Vec<&str> = refs.iter().map(|r| r.full_name.as_str()).collect();
        assert_eq!(
            names,
            vec!["sampler_clouds"],
            "only the user texture should survive"
        );
    }

    #[test]
    fn scan_collapses_duplicates_by_full_name() {
        let hlsl = "sampler sampler_clouds;\nsampler sampler_clouds;\n";
        let refs = scan_user_samplers(hlsl);
        assert_eq!(refs.len(), 1);
    }

    #[test]
    fn decompose_sampler_name_handles_filter_prefixes() {
        assert_eq!(
            decompose_sampler_name("sampler_clouds"),
            ("clouds".to_string(), "sampler_fw")
        );
        assert_eq!(
            decompose_sampler_name("sampler_fw_clouds"),
            ("clouds".to_string(), "sampler_fw")
        );
        assert_eq!(
            decompose_sampler_name("sampler_pc_clouds"),
            ("clouds".to_string(), "sampler_pc")
        );
        assert_eq!(
            decompose_sampler_name("sampler_rand02_smalltiled"),
            ("rand02_smalltiled".to_string(), "sampler_fw")
        );
    }

    #[test]
    fn plan_empty_falls_back_to_legacy_translator() {
        let plan = TextureBindingPlan::empty();
        let wgsl = translate_shader_with_plan("color = tex2D(sampler_clouds, uv);", &plan).unwrap();
        // Empty plan path: the fallback `/*was: ...*/` comment must still
        // appear (no user routing applied).
        assert!(wgsl.contains("/*was: sampler_clouds*/"), "got: {wgsl}");
    }

    #[test]
    fn plan_routes_user_sampler_to_user_binding() {
        let mut plan = TextureBindingPlan::empty();
        let slot = plan
            .add_slot(
                Some("clouds".to_string()),
                [256.0, 256.0, 1.0 / 256.0, 1.0 / 256.0],
                &[("sampler_clouds".to_string(), "sampler_fw")],
            )
            .unwrap();
        assert_eq!(slot, 0);
        let wgsl = translate_shader_with_plan("color = tex2D(sampler_clouds, uv);", &plan).unwrap();
        // The translator must emit the user-slot binding, not the fallback.
        assert!(
            wgsl.contains("textureSample(sampler_user_0_texture, sampler_fw, uv)"),
            "got: {wgsl}"
        );
        assert!(!wgsl.contains("/*was: sampler_clouds*/"));
    }

    #[test]
    fn plan_two_aliases_share_a_slot() {
        // `sampler sampler_clouds` and `sampler sampler_fw_clouds` both
        // resolve to the same logical "clouds" texture but pick a different
        // sampler binding at each call site.
        let mut plan = TextureBindingPlan::empty();
        plan.add_slot(
            Some("clouds".to_string()),
            [256.0, 256.0, 1.0 / 256.0, 1.0 / 256.0],
            &[
                ("sampler_clouds".to_string(), "sampler_fw"),
                ("sampler_fw_clouds".to_string(), "sampler_fw"),
                ("sampler_pc_clouds".to_string(), "sampler_pc"),
            ],
        );
        assert_eq!(plan.slot_count(), 1, "all aliases must share one slot");

        // Translating each alias keeps the slot but flips the sampler kind.
        let s1 =
            translate_shader_with_plan("ret = tex2D(sampler_fw_clouds, uv).xyz;", &plan).unwrap();
        let s2 =
            translate_shader_with_plan("ret = tex2D(sampler_pc_clouds, uv).xyz;", &plan).unwrap();
        assert!(s1.contains("textureSample(sampler_user_0_texture, sampler_fw, uv)"));
        assert!(s2.contains("textureSample(sampler_user_0_texture, sampler_pc, uv)"));
    }

    // ---------------------------------------------------------------
    // Quick translator fixes
    // ---------------------------------------------------------------

    #[test]
    fn mod_call_rewritten_to_float_mod_expansion() {
        // `mod` is a WGSL reserved keyword; HLSL uses it as the float
        // modulo helper. The expansion must match HLSL semantics
        // (= `a - floor(a/b)*b`).
        let wgsl = translate_shader("ret.x = mod(ang*16/M_PI, 1.0);").unwrap();
        assert!(
            wgsl.contains("floor((ang*16/M_PI) / (1.0)) * (1.0)"),
            "got: {wgsl}"
        );
        assert!(!wgsl.contains("mod("), "mod( call must be gone: {wgsl}");
    }

    #[test]
    fn lowercase_tex2d_normalised_to_tex2d() {
        // Real preset typo: `tex2d(sampler_main, uv)`. WGSL is case-
        // sensitive; the wrapper exposes `textureSample` only through the
        // canonical `tex2D` rewrite path. Normalise before the rewrite.
        let wgsl = translate_shader("ret = tex2d(sampler_main, uv).xyz;").unwrap();
        assert!(
            wgsl.contains("textureSample(sampler_main_texture, sampler_main, uv)"),
            "got: {wgsl}"
        );
    }

    #[test]
    fn lowercase_tex3d_normalised() {
        let wgsl =
            translate_shader("ret = tex3d(sampler_noisevol_hq, vec3<f32>(uv, time)).xyz;").unwrap();
        assert!(
            wgsl.contains("textureSample(sampler_noisevol_hq_texture,"),
            "got: {wgsl}"
        );
    }

    // ---------------------------------------------------------------
    // User-defined function lifting
    // ---------------------------------------------------------------

    #[test]
    fn reserved_identifier_mod_as_local_renamed() {
        // Real preset: `float mod = sin(...); ... q22*mod*...`. After
        // `mod()` function-call rewriting, the bare `mod` ident stays —
        // WGSL rejects it as reserved. We rename to `mod_`.
        let wgsl = translate_shader("float mod = sin(uv.x);\nret.y *= mod * 0.5;").unwrap();
        assert!(wgsl.contains("var mod_: f32"), "var rename missing: {wgsl}");
        assert!(
            wgsl.contains("mod_ * 0.5"),
            "reference rename missing: {wgsl}"
        );
    }

    #[test]
    fn reserved_identifier_filter_renamed() {
        // `float3 filter` as a function param or local must become `filter_`.
        let wgsl =
            translate_shader("float3 filter = float3(1, 1, 1);\nret = filter * GetPixel(uv);")
                .unwrap();
        assert!(
            wgsl.contains("var filter_: vec3<f32>"),
            "filter var rename missing: {wgsl}"
        );
    }

    #[test]
    fn user_function_is_lifted_above_body() {
        // Real preset pattern: a helper function declared before the
        // shader_body block. After translation, it should appear before
        // the LIFTED_FN_SENTINEL, with the WGSL `fn ... ->` signature.
        let hlsl = "float2 helper(float2 a, float3 b) {\n\
                       return a * 0.5 + b.xy;\n\
                    }\n\
                    shader_body {\n\
                       ret.xy = helper(uv, vec3<f32>(0));\n\
                    }";
        let wgsl = translate_shader(hlsl).unwrap();
        assert!(wgsl.contains(LIFTED_FN_SENTINEL));
        let (lifted, body) = wgsl.split_once(LIFTED_FN_SENTINEL).unwrap();
        // Signature converted: HLSL form gone, WGSL form present.
        assert!(
            lifted.contains("fn helper(a: vec2<f32>, b: vec3<f32>) -> vec2<f32>"),
            "lifted block missing canonical signature: {lifted}"
        );
        // Body uses the function; the call form itself is preserved as
        // an identifier reference inside fs_main.
        assert!(body.contains("helper("), "call site missing: {body}");
    }

    #[test]
    fn no_lift_when_no_function_definitions() {
        // Bodies without module-scope function defs must NOT emit a
        // sentinel — preserves backwards-compatibility for the v0.17.0
        // text shape.
        let hlsl = "shader_body { ret = ret * 0.5; }";
        let wgsl = translate_shader(hlsl).unwrap();
        assert!(!wgsl.contains(LIFTED_FN_SENTINEL));
    }

    #[test]
    fn lift_handles_zero_arg_function() {
        let hlsl = "float3 zero() { return vec3<f32>(0); }\n\
                    shader_body { ret = zero(); }";
        let wgsl = translate_shader(hlsl).unwrap();
        let (lifted, _body) = wgsl.split_once(LIFTED_FN_SENTINEL).unwrap();
        assert!(lifted.contains("fn zero() -> vec3<f32>"), "got: {lifted}");
    }

    #[test]
    fn lift_geiss_explosion_3_helper_translates_cleanly() {
        // Reduced repro from `Geiss - Explosion 3 nz+...milk`. The
        // helper uses `filter` as a parameter name (WGSL-reserved) and
        // a local `dx` of type vec3 with a parenthesised RHS.
        let hlsl = "float2 gradBlur1( float2 domain, float2 d, float3 filter){\n\
                       float3 dx = ( 2*GetBlur1(domain + float2(1,0)*d) - 2*GetBlur1(domain-float2(1,0)*d) );\n\
                       return 0.5*float2(dx.x*filter.x, dx.y*filter.y) / (filter.x+filter.y+filter.z);\n\
                    }\n\
                    shader_body { ret.xy = gradBlur1(uv, vec2<f32>(0.5), vec3<f32>(0.5,0.5,0.5)); }";
        let wgsl = translate_shader(hlsl).unwrap();
        assert!(wgsl.contains(LIFTED_FN_SENTINEL), "no sentinel: {wgsl}");
        let (lifted, _body) = wgsl.split_once(LIFTED_FN_SENTINEL).unwrap();
        // Lifted body must use WGSL `var` for the local, not HLSL
        // `vec3<f32> dx`. This is what the parse error "expected `(`;
        // found `dx`" was originally about.
        assert!(
            lifted.contains("var dx: vec3<f32>"),
            "local-decl rewrite didn't reach lifted body: {lifted}"
        );
        // `filter` must have been renamed to avoid the WGSL keyword.
        assert!(
            lifted.contains("filter_:"),
            "filter param not renamed in signature: {lifted}"
        );
    }

    #[test]
    fn lift_handles_function_with_nested_braces() {
        // A user function with an inner `{...}` block (e.g., an `if`)
        // must balance braces correctly and not chop off mid-body.
        let hlsl = "float foo(float t) {\n\
                       if (t > 0) { return t * 2; }\n\
                       return 0;\n\
                    }\n\
                    shader_body { ret.x = foo(0.5); }";
        let wgsl = translate_shader(hlsl).unwrap();
        let (lifted, _body) = wgsl.split_once(LIFTED_FN_SENTINEL).unwrap();
        assert!(
            lifted.contains("if (t > 0)"),
            "inner if dropped during lift: {lifted}"
        );
        assert!(lifted.contains("return 0;"));
    }

    #[test]
    fn plan_cap_is_enforced() {
        let mut plan = TextureBindingPlan::empty();
        for i in 0..MAX_USER_TEXTURE_SLOTS {
            let name = format!("tex_{i}");
            let alias = format!("sampler_tex_{i}");
            plan.add_slot(Some(name), [1.0, 1.0, 1.0, 1.0], &[(alias, "sampler_fw")])
                .unwrap();
        }
        // One past the cap → None.
        let over = plan.add_slot(
            Some("overflow".to_string()),
            [1.0; 4],
            &[("sampler_overflow".to_string(), "sampler_fw")],
        );
        assert!(over.is_none());
        assert_eq!(plan.slot_count(), MAX_USER_TEXTURE_SLOTS);
    }

    // ---------- non-square mat, builtin aliases, prose ----------

    #[test]
    fn float2x3_maps_to_mat2x3() {
        // Non-square matrix types were getting mangled by the
        // `float2`→`vec2<f32>` substring substitution, leaving
        // `vec2<f32>x3` and tripping the WGSL parser with
        // `expected ')'; found 'x3'`. Many comp residual failures share
        // this root cause.
        let out = replace_types("float2x3 m;");
        assert_eq!(out, "mat2x3<f32> m;");
    }

    #[test]
    fn float3x2_and_other_non_square_matrices_map_correctly() {
        for (hlsl, wgsl) in [
            ("float3x2", "mat3x2<f32>"),
            ("float4x3", "mat4x3<f32>"),
            ("float2x4", "mat2x4<f32>"),
            ("float3x4", "mat3x4<f32>"),
            ("float4x2", "mat4x2<f32>"),
        ] {
            let out = replace_types(&format!("{hlsl} m;"));
            assert_eq!(out, format!("{wgsl} m;"), "mapping {hlsl}");
        }
    }

    #[test]
    fn sat_aliases_saturate() {
        // Corpus ships `#define sat saturate` (stripped by
        // `strip_preprocessor`) followed by `sat(…)` calls that would go
        // unbound on the WGSL side. We alias the call here.
        let out = replace_functions("ret = sat(x);");
        assert!(out.contains("clamp(x, 0.0, 1.0)"), "got: {out}");
    }

    #[test]
    fn rsqrt_aliases_inverse_sqrt() {
        let out = replace_functions("ret = rsqrt(x);");
        assert!(out.contains("inverseSqrt(x)"), "got: {out}");
    }

    #[test]
    fn log10_expands_to_natural_log() {
        let out = replace_functions("ret = log10(x);");
        assert!(out.contains("(log(x) * 0.43429448190325176)"), "got: {out}");
    }

    #[test]
    fn tex2dbias_drops_mip_bias_args() {
        let out = replace_functions("ret = tex2Dbias(sampler_main, float4(uv, 0, 0.1));");
        assert!(out.contains("tex2D(sampler_main, uv)"), "got: {out}");
    }

    #[test]
    fn multi_decl_sampler_list_stripped() {
        // `sampler a, b, c;` is a common HLSL stylistic shortcut. A
        // simpler regex matching only the first identifier would let the
        // rest survive as orphan statements that trip the WGSL parser.
        let src = "sampler sampler_fw_rand01, sampler_pw_rand02;\nret = uv.x;\n";
        let out = strip_sampler_declarations(src);
        assert!(!out.contains("sampler_fw_rand01"), "got: {out}");
        assert!(!out.contains("sampler_pw_rand02"), "got: {out}");
        assert!(out.contains("ret = uv.x"), "body lost: {out}");
    }

    #[test]
    fn prose_line_is_commented_out() {
        // `written by martin` style attributions inside the shader body
        // get a `// ` prefix so the WGSL parser doesn't choke on
        // `expected assignment or increment/decrement; found 'by'`.
        let src = "ret = 0.5;\nwritten by martin\nuv = uv * 2.0;\n";
        let out = comment_out_prose_lines(src);
        assert!(out.contains("// written by martin"), "got: {out}");
        assert!(out.contains("ret = 0.5;"), "real code lost: {out}");
        assert!(out.contains("uv = uv * 2.0;"), "real code lost: {out}");
    }

    #[test]
    fn prose_line_does_not_eat_keywords() {
        // A line starting with `for` or `if` is a control-flow construct,
        // not prose — never comment it out.
        for kw_line in ["for (var i = 0; i < 3; i = i + 1) {", "if x = 0;"] {
            let src = format!("{kw_line}\n");
            let out = comment_out_prose_lines(&src);
            assert_eq!(out, src, "wrongly commented out: {kw_line}");
        }
    }

    #[test]
    fn bare_end_marker_commented_out() {
        // The MD2 corpus sometimes appends `END` (or similar single-word
        // markers) after `shader_body`. After `strip_shader_body_wrapper`
        // those lines land in the fragment body and crash the parser.
        let src = "ret = 0.5;\nEND\n";
        let out = comment_out_prose_lines(src);
        assert!(out.contains("// END"), "got: {out}");
    }
}