@dsbasko/cookbook-engine 0.1.0

package/src/components/AppShell/AppShell.tsx

@@ -0,0 +1,135 @@
+'use client';
+
+import { useEffect, useState, type ReactNode } from 'react';
+import { usePathname } from 'next/navigation';
+import { Sidebar } from '@/components/Sidebar';
+import { Header } from '@/components/Header';
+import { Breadcrumbs } from '@/components/Header/Breadcrumbs';
+import { HeaderLessonNav } from '@/components/Header/HeaderLessonNav';
+import { ProgramDrawer } from '@/components/ProgramDrawer';
+import { ProgressBar } from '@/components/ProgressBar';
+import {
+  type Course,
+  getNextLesson,
+  getPrevLesson,
+  getTotalLessons,
+  resolveBrandName,
+} from '@/lib/course';
+import { DEFAULT_LANG, stripLangFromPath } from '@/lib/lang';
+import { OPEN_PROGRAM_EVENT } from '@/lib/program-drawer';
+import styles from './AppShell.module.css';
+
+type AppShellProps = {
+  children: ReactNode;
+  course: Course;
+};
+
+export function AppShell({ children, course }: AppShellProps) {
+  const pathname = usePathname() ?? '/';
+  const [isDrawerOpen, setIsDrawerOpen] = useState(false);
+
+  // Allow descendant components (Hero CTA on the home page) to ask for the
+  // program drawer without lifting state up — the AppShell stays the single
+  // owner of drawer state.
+  useEffect(() => {
+    const handler = () => setIsDrawerOpen(true);
+    window.addEventListener(OPEN_PROGRAM_EVENT, handler);
+    return () => window.removeEventListener(OPEN_PROGRAM_EVENT, handler);
+  }, []);
+
+  // After the i18n restructure every route lives under `/<lang>/...`.
+  // Strip the lang segment so module/slug detection sees the same shape
+  // it did pre-i18n; the AppShell stays language-agnostic for routing
+  // but forwards the active lang to the server-rendered Header (which
+  // needs it for aria-labels via getDict).
+  const { lang: parsedLang, rest } = stripLangFromPath(pathname);
+  const lang = parsedLang ?? DEFAULT_LANG;
+  const segments = rest.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
+  const moduleId = segments[0];
+  const lessonSlug = segments[1];
+
+  const currentModule = moduleId
+    ? course.modules.find((m) => m.id === moduleId)
+    : undefined;
+  const currentLesson =
+    currentModule && lessonSlug
+      ? currentModule.lessons.find((l) => l.slug === lessonSlug)
+      : undefined;
+
+  const prev =
+    currentModule && currentLesson
+      ? getPrevLesson(course, currentModule.id, currentLesson.slug)
+      : null;
+  const next =
+    currentModule && currentLesson
+      ? getNextLesson(course, currentModule.id, currentLesson.slug)
+      : null;
+
+  const brandRoot = resolveBrandName(course);
+
+  const breadcrumbs = (
+    <Breadcrumbs
+      lang={lang}
+      moduleId={currentModule?.id}
+      moduleTitle={currentModule?.title}
+      lessonTitle={currentLesson?.title}
+      brandRoot={brandRoot}
+    />
+  );
+
+  const actions = (
+    <>
+      <ProgressBar total={getTotalLessons(course)} lang={lang} />
+      {currentModule && currentLesson ? (
+        <HeaderLessonNav
+          prev={prev}
+          next={next}
+          currentModuleId={currentModule.id}
+          currentSlug={currentLesson.slug}
+        />
+      ) : null}
+    </>
+  );
+
+  // Home and module index pages own their own hero (eyebrow + breadcrumbs +
+  // progress card) — the global header would duplicate that chrome. Lesson
+  // pages keep the header because they need lesson nav + reading progress.
+  const isHome = rest === '/' || segments.length === 0;
+  const isModuleIndex = !!moduleId && !lessonSlug;
+  const hideHeader = isHome || isModuleIndex;
+
+  return (
+    <div className={styles.shell}>
+      <Sidebar
+        onProgramClick={() => setIsDrawerOpen((prev) => !prev)}
+        isProgramOpen={isDrawerOpen}
+        repoUrl={course.repoUrl}
+      />
+      <ProgramDrawer
+        course={course}
+        currentModuleId={currentModule?.id}
+        currentSlug={currentLesson?.slug}
+        currentLessonTitle={currentLesson?.title}
+        currentLessonIndex={
+          currentModule && currentLesson
+            ? currentModule.lessons.findIndex((l) => l.slug === currentLesson.slug) + 1
+            : undefined
+        }
+        currentModuleTitle={currentModule?.title}
+        isOpen={isDrawerOpen}
+        onClose={() => setIsDrawerOpen(false)}
+        prev={prev}
+        next={next}
+        repoUrl={course.repoUrl}
+        lang={lang}
+        totalLessons={getTotalLessons(course)}
+      />
+      <div className={styles.body}>
+        {hideHeader ? null : (
+          <Header lang={lang} breadcrumbs={breadcrumbs} actions={actions} brandRoot={brandRoot} />
+        )}
+        <main className={styles.main}>{children}</main>
+      </div>
+    </div>
+  );
+}

