Chess Lab #11 — Lessons có lộ trình & goal-driven kiểm tra

Puzzle ở bài 10 cho người chơi từng câu hỏi rời rạc. Bài 11 ráp thành lộ trình: chương → bài, mỗi bài có một mục tiêu cụ thể, hoàn thành được lưu lại để buổi sau quay lại đúng chỗ. Đây là chế độ "khoá học".

Goal: discriminated union

Mỗi lesson trỏ về 1 trong 3 loại goal:

export type LessonGoal =
  | { kind: "mate" }
  | { kind: "pieceAt"; square: Square; pieceType: PieceSymbol; color: Color }
  | { kind: "captureAt"; square: Square };

Checker khớp 1-1:

function matches(goal: LessonGoal, move: Move): boolean {
  switch (goal.kind) {
    case "mate":
      return chess.status().kind === "checkmate";
    case "pieceAt": {
      const p = chess.pieceAt(goal.square);
      return !!p && p.type === goal.pieceType && p.color === goal.color;
    }
    case "captureAt":
      return move.to === goal.square && !!move.captured;
  }
}

TypeScript bắt buộc bạn cover mọi case — quên 1 nhánh, compiler báo "not all paths return". Thêm reachSquare, escapeCheck, noCheckN = thêm 1 nhánh union, TS dẫn bạn ngay tới checker và mọi UI hiển thị liên quan.

Curriculum

3 chương x 2-3 bài:

8 bài đầu cho người mới hoàn toàn. Mở rộng bằng cách push vào array CHAPTERS — không cần code mới.

LessonManager + persistence

const PROGRESS_KEY = "chess-lab.lesson-progress";

export class LessonManager {
  private current: Lesson | null = null;
  private status: LessonStatus = "playing";
  private completed: Set<string>;

  constructor() {
    this.completed = loadProgress();
  }

  load(id: string): Lesson | null {
    const l = findLesson(id);
    if (!l) return null;
    this.current = l;
    this.status = "playing";
    chess.reset(l.fen);
    return l;
  }

  checkAfterMove(move: Move): boolean {
    if (!this.current || this.status !== "playing") return false;
    if (matches(this.current.goal, move)) {
      this.status = "completed";
      this.completed.add(this.current.id);
      saveProgress(this.completed);
      return true;
    }
    return false;
  }

  isCompleted(id: string): boolean { return this.completed.has(id); }
}

function loadProgress(): Set<string> {
  try {
    const raw = localStorage.getItem(PROGRESS_KEY);
    if (!raw) return new Set();
    return new Set(JSON.parse(raw) as string[]);
  } catch { return new Set(); }
}
function saveProgress(set: Set<string>): void {
  try {
    localStorage.setItem(PROGRESS_KEY, JSON.stringify([...set]));
  } catch { /* private mode → bỏ qua */ }
}

Try-catch quanh localStorage là phòng vệ cho Safari private mode (ném QuotaExceeded khi setItem). In-memory state vẫn hoạt động — chỉ là mất tiến trình khi đóng tab.

Wire vào scene

Trong applyMove sau tryMove thành công:

if (mode.current === "lesson") {
  lessons.checkAfterMove(move);
}

Một dòng. Nếu goal đạt → status = "completed", panel render banner "✓ Đã hoàn thành" + nút "Bài tiếp →".

Mode lesson cũng bypass cả AI client lẫn tutor — học không có máy phản công, không có badge ?! ?? làm rối.

SidePanel: chapter list

Render 3 cột thông tin:

1. Lesson hiện tại — tiêu đề, intro, hint (nếu có), nút "Bài tiếp →" khi hoàn thành.
2. Chapter list — accordion phẳng các chương, mỗi lesson là 1 button có checkmark nếu đã xong.

for (const ch of CHAPTERS) {
  listHtml += `<div class="chapter"><div class="chapter-title">${ch.title}</div>`;
  for (const l of ch.lessons) {
    const done = lessons.isCompleted(l.id);
    const isCur = cur?.id === l.id;
    listHtml += `
      <button class="lesson-card ${isCur ? "current" : ""} ${done ? "done" : ""}"
              data-lesson-id="${l.id}">
        <span class="lesson-mark">${done ? "✓" : "○"}</span>
        <span class="lesson-name">${l.title}</span>
      </button>
    `;
  }
  listHtml += `</div>`;
}

Click bằng event delegation — listener gắn 1 lần trên container, đọc data-lesson-id. Re-render danh sách khi event bus emit không phá vỡ listener.

Auto-load lesson đầu chưa xong

Khi user chuyển sang mode lesson lần đầu, mặc định nhảy vào lesson đầu tiên chưa hoàn thành:

if (mode.current === "lesson") {
  const all = CHAPTERS.flatMap((c) => c.lessons);
  const next = all.find((l) => !lessons.isCompleted(l.id)) ?? all[0];
  scene.loadLesson(next.id);
}

UX nhỏ nhưng quan trọng: user quay lại sau 1 tuần, không phải scroll chapter list để tìm chỗ dừng — app dẫn vào ngay.

Bẫy hay gặp

Bài tập

1. Goal mới: reachWithKnight — user phải đưa Mã đi qua 1 chuỗi ô theo thứ tự (ví dụ a1 → b3 → d4). Thêm nhánh union, checker theo move.from + move.to so với chuỗi expected.
2. Theo dõi best score: cho mỗi lesson, lưu thêm số nước user dùng để hoàn thành. Sau mỗi lần solve, so sánh với optimal — hiển thị ★/★★/★★★ theo độ tối ưu.
3. Chapter unlock: chapter sau chỉ mở khi chương trước hoàn thành 80%+. Disable button lesson khi chương chưa unlock, kèm icon 🔒.

Bài tiếp theo

Bài 12 — Persistence + responsive + a11y: chuyển progress sang IndexedDB qua idb-keyval. Touch-friendly drag cho mobile. Scale manager đúng nghĩa cho viewport hẹp. Contrast/aria cho a11y. Lighthouse a11y ≥ 90.