use std::collections::hash_map::DefaultHasher;
use std::fmt::Write as _;
use std::hash::{Hash, Hasher};
use std::process::Command;
use std::{fs, path::Path};

fn main() {
    // Set GIT_HASH env var for compile-time inclusion via option_env!()
    println!("cargo::rustc-env=GIT_HASH={}", git_hash());

    // Compile the TypeScript frontend to static/dist/ (best-effort, see fn).
    build_frontend();

    // The three generated stylesheets. Spacing comes from makeover-geometry,
    // time from makeover-timing and composition from makeover-webview, the
    // same way colour already comes from makeover through theming.rs. Written
    // into static/ rather than a bundle directory because the server serves
    // its stylesheets; all three are gitignored, since the crates are the
    // source and a checked-in copy would drift from the pin.
    //
    // No explicit touch selector: density hangs off (hover: none),
    // (pointer: coarse) alone, because the server has no mode class to key it
    // on. GO passes `.ui-mode-mobile` because it has one.
    // The four scripts quasi-webview ships, written where the shell already says
    // they are served from. Each is behaviour a description cannot state and a
    // renderer therefore owns: how many rows are ticked and that a control over
    // none of them should not be pressable (`quasi-selection.js`), a readout
    // reckoned against the current time that keeps moving (`quasi-clock.js`),
    // an htmx answer that has to become a saved file rather than page text
    // (`quasi-download.js`), and a chosen value that lands in the box the
    // reader is typing in (`quasi-fill.js`).
    // `Shell::under("/static")` has named these addresses since each script
    // existed and only two of the files were being written, so every page has
    // been linking a script that 404s -- which is what the loop is for: a name
    // added to the renderer and forgotten here is a feature that silently does
    // nothing.
    //
    // Written from the crate's own constants for the reason they are constants:
    // the script reads hooks the emitter writes, so a copy checked in here goes
    // stale against the next bump in silence. Gitignored, like the stylesheets.
    for (name, source) in GENERATED_STATIC_JS {
        // `write_if_changed`, not `fs::write`, and this is load-bearing rather
        // than a micro-optimisation. `markup_files` globs `static/*.js`, and
        // `check_vocabulary_use` emits a `rerun-if-changed` for every file it
        // reads, so these four are files this script both writes AND watches.
        // An unconditional write moves the mtime on every run, cargo then sees
        // a watched file newer than the build script's own output, and the
        // crate recompiles on every cargo invocation forever. That is what put
        // a second full 5m25s compile inside every Sando `cargo_test` gate
        // (task 4200580f); cargo named this exact file as the stale one.
        write_if_changed(Path::new(&format!("static/{name}")), source);
    }

    makeover_build::geometry_css("static/geometry.css", None);
    // The time axis, beside the spacing one and for the same reason: the
    // durations are makeover-timing's answer, and a number typed into a
    // hand-written sheet here is the drift that crate exists to end.
    makeover_build::timing_css("static/timing.css");
    makeover_build::layout_css("static/layout.css", &makeover_build::Emit::default());

    // The embeds get their own copy of the spacing layer, because they are
    // served into third-party iframes and cannot link a stylesheet. Pointer
    // density only, and no `@media` block: an embed body is `height: 100vh`
    // inside an iframe the host page sized, so growing the gaps on a coarse
    // pointer clips rather than reflows, and the host author never sees it
    // happen. Revisit if embeds ever gain a resize protocol.
    fs::write(
        "static/embed-geometry.css",
        makeover_geometry::geometry_css_vars(makeover_geometry::Density::Pointer),
    )
    .expect("write static/embed-geometry.css");

    // The typography layer, and the faces it fetches.
    //
    // Two halves that have to agree: makeover_build writes the `@font-face`
    // rules and the tokens, and `cut_house_faces` puts the woff2 files where
    // those rules point. Both name the file through
    // `makeover::WEBFONT_*_FILE`, so the agreement is a constant rather than a
    // string typed twice.
    //
    // Young Serif is the third token, and it is here rather than in style.css
    // because that is what layer 0 is for. It used to be a hand-written
    // `@font-face` plus a `--font-heading` nothing outside this repository had
    // heard of; declared as an override it is the same shape as the two house
    // slots, and `--font-display` is the name every product uses for its brand
    // tier. The face itself is committed rather than cut: it is upstream's,
    // unmodified, and quasi-type has no part in it.
    makeover_build::typography_css_from(
        "static/typography.css",
        &makeover_build::Typography::house("/static/fonts").with_override(
            makeover_build::FontOverride::new(
                makeover_build::FontSlot::Display,
                "\"Young Serif\", serif",
            )
            .with_face(makeover_build::FontFace::new(
                "Young Serif",
                ["ysrf.woff2", "ysrf.ttf"],
            )),
        ),
    );

    // The embeds get the house layer WITHOUT the override, for the same reason
    // they get their own spacing layer: different context, different answer.
    // An embed carries no brand face by decision — `--font-display` is left
    // undefined so the `var(--font-display, Georgia, serif)` fallback in each
    // template renders — and the alternative is 21 KB of a serif face on
    // somebody else's page to style one card title. The two files are
    // generated from one `Typography` vocabulary, so they cannot disagree
    // about the house slots the way two hand-written sheets did.
    makeover_build::typography_css_from(
        "static/embed-typography.css",
        &makeover_build::Typography::house("/static/fonts"),
    );

    cut_house_faces();

    println!("cargo::rerun-if-changed=build.rs");

    // The landing shots' own dimensions, so the description can reserve their
    // space. Generated rather than written down; see `shot_dimensions`.
    let shots = shot_dimensions();
    let mut table = String::from(
        "/// Intrinsic size of each landing screenshot, by URL path.\n\
         /// Generated by build.rs from the files themselves.\n\
         pub static SHOT_DIMENSIONS: &[(&str, u32, u32)] = &[\n",
    );
    for (path, w, h) in &shots {
        let _ = writeln!(table, "    ({path:?}, {w}, {h}),");
    }
    table.push_str("];\n");
    fs::write(
        Path::new(&std::env::var("OUT_DIR").expect("OUT_DIR")).join("shot_dimensions.rs"),
        table,
    )
    .expect("write shot_dimensions.rs");

    // The same check goingson and balanced_breakfast run, out of
    // makeover-build rather than a third copy of it. The named-list form:
    // static/ holds the generated stylesheets and a bundler's output beside
    // the hand-written ones, so there is no directory to scan. No tuning
    // widths -- every threshold here is a shell boundary.
    makeover_build::check_breakpoints_files(&HAND_WRITTEN_CSS, &[]);
    makeover_build::check_vocabulary_files(
        &HAND_WRITTEN_CSS,
        &makeover_build::Emit::default(),
        REVIEWED_OVERLAPS,
        REVIEWED_ELEMENT_OVERLAPS,
    );
    makeover_build::check_vocabulary_use(
        &markup_files(),
        &makeover_build::Emit::default(),
        DEAD_VOCABULARY_HIGH_WATER,
    );

    // --- Static asset fingerprinting ---
    // Hash the content of key static files to produce a version suffix.
    // When any watched file changes, URLs in templates get a new ?v= param,
    // busting browser caches automatically.
    let static_files = [
        "static/style.css",
        // The two per-page sheets. Linked from page templates rather than
        // from the head, which is why they were outside the fingerprint and
        // served stale to any browser holding a cached copy.
        "static/wizard.css",
        "static/media-player.css",
        // Same case again, found 2026-08-15: linked from a <noscript> in the
        // carousel partial rather than from the head, so it was outside the
        // fingerprint and a change to it served stale to any browser holding a
        // cached copy. The visitors it exists for are the ones least likely to
        // hard-refresh.
        "static/no-js.css",
        "static/htmx.min.js",
        "static/upload.js",
        "static/passkey.js",
        // `static/insertions.js` was here until 2026-08-20. The file went away
        // in bd448cbe and the entry did not, so it was a watch on a path that
        // could not exist -- which cargo reads as changed, re-running this
        // script and recompiling the crate on every invocation. Same bug as the
        // old `.git/HEAD` watch; see `git_hash`. Anything added here must exist.
    ];

    let mut hasher = DefaultHasher::new();
    for path in &static_files {
        // Every path in the list above is expected to exist. Assert it rather
        // than watching a phantom: a deleted file that keeps its entry costs a
        // full recompile per cargo invocation and is invisible otherwise.
        assert!(
            Path::new(path).exists(),
            "build.rs watches {path}, which does not exist. Remove the entry, or \
             restore the file: a missing watch path recompiles this crate on \
             every cargo invocation.",
        );
        println!("cargo::rerun-if-changed={path}");
        if let Ok(content) = fs::read(path) {
            content.hash(&mut hasher);
        }
    }
    // Fold the emitted frontend bundles into the version so `?v=` busts when
    // the TypeScript changes. Read-only: the inputs under frontend/src are the
    // watched trigger (in build_frontend); watching the outputs would loop.
    hash_dir_js(Path::new("static/dist"), &mut hasher);
    // Same treatment for the generated stylesheets: read-only, so a bump of
    // makeover-geometry, makeover-timing or makeover-webview busts `?v=`
    // without the build script watching a file it writes itself.
    for path in [
        "static/geometry.css",
        "static/timing.css",
        "static/layout.css",
        "static/embed-geometry.css",
        // The tokens and the @font-face rules. Note what this does NOT cover:
        // the woff2 files themselves are served under fixed names with no `?v=`,
        // so a re-cut of the same slot ships new bytes at an old URL and a
        // browser holding a cached copy keeps it. That was equally true of the
        // Plex and Lato files this replaced, and a face changes about as often
        // as the glyph set version does, so it is a known edge rather than a
        // regression. The fix, if it ever bites, is a version in the URL
        // makeover is handed.
        "static/typography.css",
    ] {
        if let Ok(content) = fs::read(path) {
            content.hash(&mut hasher);
        }
    }
    let static_hash = format!("{:016x}", hasher.finish());
    let version = &static_hash[..8];

    // The head's own assets are no longer a generated partial: crate::shell
    // builds them into quasi-webview's Shell, which is what a described screen
    // renders through, so both halves of the converted site emit one head. All
    // that crosses the build boundary now is the version.
    println!("cargo::rustc-env=STATIC_VERSION={version}");

    // Per-page island loader macro. Heavy/page-specific islands (media player,
    // uploader, ...) load on the pages that use them via
    // `{% import "_island.html" as island %}{% call island::island("name") %}`,
    // cache-busted by the same content hash as the head assets.
    let island_partial = r#"{% macro island(name) -%}
<script type="module" src="/static/dist-__VER__/islands/{{ name }}.js"></script>
{%- endmacro %}
"#
    .replace("__VER__", version);
    write_if_changed(Path::new("templates/_island.html"), &island_partial);

    // Per-page stylesheet loader, same idea as the island macro. wizard.css and
    // media-player.css are linked by the pages that need them rather than by
    // the shell, so this is how they get the content hash.
    let sheet_partial = r#"{% macro sheet(name) -%}
<link rel="stylesheet" href="/static/{{ name }}?v=__VER__">
{%- endmacro %}
"#
    .replace("__VER__", version);
    write_if_changed(Path::new("templates/_sheet.html"), &sheet_partial);
}

