@madojs/mado 0.10.0 → 0.11.0

package/docs/ru/01-routing.md

@@ -1,194 +1,119 @@
 # Routing
 
-> Один файл-манифест. Никаких сканеров папок. Никаких спецсимволов.
+> Один app map. Никаких folder scanners. Никаких специальных path symbols.
 
-## Зачем не file-based
+Mado не выводит routes из файлов. Composition должна читаться в одном месте.
 
-В Next/SvelteKit/SolidStart роут возникает «магически» по имени файла. У этого есть плюсы (видно структуру URL по `pages/`), но в проде это означает:
+## App Manifest
 
-- Невидимый плагин-сканер в билде. Без него файлы — просто файлы.
-- Спецсимволы в путях: `[id]`, `(group)`, `_layout`, `+page.svelte`, `...slug`.
-- Server-route vs client-route путаются.
-- Тестировать роутинг — мука: нужен эмулятор сборщика.
-
-Mado считает это **слишком магией**. Мы делаем иначе.
-
-## Манифест
-
-Один файл — `src/routes.ts`. В нём один объект. Читается сверху вниз.
+Используйте `src/app.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'),
-});
+import { layout, routes } from "@madojs/mado";
+import { requireAuth } from "./modules/auth/auth.public";
+import { authRoutes } from "./modules/auth/auth.routes";
+import { billingRoutes } from "./modules/billing/billing.routes";
+
+export const manifest = {
+  "/": () => import("./modules/home/home.page.js"),
+  "/login": layout({
+    layout: () => import("./layouts/auth-shell.layout.js"),
+    routes: authRoutes,
+  }),
+  "/billing": layout({
+    layout: () => import("./layouts/app-shell.layout.js"),
+    guard: requireAuth,
+    routes: billingRoutes,
+  }),
+  "*": () => import("./modules/home/not-found.page.js"),
+};
+
+export default routes(manifest);
 ```
 
-Хочешь увидеть все роуты? Открой `routes.ts`. Никаких сюрпризов.
+Открываешь `app.routes.ts` и видишь все зоны приложения: public pages, auth,
+protected app zones, guards и shells.
 
-## Что справа от пути
+`manifest` экспортируется отдельно, чтобы `mado bake` мог его прочитать.
 
-Любая запись — это **одно из трёх**:
+## Module Routes
 
-### 1. Lazy import (рекомендовано)
+Modules экспортируют plain route maps. Они не вызывают `layout()` и не решают,
+какой shell их оборачивает.
 
 ```ts
-'/posts': () => import('./pages/posts.js'),
+export const billingRoutes = {
+  "/invoices": () => import("./pages/invoices-list.page.js"),
+  "/invoices/:id": () => import("./pages/invoice-detail.page.js"),
+};
 ```
 
-- Браузер сам сделает chunk при бандлинге (esbuild --bundle --splitting).
-- Модуль загрузится только при заходе на роут.
-- Между навигациями результат кэшируется.
+Prefix применяет `src/app.routes.ts`, когда module монтируется под
+`"/billing"`.
 
-### 2. Готовая Page (eager)
+## Layout Group
 
 ```ts
-import about from './pages/about.js';
-
-'/about': about,
+"/admin": layout({
+  layout: () => import("./layouts/app-shell.layout.js"),
+  guard: requireAuth,
+  routes: adminRoutes,
+}),
 ```
 
-Сразу в графе, без задержек. Используй для критичных страниц (home, login).
-
-### 3. Nested с layout
+Layout — обычный `page({...})` file:
 
 ```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';
+import { html, page } from "@madojs/mado";
 
 export default page({
   view: ({ child }) => html`
-    <div class="admin">
-      <aside><nav>...</nav></aside>
-      <main>${child}</main>
+    <div class="layout layout--app">
+      <main class="app-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-экспорт.
-```
+Layout view держим stateless. Page-specific signals, resources и forms живут в
+pages/components/resources, не в layout locals.
 
-## Параметры URL
+## Page Contract
 
 ```ts
