@madojs/mado 0.10.1 → 0.11.1

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

@@ -36,11 +36,11 @@ If your case does not fall into the last point — Mado is most likely not the b
 | Size           | ~6 KB                                                          | ~16 KB                                                 |
 | Age / support  | ~10 years, Google                                              | 6 months, single author                                |
 | Reactivity     | `@property` decorators + manual `requestUpdate`                | signals (`signal`/`computed`/`effect`) out of the box  |
-| Router         | none, you need to find one (`@lit-labs/router`, etc)           | included: `routes()` + nested + prefetch + sync-cache  |
+| Router         | none, you need to find one (`@lit-labs/router`, etc)           | included: `routes()` + layout groups + prefetch        |
 | Data fetching  | none, you need to assemble it                                  | `resource()` + `mutation()` + glob invalidation        |
 | Forms          | none                                                           | `useForm()` with HTML-like constraints                 |
 | SEO / static   | complex (`@lit-labs/ssr`)                                      | `bake` (linkedom) + edge-prerender                     |
-| Build          | needs esbuild/rollup/webpack                                   | `tsc` is enough                                        |
+| Build          | needs framework-specific build plugins                         | Vite transport + native runtime                         |
 | Code style     | classes + decorators                                           | functions + tagged templates                           |
 | Ecosystem      | real (Shoelace, Material Web, etc.)                            | none                                                   |
 | When to choose | writing a design system / Web Components library for embedding | writing a full application, want everything in one box |
@@ -60,14 +60,14 @@ If your case does not fall into the last point — Mado is most likely not the b
 | Reactivity      | signals (same class of ideas)                               | signals                                              |
 | Templates       | JSX (compiled to reactive expressions)                      | tagged template `html\`\``                           |
 | Component model | functions, Solid virtual nodes                              | Web Components                                       |
-| Build           | Vite + babel-plugin-solid required                          | `tsc` only                                           |
+| Build           | Vite + babel-plugin-solid required                          | Vite for dev/build, no runtime dependencies          |
 | Router          | `@solidjs/router`                                           | included                                             |
 | Data            | `createResource`                                            | `resource()`                                         |
 | SSR             | seriously supported (SolidStart)                            | intentionally none                                   |
 | Ecosystem       | growing, ~50 packages                                       | none                                                 |
-| When to choose  | need top performance + JSX + willing to configure the build | want to run without a build / minimal infrastructure |
+| When to choose  | need top performance + JSX + willing to configure the build | want browser-native runtime with simple tooling      |
 
-**Honest pitch:** _"Solid is technically faster and more mature. But Solid requires Vite + a babel plugin. Mado requires nothing but `tsc` — it's 'open VS Code, F5, and work'. If that difference isn't critical — go with Solid."_
+**Honest pitch:** _"Solid is technically faster and more mature. Mado is smaller in concept: browser-native runtime, Web Components, tagged templates, and Vite doing the boring dev/build work. If you want JSX and a larger ecosystem, go with Solid."_
 
 ---
 
@@ -162,7 +162,7 @@ I won't dwell on this for long, because React is in a **different weight class**
 
 Not size, not performance, not signals — everything has better competitors.
 
-> **"Open the source and read it in an evening. ~3500 lines, 12 modules. If something breaks — you don't go to an issue with 3000 comments. You go to `src/router.ts` and read 500 lines."**
+> **"Open the source and read it in an evening. ~3500 lines, small modules. If something breaks — you don't go to an issue with 3000 comments. You go to `src/router/` and read the code."**
 
 This is called **ownership** — you own the code, rather than depending on someone else's.
 

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

@@ -14,7 +14,7 @@ Mado is structured **like an HTTP server**. Seriously:
 | ----------------------------------- | ---------------------------------------------- |
 | HTTP router (chi, axum, mux)        | `routes()` — path manifest                     |
 | Handler `func(req, resp)`           | `page({ view: (ctx) => html\`...\` })`         |
-| Middleware                          | `layout` in `nested()` (wraps the handler)     |
+| Middleware                          | `layout()` route group (wraps the handler)     |
 | Template engine (Jinja, Handlebars) | `html\`\`` tagged template                     |
 | HTTP client with cache              | `resource()` — fetch + cache + invalidation    |
 | Reactive variable / atom            | `signal()` — reactive getter                   |