/// Cut Quasi Mono and Quasi Body into `static/fonts/`, as woff2.
///
/// Cut rather than committed, which is the same rule `shop-font` and the Alloy
/// image follow: a face in the repository is a second source of truth that
/// nothing rebuilds, so the glyph set and the shipped face drift and nobody
/// finds out until a mark looks wrong. The pipeline is the source; these are
/// its output, and they are gitignored.
///
/// The base is downloaded into `OUT_DIR` once and checksummed against
/// quasi-type's pins, so a warm target directory needs no network. `offline` is
/// false because the first build on a fresh machine has to be able to fetch,
/// and a failure here is fatal rather than skipped: a missing face is a site
/// rendering in the fallback with nothing to say so.
fn cut_house_faces() {
    let cache = Path::new(&std::env::var("OUT_DIR").expect("cargo sets OUT_DIR")).join("bases");
    quasi_type::cut_web(
        Path::new("static/fonts"),
        &cache,
        false,
        &[
            ("quasi-mono", makeover_build::WEBFONT_MONO_FILE),
            ("quasi-body", makeover_build::WEBFONT_SANS_FILE),
        ],
    )
    .expect("cut the house faces");
}

/// Intrinsic dimensions of the landing screenshots, read from the files.
///
/// A picture that cannot say how big it is cannot have its space reserved, so
/// the browser gives it none until the bytes land and then takes its full
/// height at once, which is a 478px jump per frame on the landing page and
/// 0.087 CLS for the document.
///
/// Read here rather than written down, because these files are regenerated by
/// `scripts/capture-landing-carousel.mjs` and a hand-maintained number would be
/// wrong the first time anyone re-shot them -- silently, since a wrong reserve
/// looks like a right one until the image lands.
///
/// WebP only, which is what the capture script emits. A file this cannot parse
/// is skipped rather than guessed at: `None` reserves nothing, which is the
/// behaviour before this existed, while a wrong number reserves the wrong room.
fn shot_dimensions() -> Vec<(String, u32, u32)> {
    let dir = Path::new("static/images/shots");
    println!("cargo::rerun-if-changed=static/images/shots");
    let mut out = Vec::new();
    let Ok(entries) = fs::read_dir(dir) else {
        return out;
    };
    for entry in entries.flatten() {
        let path = entry.path();
        if path.extension().and_then(|e| e.to_str()) != Some("webp") {
            continue;
        }
        let Ok(bytes) = fs::read(&path) else { continue };
        let Some((w, h)) = webp_dimensions(&bytes) else {
            continue;
        };
        if let Some(name) = path.file_name().and_then(|n| n.to_str()) {
            out.push((format!("/static/images/shots/{name}"), w, h));
        }
    }
    out.sort();
    out
}