package/src/components/AppShell/index.ts

@@ -0,0 +1 @@
+export { AppShell } from './AppShell';

package/src/components/Callout/Callout.module.css

@@ -0,0 +1,68 @@
+.callout {
+  margin: var(--space-6) 0;
+  padding: var(--space-4) var(--space-5);
+  border-left: 3px solid var(--callout-accent, var(--accent-main));
+  border-radius: var(--radius-md);
+  background-color: var(--callout-bg, var(--accent-main-soft));
+  color: var(--content-primary);
+}
+
+.callout[data-callout-type='note'] {
+  --callout-accent: var(--accent-main);
+  --callout-bg: var(--accent-main-soft);
+}
+
+.callout[data-callout-type='tip'] {
+  --callout-accent: var(--accent-success);
+  --callout-bg: var(--accent-success-soft);
+}
+
+.callout[data-callout-type='warning'] {
+  --callout-accent: var(--accent-notice);
+  --callout-bg: var(--accent-notice-soft);
+}
+
+.callout[data-callout-type='important'] {
+  --callout-accent: var(--accent-main);
+  --callout-bg: var(--accent-main-soft);
+}
+
+.callout[data-callout-type='caution'] {
+  --callout-accent: var(--accent-critical);
+  --callout-bg: var(--accent-critical-soft);
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  margin-bottom: var(--space-2);
+  color: var(--callout-accent);
+  font-weight: var(--font-weight-semibold);
+}
+
+.icon {
+  flex-shrink: 0;
+}
+
+.title {
+  font-size: var(--font-size-sm);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.body {
+  color: var(--content-primary);
+}
+
+.body > * + * {
+  margin-top: var(--space-3);
+}
+
+.body > :first-child {
+  margin-top: 0;
+}
+
+.body > :last-child {
+  margin-bottom: 0;
+}

package/src/components/Callout/Callout.tsx

@@ -0,0 +1,83 @@
+import type { ReactNode, SVGProps } from 'react';
+import { DEFAULT_LANG, type Lang } from '@/lib/lang';
+import { getDict } from '@/lib/i18n';
+import styles from './Callout.module.css';
+
+export type CalloutType = 'note' | 'tip' | 'warning' | 'important' | 'caution';
+
+type CalloutProps = {
+  type: CalloutType;
+  lang?: Lang;
+  children?: ReactNode;
+};
+
+export function Callout({ type, lang = DEFAULT_LANG, children }: CalloutProps) {
+  const Icon = ICONS[type];
+  const t = getDict(lang);
+  const titles: Readonly<Record<CalloutType, string>> = {
+    note: t.calloutNote,
+    tip: t.calloutTip,
+    warning: t.calloutWarning,
+    important: t.calloutImportant,
+    caution: t.calloutCaution,
+  };
+  return (
+    <aside className={styles.callout} data-callout-type={type} role="note">
+      <header className={styles.header}>
+        <Icon className={styles.icon} aria-hidden="true" />
+        <span className={styles.title}>{titles[type]}</span>
+      </header>
+      <div className={styles.body}>{children}</div>
+    </aside>
+  );
+}
+
+export function isCalloutType(value: unknown): value is CalloutType {
+  return (
+    typeof value === 'string' &&
+    (value === 'note' ||
+      value === 'tip' ||
+      value === 'warning' ||
+      value === 'important' ||
+      value === 'caution')
+  );
+}
+
+type IconComponent = (props: SVGProps<SVGSVGElement>) => JSX.Element;
+
+const baseSvg = (path: string): IconComponent => {
+  function Icon(props: SVGProps<SVGSVGElement>) {
+    return (
+      <svg
+        viewBox="0 0 16 16"
+        width="16"
+        height="16"
+        fill="currentColor"
+        xmlns="http://www.w3.org/2000/svg"
+        {...props}
+      >
+        <path d={path} />
+      </svg>
+    );
+  }
+  return Icon;
+};
+
+/* GitHub Octicon paths — same set used by remark-github-blockquote-alert. */
+const ICONS: Readonly<Record<CalloutType, IconComponent>> = {
+  note: baseSvg(
+    'M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z',
+  ),
+  tip: baseSvg(
+    'M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z',
+  ),
+  important: baseSvg(
+    'M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z',
+  ),
+  warning: baseSvg(
+    'M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z',
+  ),
+  caution: baseSvg(
+    'M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z',
+  ),
+};

package/src/components/Callout/index.ts

@@ -0,0 +1 @@
+export { Callout, isCalloutType, type CalloutType } from './Callout';

package/src/components/CodeBlock/CodeBlock.module.css

@@ -0,0 +1,68 @@
+.figure {
+  margin: 0;
+  border: 1px solid var(--bg-stroke);
+  border-radius: var(--radius-md);
+  background-color: var(--bg-surface);
+  overflow: hidden;
+}
+
+[data-theme='dark'] .figure {
+  background-color: var(--bg-muted);
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-3);
+  padding: var(--space-2) var(--space-4);
+  border-bottom: 1px solid var(--bg-stroke);
+  background-color: var(--bg-subtle);
+}
+
+.language {
+  font-family: var(--font-mono), ui-monospace, monospace;
+  font-size: var(--font-size-xs);
+  font-weight: var(--font-weight-medium);
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--content-tertiary);
+}
+
+.copy {
+  font-family: var(--font-mono), ui-monospace, monospace;
+  font-size: var(--font-size-xs);
+  font-weight: var(--font-weight-medium);
+  color: var(--content-secondary);
+  background-color: transparent;
+  border: 1px solid var(--bg-stroke);
+  border-radius: var(--radius-sm);
+  padding: 3px 10px;
+  cursor: pointer;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  transition:
+    color 120ms ease,
+    border-color 120ms ease,
+    background-color 120ms ease;
+}
+
+.copy:hover {
+  color: var(--content-primary);
+  border-color: var(--bg-stroke-strong);
+  background-color: var(--bg-default);
+}
+
+.copy:focus-visible {
+  outline: 2px solid var(--accent-main);
+  outline-offset: 2px;
+}
+
+.copy[data-copied='true'] {
+  color: var(--accent-success);
+  border-color: var(--accent-success);
+}
+
+.body {
+  display: block;
+}

