@madojs/mado 0.10.1 → 0.11.1

package/docs/ru/10-app-architecture.md

@@ -1,100 +1,152 @@
 # Архитектура приложения
 
-Базовая форма production-приложения на Mado должна быть скучной: один route
-manifest, один shell, один API-клиент, один auth-модуль и страницы, которые
-импортируют свои компоненты.
+Официальный starter — каноничная production-форма Mado-приложения. Это не
+framework внутри framework: только файлы, imports, Mado primitives и ESLint
+boundaries.
 
 ## Структура
 
 ```txt
 src/
 ├── main.ts
-├── routes.ts
+├── app.routes.ts
 ├── layouts/
-│   ├── app.ts
-│   └── auth.ts
-├── pages/
-│   ├── home.ts
-│   ├── login.ts
-│   ├── not-found.ts
-│   └── admin/
-├── components/
-├── lib/
-│   ├── api.ts
-│   └── auth.ts
-└── styles/
+│   ├── app-shell.layout.ts
+│   └── auth-shell.layout.ts
+├── shared/
+│   ├── http/
+│   ├── lib/
+│   ├── styles/
+│   └── ui/
+└── modules/
+    ├── auth/
+    │   ├── auth.routes.ts
+    │   ├── auth.public.ts
+    │   ├── auth.service.ts
+    │   ├── auth.connector.ts
+    │   ├── auth.guard.ts
+    │   ├── login.page.ts
+    │   └── _contracts/
+    └── billing/
+        ├── billing.routes.ts
+        ├── billing.public.ts
+        ├── billing.types.ts
+        ├── api/
+        ├── data/
+        ├── pages/
+        ├── components/
+        └── _contracts/
 ```
 
-`lib/` хранит бизнес-логику, `layouts/` оборачивает группы роутов,
-`components/` хранит переиспользуемые UI-теги, а `pages/` содержит один файл
-на страницу.
+## App Map
 
-## Entry point
-
-```ts
-import { html, render } from "@madojs/mado";
-import "./styles/global.js";
-import "./components/x-button.js";
-import routesApi from "./routes.js";
-
-render(html`${routesApi.view}`, document.getElementById("app")!);
-```
-
-В `main.ts` импортируй только глобальные провайдеры, стили и маленькие общие
-компоненты. Feature-компоненты импортирует страница, которая их рендерит.
-
-## Routes
+`src/app.routes.ts` — карта всего приложения. Modules экспортируют plain route
+maps; app routes решают, какой shell и guard оборачивают каждую зону.
 
 ```ts
 import { layout, routes } from "@madojs/mado";
-import { requireAuth } from "./lib/auth.js";
+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"),
+  "/": () => import("./modules/home/home.page"),
   "/login": layout({
-    layout: () => import("./layouts/auth.js"),
-    routes: { "/": () => import("./pages/login.js") },
+    layout: () => import("./layouts/auth-shell.layout"),
+    routes: authRoutes,
   }),
-  "/admin": layout({
-    layout: () => import("./layouts/app.js"),
+  "/billing": layout({
+    layout: () => import("./layouts/app-shell.layout"),
     guard: requireAuth,
-    routes: {
-      "/": () => import("./pages/admin/dashboard.js"),
-      "/orders": () => import("./pages/admin/orders.js"),
-    },
+    routes: billingRoutes,
   }),
-  "*": () => import("./pages/not-found.js"),
+  "*": () => import("./modules/home/not-found.page"),
 };
 
 export default routes(manifest);
 ```
 
-`export const manifest` нужен для `mado bake`.
+Rules:
 
-## API, forms, release
+- Export `manifest`, чтобы `mado bake` мог найти bakeable pages.
+- Modules не вызывают `layout()`.
+- Layouts описывают app zones, не домены.
+- Router не прячется в custom element или втором shell в `main.ts`.
 
-Держи один API-клиент и один auth-модуль. Для списков используй `resource()`,
-для записей `mutation(..., { invalidates })`, для форм `useForm()`.
+## File Forms
 
