Lời giải: Lưu trữ & migrate

      settings: { masterVolume: 1, musicVolume: 0.6, sfxVolume: 0.8, muted: false, touchControls: 'auto', tapJump: 'auto', difficulty: 'kid', showFps: false },

 * @property {boolean} showFps                 hiện bộ đếm FPS (mặc định false)

// 1) Save cũ thiếu field → nhận mặc định
localStorage.setItem('oggy.bak', localStorage.getItem('oggyAdventure.save.v1'));        // sao lưu
localStorage.setItem('oggyAdventure.save.v1', JSON.stringify({ coins: 5, settings: { musicVolume: 0.2 } }));
location.reload();
OG.Save.data.settings.showFps;      // false, merge điền từ defaults()

// 2) + 3) Ghi và phát event
OG.Events.on('settings:change', function (e) { console.log('settings:change', e); });
OG.Save.setSetting('showFps', true); // in: settings:change {key: 'showFps', value: true}
location.reload();
OG.Save.data.settings.showFps;      // true

// Khôi phục
localStorage.setItem('oggyAdventure.save.v1', localStorage.getItem('oggy.bak')); location.reload();

// @ts-check
/* ============================================================================
 * OG.JumpStats — THỐNG KÊ SỐ LẦN NHẢY (ví dụ module dùng OG.Save.ns)
 * ----------------------------------------------------------------------------
 * Vai trò:      Đếm số lần nhảy: tổng cộng và kỷ lục "ít lần nhảy nhất" mỗi màn. Lưu trong
 *               OG.Save.ns('jumpStats'), chỉ commit ở mốc quan trọng (xong màn / thua), không commit mỗi cú nhảy.
 * Khái niệm:    namespace dữ liệu (ext) · tự chữa dữ liệu thiếu/hỏng · gom ghi (batch commit) · observer
 * Bài học:      docs/learn/11-luu-tru-migrate.md (bài tập ⭐⭐)
 * Phụ thuộc:    LOAD: OG.Events.on · CHẠY: OG.Save.ns, OG.Save.commit
 * Event:        nghe: 'player:jump', 'level:start', 'level:complete', 'game:over'
 * API công khai: OG.JumpStats.total(), OG.JumpStats.fewest(levelId)
 * ========================================================================== */
(function () {
  'use strict';
  var OG = window.OG;

  // ⚠️ Bẫy: KHÔNG gọi OG.Save.ns() ở đây (lúc LOAD). Save.load() chạy SAU trong main.js và THAY
  //   OG.Save.data bằng object mới → mọi thứ ghi vào bản cũ biến mất. Cũng không lưu tham chiếu `var s = ns()`
  //   dài hạn: Save.reset() thay object, tham chiếu cũ thành "mồ côi". Gọi store() mỗi lần cần.
  function store() {
    var s = OG.Save.ns('jumpStats');
    if (typeof s.total !== 'number' || !isFinite(s.total)) s.total = 0;       // tự chữa save hỏng / sửa tay
    if (!s.fewest || typeof s.fewest !== 'object') s.fewest = {};
    return s;
  }

  var jumpsThisLevel = 0;   // trạng thái TẠM của màn đang chơi — không cần lưu

  OG.Events.on('level:start', function () { jumpsThisLevel = 0; });
  OG.Events.on('player:jump', function () {
    jumpsThisLevel++;
    store().total++;        // sửa trong bộ nhớ, CHƯA ghi xuống localStorage
  });
  OG.Events.on('level:complete', function (r) {
    var s = store(), id = r && r.levelId;
    if (id && (s.fewest[id] == null || jumpsThisLevel < s.fewest[id])) s.fewest[id] = jumpsThisLevel;
    OG.Save.commit();       // 💡 gom ghi: một lần commit thay cho hàng trăm lần (JSON.stringify cả save mỗi lần)
  });
  OG.Events.on('game:over', function () { OG.Save.commit(); });

  OG.JumpStats = {
    /** @returns {number} tổng số lần nhảy từ trước tới nay */
    total: function () { return store().total; },
    /** @param {string} levelId @returns {number|null} số lần nhảy ít nhất khi qua màn (null = chưa qua) */
    fewest: function (levelId) { var v = store().fewest[levelId]; return v == null ? null : v; }
  };
})();

