@madojs/mado 0.10.1 → 0.11.1

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

@@ -1,56 +1,97 @@
 # Архітектура застосунку
 
-Production-застосунок на Mado має бути простим: один manifest маршрутів, один
-shell, один API-клієнт, один auth-модуль і сторінки, які імпортують власні
-компоненти.
+Офіційний starter — канонічна production-форма Mado-застосунку. Це не
+framework всередині framework: лише files, imports, Mado primitives та ESLint
+boundaries.
 
 ```txt
 src/
 ├── main.ts
-├── routes.ts
+├── app.routes.ts
 ├── layouts/
-├── pages/
-├── components/
-├── lib/
-└── 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/` — один файл на сторінку.
-
-```ts
-import { html, render } from "@madojs/mado";
-import "./styles/global.js";
-import routesApi from "./routes.js";
-
-render(html`${routesApi.view}`, document.getElementById("app")!);
-```
-
-Feature-компоненти імпортує сторінка, яка їх рендерить.
+`src/app.routes.ts` is the app map. Modules export plain route maps; app routes
+decide which shell and guard wrap each zone.
 
 ```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"),
-  "/admin": layout({
-    layout: () => import("./layouts/app.js"),
+  "/": () => import("./modules/home/home.page"),
+  "/login": layout({
+    layout: () => import("./layouts/auth-shell.layout"),
+    routes: authRoutes,
+  }),
+  "/billing": layout({
+    layout: () => import("./layouts/app-shell.layout"),
     guard: requireAuth,
-    routes: { "/": () => import("./pages/admin/dashboard.js") },
+    routes: billingRoutes,
   }),
-  "*": () => import("./pages/not-found.js"),
+  "*": () => import("./modules/home/not-found.page"),
 };
 
 export default routes(manifest);
 ```
 
-`manifest` потрібен для `mado bake`. Для читання використовуй `resource()`, для
-запису `mutation(..., { invalidates })`, для форм `useForm()`.
+Page-local signals, resources and forms live inside `view()`. Module-wide state
+lives in `*.service.ts`.
+
+## 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 |
+
+Leaf components keep their own styles in ``css`...` `` inside `component()`
+options and depend on tokens, not global classes.
+
+`vite.config.ts` uses Vite's Lightning CSS transformer. Mado does not own
+prefixing, CSS lowering or minification.
+
+## CLI
 
 ```bash
-mado dev
-mado release
+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/`.
+The generator writes files only and does not edit `app.routes.ts`.

package/docs/uk/11-layouts.md

@@ -1,34 +1,47 @@
 # Layouts
 
-Рекомендований спосіб layout у Mado — вкладена група маршрутів у `routes.ts`.
+The blessed layout recipe in Mado is a route group in `src/app.routes.ts`.
+Do not put a single global shell in `main.ts` when the app has multiple zones:
+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") },
+    routes: billingRoutes,
   }),
+  "*": () => import("./modules/home/not-found.page.js"),
 };
 
 export default routes(manifest);
 ```
 
-Layout — це `page({ view })`, яка рендерить `child`:
+A layout is a normal `page({ view })` that renders `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>
+  `,
 });
 ```
 
-Один shell на групу, не на кожну сторінку. Guard на групі захищає все
-піддерево.
+Rules:
+
+- 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/uk/12-auth-and-api.md

@@ -1,34 +1,70 @@
-# Auth та API
+# Auth and API
 
-Starter `admin` містить рекомендований рецепт:
+The default starter is the blessed recipe. HTTP mechanics live in
+`src/shared/http/`, auth state lives in `src/modules/auth/`.
 
-- `src/lib/api.ts` — один HTTP-клієнт, `ApiError`, refresh після 401;
-- `src/lib/auth.ts` — `accessToken`, `restoreSession()`, `login()`,
-  `logout()`, `requireAuth`.
+```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/
+```
+
+Business module flow:
+
+```txt
+connector -> resource/mutation -> page
+```
 
