@dsbasko/cookbook-engine 0.1.0

package/src/lib/i18n.ts

@@ -0,0 +1,474 @@
+import { type Lang } from './lang';
+
+/**
+ * UI string dictionary. Every key here must exist in every entry of
+ * UI_STRINGS — TypeScript enforces this via the `Record<Lang, UIDict>`
+ * shape below. Add new keys here first, then translations.
+ *
+ * Scope: strings rendered by components listed in Task 10 of the i18n
+ * plan (Header/Breadcrumbs, Sidebar, ProgramDrawer, LessonNav, Toc,
+ * ReadingProgress, LessonLockedInterstitial, SettingsToggle, HomePage,
+ * LessonPageLayout, not-found) plus a few keys for adjacent surfaces
+ * already touched by lang switching (settings popover, theme labels
+ * previously lived in `lib/theme.ts`).
+ */
+export type UIDict = {
+  // Sidebar
+  sidebarLabel: string;
+  navMainLabel: string;
+  home: string;
+  programCourse: string;
+  githubRepo: string;
+
+  // Header / Breadcrumbs
+  breadcrumbsLabel: string;
+
+  // ProgramDrawer
+  close: string;
+  moduleListLabel: string;
+  lessonLockTitle: string;
+
+  // LessonNav
+  lessonNavLabel: string;
+  prevLesson: string;
+  nextLesson: string;
+
+  // Mobile drawer lesson-nav: short eyebrow used next to a chevron icon
+  prevLessonShort: string;
+  nextLessonShort: string;
+  currentLessonEyebrow: string;
+  currentLessonNumberPrefix: string;
+
+  // Mobile settings: "Resources" section + GitHub link sub-label
+  settingsResourcesLabel: string;
+  githubRepoSub: string;
+
+  // HeaderLessonNav (chevron buttons reuse a shorter form without the arrow)
+  prevLessonAria: string;
+  nextLessonAria: string;
+  firstLessonTitle: string;
+  lastLessonTitle: string;
+
+  // Toc
+  tocLabel: string;
+
+  // ReadingProgress
+  readingProgressLabel: string;
+
+  // LessonLockedInterstitial
+  locked: string;
+  moduleNumberPrefix: string;
+  lockedTitle: string;
+  lockedDesc: string;
+  attemptedLessonLabel: string;
+  attemptedYouTried: string;
+  continueAction: string;
+  startFromFirst: string;
+  openProgram: string;
+  courseProgress: string;
+  progress: string;
+  nextStep: string;
+  untilThisLesson: string;
+
+  // SettingsToggle — theme section labels
+  themeLight: string;
+  themeDark: string;
+  themePaper: string;
+
+  // HomePage
+  heroTitleLead: string;
+  heroTitleAccent: string;
+  heroTitleTail: string;
+  continueLessonPrefix: string;
+  startFromScratch: string;
+  progressSummary: string;
+  modulesLabel: string;
+  lessonsLabel: string;
+  durationLabel: string;
+  stackLabel: string;
+  moduleLockTitle: string;
+
+  // LessonPageLayout
+  lessonInfoLabel: string;
+
+  // not-found
+  notFoundTitle: string;
+  notFoundDesc: string;
+  goHome: string;
+
+  // SettingsToggle — language section title (also used as radiogroup aria-label)
+  language: string;
+
+  // TranslationBanner (rendered on EN lesson pages that fall back to RU)
+  translationFallbackTitle: string;
+  translationFallbackBody: string;
+
+  // ModulePage
+  startModule: string;
+  continueModulePrefix: string;
+  rereadModule: string;
+  nextModule: string;
+  moduleProgress: string;
+  lessonsCount: string;
+  durationLabelShort: string;
+  stackLabelShort: string;
+  moduleLessonsHeading: string;
+  lessonLockShort: string;
+  lessonHintContinue: string;
+  lessonNeighbourModulesLabel: string;
+  prevModule: string;
+
+  // LessonSideMeta
+  moduleMetaKey: string;
+  readingTimeMetaKey: string;
+  tagsMetaKey: string;
+  markUnread: string;
+
+  // ProgressBar / aria
+  progressBarAriaLabel: string;
+  progressAriaConnector: string;
+
+  // Metadata fallbacks. The brand wordmark is composed in at the call site
+  // (notFound title = `${notFoundTitle} · <brand name>`); `ogImageAlt` is the
+  // default alt text, overridable via brand.ogImage.alt.
+  ogImageAlt: string;
+
+  // HomePage module status (CSS-only pseudo-element labels lifted into JSX)
+  statusNotStarted: string;
+  statusInProgress: string;
+  statusComplete: string;
+
+  // Callout titles (rendered server-side via MDX pipeline)
+  calloutNote: string;
+  calloutTip: string;
+  calloutWarning: string;
+  calloutImportant: string;
+  calloutCaution: string;
+
+  // CodeBlock copy button
+  codeBlockCopy: string;
+  codeBlockCopied: string;
+  codeBlockCopyAriaLabel: string;
+  codeBlockCopiedAriaLabel: string;
+
+  // SettingsToggle — trigger label and section titles
+  settingsLabel: string;
+  settingsEyebrow: string;
+  settingsThemeSection: string;
+
+  // SettingsToggle — prose/code sections
+  readingPrefsProseSection: string;
+  readingPrefsCodeSection: string;
+  readingPrefsSize: string;
+  readingPrefsFont: string;
+  readingPrefsDecrease: string;
+  readingPrefsIncrease: string;
+  readingPrefsFontSerif: string;
+  readingPrefsFontSans: string;
+  readingPrefsFontSlab: string;
+  readingPrefsFontJetBrains: string;
+  readingPrefsFontFira: string;
+  readingPrefsPreviewProse: string;
+  readingPrefsPreviewCode: string;
+
+  // SettingsToggle — free-reading (disable progress) section
+  freeReadingSection: string;
+  freeReadingTitle: string;
+  freeReadingDesc: string;
+  freeReadingResetWarning: string;
+  freeReadingResetConfirm: string;
+  freeReadingResetCancel: string;
+};
+
+export const UI_STRINGS: Record<Lang, UIDict> = {
+  ru: {
+    sidebarLabel: 'Боковая навигация',
+    navMainLabel: 'Основная навигация',
+    home: 'Главная',
+    programCourse: 'Программа курса',
+    githubRepo: 'Репозиторий на GitHub',
+
+    breadcrumbsLabel: 'Хлебные крошки',
+
+    close: 'Закрыть',
+    moduleListLabel: 'Список модулей и уроков',
+    lessonLockTitle: 'Урок откроется после прохождения предыдущих',
+
+    lessonNavLabel: 'Навигация по урокам',
+    prevLesson: '← Предыдущий урок',
+    nextLesson: 'Следующий урок →',
+
+    prevLessonShort: 'пред.',
+    nextLessonShort: 'след.',
+    currentLessonEyebrow: '/ текущий урок',
+    currentLessonNumberPrefix: 'урок',
+
+    settingsResourcesLabel: 'Ресурсы',
+    githubRepoSub: 'исходный код курса',
+
+    prevLessonAria: 'Предыдущий урок',
+    nextLessonAria: 'Следующий урок',
+    firstLessonTitle: 'Это первый урок',
+    lastLessonTitle: 'Это последний урок',
+
+    tocLabel: 'Содержание',
+
+    readingProgressLabel: 'Прогресс чтения',
+
+    locked: 'LOCKED',
+    moduleNumberPrefix: 'Модуль',
+    lockedTitle: 'Этот урок ещё впереди',
+    lockedDesc:
+      'Курс изучается по порядку — чтобы открыть этот шаг, сначала завершите предыдущие. Так контекст накапливается без пропусков.',
+    attemptedLessonLabel: 'Урок, который вы открыли',
+    attemptedYouTried: '/ вы пытались открыть',
+    continueAction: 'Продолжить',
+    startFromFirst: 'Начать с первого урока',
+    openProgram: 'Открыть программу',
+    courseProgress: 'Прогресс курса',
+    progress: 'Прогресс',
+    nextStep: 'Следующий шаг',
+    untilThisLesson: 'До этого урока',
+
+    themeLight: 'Светлая',
+    themeDark: 'Тёмная',
+    themePaper: 'Бумага',
+
+    heroTitleLead: 'Kafka',
+    heroTitleAccent: 'для тех, кто',
+    heroTitleTail: 'пишет на Go',
+    continueLessonPrefix: 'Продолжить · урок',
+    startFromScratch: 'Начать с начала',
+    progressSummary: 'Сводка прогресса',
+    modulesLabel: 'Модулей',
+    lessonsLabel: 'Уроков',
+    durationLabel: 'Длительность',
+    stackLabel: 'Стек',
+    moduleLockTitle: 'Модуль откроется после прохождения предыдущих уроков',
+
+    lessonInfoLabel: 'Сведения об уроке',
+
+    notFoundTitle: 'Страница не найдена',
+    notFoundDesc: 'Похоже, такой лекции в курсе нет. Вернитесь на главную.',
+    goHome: 'На главную',
+
+    language: 'Язык',
+
+    translationFallbackTitle: 'Перевод в процессе',
+    translationFallbackBody:
+      'Английская версия этой лекции пока не готова. Показан оригинал на русском.',
+
+    startModule: 'Начать модуль',
+    continueModulePrefix: 'Продолжить',
+    rereadModule: 'Перечитать модуль',
+    nextModule: 'Следующий модуль',
+    moduleProgress: 'Прогресс модуля',
+    lessonsCount: 'Уроков',
+    durationLabelShort: 'Длительность',
+    stackLabelShort: 'Стек',
+    moduleLessonsHeading: 'Уроки модуля',
+    lessonLockShort: 'Урок откроется после прохождения предыдущих',
+    lessonHintContinue: '↳ продолжить отсюда',
+    lessonNeighbourModulesLabel: 'Соседние модули',
+    prevModule: '← Предыдущий модуль',
+
+    moduleMetaKey: 'модуль',
+    readingTimeMetaKey: 'время чтения',
+    tagsMetaKey: 'теги',
+    markUnread: 'Пометить непрочитанным',
+
+    progressBarAriaLabel: 'Прогресс прохождения курса',
+    progressAriaConnector: 'из',
+
+    ogImageAlt: 'Kafka Cookbook — курс по Apache Kafka на Go',
+
+    statusNotStarted: 'не начато',
+    statusInProgress: 'в процессе',
+    statusComplete: 'пройдено',
+
+    calloutNote: 'Заметка',
+    calloutTip: 'Подсказка',
+    calloutWarning: 'Внимание',
+    calloutImportant: 'Важно',
+    calloutCaution: 'Осторожно',
+
+    codeBlockCopy: 'copy',
+    codeBlockCopied: '✓ скопировано',
+    codeBlockCopyAriaLabel: 'Скопировать код',
+    codeBlockCopiedAriaLabel: 'Скопировано',
+
+    settingsLabel: 'Настройки',
+    settingsEyebrow: '/ config',
+    settingsThemeSection: 'Тема',
+    readingPrefsProseSection: 'Текст лекции',
+    readingPrefsCodeSection: 'Текст кода',
+    readingPrefsSize: 'Размер',
+    readingPrefsFont: 'Шрифт',
+    readingPrefsDecrease: 'A−',
+    readingPrefsIncrease: 'A+',
+    readingPrefsFontSerif: 'Literata',
+    readingPrefsFontSans: 'Inter',
+    readingPrefsFontSlab: 'Roboto Slab',
+    readingPrefsFontJetBrains: 'JetBrains',
+    readingPrefsFontFira: 'Fira',
+    readingPrefsPreviewProse:
+      'Шрифт и размер выбираются так, чтобы длинные лекции читались легко.',
+    readingPrefsPreviewCode: 'consumer.subscribe(topics)',
+
+    freeReadingSection: 'Прогресс',
+    freeReadingTitle: 'Свободное чтение',
+    freeReadingDesc: 'Открыть все уроки и скрыть прогресс',
+    freeReadingResetWarning: 'Накопленный прогресс будет сброшен.',
+    freeReadingResetConfirm: 'Сбросить',
+    freeReadingResetCancel: 'Отмена',
+  },
+  en: {
+    sidebarLabel: 'Side navigation',
+    navMainLabel: 'Main navigation',
+    home: 'Home',
+    programCourse: 'Course outline',
+    githubRepo: 'GitHub repository',
+
+    breadcrumbsLabel: 'Breadcrumbs',
+
+    close: 'Close',
+    moduleListLabel: 'Module and lesson list',
+    lessonLockTitle: 'Lesson unlocks after the previous ones are complete',
+
+    lessonNavLabel: 'Lesson navigation',
+    prevLesson: '← Previous lesson',
+    nextLesson: 'Next lesson →',
+
+    prevLessonShort: 'prev',
+    nextLessonShort: 'next',
+    currentLessonEyebrow: '/ current lesson',
+    currentLessonNumberPrefix: 'lesson',
+
+    settingsResourcesLabel: 'Resources',
+    githubRepoSub: 'course source code',
+
+    prevLessonAria: 'Previous lesson',
+    nextLessonAria: 'Next lesson',
+    firstLessonTitle: 'This is the first lesson',
+    lastLessonTitle: 'This is the last lesson',
+
+    tocLabel: 'Contents',
+
+    readingProgressLabel: 'Reading progress',
+
+    locked: 'LOCKED',
+    moduleNumberPrefix: 'Module',
+    lockedTitle: 'This lesson is still ahead',
+    lockedDesc:
+      'The course goes in order — to open this step, finish the previous ones first. Context builds up without gaps that way.',
+    attemptedLessonLabel: 'Lesson you tried to open',
+    attemptedYouTried: '/ you tried to open',
+    continueAction: 'Continue',
+    startFromFirst: 'Start from the first lesson',
+    openProgram: 'Open outline',
+    courseProgress: 'Course progress',
+    progress: 'Progress',
+    nextStep: 'Next step',
+    untilThisLesson: 'Until this lesson',
+
+    themeLight: 'Light',
+    themeDark: 'Dark',
+    themePaper: 'Paper',
+
+    heroTitleLead: 'Kafka',
+    heroTitleAccent: 'for people who',
+    heroTitleTail: 'write Go',
+    continueLessonPrefix: 'Continue · lesson',
+    startFromScratch: 'Start over',
+    progressSummary: 'Progress summary',
+    modulesLabel: 'Modules',
+    lessonsLabel: 'Lessons',
+    durationLabel: 'Duration',
+    stackLabel: 'Stack',
+    moduleLockTitle: 'Module unlocks after the previous lessons are complete',
+
+    lessonInfoLabel: 'Lesson info',
+
+    notFoundTitle: 'Page not found',
+    notFoundDesc: 'There is no such lesson in the course. Head back home.',
+    goHome: 'Go home',
+
+    language: 'Language',
+
+    translationFallbackTitle: 'Translation in progress',
+    translationFallbackBody:
+      'The English version of this lesson is not ready yet. Showing the original Russian text.',
+
+    startModule: 'Start module',
+    continueModulePrefix: 'Continue',
+    rereadModule: 'Reread module',
+    nextModule: 'Next module',
+    moduleProgress: 'Module progress',
+    lessonsCount: 'Lessons',
+    durationLabelShort: 'Duration',
+    stackLabelShort: 'Stack',
+    moduleLessonsHeading: 'Lessons',
+    lessonLockShort: 'Lesson unlocks after the previous ones are complete',
+    lessonHintContinue: '↳ continue from here',
+    lessonNeighbourModulesLabel: 'Neighbouring modules',
+    prevModule: '← Previous module',
+
+    moduleMetaKey: 'module',
+    readingTimeMetaKey: 'reading time',
+    tagsMetaKey: 'tags',
+    markUnread: 'Mark as unread',
+
+    progressBarAriaLabel: 'Course completion progress',
+    progressAriaConnector: 'of',
+
+    ogImageAlt: 'Kafka Cookbook — Apache Kafka course in Go',
+
+    statusNotStarted: 'not started',
+    statusInProgress: 'in progress',
+    statusComplete: 'complete',
+
+    calloutNote: 'Note',
+    calloutTip: 'Tip',
+    calloutWarning: 'Warning',
+    calloutImportant: 'Important',
+    calloutCaution: 'Caution',
+
+    codeBlockCopy: 'copy',
+    codeBlockCopied: '✓ copied',
+    codeBlockCopyAriaLabel: 'Copy code',
+    codeBlockCopiedAriaLabel: 'Copied',
+
+    settingsLabel: 'Settings',
+    settingsEyebrow: '/ config',
+    settingsThemeSection: 'Theme',
+    readingPrefsProseSection: 'Lesson text',
+    readingPrefsCodeSection: 'Code text',
+    readingPrefsSize: 'Size',
+    readingPrefsFont: 'Font',
+    readingPrefsDecrease: 'A−',
+    readingPrefsIncrease: 'A+',
+    readingPrefsFontSerif: 'Literata',
+    readingPrefsFontSans: 'Inter',
+    readingPrefsFontSlab: 'Roboto Slab',
+    readingPrefsFontJetBrains: 'JetBrains',
+    readingPrefsFontFira: 'Fira',
+    readingPrefsPreviewProse: 'Pick a typeface and size that make long lessons comfortable to read.',
+    readingPrefsPreviewCode: 'consumer.subscribe(topics)',
+
+    freeReadingSection: 'Progress',
+    freeReadingTitle: 'Free reading',
+    freeReadingDesc: 'Unlock every lesson and hide progress',
+    freeReadingResetWarning: 'Your accumulated progress will be reset.',
+    freeReadingResetConfirm: 'Reset',
+    freeReadingResetCancel: 'Cancel',
+  },
+};
+
+/**
+ * Server-friendly accessor. Server components receive `lang` via route
+ * params; pass it in here. Client components should prefer `useT()` from
+ * `web/lib/use-i18n.ts` instead — it reads `lang` from `useParams()`.
+ */
+export function getDict(lang: Lang): UIDict {
+  return UI_STRINGS[lang];
+}

