@madojs/mado 0.10.0 → 0.11.0

package/docs/ru/13-deployment.md

@@ -1,6 +1,6 @@
 # Deployment
 
-Один command, один artifact:
+Одна команда, один deploy artifact:
 
 ```bash
 mado release
@@ -10,15 +10,18 @@ mado release
 
 ```txt
 out/
-├── index.html
-├── assets/
-├── baked/
-├── _redirects
-└── _headers
+├── index.html              ← SPA shell или baked HTML для /
+├── assets/                 ← Vite hashed assets
+│   ├── *.gz                ← precompressed gzip
+│   └── *.br                ← precompressed brotli
+├── <route>/index.html      ← baked HTML для static hosts
+├── sitemap.xml             ← sitemap в root сайта
+├── _redirects              ← Cloudflare Pages / Netlify SPA fallback
+└── _headers                ← cache rules
 ```
 
 `out/` можно деплоить на nginx, Cloudflare Pages, Netlify, S3/CloudFront или
-GitHub Pages.
+GitHub Pages. Деплоится только `out/`.
 
 ## Preview
 
@@ -27,8 +30,9 @@ mado release
 mado preview
 ```
 
-`mado preview` сервит `out/` как статический хост: baked HTML имеет приоритет,
-а неизвестные пути падают в SPA fallback.
+`mado preview` сервит финальный `out/` как обычный static host: сначала реальные
+файлы (`/<route>/index.html`, если route был baked), потом SPA fallback в
+`index.html`. Preview проверяет ровно то, что будет загружено на хостинг.
 
 ## VPS + nginx
 
@@ -37,8 +41,8 @@ mado release
 rsync -avz --delete out/ user@server:/var/www/myapp/
 ```
 
-В репозитории есть production `nginx.conf`: hashed bundles кешируются
-immutably, HTML идет с `no-cache`, deep links работают через SPA fallback.
+Опциональный nginx-рецепт лежит в `docs/recipes/nginx/`: assets кешируются
+immutable, HTML идет с `no-cache`, deep links работают через SPA fallback.
 
 ## Cloudflare / Netlify
 
@@ -47,9 +51,11 @@ mado release
 npx wrangler pages deploy out --project-name=myapp
 ```
 
-`_redirects` и `_headers` генерируются автоматически.
+`_redirects` и `_headers` генерируются автоматически, если ты не положил свои.
+Baked routes промотируются в реальные файлы (`out/<route>/index.html`), поэтому
+static host отдаст их до SPA fallback.
 
-## Cache rules
+## Cache Rules
 
 | Path | Cache-Control |
 |---|---|

package/docs/ru/14-testing.md

@@ -26,7 +26,7 @@ globalThis.document = window.document;
 globalThis.Node = window.Node;
 globalThis.HTMLElement = window.HTMLElement;
 
