@dsbasko/cookbook-engine 0.1.0

package/src/pages/lesson.tsx

@@ -0,0 +1,260 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { LessonLockedInterstitial } from '@/components/LessonLockedInterstitial';
+import { LessonNav, type LessonNavLink } from '@/components/LessonNav';
+import { LessonPageLayout } from '@/components/LessonPageLayout';
+import { LessonSideMeta } from '@/components/LessonSideMeta';
+import { ReadingProgress } from '@/components/ReadingProgress';
+import { Toc } from '@/components/Toc';
+import { TranslationBanner } from '@/components/TranslationBanner';
+import {
+  findLesson,
+  flattenLessons,
+  getNextLesson,
+  getPrevLesson,
+  resolveBrandName,
+  type FlatLessonEntry,
+} from '@/lib/course';
+import { loadCourse } from '@/lib/course-loader';
+import { getDict } from '@/lib/i18n';
+import { isLang, LANGS, type Lang } from '@/lib/lang';
+import { getLessonContent } from '@/lib/lesson';
+import { renderLessonMarkdown } from '@/lib/markdown';
+import { extractDescription } from '@/lib/description';
+import { buildLessonLangMap } from '@/lib/sitemap';
+import { buildAssetUrl, buildSiteUrl, getRuntimeBasePath } from '@/lib/site-url';
+
+type LessonPageProps = {
+  params: { lang: string; module: string; lesson: string };
+};
+
+export function generateStaticParams(): Array<{
+  lang: Lang;
+  module: string;
+  lesson: string;
+}> {
+  // Pages are emitted for every (lang × module × lesson) triple — even when
+  // the EN translation is missing. The page renders with a fallback banner
+  // and noindex metadata in that case (see generateMetadata + render below).
+  const course = loadCourse('ru');
+  const lessonPairs = flattenLessons(course).map((entry) => ({
+    module: entry.moduleId,
+    lesson: entry.lesson.slug,
+  }));
+  return LANGS.flatMap((lang) =>
+    lessonPairs.map((pair) => ({ lang, ...pair })),
+  );
+}
+
+export async function generateMetadata({
+  params,
+}: LessonPageProps): Promise<Metadata> {
+  if (!isLang(params.lang)) return {};
+  const lang = params.lang as Lang;
+  const t = getDict(lang);
+  const course = loadCourse(lang);
+  const lesson = findLesson(course, params.module, params.lesson);
+  if (!lesson) {
+    return { title: `${t.notFoundTitle} · ${resolveBrandName(course)}` };
+  }
+
+  const courseDescription = course.description.replace(/\s+/g, ' ').trim();
+  let description = courseDescription;
+  let fallbackUsed = false;
+  try {
+    const content = await getLessonContent(params.module, params.lesson, lang);
+    fallbackUsed = content.fallbackUsed;
+    // When EN falls back to the RU README, the markdown is Russian — extracting
+    // a description from it would leak RU text into the EN page's <meta>. Keep
+    // the EN course-level description instead.
+    if (!fallbackUsed) {
+      description = extractDescription(content.markdown) ?? courseDescription;
+    }
+  } catch {
+    // metadata is best-effort; the page render will surface the real failure.
+  }
+
+  const title = `${lesson.title} · ${course.title}`;
+  const canonicalUrl = buildSiteUrl(course.basePath, [
+    lang,
+    params.module,
+    params.lesson,
+  ]);
+  const ogImage = {
+    url: buildAssetUrl(course.basePath, '/opengraph-image'),
+    width: 1200,
+    height: 630,
+    alt: course.brand?.ogImage?.alt ?? t.ogImageAlt,
+  };
+
+  // Determine EN translation presence independently of the route lang:
+  // `course.hasTranslation` only reflects whichever language the course was
+  // loaded with, but the hreflang map must always say whether the EN copy
+  // exists. On EN we already loaded it; on RU we re-resolve via loadCourse.
+  let hasEn: boolean;
+  if (lang === 'en') {
+    hasEn = !fallbackUsed;
+  } else {
+    const enCourse = loadCourse('en');
+    const enLesson = findLesson(enCourse, params.module, params.lesson);
+    hasEn = enLesson?.hasTranslation ?? false;
+  }
+  const languages = buildLessonLangMap(
+    course.basePath,
+    params.module,
+    params.lesson,
+    hasEn,
+  );
+
+  // EN page falling back to RU content — withhold from search and point the
+  // canonical at the actual RU URL so search engines don't index a duplicate
+  // under the wrong language. Still emit a full openGraph block: without it
+  // social-share unfurls inherit root-layout defaults (og:url=/en/,
+  // og:type=website), which gives misleading previews even though crawlers
+  // honour the noindex.
+  if (lang === 'en' && fallbackUsed) {
+    const ruCanonical = buildSiteUrl(course.basePath, [
+      'ru',
+      params.module,
+      params.lesson,
+    ]);
+    return {
+      title,
+      description,
+      alternates: { canonical: ruCanonical, languages },
+      robots: { index: false, follow: true },
+      openGraph: {
+        type: 'article',
+        siteName: course.title,
+        title,
+        description,
+        url: ruCanonical,
+        locale: 'ru_RU',
+        images: [ogImage],
+      },
+      twitter: {
+        card: 'summary_large_image',
+        title,
+        description,
+        images: [ogImage.url],
+      },
+    };
+  }
+
+  return {
+    title,
+    description,
+    alternates: { canonical: canonicalUrl, languages },
+    openGraph: {
+      type: 'article',
+      siteName: course.title,
+      title,
+      description,
+      url: canonicalUrl,
+      locale: lang === 'ru' ? 'ru_RU' : 'en_US',
+      images: [ogImage],
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title,
+      description,
+      images: [ogImage.url],
+    },
+  };
+}
+
+export default async function LessonPage({ params }: LessonPageProps) {
+  if (!isLang(params.lang)) notFound();
+  const lang = params.lang as Lang;
+  const course = loadCourse(lang);
+  const lesson = findLesson(course, params.module, params.lesson);
+  if (!lesson) {
+    notFound();
+  }
+
+  const { markdown, lang: contentLang, fallbackUsed } = await getLessonContent(
+    params.module,
+    params.lesson,
+    lang,
+  );
+  const { content, toc } = await renderLessonMarkdown(markdown, {
+    moduleId: params.module,
+    slug: params.lesson,
+    basePath: getRuntimeBasePath(course.basePath),
+    course,
+    // Keep emitting `/<route-lang>/` URLs so an EN reader who clicks a sibling
+    // link inside fallback RU content stays on EN routes (and gets the same
+    // fallback banner there). `sourceLang` follows the README we actually
+    // loaded so relative paths are anchored at `i18n/<source>/`.
+    lang,
+    sourceLang: contentLang,
+  });
+
+  const prev = toNavLink(getPrevLesson(course, params.module, params.lesson));
+  const next = toNavLink(getNextLesson(course, params.module, params.lesson));
+
+  const currentModule = course.modules.find((m) => m.id === params.module);
+  const moduleIndex = currentModule
+    ? course.modules.findIndex((m) => m.id === currentModule.id) + 1
+    : 0;
+
+  // Both branches render side-by-side. CSS toggles their visibility via the
+  // `data-lesson-locked` attribute on <html>, which the inline gate-init
+  // script stamps synchronously before <body> is parsed (no flash) and which
+  // GateProvider keeps in sync on the client (route changes, cross-tab
+  // localStorage updates).
+  return (
+    <>
+      <div data-lesson-body>
+        <ReadingProgress />
+        <LessonPageLayout
+          lang={lang}
+          title={lesson.title}
+          tocSlot={<Toc entries={toc} />}
+          sideMetaSlot={
+            currentModule ? (
+              <LessonSideMeta
+                moduleId={currentModule.id}
+                moduleTitle={currentModule.title}
+                moduleIndex={moduleIndex}
+                slug={params.lesson}
+                duration={lesson.duration}
+                tags={lesson.tags}
+              />
+            ) : null
+          }
+          footer={
+            <LessonNav
+              prev={prev}
+              next={next}
+              currentModuleId={params.module}
+              currentSlug={params.lesson}
+            />
+          }
+        >
+          <article className="markdown" data-translation-fallback={fallbackUsed ? 'true' : 'false'}>
+            {lang === 'en' && fallbackUsed ? (
+              <TranslationBanner lang={lang} />
+            ) : null}
+            {content}
+          </article>
+        </LessonPageLayout>
+      </div>
+      <div data-lesson-gate>
+        <LessonLockedInterstitial
+          attemptedModuleId={params.module}
+          attemptedSlug={params.lesson}
+        />
+      </div>
+    </>
+  );
+}
+
+function toNavLink(entry: FlatLessonEntry | null): LessonNavLink | null {
+  if (!entry) return null;
+  return {
+    moduleId: entry.moduleId,
+    slug: entry.lesson.slug,
+    title: entry.lesson.title,
+  };
+}