package/src/components/CodeBlock/CodeBlock.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+import { useEffect, useRef, useState, type ReactNode } from 'react';
+import { DEFAULT_LANG, type Lang } from '@/lib/lang';
+import { getDict } from '@/lib/i18n';
+import styles from './CodeBlock.module.css';
+
+const COPY_RESET_MS = 1500;
+
+type CodeBlockProps = {
+  language: string;
+  lang?: Lang;
+  children: ReactNode;
+};
+
+export function CodeBlock({ language, lang = DEFAULT_LANG, children }: CodeBlockProps) {
+  const t = getDict(lang);
+  const figureRef = useRef<HTMLElement>(null);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [copied, setCopied] = useState(false);
+
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    };
+  }, []);
+
+  const handleCopy = async () => {
+    const code = figureRef.current?.querySelector('pre code');
+    if (!code) return;
+    const text = code.textContent ?? '';
+    if (!text) return;
+    try {
+      await navigator.clipboard.writeText(text);
+    } catch {
+      return;
+    }
+    if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    setCopied(true);
+    timeoutRef.current = setTimeout(() => setCopied(false), COPY_RESET_MS);
+  };
+
+  return (
+    <figure
+      ref={figureRef}
+      className={styles.figure}
+      data-rehype-pretty-code-figure=""
+      data-language={language}
+    >
+      <header className={styles.header}>
+        <span className={styles.language}>{language}</span>
+        <button
+          type="button"
+          className={styles.copy}
+          data-copied={copied ? 'true' : 'false'}
+          onClick={handleCopy}
+          aria-label={copied ? t.codeBlockCopiedAriaLabel : t.codeBlockCopyAriaLabel}
+        >
+          {copied ? t.codeBlockCopied : t.codeBlockCopy}
+        </button>
+      </header>
+      <div className={styles.body}>{children}</div>
+    </figure>
+  );
+}