<script src="src/game/jump-stats.js"></script>

  var SAVE_VERSION = 2;
  /** @param {any[]} arr @returns {any[]} mảng đã bỏ phần tử trùng (giữ thứ tự gặp đầu tiên) */
  function unique(arr) { return arr.filter(function (x, i) { return arr.indexOf(x) === i; }); }
  /**
   * MIGRATIONS[n] nâng dữ liệu từ v = n lên v = n + 1 (SỬA trực tiếp d). Mỗi bước chỉ biết đúng 2 phiên bản kề nhau.
   * @type {Object<number, function(any): void>}
   */
  var MIGRATIONS = {
    1: function (d) {
      // v2: chỉ nhận 2 chế độ chơi; giá trị lạ (save sửa tay, bản thử nghiệm) → 'kid'.
      if (d.settings.difficulty !== 'kid' && d.settings.difficulty !== 'challenge') d.settings.difficulty = 'kid';
      // v2: danh sách mở khoá không được trùng (bản cũ có thể push 2 lần).
      if (Array.isArray(d.unlockedChars)) d.unlockedChars = unique(d.unlockedChars);
      if (d.progress && Array.isArray(d.progress.unlocked)) d.progress.unlocked = unique(d.progress.unlocked);
    }
  };
  /** Chạy lần lượt các bước migrate cho tới SAVE_VERSION. @param {any} d @returns {any} chính d */
  function migrate(d) {
    if (typeof d.v !== 'number' || !isFinite(d.v)) d.v = 1;      // save rất cũ không có v → coi là v1
    if (d.v > SAVE_VERSION) { console.warn('[OG.Save] save từ phiên bản mới hơn (v' + d.v + '), giữ nguyên'); return d; }
    while (d.v < SAVE_VERSION) {
      var step = MIGRATIONS[d.v];
      if (!step) { console.warn('[OG.Save] thiếu migrate v' + d.v); break; }
      step(d);
      d.v++;
    }
    return d;
  }

    return {
      v: SAVE_VERSION,              // save MỚI đã ở phiên bản mới nhất, không cần migrate
      coins: 0,

        var saved = null;
        try { saved = JSON.parse(raw); } catch (e) { console.warn('[OG.Save] dữ liệu hỏng, dùng mặc định'); }
        if (saved && typeof saved === 'object') {
          var oldV = typeof saved.v === 'number' ? saved.v : 1;
          d = merge(d, saved);
          // ⚠️ Bẫy: save cũ KHÔNG có field v thì merge giữ v mặc định (= SAVE_VERSION) → tưởng đã mới, bỏ qua
          //   migrate. Phải đặt lại v theo dữ liệu ĐÃ LƯU.
          d.v = oldV;
          // Sao lưu chuỗi gốc trước khi biến đổi: migrate có bug thì vẫn khôi phục được bằng tay.
          if (oldV < SAVE_VERSION) storageSet(KEY + '.bak.v' + oldV, raw);
          try { migrate(d); } catch (e) { console.warn('[OG.Save] migrate lỗi, giữ dữ liệu đã gộp', e); }
        }

// check-migrate.js — chạy: node check-migrate.js   (đặt ở gốc repo)
const fs = require('fs'), vm = require('vm');
const D = require('./tests/fake-dom.js');
function run(saved) {
  const storage = D.makeStorage();
  storage.setItem('oggyAdventure.save.v1', JSON.stringify(saved));
  const warns = [];
  const ctx = { localStorage: storage, console: { warn: (...a) => warns.push(a.join(' ')), log() {} } };
  ctx.window = ctx; ctx.OG = { Events: { emit() {} } };      // save.js chỉ cần OG.Events.emit
  vm.createContext(ctx);
  vm.runInContext(fs.readFileSync('src/core/save.js', 'utf8'), ctx);
  const d = ctx.OG.Save.load();
  return { v: d.v, diff: d.settings.difficulty, chars: d.unlockedChars, unl: d.progress.unlocked,
    bak: storage.getItem('oggyAdventure.save.v1.bak.v1') != null, warns };
}
console.log(run({ v: 1, coins: 50, unlockedChars: ['oggy', 'jack', 'oggy'], settings: { difficulty: 'easy' }, progress: { unlocked: ['kitchen', 'kitchen'] } }));
console.log(run({ coins: 7, settings: { difficulty: 'challenge' } }));   // save rất cũ, không có v
console.log(run({ v: 2, coins: 9 }));
console.log(run({ v: 3, coins: 9 }));                                     // từ phiên bản mới hơn