-'/users/:id': () => import('./pages/user.js'),
-```
+import { html, page } from "@madojs/mado";
 
-```ts
 export default page<{ id: string }>({
   title: ({ id }) => `User ${id}`,
-  view:  ({ params }) => html`<h1>${params.id}</h1>`,
+  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}/>`,
-  },
-);
-```
-
-## Программная навигация
+## Navigation
 
 ```ts
-import route from './routes.js';
+import appRoutes from "./app.routes.js";
 
-route.navigate('/posts');
-route.navigate('/posts?page=2');
-route.navigate('/posts', { replace: true });
+appRoutes.navigate("/billing/invoices");
+appRoutes.navigate("/billing/invoices?page=2");
+appRoutes.navigate("/login", { replace: true });
 ```
 
-Клики по `<a href="/foo" data-link>` перехватываются глобально (без атрибута — браузер сделает full reload, как и положено для внешних ссылок).
-
-## Query-параметры
+## Query Parameters
 
 ```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.
-
-## Что осознанно отсутствует
+import { queryParam } from "@madojs/mado";
 
-- ❌ Авто-сканирование `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'),
-});
+const page = queryParam("page", "1");
+page();
+page.set("2");
+page.set(null);
+page.set("3", { push: true });
 ```
 
-**Как тестировать роутинг?**
-Импортируешь `routes.ts` — это просто объект. Подставляешь свой mock-router. Никакой эмуляции сборщика не нужно.
+## Чего нет намеренно
 
-**Code splitting работает?**
-Да. При `esbuild --bundle --splitting --format=esm` каждый `() => import('./pages/x.js')` становится отдельным chunk'ом.
+- Auto-scan of page folders.
+- Filesystem syntax вроде `[id]`, `(group)`, `_layout`.
+- Server routes в client manifest.
+- Hidden layout discovery.

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

@@ -1,57 +1,84 @@
-# Project layout
+# Project Layout
 
-Каждый new-проект на Mado имеет одинаковую структуру. Это **обязательное** соглашение.
+Каждое Mado-приложение использует одну каноничную форму. Это не примерная
+рекомендация, а соглашение, чтобы люди и AI-ассистенты одинаково понимали,
+куда класть код.
 
-```
+```txt
 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, манифесты)
+├── package.json              # runtime dep: @madojs/mado
+├── tsconfig.json             # strict TS, ES2022, Bundler resolution
+├── vite.config.ts            # mado() from @madojs/mado/vite
+├── index.html                # Vite entry + SPA shell
+├── public/                   # статика: favicon, images, robots.txt
 └── 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          # темы
-        └── ...               # утилиты, типы, бизнес-правила
+    ├── main.ts               # импорт CSS и mount router в #app
+    ├── app.routes.ts         # app map: manifest + default routes(...)
+    ├── layouts/              # layouts app-зон, не доменные модули
+    ├── shared/               # ui, http, lib, styles
+    └── modules/              # bounded contexts
+        └── billing/
+            ├── billing.routes.ts
+            ├── billing.public.ts
+            ├── billing.types.ts
+            ├── pages/
+            ├── data/
+            ├── api/
+            └── _contracts/
 ```
 
+## Artifact States
+
+| Folder | Что это | Кто пишет | Deploy? |
+| --- | --- | --- | --- |
+| `src/` | исходники TypeScript | ты | no |
+| `public/` | статика, копируется как есть | ты | через `out/` |
+| `out/` | deploy artifact: SPA shell + assets + baked HTML | `mado release` | yes |
+
+`mado release` = `typecheck` + Vite build (`out/index.html`, `out/assets/`,
+`public/*`) + `bake` прямо в route paths + `sitemap.xml` + precompression.
+
+`index.html` лежит в корне, потому что для Vite это entry template. В
+`public/` кладите только файлы, которые нужно скопировать как есть.
+
 ## Куда положить новый файл?
 
 | Что | Куда |
-|---|---|
-| Страница на новый 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/`.
+| --- | --- |
+| Страница на новый URL | `src/modules/<module>/pages/<name>.page.ts` + module routes |
+| Module route map | `src/modules/<module>/<module>.routes.ts` |
+| App shell/layout | `src/layouts/<zone>.layout.ts` |
+| Shared UI widget | `src/shared/ui/<x-name>.component.ts` |
+| Module-only UI widget | `src/modules/<module>/components/<name>.component.ts` |
+| API connector | `src/modules/<module>/api/<provider>.connector.ts` |
+| Data resource/mutation | `src/modules/<module>/data/<name>.resource.ts` |
+| Auth/session | `src/modules/auth/` |
+| Public module surface | `src/modules/<module>/<module>.public.ts` |
+| Pure function без UI | `src/shared/lib/<name>.ts` |
+| Static image / favicon | `public/<file>` |
+| App-zone shell CSS | `src/shared/styles/shell.css` |
+| Page-level CSS | `src/shared/styles/content.css` |
+
+## Vite Config
+
+```ts
+import { defineConfig } from "vite";
+import { mado } from "@madojs/mado/vite";
+
+export default defineConfig({
+  plugins: [mado()],
+  css: {
+    transformer: "lightningcss",
+  },
+});
+```
+
+Starter включает Vite Lightning CSS transformer. Mado не владеет prefixing,
+CSS lowering или minification.
+
+## Что НЕ кладём в `src/`
+
+- Лишние build-tool configs — настройка живет в `vite.config.ts`.
+- `.env` files — читайте env в `src/shared/lib/config.ts` и импортируйте этот
+  модуль.
+- Tests рядом с кодом — держите их в `test/`.

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

@@ -100,7 +100,7 @@ export default routes(manifest, { titleSuffix: " · MyShop" });
 ## Запуск
 
 ```bash