-- access token у пам'яті через `signal`, не в `localStorage`;
-- HttpOnly refresh cookie відновлює сесію;
-- усі запити проходять через API-клієнт;
-- захищені routes використовують group guard.
+Pages do not import DTOs and do not call `fetch()` directly. Connectors do not
+import Mado reactivity or UI.
+
+## Auth Service
 
 ```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);
 ```
 
-Dev proxy:
+Expose only what other modules need through `auth.public.ts`.
 
-```jsonc
-{
-  "dev": {
-    "proxy": { "/api": "http://localhost:3000" }
-  }
+## Guards
+
+```ts
+export function requireAuth(): boolean | string {
+  if (isAuthed()) return true;
+  return "/login";
 }
 ```
 
-Якщо backend має іншу auth-схему, змінюй `api.ts`/`auth.ts`, а не сторінки.
+Use in `src/app.routes.ts`:
+
+```ts
+"/billing": layout({
+  layout: () => import("./layouts/app-shell.layout"),
+  guard: requireAuth,
+  routes: billingRoutes,
+}),
+```
+
+## Dev Proxy
+
+```ts
+export default defineConfig({
+  plugins: [mado()],
+  server: {
+    proxy: { "/api": "http://localhost:3000" },
+  },
+});
+```

package/docs/uk/13-deployment.md

@@ -12,7 +12,8 @@ mado release
 out/
 ├── index.html
 ├── assets/
-├── baked/
+├── <route>/index.html
+├── sitemap.xml
 ├── _redirects
 └── _headers
 ```
