Jyotisha/frontend/src/lib/home-warm-snapshot.ts

/**
 * Home warm snapshot (BUG-1040).
 *
 * The loading ring plays once per document load, not once per Home mount.
 * After the first cold bootstrap succeeds, Home keeps here what it would
 * otherwise re-fetch on every client navigation back to `/`: the model
 * catalog, the rectification entry summary, the session-page cursor and
 * today's starlanguage card. Account, profile and the session list are not
 * copied: they already live in the layout-level SessionListProvider, which
 * survives client navigation.
 *
 * Memory only, one account at a time. Nothing here is written to
 * localStorage / sessionStorage / IndexedDB; a document load starts empty.
 * Cleared on account change, sign-out and any 401 login redirect.
 *
 * Pure module state, no React. Callers: `home-warm-start.ts` (read),
 * Home's sync effect (write), `DailyStarlanguageBinder` (daily card),
 * `redirectToLogin` / `signOut` / the provider's signed-out branch (clear).
 */

import type { DailyStarlanguageCard } from "./home-types.ts";
import type { PublicLanguageModelCatalog } from "./public-models.ts";
import type { RectificationEntrySummary } from "./rectification-entry.ts";

export type HomeWarmSnapshot = Readonly<{
  accountId: string;
  modelCatalog: PublicLanguageModelCatalog;
  entrySummary: RectificationEntrySummary | null;
  entrySummarySettled: boolean;
  sessionsCursor: string | null;
  /**
   * Identity of the provider's boot object when the cursor was taken. A
   * provider reload (person switch while away) replaces it, and its own
   * cursor then wins over ours.
   */
  listBoot: object | null;
}>;

/** Today's card, keyed by person + birth-data fingerprint + calendar day. */
export type HomeWarmDaily = Readonly<{
  accountId: string;
  subjectId: string;
  fingerprint: string;
  day: string;
  card: DailyStarlanguageCard;
}>;

let snapshot: HomeWarmSnapshot | null = null;
let daily: HomeWarmDaily | null = null;

export function clearHomeWarmSnapshot(): void {
  snapshot = null;
  daily = null;
}

/** Written after a successful cold bootstrap and kept current while Home is mounted. */
export function writeHomeWarmSnapshot(next: HomeWarmSnapshot): void {
  if (!next.accountId) return;
  if (snapshot && snapshot.accountId !== next.accountId) clearHomeWarmSnapshot();
  if (daily && daily.accountId !== next.accountId) daily = null;
  snapshot = next;
}

/**
 * The snapshot for this account, or null. Another account's snapshot is
 * dropped on sight: an account change must never paint the previous
 * account's catalog, summary or card.
 */
export function readHomeWarmSnapshot(accountId: string | null | undefined): HomeWarmSnapshot | null {
  if (!accountId) return null;
  if (snapshot && snapshot.accountId !== accountId) {
    clearHomeWarmSnapshot();
    return null;
  }
  return snapshot;
}

/** Complete means a warm return can paint without waiting for anything. */
export function isCompleteHomeWarmSnapshot(value: HomeWarmSnapshot | null): value is HomeWarmSnapshot {
  return Boolean(value && value.accountId && value.modelCatalog && value.modelCatalog.models.length > 0 && value.entrySummarySettled);
}

export function rememberHomeWarmDaily(next: HomeWarmDaily): void {
  if (!next.accountId) return;
  if (snapshot && snapshot.accountId !== next.accountId) clearHomeWarmSnapshot();
  daily = next;
}

/** The remembered card only when person, fingerprint and day all still match. */
export function readHomeWarmDaily(key: Readonly<{
  accountId: string;
  subjectId: string;
  fingerprint: string;
  day: string;
}>): DailyStarlanguageCard | null {
  if (!daily || daily.accountId !== key.accountId) return null;
  if (daily.subjectId !== key.subjectId || daily.fingerprint !== key.fingerprint || daily.day !== key.day) return null;
  return daily.card;
}