@dsbasko/cookbook-engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitriy Basenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+# @dsbasko/cookbook-engine
+
+Переиспользуемый движок учебников на Next.js 14 (static export). Один движок —
+много курсов: новый учебник = `course.yaml` + `lectures/` + `public/` + тонкая
+обёртка из ре-экспортов. Вся логика, UI и SEO живут в пакете; репозиторий курса
+держит только данные и бренд.
+
+`kafka-cookbook` — первый потребитель пакета и его живой валидатор.
+
+## Как завести новый курс
+
+Новый курс — это репозиторий **только с данными**: ноль TS-логики, всё
+поведение приходит из пакета. Нужны четыре вещи.
+
+### 1. Данные курса
+
+```
+my-course/
+├── course.yaml          # манифест: модули, уроки, i18n-заголовки, basePath, brand
+├── lectures/            # markdown-контент
+│   └── <module>/<slug>/i18n/<lang>/README.md
+├── web/                 # тонкая обёртка-потребитель (см. ниже)
+└── public/              # favicon, logo, og-картинки курса (специфичны)
+```
+
+`course.yaml` описывает структуру (см. формат полей ниже); контент уроков лежит
+в `lectures/<module>/<slug>/i18n/<lang>/README.md`. Если перевода для языка нет,
+движок рендерит fallback-баннер и отдаёт `noindex` на этой странице.
+
+### 2. Тонкая обёртка `web/`
+
+Все файлы роутов — **голые ре-экспорты** entry-points пакета. Next требует,
+чтобы `default`/`generateStaticParams`/`generateMetadata` были именованными
+экспортами самого файла роута, поэтому ре-экспорт — единственная форма (данные
+приходят из `cwd` курса через FS, параметризовать пути не нужно).
+
+```
+web/
+├── next.config.mjs                     # export default createCookbookConfig()
+├── package.json                        # зависит от @dsbasko/cookbook-engine
+├── tsconfig.json                       # paths: @/* → engine/src/*
+└── app/
+    ├── layout.tsx                      # → /layout/root
+    ├── page.tsx                        # → /pages/root
+    ├── not-found.tsx                   # → /pages/not-found-root
+    ├── icon.tsx                        # → /og/icon
+    ├── opengraph-image.tsx             # → /og/opengraph-image
+    ├── robots.ts                       # → /seo/robots
+    ├── sitemap.ts                      # → /seo/sitemap
+    └── [lang]/
+        ├── layout.tsx                  # → /layout/lang
+        ├── page.tsx                    # → /pages/home
+        ├── not-found.tsx               # → /pages/not-found-lang
+        └── [module]/
+            ├── page.tsx                # → /pages/module
+            └── [lesson]/page.tsx       # → /pages/lesson
+```
+
+`web/next.config.mjs` целиком:
+
+```js
+import { createCookbookConfig } from '@dsbasko/cookbook-engine/config';
+export default createCookbookConfig();
+```
+
+Пример ре-экспорта (`web/app/[lang]/[module]/[lesson]/page.tsx`):
+
+```ts
+export {
+  default,
+  generateStaticParams,
+  generateMetadata,
+} from '@dsbasko/cookbook-engine/pages/lesson';
+```
+
+Полный готовый комплект обёртки лежит в [`examples/web/`](./examples/web) — его
+можно копировать как шаблон 1-в-1.
+
+### 3. tsconfig обёртки
+
+Внутренний код движка использует TS-алиас `@/*`. Чтобы `tsc` потребителя его
+видел, добавьте в `web/tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": { "@/*": ["./node_modules/@dsbasko/cookbook-engine/src/*"] }
+  }
+}
+```
+
+Webpack-алиас `@` → `engine/src` инлайнится автоматически из
+`createCookbookConfig` — для сборки руками ничего настраивать не нужно.
+
+### 4. Сборка
+
+```bash
+pnpm install
+pnpm --filter web build    # next build, output:'export' → web/out/
+```
+
+`prebuild`/`postbuild`-хуки курса зовут хелперы пакета (`cookbook-sync-images`,
+`cookbook-fix-static-images`) — они синкают картинки уроков и чинят расширения
+статических изображений; оба резолвят пути через `process.cwd()`, так что
+запускаются из `web/`.
+
+## Формат `course.yaml`
+
+Базовые поля (обязательные) — как у любого курса: `title`, `description`
+(`{ru,en}`), `basePath`, `repoUrl`, `modules[]`. Брендирование — опциональная
+секция `brand`; при её отсутствии движок берёт исторические дефолты Kafka
+Cookbook, поэтому существующие курсы рендерятся без изменений.
+
+```yaml
+brand:
+  accent: "#7c3aed"        # hex; переопределяет семейство --accent-main (light/paper)
+  accentDark: "#a78bfa"    # hex; для [data-theme=dark]; fallback → accent
+  glyph: "D"               # один символ для favicon + бейджа og-картинки (дефолт "K")
+  logo: /logo.svg          # путь в public/ курса
+  siteUrl: https://my.dev  # canonical origin; сахар над NEXT_PUBLIC_SITE_URL
+  level: "Demo"            # подпись стека в карточке статистики (дефолт "Go")
+  breadcrumbRoot: { ru: Demo Cookbook, en: Demo Cookbook }   # лейбл breadcrumb/header
+  hero:                    # трёхчастный заголовок главной (lead / accent / tail)
+    lead:   { ru: Демонстрационный, en: A demo }
+    accent: { ru: Cookbook, en: Cookbook }
+    tail:   { ru: движок на практике, en: engine in practice }
+  ogImage:
+    title:    { ru: Demo Cookbook, en: Demo Cookbook }
+    subtitle: { ru: Харнесс движка, en: The engine harness }   # fallback → truncated description
+    footerTag: "cookbook-engine · demo"                        # дефолт "Apache Kafka · Go"
+    alt:      { ru: Demo Cookbook …, en: Demo Cookbook … }     # fallback → i18n-дефолт
+```
+
+Правила валидации (`parseCourse`/`parseBrand`):
+
+- `accent`/`accentDark` — валидный hex, иначе сборка падает с ошибкой парсинга;
+- `siteUrl` — `http(s)`-URL;
+- скалярные поля (`glyph`, `level`, `footerTag`) — непустые строки;
+- per-lang поля (`breadcrumbRoot`, `hero.*`, `ogImage.title/subtitle/alt`)
+  резолвятся в одну строку для активного языка на этапе парсинга, как
+  `title`/`description`.
+
+Акцент-цвет: `brand.accent` схлопывает light+paper в один цвет и деривит
+hover/soft через `color-mix`. Это переопределяет семейство `--accent-main` через
+инлайн `<style>` с селекторами `:root[data-theme=…]` (специфичность выигрывает
+у `tokens.css`). Если курсу нужны hand-tuned per-theme палитры (как у Kafka —
+три отдельных акцента light/paper/dark), `brand.accent` опускают и правят
+`tokens.css` в движке.
+
+Меняется бренд **только** правкой `course.yaml` + логотип в `public/` — кода
+трогать не нужно.
+
+## Публичный API (entry-points через `package.json#exports`)
+
+| Импорт                                              | Назначение                                       |
+| --------------------------------------------------- | ------------------------------------------------ |
+| `@dsbasko/cookbook-engine`                          | Барелл: компоненты + ключевые lib-функции        |
+| `@dsbasko/cookbook-engine/config`                   | `createCookbookConfig(overrides?)`               |
+| `@dsbasko/cookbook-engine/layout/root`              | Root layout: `default` + `generateMetadata` + `viewport` |
+| `@dsbasko/cookbook-engine/layout/lang`              | `[lang]` layout: `default` + `generateStaticParams` + `generateMetadata` |
+| `@dsbasko/cookbook-engine/pages/root`               | Индекс `/` (lang-redirect)                       |
+| `@dsbasko/cookbook-engine/pages/home`               | Главная `[lang]`                                 |
+| `@dsbasko/cookbook-engine/pages/module`             | Страница модуля                                  |
+| `@dsbasko/cookbook-engine/pages/lesson`             | Страница урока                                   |
+| `@dsbasko/cookbook-engine/pages/not-found-root`     | 404 (статический EN)                             |
+| `@dsbasko/cookbook-engine/pages/not-found-lang`     | 404 (клиентский i18n)                            |
+| `@dsbasko/cookbook-engine/og/icon`                  | favicon                                          |
+| `@dsbasko/cookbook-engine/og/opengraph-image`       | og-картинка                                      |
+| `@dsbasko/cookbook-engine/seo/sitemap`              | sitemap.xml                                      |
+| `@dsbasko/cookbook-engine/seo/robots`               | robots.txt                                       |
+| `@dsbasko/cookbook-engine/styles/*.css`             | Глобальные стили (`reset`/`tokens`/`globals`/`markdown`/…) |
+
+`createCookbookConfig(overrides?)` читает `course.yaml` через `process.cwd()`,
+берёт `basePath`, ставит `output:'export'`, `trailingSlash`,
+`images.unoptimized`, prod `basePath`/`assetPrefix`,
+`transpilePackages:['@dsbasko/cookbook-engine']`, инлайнит webpack-алиас
+`@`→`engine/src` и прокидывает `brand.siteUrl`→`env.NEXT_PUBLIC_SITE_URL`.
+`overrides` мёржатся поверх (shallow, с сохранением `experimental`-дефолтов).
+
+## Состав пакета
+
+- `src/components/**` — UI-компоненты (AppShell, Header, Sidebar, Toc, CodeBlock,
+  LessonNav, провайдеры темы/прогресса/reading-prefs/gating, …).
+- `src/lib/**` — course-loader, markdown, i18n, gating, progress, SEO-хелперы и
+  `mdx-plugins/**`. Юнит-тесты (`*.test.ts`, vitest) лежат рядом и являются
+  контрактом публичного поведения.
+- `src/styles/**` — `reset`/`tokens`/`globals`/`markdown`/`slab`.
+- `src/layout/**`, `src/pages/**`, `src/og/**`, `src/seo/**` — entry-points для
+  роутов курса.
+- `src/config.mjs` — `createCookbookConfig()`.
+- `assets/fonts/**` — woff2 (JetBrains Mono), общие для всех курсов.
+- `scripts/**` — хелперы сборки (`cookbook-sync-images`,
+  `cookbook-fix-static-images`, coverage/TOC).
+
+Формат пакета — **нетранспилированный ESM** (source as-is: `.tsx`/`.ts`/`.css`):
+потребитель включает `transpilePackages` (вшито в `createCookbookConfig`),
+сохраняются `'use client'`, `next/font`, server/client-компоненты.
+
+## Политика версионирования (SemVer)
+
+Публичный контракт — это `package.json#exports`, сигнатуры entry-points и формат
+`course.yaml` (включая секцию `brand`). Версия — контракт:
+
+- **major** — несовместимое изменение: удалён/переименован entry-point,
+  изменилась сигнатура экспорта роута, удалено/переименовано поле `course.yaml`,
+  ужесточена валидация так, что ранее валидный курс перестаёт собираться, либо
+  смена peer-диапазона next/react.
+- **minor** — новый entry-point, новое **опциональное** поле `brand`/`course.yaml`,
+  новый компонент в барелле, новая фича без поломки существующих курсов.
+- **patch** — багфиксы, правки стилей/контента, внутренний рефактор без изменения
+  контракта.
+
+Потребители (`kafka-cookbook` и др.) пинят major-диапазон и получают
+авто-обновления движка через `pnpm update`. Изменения, требующие правок в
+курсах, идут только в major с заметкой в changelog.
+
+## Разработка
+
+Основной полигон — мини-курс `examples/` (двуязычный демо-курс с полной секцией
+`brand`):
+
+```bash
+pnpm install
+pnpm typecheck       # tsc --noEmit
+pnpm test            # vitest run — контракт публичного поведения
+pnpm lint            # eslint .
+pnpm examples:dev    # поднять examples/web на localhost:3000
+pnpm smoke           # next build examples/web (output:'export') — e2e-smoke для SSG
+```
+
+Требуется Node `>=20` и pnpm `9`.

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@dsbasko/cookbook-engine",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Reusable Next.js engine for cookbook-style courses driven by course.yaml + markdown lectures.",
+  "author": "Dmitriy Basenko",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@9.15.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "src",
+    "assets",
+    "scripts",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "!**/__snapshots__"
+  ],
+  "bin": {
+    "cookbook-sync-images": "./scripts/sync-images.mjs",
+    "cookbook-fix-static-images": "./scripts/fix-static-image-extensions.mjs"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./config": "./src/config.mjs",
+    "./layout/root": "./src/layout/root.tsx",
+    "./layout/lang": "./src/layout/lang.tsx",
+    "./pages/root": "./src/pages/root.tsx",
+    "./pages/home": "./src/pages/home.tsx",
+    "./pages/module": "./src/pages/module.tsx",
+    "./pages/lesson": "./src/pages/lesson.tsx",
+    "./pages/not-found-root": "./src/pages/not-found-root.tsx",
+    "./pages/not-found-lang": "./src/pages/not-found-lang.tsx",
+    "./og/icon": "./src/og/icon.tsx",
+    "./og/opengraph-image": "./src/og/opengraph-image.tsx",
+    "./seo/sitemap": "./src/seo/sitemap.ts",
+    "./seo/robots": "./src/seo/robots.ts",
+    "./styles/*.css": "./src/styles/*.css"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "examples:dev": "pnpm -C examples/web dev",
+    "smoke": "pnpm -C examples/web build"
+  },
+  "peerDependencies": {
+    "next": "^14.2.18",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "dependencies": {
+    "hast-util-to-jsx-runtime": "2.3.6",
+    "js-yaml": "4.1.0",
+    "rehype-autolink-headings": "7.1.0",
+    "rehype-pretty-code": "0.13.2",
+    "rehype-slug": "6.0.0",
+    "remark-gfm": "4.0.1",
+    "remark-github-blockquote-alert": "^2.1.0",
+    "remark-parse": "11.0.0",
+    "remark-rehype": "11.1.2",
+    "shiki": "1.29.2",
+    "unified": "11.0.5"
+  },
+  "devDependencies": {
+    "@types/hast": "3.0.4",
+    "@types/js-yaml": "4.0.9",
+    "@types/node": "20.17.9",
+    "@types/react": "18.3.12",
+    "@types/react-dom": "18.3.1",
+    "@vitejs/plugin-react": "4.3.4",
+    "@vitest/ui": "2.1.8",
+    "eslint": "8.57.1",
+    "eslint-config-next": "14.2.18",
+    "eslint-config-prettier": "9.1.0",
+    "jsdom": "25.0.1",
+    "next": "14.2.18",
+    "prettier": "3.4.2",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "tsx": "4.19.2",
+    "typescript": "5.7.2",
+    "vitest": "2.1.8"
+  }
+}