@@ -35,5 +36,5 @@ mado release
 rsync -avz --delete out/ user@server:/var/www/myapp/
 ```
 
-Наданий `nginx.conf` налаштовує immutable cache для hash bundles, no-cache для
-HTML та fallback для deep links.
+Опційний nginx recipe живе в `docs/recipes/nginx/`: immutable cache для
+`/assets/*`, no-cache для HTML та fallback для deep links.

package/docs/uk/14-testing.md

@@ -20,7 +20,7 @@ const { window } = parseHTML("<!doctype html><html><body></body></html>");
 globalThis.window = window;
 globalThis.document = window.document;
 
-const { html, render } = await import("../dist/src/html.js");
+const { html, render } = await import("../dist/src/html/template.js");
 
 test("renders", () => {
   const root = document.createElement("div");

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

@@ -27,7 +27,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`.

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

@@ -25,7 +25,7 @@ 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`).
+  `preview`, `init`, `new`).
 
 Ламати це можна тільки в major version.
 

package/llms.txt

@@ -79,7 +79,7 @@ import {
   component,
   css, cssVars,
   routes, router, navigate, queryParam, prefetchPath,
-  page, nested,
+  page, layout,
   resource, mutation, invalidate, jsonFetcher,
   useForm,
   createContext, provide, inject,
@@ -147,8 +147,9 @@ Use `jsonFetcher()` for public endpoints, `apiFetcher()` for anything behind aut
 
 ## Layouts and bake
 
-Use `layout()` in `routes.ts` for shared shells. A layout view should be a pure
-wrapper around `${child}` and shared chrome:
+Use `layout()` in `src/app.routes.ts` for shared shells. Modules export plain
+route maps; app routes decide which layout and guard wrap each zone. A layout
+view should be a pure wrapper around `${child}` and shared chrome:
 
 ```ts
 export default page({
@@ -169,17 +170,18 @@ relative `fetch`, and runtime directives like keyed `each()` during bake.
 ```ts
 // src/main.ts
 import { html, render } from "@madojs/mado";
-import routesApi from "./routes.js";
+import routesApi from "./app.routes.js";
 render(html`${routesApi.view}`, document.getElementById("app")!);
 
-// src/routes.ts
+// src/app.routes.ts
 import { routes } from "@madojs/mado";
-export default routes({
-  "/": () => import("./pages/home.js"),
-  "*": () => import("./pages/not-found.js"),
-});
+export const manifest = {
+  "/": () => import("./modules/home/home.page.js"),
+  "*": () => import("./modules/home/not-found.page.js"),
+};
+export default routes(manifest);
 
-// src/pages/home.ts
+// src/modules/home/home.page.ts
 import { page, component, html, css, signal } from "@madojs/mado";
 
 component("x-counter", () => {
@@ -254,10 +256,7 @@ export default page({
 - docs/en/18-api-freeze-map.md — stable public API vs internal implementation details
 - docs/en/19-reactivity-ordering.md — signal ordering, batching and teardown guarantees
 - docs/en/20-v1-stability.md — v1 SemVer contract and what remains internal
-- examples/basic/ — minimal API tour
-- examples/tickets/ — LLM zero-history CRUD validation
-- examples/showcase/ — flagship CRM pressure app (auth, nested routes, forms, mutations)
-- examples/cloudflare/ — Edge prerender PoC on Cloudflare Workers
+- starters/default/ — canonical generated app shape
 
 ## What Mado does NOT do (intentionally)
 
@@ -265,7 +264,7 @@ export default page({
 - ❌ Virtual DOM → fine-grained signal updates
 - ❌ SSR with hydration → `bake` static meta-shell or edge-prerender for SEO
 - ❌ Hooks and rules of hooks → signals
-- ❌ Mandatory Webpack/Vite → only `tsc`
+- ❌ Runtime framework dependencies → generated apps use Vite as dev/build tooling
 - ❌ React-Router / TanStack → built-in 500-line `routes()`
 - ❌ React-Query / SWR → built-in `resource()`
 - ❌ Formik / RHF → built-in `useForm()` (HTML5 validation)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@madojs/mado",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "Mado — a calm browser-native SPA framework for internal tools, admin panels and business apps. Routing, forms, state and data fetching without frontend infrastructure overhead.",
   "type": "module",
   "license": "MIT",
@@ -11,7 +11,7 @@
     "signals",
     "tagged-templates",
     "router",
-    "no-build",
+    "vite",
     "tsc",
     "minimal",
     "lit-alternative",
@@ -39,19 +39,20 @@
     "./devtools.js": {
       "types": "./dist/src/devtools.d.ts",
       "import": "./dist/src/devtools.js"
+    },
+    "./vite": {
+      "types": "./dist/src/vite/index.d.ts",
+      "import": "./dist/src/vite/index.js"
     }
   },
   "files": [
     "dist/src",
     "scripts",
-    "server",
     "templates",
     "starters",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
-    "MADO_V1_PLAN.md",
-    "ROADMAP.md",
     "TODO.md",
     "AGENTS.md",
     "llms.txt",
@@ -60,27 +61,33 @@
   "scripts": {
     "build": "node scripts/cli.mjs build",
     "watch": "node scripts/cli.mjs watch",
-    "serve": "node scripts/cli.mjs serve",
     "dev": "node scripts/cli.mjs dev",
-    "bundle": "node scripts/cli.mjs bundle",
     "bake": "node scripts/cli.mjs bake",
     "preview": "node scripts/cli.mjs preview",
-    "test:browser": "node scripts/cli.mjs test browser",
     "new": "node scripts/cli.mjs new",
-    "examples": "node scripts/cli.mjs examples",
     "size": "node scripts/size-budget.mjs",
     "package:smoke": "node scripts/package-smoke.mjs",
-    "llm:smoke": "node scripts/llm-zero-history-smoke.mjs",
     "test": "node scripts/cli.mjs test",
     "typecheck": "node scripts/cli.mjs typecheck",
     "clean": "rm -rf dist out",
     "prepublishOnly": "npm run clean && npm run build && npm test"
   },
   "devDependencies": {
+    "@types/node": "^20.19.0",
     "esbuild": "^0.28.0",
+    "lightningcss": "^1.32.0",
     "linkedom": "^0.18.12",
     "playwright-core": "^1.47.0",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16"
+  },
+  "peerDependencies": {
+    "vite": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=20"