/// Canvas size from a WebP header, for the three chunk layouts that exist.
///
/// Header offsets only -- nothing is decoded. `None` for anything unrecognised,
/// which the caller treats as "this picture does not know its size".
fn webp_dimensions(b: &[u8]) -> Option<(u32, u32)> {
    if b.len() < 30 || &b[0..4] != b"RIFF" || &b[8..12] != b"WEBP" {
        return None;
    }
    match &b[12..16] {
        // Lossy. Three-byte frame tag, then the 3-byte sync code, then two
        // 14-bit dimensions.
        b"VP8 " => {
            let w = u16::from_le_bytes([b[26], b[27]]) & 0x3fff;
            let h = u16::from_le_bytes([b[28], b[29]]) & 0x3fff;
            Some((u32::from(w), u32::from(h)))
        }
        // Lossless. One signature byte, then 14 bits of width-1 and 14 of
        // height-1 packed into the next four.
        b"VP8L" => {
            let bits = u32::from_le_bytes([b[21], b[22], b[23], b[24]]);
            Some(((bits & 0x3fff) + 1, ((bits >> 14) & 0x3fff) + 1))
        }
        // Extended. Canvas size as two 24-bit little-endian minus-ones.
        b"VP8X" => {
            let w = u32::from_le_bytes([b[24], b[25], b[26], 0]) + 1;
            let h = u32::from_le_bytes([b[27], b[28], b[29], 0]) + 1;
            Some((w, h))
        }
        _ => None,
    }
}