package/scripts/check-course-coverage.mts

@@ -0,0 +1,32 @@
+#!/usr/bin/env tsx
+// Engine-side coverage check. Verifies course.yaml ↔ lectures/ parity plus
+// RU/EN translation coverage. Resolves course data via process.cwd() (run it
+// from the consumer's web/), and imports the engine's lib by relative path so
+// it works straight off the package source under tsx.
+import {
+  buildCoverageReport,
+  formatCoverageReport,
+  isCoverageFailing,
+} from '../src/lib/coverage.ts';
+import { loadCourse } from '../src/lib/course-loader.ts';
+import { resolveCourseYaml, resolveLecturesRoot } from './resolve-course-paths.mjs';
+
+function main(): void {
+  const courseYaml = resolveCourseYaml();
+  const lecturesRoot = resolveLecturesRoot();
+  const course = loadCourse('ru', {
+    filePath: courseYaml,
+    lecturesRoot,
+  });
+  const report = buildCoverageReport(course, lecturesRoot);
+  const formatted = formatCoverageReport(report);
+
+  for (const line of formatted.ok) console.log(line);
+  for (const line of formatted.translationGaps) console.log(line);
+  for (const line of formatted.mismatches) console.error(line);
+  console.error(`\n${formatted.summary}`);
+
+  process.exit(isCoverageFailing(report) ? 1 : 0);
+}
+
+main();

