feedback7: merge fb7-stats — the local statistics page (PR #323 by @2321Robin, reworked): a match counts when it reached its result or the player cleared at least one round before quitting; earlier quits stay in the history marked 中途退出 / 不计入统计 (the owner's rule of 2026-10-08)

- Conflict: docs/PLAYING.md — #321's §12 反馈问题 and the stats §12 both added; the stats section is §13 (README anchor
  updated).
- Golden unchanged; broad node --test 5382 (5381 pass, 0 fail, 1 skipped); lint 0 errors.

public/js/ui/components.js

@@ -55,6 +55,8 @@ export const ICONS = {
   users: { d: 'M9 4a3.5 3.5 0 1 1 0 7 3.5 3.5 0 0 1 0-7zM2 20a7 6.5 0 0 1 14 0zM16.5 5a3 3 0 1 1 0 6 3 3 0 0 1 0-6zm.9 8.1A6.5 6 0 0 1 22.5 20H18a8.6 8 0 0 0-2.4-6.1 6 6 0 0 1 1.8-.8z' },
   rook: { d: 'M5 3h3v2h2V3h4v2h2V3h3v5l-2 2v7l2 2v2H5v-2l2-2v-7L5 8z' },
   signal: { d: 'M2 17h3v4H2zm6-4h3v8H8zm6-4h3v12h-3zm6-4h3v16h-3z' },
+  // 统计 (the stats page's entry): three columns on a baseline — apart from `signal`, the ping bars
+  chart: { d: 'M4 12h4v7H4zm6-6h4v13h-4zm6 3h4v10h-4zM3 20h18v2H3z' },
   refresh: { d: 'M12 4a8 8 0 0 1 7.4 5H17v2h6V5h-2v2.3A10 10 0 0 0 2 12h2a8 8 0 0 1 8-8zm0 16a8 8 0 0 1-7.4-5H7v-2H1v6h2v-2.3A10 10 0 0 0 22 12h-2a8 8 0 0 1-8 8z' },
   snow: { d: 'M11 2h2v4.2l2.3-2.3 1.4 1.4-3.7 3.7v2h2l3.7-3.7 1.4 1.4-2.3 2.3H22v2h-4.2l2.3 2.3-1.4 1.4-3.7-3.7h-2v2l3.7 3.7-1.4 1.4-2.3-2.3V22h-2v-4.2l-2.3 2.3-1.4-1.4 3.7-3.7v-2H9l-3.7 3.7-1.4-1.4L6.2 13H2v-2h4.2L3.9 8.7l1.4-1.4L9 11h2V9L7.3 5.3l1.4-1.4L11 6.2z' },
   chevronRight: { d: 'M8.6 5 7.2 6.4 12.8 12l-5.6 5.6L8.6 19l7-7z' },

public/js/ui/matchChrome.js

@@ -12,6 +12,7 @@ import { net } from '../net.js';
 import { store, useStore, shallowEqual, emptyMatch, createStore, isSpectating } from '../store.js';
 import { GIcon } from './gameComponents.js';
 import { GuideButton } from './guide.js';
+import { recordQuit } from './stats.js';
 import { t, tParts, N_ } from '../../../shared/i18n.js';
 
 /**
@@ -37,18 +38,27 @@ export const awayEnds = (s, prev) => (!!prev?.match?.public && !s?.match?.public
 store.subscribe((s, prev) => { if (awayStore.get().away && awayEnds(s, prev)) awayStore.set({ away: false }); });
 
 /**
- * Leave the match for good (g.leave → room.leave), then drop local room/match state.
+ * Leave the match for good (g.leave → room.leave), then drop local room/match state. The server sends a leaver no
+ * settlement, so the page records the match itself before it is cleared (本机统计, ui/stats.js recordQuit: a 中途退出
+ * entry of the history; it counts only when a round had been cleared) — once the leave went through.
  * @returns {Promise<void>}
  */
 export async function quitMatch() {
+  const before = store.get();
+  let left = false;
   try {
     try { await net.request('g.leave', {}); } catch (err) {
       if (err?.code !== 'NOT_IN_ROOM' && err?.code !== 'WRONG_PHASE' && err?.code !== 'OFFLINE') throw err;
     }
     try { await net.request('room.leave', {}); } catch (err) { if (err?.code !== 'NOT_IN_ROOM' && err?.code !== 'OFFLINE') throw err; }
+    left = true;
   } catch (err) {
     toastError(err);
   } finally {
+    // (a settlement that arrived while the leave was in flight is the match's record already)
+    if (left && !store.get().match.result) {
+      try { recordQuit(before); } catch (err) { console.warn('[stats] quit record failed', err); }
+    }
     store.set({ room: null, match: emptyMatch() });
   }
 }

public/js/ui/stats.js

@@ -0,0 +1,744 @@
+// Local match statistics: every match the local player took part in is appended as one record to localStorage
+// (`sp.pref.stats`). Per-browser only — the server keeps matches in memory and has no identity, so there is nowhere
+// else for cross-match numbers to live; nothing here is ever sent anywhere. The stats page labels itself 本机数据 and
+// offers JSON export / import for moving between devices. (Ported from PR #323 by @2321Robin, reworked for 0.2.2.)
+//
+// Two kinds of record (`end`):
+//   'settled'  the match reached its settlement: m.result arrived (server/match/results.js buildResult). The record
+//              keeps what the settlement offers — the match frame (difficulty, mode, boss, seed, duration, hidden-core
+//              outcome, reason) and one row per player (band, title, lineup, bonds, the stat block) — so the page can
+//              re-view the settlement screen (recordToResult).
+//   'quit'     the player gave up (放弃模拟) before the settlement; the server sends a leaver nothing, so the record is
+//              built from what the client knew at that moment (buildQuitRecord): the frame, the player's own row, the
+//              rounds cleared. It is listed in the history, marked 中途退出, and cannot be re-viewed.
+//
+// What counts (countsTowardStats, the owner's decision of 2026-10-08: a match entered and left right away must not
+// count): every aggregate — games, wins, win rate, hidden core, best round, time played, the strategy table, titles
+// and the combat totals — is taken over the records that count. A settled record always counts. A quit record counts
+// once at least one of the player's own battles had finished — a round cleared (the server's rule: leaving while
+// round k runs has passed k − 1 rounds, leaving in its settlement k) or already eliminated. A match left earlier is
+// history only.
+//
+// Bounded storage: at most MAX_RECORDS matches and MAX_CHARS characters of JSON. Only the newest FULL_KEEP records
+// keep their full rows (lineups, bonds, teammates' names — what the settlement replay needs); older ones are compacted
+// to the player's own summary row, which is all the aggregates read. The oldest records go first when a budget is hit,
+// and a write the browser refuses shrinks the list further instead of failing. Teammates' display names are part of
+// the newest records and of an export file: they stay on this device unless the player exports them.
+//
+// Format evolution: the envelope carries a version (`STATS_VERSION`); `migrateStats` walks records through a chain of
+// per-version steps and every loaded / imported record passes `normalizeRecord`, a strict schema: missing fields get
+// defaults, unknown fields and oversized values are dropped, a row it cannot salvage is dropped. An envelope from a
+// NEWER version than this build is refused (never downgraded and written back); an unreadable one is set aside
+// (`sp.pref.stats.damaged`) and the history starts again.
+//
+// Pure logic, no Preact / DOM: Node-testable (test/ui/stats.test.js); localStorage is touched only by loadStats /
+// saveStats / their helpers.
+
+import { PHASE } from '../../../shared/constants.js';
+
+/** Current record-envelope version (bump + add a MIGRATIONS step when the record shape changes). */
+export const STATS_VERSION = 1;
+/** localStorage key under the app's `sp.pref.` prefix (store.js loadPref). */
+export const STATS_PREF_KEY = 'stats';
+/** Oldest records are dropped beyond this many matches. */
+export const MAX_RECORDS = 1000;
+/** The newest records that keep their full rows (lineups, bonds, teammates) — what the settlement replay reads. */
+export const FULL_KEEP = 30;
+/** Budget of the stored JSON in characters (a character costs up to 2 bytes of the browser's ~5 MB quota): the oldest records go first. */
+export const MAX_CHARS = 800_000;
+/** Largest export file the page reads. */
+export const IMPORT_MAX_CHARS = 8_000_000;
+
+const FULL_KEY = `sp.pref.${STATS_PREF_KEY}`;
+const DAMAGED_KEY = `${FULL_KEY}.damaged`;
+
+/** @returns {{ v: number, records: Array }} a fresh empty envelope */
+export const emptyStats = () => ({ v: STATS_VERSION, records: [] });
+
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const int = (v, d) => (Number.isFinite(v) ? Math.round(v) : d);
+const num = (v) => (Number.isFinite(v) ? v : null);
+const bool = (v, d = false) => (typeof v === 'boolean' ? v : d);
+/** A non-empty string, cut to `max` characters. */
+const str = (v, max = 64) => (typeof v === 'string' && v.length ? v.slice(0, max) : null);
+
+// per-record bounds (an imported file is foreign data: nothing a row holds may grow without limit)
+const MAX_PLAYERS = 6; // the game seats 4
+const MAX_LINEUP = 12;
+const MAX_ITEMS = 4;
+const MAX_BONDS = 24;
+const MAX_STAT_KEYS = 24;
+const MAX_NAME = 24;
+
+/**
+ * Copy only the finite numeric keys of a stats block (the settlement's numbers; a numeric field this build does not
+ * know is kept too, up to MAX_STAT_KEYS — display can lag, data should not).
+ * @param {any} raw
+ * @returns {Record<string, number>}
+ */
+function normalizeStatBlock(raw) {
+  const out = {};
+  if (!isObj(raw)) return out;
+  let n = 0;
+  for (const [k, v] of Object.entries(raw)) {
+    if (!Number.isFinite(v) || k.length > 32) continue;
+    out[k] = v;
+    if (++n >= MAX_STAT_KEYS) break;
+  }
+  return out;
+}
+
+/**
+ * FNV-1a 32-bit, hex — a content hash needs no crypto, only stability across sessions.
+ * @param {string} s
+ * @returns {string}
+ */
+function fnv1a(s) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+/**
+ * The record's dedupe id, from match facts the server replays byte-identically on reconnect / reload
+ * (server/lobby.js result replay): seed + duration + mode + rounds + outcome + who I was. Two distinct
+ * matches colliding on all of these is not a real scenario; a replayed m.result hits the same id and is
+ * dropped, which is the point (recording happens on every m.result arrival, replays included).
+ * @param {any} res raw m.result payload
+ * @param {string|null|undefined} myId the local player's id at that moment
+ * @returns {string}
+ */
+export function recordId(res, myId) {
+  const r = isObj(res) ? res : {};
+  return `r1.${fnv1a([r.seed ?? '-', r.durationMs ?? '-', r.modeId ?? '-', r.roundsPassed ?? '-', r.victory ? 1 : 0, myId ?? '-'].join('|'))}`;
+}
+
+/**
+ * Normalize ONE player row: known fields defaulted and bounded, unknown fields dropped. `quit`: the record is a quit
+ * record, whose row may not know its rounds (`roundsPassed: null`).
+ * @param {any} raw
+ * @param {boolean} [quit]
+ * @returns {any}
+ */
+function normalizePlayerRow(raw, quit = false) {
+  const p = isObj(raw) ? raw : {};
+  // the page and the replay read the title record from the game data by id: the sent texts are not kept
+  const title = isObj(p.title) && str(p.title.id) ? { id: str(p.title.id) } : null;
+  const lineup = (Array.isArray(p.lineup) ? p.lineup : []).filter(isObj).slice(0, MAX_LINEUP).map((u) => {
+    // ids only — the tile position (row/col) is replay detail, not a statistic; items kept (配发装备统计); a 自选
+    // pick and a 补位 stand-in kept too, or the replayed card would draw the plain operator
+    const e = {
+      id: str(u.id) || '', golden: bool(u.golden), tier: int(u.tier, 0),
+      items: (Array.isArray(u.items) ? u.items : []).filter((i) => typeof i === 'string' && i.length).slice(0, MAX_ITEMS).map((i) => i.slice(0, 64)),
+    };
+    if (u.kind === 'token') e.kind = 'token';
+    if (isObj(u.diy) && str(u.diy.charId)) {
+      e.diy = { charId: str(u.diy.charId), skillIndex: Number.isInteger(u.diy.skillIndex) ? u.diy.skillIndex : 0, uniEquipId: str(u.diy.uniEquipId) };
+    }
+    if (str(u.standInFor)) e.standInFor = str(u.standInFor);
+    return e;
+  }).filter((u) => u.id);
+  const bonds = (Array.isArray(p.bonds) ? p.bonds : []).filter(isObj).slice(0, MAX_BONDS).map((b) => ({
+    bondId: str(b.bondId) || str(b.id) || '', layers: int(b.layers, 0), active: bool(b.active),
+  })).filter((b) => b.bondId);
+  return {
+    playerId: str(p.playerId) || '',
+    seat: int(p.seat, 0),
+    name: str(p.name, MAX_NAME) || '',
+    isBot: bool(p.isBot),
+    left: bool(p.left),
+    alive: bool(p.alive, true),
+    victory: bool(p.victory), // server semantics: team won AND this player was still in at the end
+    roundsPassed: quit ? num(p.roundsPassed) : int(p.roundsPassed, 0),
+    eliminatedRound: num(p.eliminatedRound),
+    lp: num(p.lp),
+    bandId: str(p.bandId),
+    title,
+    trophies: int(p.trophies, 0),
+    reward: int(p.reward, 0),
+    lineup,
+    bonds,
+    stats: normalizeStatBlock(p.stats),
+  };
+}
+
+/**
+ * Normalize ONE match record to the current shape (a strict schema: missing fields get defaults, unknown ones are
+ * dropped, every string / list is bounded). A record without an `end` is a settled one — the PR #323 build, which
+ * never recorded anything else, wrote none.
+ * @param {any} raw
+ * @returns {any|null} null when the row is not salvageable (no usable player row at all)
+ */
+export function normalizeRecord(raw) {
+  const r = isObj(raw) ? raw : {};
+  // a record IS a played match — no usable players array, no record
+  if (!Array.isArray(r.players)) return null;
+  const quit = r.end === 'quit';
+  const players = r.players.filter(isObj).slice(0, MAX_PLAYERS).map((p) => normalizePlayerRow(p, quit));
+  if (!players.length) return null;
+  const rec = {
+    id: str(r.id),
+    v: STATS_VERSION,
+    t: int(r.t, 0),
+    end: quit ? 'quit' : 'settled',
+    victory: bool(r.victory),
+    roundsPassed: quit ? num(r.roundsPassed) : int(r.roundsPassed, 0),
+    lastRound: num(r.lastRound),
+    hiddenReached: bool(r.hiddenReached),
+    hiddenCleared: bool(r.hiddenCleared),
+    reason: str(r.reason, 32),
+    modeId: str(r.modeId),
+    difficulty: str(r.difficulty, 24),
+    stageId: str(r.stageId),
+    bossId: str(r.bossId),
+    hiddenBossId: str(r.hiddenBossId),
+    seed: num(r.seed),
+    durationMs: num(r.durationMs),
+    teamLp: num(r.teamLp),
+    roomMode: r.roomMode === 'solo' || r.roomMode === 'coop' ? r.roomMode : null,
+    selfId: str(r.selfId),
+    players,
+  };
+  if (r.compact === true) rec.compact = true;
+  // an id-less (hand-made) record gets a content id, so both copies of it land on the same key
+  if (!rec.id) rec.id = `c.${fnv1a(JSON.stringify(rec))}`;
+  return rec;
+}
+
+/**
+ * The MIGRATIONS chain: `MIGRATIONS[v]` upgrades a v-envelope to v+1, for v = STATS_VERSION and down.
+ * Empty at v1 — the steps exist so the next format change lands as one function here and every stored /
+ * imported envelope walks the whole chain.
+ * @type {Record<number, (stats: any) => any>}
+ */
+export const MIGRATIONS = {};
+
+/** Newest first (the stored order): by time, then id. */
+const newestFirst = (a, b) => (b.t - a.t) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+/**
+ * Bring any stored / imported envelope to the current version.
+ * @param {any} raw
+ * @returns {{ stats: { v: number, records: any[] }, changed: boolean, newer: boolean, dropped: number }}
+ *   `newer` = the data was written by a NEWER build: returned untouched, callers must not save over it.
+ *   `dropped` = rows that were not salvageable, repeated a record or went beyond MAX_RECORDS: gone from `stats`.
+ */
+export function migrateStats(raw) {
+  if (!isObj(raw) || !Array.isArray(raw.records)) return { stats: emptyStats(), changed: false, newer: false, dropped: 0 };
+  if ((raw.v ?? 0) > STATS_VERSION) {
+    return { stats: { v: raw.v, records: raw.records }, changed: false, newer: true, dropped: 0 };
+  }
+  let v = Number.isFinite(raw.v) ? raw.v : 0;
+  let records = raw.records;
+  let changed = v !== STATS_VERSION;
+  while (v < STATS_VERSION) {
+    const step = MIGRATIONS[v];
+    if (typeof step === 'function') records = step({ v, records }).records;
+    v++;
+  }
+  // a hand-edited / merged list can be oversized, unsorted or repeat a record: only the newest MAX_RECORDS survive, newest first
+  const normalized = [];
+  const seen = new Set(); // a record listed twice (hand-merged data) counts once: the first copy
+  for (const r of records) {
+    const rec = normalizeRecord(r);
+    if (rec && !seen.has(rec.id)) { seen.add(rec.id); normalized.push(rec); }
+  }
+  normalized.sort(newestFirst);
+  const kept = normalized.slice(0, MAX_RECORDS);
+  const dropped = records.length - kept.length;
+  // storage is rewritten (self-healed) when a row went, the order changed or an id-less row got its content id
+  changed ||= dropped > 0 || kept.some((rec, i) => !isObj(records[i]) || rec.id !== records[i].id);
+  return { stats: { v: STATS_VERSION, records: kept }, changed, newer: false, dropped };
+}
+
+/** Read the raw stored string (null when absent or unreadable). */
+function readRaw() {
+  try { return globalThis.localStorage?.getItem(FULL_KEY) ?? null; } catch { return null; }
+}
+
+/**
+ * Read + migrate the persisted envelope; self-heals older shapes back to storage. An unreadable value (not JSON, or
+ * not an envelope) is moved to `sp.pref.stats.damaged` — kept for a manual recovery — and the history starts again.
+ * @returns {{ v: number, records: any[], newer: boolean, dropped: number, damaged: boolean }}
+ */
+export function loadStats() {
+  const raw = readRaw();
+  if (raw == null) return { ...emptyStats(), newer: false, dropped: 0, damaged: false };
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch { parsed = undefined; }
+  if (!isObj(parsed) || !Array.isArray(parsed.records)) {
+    // keep the bad value where a person can find it; if even that write fails the next save simply replaces it
+    try { globalThis.localStorage?.setItem(DAMAGED_KEY, raw); globalThis.localStorage?.removeItem(FULL_KEY); } catch { /* keep it in place */ }
+    return { ...emptyStats(), newer: false, dropped: 0, damaged: true };
+  }
+  const { stats, changed, newer, dropped } = migrateStats(parsed);
+  if (!newer && changed) saveStats(stats);
+  return { ...stats, newer, dropped, damaged: false };
+}
+
+// ---- compaction + the storage budget ---------------------------------------------------------------------------
+
+const COMPACT_FRAME = ['id', 'v', 't', 'end', 'victory', 'roundsPassed', 'lastRound', 'hiddenReached', 'hiddenCleared', 'reason', 'modeId',
+  'difficulty', 'roomMode', 'durationMs', 'selfId'];
+
+/**
+ * The compact form of a record: the frame and the player's OWN row without lineup, bonds and name — everything the
+ * aggregates and the history list read, nothing a replay needs. Teammates are gone. Idempotent.
+ * @param {any} rec a normalized record
+ * @returns {any}
+ */
+export function compactRecord(rec) {
+  const self = selfRowOf(rec);
+  const out = {};
+  for (const k of COMPACT_FRAME) if (rec[k] != null) out[k] = rec[k];
+  out.compact = true;
+  out.players = self ? [{
+    playerId: self.playerId, seat: self.seat, alive: self.alive, victory: self.victory, roundsPassed: self.roundsPassed,
+    eliminatedRound: self.eliminatedRound, bandId: self.bandId, title: self.title, left: self.left, stats: self.stats,
+  }] : [];
+  return out;
+}
+
+/**
+ * What goes to storage: the newest FULL_KEEP records as they are, older ones compacted, then the oldest dropped until
+ * the JSON fits `maxChars` (the newest record is always kept).
+ * @param {any[]} records newest first
+ * @param {number} [maxChars]
+ * @returns {any[]}
+ */
+export function fitToBudget(records, maxChars = MAX_CHARS) {
+  const kept = [];
+  let used = 40; // the envelope itself
+  records.slice(0, MAX_RECORDS).forEach((r, i) => {
+    const rec = i < FULL_KEEP ? r : compactRecord(r);
+    const n = JSON.stringify(rec).length + 1;
+    if (kept.length && used + n > maxChars) return;
+    used += n;
+    kept.push(rec);
+  });
+  return kept;
+}
+
+/**
+ * Persist the envelope. Never overwrites an envelope of a newer build. Compacts and trims to the budget first; a write
+ * the browser refuses (quota — other keys share it) is retried with half the history, down to a handful of records.
+ * @param {{ v: number, records: any[], newer?: boolean }} stats
+ * @returns {boolean} whether a write stuck
+ */
+export function saveStats(stats) {
+  if (stats.newer) return false;
+  let recs = fitToBudget(stats.records);
+  for (;;) {
+    try {
+      const ls = globalThis.localStorage;
+      if (!ls) return false; // no storage at all (disabled by the browser)
+      ls.setItem(FULL_KEY, JSON.stringify({ v: STATS_VERSION, records: recs }));
+      return true;
+    } catch { /* quota or storage disabled — fall through to shrinking */ }
+    if (recs.length <= 8) return false; // a small history that still does not fit is foreign quota pressure
+    recs = recs.slice(0, Math.max(8, Math.ceil(recs.length / 2)));
+  }
+}
+
+/**
+ * Derive the room shape ('solo' | 'coop') the way constants.js modeIdFor builds modeIds.
+ * @param {string|null|undefined} modeId
+ * @param {string|null|undefined} roomMode room.state `mode` when known
+ * @returns {'solo'|'coop'|null}
+ */
+export function roomModeOf(modeId, roomMode) {
+  if (roomMode === 'solo' || roomMode === 'coop') return roomMode;
+  if (typeof modeId !== 'string') return null;
+  if (modeId.includes('_single_')) return 'solo';
+  if (modeId.includes('_multi_')) return 'coop';
+  return null;
+}
+
+/**
+ * Build one settled record from a raw m.result payload (+ context). Null when there is nothing to store: payloads
+ * without players (the error-path settlement) or matches the local player did not take part in (spectator
+ * seats get every result pushed too — eliminated players, who ARE in players[], keep recording).
+ * @param {any} res raw m.result payload
+ * @param {{ myId?: string|null, roomMode?: string|null, now?: number }} ctx
+ * @returns {any|null}
+ */
+export function buildRecord(res, ctx = {}) {
+  const r = isObj(res) ? res : {};
+  if (!Array.isArray(r.players) || !r.players.length) return null;
+  const myId = str(ctx.myId);
+  const selfRow = r.players.find((p) => isObj(p) && p.playerId === myId);
+  if (!selfRow) return null; // spectator / observer: not my match
+  return normalizeRecord({
+    v: STATS_VERSION,
+    t: int(ctx.now, 0),
+    id: recordId(r, myId),
+    end: 'settled',
+    victory: bool(r.victory),
+    roundsPassed: int(r.roundsPassed, 0),
+    lastRound: num(r.lastRound),
+    hiddenReached: bool(r.hiddenReached),
+    hiddenCleared: bool(r.hiddenCleared),
+    reason: str(r.reason),
+    modeId: str(r.modeId),
+    difficulty: str(r.difficulty),
+    stageId: str(r.stageId),
+    bossId: str(r.bossId),
+    hiddenBossId: str(r.hiddenBossId),
+    seed: num(r.seed),
+    durationMs: num(r.durationMs),
+    teamLp: num(r.teamLp),
+    roomMode: roomModeOf(str(r.modeId), ctx.roomMode),
+    selfId: myId,
+    players: r.players,
+  });
+}
+
+// ---- the match left early ----------------------------------------------------------------------------------------
+
+/**
+ * What the page remembers of the match on screen, so that giving it up can still be recorded: when the page first saw
+ * it, whether that was at the start (a duration is only kept then), and the last round the player was seen alive in
+ * (the server tells the others at the settlement, a leaver nothing).
+ * @returns {{ active: boolean, startedAt: number, sawStart: boolean, aliveRound: number|null }}
+ */
+export const createLiveMatch = () => ({ active: false, startedAt: 0, sawStart: false, aliveRound: null });
+
+/** The module's own tracker (fed by installStatsRecorder, read by recordQuit). */
+export const liveMatch = createLiveMatch();
+
+/**
+ * Feed the tracker one app state (cheap: called on every store change).
+ * @param {ReturnType<typeof createLiveMatch>} live
+ * @param {any} state the app store state
+ * @param {number} [now]
+ */
+export function observeMatch(live, state, now = Date.now()) {
+  const pub = state?.match?.public;
+  const inMatch = !!pub && !!pub.phase && pub.phase !== PHASE.LOBBY && pub.phase !== PHASE.RESULT && !state.match.result;
+  if (!inMatch) { live.active = false; return live; }
+  const round = Number(pub.round) || 0;
+  if (!live.active) {
+    live.active = true;
+    live.startedAt = now;
+    live.sawStart = round <= 1;
+    live.aliveRound = null;
+  }
+  const me = Array.isArray(pub.players) ? pub.players.find((p) => isObj(p) && p.playerId === state.me?.playerId) : null;
+  if (me && me.alive !== false) live.aliveRound = Math.max(live.aliveRound ?? 0, round);
+  return live;
+}
+
+/** Start following the store (main.js). Returns the unsubscribe function. */
+export function installStatsRecorder(store) {
+  observeMatch(liveMatch, store.get());
+  return store.subscribe((s) => observeMatch(liveMatch, s));
+}
+
+/**
+ * The rounds a player who leaves in `phase` of `round` has cleared — the server's rule for a quit (platform.js _quit:
+ * eliminated in round k ⇒ k − 1 passed; leaving in the settlement of round k counts k).
+ * @param {string} phase @param {number} round
+ */
+export function clearedRounds(phase, round) {
+  const r = Number.isFinite(round) ? round : 0;
+  return Math.max(0, phase === PHASE.SETTLE ? r : r - 1);
+}
+
+/**
+ * Build the quit record of a match the local player is leaving (放弃模拟), from the app state and the tracker. Null when
+ * there is nothing of mine to record: no match on screen, its settlement already here (that one is recorded by
+ * recordResult), a spectator seat, or a match the page never saw.
+ * @param {any} state the app store state BEFORE the match is cleared
+ * @param {{ live?: ReturnType<typeof createLiveMatch>, now?: number }} [ctx]
+ * @returns {any|null}
+ */
+export function buildQuitRecord(state, ctx = {}) {
+  const live = ctx.live ?? liveMatch;
+  const now = int(ctx.now, Date.now());
+  const pub = state?.match?.public;
+  const myId = str(state?.me?.playerId);
+  if (!pub || !myId || state.match.result || !live.active) return null;
+  const row = Array.isArray(pub.players) ? pub.players.find((p) => isObj(p) && p.playerId === myId) : null;
+  if (!row) return null; // a spectator seat is no player of the match
+  const alive = row.alive !== false;
+  const round = Number(pub.round) || 0;
+  // alive: the rounds cleared so far; already eliminated: the round it was seen alive in, less one (unknown when the
+  // page never saw it alive — a reload after the elimination)
+  const roundsPassed = alive ? clearedRounds(pub.phase, round) : (live.aliveRound != null ? Math.max(0, live.aliveRound - 1) : null);
+  return normalizeRecord({
+    v: STATS_VERSION,
+    t: now,
+    id: `q.${fnv1a([myId, live.startedAt, pub.modeId ?? '-', state.room?.code ?? '-'].join('|'))}`,
+    end: 'quit',
+    victory: false,
+    roundsPassed,
+    lastRound: num(pub.lastRound),
+    hiddenReached: pub.phase === PHASE.HIDDEN_CORE,
+    hiddenCleared: false,
+    reason: 'quit',
+    modeId: str(pub.modeId),
+    difficulty: str(pub.difficulty),
+    stageId: str(pub.stageId),
+    bossId: str(pub.bossId),
+    hiddenBossId: str(pub.hiddenBossId),
+    seed: null,
+    durationMs: live.sawStart ? Math.max(0, now - live.startedAt) : null,
+    teamLp: num(pub.teamLp),
+    roomMode: roomModeOf(str(pub.modeId), state.room?.mode),
+    selfId: myId,
+    players: [{
+      playerId: myId, seat: row.seat, name: row.name, isBot: false, left: true, alive, victory: false, roundsPassed,
+      eliminatedRound: alive ? null : live.aliveRound, lp: row.lp, bandId: row.bandId,
+    }],
+  });
+}
+
+/**
+ * The m.result-shaped payload behind a settled record — the inverse of buildRecord. The stats page's history
+ * rows hand this to the settlement view (screens/result.js reads it through normalizeResult): a finished match can be
+ * RE-VIEWED because the record kept every field the payload had. Whatever a record never stored is simply absent and
+ * normalizeResult defaults it, exactly like a tolerant live payload. A quit record (nothing was settled) and a
+ * compacted one (its rows are gone) have no settlement to show.
+ * @param {any} rec
+ * @returns {any|null} null when the row is not a usable, full, settled record
+ */
+export function recordToResult(rec) {
+  const r = normalizeRecord(rec);
+  if (!r || r.end === 'quit' || r.compact) return null;
+  const res = {
+    victory: r.victory,
+    roundsPassed: r.roundsPassed,
+    hiddenReached: r.hiddenReached,
+    hiddenCleared: r.hiddenCleared,
+    reason: r.reason,
+    modeId: r.modeId,
+    difficulty: r.difficulty,
+    bossId: r.bossId,
+    hiddenBossId: r.hiddenBossId,
+    seed: r.seed,
+    durationMs: r.durationMs,
+    teamLp: r.teamLp,
+    players: r.players,
+  };
+  if (Number.isFinite(r.lastRound)) res.lastRound = r.lastRound;
+  return res;
+}
+
+/**
+ * Append one record: replays (same content id) are dropped, newest first, capped at MAX_RECORDS.
+ * @param {{ v: number, records: any[] }} stats
+ * @param {any} record
+ * @returns {{ stats: { v: number, records: any[] }, added: boolean }}
+ */
+export function appendRecord(stats, record) {
+  if (!record || !record.id) return { stats, added: false };
+  if (stats.records.some((r) => r.id === record.id)) return { stats, added: false };
+  const records = [record, ...stats.records].slice(0, MAX_RECORDS);
+  return { stats: { v: STATS_VERSION, records }, added: true };
+}
+
+/** load → append → save of one built record (never over an envelope of a newer build). @returns {any|null} the record when stored */
+function storeRecord(rec) {
+  if (!rec) return null;
+  const stats = loadStats();
+  if (stats.newer) return null;
+  const { stats: next, added } = appendRecord(stats, rec);
+  if (added && !saveStats(next)) console.warn('[stats] localStorage write failed (quota?), record not persisted');
+  return added ? rec : null;
+}
+
+/**
+ * Record a finished match end-to-end (load → append → save). Returns the built record, or null when
+ * nothing was stored (no players / not my match / replay).
+ * @param {any} res raw m.result payload
+ * @param {{ myId?: string|null, roomMode?: string|null, now?: number }} [ctx]
+ * @returns {any|null}
+ */
+export function recordResult(res, ctx = {}) {
+  return storeRecord(buildRecord(res, ctx));
+}
+
+/**
+ * Record the match the player is giving up (放弃模拟), before the app clears its state. Returns the record, or null.
+ * @param {any} state the app store state before the match is cleared
+ * @param {{ live?: ReturnType<typeof createLiveMatch>, now?: number }} [ctx]
+ * @returns {any|null}
+ */
+export function recordQuit(state, ctx = {}) {
+  const live = ctx.live ?? liveMatch;
+  const rec = storeRecord(buildQuitRecord(state, ctx));
+  live.active = false; // one record per match
+  return rec;
+}
+
+/**
+ * Merge two envelopes (import into existing): union by record id, newest first, capped.
+ * @param {{ records: any[] }} a current (wins ties)
+ * @param {{ records: any[] }} b incoming
+ * @returns {{ v: number, records: any[] }}
+ */
+export function mergeStats(a, b) {
+  const byId = new Map();
+  for (const r of [...(Array.isArray(b?.records) ? b.records : []), ...(Array.isArray(a?.records) ? a.records : [])]) {
+    const rec = normalizeRecord(r);
+    if (rec) byId.set(rec.id, rec);
+  }
+  const records = [...byId.values()].sort(newestFirst).slice(0, MAX_RECORDS);
+  return { v: STATS_VERSION, records };
+}
+
+/**
+ * Parse + migrate + merge an exported / pasted payload into the current data.
+ * @param {any} raw parsed JSON of the imported file
+ * @param {{ records: any[] }} current current envelope
+ * @returns {{ stats: { v: number, records: any[] }, added: number, skipped: number, dropped: number }}
+ *   added = records new to this device; skipped = duplicates of records it has; dropped = rows of the file that could
+ *   not be read
+ */
+export function importStats(raw, current) {
+  if (isObj(raw) && raw.kind != null && raw.kind !== 'local-stats') {
+    const err = new Error('not a stats export'); // the page shows its own text
+    err.code = 'stats-bad-file';
+    throw err;
+  }
+  if (!isObj(raw) || !Array.isArray(raw.records)) {
+    const err = new Error('not a stats export');
+    err.code = 'stats-bad-file';
+    throw err;
+  }
+  const { stats: incoming, newer, dropped } = migrateStats(raw);
+  if (newer) {
+    const err = new Error('exported by a newer client'); // the page shows its own text
+    err.code = 'stats-newer-version';
+    throw err;
+  }
+  const have = new Set((Array.isArray(current?.records) ? current.records : []).map((r) => r.id));
+  const merged = mergeStats(current, incoming);
+  const added = incoming.records.filter((r) => !have.has(r.id)).length;
+  return { stats: merged, added, skipped: incoming.records.length - added, dropped };
+}
+
+/**
+ * The payload the export button downloads (envelope + a little provenance).
+ * @param {{ records: any[] }} stats
+ * @returns {{ app: string, kind: string, v: number, exportedAt: string, records: any[] }}
+ */
+export function exportStats(stats) {
+  return {
+    app: 'stronghold-protocol',
+    kind: 'local-stats',
+    v: STATS_VERSION,
+    exportedAt: new Date().toISOString(),
+    records: fitToBudget(Array.isArray(stats?.records) ? stats.records : []),
+  };
+}
+
+// ---- aggregation (what the page shows; records may hold more than any view uses) ------------------------------------
+
+const SELF_STATS = ['dmgDealt', 'kills', 'bossDamage', 'activatedLayers', 'merges', 'itemsEquipped', 'gold', 'perfectRounds', 'refreshes', 'leaks', 'lpLost'];
+
+/**
+ * The row that "is me" in a record: selfId, else the only human, else seat 0 — records written by
+ * recordResult always have selfId; the fallbacks only serve imported / hand-made data.
+ * @param {any} rec
+ * @returns {any|null}
+ */
+export function selfRowOf(rec) {
+  const ps = Array.isArray(rec?.players) ? rec.players : [];
+  return ps.find((p) => p.playerId && p.playerId === rec.selfId)
+    || ps.find((p) => !p.isBot)
+    || ps[0]
+    || null;
+}
+
+/** Whether this record counts as a win for its self player (per-row victory = team won AND still in). */
+const selfWon = (rec, self) => (self ? !!self.victory : !!rec.victory);
+
+/**
+ * The rounds the player passed in a record: its own row's (the table the settlement prints per player), else the
+ * team's; 0 when the record does not know.
+ * @param {any} rec
+ */
+export function roundsOf(rec) {
+  const self = selfRowOf(rec);
+  const v = self && Number.isFinite(self.roundsPassed) ? self.roundsPassed : rec?.roundsPassed;
+  return Number.isFinite(v) ? v : 0;
+}
+
+/**
+ * Whether a record enters the aggregates (see the header). A settled record always does. A quit record does once the
+ * player had finished at least one battle: cleared a round, or was already eliminated; a match given up before that —
+ * entered and left right away — is history only.
+ * @param {any} rec a normalized record
+ * @returns {boolean}
+ */
+export function countsTowardStats(rec) {
+  if (!isObj(rec)) return false;
+  if (rec.end !== 'quit') return true;
+  const self = selfRowOf(rec);
+  if (!self) return false;
+  return self.alive === false || (Number.isFinite(self.roundsPassed) && self.roundsPassed >= 1);
+}
+
+/**
+ * Aggregate records for the stats page — over the records that count; `total` / `excluded` say how many did not.
+ * Everything is keyed by ids (bandId / titleId / difficulty); the page maps them to names and icons through the game
+ * data. The combat totals read the settled records' stat blocks (a quit record has none).
+ * @param {any[]} records
+ * @returns {any}
+ */
+export function aggregateStats(records) {
+  const all = Array.isArray(records) ? records : [];
+  const rs = all.filter(countsTowardStats);
+  const out = {
+    total: all.length, count: rs.length, excluded: all.length - rs.length, wins: 0,
+    rounds: { total: 0, max: 0 },
+    duration: { totalMs: 0 },
+    hidden: { reached: 0, cleared: 0 },
+    byDifficulty: {}, byMode: { solo: 0, coop: 0 },
+    titles: {}, bands: {}, sums: {},
+  };
+  for (const rec of rs) {
+    const self = selfRowOf(rec);
+    const won = selfWon(rec, self);
+    if (won) out.wins++;
+    const rounds = roundsOf(rec);
+    out.rounds.total += rounds;
+    out.rounds.max = Math.max(out.rounds.max, rounds);
+    out.duration.totalMs += num(rec.durationMs) || 0;
+    if (rec.hiddenReached) out.hidden.reached++;
+    if (rec.hiddenCleared) out.hidden.cleared++;
+
+    const d = rec.difficulty || 'UNKNOWN';
+    const bd = (out.byDifficulty[d] ||= { games: 0, wins: 0, hiddenCleared: 0 });
+    bd.games++;
+    if (won) bd.wins++;
+    if (rec.hiddenCleared) bd.hiddenCleared++;
+
+    if (rec.roomMode === 'solo' || rec.roomMode === 'coop') out.byMode[rec.roomMode]++;
+
+    const titleId = self?.title?.id;
+    if (titleId) {
+      const t = (out.titles[titleId] ||= { count: 0 });
+      t.count++;
+    }
+
+    const bandId = self?.bandId;
+    if (bandId) {
+      const b = (out.bands[bandId] ||= { games: 0, wins: 0 });
+      b.games++;
+      if (won) b.wins++;
+    }
+
+    if (rec.end !== 'quit' && self && isObj(self.stats)) {
+      for (const k of SELF_STATS) {
+        const v = self.stats[k];
+        if (Number.isFinite(v)) out.sums[k] = (out.sums[k] || 0) + v;
+      }
+    }
+  }
+  return out;
+}