package/src/pages/module.tsx

@@ -0,0 +1,80 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { ModulePage } from '@/components/ModulePage';
+import { resolveBrandLevel, resolveBrandName } from '@/lib/course';
+import { loadCourse } from '@/lib/course-loader';
+import { getDict } from '@/lib/i18n';
+import { isLang, LANGS, type Lang } from '@/lib/lang';
+import { buildLangMap } from '@/lib/sitemap';
+import { buildAssetUrl, buildSiteUrl } from '@/lib/site-url';
+
+type ModulePageProps = {
+  params: { lang: string; module: string };
+};
+
+export function generateStaticParams(): Array<{ lang: Lang; module: string }> {
+  // Module set is shared across languages (titles differ, ids don't), so
+  // re-loading per lang is wasteful — parse once and fan out.
+  const course = loadCourse('ru');
+  const moduleIds = course.modules.map((m) => m.id);
+  return LANGS.flatMap((lang) =>
+    moduleIds.map((module) => ({ lang, module })),
+  );
+}
+
+export function generateMetadata({ params }: ModulePageProps): Metadata {
+  if (!isLang(params.lang)) return {};
+  const lang = params.lang as Lang;
+  const t = getDict(lang);
+  const course = loadCourse(lang);
+  const mod = course.modules.find((m) => m.id === params.module);
+  if (!mod) {
+    return { title: `${t.notFoundTitle} · ${resolveBrandName(course)}` };
+  }
+  const description = collapseWhitespace(mod.description);
+  const title = `${mod.title} · ${course.title}`;
+  const url = buildSiteUrl(course.basePath, [lang, mod.id]);
+  const ogImage = {
+    url: buildAssetUrl(course.basePath, '/opengraph-image'),
+    width: 1200,
+    height: 630,
+    alt: course.brand?.ogImage?.alt ?? t.ogImageAlt,
+  };
+  // See note in `home.tsx`: `alternates` from the root layout is
+  // overridden, not merged, so we have to re-emit the hreflang map.
+  const languages = buildLangMap(course.basePath, [mod.id]);
+  return {
+    title,
+    description,
+    alternates: { canonical: url, languages },
+    openGraph: {
+      type: 'article',
+      siteName: course.title,
+      title,
+      description,
+      url,
+      locale: lang === 'ru' ? 'ru_RU' : 'en_US',
+      images: [ogImage],
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title,
+      description,
+      images: [ogImage.url],
+    },
+  };
+}
+
+export default function ModuleRoute({ params }: ModulePageProps) {
+  if (!isLang(params.lang)) notFound();
+  const course = loadCourse(params.lang as Lang);
+  const mod = course.modules.find((m) => m.id === params.module);
+  if (!mod) {
+    notFound();
+  }
+  return <ModulePage course={course} module={mod} level={resolveBrandLevel(course)} />;
+}
+
+function collapseWhitespace(text: string): string {
+  return text.replace(/\s+/g, ' ').trim();
+}