package/scripts/fix-static-image-extensions.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// Engine-side postbuild helper. Next.js App Router materializes
+// app/opengraph-image.tsx and app/icon.tsx as extension-less files
+// (out/opengraph-image, out/icon). GitHub Pages serves such files as
+// application/octet-stream, which breaks social-card crawlers and the favicon.
+// Rename the files to .png and patch every reference in the generated HTML.
+//
+// Parameterized via process.cwd() (NOT import.meta.url): the consumer runs it
+// from web/ after `next build`, so the export dir is cwd/out.
+import { promises as fs, existsSync } from 'node:fs';
+import path from 'node:path';
+
+const OUT_DIR = path.resolve(process.cwd(), 'out');
+
+const RENAMES = [
+  { from: 'opengraph-image', to: 'opengraph-image.png' },
+  { from: 'icon', to: 'icon.png' },
+];
+
+async function* walkHtml(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkHtml(abs);
+    } else if (entry.isFile() && entry.name.endsWith('.html')) {
+      yield abs;
+    }
+  }
+}
+
+function patchContent(content) {
+  let next = content;
+  for (const { from, to } of RENAMES) {
+    // Match /<name> when followed by ?, ", or backslash (for JSON-escaped
+    // strings inside <script>). Lookahead keeps existing query/fragment.
+    const re = new RegExp(`/${from}(?=[?"\\\\])`, 'g');
+    next = next.replace(re, `/${to}`);
+  }
+  return next;
+}
+
+async function main() {
+  if (!existsSync(OUT_DIR)) {
+    console.error(`fix-static-image-extensions: ${OUT_DIR} not found`);
+    process.exit(1);
+  }
+
+  for (const { from, to } of RENAMES) {
+    const src = path.join(OUT_DIR, from);
+    const dst = path.join(OUT_DIR, to);
+    if (!existsSync(src)) {
+      console.error(`fix-static-image-extensions: missing ${src}`);
+      process.exit(1);
+    }
+    await fs.rename(src, dst);
+  }
+
+  let patched = 0;
+  for await (const file of walkHtml(OUT_DIR)) {
+    const original = await fs.readFile(file, 'utf8');
+    const updated = patchContent(original);
+    if (updated !== original) {
+      await fs.writeFile(file, updated);
+      patched += 1;
+    }
+  }
+
+  console.log(
+    `fix-static-image-extensions: renamed ${RENAMES.length} files, patched ${patched} html files`,
+  );
+}
+
+main().catch((err) => {
+  console.error('fix-static-image-extensions: failed');
+  console.error(err);
+  process.exit(1);
+});