-const { html, render } = await import("../dist/src/html.js");
+const { html, render } = await import("../dist/src/html/template.js");
 
 test("renders a value", () => {
   const root = document.createElement("div");

package/docs/ru/16-bake-cookbook.md

@@ -1,9 +1,9 @@
-# Bake cookbook
+# Bake Cookbook
 
 `mado bake` рендерит выбранные роуты в статический HTML. Это для SEO и быстрого
 первого ответа, не SSR с hydration.
 
-## Минимальная страница
+## Минимальная Страница
 
 ```ts
 export default page({
@@ -23,9 +23,9 @@ export default page({
 ```
 
 В baked views лучше использовать обычные массивы (`items.map(...)`). Runtime
-директивы вроде `each()` нужны браузеру.
+директивы вроде keyed `each()` нужны браузеру.
 
-## Dynamic routes
+## Dynamic Routes
 
 ```ts
 export default page<{ slug: string }>({
@@ -40,16 +40,56 @@ export default page<{ slug: string }>({
 
 `unsafeHTML()` используй только для доверенного или заранее очищенного HTML.
 
-## Manifest и output
+## Route Manifest
+
+`mado bake` нужен source manifest:
 
 ```ts
 export const manifest = {
   "/": () => import("./pages/home.js"),
   "/blog/:slug": () => import("./pages/blog-post.js"),
 };
+
 export default routes(manifest);
 ```
 
-`mado release` создает deploy artifact в `out/`. Если bake ругается на
-unsupported value, значит в статическую страницу попало runtime-only значение:
-замени `each()` на `items.map(...)` или вынеси интерактивный кусок в клиент.
+## Output
+
+Standalone `mado bake` по умолчанию пишет baked pages прямо в `out/`.
+`mado release` сначала запускает Vite build, затем bake заменяет route HTML
+на месте и пишет sitemap в `out/sitemap.xml`.
+
+```bash
+mado release
+tree out
+```
+
+Deployable folder — `out/`, не `dist/`.
+
+`mado release --keep-bake-dir` оставляет дополнительную копию `out/baked/`
+только для debugging/inspection.
+
+## Client Boot
+
+Baked HTML помечает `#app` атрибутом `data-mado-baked`. Это не hydration:
+клиентский `render()` заменяет baked DOM живыми bindings при старте приложения.
+Так первый ответ содержит SEO/first-paint HTML, а SPA после загрузки работает
+как обычно.
+
+## Unsupported Values
+
+Bake намеренно падает громко вместо записи `[object Object]`. Если baked view
+ругается на unsupported directive:
+
+- замени `each()` на `items.map(...)` в baked markup;
+- интерактивные виджеты оставь в client-only routes;
+- убедись, что все значения сериализуются в статический HTML.
+
+## Canonical Links
+
+Передай `--base-url`, чтобы canonical links и sitemap указывали на production.
+
+```bash
+mado bake --base-url https://example.com
+mado release --base-url https://example.com
+```

package/docs/ru/18-api-freeze-map.md

@@ -9,10 +9,11 @@
 import { component, html, resource, routes, signal } from "@madojs/mado";
 ```
 
-Единственный публичный subpath — side-effect модуль devtools:
+Публичные subpaths — side-effect модуль devtools и Vite integration:
 
 ```ts
 import "@madojs/mado/devtools.js";
+import { mado } from "@madojs/mado/vite";
 ```
 
 Все остальное под `dist/src/` — деталь реализации, даже если файл виден в
@@ -27,7 +28,7 @@ import "@madojs/mado/devtools.js";
 - Templates и directives: `html`, `render`, `each`, `list`, `unsafeHTML`,
   `ref`, `classMap`, `styleMap`.
 - Components и CSS: `component`, `css`, `cssVars`.
-- Routing и pages: `routes`, `router`, `page`, `layout`, `nested`,
+- Routing и pages: `routes`, `router`, `page`, `layout`,
   `navigate`, `queryParam`, `prefetchPath`.
 - Data: `resource`, `mutation`, `invalidate`, `jsonFetcher`, `HttpError`.
 - Forms: `useForm`.
@@ -41,7 +42,8 @@ import "@madojs/mado/devtools.js";
 
 Это не публичный API:
 
-- Package subpaths кроме `@madojs/mado` и `@madojs/mado/devtools.js`.
+- Package subpaths кроме `@madojs/mado`, `@madojs/mado/devtools.js` и
+  `@madojs/mado/vite`.
 - Internals парсера/биндингов: `html/parser.js`, `html/bindings.js`,
   `ChildState`, `EachEntry`.
 - Internals роутера: `router/match.js`, `router/navigation.js`,

package/docs/ru/20-v1-stability.md

@@ -25,7 +25,7 @@ byte, starter copy или diagnostic string заморожены навсегд
   deferred teardown для same-tick moves, cleanup через `ctx.onDispose`.
 - Router/page/resource/form contracts, описанные в English docs.
 - Имена CLI commands и широкий смысл команд (`build`, `dev`, `release`,
-  `bake`, `bundle`, `preview`, `init`, `new`).
+  `bake`, `preview`, `init`, `new`).
 
 Ломать это можно только в major version.
 

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

@@ -2,55 +2,81 @@
 
 > Один зрозумілий шлях. Жорсткі контракти. Мінімум магії.
 
-Mado — фреймворк для команд, що будують адмін-панелі, внутрішні інструменти
-та бізнес-SPA — застосунки, які мають бути простими у розробці та нудними в
-підтримці. Для цього він задає **набір домовленостей**. Якщо їх дотримуватись,
-проєкт залишається читабельним навіть тоді, коли в ньому десятки сторінок і
-кілька розробників.
-
-## Принципи
-
-1. **Один спосіб.** Для типової задачі має бути один канонічний шлях, а не п’ять
-   рівноправних стилів.
-2. **Явність замість магії.** Немає сканерів файлів, прихованих глобалів і
-   неочевидних side effects.
-3. **Платформа спочатку.** Якщо браузер уже має потрібну можливість, Mado дає
-   тонку обгортку, а не переписує платформу.
-4. **Суворий TypeScript.** `tsc --strict` — базовий контракт.
-5. **Нуль runtime-залежностей.** Кожна залежність — це довгострокове
-   зобов’язання.
-
-## Базова структура
-
-```text
+Mado — framework для команд, що будують admin panels, internal tools і
+business SPA. Такі apps мають бути простими у розробці та нудними в підтримці,
+тому Mado обирає чіткі conventions замість п'яти рівноправних стилів.
+
+## Principles
+
+1. **One way.** If code feels unusual, first check whether a canonical helper/API
+   already exists.
+2. **Explicit over magic.** No file-system scanners, implicit globals or hidden
+   side effects.
+3. **Platform first.** Web Components, History API, `<form>`, `fetch` and Shadow
+   DOM stay visible.
+4. **Strict types.** `tsc --strict --noUncheckedIndexedAccess` always.
+5. **No runtime dependencies.** Dev/build tooling is fine; Mado runtime stays
+   native.
+
+## Project Structure
+
+```txt
 src/
-├── routes.ts
-├── main.ts
-├── pages/
-├── components/
-├── layouts/
-├── lib/
-└── styles/
+├── main.ts           ← boot: global CSS/providers + render router
+├── app.routes.ts     ← readable app map, exports `manifest` + default routes()
+├── layouts/          ← app-zone wrappers (`page({ view: ({ child }) => ... })`)
+├── shared/           ← UI bricks, http client, pure lib, global CSS
+└── modules/          ← bounded contexts
+    └── billing/
+        ├── billing.routes.ts
+        ├── billing.public.ts
+        ├── billing.types.ts
+        ├── pages/
+        ├── data/
+        ├── api/
+        └── _contracts/
+```
+
+The default starter is the canonical version of this shape.
+
+## One Component = One File
+
+```ts
+import { component, css, html } from "@madojs/mado";
+
+component("x-user-card", () => () => html`<div class="card"><slot></slot></div>`, {
+  styles: css`
+    .card { padding: 1rem; }
+  `,
+});
 ```
 
-Кожна сторінка живе в окремому файлі та експортує `page({...})`.
-Компоненти реєструються через `component()`. Дані читаються через `resource()`,
-зміни виконуються через `mutation()`, списки рендеряться через `each()`.
+Importing the component file registers the element. Import it where the tag is
+used.
 
-## Імена компонентів
+## One Way To Describe A Page
+
+```ts
+import { html, page, resource, jsonFetcher } from "@madojs/mado";
+
+export default page({
+  title: ({ id }) => `User #${id}`,
+  view: ({ params }) => {
+    const user = resource(() => `/api/users/${params.id}`, jsonFetcher());
+    return html`...`;
+  },
+});
+```
 
-Єдине правило браузера: ім’я custom element має містити дефіс. `x-*` у прикладах
-Mado — це демо-конвенція, а не вимога фреймворку. У production краще брати
-префікс домену: `app-*`, `crm-*`, `ticket-*`, `admin-*`.
+Page-local signals, resources and forms live inside `view()`. Module-wide state
+lives in `*.service.ts`.
 
-## Чого не робимо
+## What We Do Not Do
 
-- Не пишемо JSX або Vue-шаблони.
-- Не читаємо сигнал через `.value`; сигнал читається як функція: `count()`.
-- Не використовуємо `disabled=${...}` для булевих атрибутів; треба
-  `?disabled=${...}`.
-- Не рендеримо динамічні списки через `.map()` там, де потрібне збереження DOM
-  стану; використовуємо `each()`.
-- Не додаємо runtime-залежності без дуже вагомої причини.
+- No JSX/Vue/Svelte syntax.
+- No custom elements without a hyphen.
+- No signal `.value`; a signal is a function.
+- No direct `innerHTML`.
+- No runtime packages without discussion.
 
-Коли є сумнів, краще додати рецепт у документацію, ніж новий primitive в core.
+When in doubt, document one clear recipe instead of adding a new core primitive.

package/docs/uk/01-routing.md

@@ -1,76 +1,70 @@
-# Маршрутизація
+# Routing
 
-Mado використовує явний route manifest: один файл показує весь URL-граф
-застосунку.
+> One app map. No folder scanners. No magic path syntax.
+
+Mado uses an explicit route manifest. Route composition should be readable in
+one place: `src/app.routes.ts`.
 
 ```ts