package/src/pages/not-found-lang.tsx

@@ -0,0 +1,51 @@
+'use client';
+
+import Link from 'next/link';
+import { useLang, useT } from '@/lib/use-i18n';
+
+export default function NotFound() {
+  const t = useT();
+  const lang = useLang();
+  return (
+    <main
+      style={{
+        maxWidth: 'var(--layout-content-max)',
+        margin: '0 auto',
+        padding: 'var(--space-12) var(--space-6)',
+        textAlign: 'center',
+      }}
+    >
+      <h1
+        style={{
+          fontSize: 'var(--font-size-3xl)',
+          fontWeight: 'var(--font-weight-bold)',
+          marginBottom: 'var(--space-4)',
+        }}
+      >
+        {t.notFoundTitle}
+      </h1>
+      <p
+        style={{
+          fontSize: 'var(--font-size-lg)',
+          color: 'var(--content-secondary)',
+          marginBottom: 'var(--space-6)',
+        }}
+      >
+        {t.notFoundDesc}
+      </p>
+      <Link
+        href={`/${lang}`}
+        style={{
+          display: 'inline-block',
+          padding: 'var(--space-3) var(--space-6)',
+          borderRadius: 'var(--radius-md)',
+          backgroundColor: 'var(--accent-main)',
+          color: 'var(--content-inverse)',
+          fontWeight: 'var(--font-weight-semibold)',
+        }}
+      >
+        {t.goHome}
+      </Link>
+    </main>
+  );
+}