/// How many generated classes may go unused before the build fails.
///
/// One-sided: over this fails, under it warns and asks for the seal to be
/// lowered. A build that broke on deleting dead CSS would teach the wrong
/// lesson, so the number only ever ratchets down.
///
/// Measured against [`markup_files`]. The stylesheets are deliberately out -- a
/// class in `style.css` is that class being styled, not that class being
/// emitted, and counting them would mark the whole vocabulary used by
/// definition. `static/dist` is out for a subtler reason: it is `tsc` output of
/// `frontend/src`, so including both counts one class-writing line twice, and
/// the source is the half a human edits.
///
/// The server's markup is spread wider than either desktop app's -- 200-odd
/// Askama templates, the hand-written scripts in `static/`, the TypeScript they
/// are being replaced by, and the Rust that writes markup directly -- which is
/// the whole reason this seal took a pass of its own rather than landing beside
/// the check that reads the stylesheets.
///
/// A rise usually means a dependency grew vocabulary this repo does not spell.
/// `quasi-webview` and `makeover-webview` emit markup from a description at
/// request time, so their classes are invisible to a scanner reading this
/// repo's files and arrive dead here by construction. Those tighten as screens
/// convert. A few can never tighten: `menu.js` builds the overflow control when
/// it measures a run as tight, so no markup anywhere can spell
/// `.run-overflow` (see `makeover_webview::RUN_CLASSES`).
///
/// The scan is a word match over markup files, so a class whose name appears as
/// an ordinary word (`.run`, `.facet`) reads as used when it is not. Documented
/// loose in the safe direction rather than fixed; telling a class from a word
/// would mean parsing every template.
///
/// So a rising number here is not automatically a regression. Read it against
/// what moved: markup deleted in favour of a description will raise it, and a
/// class that genuinely lost its writer will too. The list the failure prints
/// is what tells them apart -- if a name on it is one this server still means
/// to render, that is the bug.
///
/// 49 rather than 48 because the scan is a word match. `.table-heading` was
/// counted used on the strength of a comment in `static/tab-project-content.js`
/// naming the selector it styled; that script is deleted and the class is
/// emitted by `quasi-webview` at request time, which no scan of this repo can
/// see. A class the description writes is dead here by construction.
///
/// # 52 since 2026-09-01, and the three were already loose
///
/// Re-sealed after measuring, not after a change: the count was 52 at the
/// commit before the makeover-layout 0.42.0 cascade as well, computed over the
/// same file set against `makeover_webview::vocabulary::names` from the
/// published 0.70.2. The breach was latent because nothing had invalidated this
/// build script in a while, and a `cargo check` that recompiles nothing does not
/// run it. The cascade changed a dependency, the script re-ran, and a seal that
/// had been wrong for some time reported itself.
///
/// The cause is the one the check names first: the vocabulary grew. Described
/// screens carry `cell-*`, `facet-*`, `run-*` and `track-*` classes, and 19 of
/// this server's screens are described against roughly 176 templates. So the
/// generated set runs ahead of the markup by construction while the transition
/// is mid-flight, and this number should FALL as phase 3 converts screens
/// rather than being raised again. If it needs raising a second time, read the
/// list before doing it.
const DEAD_VOCABULARY_HIGH_WATER: usize = 52;

