feat: add "train second key" guided lesson option

Adds lesson.guided.trainSecondKey: previews and unlocks a second key
alongside the primary focus, one letter at a time.

Author: jpds

packages/keybr-lesson/lib/confirmed-unlocks.ts

@@ -0,0 +1,45 @@
+import { type CodePoint } from "@keybr/unicode";
+
+const storageKey = "lesson.guided.confirmedUnlocks";
+
+// Local-only, like @keybr/settings's Preferences -- deliberately not a
+// Settings prop, since writing one reconstructs GuidedLesson itself.
+export class ConfirmedUnlocks {
+  static load(scope: string): ReadonlySet<CodePoint> {
+    return new Set(readAll()[scope] ?? []);
+  }
+
+  static confirm(scope: string, codePoint: CodePoint): void {
+    const all = readAll();
+    const scoped = new Set(all[scope] ?? []);
+    if (!scoped.has(codePoint)) {
+      scoped.add(codePoint);
+      writeAll({ ...all, [scope]: [...scoped] });
+    }
+  }
+}
+
+function readAll(): Record<string, readonly CodePoint[]> {
+  if (typeof window !== "object") {
+    return {};
+  }
+  const item = window.localStorage.getItem(storageKey);
+  if (item == null) {
+    return {};
+  }
+  try {
+    const parsed: unknown = JSON.parse(item);
+    return parsed != null && typeof parsed === "object"
+      ? (parsed as Record<string, readonly CodePoint[]>)
+      : {};
+  } catch {
+    window.localStorage.removeItem(storageKey);
+    return {};
+  }
+}
+
+function writeAll(all: Record<string, readonly CodePoint[]>): void {
+  if (typeof window === "object") {
+    window.localStorage.setItem(storageKey, JSON.stringify(all));
+  }
+}

packages/keybr-lesson/lib/fakes.ts

@@ -1,20 +1,28 @@
 import { type Letter } from "@keybr/phonetic-model";
-import { type KeyStats, type KeyStatsMap, speedToTime } from "@keybr/result";
+import {
+  type KeySample,
+  type KeyStats,
+  type KeyStatsMap,
+  speedToTime,
+} from "@keybr/result";
 import { type Settings } from "@keybr/settings";
 import { type LessonKeys } from "./key.ts";
 import { Target } from "./target.ts";
 
+const defaultSampleCount = 5;
+
 export function fakeKeyStatsMap(
   settings: Settings,
   items: [
     letter: Letter,
     confidence: number | null,
     bestConfidence: number | null,
+    sampleCount?: number,
   ][],
 ): KeyStatsMap {
   const target = new Target(settings);
   const map = new Map<Letter, KeyStats>(
-    items.map(([letter, confidence, bestConfidence]) => {
+    items.map(([letter, confidence, bestConfidence, sampleCount]) => {
       const timeToType =
         confidence == null
           ? null
@@ -23,28 +31,54 @@ export function fakeKeyStatsMap(
         bestConfidence == null
           ? null
           : speedToTime(target.targetSpeed) / bestConfidence;
+      const count =
+        confidence == null && bestConfidence == null
+          ? 0
+          : (sampleCount ?? defaultSampleCount);
+      const samples: KeySample[] = Array.from(
+        { length: count },
+        (_, index) => ({
+          index,
+          timeStamp: 0,
+          hitCount: 1,
+          missCount: 0,
+          timeToType: timeToType ?? 0,
+          filteredTimeToType: timeToType ?? 0,
+        }),
+      );
       return [
         letter,
         {
           letter,
-          samples: [],
+          samples,
           timeToType,
           bestTimeToType,
         } as KeyStats,
       ];
     }),
   );
+  // A real KeyStatsMap.results grows by one per round; GuidedLesson.update()
+  // memoizes on it (plus identity of the last entry) to make its two
+  // same-round call sites idempotent. Synthesize one placeholder entry per
+  // sample so that varying sample counts across simulated rounds is seen
+  // as new evidence, while passing the exact same fakeKeyStatsMap() result
+  // to update() twice (same array, same last entry) is seen as a repeat.
+  const totalSamples = [...map.values()].reduce(
+    (sum, keyStats) => sum + keyStats.samples.length,
+    0,
+  );
+  const results = Array.from({ length: totalSamples }, () => ({}));
   return {
     letters: [...map.keys()],
-    results: [],
+    results,
     get: (letter) => map.get(letter),
     [Symbol.iterator]: () => map.values(),
   } as KeyStatsMap;
 }
 
 export function printLessonKeys(lessonKeys: LessonKeys) {
-  return lessonKeys
-    .findIncludedKeys()
+  return [...lessonKeys]
+    .filter((key) => key.isIncluded || key.isSecondFocused)
     .map((key) => {
       let s = `${key.letter}`;
       if (key.isForced) {
@@ -53,6 +87,9 @@ export function printLessonKeys(lessonKeys: LessonKeys) {
       if (key.isFocused) {
         s = `[${s}]`;
       }
+      if (key.isSecondFocused) {
+        s = `(${s})`;
+      }
       return s;
     })
     .join("");