package/src/pages/not-found-root.tsx

@@ -0,0 +1,48 @@
+import Link from 'next/link';
+
+// Root not-found is the fallback used when no lang segment matches. Always
+// rendered in DEFAULT_LANG; per-lang copies live at `not-found-lang.tsx`.
+export default function NotFound() {
+  return (
+    <main
+      style={{
+        maxWidth: 'var(--layout-content-max)',
+        margin: '0 auto',
+        padding: 'var(--space-12) var(--space-6)',
+        textAlign: 'center',
+      }}
+    >
+      <h1
+        style={{
+          fontSize: 'var(--font-size-3xl)',
+          fontWeight: 'var(--font-weight-bold)',
+          marginBottom: 'var(--space-4)',
+        }}
+      >
+        Page not found
+      </h1>
+      <p
+        style={{
+          fontSize: 'var(--font-size-lg)',
+          color: 'var(--content-secondary)',
+          marginBottom: 'var(--space-6)',
+        }}
+      >
+        That lesson is not part of the course. Head back to the home page.
+      </p>
+      <Link
+        href="/"
+        style={{
+          display: 'inline-block',
+          padding: 'var(--space-3) var(--space-6)',
+          borderRadius: 'var(--radius-md)',
+          backgroundColor: 'var(--accent-main)',
+          color: 'var(--content-inverse)',
+          fontWeight: 'var(--font-weight-semibold)',
+        }}
+      >
+        Go home
+      </Link>
+    </main>
+  );
+}

package/src/pages/root.tsx

