gitmost/apps/client/src/lib/reload-guard.ts

// Shared one-shot auto-reload guard.
//
// Both auto-reload paths — the reactive chunk-load-error-boundary (recovers
// AFTER a stale lazy chunk 404s) and the proactive version-coherence feature
// (reloads BEFORE the tab hits a stale chunk) — go through these functions so
// they share ONE session-scoped flag. Net guarantee: at most a single
// automatic reload per browser session across both paths. Once the flag is set
// (or sessionStorage is unavailable), every further mismatch degrades to a
// manual banner/UI — no reload loop under permanent skew, node oscillation, or
// a disabled storage.
const RELOAD_FLAG = "chunk-reload-attempted";

/**
 * Has an automatic reload already been performed (or attempted) this session?
 *
 * A storage read error (private mode / disabled) is reported as `true` so the
 * caller fails toward NOT reloading — an unguarded loop is worse than a stale
 * tab the user can reload manually.
 */
export function hasAutoReloaded(): boolean {
  try {
    return sessionStorage.getItem(RELOAD_FLAG) !== null;
  } catch {
    return true;
  }
}

/**
 * Record that an automatic reload is being performed this session.
 *
 * Returns whether the write succeeded. A `false` return (storage unavailable)
 * means the caller MUST NOT reload — otherwise the flag would never stick and
 * the reload could loop.
 */
export function markAutoReloaded(): boolean {
  try {
    sessionStorage.setItem(RELOAD_FLAG, "1");
    return true;
  } catch {
    return false;
  }
}

// Diagnostic breadcrumb for an automatic reload. Written right before
// window.location.reload() (which clears the console) and read back on the next
// page load, so a "the tab reloaded itself / it's looping" field report is
// diagnosable: which path fired (proactive version-coherence vs the reactive
// chunk-load boundary) and which version pair triggered it. sessionStorage
// survives a same-tab reload, unlike the console.
const RELOAD_BREADCRUMB_KEY = "reload-breadcrumb";

export type ReloadBreadcrumb = {
  path: "proactive" | "chunk-boundary";
  serverVersion?: string;
  clientVersion?: string;
  at: number;
};

/**
 * Persist a best-effort breadcrumb just before an automatic reload. Failures
 * (storage unavailable) are swallowed — this is diagnostics only and must never
 * block or alter the reload decision.
 */
export function recordReloadBreadcrumb(
  entry: Omit<ReloadBreadcrumb, "at">,
): void {
  try {
    sessionStorage.setItem(
      RELOAD_BREADCRUMB_KEY,
      JSON.stringify({ ...entry, at: Date.now() }),
    );
  } catch {
    // best-effort diagnostics only
  }
}

/**
 * Read and clear the breadcrumb left by an auto-reload in the previous page
 * load. Cleared on read so it surfaces exactly once per reload.
 */
export function takeReloadBreadcrumb(): ReloadBreadcrumb | null {
  try {
    const raw = sessionStorage.getItem(RELOAD_BREADCRUMB_KEY);
    if (!raw) return null;
    sessionStorage.removeItem(RELOAD_BREADCRUMB_KEY);
    return JSON.parse(raw) as ReloadBreadcrumb;
  } catch {
    return null;
  }
}