/// The scripts this build script generates into `static/`.
///
/// One list, two consumers, and that is the whole point of it being a const.
/// The write loop iterates it, and [`markup_files`] excludes it. Those two have
/// to agree or the build recompiles on every cargo invocation forever.
///
/// # Why a generated file may never reach `markup_files`
///
/// `markup_files` globs `static/*.js`, and `makeover_build::check_vocabulary_use`
/// emits a `cargo::rerun-if-changed` for every file it reads. So a generated file
/// under `static/` is a file this script both **writes and watches**: the write
/// moves its mtime, cargo then sees a watched file newer than the build script's
/// own output, and the fingerprint can never settle. Nothing fails, nothing warns;
/// the crate just recompiles every time, which cost a second full 5m25s compile
/// inside every Sando `cargo_test` gate for five days.
///
/// Two doors lead here: a deleted file left in the watched list, and generated
/// files added to a globbed directory. `write_if_changed` fixes an instance.
/// This list plus the assertion in `markup_files` closes the door.
///
/// **Adding a generated file under `static/`? Add it here too.** The shell links
/// every script the renderer ships unless the host says otherwise, and this host
/// says otherwise about none of them, so a script missing from this list is
/// linked and unserved: a 404 per document, with nothing in the log.
const GENERATED_STATIC_JS: [(&str, &str); 12] = [
    ("quasi-selection.js", quasi_webview::SELECTION_JS),
    ("quasi-clock.js", quasi_webview::CLOCK_JS),
    ("quasi-download.js", quasi_webview::DOWNLOAD_JS),
    ("quasi-fill.js", quasi_webview::FILL_JS),
    ("quasi-reveal.js", quasi_webview::REVEAL_JS),
    ("quasi-copy.js", quasi_webview::COPY_JS),
    ("quasi-repeat.js", quasi_webview::REPEAT_JS),
    ("quasi-awaiting.js", quasi_webview::AWAITING_JS),
    ("quasi-instant.js", quasi_webview::INSTANT_JS),
    ("quasi-focus.js", quasi_webview::FOCUS_JS),
    ("quasi-menu.js", quasi_webview::MENU_JS),
    ("quasi-outline.js", quasi_webview::OUTLINE_JS),
];

/// Every file that can carry a class name.
///
/// Sorted within each group, so two machines read the same set in the same
/// order. It makes no difference to the count and every difference to reading a
/// diff of the warning.
///
/// Generated files are excluded: see [`GENERATED_STATIC_JS`] for why watching one
/// is a build that never settles. These four are also quasi-webview's emitted
/// output rather than markup this repo writes, so measuring them against this
/// server's own vocabulary seal was answering a question about another crate.
fn markup_files() -> Vec<std::path::PathBuf> {
    let mut files = Vec::new();
    for (dir, extension) in [
        ("templates", "html"),
        ("static", "js"),
        ("frontend/src", "ts"),
        ("src", "rs"),
    ] {
        let mut found = Vec::new();
        collect(Path::new(dir), extension, &mut found);
        found.sort();
        files.extend(found);
    }

    // The door, closed. Excluding by file name rather than by full path because
    // `collect` walks recursively and the generated ones sit at the root of
    // `static/`; a name collision deeper in the tree would be a second file
    // called `quasi-clock.js`, which is its own problem.
    let before = files.len();
    files.retain(|path| {
        !path
            .file_name()
            .and_then(|name| name.to_str())
            .is_some_and(|name| GENERATED_STATIC_JS.iter().any(|(g, _)| *g == name))
    });

    // Catches a listed script that `markup_files` cannot see: an entry given a
    // name `collect` does not glob, such as a `.mjs` or one written somewhere
    // other than `static/`. It would be excluded from nothing while still being
    // written and watched.
    //
    // It deliberately does NOT catch a deleted or renamed file, and the comment
    // here used to claim it did. It cannot: the write loop iterates this same
    // const and regenerates every entry before this function runs, so a missing
    // one is recreated rather than absent. Verified by deleting
    // `static/quasi-fill.js` and watching the build stay green. The `.gitignore`
    // cross-check below is the half that does the real work.
    let excluded = before - files.len();
    assert_eq!(
        excluded,
        GENERATED_STATIC_JS.len(),
        "markup_files excluded {excluded} generated scripts but GENERATED_STATIC_JS \
         names {}. A generated file under static/ that reaches markup_files is one \
         this build script both writes and watches, which recompiles the crate on \
         every cargo invocation. Update GENERATED_STATIC_JS to match what is written.",
        GENERATED_STATIC_JS.len(),
    );

    // The other half of the guard, and the one that catches the likelier
    // mistake. The assertion above catches a listed script that stopped
    // existing; this catches a NEW generated script nobody added to the list.
    //
    // `.gitignore` is the cross-check because it is the other place a generated
    // file has to be named: it is not committed, so it either gets an entry or
    // it shows up as untracked in every `git status` until someone adds one.
    // Read rather than asked of `git`, so this costs no subprocess and still
    // works where there is no git at all -- and where the file is unreadable it
    // fails open, which is the right direction for a guard rather than a gate.
    let ignored = fs::read_to_string("../.gitignore").unwrap_or_default();
    for name in ignored
        .lines()
        .map(str::trim)
        .filter_map(|line| line.strip_prefix("server/static/"))
        .filter(|name| {
            Path::new(name)
                .extension()
                .is_some_and(|ext| ext.eq_ignore_ascii_case("js"))
        })
    {
        assert!(
            GENERATED_STATIC_JS.iter().any(|(g, _)| *g == name),
            "`.gitignore` names generated script static/{name}, which \
             GENERATED_STATIC_JS does not. markup_files therefore watches a file \
             this build script writes, and the crate will recompile on every cargo \
             invocation with no other symptom. Add it to GENERATED_STATIC_JS.",
        );
    }

    files
}

