@madojs/mado 0.10.0 → 0.11.0

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

@@ -1,36 +1,34 @@
 # LLM Zero-History Test
 
-Мета тесту: перевірити, чи може LLM без попередньої історії написати ідіоматичний
-Mado CRUD, не перетворюючи його на React у tagged templates.
+This document defines a manual validation test: can a fresh LLM write idiomatic
+Mado without falling back to React-shaped code?
 
-## Дозволений контекст
+## Allowed Context
 
 - `AGENTS.md`
 - `README.md`
-- `docs/uk/07-llm-pitfalls.md` або відповідна англійська версія
-- `examples/basic/README.md`
-- конкретні файли прикладів тільки за потреби
+- `docs/uk/07-llm-pitfalls.md` or the English version
+- files from the external `madojs-examples` workspace only when the agent asks
+  for a larger app pattern
 
-## Що перевіряти
+## Task
 
-- Немає JSX, `useState`, `useEffect`.
-- Немає signal `.value`.
-- Reactive child bindings з `count()` обгорнуті у `() =>`.
-- Boolean attributes пишуться як `?disabled`, `?checked`.
-- Динамічні списки використовують `each()`.
-- Imports мають `.js`.
-- `resource()` створюється в lifecycle-aware контексті.
+Build a small ticket-admin SPA:
 
-## Артефакт
+- routes: `/`, `/tickets`, `/tickets/new`, `/tickets/:id`, `*`;
+- in-memory mock API with realistic async delays;
+- list page with `resource()`, `queryParam()`, `computed()` and keyed `each()`;
+- create/edit flows with `useForm()` + `mutation()` + `invalidates`;
+- local UI state with `signal()`.
 
-`examples/tickets` — маленький ticket-admin SPA з routes, mock API, forms,
-resources, mutations, invalidation, `queryParam`, `computed`, `signal` і
-keyed lists.
+## Failure Checklist
 
-CI запускає `npm run llm:smoke` як детермінований proxy для цієї задачі:
-перевіряє, що `llms.txt` містить ключові правила, звіряє закомічений артефакт
-`examples/tickets` з потрібною Mado API surface та failure patterns, потім
-збирає проєкт і запускає `test/tickets-smoke.test.mjs`.
+- JSX, `useState`, `useEffect`, `ref`, `$state`, class-style components;
+- `${signal()}` where a reactive child thunk is required;
+- `disabled=${...}` instead of `?disabled=${...}`;
+- unkeyed `.map()` for dynamic lists;
+- `resource()` created outside lifecycle-aware context;
+- new runtime dependencies or new public APIs.
 
-Критерій успіху: код виглядає як Mado, а не як React/Vue, переодягнений у
-template strings.
+The historical tickets implementation lives in the external examples workspace.
+The core repository no longer ships that artifact.

package/docs/uk/09-shadow-vs-light-dom.md

@@ -1,107 +1,58 @@
 # Shadow DOM vs Light DOM
 
-Mado використовує Shadow DOM за замовчуванням. Це хороший default для
-самодостатніх widgets, але не для кожного компонента в app.
+Mado components use Shadow DOM by default. This is good for self-contained
+widgets, but app zones and pages usually stay as light DOM templates.
 
-## Практичне правило
+## Rule
 
-У Mado layout — це теж component. Якщо файл описує видиму reusable частину
-UI-дерева — app shell, sidebar, modal, table, page section — за замовчуванням
-робіть Web Component через `component()`.
-
-Звичайні функції залишайте для маленьких inline helpers:
-
-```ts
-const money = (value: number) => html`<span>${formatMoney(value)}</span>`;
-```
-
-Не варто робити app shell функцією в public examples. Це працює, але ховає
-browser model замість того, щоб її пояснювати.
-
-Використовуйте **Shadow DOM** для leaf widgets:
-
-- buttons, badges, cards, metrics;
-- modals, toasts, small visual components;
-- embedded widgets, які не мають випадково успадковувати app CSS;
-- components, чиї styles належать самому component.
-
-Використовуйте **Light DOM** (`{ shadow: false }`) для app structure, якій
-потрібні global CSS utilities:
-
-- route/page components;
-- admin screens з dense table/form layouts;
-- data-heavy screens з tables and forms;
-- місця, де children мають залишатися normal document DOM.
-
-Використовуйте **Shadow DOM** для slot-based layouts:
-
-- app shells, які render `<slot>`;
-- sidebar/content wrappers;
-- reusable layout frames, які володіють своїм grid/header/sidebar CSS.
-
-`<slot>` — це feature Shadow DOM. У component з `shadow: false` тег `<slot>` є
-звичайним DOM element і не переносить children у це місце layout.
-
-## Як працює import
+Use route layouts for app zones:
 
 ```ts
-import "./components/app-layout.js";
-
-render(html`<x-app-layout>${router.view}</x-app-layout>`, app);
+export default page({
+  view: ({ child }) => html`<main class="app-main">${child}</main>`,
+});
 ```
 