-npm install -D linkedom esbuild
+npm install -D linkedom vite
 npm run build
 npm run bake
 ```
@@ -144,7 +144,7 @@ out/
     {"slug":"mado-mug","name":"Mado-кружка","price":12,"..."}
   </script>
 
-  <script type="module" src="/dist/examples/main.js"></script>
+  <script type="module" src="/assets/index-HASH.js"></script>
 </body>
 ```
 

package/docs/ru/05-why-mado.md

@@ -31,11 +31,11 @@ Mado — не «убийца» React/Vue/Svelte. Это узкоспециали
 | Размер | ~6 КБ | ~16 КБ |
 | Возраст / поддержка | ~10 лет, Google | 6 месяцев, один автор |
 | Реактивность | декораторы `@property` + ручной `requestUpdate` | сигналы (`signal`/`computed`/`effect`) из коробки |
-| Роутер | нет, нужно искать (`@lit-labs/router`, etc) | в комплекте: `routes()` + nested + prefetch + sync-cache |
+| Роутер | нет, нужно искать (`@lit-labs/router`, etc) | в комплекте: `routes()` + layout groups + prefetch |
 | Data fetching | нет, нужно собирать | `resource()` + `mutation()` + glob-инвалидация |
 | Формы | нет | `useForm()` с HTML-like constraints |
 | SEO / static | сложно (`@lit-labs/ssr`) | `bake` (linkedom) + edge-prerender |
-| Билд | нужен esbuild/rollup/webpack | хватает `tsc` |
+| Билд | нужны framework-specific build plugins | Vite transport + native runtime |
 | Стиль кода | классы + декораторы | функции + tagged templates |
 | Экосистема | реальная (Shoelace, Material Web, и т.д.) | нет |
 | Когда выбрать | пишете дизайн-систему / Web-Components-библиотеку для встраивания | пишете приложение целиком, хотите всё в одной коробке |
@@ -55,14 +55,14 @@ Mado — не «убийца» React/Vue/Svelte. Это узкоспециали
 | Реактивность | сигналы (тот же класс идей) | сигналы |
 | Шаблоны | JSX (компилируется в реактивные expressions) | tagged template `html\`\`` |
 | Компонентная модель | функции, виртуальные узлы Solid | Web Components |
-| Билд | Vite + babel-plugin-solid обязательны | только `tsc` |
+| Билд | Vite + babel-plugin-solid обязательны | Vite для dev/build, без runtime-зависимостей |
 | Роутер | `@solidjs/router` | в комплекте |
 | Data | `createResource` | `resource()` |
 | SSR | поддерживается серьёзно (SolidStart) | намеренно нет |
 | Экосистема | растёт, ~50 пакетов | нет |
-| Когда выбрать | нужен топовый перф + JSX + готов настраивать билд | хотите запустить без билда / минимум инфраструктуры |
+| Когда выбрать | нужен топовый перф + JSX + готов настраивать билд | нужен browser-native runtime с простым tooling |
 
-**Честный pitch:** *«Solid технически быстрее и зрелее. Но Solid требует Vite + babel-плагин. Mado не требует ничего, кроме `tsc` — это «открой VS Code, F5 и работай». Если эта разница не критична — берите Solid.»*
+**Честный pitch:** *«Solid технически быстрее и зрелее. Mado проще концептуально: browser-native runtime, Web Components, tagged templates, а Vite забирает на себя скучный dev/build. Если нужны JSX и большая экосистема — берите Solid.»*
 
 ---
 
@@ -153,7 +153,7 @@ Mado — не «убийца» React/Vue/Svelte. Это узкоспециали
 
 Не размер, не перф, не сигналы — у всего этого есть конкуренты лучше.
 