package/src/lib/lang.ts

@@ -0,0 +1,90 @@
+export type Lang = 'ru' | 'en';
+
+export const LANGS: readonly Lang[] = ['ru', 'en'] as const;
+export const DEFAULT_LANG: Lang = 'en';
+export const LANG_STORAGE_KEY = 'kafka-cookbook-lang';
+
+export const LANG_LABELS: Record<Lang, string> = {
+  ru: 'Русский',
+  en: 'English',
+};
+
+export function isLang(value: unknown): value is Lang {
+  return value === 'ru' || value === 'en';
+}
+
+export function getBrowserLang(): Lang {
+  if (typeof navigator === 'undefined') return DEFAULT_LANG;
+  const raw = navigator.language || (navigator.languages && navigator.languages[0]) || '';
+  return raw.toLowerCase().startsWith('ru') ? 'ru' : 'en';
+}
+
+export function readStoredLang(): Lang | null {
+  if (typeof window === 'undefined') return null;
+  try {
+    const raw = window.localStorage.getItem(LANG_STORAGE_KEY);
+    return isLang(raw) ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeStoredLang(lang: Lang): void {
+  if (typeof window === 'undefined') return;
+  try {
+    window.localStorage.setItem(LANG_STORAGE_KEY, lang);
+  } catch {
+    /* storage may be unavailable (private mode, quota); ignore. */
+  }
+}
+
+/**
+ * Strips a leading `/ru/` or `/en/` segment from a pathname. Used by URL
+ * parsers (LessonAwareLink, GateProvider, gate-scripts) so the remaining
+ * segments are `[moduleId, slug]` regardless of the active language.
+ *
+ * Examples:
+ *   /ru/foo/bar  -> { lang: 'ru', rest: '/foo/bar' }
+ *   /en/         -> { lang: 'en', rest: '/' }
+ *   /ru          -> { lang: 'ru', rest: '/' }
+ *   /foo/bar     -> { lang: null, rest: '/foo/bar' }
+ *   /enfoo       -> { lang: null, rest: '/enfoo' }
+ *   ''           -> { lang: null, rest: '/' }
+ */
+export function stripLangFromPath(pathname: string): { lang: Lang | null; rest: string } {
+  if (!pathname) return { lang: null, rest: '/' };
+  const match = pathname.match(/^\/(ru|en)(\/.*)?$/);
+  if (!match) return { lang: null, rest: pathname };
+  const lang = match[1] as Lang;
+  const rest = match[2] && match[2].length > 0 ? match[2] : '/';
+  return { lang, rest };
+}
+
+/**
+ * Inline script for the root `/page.tsx`. Decides whether to redirect the
+ * visitor to `/{lang}/` based on (1) stored preference, (2) navigator.language.
+ * If the resolved language equals DEFAULT_LANG we skip the redirect to avoid
+ * a flash — the static `/index.html` already serves DEFAULT_LANG content.
+ *
+ * Side effect: when the language is auto-detected (no stored value yet) we
+ * persist the choice so subsequent visits are stable.
+ *
+ * basePath is derived from `window.location.pathname`: the root index.html
+ * sits at `/{basePath}/`, so appending `{lang}/` to that path yields the
+ * correct redirect target without needing a build-time substitution.
+ */
+export const LANG_INIT_SCRIPT = `(function(){try{var key=${JSON.stringify(
+  LANG_STORAGE_KEY,
+)};var def=${JSON.stringify(
+  DEFAULT_LANG,
+)};var stored=null;try{stored=window.localStorage.getItem(key);}catch(e){}var lang;if(stored==='ru'||stored==='en'){lang=stored;}else{var nav=(navigator&&(navigator.language||(navigator.languages&&navigator.languages[0])))||'';lang=String(nav).toLowerCase().indexOf('ru')===0?'ru':'en';try{window.localStorage.setItem(key,lang);}catch(e){}}if(lang===def)return;var p=window.location.pathname;if(p.charAt(p.length-1)!=='/')p+='/';window.location.replace(p+lang+'/');}catch(e){}})();`;
+
+/**
+ * Inline script for `[lang]/layout.tsx`. Syncs `document.documentElement.lang`
+ * to the active language so in-browser APIs (Intl, screen readers) see the
+ * correct value — the static HTML always carries `<html lang={DEFAULT_LANG}>`
+ * because Next.js renders <html> once at the root layout.
+ */
+export function LANG_SYNC_SCRIPT(lang: Lang): string {
+  return `(function(){try{document.documentElement.lang=${JSON.stringify(lang)};}catch(e){}})();`;
+}

package/src/lib/lesson-gate.ts

@@ -0,0 +1,79 @@
+import {
+  flattenLessons,
+  getLessonIndex,
+  type Course,
+  type FlatLessonEntry,
+} from './course';
+import { isCompleted, lessonKey, type LessonKey, type ProgressMap } from './progress';
+
+/**
+ * Resolve the linear index of the user's furthest reached lesson. Returns
+ * the max of (a) the index of the stored pointer when it still maps to a
+ * real lesson, and (b) the highest index among completed entries that still
+ * exist in the course. Combining both sources protects against a cross-tab
+ * `bumpFurthest` race that could persist a lower pointer than the user has
+ * actually reached: the still-valid `progress` map heals the regression
+ * without waiting for another advance write. Returns -1 only when both
+ * sources are empty.
+ */
+export function resolveFurthestIndex(
+  course: Course,
+  furthestKey: LessonKey | null,
+  progress: ProgressMap,
+): number {
+  const flat = flattenLessons(course);
+  let max = -1;
+
+  if (furthestKey !== null) {
+    const idx = flat.findIndex((e) => lessonKey(e.moduleId, e.lesson.slug) === furthestKey);
+    if (idx > max) max = idx;
+  }
+
+  for (let i = 0; i < flat.length; i += 1) {
+    const key = lessonKey(flat[i].moduleId, flat[i].lesson.slug);
+    if (isCompleted(progress, key) && i > max) {
+      max = i;
+    }
+  }
+  return max;
+}
+
+/**
+ * A lesson is unlocked when its index is no further than `furthestIndex + 1`.
+ * That extra step is what makes "the next lesson after the furthest" reachable
+ * — without it, a fresh user (furthestIndex = -1) could not even open the
+ * first lesson (index 0).
+ */
+export function isLessonUnlocked(lessonIndex: number, furthestIndex: number): boolean {
+  if (lessonIndex < 0) return false;
+  return lessonIndex <= furthestIndex + 1;
+}
+
+export function isLessonKeyUnlocked(
+  course: Course,
+  moduleId: string,
+  slug: string,
+  furthestKey: LessonKey | null,
+  progress: ProgressMap,
+): boolean {
+  const idx = getLessonIndex(course, moduleId, slug);
+  if (idx === -1) return false;
+  return isLessonUnlocked(idx, resolveFurthestIndex(course, furthestKey, progress));
+}
+
+/**
+ * The "current frontier" lesson — the one a fresh CTA should target. Always
+ * the first locked-but-reachable lesson (`furthestIndex + 1`), so the user
+ * lands on what they've not yet finished even when checkmarks have been
+ * toggled. Returns null when the course is empty or the user has finished it.
+ */
+export function getFrontierLesson(
+  course: Course,
+  furthestIndex: number,
+): FlatLessonEntry | null {
+  const flat = flattenLessons(course);
+  if (flat.length === 0) return null;
+  const targetIndex = Math.min(furthestIndex + 1, flat.length - 1);
+  if (targetIndex < 0) return null;
+  return flat[targetIndex];
+}