@madojs/mado 0.5.0

package/docs/ru/00-the-mado-way.md

@@ -0,0 +1,93 @@
+# The Mado Way
+
+> Один правильный путь. Жёсткие контракты. Никакой магии.
+
+Mado — это не просто фреймворк, это **набор соглашений**. Если ты следуешь им, проект остаётся понятным даже когда в нём 200 экранов и 5 разработчиков. Если нарушаешь — типы и линтер скажут об этом сразу.
+
+## Принципы
+
+1. **Один способ.** Для каждой задачи — один правильный путь, не пять. Если ты пишешь странное — спроси себя, не существует ли уже идиоматичный хелпер.
+2. **Явность над магией.** Никаких сканеров файлов, неявных глобалов, скрытых side-effects. Всё, что делает фреймворк, можно прочитать в одном файле.
+3. **Платформа сначала.** Если в браузере уже есть фича — используем её напрямую. Своих абстракций над `fetch`, `<form>`, History API, Shadow DOM не плодим.
+4. **Жёсткие типы.** `tsc --strict --noUncheckedIndexedAccess` всегда. Если что-то не типизируется — это сигнал что API кривой.
+5. **Никаких рантайм-зависимостей.** Любая зависимость — обязательство на годы; экосистема Web Components этого не требует.
+
+## Соглашения
+
+### Структура проекта
+
+```
+src/
+├── routes.ts         ← манифест маршрутов, один файл на проект
+├── main.ts           ← точка входа: провайдеры + монтаж <x-app>
+├── pages/            ← одна страница = один файл = `export default page({...})`
+├── components/       ← переиспользуемые компоненты, side-effect-регистрация
+├── lib/              ← контексты, API-клиенты, бизнес-логика без UI
+└── styles/           ← общие стили (если нужны), .ts с css``
+```
+
+Это **обязательно**, не "по желанию". Если у проекта будет 10 разработчиков — они все должны писать одинаково.
+
+### Один компонент = один файл
+
+```ts
+// src/components/user-card.ts
+import { component, html, css } from '@madojs/mado';
+
+component('x-user-card', () => {
+  return () => html`<div class="card"><slot/></div>`;
+}, {
+  styles: css`.card { padding: 1rem; }`,
+});
+```
+
+Импорт `import './components/user-card.js'` **регистрирует** компонент через `customElements.define`. Это side-effect. Где компонент нужен — там и импортируем.
+
+### Один способ загрузки данных
+
+❌ Не зовём `fetch()` напрямую из компонента. Всегда через:
+
+```ts
+// чтение → resource
+const user = resource(() => `/api/users/${id()}`, jsonFetcher());
+
+// запись → mutation
+const save = mutation(api.save, { invalidates: ['/api/users*'] });
+```
+
+Это даёт кеш, отмену, обработку ошибок, авто-инвалидацию.
+
+### Один способ описать страницу
+
+```ts
+// src/pages/user-profile.ts
+import { page, html, resource, jsonFetcher } from '@madojs/mado';
+
+export default page({
+  title: ({ id }) => `User #${id}`,
+  view:  ({ params }) => html`...`,
+});
+```
+
+Три слота — `title`, `load`, `view`. Других нет. Хочешь что-то ещё — это уже компонент или хелпер.
+
+### Один способ объявить роуты
+
+См. [`01-routing.md`](./01-routing.md).
+
+## Чего НЕ делаем
+
+- ❌ Не пишем компоненты без дефиса. Это правило браузера для custom elements: `user-card` ок, `usercard` нет.
+- `x-*` — только convention для примеров и тестов Mado, не брендовый стандарт. В production лучше брать префикс домена: `app-*`, `crm-*`, `ticket-*`, `admin-*`.
+- ❌ Не используем `innerHTML` напрямую. Только через `html\`\``.
+- ❌ Не вызываем `setTimeout`/`setInterval` без cleanup. Только внутри `effect()`.
+- ❌ Не храним глобальный мутируемый state. Используем сигналы и `context`.
+- ❌ Не подключаем pkg без обсуждения. Каждая зависимость — обязательство.
+
+## Когда сомневаешься
+
+Если ты задаёшься вопросом "а как тут лучше?" — это сигнал, что:
+1. Либо есть встроенный хелпер, который ты не знаешь (загляни в `docs/`).
+2. Либо это новая ситуация — её надо обсудить и **зафиксировать** в этом документе как ещё одно соглашение.
+
+«Лучше единый-окей, чем разный-идеальный.»