package/src/components/CodeBlock/index.ts

@@ -0,0 +1 @@
+export { CodeBlock } from './CodeBlock';

package/src/components/GateProvider/GateProvider.tsx

@@ -0,0 +1,207 @@
+'use client';
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react';
+import { usePathname } from 'next/navigation';
+import type { Course, FlatLessonEntry } from '@/lib/course';
+import { GATE_LOCKED_ATTR } from '@/lib/gate-init-script';
+import {
+  applyGatePainting,
+  GATE_ITEM_KEY_ATTR,
+  GATE_ITEM_LOCKED_ATTR,
+} from '@/lib/gate-mark-script';
+import { DEFAULT_LANG, stripLangFromPath } from '@/lib/lang';
+import { useProgressMode } from '@/components/ProgressModeProvider';
+import {
+  getFrontierLesson,
+  isLessonKeyUnlocked,
+  resolveFurthestIndex,
+} from '@/lib/lesson-gate';
+import {
+  FURTHEST_STORAGE_KEY,
+  getFurthestKey,
+  getProgress,
+  PROGRESS_CHANGE_EVENT,
+  PROGRESS_STORAGE_KEY,
+  type LessonKey,
+  type ProgressMap,
+} from '@/lib/progress';
+
+export type GateContextValue = {
+  course: Course;
+  basePath: string;
+  hydrated: boolean;
+  progress: ProgressMap;
+  furthestKey: LessonKey | null;
+  furthestIndex: number;
+  isLessonUnlocked(moduleId: string, slug: string): boolean;
+  getFrontier(): FlatLessonEntry | null;
+};
+
+export const GateContext = createContext<GateContextValue | null>(null);
+
+type GateProviderProps = {
+  course: Course;
+  basePath: string;
+  children: ReactNode;
+};
+
+export function GateProvider({ course, basePath, children }: GateProviderProps) {
+  const [hydrated, setHydrated] = useState(false);
+  const [progress, setProgress] = useState<ProgressMap>({});
+  const [furthestKey, setFurthestKeyState] = useState<LessonKey | null>(null);
+  const pathname = usePathname();
+  const { disabled } = useProgressMode();
+
+  useEffect(() => {
+    setProgress(getProgress());
+    setFurthestKeyState(getFurthestKey());
+    setHydrated(true);
+
+    function refresh() {
+      setProgress(getProgress());
+      setFurthestKeyState(getFurthestKey());
+    }
+    function syncStorage(e: StorageEvent) {
+      if (e.key !== PROGRESS_STORAGE_KEY && e.key !== FURTHEST_STORAGE_KEY) return;
+      refresh();
+    }
+    window.addEventListener(PROGRESS_CHANGE_EVENT, refresh);
+    window.addEventListener('storage', syncStorage);
+    return () => {
+      window.removeEventListener(PROGRESS_CHANGE_EVENT, refresh);
+      window.removeEventListener('storage', syncStorage);
+    };
+  }, []);
+
+  // The inline LANG_SYNC_SCRIPT in [lang]/layout fixes <html lang> for the
+  // very first paint, but client navigation between sibling /ru/ and /en/
+  // routes only re-renders the script element — browsers do not execute
+  // <script> tags inserted via DOM mutation, so the static `<html lang>`
+  // from the root layout would stay wrong for screen readers and Intl APIs
+  // after a language switch. Mirror the route lang from a client effect.
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const { lang } = stripLangFromPath(pathname ?? '/');
+    document.documentElement.lang = lang ?? DEFAULT_LANG;
+  }, [pathname]);
+
+  // Keep gate markers in sync with current state. Two attributes are
+  // managed here from a single source of truth (resolveFurthestIndex):
+  //   • `data-lesson-locked` on <html> — controls the lesson page gate.
+  //     The inline init script handles the very first paint on direct
+  //     navigation; this effect covers SPA route changes and cross-tab
+  //     localStorage updates.
+  //   • `data-locked` on every `[data-lesson-key]` element — controls
+  //     locked styling in lists (HomePage modules, ModulePage lessons,
+  //     ProgramDrawer, MDX cross-lesson links). The inline gate-mark
+  //     script sets these before first paint; this effect re-applies them
+  //     after React updates the DOM (e.g. drawer opening, route change
+  //     introducing new rows, cross-tab progress sync).
+  useEffect(() => {
+    if (!hydrated) return;
+    if (typeof document === 'undefined') return;
+    const root = document.documentElement;
+
+    // Free-reading mode: every lesson is reachable, so there is nothing to
+    // gate. Drop the page-level lock and skip painting entirely. We must also
+    // actively strip any residual markers gate-mark may have painted before the
+    // flag flipped (e.g. cross-tab sync or a route change). Besides the lock
+    // markers (whose styling the CSS hide-list doesn't cover for MDX cross-
+    // lesson links or ProgramDrawer rows), we also clear the completion markers
+    // `data-completed`/`data-next`: progress was just reset, and the CSS hide-
+    // list doesn't cover `[data-completed]`, so the "done" affordances
+    // (checkmark, strikethrough, ModulePage dimming, the "mark unread" button)
+    // would otherwise linger on already-painted rows.
+    if (disabled) {
+      root.removeAttribute(GATE_LOCKED_ATTR);
+      // `data-has-progress` is stamped on <html> by gate-mark; clear it so no
+      // residual progress-state lingers on the document root.
+      root.removeAttribute('data-has-progress');
+      document
+        .querySelectorAll<HTMLElement>(`[${GATE_ITEM_KEY_ATTR}]`)
+        .forEach((el) => {
+          el.removeAttribute(GATE_ITEM_LOCKED_ATTR);
+          el.removeAttribute('data-completed');
+          el.removeAttribute('data-next');
+          el.removeAttribute('aria-disabled');
+          el.removeAttribute('tabindex');
+        });
+      // CTA frontier rows are intentionally NOT hidden by the free-reading CSS
+      // (the plain "start" variant must stay visible). But gate-mark may have
+      // already painted `data-cta-state="in-progress"/"complete"` before the
+      // flag flipped (in-tab toggle or cross-tab sync), and nothing else resets
+      // it — so reset them to the SSR baseline so the right CTA variant shows
+      // without a reload.
+      document
+        .querySelectorAll<HTMLElement>('[data-cta-frontier]')
+        .forEach((el) => {
+          el.setAttribute('data-cta-state', 'not-started');
+        });
+      return;
+    }
+
+    const furthestIndex = resolveFurthestIndex(course, furthestKey, progress);
+
+    const { lang: parsedLang, rest } = stripLangFromPath(pathname ?? '/');
+    const segments = rest
+      .replace(/^\/+|\/+$/g, '')
+      .split('/')
+      .filter(Boolean);
+    if (segments.length < 2) {
+      root.removeAttribute(GATE_LOCKED_ATTR);
+    } else {
+      const [moduleId, slug] = segments;
+      const locked = !isLessonKeyUnlocked(course, moduleId, slug, furthestKey, progress);
+      if (locked) {
+        root.setAttribute(GATE_LOCKED_ATTR, 'true');
+      } else {
+        root.removeAttribute(GATE_LOCKED_ATTR);
+      }
+    }
+
+    applyGatePainting(course, furthestIndex, basePath, parsedLang ?? DEFAULT_LANG);
+  }, [hydrated, pathname, course, basePath, furthestKey, progress, disabled]);
+
+  const value = useMemo<GateContextValue>(() => {
+    const furthestIndex = resolveFurthestIndex(course, furthestKey, progress);
+    return {
+      course,
+      basePath,
+      hydrated,
+      progress,
+      furthestKey,
+      furthestIndex,
+      isLessonUnlocked(moduleId, slug) {
+        // Free-reading mode unlocks everything. Checked before `!hydrated`
+        // because `disabled` is seeded synchronously from the <html> attribute,
+        // so it is already correct during SSR/pre-hydration.
+        if (disabled) return true;
+        // Pre-hydration we cannot know what the user has unlocked — render
+        // everything as reachable so SSR matches and the user never sees a
+        // flash of locked items that immediately unlock on hydration.
+        if (!hydrated) return true;
+        return isLessonKeyUnlocked(course, moduleId, slug, furthestKey, progress);
+      },
+      getFrontier() {
+        return getFrontierLesson(course, furthestIndex);
+      },
+    };
+  }, [course, basePath, hydrated, progress, furthestKey, disabled]);
+
+  return <GateContext.Provider value={value}>{children}</GateContext.Provider>;
+}
+
+export function useGate(): GateContextValue {
+  const value = useContext(GateContext);
+  if (!value) {
+    throw new Error('useGate must be used within <GateProvider>');
+  }
+  return value;
+}