@@ -0,0 +1,44 @@
+import { AppShell } from '@/components/AppShell';
+import { GateProvider } from '@/components/GateProvider';
+import { HomePage } from '@/components/HomePage';
+import { resolveBrandLevel } from '@/lib/course';
+import { loadCourse } from '@/lib/course-loader';
+import { DEFAULT_LANG, LANG_INIT_SCRIPT, LANG_LABELS, LANGS } from '@/lib/lang';
+import { buildSiteUrl, getRuntimeBasePath } from '@/lib/site-url';
+
+export default function RootPage() {
+  // Static `/index.html` always serves the default-language HomePage. Visitors
+  // whose stored or browser language differs are redirected client-side by
+  // LANG_INIT_SCRIPT to `/{lang}/`. <noscript> ships explicit per-lang links so
+  // users without JS can still pick a language.
+  const course = loadCourse(DEFAULT_LANG);
+  const basePath = getRuntimeBasePath(course.basePath);
+
+  return (
+    <>
+      <script
+        id="lang-init"
+        // Renders as the first body child. Before the rest of the body paints,
+        // it redirects to `/{lang}/` when the resolved language differs from
+        // DEFAULT_LANG — at worst the user sees a brief background flash before
+        // the new page loads.
+        dangerouslySetInnerHTML={{ __html: LANG_INIT_SCRIPT }}
+      />
+      <GateProvider course={course} basePath={basePath}>
+        <AppShell course={course}>
+          <HomePage course={course} level={resolveBrandLevel(course)} />
+        </AppShell>
+      </GateProvider>
+      <noscript>
+        <p>Choose your language / Выберите язык:</p>
+        <ul>
+          {LANGS.map((lang) => (
+            <li key={lang}>
+              <a href={buildSiteUrl(course.basePath, [lang])}>{LANG_LABELS[lang]}</a>
+            </li>
+          ))}
+        </ul>
+      </noscript>
+    </>
+  );
+}

package/src/seo/robots.ts

@@ -0,0 +1,16 @@
+import type { MetadataRoute } from 'next';
+import { loadCourse } from '@/lib/course-loader';
+import { buildSiteUrl } from '@/lib/site-url';
+
+export default function robots(): MetadataRoute.Robots {
+  const course = loadCourse('ru');
+  return {
+    rules: [
+      {
+        userAgent: '*',
+        allow: '/',
+      },
+    ],
+    sitemap: `${buildSiteUrl(course.basePath)}sitemap.xml`,
+  };
+}

package/src/seo/sitemap.ts

@@ -0,0 +1,10 @@
+import type { MetadataRoute } from 'next';
+import { loadCourse } from '@/lib/course-loader';
+import { buildSitemap } from '@/lib/sitemap';
+
+// Load with `'en'` so `lesson.hasTranslation` reflects the EN README — the
+// sitemap uses that flag to skip /en/<m>/<l> entries for untranslated lessons.
+// Titles aren't needed here, so RU vs EN resolution of strings doesn't matter.
+export default function sitemap(): MetadataRoute.Sitemap {
+  return buildSitemap(loadCourse('en'));
+}

package/src/styles/globals.css