package/scripts/generate-readme-toc.mts

@@ -0,0 +1,32 @@
+#!/usr/bin/env tsx
+// Engine-side README TOC generator. Prints the markdown table of contents for
+// the course root README. Resolves course data via process.cwd() (run it from
+// the consumer's web/), imports engine lib by relative path under tsx.
+import { loadCourse } from '../src/lib/course-loader.ts';
+import { isLang, type Lang } from '../src/lib/lang.ts';
+import { generateReadmeToc } from '../src/lib/readme-toc.ts';
+import { resolveCourseYaml, resolveLecturesRoot } from './resolve-course-paths.mjs';
+
+function parseLang(): Lang {
+  const arg = process.argv.slice(2).find((a) => a.startsWith('--lang='));
+  if (!arg) return 'en';
+  const value = arg.slice('--lang='.length);
+  if (!isLang(value)) {
+    console.error(`Invalid --lang value: ${value}. Expected 'ru' or 'en'.`);
+    process.exit(2);
+  }
+  return value;
+}
+
+function main(): void {
+  const lang = parseLang();
+  const courseYaml = resolveCourseYaml();
+  const lecturesRoot = resolveLecturesRoot();
+  const course = loadCourse(lang, {
+    filePath: courseYaml,
+    lecturesRoot,
+  });
+  process.stdout.write(generateReadmeToc(course, { lang, lecturesRoot }));
+}
+
+main();