/// Every file under `dir` with this extension, recursively.
fn collect(dir: &Path, extension: &str, out: &mut Vec<std::path::PathBuf>) {
    let Ok(entries) = fs::read_dir(dir) else {
        return;
    };
    for entry in entries.flatten() {
        let path = entry.path();
        if path.is_dir() {
            // The bundler's output, which is `frontend/src` compiled. Reading
            // both would count the same line twice.
            if path.file_name().is_some_and(|name| name == "dist") {
                continue;
            }
            collect(&path, extension, out);
        } else if path.extension().is_some_and(|ext| ext == extension) {
            out.push(path);
        }
    }
}

/// The hand-written stylesheets. Ordered, so the guard reports the same way
/// twice. `geometry.css` and `layout.css` are excluded: they are generated.
///
/// Every hand-authored sheet served to real visitors belongs here: the
/// breakpoint and vocabulary guards apply to all of them, and a sheet outside
/// the list can diverge without the build noticing. `tests/frontend_payload.rs`
/// weighs the same list, and a seal that skipped a sheet would let bytes move
/// between sheets and read as a deletion.
const HAND_WRITTEN_CSS: [&str; 4] = [
    "static/style.css",
    "static/wizard.css",
    "static/media-player.css",
    "static/no-js.css",
];

/// Write `contents` to `path` only if it differs, to avoid needless rebuilds.
fn write_if_changed(path: &Path, contents: &str) {
    let needs_write = fs::read_to_string(path).map_or(true, |existing| existing != contents);
    if needs_write {
        fs::write(path, contents)
            .unwrap_or_else(|e| panic!("failed to write {}: {e}", path.display()));
    }
}

/// Compile the TypeScript frontend (`frontend/`) to browser ESM in
/// `static/dist/` via `npm run build` (which runs `tsc`).
///
/// Self-contained: on a fresh checkout or a new build host (no `node_modules`)
/// it runs `npm ci` first, so there is no manual install gate before a deploy.
/// Best-effort and non-fatal otherwise, an absent Node or a compile error only
/// emits a `cargo::warning` and leaves the Rust build to succeed against
/// whatever `static/dist/` already holds. Set `MNW_SKIP_FRONTEND_BUILD=1` to
/// opt out entirely (e.g. a Node-less CI that doesn't need the JS).
fn build_frontend() {
    // Re-run the whole build script when the TS sources or its config change.
    println!("cargo::rerun-if-changed=frontend/src");
    println!("cargo::rerun-if-changed=frontend/package.json");
    println!("cargo::rerun-if-changed=frontend/package-lock.json");
    println!("cargo::rerun-if-changed=frontend/tsconfig.json");

    if std::env::var_os("MNW_SKIP_FRONTEND_BUILD").is_some() {
        println!("cargo::warning=frontend build skipped (MNW_SKIP_FRONTEND_BUILD set)");
        return;
    }
    // Fresh checkout / new build host: install deps once (clean, from the
    // lockfile) so the frontend build needs no manual `npm install` gate before
    // a deploy. Skipped once node_modules exists; needs network on this run.
    if !Path::new("frontend/node_modules").is_dir() {
        match Command::new("npm")
            .args(["ci"])
            .current_dir("frontend")
            .status()
        {
            Ok(s) if s.success() => {}
            Ok(s) => {
                println!(
                    "cargo::warning=npm ci failed (exit {:?}); skipping frontend build (serving existing static/dist)",
                    s.code()
                );
                return;
            }
            Err(e) => {
                println!(
                    "cargo::warning=could not run npm ({e}); is Node installed? skipping frontend build (serving existing static/dist)"
                );
                return;
            }
        }
    }
    match Command::new("npm")
        .args(["run", "build"])
        .current_dir("frontend")
        .status()
    {
        Ok(s) if s.success() => {}
        Ok(s) => println!(
            "cargo::warning=frontend build failed (npm run build exit {:?}); serving stale static/dist",
            s.code()
        ),
        Err(e) => println!(
            "cargo::warning=could not run npm for the frontend build ({e}); is Node installed? \
             skipping (serving existing static/dist)"
        ),
    }
}