-> **«Открой исходник и прочитай его за вечер. ~3500 строк, 12 модулей. Если что-то сломалось — ты не идёшь в issue на 3000 комментариев. Ты идёшь в `src/router.ts` и читаешь 500 строк.»**
+> **«Открой исходник и прочитай его за вечер. ~3500 строк, маленькие модули. Если что-то сломалось — ты не идёшь в issue на 3000 комментариев. Ты идёшь в `src/router/` и читаешь код.»**
 
 Это называется **ownership** — ты владеешь кодом, а не зависишь от чужого.
 

package/docs/ru/06-for-backenders.md

@@ -13,7 +13,7 @@ Mado устроен **как HTTP-сервер**. Серьёзно:
 |---|---|
 | HTTP-роутер (chi, axum, mux) | `routes()` — манифест путей |
 | Handler `func(req, resp)` | `page({ view: (ctx) => html\`...\` })` |
-| Middleware | `layout` в `nested()` (оборачивает handler) |
+| Middleware | route group через `layout()` (оборачивает handler) |
 | Шаблонизатор (Jinja, Handlebars) | `html\`\`` tagged template |
 | HTTP-клиент с кешем | `resource()` — fetch + cache + invalidation |
 | Reactive variable / atom | `signal()` — реактивный геттер |
@@ -350,17 +350,17 @@ export default page({
 ```
 
 ```ts
-// src/routes.ts
-import { routes, nested } from "@madojs/mado";
+// src/app.routes.ts
+import { layout, routes } from "@madojs/mado";
 
 export default routes({
   "/login": () => import("./pages/login.js"),
 
-  "/app/*": nested({
+  "/app": layout({
     layout: () => import("./layouts/auth-layout.js"),
     routes: {
-      "dashboard": () => import("./pages/dashboard.js"),
-      "users": () => import("./pages/users.js"),
+      "/dashboard": () => import("./pages/dashboard.js"),
+      "/users": () => import("./pages/users.js"),
     },
   }),
 });
@@ -423,6 +423,6 @@ export const api = new ApiClient("/api");
 - **[`01-routing.md`](./01-routing.md)** — детально про роутер.
 - **[`02-project-layout.md`](./02-project-layout.md)** — структура проекта.
 - **[`03-static-bake.md`](./03-static-bake.md)** — SEO без SSR.
-- **[`examples/showcase/`](../../examples/showcase/)** — полный пример (landing + admin).
+- **Внешний workspace `madojs-examples`** — полные демо (landing + admin).
 
 Если что-то непонятно — open issue, или просто открой исходник. Это правда читается за вечер.

package/docs/ru/08-llm-zero-history-test.md

@@ -13,15 +13,15 @@
 - `AGENTS.md`
 - `README.md`
 - `docs/en/07-llm-pitfalls.md`
-- `examples/basic/README.md` если нужен минимальный обзор API
-- конкретные файлы из `examples/showcase/**` только если агент сам попросит паттерн более крупного приложения
+- файлы из внешнего workspace `madojs-examples` только если агент сам попросит
+  паттерн более крупного приложения
 
 Агент может искать целевые API в `src/` когда заблокирован, но не должен
 загружать весь фреймворк в контекст.
 
 ## Задание
 
-Построить `examples/tickets`: маленький ticket-admin SPA для соло/бекенд-разработчика.
+Построить маленький ticket-admin SPA для соло/бекенд-разработчика.
 
 Требуемое поведение:
 
@@ -48,15 +48,10 @@
 
 ## Заметки по результатам
 
-Текущая реализация `examples/tickets` не потребовала новых публичных API или
-runtime-зависимостей.
+Историческая реализация tickets живет во внешнем workspace `madojs-examples`.
+Core-репозиторий больше не поставляет этот артефакт и отдельную smoke-команду;
+используйте этот документ как ручной сценарий оценки при обновлении LLM-guidance.
 
-CI запускает `npm run llm:smoke` как детерминированный proxy для этой задачи:
-проверяет, что `llms.txt` всё ещё содержит ключевые правила, сверяет
-зафиксированный артефакт `examples/tickets` с нужной Mado API surface и
-failure patterns, затем собирает проект и запускает `test/tickets-smoke.test.mjs`.
-
-Основная болевая точка в документации остается lifecycle: старые примеры могут
-создать впечатление, что создание `resource()` прямо в `page.view()` допустимо.
-Пример tickets использует page-level wrapper-компоненты вместо этого, поэтому
-ресурсы регистрируются внутри component setup и очищаются вместе с компонентом.
+Основная болевая точка в документации остается lifecycle: примеры не должны
+создавать впечатление, что long-lived `resource()` можно случайно держать на
+module scope или в route-коде без cleanup.