-import { routes } from "@madojs/mado";
+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("./pages/home.js"),
-  "/users/:id": () => import("./pages/user-detail.js"),
-  "*": () => import("./pages/not-found.js"),
+  "/": () => 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);
 ```
 
-## Сторінка
-
-```ts
-import { page, html } from "@madojs/mado";
-
-export default page<{ id: string }>({
-  title: ({ id }) => `User ${id}`,
-  view: ({ params }) => html`<x-user data-id=${params.id}></x-user>`,
-});
-```
+Export `manifest` so `mado bake` can read it.
 
-Сторінка може мати `title`, `head`, `load`, `view`, `errorView` і `bake`.
-Маршрут може бути lazy import або готовим `page({...})`.
+## Module Routes
 
-## Nested routes
+Modules export plain route maps. They do not call `layout()`.
 
 ```ts
-import { nested, routes } from "@madojs/mado";
-
-export const manifest = {
-  "/": () => import("./pages/home.js"),
-  "/app": nested({
-    layout: () => import("./layouts/app-layout.js"),
-    routes: {
-      "/dashboard": () => import("./pages/dashboard.js"),
-      "/settings": () => import("./pages/settings.js"),
-    },
-  }),
+export const billingRoutes = {
+  "/invoices": () => import("./pages/invoices-list.page.js"),
+  "/invoices/:id": () => import("./pages/invoice-detail.page.js"),
 };
-
-export default routes(manifest);
 ```
 
-Layout отримує дочірній view і може рендерити shell: nav, sidebar, toolbar,
-notifications.
+The prefix is applied by `src/app.routes.ts`.
 
-## Навігація
+## Page
 
-Посилання з `data-link` перехоплюються роутером:
+```ts
+import { html, page } from "@madojs/mado";
 
-```html
-<a href="/users/42" data-link>Open</a>
+export default page<{ id: string }>({
+  title: ({ id }) => `User ${id}`,
+  view: ({ params }) => html`<h1>${params.id}</h1>`,
+});
 ```
 
-Програмна навігація:
+## Navigation
 
 ```ts
-import { navigate } from "@madojs/mado";
+import appRoutes from "./app.routes.js";
 
-navigate("/users/42");
+appRoutes.navigate("/billing/invoices");
+appRoutes.navigate("/billing/invoices?page=2");
+appRoutes.navigate("/login", { replace: true });
 ```
 
-Router підтримує hover-prefetch, stale async guard, scroll-to-top для нової
-навігації та `dispose()` для тестів/dev overlay.
-
-## Query params
+## Query Params
 
 ```ts
 import { queryParam } from "@madojs/mado";
@@ -79,4 +73,4 @@ const search = queryParam("q", "");
 search.set("mado");
 ```
 
-`queryParam()` повертає signal-like API і синхронізує стан із URL.
+`queryParam()` returns a signal-like API and syncs state with the URL.

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

@@ -1,46 +1,73 @@
 # Структура проєкту
 
-Рекомендована структура Mado-застосунку:
-
-```text
-src/
-├── main.ts
-├── routes.ts
-├── pages/
-├── components/
-├── layouts/
-├── lib/
-└── styles/
+Кожен Mado-застосунок використовує одну канонічну форму. Це потрібно, щоб люди
+й AI-асистенти однаково розуміли, де живе код.
+
+```txt
+my-app/
+├── 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/                   # static assets: favicon, images, robots.txt
+└── src/
+    ├── main.ts               # imports CSS and mounts router into #app
+    ├── app.routes.ts         # app map: manifest + default routes(...)
+    ├── layouts/              # app-zone layouts
+    ├── shared/               # ui, http, lib, styles
+    └── modules/              # bounded contexts
+        └── billing/
+            ├── billing.routes.ts
+            ├── billing.public.ts
+            ├── billing.types.ts
+            ├── pages/
+            ├── data/
+            ├── api/
+            └── _contracts/
 ```
 
-## `main.ts`
-
-Точка входу: встановлює глобальні стилі, провайдери контексту та монтує кореневий
-компонент у `#app`.
-
-## `routes.ts`
-
-Єдиний manifest маршрутів. Немає file-system routing, груп у назвах папок або
-прихованих conventions.
-
-## `pages/`
-
-Одна сторінка — один файл — `export default page({...})`.
-
-## `components/`
-
-Повторно використовувані Web Components. Імпорт файлу реєструє компонент як side
-effect.
-
-## `layouts/`
-
-Shell для nested routes: admin layout, marketing layout, authenticated area.
-
-## `lib/`
-
-API-клієнти, contexts, чиста бізнес-логіка без UI.
-
-## `styles/`
+## Artifact States
+
+| Folder | Що це | Хто пише | Deploy? |
+| --- | --- | --- | --- |
+| `src/` | TypeScript sources | ви | no |
+| `public/` | static assets copied as-is | ви | via `out/` |
+| `out/` | deploy artifact: SPA shell + assets + baked HTML | `mado release` | yes |
+
+`mado release` = `typecheck` + Vite build (`out/index.html`, `out/assets/`,
+`public/*`) + `bake` directly into route paths + `sitemap.xml` + precompression.
+
+## Where To Put Files
+
+| What | Where |
+| --- | --- |
+| Page for a new 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 without 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",
+  },
+});
+```
 
-Глобальні tokens або shared CSS через `css```. Для app-shell часто зручно
-використовувати Light DOM, для leaf-компонентів — Shadow DOM.
+Starter uses Vite's Lightning CSS transformer. Mado does not own prefixing, CSS
+lowering or minification.

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

@@ -42,8 +42,7 @@ export default page<{ slug: string }, Product>({
 ## Edge prerender
 
 Для великих наборів сторінок можна робити той самий підхід на edge: Cloudflare
-Worker генерує HTML на cache miss, кладе в KV і віддає з TTL. Приклад лежить в
-`examples/cloudflare`.
+Worker генерує HTML на cache miss, кладе в KV і віддає з TTL.
 
 Це не hydration. Клієнтський Mado-застосунок все одно стартує нормально і
 перерендерює сторінку після завантаження.

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

@@ -7,7 +7,7 @@
 |---|---|
 | router | `routes()` |
 | handler | `page().view` |
-| middleware/layout | `nested()` + layout |
+| middleware/layout | `layout()` route group |
 | cache get-or-set | `resource()` |
 | POST/PUT/DELETE | `mutation()` |
 | cache invalidation | `invalidates` / `invalidate()` |
@@ -44,8 +44,8 @@ Mado використовує schema-based validation, близьку до HTML
 
 ## Auth
 
-Auth зазвичай живе в `lib/auth.ts` як signal/context. Protected area зручно
-робити через nested layout, який перевіряє session і показує dashboard або
+Auth зазвичай живе в `modules/auth` як signal/context. Protected area зручно
+робити через `layout()` group, який перевіряє session і показує dashboard або
 redirect/login.
 
 ## Правило