/// Recursively hash every `.js` file under `dir` into `hasher`, in a
/// deterministic order. Missing directory is a no-op (first build before the
/// frontend has been compiled).
fn hash_dir_js(dir: &Path, hasher: &mut DefaultHasher) {
    let Ok(entries) = fs::read_dir(dir) else {
        return;
    };
    let mut paths: Vec<_> = entries.flatten().map(|e| e.path()).collect();
    paths.sort();
    for path in paths {
        if path.is_dir() {
            hash_dir_js(&path, hasher);
        } else if path.extension().and_then(|e| e.to_str()) == Some("js")
            && let Ok(content) = fs::read(&path)
        {
            content.hash(hasher);
        }
    }
}

/// Class-and-property overlaps with the generated stylesheet that have been
/// read and kept.
///
/// Two kinds, and only the first is what the check is really for.
///
/// **Different selector arms.** `.badge { color }` and `.card { color }`:
/// makeover colours the tone and disabled arms, the server colours the base and
/// its own variants (`.badge.ai-tier-*`, `.badge--founder-*`). Neither touches
/// the other's arm. The check collapses arms, because separating them would
/// need a selector matcher and a checker that guesses wrong about specificity
/// fails correct builds, so the judgement is recorded here.
///
/// **A deliberate pairing.** `.progress-fill { background }` is a different
/// element rather than a different arm: the media scrubber's fill, which lives
/// inside `.progress-bar` and never matches the generated
/// `.progress > .progress-fill`. It already carried a `respec-ok` comment
/// saying so.
///
/// `.tab { box-shadow }`, `{ color }` and `{ cursor }` are this file taking the
/// property outright: it zeroes the base `button` shadow on a tab and dresses
/// the tab's own text, and a described tab gets that rather than makeover's.
/// The chosen arm is the opposite: it is a `revert-layer`, which is not read as
/// a taking and needs no entry.
///
/// **A `revert-layer` needs no entry.** The check reads the value, not only the
/// property name, so a later layer handing a property back is not read as a
/// later layer taking it, and the handoffs at the end of `style.css` speak for
/// themselves. Keep them out of this list: an entry permits a real override on
/// the same pair for good, which turns a remedy into a licence.
///
/// The element rules those handoffs defer past are the other half of the same
/// release: `REVIEWED_ELEMENT_OVERLAPS` below, and the section at the end of
/// `style.css` that keeps it empty.
///
/// Still overlapping and still this file's: `.badge` and `.card` on their own
/// arms, and the disabled treatment's `opacity`, which is a charter decision
/// and a property makeover does not set.
///
/// **A divergence taken on purpose.** `.table-row { display }` is `grid` here
/// against makeover's `table-row`, which is the same build-time grid story
/// goingson is on. `.table-head { display }` is the same divergence on the
/// heading row: the feed's five column tracks have to be stated on both arms
/// or the headings stop lining up with the cells under them.
///
/// Do not restate a state makeover already names: tabs carry `chosen`, in the
/// templates and in `frontend/src/core/tabs.ts`, rather than a local
/// `.tab.is-selected` setting the same `--surface-raised` and `--bevel-raised`.
/// The caret is the renderer's too: it emits the leading space and the reserved
/// box itself.
///
/// An entry that stops colliding fails the build, so this list cannot outlive
/// what it describes.
const REVIEWED_OVERLAPS: &[(&str, &str)] = &[
    ("badge", "color"),
    // A carousel showing one frame at a time, 2026-08-14. This was
    // `("picture-img", "display")` until makeover-layout 0.23.0 described the
    // showing itself; the frames are wrapped in `.showing-frame` now and the old
    // entry stopped colliding, which this list is built to notice.
    //
    // The two arms are the same rule at two moments, and that is the whole of
    // why the overlap is kept. Makeover collapses the stack on `[data-ready]`,
    // which is the only honest default for a renderer that cannot know whether
    // a page has script: ship every child, take them away once something binds
    // them. This site collapses it from first paint instead, because rendering
    // three frames and collapsing them was a measured 141px -> 58px jump that
    // every visitor with JS paid, and `no-js.css` from a <noscript> opens the
    // stack for the few without. That trade is this landing page's to make and
    // a generated stylesheet has no way to reach <noscript>.
    ("showing-frame", "display"),
    ("current", "display"),
    ("card", "color"),
    ("progress-fill", "background"),
    ("tab", "box-shadow"),
    ("tab", "color"),
    ("tab", "cursor"),
    ("table-row", "display"),
    ("table-head", "display"),
];