package/scripts/resolve-course-paths.mjs

@@ -0,0 +1,28 @@
+// Shared cwd-based resolver for the engine CLI helpers. Mirrors the candidate
+// lists in lib/course-loader.ts: probe CWD=repo-root (`./course.yaml`,
+// `./lectures`) first, then CWD=web/ (`../course.yaml`, `../lectures`). NEVER
+// resolves via import.meta.url — the package lives in node_modules, so the
+// course data must always come from the consumer's process.cwd().
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+function firstExisting(candidates) {
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return candidates[0];
+}
+
+export function resolveCourseYaml() {
+  return firstExisting([
+    path.resolve(process.cwd(), 'course.yaml'),
+    path.resolve(process.cwd(), '..', 'course.yaml'),
+  ]);
+}
+
+export function resolveLecturesRoot() {
+  return firstExisting([
+    path.resolve(process.cwd(), 'lectures'),
+    path.resolve(process.cwd(), '..', 'lectures'),
+  ]);
+}

package/scripts/sync-images.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Engine-side prebuild helper. Copies lecture images from <repoRoot>/lectures
+// into the consumer web app's public/ tree so Next can serve them as static
+// assets. Parameterized via process.cwd() (NOT import.meta.url) so the same
+// file works from any course repo: the consumer runs it from web/, so the
+// course repo root is one level up and the public dir is cwd/public.
+import { promises as fs, existsSync } from 'node:fs';
+import path from 'node:path';
+
+const WEB_DIR = process.cwd();
+const REPO_ROOT = path.resolve(WEB_DIR, '..');
+const LECTURES_DIR = path.join(REPO_ROOT, 'lectures');
+const PUBLIC_DIR = path.join(WEB_DIR, 'public', 'static', 'lectures');
+
+const ALLOWED_EXT = new Set([
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.svg',
+  '.webp',
+  '.gif',
+]);
+
+async function* walkImages(dir, relativeFromRoot = '') {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const abs = path.join(dir, entry.name);
+    const rel = path.join(relativeFromRoot, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkImages(abs, rel);
+    } else if (entry.isFile()) {
+      const ext = path.extname(entry.name).toLowerCase();
+      if (ALLOWED_EXT.has(ext)) {
+        yield { abs, rel };
+      }
+    }
+  }
+}
+
+async function main() {
+  if (!existsSync(LECTURES_DIR)) {
+    console.error(`sync-images: lectures dir not found at ${LECTURES_DIR}`);
+    process.exit(1);
+  }
+
+  await fs.rm(PUBLIC_DIR, { recursive: true, force: true });
+  await fs.mkdir(PUBLIC_DIR, { recursive: true });
+
+  let copied = 0;
+  const moduleEntries = await fs.readdir(LECTURES_DIR, { withFileTypes: true });
+
+  for (const moduleEntry of moduleEntries) {
+    if (!moduleEntry.isDirectory()) continue;
+    if (!/^\d{2}-/.test(moduleEntry.name)) continue;
+
+    const moduleDir = path.join(LECTURES_DIR, moduleEntry.name);
+    const lessonEntries = await fs.readdir(moduleDir, { withFileTypes: true });
+
+    for (const lessonEntry of lessonEntries) {
+      if (!lessonEntry.isDirectory()) continue;
+
+      const imagesDir = path.join(moduleDir, lessonEntry.name, 'images');
+      if (!existsSync(imagesDir)) continue;
+
+      const destDir = path.join(
+        PUBLIC_DIR,
+        moduleEntry.name,
+        lessonEntry.name,
+        'images',
+      );
+
+      for await (const file of walkImages(imagesDir)) {
+        const dest = path.join(destDir, file.rel);
+        await fs.mkdir(path.dirname(dest), { recursive: true });
+        await fs.copyFile(file.abs, dest);
+        copied += 1;
+      }
+    }
+  }
+
+  console.log(`sync-images: copied ${copied} image${copied === 1 ? '' : 's'}`);
+}
+
+main().catch((err) => {
+  console.error('sync-images: failed');
+  console.error(err);
+  process.exit(1);
+});

package/src/components/AppShell/AppShell.module.css

@@ -0,0 +1,40 @@
+.shell {
+  display: flex;
+  flex-direction: row;
+  min-height: 100dvh;
+  background-color: var(--bg-default);
+  color: var(--content-primary);
+}
+
+.body {
+  display: flex;
+  flex-direction: column;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.main {
+  flex: 1 1 auto;
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+@media (max-width: 1023px) {
+  .shell {
+    flex-direction: column;
+  }
+
+  /* Sidebar collapses into two FABs at the top of the viewport (see
+     Sidebar.module.css). The body reclaims full width; the main column adds
+     a top clearance so heroes/hl titles don't render under the gradient
+     band that the FABs sit on. */
+  .body {
+    width: 100%;
+  }
+
+  .main {
+    padding-top: calc(env(safe-area-inset-top, 0px) + 56px);
+    padding-bottom: env(safe-area-inset-bottom);
+  }
+}