@@ -61,7 +61,7 @@ http.ListenAndServe(":8080", r)
 ### Mado — the same thing
 
 ```ts
-// src/routes.ts
+// src/app.routes.ts
 import { routes } from "@madojs/mado";
 
 export default routes({
@@ -71,7 +71,7 @@ export default routes({
 ```
 
 ```ts
-// src/pages/home.ts
+// src/modules/<module>/pages/home.ts
 import { page, html } from "@madojs/mado";
 export default page({
   view: () => html`<h1>Hello</h1>`,
@@ -79,7 +79,7 @@ export default page({
 ```
 
 ```ts
-// src/pages/user.ts
+// src/modules/<module>/pages/user.ts
 import { page, html } from "@madojs/mado";
 export default page<{ id: string }>({
   view: ({ params }) => html`<h1>User ${params.id}</h1>`,
@@ -266,7 +266,7 @@ This is like `context.WithValue` / `ctx.Value` in Go, but reactive.
 If you're used to server-side rendering for SEO, in Mado this is solved differently: **prerender at build time**.
 
 ```ts
-// src/pages/product.ts
+// src/modules/<module>/pages/product.ts
 export default page({
   bake: {
     paths: () => api.allProductSlugs(), // build-time fetch
@@ -369,37 +369,33 @@ 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"),
     },
   }),
 });
 ```
 
-### Global API client (like a singleton in Go)
+### Shared HTTP client (like a small transport package in Go)
 
 ```ts