@@ -0,0 +1,139 @@
+@import './tokens.css';
+@import './reset.css';
+@import './markdown.css';
+
+html {
+  font-family: var(--font-ui), -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui,
+    sans-serif;
+  font-size: var(--font-size-md);
+  color-scheme: light dark;
+  /* iOS Safari paints the area above the layout viewport (under the URL bar
+     chip and inside the rubber-band overscroll) with the <html> background,
+     not <body>. Without this, that area falls back to a default dark colour
+     and the FAB halos appear to clip at the top edge of the page. */
+  background-color: var(--bg-default);
+}
+
+body {
+  background-color: var(--bg-default);
+  color: var(--content-primary);
+  font-size: var(--font-size-md);
+  line-height: var(--line-height-normal);
+  transition:
+    background-color 120ms ease,
+    color 120ms ease;
+}
+
+a {
+  color: var(--content-link);
+  text-decoration: none;
+  transition: color 120ms ease;
+}
+
+a:hover {
+  color: var(--content-link-hover);
+}
+
+a:focus-visible,
+button:focus-visible,
+[tabindex]:focus-visible {
+  outline: 2px solid var(--accent-main);
+  outline-offset: 2px;
+  border-radius: var(--radius-sm);
+}
+
+::selection {
+  background-color: var(--accent-main-soft);
+  color: var(--content-primary);
+}
+
+code,
+kbd,
+samp,
+pre {
+  font-family: var(--font-mono), ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace;
+}
+
+/* Lesson gate: the lesson page renders both the lesson body and the locked
+   interstitial side-by-side; visibility is toggled via the data attribute
+   on <html>. The attribute is set synchronously by the gate-init inline
+   script before <body> parses (no flash on direct navigation) and kept in
+   sync on the client by GateProvider (SPA route changes, cross-tab
+   localStorage updates). Default state hides the gate. */
+[data-lesson-gate] {
+  display: none;
+}
+
+html[data-lesson-locked='true'] [data-lesson-body] {
+  display: none;
+}
+
+html[data-lesson-locked='true'] [data-lesson-gate] {
+  display: block;
+}
+
+/* Cross-lesson links inside MDX prose: the inline gate-mark script flips
+   `data-locked` on any `<a>` whose `data-lesson-key` points at a still-
+   locked lesson. Visual is global because the selector targets a bare
+   attribute pattern that CSS Modules forbids; the trailing lock badge is
+   a local class on the link (see LessonAwareLink.module.css).
+   `cursor: not-allowed` signals the disabled state on hover; actual click
+   blocking is handled by the JS preventDefault in LessonAwareLink and
+   `tabindex=-1` / `aria-disabled` stamped by the gate-mark script. */
+a[data-lesson-key][data-locked='true'],
+.markdown a[data-lesson-key][data-locked='true'] {
+  color: var(--content-tertiary);
+  font-weight: var(--font-weight-semibold);
+  text-decoration: underline dotted;
+  text-decoration-color: var(--content-tertiary);
+  text-underline-offset: 3px;
+  text-decoration-thickness: 1px;
+  cursor: not-allowed;
+}
+
+a[data-lesson-key][data-locked='true']:hover {
+  color: var(--content-tertiary);
+}
+
+a[data-lesson-key][data-locked='true'] [data-lock-badge] {
+  display: inline-flex;
+}
+
+/* Free-reading mode: the progress-mode-init inline script stamps
+   `data-progress-disabled="true"` on <html> synchronously (before first paint),
+   so these rules hide every progress-gamification widget without a flash. We key
+   on the stable `data-progress-*` hooks rather than hashed CSS-module class names.
+
+   Scoping caveats (verified against the real components):
+   - The header course bar is `[data-progress-scope][role='progressbar']`. We must
+     NOT hide bare `[role='progressbar']` — ReadingProgress (scroll position) reuses
+     that role and stays visible in free-reading mode.
+   - Standalone stats cards are `aside[data-progress-scope]` (HomePage hero aside,
+     ModulePage side card). We must NOT hide bare `[data-progress-scope]` — HomePage
+     module rows are `<a data-progress-scope="module">` navigation and must stay.
+   - The per-module progress meter inside those navigation rows is wrapped in
+     `[data-module-progress]`, so we hide that whole block (status label, count,
+     and bar together) while the row itself stays navigable. Hiding only the
+     granular count/bar slots would leave the bare "/N" text, the "not started"
+     label, and the empty bar track visible.
+   - The granular `[data-progress-count]`/`[data-progress-pct]`/`[data-progress-bar]`
+     slots are still hidden directly for progress widgets that live outside a
+     module row (e.g. the header bar).
+   - The ProgramDrawer per-module done/total pill is `[data-module-badge]`. It is
+     a React-rendered "N/M" counter (not a paint-script slot), so it needs its own
+     hook to stay hidden in free-reading mode.
+   - CTA frontier rows are left alone: without gate-paint they keep their SSR
+     `data-cta-state="not-started"` baseline, so only the plain "start" variant shows
+     (the "continue/reread" progress variants stay hidden) and the Program button stays.
+   - The locked interstitial needs no rule here — it's already hidden by the gate CSS
+     above once `data-lesson-locked` is cleared. */
+html[data-progress-disabled='true'] [data-progress-scope][role='progressbar'],
+html[data-progress-disabled='true'] aside[data-progress-scope],
+html[data-progress-disabled='true'] [data-module-progress],
+html[data-progress-disabled='true'] [data-frontier-hint],
+html[data-progress-disabled='true'] [data-progress-count],
+html[data-progress-disabled='true'] [data-progress-pct],
+html[data-progress-disabled='true'] [data-progress-bar],
+html[data-progress-disabled='true'] [data-module-badge] {
+  display: none;
+}