/**
 * IS THIS TAB RUNNING SUPERSEDED CODE? -.
 *
 * WHY THIS EXISTS, and it is a measured cost rather than a tidy idea. On 2026-08-23 THREE
 * real-looking defects were investigated and withdrawn in one day, all from one cause: a browser tab
 * held open across a deploy. A stale bundle does not present as staleness - it presents as a coherent,
 * reproducible bug. One of them reproduced three times and survived four competing explanations before
 * the cause was found, and one was raised as a critical beta-blocker before being withdrawn.
 * The fourth would have been believed.
 *
 * WHY NO AMOUNT OF CACHE HEADERS FIXES IT
 *
 * THIS IS A SINGLE-PAGE APP, AND THAT IS THE WHOLE MECHANISM. Measured on a real session:
 * `performance.getEntriesByType('navigation').length === 1` after twenty minutes and a dozen "pages" -
 * because `location.hash = '#/dashboard/...'` issues no request. **The document is fetched once and never
 * again**, so the browser is never given the chance to notice a newer one. Nothing is misbehaving.
 *
 * So this is NOT the same problem as, and it does not replace it. That card stops the
 * DOCUMENT being served from a cache (`nocache_headers()` + `DONOTCACHEPAGE`), and it works - verified
 * live. It governs a request; this governs a session that never makes one.
 *
 * THE CHECK, AND WHY IT IS SHAPED THIS WAY
 *
 * IT DOES NOT RELY ON A RELOAD, deliberately. The obvious advice - "hard-reload before diagnosing" -
 * was already written down and still failed, because a reload is a CLAIM and not an action you can
 * assume succeeded: `Ctrl+Shift+R` through an automation harness does not reload, and a plain
 * re-navigation re-uses the cached document. Both leave the old `?ver=` in place, and the page then
 * looks perfectly self-consistent.
 * Asking the SERVER what it currently advertises is the only check that cannot be defeated by a
 * reload that silently did nothing.
 *
 * AND IT DOES NOT COMPARE THE BUNDLE'S CONTENT. Fetching `main.tsx.js?ver=<old>` returns whatever
 * that file is NOW - the query string is not part of the path, so the filesystem ignores it. That probe
 * reads as "two bundles under one version" and is really one file at two times; it produced one of the
 * three withdrawn cards.
 */

/** The script tag WordPress emitted into the document this tab is running. */
const loadedBundleVersion = (): string | undefined =>
    document
        .querySelector<HTMLScriptElement>('script[src*="main.tsx.js"]')
        ?.src.split('ver=')[1];

const VERSION_IN_MARKUP = /main\.tsx\.js\?ver=([A-Za-z0-9]+)/;

/**
 * What the server would send a browser asking for this page right now.
 *
 * `cache: 'no-store'` matters: without it this request can itself be answered from the cache that made
 * the document stale, and the check would cheerfully compare a value with itself.
 */
const servedBundleVersion = async (): Promise<string | undefined> => {
    const response = await fetch(window.location.pathname, { cache: 'no-store' });
    if (!response.ok) return undefined;
    return VERSION_IN_MARKUP.exec(await response.text())?.[1];
};

/**
 * Warn when this tab is running code the server has already replaced.
 *
 * Returns the verdict so a caller can act on it; the console line is the point for now, because the
 * audience is whoever is staring at a screen wondering why their fix is not there.
 * Deliberately NOT a user-facing banner: a patient mid-form does not need to be told about our
 * deploys, and the failure this prevents is a wasted investigation rather than a broken session.
 */
export const warnIfRunningSupersededCode = async (): Promise<boolean> => {
    try {
        const loaded = loadedBundleVersion();
        if (!loaded) return false;

        const served = await servedBundleVersion();
        // No answer is not evidence of staleness - say nothing rather than cry wolf. A check that
        // reports a problem when it simply could not look is worse than no check.
        if (!served || served === loaded) return false;

        console.warn(
            'STALE_DOCUMENT: this tab is running a superseded bundle. It loaded '
            + `${loaded}, and the server is now serving ${served}. This happens because the app is a `
            + 'single-page app — hash navigation never re-requests the document, so a tab left open '
            + 'across a deploy keeps running the code it started with. Anything missing or misbehaving '
            + 'on this screen may already be fixed. Reload the page (a NEW request, not a hash change) '
            + 'before investigating it as a defect.',
        );
        return true;
    } catch {
        // Never let a diagnostic take the app down. A failed check is silence, not an error.
        return false;
    }
};