@dsbasko/cookbook-engine 0.1.0

package/src/config.d.mts

@@ -0,0 +1,12 @@
+import type { NextConfig } from 'next';
+
+/**
+ * Builds the Next.js config for a cookbook course consumer. Reads `course.yaml`
+ * (via process.cwd()) for `basePath`, enables the static export pipeline, wires
+ * `transpilePackages` for the engine, and injects `course.brand.siteUrl` into
+ * `env.NEXT_PUBLIC_SITE_URL` at build time when present.
+ */
+export function createCookbookConfig(overrides?: NextConfig): NextConfig;
+
+declare const _default: typeof createCookbookConfig;
+export default _default;

package/src/config.mjs

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
+
+const PACKAGE_NAME = '@dsbasko/cookbook-engine';
+
+// Absolute path to the engine's own `src/` dir. This file lives at
+// `<engineRoot>/src/config.mjs`, so dirname(import.meta.url) IS that dir even
+// when the engine is installed under the consumer's node_modules. Note the
+// asymmetry with course.yaml resolution: course.yaml MUST come from the
+// consumer (process.cwd()), but the engine's source is resolved relative to the
+// engine itself — that is exactly what import.meta.url gives here.
+const ENGINE_SRC = path.dirname(fileURLToPath(import.meta.url));
+
+// Resolve the consumer's course.yaml relative to process.cwd() — NEVER via
+// import.meta.url/__dirname. The engine lives in node_modules, so a __dirname
+// probe would point inside the package and the build would crash at startup
+// (see plan Task 0b verdict). The consumer runs `next build` from web/, so we
+// probe both CWD=repo-root (`./course.yaml`) and CWD=web/ (`../course.yaml`),
+// matching the candidate lists in lib/course-loader.ts.
+function resolveCourseYamlPath() {
+  const candidates = [
+    path.resolve(process.cwd(), 'course.yaml'),
+    path.resolve(process.cwd(), '..', 'course.yaml'),
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return candidates[0];
+}
+
+function readCourse() {
+  const courseYamlPath = resolveCourseYamlPath();
+  const course = yaml.load(readFileSync(courseYamlPath, 'utf8'));
+  if (!course || typeof course.basePath !== 'string' || !course.basePath.startsWith('/')) {
+    throw new Error(
+      `createCookbookConfig: course.yaml at ${courseYamlPath} must define a basePath string starting with '/'`,
+    );
+  }
+  return course;
+}
+
+/**
+ * Builds the Next.js config for a cookbook course consumer.
+ *
+ * Reads `course.yaml` (via process.cwd()) for `basePath`, enables the static
+ * export pipeline, wires `transpilePackages` for the engine, and — when
+ * `course.brand.siteUrl` is set — injects it into `env.NEXT_PUBLIC_SITE_URL`
+ * at build time so the client-only `getSiteUrl()` stays env-based.
+ *
+ * @param {import('next').NextConfig} [overrides] shallow-merged over the base config.
+ * @returns {import('next').NextConfig}
+ */
+export function createCookbookConfig(overrides = {}) {
+  const course = readCourse();
+  const coursePath = course.basePath;
+  const isProd = process.env.NODE_ENV === 'production';
+
+  // brand.siteUrl is sugar over NEXT_PUBLIC_SITE_URL: surface it at build time
+  // so the client bundle inlines it. An explicit env var still wins.
+  const siteUrl =
+    course.brand && typeof course.brand.siteUrl === 'string' && course.brand.siteUrl.trim().length > 0
+      ? course.brand.siteUrl.trim()
+      : undefined;
+  const env = {
+    ...(siteUrl && !process.env.NEXT_PUBLIC_SITE_URL ? { NEXT_PUBLIC_SITE_URL: siteUrl } : {}),
+    ...(overrides.env ?? {}),
+  };
+
+  // The engine source uses the `@/*` path alias internally (TS-only). Under
+  // transpilePackages the consumer's webpack compiles those files, so it must
+  // resolve `@/foo` to the engine's own src — otherwise every engine import
+  // fails with "Module not found". The consumer apps are thin re-export
+  // wrappers with no `@/` imports of their own, so this global alias is safe.
+  const userWebpack = typeof overrides.webpack === 'function' ? overrides.webpack : undefined;
+  /** @type {NonNullable<import('next').NextConfig['webpack']>} */
+  const webpack = (config, context) => {
+    config.resolve = config.resolve ?? {};
+    config.resolve.alias = { ...(config.resolve.alias ?? {}), '@': ENGINE_SRC };
+    return userWebpack ? userWebpack(config, context) : config;
+  };
+
+  /** @type {import('next').NextConfig} */
+  const base = {
+    output: 'export',
+    basePath: isProd ? coursePath : '',
+    assetPrefix: isProd ? `${coursePath}/` : undefined,
+    trailingSlash: true,
+    images: { unoptimized: true },
+    reactStrictMode: true,
+    transpilePackages: [PACKAGE_NAME],
+    webpack,
+    experimental: {
+      typedRoutes: true,
+      ...(overrides.experimental ?? {}),
+    },
+    ...(Object.keys(env).length > 0 ? { env } : {}),
+  };
+
+  const {
+    experimental: _experimental,
+    env: _env,
+    webpack: _webpack,
+    ...restOverrides
+  } = overrides;
+  return { ...base, ...restOverrides };
+}
+
+export default createCookbookConfig;

package/src/index.ts

@@ -0,0 +1,62 @@
+// Public barrel for @dsbasko/cookbook-engine.
+//
+// Course consumers normally use the dedicated entry-points
+// (`/config`, `/layout/*`, `/pages/*`, `/og/*`, `/seo/*`, `/styles/*`). This
+// barrel is the escape hatch for advanced cases: composing custom layouts or
+// pages on top of the engine's components and lib helpers.
+
+export const ENGINE_PACKAGE_NAME = '@dsbasko/cookbook-engine';
+
+// --- lib: course model + loading -------------------------------------------
+export * from './lib/course';
+export * from './lib/course-loader';
+export * from './lib/lesson';
+export * from './lib/lang';
+export * from './lib/use-i18n';
+export * from './lib/i18n';
+
+// --- lib: content rendering -------------------------------------------------
+export * from './lib/markdown';
+export * from './lib/extract-toc';
+export * from './lib/readme-toc';
+export * from './lib/slug';
+export * from './lib/format';
+export * from './lib/description';
+export * from './lib/frontier-link';
+
+// --- lib: client state (theme / progress / reading prefs / gating) ----------
+export * from './lib/theme';
+export * from './lib/progress';
+export * from './lib/progress-mode';
+export * from './lib/reading-prefs';
+export * from './lib/lesson-gate';
+export * from './lib/program-drawer';
+
+// --- lib: SEO ---------------------------------------------------------------
+export * from './lib/site-url';
+export * from './lib/sitemap';
+
+// --- components -------------------------------------------------------------
+export { AppShell } from './components/AppShell';
+export { Header } from './components/Header';
+export { Sidebar } from './components/Sidebar';
+export { HomePage } from './components/HomePage';
+export { ModulePage } from './components/ModulePage';
+export { Toc } from './components/Toc';
+export { CodeBlock } from './components/CodeBlock';
+export { Callout } from './components/Callout';
+export { LessonNav } from './components/LessonNav';
+export { LessonLayout } from './components/LessonLayout';
+export { LessonPageLayout } from './components/LessonPageLayout';
+export { LessonSideMeta } from './components/LessonSideMeta';
+export { LessonAwareLink } from './components/LessonAwareLink';
+export { LessonLockedInterstitial } from './components/LessonLockedInterstitial';
+export { ProgramDrawer } from './components/ProgramDrawer';
+export { ProgressBar } from './components/ProgressBar';
+export { ReadingProgress } from './components/ReadingProgress';
+export { SettingsToggle } from './components/SettingsToggle';
+export { TranslationBanner } from './components/TranslationBanner';
+export { GateProvider } from './components/GateProvider';
+export { ThemeProvider } from './components/ThemeProvider';
+export { ProgressModeProvider } from './components/ProgressModeProvider';
+export { ReadingPrefsProvider } from './components/ReadingPrefsProvider';

package/src/layout/lang.tsx

@@ -0,0 +1,44 @@
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { AppShell } from '@/components/AppShell';
+import { GateProvider } from '@/components/GateProvider';
+import { loadCourse } from '@/lib/course-loader';
+import { isLang, LANG_SYNC_SCRIPT, LANGS, type Lang } from '@/lib/lang';
+import { getRuntimeBasePath } from '@/lib/site-url';
+
+type LangLayoutProps = {
+  children: React.ReactNode;
+  params: { lang: string };
+};
+
+export function generateStaticParams(): Array<{ lang: Lang }> {
+  return LANGS.map((lang) => ({ lang }));
+}
+
+export function generateMetadata({ params }: LangLayoutProps): Metadata {
+  if (!isLang(params.lang)) return {};
+  // The static HTML on disk always carries `<html lang={DEFAULT_LANG}>` because
+  // Next renders <html> once at the root layout. `content-language` is the
+  // per-lang signal crawlers read instead.
+  return { other: { 'content-language': params.lang } };
+}
+
+export default function LangLayout({ children, params }: LangLayoutProps) {
+  if (!isLang(params.lang)) notFound();
+  const lang = params.lang as Lang;
+  const course = loadCourse(lang);
+  const basePath = getRuntimeBasePath(course.basePath);
+
+  return (
+    <GateProvider course={course} basePath={basePath}>
+      <AppShell course={course}>{children}</AppShell>
+      <script
+        // Static HTML always carries `<html lang={DEFAULT_LANG}>`. Sync it to
+        // the active route so in-browser APIs (Intl, screen readers) see the
+        // correct value the moment this subtree mounts.
+        id={`lang-sync-${lang}`}
+        dangerouslySetInnerHTML={{ __html: LANG_SYNC_SCRIPT(lang) }}
+      />
+    </GateProvider>
+  );
+}

package/src/layout/root.tsx

@@ -0,0 +1,223 @@
+import type { Metadata, Viewport } from 'next';
+import { Fira_Code, Inter, Literata, Manrope, Roboto_Slab } from 'next/font/google';
+import localFont from 'next/font/local';
+import { ProgressModeProvider } from '@/components/ProgressModeProvider';
+import { ReadingPrefsProvider } from '@/components/ReadingPrefsProvider';
+import { ThemeProvider } from '@/components/ThemeProvider';
+import { buildBrandAccentCss, type Course } from '@/lib/course';
+import { loadCourse } from '@/lib/course-loader';
+import { buildGateInitScript } from '@/lib/gate-init-script';
+import { buildGateMarkScript } from '@/lib/gate-mark-script';
+import { DEFAULT_LANG, LANGS, type Lang } from '@/lib/lang';
+import { PROGRESS_MODE_INIT_SCRIPT } from '@/lib/progress-mode';
+import { READING_PREFS_INIT_SCRIPT } from '@/lib/reading-prefs';
+import { buildSiteUrl, getRuntimeBasePath, getSiteUrl } from '@/lib/site-url';
+import { THEME_INIT_SCRIPT } from '@/lib/theme';
+import '@/styles/globals.css';
+
+const manrope = Manrope({
+  subsets: ['latin', 'cyrillic'],
+  display: 'swap',
+  variable: '--font-ui',
+});
+
+// Self-hosted JetBrains Mono with full glyph coverage (incl. Box Drawing U+2500–U+257F),
+// avoids Google Fonts' subset split that breaks ASCII-art alignment.
+// Fonts ship inside the package (assets/fonts/); relative paths resolve from
+// node_modules via the consumer's transpilePackages (verified in spike 0a).
+const jetbrains = localFont({
+  variable: '--font-mono',
+  display: 'swap',
+  src: [
+    { path: '../../assets/fonts/jetbrains-mono/JetBrainsMono-Regular.woff2', weight: '400', style: 'normal' },
+    { path: '../../assets/fonts/jetbrains-mono/JetBrainsMono-Italic.woff2', weight: '400', style: 'italic' },
+    { path: '../../assets/fonts/jetbrains-mono/JetBrainsMono-Medium.woff2', weight: '500', style: 'normal' },
+    { path: '../../assets/fonts/jetbrains-mono/JetBrainsMono-SemiBold.woff2', weight: '600', style: 'normal' },
+    { path: '../../assets/fonts/jetbrains-mono/JetBrainsMono-Bold.woff2', weight: '700', style: 'normal' },
+    { path: '../../assets/fonts/jetbrains-mono/JetBrainsMono-BoldItalic.woff2', weight: '700', style: 'italic' },
+  ],
+});
+
+// Literata is the default prose face — designed by TypeTogether for Google Play
+// Books, tuned for long-form on-screen reading (low stroke contrast, sturdy
+// serifs, near-upright italic that holds the pixel grid).
+const literataProse = Literata({
+  subsets: ['latin', 'cyrillic'],
+  weight: ['400', '500', '600', '700'],
+  style: ['normal', 'italic'],
+  display: 'swap',
+  variable: '--font-serif',
+});
+
+// Optional reading-prefs fonts. Weights are pinned explicitly so next/font does
+// not pull the full axis (cyrillic subsets balloon otherwise). Only the CSS
+// variable is exposed; the actual font kicks in once the user picks the
+// matching prose/code option in <SettingsToggle>.
+const interProse = Inter({
+  subsets: ['latin', 'cyrillic'],
+  weight: ['400', '500', '600', '700'],
+  style: ['normal'],
+  display: 'swap',
+  variable: '--font-prose-inter',
+});
+
+// Roboto Slab provides the "slab" universe — third prose option. It has no
+// true italic, so reserve it for accent/short-form blocks (see slab.css).
+const robotoSlab = Roboto_Slab({
+  subsets: ['latin', 'cyrillic'],
+  weight: ['400', '500', '600', '700'],
+  style: ['normal'],
+  display: 'swap',
+  variable: '--font-prose-slab',
+});
+
+const firaCode = Fira_Code({
+  subsets: ['latin', 'cyrillic'],
+  weight: ['400', '500', '700'],
+  style: ['normal'],
+  display: 'swap',
+  variable: '--font-code-fira',
+});
+
+export function generateMetadata(): Metadata {
+  // The root layout is the SEO entry point. Default-language content lives at
+  // `/` (this layout's child), with `/{ru,en}/` mirrors under [lang]/. The
+  // canonical points at the default-lang URL and `alternates.languages` lets
+  // crawlers discover the per-lang copies.
+  const course = loadCourse(DEFAULT_LANG);
+  // course.yaml owns the per-lang description; loadCourse(DEFAULT_LANG) has
+  // already resolved the right side of the `{ ru, en }` map. Normalize
+  // whitespace so multi-line YAML scalars render as a single sentence.
+  const description = course.description.replace(/\s+/g, ' ').trim();
+  const canonical = buildSiteUrl(course.basePath, [DEFAULT_LANG]);
+  const languages: Record<string, string> = {
+    'x-default': canonical,
+  };
+  for (const lang of LANGS) {
+    languages[lang] = buildSiteUrl(course.basePath, [lang]);
+  }
+  return {
+    metadataBase: new URL(getSiteUrl()),
+    title: course.title,
+    description,
+    alternates: { canonical, languages },
+    openGraph: {
+      type: 'website',
+      siteName: course.title,
+      title: course.title,
+      description,
+      url: canonical,
+      locale: DEFAULT_LANG === 'ru' ? 'ru_RU' : 'en_US',
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title: course.title,
+      description,
+    },
+  };
+}
+
+// `viewportFit: 'cover'` extends the layout viewport across the entire
+// physical screen on iOS (under the notch / status bar / home indicator)
+// instead of clipping at the safe-area edges. Two side-effects we need:
+//   1. env(safe-area-inset-*) returns real pixel values (≈47px top on
+//      notched devices) so the sidebar padding pushes FABs below the notch.
+//   2. box-shadow on `position: fixed; top: 0` elements can finally render
+//      ABOVE the FAB into the now-paintable status-bar zone instead of
+//      hitting a hard clip at the layout-viewport edge.
+// `themeColor` then matches Safari chrome (status bar + URL chip) to
+// --bg-default so the chrome reads as part of the page. Paper mode is a
+// manual user choice and falls under the light branch — close enough in hue.
+export const viewport: Viewport = {
+  width: 'device-width',
+  initialScale: 1,
+  viewportFit: 'cover',
+  themeColor: [
+    { media: '(prefers-color-scheme: light)', color: '#faf7f2' },
+    { media: '(prefers-color-scheme: dark)', color: '#16140f' },
+  ],
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  // gate-init operates on lesson keys + linear order (language-agnostic), so
+  // the default-lang course is enough. gate-mark, however, writes localized
+  // lesson/module titles into CTA/hint slots — it must ship per-lang title
+  // tables and pick the right one at runtime based on the URL prefix; without
+  // this, RU pages flash EN titles into CTAs between SSR and hydration.
+  const coursesByLang: Record<Lang, Course> = {
+    ru: loadCourse('ru'),
+    en: loadCourse('en'),
+  };
+  const course = coursesByLang[DEFAULT_LANG];
+  const basePath = getRuntimeBasePath(course.basePath);
+  const gateInitScript = buildGateInitScript(course, basePath);
+  const gateMarkScript = buildGateMarkScript(coursesByLang, basePath, DEFAULT_LANG);
+  // When the course declares brand.accent, override the --accent-main family
+  // for both themes. The injected selectors out-specify tokens.css so the
+  // brand colour wins the cascade regardless of stylesheet order.
+  const brandAccentCss = buildBrandAccentCss(course.brand);
+  return (
+    <html
+      lang={DEFAULT_LANG}
+      data-theme="light"
+      className={`${manrope.variable} ${jetbrains.variable} ${literataProse.variable} ${interProse.variable} ${robotoSlab.variable} ${firaCode.variable}`}
+      suppressHydrationWarning
+    >
+      <head>
+        <script
+          id="theme-init"
+          // FOUC-free: applies stored/system theme to <html data-theme> before hydration.
+          dangerouslySetInnerHTML={{ __html: THEME_INIT_SCRIPT }}
+        />
+        <script
+          id="reading-prefs-init"
+          // FOUC-free: stamps four data-prose-*/data-code-* attributes on <html>
+          // from localStorage before hydration. Sits between theme-init and
+          // gate-init so personal-preferences scripts group together.
+          dangerouslySetInnerHTML={{ __html: READING_PREFS_INIT_SCRIPT }}
+        />
+        <script
+          id="progress-mode-init"
+          // FOUC-free: stamps data-progress-disabled on <html> from localStorage
+          // before hydration. MUST run before gate-init so that gate-init's early
+          // exit (free-reading mode) sees the attribute and never locks a lesson —
+          // otherwise a previously-locked lesson would flash its interstitial.
+          dangerouslySetInnerHTML={{ __html: PROGRESS_MODE_INIT_SCRIPT }}
+        />
+        <script
+          id="gate-init"
+          // Pre-hydration gate: stamps data-lesson-locked on <html> when the
+          // current URL targets a locked lesson, so CSS can hide the content
+          // before React mounts and there is no flash of "open" lesson body.
+          // The script strips the `/{ru,en}/` prefix internally (see
+          // gate-init-script.ts) so it stays lang-agnostic.
+          dangerouslySetInnerHTML={{ __html: gateInitScript }}
+        />
+        {brandAccentCss ? (
+          <style
+            id="brand-accent"
+            // Brand accent override from course.yaml.brand.accent. Rendered
+            // last in <head> and selector-weighted to beat the tokens.css
+            // defaults; absent entirely when no brand accent is configured.
+            dangerouslySetInnerHTML={{ __html: brandAccentCss }}
+          />
+        ) : null}
+      </head>
+      <body>
+        <ProgressModeProvider>
+          <ThemeProvider>
+            <ReadingPrefsProvider>{children}</ReadingPrefsProvider>
+          </ThemeProvider>
+        </ProgressModeProvider>
+        {/* Runs as the last body child — by that point every [data-lesson-key]
+            element from server-rendered lists is in the DOM, so we can stamp
+            data-locked before the browser paints. Stops the flash where rows
+            momentarily appear unlocked before React's hydration cycle. */}
+        <script
+          id="gate-mark"
+          dangerouslySetInnerHTML={{ __html: gateMarkScript }}
+        />
+      </body>
+    </html>
+  );
+}

package/src/lib/course-loader.ts

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseCourse, type Course } from './course';
+import { type Lang } from './lang';
+import { resolveCourseYaml, resolveLecturesRoot } from './paths';
+
+export interface LoadCourseOptions {
+  filePath?: string;
+  lecturesRoot?: string;
+}
+
+export function loadCourse(lang: Lang, options: LoadCourseOptions = {}): Course {
+  const filePath = options.filePath ?? resolveCourseYaml();
+  const lecturesRoot = options.lecturesRoot ?? resolveLecturesRoot();
+  const raw = readFileSync(filePath, 'utf8');
+  const course = parseCourse(raw, lang, filePath);
+
+  for (const mod of course.modules) {
+    for (const lesson of mod.lessons) {
+      const translationPath = path.join(
+        lecturesRoot,
+        mod.id,
+        lesson.slug,
+        'i18n',
+        lang,
+        'README.md',
+      );
+      lesson.hasTranslation = existsSync(translationPath);
+    }
+  }
+
+  return course;
+}