package/docs/ru/01-routing.md

@@ -0,0 +1,194 @@
+# Routing
+
+> Один файл-манифест. Никаких сканеров папок. Никаких спецсимволов.
+
+## Зачем не file-based
+
+В Next/SvelteKit/SolidStart роут возникает «магически» по имени файла. У этого есть плюсы (видно структуру URL по `pages/`), но в проде это означает:
+
+- Невидимый плагин-сканер в билде. Без него файлы — просто файлы.
+- Спецсимволы в путях: `[id]`, `(group)`, `_layout`, `+page.svelte`, `...slug`.
+- Server-route vs client-route путаются.
+- Тестировать роутинг — мука: нужен эмулятор сборщика.
+
+Mado считает это **слишком магией**. Мы делаем иначе.
+
+## Манифест
+
+Один файл — `src/routes.ts`. В нём один объект. Читается сверху вниз.
+
+```ts
+// src/routes.ts
+import { routes } from '@madojs/mado';
+
+export default routes({
+  '/':              () => import('./pages/home.js'),
+  '/about':         () => import('./pages/about.js'),
+  '/users/:id':     () => import('./pages/user-profile.js'),
+  '/users/:id/edit':() => import('./pages/user-edit.js'),
+  '*':              () => import('./pages/not-found.js'),
+});
+```
+
+Хочешь увидеть все роуты? Открой `routes.ts`. Никаких сюрпризов.
+
+## Что справа от пути
+
+Любая запись — это **одно из трёх**:
+
+### 1. Lazy import (рекомендовано)
+
+```ts
+'/posts': () => import('./pages/posts.js'),
+```
+
+- Браузер сам сделает chunk при бандлинге (esbuild --bundle --splitting).
+- Модуль загрузится только при заходе на роут.
+- Между навигациями результат кэшируется.
+
+### 2. Готовая Page (eager)
+
+```ts
+import about from './pages/about.js';
+
+'/about': about,
+```
+
+Сразу в графе, без задержек. Используй для критичных страниц (home, login).
+
+### 3. Nested с layout
+
+```ts
+import { routes, nested } from '@madojs/mado';
+
+export default routes({
+  '/': () => import('./pages/home.js'),
+
+  '/admin/*': nested({
+    layout: () => import('./layouts/admin.js'),
+    routes: {
+      '':       () => import('./pages/admin/dashboard.js'),
+      'users':  () => import('./pages/admin/users.js'),
+      'logs':   () => import('./pages/admin/logs.js'),
+    },
+  }),
+});
+```
+
+Layout — это **обычный** `page({...})`, который рендерит `ctx.child` куда хочет:
+
+```ts
+// src/layouts/admin.ts
+import { page, html, css, component } from '@madojs/mado';
+
+export default page({
+  view: ({ child }) => html`
+    <div class="admin">
+      <aside><nav>...</nav></aside>
+      <main>${child}</main>
+    </div>
+  `,
+});
+```
+
+## Контракт страницы
+
+```ts
+import { page, html, resource, jsonFetcher } from '@madojs/mado';
+
+export default page({
+  title: ({ id }) => `User #${id}`,        // string | (params) => string
+  load:  ({ id }) => resource(...),         // опц., возвращает Resource или данные
+  view:  ({ params, data, path, child }) => html`...`,  // ОБЯЗАТЕЛЬНО
+});
+```
+
+Три слота, всё. Если ты экспортируешь не `page({...})`, а просто функцию — `routes()` кинет понятную ошибку:
+
+```
+[Mado] Lazy-роут не вернул page({...}) как default-экспорт.
+```
+
+## Параметры URL
+
+```ts
+'/users/:id': () => import('./pages/user.js'),
+```
+
+```ts
+export default page<{ id: string }>({
+  title: ({ id }) => `User ${id}`,
+  view:  ({ params }) => html`<h1>${params.id}</h1>`,
+});
+```
+
+Типы передаются в `page<Params>` — `tsc` проверит что вы не обратились к `params.foo`, которого нет в роуте.
+
+## Глобальные опции
+
+```ts
+export default routes(
+  { '/': home, '/about': about, '*': nf },
+  {
+    titleSuffix: ' · MyApp',                       // → "Главная · MyApp"
+    loading: () => html`<x-spinner/>`,             // пока модуль грузится
+    error:   (err) => html`<x-fatal-error .err=${err}/>`,
+  },
+);
+```
+
+## Программная навигация
+
+```ts
+import route from './routes.js';
+
+route.navigate('/posts');
+route.navigate('/posts?page=2');
+route.navigate('/posts', { replace: true });
+```
+
+Клики по `<a href="/foo" data-link>` перехватываются глобально (без атрибута — браузер сделает full reload, как и положено для внешних ссылок).
+
+## Query-параметры
+
+```ts
+import { queryParam } from '@madojs/mado';
+
+const page = queryParam('page', '1');
+page();              // '1'
+page.set('2');       // history.replaceState + перерисовка
+page.set(null);      // удалить параметр
+page.set('3', { push: true });   // history.pushState
+```
+
+`queryParam` — обычный сигнал. Использовать можно где угодно: в страницах, компонентах, computed.
+
+## Что осознанно отсутствует
+
+- ❌ Авто-сканирование `pages/`. **Один файл-манифест явный**.
+- ❌ Спецсимволы в путях (`[id]`, `(group)`, `_layout`). **Параметры — только `:name`, ничего больше**.
+- ❌ Server-side роутинг в этом же манифесте. Mado — клиентский фреймворк.
+- ❌ Auto-prefetch при наведении. Если очень нужно — можно сделать вручную: `link.addEventListener('mouseenter', loader)`. Но обычно лишнее.
+
+## FAQ
+
+**А если у меня 100 роутов? Не разрастётся ли файл?**
+Разрастётся до ~150 строк. Это всё ещё **один источник правды** против сотни файлов в `pages/` с магическими именами. На практике даже у больших проектов (1000+ страниц) можно бить на feature-манифесты:
+
+```ts
+import { routes } from '@madojs/mado';
+import adminRoutes from './features/admin/routes.js';
+import billingRoutes from './features/billing/routes.js';
+
+export default routes({
+  ...adminRoutes,
+  ...billingRoutes,
+  '*': () => import('./pages/not-found.js'),
+});
+```
+
+**Как тестировать роутинг?**
+Импортируешь `routes.ts` — это просто объект. Подставляешь свой mock-router. Никакой эмуляции сборщика не нужно.
+
+**Code splitting работает?**
+Да. При `esbuild --bundle --splitting --format=esm` каждый `() => import('./pages/x.js')` становится отдельным chunk'ом.

package/docs/ru/02-project-layout.md

@@ -0,0 +1,57 @@
+# Project layout
+
+Каждый new-проект на Mado имеет одинаковую структуру. Это **обязательное** соглашение.
+
+```
+my-app/
+├── package.json              # ровно 1 dep: typescript (esbuild опц.)
+├── tsconfig.json             # с paths "@madojs/mado" → импорт без относительных путей
+├── Dockerfile + nginx.conf   # копируем из Mado/ при scaffold
+├── .gitlab-ci.yml | .github/workflows/ci.yml
+├── server/serve.mjs          # dev-сервер из Mado, без deps
+├── scripts/
+│   ├── bundle.mjs            # esbuild прод-бандл
+│   └── new.mjs               # скаффолд страницы
+├── templates/                # шаблоны для new.mjs
+├── docs/                     # проектные доки (можно копировать наши гайды)
+├── public/                   # статика (favicon, манифесты)
+└── src/
+    ├── main.ts               # точка входа: провайдеры + монтаж <x-app>
+    ├── routes.ts             # манифест роутов
+    ├── pages/                # одна страница = один файл = `export default page({...})`
+    ├── components/           # переиспользуемые компоненты (x-*)
+    ├── layouts/              # layout-страницы (для nested)
+    └── lib/
+        ├── api.ts            # все fetch-обёртки
+        ├── contexts.ts       # createContext(...)
+        ├── theme.ts          # темы
+        └── ...               # утилиты, типы, бизнес-правила
+```
+
+## Куда положить новый файл?
+
+| Что | Куда |
+|---|---|
+| Страница на новый URL | `src/pages/foo.ts` + добавить в `src/routes.ts` |
+| Переиспользуемая UI-штука | `src/components/foo-bar.ts` |
+| Обёртка над API | `src/lib/api.ts` (добавить метод) |
+| Глобальный контекст (тема, юзер, i18n) | `src/lib/<name>.ts` |
+| Чистая функция без UI | `src/lib/util/<name>.ts` |
+
+Если не понимаешь куда — это сигнал что **архитектура страдает**. Спроси команду, **зафиксируй** ответ в `docs/`.
+
+## Правила именования
+
+| Что | Стиль | Пример |
+|---|---|---|
+| Файл | kebab-case | `user-profile.ts` |
+| Тэг компонента | `x-` + kebab | `<x-user-profile>` |
+| Контекст | PascalCase + `Ctx` | `ThemeCtx`, `AuthCtx` |
+| Сигнал | camelCase | `userId`, `isLoggedIn` |
+| Page-функция (внутренний компонент) | `x-<route>-page` | `<x-posts-page>` |
+
+## Что НЕ кладём в src/
+
+- ❌ Конфиги билдеров (webpack, rollup, vite) — у нас их нет.
+- ❌ `.env`-файлы — env читается из `process.env`/`import.meta.env` в `lib/config.ts`.
+- ❌ Тесты вперемешку с кодом — все в `test/`.

package/docs/ru/03-static-bake.md

@@ -0,0 +1,251 @@
+# Smart Static (`bake`)
+
+> Выпекание HTML для SEO без runtime SSR. **Идея: данные и view в одном файле, статика на выходе.**
+
+`bake` — это **build-time prerender**, не SSR. На выходе — статические `*.html` файлы, которые любой nginx/Cloudflare раздаёт как обычную статику. На клиенте Web Components оживают и работает SPA-навигация дальше.
+
+---
+
+## Когда `bake` подходит
+
+- **Маркетинговые страницы**: лендинги, landing/sub-landings под рекламные кампании, страницы продуктов.
+- **Каталог с относительно стабильным набором страниц**: блог, документация, портфолио, e-commerce до **~10k SKU** с обновлениями реже раза в час.
+- **Контент, общий для всех пользователей**: вся страница одинакова для гостя и для авторизованного юзера (или авторизация дорисовывается через `effect()` уже на клиенте).
+- Нужен **хороший SEO** (rich snippets, OG, JSON-LD) и **быстрый first paint** без поднятия node-серверов в проде.
+
+## Когда `bake` **не** подходит
+
+- **Сотни тысяч страниц с частыми изменениями**. `bake` обходит все `paths` синхронно за один прогон. На 100k+ страниц это минуты ребилда, и инвалидация одной страницы либо требует полного rebake, либо отдельной CI-логики (см. ниже про точечный revalidate).
+- **Персонализированный контент в HTML**. Если на странице должно быть "Привет, Иван" в `<title>` или в meta — это не для `bake`. Авторизованный кабинет, личный фид, корзина с реальными ценами для юзера — оставляйте SPA.
+- **Нужны server-only API в render**: cookies, headers, реальные сетевые запросы к закрытым API. На bake-стороне доступен только `linkedom`, никакого Node-окружения для компонентов.
+- **A/B-тесты и flag'и, которые меняют разметку в первом paint**. `bake` зафиксирует один вариант. Динамику делайте на клиенте через `effect()`.
+- **Real-time / часто меняющиеся данные** (биржевые котировки, остатки на складе минута-в-минуту). `bake.revalidate` — это метаданные, не runtime: фреймворк сам ничего не перевыпекает.
+- Контент **под авторизацией** (admin, internal tools). Незачем; используйте SPA-режим.
+
+---
+
+## Концепция
+
+`page({...})` имеет четыре опциональных слота, относящихся к `bake`:
+
+- `head` — meta, OG, JSON-LD.
+- `bake.paths` — список URL-параметров для генерации (build-time, может быть `async`).
+- `bake.data` — данные для конкретного URL (build-time, может быть `async`).
+- `bake.revalidate` — через сколько секунд кэш устарел (записывается в `<meta>`, реальную инвалидацию решает ваша CI/CDN).
+
+Команда `npm run bake` обходит все `page` с `bake`, генерит HTML через `linkedom`, складывает в `out/<path>/index.html`. **Никакого Chromium не нужно** — `linkedom` весит ~50 КБ.
+
+---
+
+## Пример
+
+```ts
+// src/pages/product.ts
+import { page, component, html } from "@madojs/mado";
+import { findProduct, products, type Product } from "../lib/products.js";
+
+component("x-product-page", ({ host }) => {
+  return () => {
+    const p = findProduct(host.dataset.slug);
+    return p
+      ? html`<h1>${p.name}</h1><p>${p.description}</p>`
+      : html`<p>Не найдено.</p>`;
+  };
+});
+
+export default page<{ slug: string }, Product | undefined>({
+  title: ({ slug }) => `${findProduct(slug)?.name} — MyShop`,
+
+  head: ({ slug }, baked) => {
+    const p = baked ?? findProduct(slug);
+    if (!p) return {};
+    return {
+      description: p.description,
+      canonical: `/product/${p.slug}`,
+      og: { title: p.name, image: p.image, type: "product" },
+      jsonLd: {
+        "@context": "https://schema.org",
+        "@type": "Product",
+        name: p.name,
+        offers: { "@type": "Offer", price: p.price, priceCurrency: p.currency },
+      },
+    };
+  },
+
+  bake: {
+    paths: () => products.map((p) => ({ slug: p.slug })),
+    data: ({ slug }) => findProduct(slug),
+    revalidate: 3600,
+  },
+
+  view: ({ params }) =>
+    html`<x-product-page data-slug=${params.slug}></x-product-page>`,
+});
+```
+
+```ts
+// src/routes.ts
+import { routes, type RoutesMap } from "@madojs/mado";
+
+// Экспортируем И default (RouterApi для рантайма), И manifest (для bake-скрипта).
+export const manifest: RoutesMap = {
+  "/": () => import("./pages/home.js"),
+  "/product/:slug": () => import("./pages/product.js"),
+  "*": () => import("./pages/not-found.js"),
+};
+
+export default routes(manifest, { titleSuffix: " · MyShop" });
+```
+
+## Запуск
+
+```bash
+npm install -D linkedom esbuild
+npm run build
+npm run bake
+```
+
+Получаешь:
+
+```
+out/
+├── product/
+│   ├── mado-mug/index.html        ← HTML с meta + JSON-LD
+│   ├── raw-bundler/index.html
+│   └── shadow-dom/index.html
+└── sitemap.xml
+```
+
+## Что внутри сгенерированного HTML
+
+```html
+<head>
+  <title>Mado-кружка — MyShop</title>
+  <meta name="description" content="..." data-mado-head="baked">
+  <link rel="canonical" href="/product/mado-mug" data-mado-head="baked">
+  <meta property="og:title" content="Mado-кружка" data-mado-head="baked">
+  <meta property="og:image" content="..." data-mado-head="baked">
+  <script type="application/ld+json" data-mado-head="baked">
+    {"@context":"https://schema.org","@type":"Product","..."}
+  </script>
+  <meta name="bake-revalidate" content="3600" data-mado-head="baked">
+  <meta name="bake-stamp" content="1234567890" data-mado-head="baked">
+</head>
+<body>
+  <div id="app">
+    <x-product-page data-slug="mado-mug">
+      <h1>Mado-кружка</h1>
+      <p>Кружка с надписью «zero dependencies».</p>
+      <strong>12 EUR</strong>
+    </x-product-page>
+  </div>
+
+  <!-- предзагруженные данные для гидрации -->
+  <script id="bake" type="application/json">
+    {"slug":"mado-mug","name":"Mado-кружка","price":12,"..."}
+  </script>
+
+  <script type="module" src="/dist/examples/main.js"></script>
+</body>
+```
+
+После загрузки JS:
+
+1. Web Components `<x-product-page>` оживают (браузер уже знает кастомные элементы).
+2. `page.load()` получает `baked` как initialData — никаких лишних `fetch`.
+3. SPA-навигация работает дальше как обычно.
+
+---
+
+## Cookbook: типовые сценарии
+
+### Блог (Markdown → bake)
+
+```ts
+// src/lib/posts.ts
+import { readdirSync, readFileSync } from "node:fs";
+// (этот модуль импортируется только из bake-скрипта,
+// в браузере не должен попасть в граф — выносите в lib/server/ или ifdef'ьте)
+
+export const allPosts = () =>
+  readdirSync("content/blog").map((file) => ({
+    slug: file.replace(/\.md$/, ""),
+    ...parseFrontmatter(readFileSync(`content/blog/${file}`, "utf-8")),
+  }));
+```
+
+```ts
+// src/pages/blog-post.ts
+import { page, html } from "@madojs/mado";
+import { allPosts } from "../lib/posts.js";
+
+export default page<{ slug: string }>({
+  title: ({ slug }) => allPosts().find((p) => p.slug === slug)?.title ?? slug,
+  head: ({ slug }, post) => ({
+    description: post?.excerpt,
+    canonical: `/blog/${slug}`,
+    og: { title: post?.title, type: "article" },
+  }),
+  bake: {
+    paths: () => allPosts().map(({ slug }) => ({ slug })),
+    data: ({ slug }) => allPosts().find((p) => p.slug === slug),
+  },
+  view: ({ params }) =>
+    html`<x-blog-post data-slug=${params.slug}></x-blog-post>`,
+});
+```
+
+### Каталог продуктов (e-commerce, ≤ 10k SKU)
+
+- `bake.paths` → SELECT slug FROM products
+- `bake.data` → SELECT * FROM products WHERE slug=?
+- Полная инвалидация раз в N часов через cron + `npm run bake`
+- Точечная инвалидация одного товара: webhook → пересборка только этого `paths`
+
+### Документация
+
+- `bake.paths` — обход файловой системы `docs/**/*.md`
+- `bake.data` — парсинг Markdown
+- `head.jsonLd` — `TechArticle`
+
+---
+
+## Revalidate / CDN
+
+`bake.revalidate: 3600` пишет в HTML `<meta name="bake-revalidate" content="3600">` и `bake-stamp`. Это **метаданные** — фреймворк сам ничего не перевыпекает. Стратегии:
+
+1. **Простейший вариант**: cron в CI — `npm run bake && rsync out/ origin:/var/www/`.
+2. **Через CDN** (Cloudflare/Fastly): кладёте HTML с `Cache-Control: max-age=3600`. CDN сам инвалидирует.
+3. **Webhook-триггер**: API magazin → POST `/_revalidate?path=/product/mado-mug` → CI пере-выпекает только эту страницу (можно сделать `bake.paths`, который возвращает точечный список по env-параметру).
+
+---
+
+## Сравнение с альтернативами
+
+|                          | Next.js SSG/ISR    | playwright-prerender | **mado bake** |
+|--------------------------|--------------------|----------------------|-----------------|
+| Нужен Chrome в CI        | нет                | **да** (~300 МБ)     | **нет**         |
+| Нужен node в проде       | для ISR            | нет                  | **нет**         |
+| Время на 1000 страниц    | минуты             | минуты               | **секунды**     |
+| Magic-уровень            | high               | low                  | **zero**        |
+| HTML-парсер              | React-renderer     | браузер              | linkedom (~50 КБ) |
+| Конфигурация             | next.config.js + … | один скрипт          | один скрипт     |
+| Источник правды view+data | разные             | страница             | **одна страница** |
+
+---
+
+## Ограничения и подводные камни
+
+- **В bake-стороне нет браузера.** Не работают: `setTimeout` (точнее работает, но bake завершается раньше), `fetch` к относительным URL, любые `effect()`/`signal()` побочки, реальные `requestAnimationFrame`. Render-функция должна быть детерминирована от `params` / `data`.
+- **`linkedom` ≠ браузер.** Не все API DOM поддержаны (например, `HTMLElement.click()` ведёт себя проще). Тяжёлая логика в Web Components будет выполнена только в браузере после `connectedCallback`; в baked HTML попадёт только то, что синхронно отрендерилось при первом проходе.
+- **Динамичный контент дорисовывайте на клиенте.** Текущее время, A/B-тест, гео-баннер, корзина юзера — не должны быть в выпеченном HTML. Используйте `effect()` для дорисовки.
+- **Серверные импорты не должны попадать в клиентский граф.** Если `lib/posts.ts` импортит `node:fs`, его нельзя импортить из `view`. Держите такие модули в отдельной папке (`lib/build/`) и используйте только из `bake.paths`/`bake.data`.
+- **`paths` и `data` исполняются на каждый bake-прогон.** Если за ними тяжёлый запрос к БД — кешируйте на уровне скрипта.
+
+---
+
+## TL;DR
+
+Если страница **общая для всех пользователей**, имеет **относительно стабильный набор URL'ов** и важен **SEO + первый paint** — добавьте `bake: { paths, data }` и получите статический HTML с meta/JSON-LD/sitemap за миллисекунды. Без node-сервера, без Chrome, без магии.
+
+Если страница персонализирована, или URL'ов миллион, или контент меняется в реальном времени — `bake` не ваш инструмент. Оставляйте SPA или подключайте отдельный SSR-фреймворк.