package/src/components/GateProvider/index.ts

@@ -0,0 +1 @@
+export { GateContext, GateProvider, useGate, type GateContextValue } from './GateProvider';

package/src/components/Header/Breadcrumbs.tsx

@@ -0,0 +1,50 @@
+import Link from 'next/link';
+import { DEFAULT_BRAND_NAME } from '@/lib/course';
+import type { Lang } from '@/lib/lang';
+import styles from './Header.module.css';
+
+type BreadcrumbsProps = {
+  lang: Lang;
+  moduleId?: string;
+  moduleTitle?: string;
+  lessonTitle?: string;
+  brandRoot?: string;
+};
+
+export function Breadcrumbs({
+  lang,
+  moduleId,
+  moduleTitle,
+  lessonTitle,
+  brandRoot = DEFAULT_BRAND_NAME,
+}: BreadcrumbsProps) {
+  if (!moduleId || !moduleTitle) {
+    return <span className={styles.breadcrumbRoot}>{brandRoot}</span>;
+  }
+
+  return (
+    <>
+      <Link href={`/${lang}`} className={styles.breadcrumbLink}>
+        {brandRoot}
+      </Link>
+      <span className={styles.breadcrumbSeparator} aria-hidden="true">
+        /
+      </span>
+      {lessonTitle ? (
+        <Link href={`/${lang}/${moduleId}`} className={styles.breadcrumbLink}>
+          {moduleTitle}
+        </Link>
+      ) : (
+        <span className={styles.breadcrumbCurrent}>{moduleTitle}</span>
+      )}
+      {lessonTitle && (
+        <>
+          <span className={styles.breadcrumbSeparator} aria-hidden="true">
+            /
+          </span>
+          <span className={styles.breadcrumbCurrent}>{lessonTitle}</span>
+        </>
+      )}
+    </>
+  );
+}