-```ts
-const form = useForm({
-  email: { required: true, type: "email" },
-  "items.*.title": { required: true },
-});
-const items = form.array("items");
-```
+| Suffix | Role |
+| --- | --- |
+| `*.page.ts` | route page, default `page({...})` |
+| `*.layout.ts` | app-zone wrapper, default `page(...)` |
+| `*.connector.ts` | one external API system |
+| `*.resource.ts` | `resource()` and `mutation()` layer |
+| `*.service.ts` | module singleton state |
+| `*.guard.ts` | route guard |
+| `*.routes.ts` | module-local route map |
+| `*.public.ts` | only public module surface |
+| `*.types.ts` | domain types |
+| `*.component.ts` | Web Component registration |
 
-Разработка:
+Page-local signals, resources and forms live inside `view()`. Module-wide state
+lives in `*.service.ts`.
 
-```bash
-mado dev
+## Data Flow
+
+```txt
+shared/http/http-client.ts
+        ▲
+modules/<x>/api/*.connector.ts      DTO -> domain mapping
+        ▲
+modules/<x>/data/*.resource.ts      cache keys + mutations
+        ▲
+modules/<x>/pages/*.page.ts         UI consumes domain types
 ```
 
-Продакшен:
+## Module Boundaries
+
+Модуль opaque, кроме `<module>.public.ts`. Другие modules импортируют через этот
+файл или никак. DTO внешних систем лежат в `_contracts/` и остаются private для
+connector.
+
+Default starter enforces this with ESLint:
+
+- no barrels (`index.ts`);
+- no `export *`;
+- no CSS imports outside `src/main.ts`;
+- no cross-module imports except public surfaces;
+- no `_contracts` imports outside connectors.
+
+## Styles
+
+| File | Role |
+| --- | --- |
+| `src/shared/styles/tokens.css` | design tokens as CSS custom properties |
+| `src/shared/styles/reset.css` | document/light DOM reset |
+| `src/shared/styles/shell.css` | app-zone layouts from `src/layouts/` |
+| `src/shared/styles/content.css` | page-level forms, tables, prose and states |
+
+Reusable leaf components keep their own styles in ``css`...` `` inside
+`component()` options and depend on tokens, not global classes.
+
+`vite.config.ts` opts into Vite Lightning CSS transformer. Mado does not own
+prefixing, CSS lowering or minification.
+
+## CLI
+
+Use `mado new` for boring file scaffolding:
 
 ```bash
-mado release
-rsync -avz out/ user@server:/var/www/app/
+mado new module billing
+mado new page billing/pages/invoices-list
+mado new connector billing/api/stripe
+mado new resource billing/data/invoices
+mado new service billing/cart
+mado new form billing/invoice
+mado new component billing/components/invoice-status-badge
+mado new guard billing/billing
+mado new layout app-shell
 ```
 
-Деплоится только `out/`. `dist/` — внутренний результат `tsc`.
+The generator writes files only. It does not edit `app.routes.ts`, does not scan
+the filesystem, and refuses to overwrite existing files.

package/docs/ru/11-layouts.md

@@ -1,47 +1,47 @@
 # Layouts
 
-В Mado blessed-способ для layout — nested route group в `routes.ts`.
-Не заворачивай каждую страницу вручную и не клади общий shell в `main.ts`,
-если в приложении есть разные зоны вроде public/login/admin.
+Blessed layout способ в Mado — route group в `src/app.routes.ts`.
+Не заворачивайте каждую страницу вручную и не кладите общий shell в `main.ts`,
+если есть разные зоны: public, auth, app, embed.
 
 ```ts
 import { layout, routes } from "@madojs/mado";
-import { requireAuth } from "./lib/auth.js";
+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"),
+  "/": () => import("./modules/home/home.page.js"),
   "/login": layout({
-    layout: () => import("./layouts/auth.js"),
-    routes: { "/": () => import("./pages/login.js") },
+    layout: () => import("./layouts/auth-shell.layout.js"),
+    routes: authRoutes,
   }),
-  "/admin": layout({
-    layout: () => import("./layouts/app.js"),
+  "/billing": layout({
+    layout: () => import("./layouts/app-shell.layout.js"),
     guard: requireAuth,
-    routes: {
-      "/": () => import("./pages/admin/dashboard.js"),
-      "/orders": () => import("./pages/admin/orders.js"),
-    },
+    routes: billingRoutes,
   }),
-  "*": () => import("./pages/not-found.js"),
+  "*": () => import("./modules/home/not-found.page.js"),
 };
 
 export default routes(manifest);
 ```
 
-Layout — это обычная `page({ view })`, которая рендерит `child`:
+Layout — обычный `page({ view })`, который рендерит `child`:
 
 ```ts
 export default page({
-  view: ({ child }) => html`<x-app-shell>${child}</x-app-shell>`,
+  view: ({ child }) => html`
+    <div class="layout layout--app">
+      <main class="app-main">${child}</main>
+    </div>
+  `,
 });
 ```
 
-Правила:
+Rules:
 
-- один shell на группу, не на каждую страницу;
-- outer layouts оборачивают inner layouts;
-- guard на группе защищает всю поддеревянную часть;
-- layout можно lazy-load через `() => import(...)`.
-
-Single-shell wrapper в `main.ts` допустим только для приложений, где абсолютно
-все роуты живут в одной оболочке.
+- one shell per route group, not per page;
+- modules export plain route maps and do not call `layout()`;
+- guard on a group protects the whole subtree;
+- layout view stays stateless; page-local state lives in pages/components/resources.

package/docs/ru/12-auth-and-api.md

@@ -1,53 +1,75 @@
 # Auth and API
 
-Mado не навязывает auth, но starter `admin` дает blessed recipe:
+Default starter — blessed recipe. HTTP mechanics живут в `src/shared/http/`,
+auth state — в `src/modules/auth/`.
 
-- `src/lib/api.ts` — один HTTP boundary, `ApiError`, refresh-on-401;
-- `src/lib/auth.ts` — `accessToken`, `restoreSession()`, `login()`,
-  `logout()`, `requireAuth` guard.
+```txt
+src/shared/http/
+  http-client.ts
+  http-error.ts
+  interceptors.ts
 
-Модель:
+src/modules/auth/
+  auth.connector.ts
+  auth.service.ts
+  auth.guard.ts
+  auth.routes.ts
+  auth.public.ts
+  _contracts/
+```
+
+Flow для business module:
+
+```txt
+connector -> resource/mutation -> page
+```
+
+Pages не импортируют DTOs и не вызывают `fetch()` напрямую. Connectors не
+импортируют Mado reactivity или UI.
 
-- access token хранится в памяти через `signal`, не в `localStorage`;
-- HttpOnly refresh cookie восстанавливает сессию после reload;
-- все запросы идут через один API-клиент;
-- protected routes закрываются group guard.
+## Auth Service
+
+Auth state — ES module singleton:
 
 ```ts
-export const requireAuth: Guard = async ({ path }) => {
-  if (accessToken()) return;
-  if (await restoreSession()) return;
-  return { redirect: `/login?return=${encodeURIComponent(path)}`, replace: true };
-};
+const _user = signal<User | null>(null);
+const _token = signal<string | null>(null);
+
+export const user = () => _user();
+export const isAuthed = computed(() => _user() !== null);
 ```
 
-В route manifest:
+Expose only what other modules need through `auth.public.ts`.
+
+## Guards
 
 ```ts
-"/admin": layout({
-  layout: () => import("./layouts/app.js"),
-  guard: requireAuth,
-  routes: { "/": () => import("./pages/admin/dashboard.js") },
-}),
+export function requireAuth(): boolean | string {
+  if (isAuthed()) return true;
+  return "/login";
+}
 ```
 
-Backend contract по умолчанию:
+Use in `src/app.routes.ts`:
 
-| Endpoint | Response | Notes |
-|---|---|---|
-| `POST /api/auth/login` | `{ accessToken }` | ставит HttpOnly refresh cookie |
-| `POST /api/auth/refresh` | `{ accessToken }` | читает refresh cookie |
-| `POST /api/auth/logout` | `204` | очищает cookie |
+```ts
+"/billing": layout({
+  layout: () => import("./layouts/app-shell.layout"),
+  guard: requireAuth,
+  routes: billingRoutes,
+}),
+```
 
-Для dev proxy:
+## Dev Proxy
 
-```jsonc
-{
-  "dev": {
-    "proxy": { "/api": "http://localhost:3000" }
-  }
-}
+```ts
+export default defineConfig({
+  plugins: [mado()],
+  server: {
+    proxy: { "/api": "http://localhost:3000" },
+  },
+});
 ```
 
-Если backend использует другую схему auth, меняй только `api.ts`/`auth.ts`.
-Страницы должны оставаться невинными.
+Rule: `shared/http` knows HTTP, connectors know one external system, resources
+know cache keys, pages know UI, `*.public.ts` is the cross-module surface.

package/docs/ru/13-deployment.md

@@ -10,21 +10,18 @@ mado release
 
 ```txt
 out/
-├── index.html              ← SPA shell или promoted baked HTML для /
-├── assets/                 ← hashed bundles (main-ABC.js, chunk-XYZ.js, ...)
+├── index.html              ← SPA shell или baked HTML для /
+├── assets/                 ← Vite hashed assets
 │   ├── *.gz                ← precompressed gzip
 │   └── *.br                ← precompressed brotli
-├── baked/                  ← копия результата bake для inspection/debugging
-│   ├── <route>/index.html
-│   └── sitemap.xml
-├── <route>/index.html      ← promoted baked HTML для static hosts
+├── <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. Не деплой `dist/`: это внутренний output для dev/build.
+GitHub Pages. Деплоится только `out/`.
 
 ## Preview
 
@@ -35,8 +32,7 @@ mado preview
 
 `mado preview` сервит финальный `out/` как обычный static host: сначала реальные
 файлы (`/<route>/index.html`, если route был baked), потом SPA fallback в
-`index.html`. Preview больше не делает отдельную виртуальную подстановку из
-`out/baked/`, поэтому он проверяет ровно то, что будет загружено на хостинг.
+`index.html`. Preview проверяет ровно то, что будет загружено на хостинг.
 
 ## VPS + nginx
 
@@ -45,8 +41,8 @@ mado release
 rsync -avz --delete out/ user@server:/var/www/myapp/
 ```
 
-В репозитории есть production `nginx.conf`: hashed bundles кешируются immutable,
-HTML идет с `no-cache`, deep links работают через SPA fallback.
+Опциональный nginx-рецепт лежит в `docs/recipes/nginx/`: assets кешируются
+immutable, HTML идет с `no-cache`, deep links работают через SPA fallback.
 
 ## Cloudflare / Netlify
 

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

@@ -55,10 +55,9 @@ export default routes(manifest);
 
 ## Output
 
-Standalone `mado bake` по умолчанию пишет baked pages в `out/baked/`.
-`mado release` использует bundled production shell, оставляет копию в
-`out/baked/` для inspection, промотирует HTML в реальные route paths внутри
-`out/` и копирует sitemap в `out/sitemap.xml`.
+Standalone `mado bake` по умолчанию пишет baked pages прямо в `out/`.
+`mado release` сначала запускает Vite build, затем bake заменяет route HTML
+на месте и пишет sitemap в `out/sitemap.xml`.
 
 ```bash
 mado release
@@ -67,6 +66,9 @@ tree out
 
 Deployable folder — `out/`, не `dist/`.
 
+`mado release --keep-bake-dir` оставляет дополнительную копию `out/baked/`
+только для debugging/inspection.
+
 ## Client Boot
 
 Baked HTML помечает `#app` атрибутом `data-mado-baked`. Это не hydration:
@@ -85,5 +87,9 @@ Bake намеренно падает громко вместо записи `[ob
 
 ## Canonical Links
 
-Передай `--base-url` или задай `bake.baseUrl` в `mado.config.json`, чтобы
-canonical links и sitemap указывали на production.
+Передай `--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.