/// Bare element rules that reach a generated class and have been read and kept.
///
/// The second pass of the same check, and the one this file had no answer to
/// until makeover-build 0.50.0: a rule with no class in it is invisible to the
/// list above, and `button { color: var(--content) }` in @layer components beat
/// the generated `.button[data-tone]` on every described act on the site. A
/// destructive act rendered identically to an ordinary one for months.
///
/// Empty, and meant to stay that way. The remedy for every one of them is a
/// `revert-layer` handoff in style.css, which says which arms makeover keeps in
/// the file the browser reads rather than in a build script.
const REVIEWED_ELEMENT_OVERLAPS: &[(&str, &str, &str)] = &[];

/// The short commit sha to stamp into `GIT_HASH`, and the watches that decide
/// when this build script has to run again.
///
/// The watches are the whole point. Cargo treats a `rerun-if-changed` path that
/// does not exist as *changed*, so a watch on a path that can never exist makes
/// this script re-run on every single cargo invocation, and re-running it
/// recompiles the crate. This file used to watch `.git/HEAD`, which resolves
/// against the package root: there is no `.git` in `server/` or in
/// `multithreaded/` because the repository root is `MNW/`. So the watch never
/// resolved, and the crate recompiled every time.
///
/// It cost 347s per Sando pipeline (294s in the server, 53s in multithreaded,
/// measured off `/srv/sando/logs/0.11.20/cargo_test.log`), which is 35% of the
/// `cargo_test` gate, and it cost the same on every local `cargo build`,
/// `cargo test` and `cargo clippy`. The two crates carrying a `build.rs` were
/// the only two in the pipeline that recompiled on a second cargo invocation;
/// the ones without one were already free.
///
/// Two rules follow, and both matter:
///   - resolve the paths through git rather than guessing them, and
///   - emit a watch ONLY for a path that exists, or the bug comes straight back.
fn git_hash() -> String {
    // An explicit hash wins and skips git entirely, for a build system that
    // already knows the sha. Nothing sets this today: Sando would have to set it
    // on EVERY cargo invocation it makes, because `GIT_HASH` is a `rustc-env`
    // and therefore part of the crate fingerprint, so a value present for the
    // release build and absent for `cargo_test` would force the recompile this
    // function exists to remove.
    println!("cargo::rerun-if-env-changed=MNW_GIT_HASH");
    if let Ok(h) = std::env::var("MNW_GIT_HASH") {
        let h = h.trim().to_string();
        if !h.is_empty() {
            return h;
        }
    }

    // Watch what git actually rewrites when the checkout moves. `.git/HEAD`
    // alone is not enough even when resolved: committing on a branch rewrites
    // that branch's ref, not HEAD, so a watch on HEAD by itself would go stale
    // in the ordinary case of a commit.
    watch_if_exists(git_path("HEAD").as_deref());
    if let Some(r) = git_output(&["symbolic-ref", "-q", "HEAD"]) {
        watch_if_exists(git_path(&r).as_deref());
    }
    // A ref that has been packed has no loose file, so this is the fallback
    // that keeps the watch honest after a `git gc`.
    watch_if_exists(git_path("packed-refs").as_deref());

    git_output(&["rev-parse", "--short", "HEAD"]).unwrap_or_default()
}

/// Run a git command in the package directory and return its trimmed stdout.
fn git_output(args: &[&str]) -> Option<String> {
    Command::new("git")
        .args(args)
        .output()
        .ok()
        .filter(|o| o.status.success())
        .and_then(|o| String::from_utf8(o.stdout).ok())
        .map(|s| s.trim().to_string())
        .filter(|s| !s.is_empty())
}

/// Resolve a name inside the git directory to a path, honouring worktrees and a
/// `.git` file that points elsewhere. `None` when this is not a checkout at all,
/// which is the case in a vendored or packaged build.
fn git_path(name: &str) -> Option<String> {
    git_output(&["rev-parse", "--git-path", name])
}

/// Emit a watch for a path, but only when it exists.
///
/// The guard is the fix. A missing path reads as changed to cargo, so emitting
/// one unconditionally is what caused the recompile-every-time bug.
fn watch_if_exists(path: Option<&str>) {
    if let Some(p) = path
        && Path::new(p).exists()
    {
        println!("cargo::rerun-if-changed={p}");
    }
}