-Import реєструє custom element через `customElements.define()`. Template створює
-`<x-app-layout>` element. Далі browser сам з'єднує tag з component class. Це не
-React-style component value, який передається як function.
-
-## Routing and links
+These files live in `src/layouts/` and are composed from `src/app.routes.ts`
+with `layout()`. They are styled by `src/shared/styles/shell.css`.
 
-`data-link` працює всередині Shadow DOM, бо router використовує
-`event.composedPath()`.
+Use page files for screens:
 
 ```ts
-component("x-card-link", () => () => html`
-  <a href="/app/accounts" data-link>Accounts</a>
-`);
+export default page({
+  view: () => html`<section><h1>Users</h1></section>`,
+});
 ```
 
-Link може бути в Shadow DOM; navigation все одно залишається SPA.
+Page-level tables, forms, prose and simple states are styled by
+`src/shared/styles/content.css`.
 
-## Де імпортувати компоненти
+Use Shadow DOM components for leaf widgets:
 
-Custom elements стають global після registration, але registration все одно є
-явним JavaScript import.
+- buttons, badges, cards, metrics;
+- spinners, modals, toasts;
+- widgets that should own their CSS.
 
 ```ts
-// main.ts: global app frame
-import "./components/app-shell.js";
-
-// pages/tickets.ts: component, яким володіє ця page
-import "../components/ticket-list.js";
+component("x-status-badge", ({ attr }) => {
+  const status = attr("status", "draft");
+  return () => html`<span>${status}</span>`;
+}, {
+  styles: css`
+    :host { display: inline-block; }
+    span { color: var(--color-text-muted); }
+  `,
+});
 ```
 
-Browser **не** завантажує `ticket-list.js` лише тому, що побачив
-`<ticket-list>`. File має бути imported десь першим. Після import він викликає
-`customElements.define(...)`, і tag стає відомим у поточному document.
-
-Не робіть bulk-import усіх components у `main.ts` "just in case". Це працює в
-tiny demos, але ховає ownership і ламає lazy route loading. Краще:
-
-- global app shell/providers імпортувати в `main.ts`;
-- components, якими володіє одна page, імпортувати в цій page;
-- shared feature components імпортувати у feature entry page;
-- truly global leaf components імпортувати в `main.ts` лише якщо вони реально
-  використовуються всюди.
-
-## Showcase lesson
-
-`examples/showcase` використовує цей split навмисно:
+## Style Behavior
 
-- `x-app` і CRM route pages — Light DOM;
-- `x-app-layout` — Shadow DOM, бо він володіє slot-based sidebar/content shell;
-- table/form/page utilities живуть у `styles/global.ts`;
-- leaf components на кшталт `x-stat-card`, `x-status-badge`, `x-modal`,
-  `x-toast-stack` залишають Shadow DOM.
+- `tokens.css` defines CSS custom properties; `var(...)` crosses Shadow DOM.
+- `reset.css`, `shell.css`, `content.css` apply only to document/light DOM.
+- Class selectors like `.data`, `.app-main`, `.error` do not cross Shadow DOM.
+- Component-local styles live in ``css`...` `` inside `component()` options.
+- If a Shadow component accepts children, use `<slot>` and style the frame in
+  component styles.
 
-Якщо page раптом виглядає unstyled, перевірте, чи не використовує вона global
-classes всередині Shadow DOM component. Зазвичай проблема саме в цьому.
+If a page looks unstyled, you probably used global classes inside a Shadow DOM
+component. Move markup into a page/layout or move CSS into component styles.

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)