-// src/lib/api.ts
-export class ApiClient {
-  constructor(private base: string) {}
-  get<T>(path: string): Promise<T> {
-    return fetch(this.base + path).then((r) => r.json());
-  }
-}
-
-export const api = new ApiClient("/api");
+// src/shared/http/http-client.ts
+export const httpClient = {
+  get: <T>(path: string): Promise<T> =>
+    fetch(path).then((r) => r.json() as Promise<T>),
+};
 ```
 
-Used directly via `import { api } from '...'` or through `createContext` for testability.
+Module connectors build on this transport and map DTOs to domain types.
 
 ---
 
@@ -442,6 +438,6 @@ Everything else — standard browser + TypeScript.
 - **[`01-routing.md`](./01-routing.md)** — the router in detail.
 - **[`02-project-layout.md`](./02-project-layout.md)** — project structure.
 - **[`03-static-bake.md`](./03-static-bake.md)** — SEO without SSR.
-- **[`examples/showcase/`](../../examples/showcase/)** — full example (landing + admin).
+- **External `madojs-examples` workspace** — full demos (landing + admin).
 
 If something is unclear — open an issue, or just open the source. It really is readable in an evening.

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

@@ -12,15 +12,15 @@ For the first pass, give the agent only:
 - `AGENTS.md`
 - `README.md`
 - `docs/en/07-llm-pitfalls.md`
-- `examples/basic/README.md` if a minimal API tour is needed
-- specific `examples/showcase/**` files only when the agent asks for a larger app pattern
+- files from the external `madojs-examples` workspace only when the agent asks
+  for a larger app pattern
 
 The agent may search targeted APIs in `src/` when blocked, but should not load
 the whole framework into context.
 
 ## Task
 
-Build `examples/tickets`: a small ticket-admin SPA for a solo/backend developer.
+Build a small ticket-admin SPA for a solo/backend developer.
 
 Required behavior:
 
@@ -47,15 +47,10 @@ Look for these after implementation:
 
 ## Result notes
 
-The current `examples/tickets` implementation did not require new public APIs or
-runtime dependencies.
+The historical tickets implementation lives in the external examples workspace.
+The core repository no longer ships that artifact or a dedicated smoke command;
+use this document as a manual evaluation script when updating LLM guidance.
 
-CI runs `npm run llm:smoke` as a deterministic proxy for this task: it verifies
-that `llms.txt` still contains the key guidance, checks the committed
-`examples/tickets` artifact against the required Mado API surface and failure
-patterns, then builds and runs `test/tickets-smoke.test.mjs`.
-
-The main documentation pressure point remains lifecycle: older examples can make
-it look acceptable to create `resource()` directly in `page.view()`. The tickets
-example uses page-level wrapper components instead, so resources are registered
-inside component setup and clean up with the component.
+The main documentation pressure point remains lifecycle: examples should not
+make it look acceptable to create long-lived `resource()` instances accidentally
+at module scope or in route code that never cleans up.

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

@@ -6,18 +6,19 @@ an application.
 
 ## Rule of Thumb
 
-In Mado, layouts are components too. If a file represents a visible reusable
-part of the app tree — app shell, sidebar, modal, table, page section — prefer a
-Web Component registered with `component()`.
+Use Mado route layouts (`page({ view: ({ child }) => ... })`) for app zones:
+auth shells, admin shells, public shells and embedded shells. These live in
+`src/layouts/` and are composed from `src/app.routes.ts`.
 
-Use plain functions only for small inline template helpers:
+Use Web Components registered with `component()` for reusable UI elements and
+widgets. Use plain functions only for small inline template helpers:
 
 ```ts
 const money = (value: number) => html`<span>${formatMoney(value)}</span>`;
 ```
 
-Do not use functions for app shells in public examples. They work, but they
-hide the browser model instead of teaching it.
+Do not hide app shells inside `main.ts` or generic helper functions. The app
+map should show which layout wraps which route group.
 
 Use **Shadow DOM** for leaf widgets:
 
@@ -26,23 +27,14 @@ Use **Shadow DOM** for leaf widgets:
 - embed widgets that should not inherit app CSS accidentally;
 - components whose styling should be owned by the component itself.
 
-Use **Light DOM** (`{ shadow: false }`) for app structure that wants to share
-global CSS utilities:
+Use **Light DOM** for app structure that wants to share global CSS:
 
-- route/page components;
+- route pages and route layouts;
 - admin screens with dense table/form layouts;
 - data-heavy screens with tables and forms;
-- components that intentionally share global layout, form and table utilities;
 - places where children should simply remain normal document DOM.
 
-Use **Shadow DOM** for slot-based layouts:
-
-- app shells that render `<slot>`;
-- sidebar/content wrappers;
-- reusable layout frames that own their own grid/header/sidebar CSS.
-
-`<slot>` is a Shadow DOM feature. In a `shadow: false` component, `<slot>` is
-just a normal element and does not move children into that position.
+Route layouts receive `child` from Mado, so they do not need `<slot>`.
 
 ## The Footgun
 
@@ -96,12 +88,15 @@ Now global utilities and local scoped styles both work.
 ## Recommended App Shape
 
 ```ts
-// root and pages: Light DOM
-component("x-app", setup, { shadow: false });
-component("x-users-page", setup, { shadow: false });
+// app zone: route layout, styled by shared/styles/shell.css
+export default page({
+  view: ({ child }) => html`<main class="app-main">${child}</main>`,
+});
 
-// slot-based layout: Shadow DOM default, because it owns the shell grid
-component("x-app-layout", setup);
+// route page: light DOM, styled by shared/styles/content.css
+export default page({
+  view: () => html`<section><h1>Users</h1></section>`,
+});
 
 // leaf widgets: Shadow DOM default
 component("x-status-badge", setup);
@@ -109,8 +104,8 @@ component("x-stat-card", setup);
 component("x-toast-stack", setup);
 ```
 
-This gives backend-admin screens predictable CSS while preserving encapsulation
-for reusable widgets and slot-based shells.
+This gives admin screens predictable CSS while preserving encapsulation for
+reusable leaf widgets.
 
 The import model is deliberately browser-native:
 
@@ -124,9 +119,8 @@ The import registers the custom element with `customElements.define()`. The
 template creates an `<x-app-layout>` element. The browser connects the two.
 There is no React-style component value being passed around.
 
-If a layout does not need slot projection and should be styled entirely by
-global CSS, `shadow: false` can still be a good choice. If it contains
-`<slot>`, keep Shadow DOM and put the shell styles in that component.
+If you do need a reusable slot-based frame, keep it as a Shadow DOM component
+and put frame styles in that component.
 
 ## Routing and Links
 
@@ -167,16 +161,14 @@ tiny demos, but it hides ownership and defeats lazy route loading. Prefer:
 - feature-owned shared components in the feature entry page;
 - truly global leaf components in `main.ts` only when they are used everywhere.
 
-## Showcase Lesson
+## Starter Lesson
 
-`examples/showcase` uses this split deliberately:
+The default starter uses this split deliberately:
 
-- `x-app` and CRM route pages are Light DOM;
-- `x-app-layout` keeps Shadow DOM because it owns a slot-based sidebar/content
-  shell;
-- table/form/page utilities live in `styles/global.ts`;
-- leaf components such as `x-stat-card`, `x-status-badge`, `x-modal`, and
-  `x-toast-stack` keep Shadow DOM.
+- route layouts are `page()` files under `src/layouts/`;
+- `shell.css` owns app-zone chrome;
+- `content.css` owns page-level tables/forms/prose;
+- leaf components such as `x-button`, `x-spinner` and badges keep Shadow DOM.
 
 If a page suddenly looks unstyled, check whether it uses global classes inside a
 Shadow DOM component. That is usually the issue.

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

@@ -1,141 +1,203 @@
 # App architecture
 
-This is the default shape for a production Mado app. It is intentionally boring:
-one route manifest, one shell, one API client, one auth module, and page files
-that own their feature components.
+The official starter is the canonical production shape for Mado apps. It is
+not a demo architecture and not a framework inside the framework: it is plain
+files, imports, Mado primitives, and ESLint boundaries.
 
-## File tree
+## File Tree
 
 ```txt
 src/
 ├── main.ts
-├── routes.ts
+├── app.routes.ts
 ├── layouts/
-│   ├── app.ts
-│   └── auth.ts
-├── pages/
-│   ├── home.ts
-│   ├── login.ts
-│   ├── not-found.ts
-│   └── admin/
-│       ├── dashboard.ts
-│       ├── orders.ts
-│       └── order-detail.ts
-├── components/
-│   ├── x-button.ts
-│   └── x-input.ts
-├── lib/
-│   ├── api.ts
-│   └── auth.ts
-└── styles/
-    └── global.ts
+│   ├── 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/
 ```
 
-Keep business logic in `lib/`, route wrapping in `layouts/`, and UI leaves in
-`components/`. A page should import the components it renders.
+## The App Map
 
-## Entry point
+`src/app.routes.ts` is the whole application map. Modules export plain route
+maps; app routes decide which shell and guard wrap each zone.
 
 ```ts
-// src/main.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")!);
-```
-
-Import global providers and tiny shared components here. Do not bulk-import
-every feature component.
-
-## Routes
-
-```ts
-// src/routes.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"),
-      "/orders/:id": () => import("./pages/admin/order-detail.js"),
-    },
+    routes: billingRoutes,
   }),
-  "*": () => import("./pages/not-found.js"),
+  "*": () => import("./modules/home/not-found.page"),
 };
 
-export default routes(manifest, {
-  errorPage: (err) => html`<main><h1>Something went wrong</h1><pre>${err.message}</pre></main>`,
-});
+export default routes(manifest);
 ```
 
-Exporting `manifest` lets `mado bake` inspect the same route table.
+Rules:
 
-## API and auth
+- Export `manifest` so `mado bake` can discover bakeable pages.
+- Modules never call `layout()`.
+- Layouts describe app zones, not domains.
+- Do not hide the router inside a custom element or a second shell in
+  `main.ts`.
 
-Use one API client and one auth module. The admin starter ships a complete
-version with token storage, a single-flight refresh request, and a route guard.
+## File Forms
 
-```ts
-// pages/admin/orders.ts
-import { each, html, page, resource } from "@madojs/mado";
-import { api } from "../../lib/api.js";
-
-const orders = resource(() => "/api/orders", () => api.get("/orders"));
-
-export default page({
-  title: "Orders",
-  view: () => html`
-    <main>
-      <h1>Orders</h1>
-      <ul>
-        ${() => each(orders.data() ?? [], o => o.id, o => html`<li>${o.number}</li>`)}
-      </ul>
-    </main>
-  `,
-});
+The suffix tells you the shape:
+
+| 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`.
+
+## 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
 ```
 
-Mutations should declare invalidation near the write:
+Connectors talk to the wire and return domain types. Resources own cache keys
+and invalidation. Pages render and call resources/mutations.
 
-```ts
-const save = mutation((payload) => api.post("/orders", payload), {
-  invalidates: ["/api/orders*"],
-});
+## Module Boundaries
+
+Each module is opaque except for `<module>.public.ts`. Other modules import
+through that file or not at all. DTOs live under `_contracts/` and stay private
+to the connector that understands that external system.
+
+The 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
+
+The starter uses plain CSS plus component-local ``css`...` ``. The split is
+intentional:
+
+| 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. They should depend on tokens (`var(--color-text)`)
+rather than global classes.
+
+`vite.config.ts` opts into Vite's Lightning CSS transformer. Mado does not own
+prefixing, CSS lowering or minification.
+
+## Growth
+
+Start flat when a module is small:
+
+```txt
+modules/auth/
+  auth.types.ts
+  auth.routes.ts
+  auth.public.ts
+  auth.service.ts
+  auth.connector.ts
+  login.page.ts
 ```
 
-## Forms
+When a module grows, group by role without changing suffixes:
 
-Prefer one `useForm()` per user workflow.
+```txt
+modules/billing/
+  pages/
+  data/
+  api/
+  components/
+  forms/
+  _contracts/
+```
 
-```ts
-const form = useForm({
-  email: { required: true, type: "email" },
-  "items.*.title": { required: true },
-});
-const items = form.array("items");
+If a module becomes too large, split it by subdomain and keep communication
+through public surfaces.
+
+## CLI
+
+Use `mado new` for boring file scaffolding:
+
+```bash
+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
 ```
 
-Use dotted paths for arrays (`items.0.title`) and keep async validation in
-`validateAsync` when it talks to the backend.
+The generator only writes new files. It does not edit `app.routes.ts`, does
+not scan the filesystem, and refuses to overwrite existing files.
 
 ## Release
 
-Local development uses `mado dev`. Production uses exactly one artifact:
+Local development uses Vite through `mado dev`. Production uses one deploy
+artifact:
 
 ```bash
 mado release
 rsync -avz out/ user@server:/var/www/app/
 ```
 
-`out/` is the deploy folder. `dist/` is internal build output.
+`out/` is the deploy folder. `dist/` is internal package output.