sindicate 0.2.0 → 0.5.0

package/src/systems/missions.js

@@ -0,0 +1,418 @@
+// missions.js — the mission ENGINE (v2). A mission is an ordered list of STAGES, each a first-class
+// objective (talk · kill · goto · deliver · defend · escort) with a target, a description, a live
+// counter, and optional onEnter/onComplete hooks. The engine runs ONE story spine at a time, advances
+// stage by stage, drives the compass/map objective marker, and only pays out at the end. Definitions
+// (data/missions.js) are immutable; PROGRESS is a small JSON blob persisted to localStorage (auto-save
+// on every stage change) — the basis for save/load. See docs/PLAN_missions_v2.md.
+//
+// Wiring (main.js): registerNpc(npc) for every giver/target NPC, registerHook(id, fn) for the spawn
+// hooks a mission's onEnter needs, then boot() once the world exists. The game feeds events in:
+// enemyKilled(e) from enemy.die, talked(npcId) from a dialogue topic, and update(dt) each frame for
+// the position-based types.
+import * as THREE from 'three/webgpu';
+// Campaign defs, save-key namespace and act title-cards are GAME data:
+//   configureMissions({ defs, saveKey, stageCards })
+let MISSION_DEFS = [];
+let KEY = 'sindicate_save_';
+let STAGE_CARDS = {};
+export function configureMissions({ defs = null, saveKey = null, stageCards = null } = {}) {
+  if (defs) MISSION_DEFS = defs;
+  if (saveKey) KEY = saveKey;
+  if (stageCards) STAGE_CARDS = stageCards;
+}
+
+// MULTI-SLOT SAVES. localStorage `dustwater_save_<slot>`: slot 'auto' is the running autosave (written
+// silently on every stage change); numbered slots are the player's manual saves from the Save screen.
+
+const AUTO = 'auto';
+
+// Act-break cards (ui.stageCard) — shown when the spine crosses into a new stage-pack.
+const keyOf = (slot) => KEY + slot;
+
+// A small JPEG of the scene for the Load screen. WebGPU won't let drawImage read the canvas, so render
+// the scene to a tiny offscreen target and read it back — the exact pattern tools/map.js uses for its
+// thumbnails (sync render, setRenderTarget(null), buffer RETURNED, top-left origin so no flip). Reuses
+// one target + canvas. Null (→ "no preview") if it can't. Called after a save, patching the slot.
+async function captureThumb(game) {
+  try {
+    const { renderer, scene, camera } = game;
+    if (!renderer?.readRenderTargetPixelsAsync || !scene || !camera) return null;
+    const w = 256, h = 144;
+    const rt = (captureThumb._rt ||= new THREE.RenderTarget(w, h));
+    renderer.setRenderTarget(rt);
+    renderer.render(scene, camera);
+    renderer.setRenderTarget(null);
+    const buf = await renderer.readRenderTargetPixelsAsync(rt, 0, 0, w, h);
+    // the RT is LINEAR (no post grade), so it reads dark — lift it to sRGB (gamma 1/2.2) via a LUT so
+    // the thumbnail looks like the graded game, not a murky raw pass.
+    const lut = (captureThumb._lut ||= (() => { const t = new Uint8Array(256); for (let i = 0; i < 256; i++) t[i] = Math.round(255 * Math.pow(i / 255, 1 / 2.2)); return t; })());
+    for (let i = 0; i < buf.length; i += 4) { buf[i] = lut[buf[i]]; buf[i + 1] = lut[buf[i + 1]]; buf[i + 2] = lut[buf[i + 2]]; }
+    const c = (captureThumb._c ||= Object.assign(document.createElement('canvas'), { width: w, height: h }));
+    const ctx = c.getContext('2d'), img = ctx.createImageData(w, h);
+    img.data.set(buf);   // top-left origin — no flip (per map.js)
+    ctx.putImageData(img, 0, 0);
+    return c.toDataURL('image/jpeg', 0.62);
+  } catch (e) { console.warn('[save] thumbnail failed', e?.message ?? e); return null; }
+}
+
+export class Missions {
+  constructor(game) {
+    this.game = game;
+    this.defs = MISSION_DEFS;
+    this.hooks = {};             // hook id -> fn (onEnter spawners, etc.)
+    this.npcs = {};              // def.id -> NPC (givers + talk targets)
+    this._stageEnemies = [];     // the live hostiles a kill stage is tracking
+    this.progress = this._loadKey(keyOf(AUTO)) || this._loadKey(keyOf('1')) || this._fresh();   // resume the autosave (legacy slot 1 as fallback)
+  }
+
+  _fresh() { return { version: 1, money: null, active: MISSION_DEFS[0]?.id ?? null, missions: {}, flags: {}, stats: {} }; }   // read at CALL time — a module-level capture predates registration
+  // `id` override: county NPCs carry GENERATED ids (`sheriff7`), so campaign givers found by NAME
+  // register under a stable alias the mission defs can target ('fisk', 'august', 'rand'…).
+  registerNpc(npc, id = null) { const k = id ?? npc?.def?.id; if (k && npc) this.npcs[k] = npc; }
+  registerHook(id, fn) { this.hooks[id] = fn; }
+
+  // STORY FLAGS — the campaign's persistent keys (badge worn, dynamite proven, house for sale…).
+  // Written by mission completion (def.flags) or by anything else (the house purchase), saved with
+  // the rest of progress.
+  flag(name) { return !!(this.progress.flags ??= {})[name]; }
+  setFlag(name, v = true) { (this.progress.flags ??= {})[name] = v; this.game._applyCrewState?.(); this._save(); }
+
+  // STORY STATS — the campaign's sliding scales (trust, reputation). Numbers, not booleans: every
+  // hard choice nudges them (topic `stat: { trust: -1 }`), and later stages read them through
+  // onlyIf/skipIf-style gates in dialogue (`statMin: { trust: 2 }` / `statMax`) or plain stat().
+  stat(name) { return (this.progress.stats ??= {})[name] ?? 0; }
+  addStat(name, d) { const s = (this.progress.stats ??= {}); s[name] = (s[name] ?? 0) + d; this.game._applyCrewState?.(); this._save(); }
+
+  // ── lookups into the active mission ──────────────────────────────────────────────────
+  get def() { return this.defs.find((m) => m.id === this.progress.active) || null; }
+  _rec() { const a = this.progress.active; return (this.progress.missions[a] ??= { stage: 0, done: false, counters: {} }); }
+  get stageIndex() { return this._rec().stage; }
+  get stage() { return this.def?.stages[this.stageIndex] || null; }
+
+  // Called once after the NPCs + world exist. Resumes the saved mission at its stage (silent) and
+  // restores the purse. (Position is NOT restored on boot — only via an explicit Load — so a dev
+  // reload doesn't yank the player around; a Continue from the title will call loadGame instead.)
+  boot() {
+    // MIGRATION: a save from before the campaign shipped finished m1 and persisted active: null —
+    // under the old defs there was nothing to unlock. Re-open the spine: first mission not yet done
+    // whose prerequisites all are (for that save, c1_dust).
+    if (!this.progress.active) {
+      const next = this.defs.find((m) => !this.progress.missions[m.id]?.done
+        && (m.requires || []).every((r) => this.progress.missions[r]?.done));
+      if (next) this.progress.active = next.id;
+    }
+    if (!this.progress.active) return;
+    if (this.progress.money != null && this.game.loot) this.game.loot.money = this.progress.money;
+    this._enterStage(true);
+  }
+
+  // In-session load (the SYSTEM tab's Load Game): restore progress + purse + position, then rebuild
+  // the current stage's world. NOTE: kill counters reset on load — the benched hostiles all respawn
+  // (per-enemy kill persistence is a later refinement).
+  loadGame(slot) {
+    const s = slot != null ? this._loadKey(keyOf(slot)) : this._mostRecent();
+    if (!s || !s.active) { this.game.ui?.toast?.('No saved game found.', 3000); return false; }
+    this.progress = { version: s.version, money: s.money, active: s.active, missions: s.missions || {}, flags: s.flags || {}, stats: s.stats || {}, player: s.player };
+    if (s.money != null && this.game.loot) this.game.loot.money = s.money;
+    if (s.playtime != null) this.game._playSeconds = s.playtime;
+    if (s.player && this.game.player) {
+      this.game.player.position.set(s.player.x, this.game.world.groundAt(s.player.x, s.player.z) + 0.5, s.player.z);
+      if (s.player.heading != null) this.game.player.heading = s.player.heading;
+    }
+    this._enterStage(true);
+    this.game.ui?.toast?.('Game loaded.', 2500);
+    return true;
+  }
+
+  hasSave() { return this.listSaves().length > 0; }   // any save FILE exists (auto or manual)
+
+  // ── stage lifecycle ──────────────────────────────────────────────────────────────────
+  _enterStage(resuming) {
+    const s = this.stage;
+    if (!s) return;
+    this.game._ensurePackBench?.(this.progress.active);   // lazy-bench this pack's hostiles (+ the next's)
+    this._stageEnemies = [];
+    // a talk stage hands its own dialogue to the giver, so his lines match the stage. The NPC's
+    // ORIGINAL tree (usually undefined — treeFor falls back to NAMED/ROLES) is stashed on first
+    // wrap and restored when the mission completes, so a barkeep goes back to being a MERCHANT
+    // and not a man stuck forever on one campaign scene.
+    if (s.type === 'talk' && s.tree) {
+      const npc = this.npcs[s.target];
+      if (npc) {
+        if (!('_preTree' in npc.def)) npc.def._preTree = npc.def.tree;
+        npc.def.tree = this._wrapTree(s.tree, s.target);
+        ((this._wrapped ??= {})[this.progress.active] ??= new Set()).add(s.target);
+      }
+    }
+    // FOLLOW / UNFOLLOW — a stage can put a registered NPC on the player's heel (escorts, walking a
+    // recruit home) and take him off it. Tracked per mission so complete() can never leave a man
+    // trailing the player for the rest of his life.
+    for (const key of [].concat(s.follow ?? [])) {
+      const n = this.npcs[key];
+      if (n) { n._follow = true; ((this._followers ??= {})[this.progress.active] ??= new Set()).add(key); }
+    }
+    for (const key of [].concat(s.unfollow ?? [])) { const n = this.npcs[key]; if (n) n._follow = false; }
+    // onEnter hook (spawn/teleport a set, open a door…). Runs on resume too — the hooks teleport
+    // already-benched entities, so they're idempotent, and a saved kill stage needs its world back.
+    if (s.onEnter) this.hooks[s.onEnter]?.(this);
+    this._setMarkers();
+    // A KILL STAGE WITH NOBODY LEFT TO KILL completes itself. Reachable via an in-session Load of a
+    // stale slot (the bench died later in this same session — the hook skips the dead), where the
+    // old behavior was worse than a stall: with zero matched hostiles, the NEXT kill of ANY stranger
+    // in the county advanced the stage. Skip it cleanly instead — UNLESS the tag's bench is simply
+    // still LOADING (pack-gated lazy spawn): then hold; _spawnPackBench re-enters when the men land.
+    if (s.type === 'kill' && this._stageEnemies.length === 0) {
+      if (this.game._benchPending?.(s.tag)) return;
+      this._save(); return this.advance();
+    }
+    // a stage can open on a SCENE (scenes.js — letterboxed camera beats; plays once per save)
+    if (s.scene) this.game.scenes?.play?.(s.scene);
+    if (!resuming) {
+      if (this.stageIndex === 0 && !this._quietTitle) this.game.ui?.questBanner?.(this.def.title?.toUpperCase?.() || 'NEW JOB');
+      if (s.desc) this.game.ui?.toast?.(s.desc, 6500);
+    }
+    this._save();
+  }
+
+  // Transform a data tree's `complete: true` topic into one that advances this talk stage when picked.
+  // `targetId` is the stage's own target key, captured at wrap time — NOT npc.def.id: county NPCs are
+  // registered under a stable ALIAS ('fisk', 'august', 'rand') while their def.id is generated, so
+  // completing via def.id would never match the stage and the talk would never advance.
+  //
+  // BRANCHING lives in the topics (the campaign's choices are things you SAY):
+  //   flag: 'name'|[...]   picking this topic sets these story flags (spare/kill, bribe/refuse…)
+  //   goto: 'stageId'      a completing topic can route to a NAMED stage instead of the next one
+  //   onlyIf / skipIf      the topic only appears when the flags allow — earlier choices shape
+  //                        later conversations (evaluated at stage entry, when the tree is wrapped)
+  _wrapTree(tree, targetId) {
+    const topics = (tree.topics || [])
+      .filter((t) => this._condOk(t))
+      .map((t) => (t.complete || t.flag || t.stat)
+        ? { ...t, action: (npc, dlg) => {
+            for (const f of [].concat(t.flag ?? [])) (this.progress.flags ??= {})[f] = true;
+            for (const [k, d] of Object.entries(t.stat ?? {})) { const s = (this.progress.stats ??= {}); s[k] = (s[k] ?? 0) + d; }
+            this.game._applyCrewState?.();
+            if (t.complete) dlg?.ui?.game?.missions?.talked(targetId ?? npc?.def?.id, t.goto);
+          } }
+        : t);
+    return { ...tree, topics };
+  }
+
+  // Gate checks, shared by stages AND topics:
+  //   onlyIf / skipIf — a flag name or list (onlyIf: all set; skipIf: none set)
+  //   statMin / statMax — { statName: bound } thresholds (statMin: at least; statMax: at most)
+  _condOk(o) {
+    const f = this.progress.flags ?? {};
+    if (o.onlyIf && ![].concat(o.onlyIf).every((k) => f[k])) return false;
+    if (o.skipIf && [].concat(o.skipIf).some((k) => f[k])) return false;
+    for (const [k, v] of Object.entries(o.statMin ?? {})) if (this.stat(k) < v) return false;
+    for (const [k, v] of Object.entries(o.statMax ?? {})) if (this.stat(k) > v) return false;
+    return true;
+  }
+
+  // The active stage's target lights the gold objective marker (compass + map).
+  _setMarkers() {
+    const s = this.stage;
+    // clear old
+    for (const id in this.npcs) this.npcs[id].objective = false;
+    for (const e of this._stageEnemies) if (e) e.objective = false;
+    let marks = [];
+    if (!s) { this.game.questMarkers = []; return; }
+    if (s.type === 'talk' || s.type === 'deliver') {
+      const npc = this.npcs[s.target || s.to];
+      if (npc) { npc.objective = true; marks = [npc]; }
+    } else if (s.type === 'kill' || s.type === 'defend' || s.type === 'escort') {
+      this._stageEnemies = this._matchEnemies(s);
+      for (const e of this._stageEnemies) e.objective = true;
+      marks = this._stageEnemies.slice();
+      if (s.type === 'escort' && this.npcs[s.who]) marks.push(this.npcs[s.who]);
+    } else if (s.type === 'goto') {
+      marks = [{ position: { x: s.pos.x, y: 0, z: s.pos.z }, objective: true, alive: true, type: 'objective' }];
+    }
+    this.game.questMarkers = marks;
+  }
+
+  // the live hostiles this stage cares about, by explicit ids or a mission tag stamped at spawn
+  _matchEnemies(s) {
+    const en = this.game.combat?.enemies ?? [];
+    return en.filter((e) => e.alive && (
+      (s.targets && s.targets.includes(e.missionId)) || (s.tag && e.missionTag === s.tag)));
+  }
+
+  // ── the event bus the game feeds ─────────────────────────────────────────────────────
+  // a hostile died — advance a kill stage when its quota is met
+  enemyKilled(e) {
+    const s = this.stage;
+    if (!s || s.type !== 'kill') return;
+    const rec = this._rec();
+    const alive = this._matchEnemies(s).length;
+    const spawned = s.count ?? this._stageEnemies.length;
+    rec.counters[s.id] = Math.min(spawned, spawned - alive);
+    this._setMarkers();
+    this._save();
+    if (alive === 0 && (rec.counters[s.id] >= spawned || this._stageEnemies.length === 0)) this.advance();
+  }
+
+  // the player finished a giver's dialogue that completes the current talk stage. `gotoId` is the
+  // branching topic's routing — advance to that named stage instead of the next in order.
+  talked(npcId, gotoId = null) {
+    const s = this.stage;
+    if (s && s.type === 'talk' && s.target === npcId) this.advance(gotoId);
+  }
+
+  // per-frame — position-based completion (goto, escort arrival, defend timer), plus the two gates:
+  //   timeLimit + onExpire — a stage that can be LOST forward: run out the clock and the mission
+  //                          routes to the named stage instead (the fuse burns down, the wagon rolls)
+  //   hours: [from, to]    — a goto that only completes inside the window (night jobs). Wrapping
+  //                          windows (21→5) welcome.
+  update(dt) {
+    const s = this.stage;
+    if (!s) return;
+    if (s.timeLimit && s.onExpire) {
+      const rec = this._rec();
+      rec.counters[`t_${s.id}`] = (rec.counters[`t_${s.id}`] ?? 0) + dt;
+      if (rec.counters[`t_${s.id}`] >= s.timeLimit) { this.game.ui?.toast?.(s.expireDesc ?? 'Too late.', 5000); return this.advance(s.onExpire); }
+    }
+    const p = this.game.player?.position;
+    if (s.type === 'goto' && p) {
+      if (s.hours) {
+        const h = this.game.world?.sky?.hour ?? 12, [a, b] = s.hours;
+        const inWin = a <= b ? (h >= a && h <= b) : (h >= a || h <= b);
+        if (!inWin) {
+          // standing at the mark at the wrong hour: say so, once — the man at the door at noon
+          // shouldn't have to guess that the job wants dark (rest at a fire passes the hours)
+          const r = s.radius ?? 6;
+          if ((p.x - s.pos.x) ** 2 + (p.z - s.pos.z) ** 2 <= (r + 8) ** 2)
+            this.game.hint?.(`hours_${s.id}`, `Not at this hour. This work keeps different ones — rest at a fire to pass the time.`);
+          return;
+        }
+      }
+      const r = s.radius ?? 6;
+      if ((p.x - s.pos.x) ** 2 + (p.z - s.pos.z) ** 2 <= r * r) this.advance();
+    } else if (s.type === 'defend' && s.seconds) {
+      const rec = this._rec();
+      rec.counters[s.id] = (rec.counters[s.id] ?? 0) + dt;
+      if (rec.counters[s.id] >= s.seconds) this.advance();
+    } else if (s.type === 'escort') {
+      const who = this.npcs[s.who];
+      if (who && ((who.position.x - s.to.x) ** 2 + (who.position.z - s.to.z) ** 2) <= (s.radius ?? 6) ** 2) this.advance();
+    }
+  }
+
+  // an item reached its destination (called from the delivery interaction when it lands)
+  delivered(item, toId) {
+    const s = this.stage;
+    if (s && s.type === 'deliver' && s.item === item && (s.to === toId || !s.to)) this.advance();
+  }
+
+  // ── advance / complete ───────────────────────────────────────────────────────────────
+  // `toId` (branching): jump to the named stage instead of the next in order. Either way, stages
+  // whose onlyIf/skipIf don't match this playthrough's flags are stepped over — that's how one
+  // mission carries both halves of a fork and each run only walks its own.
+  advance(toId = null) {
+    const rec = this._rec(), def = this.def, s = this.stage;
+    if (s?.onComplete) this.hooks[s.onComplete]?.(this);
+    let i = toId != null ? def.stages.findIndex((st) => st.id === toId) : rec.stage + 1;
+    if (i < 0) { console.warn('[missions] goto to unknown stage', toId); i = rec.stage + 1; }
+    while (i < def.stages.length && !this._condOk(def.stages[i])) i++;
+    if (i >= def.stages.length) { this.complete(); return; }
+    rec.stage = i;
+    this._enterStage(false);
+  }
+
+  complete() {
+    const rec = this._rec(), def = this.def;
+    rec.done = true;
+    if (def.reward?.money && this.game.loot) this.game.loot.money = (this.game.loot.money ?? 0) + def.reward.money;
+    if (def.reward?.items?.length) this.game.loot?._giveItems?.(def.reward.items);       // [{id,n}] into the satchel, toasted
+    for (const f of def.flags ?? []) (this.progress.flags ??= {})[f] = true;             // story keys this mission proves
+    this.game.ui?.questBanner?.(def.doneBanner ?? 'THE JOB IS DONE');
+    if (def.reward?.money) this.game.ui?.toast?.(`$${def.reward.money} — the county pays its debts.`, 8000);
+    // Every NPC this mission wrapped goes back to who he was: the stashed original tree (usually
+    // undefined → treeFor's NAMED/ROLES fallback, which is how the barkeep gets his BAR back after
+    // c1 and August his ammunition counter after c4 — a wrapped tree left in place buried their
+    // merchant lines for the rest of the game). Toomey alone keeps a plain post-mission line: his
+    // role fallback is the anonymous drifter tree, which reads worse than one tired sentence.
+    for (const key of this._wrapped?.[def.id] ?? []) {
+      const n = this.npcs[key];
+      if (n && '_preTree' in n.def) { n.def.tree = n.def._preTree; delete n.def._preTree; }
+    }
+    delete this._wrapped?.[def.id];
+    // …and nobody keeps following the player out of a finished mission
+    for (const key of this._followers?.[def.id] ?? []) { const n = this.npcs[key]; if (n) n._follow = false; }
+    delete this._followers?.[def.id];
+    this.game._applyCrewState?.();   // completion flags may have recruited someone — seat them at the house
+    if (def.giver === 'deputy_toomey' && this.npcs.deputy_toomey) {
+      this.npcs.deputy_toomey.def.tree = { openers: [`Town's quieter than it was. There'll be more paper before long.`], topics: [] };
+    }
+    // unlock the next spine mission (one at a time): first unlock whose prereqs are all done
+    const next = (def.unlocks || []).map((id) => this.defs.find((m) => m.id === id))
+      .find((m) => m && (m.requires || []).every((r) => this.progress.missions[r]?.done));
+    this.progress.active = next ? next.id : null;
+    if (next) {
+      // crossing into a new STAGE-PACK gets the act-break card (letterbox + act title) on top of
+      // everything else — the campaign's between-stages cinematic beat.
+      const actBreak = next.id[0] !== def.id[0] && STAGE_CARDS[next.id[0]];
+      if (actBreak) setTimeout(() => this.game.ui?.stageCard?.(actBreak[0], actBreak[1]), 2600);
+      // enter the next mission with its TITLE BANNER held back — fired synchronously it lands in the
+      // same frame as the doneBanner above and stomps it (questBanner replaces immediately). The
+      // banner is wall-clock UI chrome, so a wall-clock delay is the right tool; the guard drops it
+      // if the player has already moved the story on by then.
+      this._rec(); this._quietTitle = true; this._enterStage(false); this._quietTitle = false;
+      const nd = this.def;
+      setTimeout(() => { if (this.def === nd) this.game.ui?.questBanner?.(nd.title?.toUpperCase?.() || 'NEW JOB'); }, actBreak ? 10200 : 4800);
+    } else this._setMarkers();                            // no next — clear every objective marker
+    this._save();
+  }
+
+  // ── persistence (multi-slot) ──────────────────────────────────────────────────────────
+  snapshot() {
+    const p = this.game.player?.position;
+    return { version: this.progress.version, money: this.game.loot?.money ?? this.progress.money,
+      active: this.progress.active, missions: this.progress.missions, flags: this.progress.flags ?? {}, stats: this.progress.stats ?? {},
+      player: p ? { x: p.x, z: p.z, heading: this.game.player.heading } : this.progress.player,
+      // metadata for the Load screen: date, current job, playtime. (thumb is filled in async below.)
+      savedAt: Date.now(), title: this.def?.title ?? 'Dustwater', objective: this.stage?.desc ?? '',
+      playtime: this.game._playSeconds ?? 0 };
+  }
+
+  // Write a save. slot 'auto' = the running autosave (silent); a number = a manual save (toasts). The
+  // thumbnail is a WebGPU readback (async), so the slot is written now with the PREVIOUS thumb (no
+  // flicker) and patched with the fresh one when the pixels land.
+  saveGame(slot = AUTO, name = null) {
+    const snap = this.snapshot();
+    snap.slot = slot; snap.auto = (slot === AUTO);
+    snap.name = name != null ? name : (slot === AUTO ? 'Autosave' : snap.title);
+    const prev = this._loadKey(keyOf(slot)); if (prev?.thumb) snap.thumb = prev.thumb;
+    try { localStorage.setItem(keyOf(slot), JSON.stringify(snap)); } catch (e) { /* private mode / quota */ }
+    this.game.ui?.saving?.();                                          // the SAVING… spinner (auto + manual)
+    if (slot !== AUTO) this.game.ui?.toast?.('Game saved.', 2500);
+    this._patchThumb(slot);
+    return true;
+  }
+  async _patchThumb(slot) {
+    const thumb = await captureThumb(this.game);
+    if (!thumb) return;
+    try { const raw = localStorage.getItem(keyOf(slot)); if (!raw) return; const s = JSON.parse(raw); s.thumb = thumb; localStorage.setItem(keyOf(slot), JSON.stringify(s)); } catch (e) {}
+  }
+  _save() { this.saveGame(AUTO); }   // auto-persist on every stage change (silent)
+
+  // every save on disk, newest first, with its slot id — for the Save/Load screen.
+  listSaves() {
+    const out = [];
+    try {
+      for (let i = 0; i < localStorage.length; i++) {
+        const k = localStorage.key(i);
+        if (!k || !k.startsWith(KEY)) continue;
+        const s = JSON.parse(localStorage.getItem(k));
+        if (s && s.active !== undefined) out.push({ ...s, slot: s.slot ?? k.slice(KEY.length) });
+      }
+    } catch (e) { /* private mode / bad json */ }
+    return out.sort((a, b) => (b.savedAt ?? 0) - (a.savedAt ?? 0));
+  }
+  _mostRecent() { return this.listSaves()[0] || null; }
+  deleteSave(slot) { try { localStorage.removeItem(keyOf(slot)); } catch (e) {} }
+  _loadKey(k) { try { const s = localStorage.getItem(k); return s ? JSON.parse(s) : null; } catch (e) { return null; } }
+
+  reset() { this.deleteSave(AUTO); this.progress = this._fresh(); }   // New Game: fresh autosave; manual saves are kept
+}