@madojs/mado 0.10.1 → 0.11.0

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.

package/docs/en/11-layouts.md

@@ -1,34 +1,32 @@
 # Layouts
 
-> **One blessed path.** Layouts in Mado are nested-route groups with a shared
+> **One blessed path.** Layouts in Mado are route groups with a shared
 > shell. There is exactly one canonical place to declare a layout — your
-> `routes.ts` manifest. Putting layout code anywhere else (in `main.ts`, in a
+> `app.routes.ts` manifest. Putting layout code anywhere else (in `main.ts`, in a
 > page view, in a global custom-element wrapper) is a bug pattern: the LLM and
 > the human both produce visually broken UI when they guess differently.
 
 ## The canonical recipe
 
 ```ts
-// src/routes.ts
+// src/app.routes.ts
 import { layout, routes } from "@madojs/mado";
-import { requireAuth } from "./lib/auth.js";
+import { requireAuth } from "./modules/auth/auth.public.js";
+import { authRoutes } from "./modules/auth/auth.routes.js";
+import { billingRoutes } from "./modules/billing/billing.routes.js";
 
 export const manifest = {
-  "/":       () => import("./pages/home.js"),       // no layout
+  "/":       () => import("./modules/home/home.page.js"),
   "/login": layout({
-    layout:  () => import("./layouts/auth.js"),     // centered card
-    routes:  { "/": () => import("./pages/login.js") },
+    layout:  () => import("./layouts/auth-shell.layout.js"),
+    routes:  authRoutes,
   }),
-  "/admin": layout({
-    layout:  () => import("./layouts/app.js"),      // admin shell
-    guard:   requireAuth,                           // ← see 12-auth-and-api.md
-    routes: {
-      "/":           () => import("./pages/admin/dashboard.js"),
-      "/orders":     () => import("./pages/admin/orders.js"),
-      "/orders/:id": () => import("./pages/admin/order-detail.js"),
-    },
+  "/billing": layout({
+    layout:  () => import("./layouts/app-shell.layout.js"),
+    guard:   requireAuth,
+    routes:  billingRoutes,
   }),
-  "*": () => import("./pages/not-found.js"),
+  "*": () => import("./modules/home/not-found.page.js"),
 };
 
 export default routes(manifest);
@@ -62,14 +60,14 @@ That is the whole API.
 Without this convention, every page accumulates `<x-app-shell>${...}</x-app-shell>`
 boilerplate, the LLM eventually puts the shell wrapper into `main.ts` "to make
 it consistent", and the next refactor produces the classic
-*"navigation appears below the page content"* screenshot. The nested-routes
+*"navigation appears below the page content"* screenshot. The layout-group
 recipe makes the shell the **outer frame** structurally; there is no way to
 re-order it by accident.
 
 ## Two acceptable alternatives (with caveats)
 
-These exist for completeness. Reach for them only if you cannot use nested
-routes.
+These exist for completeness. Reach for them only if you cannot use layout
+groups.
 
 ### a) A single shell with the router slot in `main.ts`
 
@@ -104,12 +102,12 @@ place. **Do not start with this.**
 
 ## Where to find more
 
-- `src/page.ts` defines `layout()`, `page()`, `Guard` and `NestedRoutes`.
-- `src/router/manifest.ts` flattens the nested manifest and applies guards
+- `src/page.ts` defines `layout()`, `page()`, `Guard` and `LayoutRoutes`.
+- `src/router/manifest.ts` flattens the layout manifest and applies guards
   outer → inner before the page renders.
-- The `admin` starter (`mado init my-app --starter admin`) ships with three
-  groups (`/`, `/login`, `/admin`) and is the reference implementation.
+- The default starter (`mado init my-app`) ships with public, auth and
+  authenticated app zones and is the reference implementation.
 
 If you ever feel tempted to invent a fourth pattern, write it down in your
 project `docs/` first and discuss it with the team. The cost of inconsistency
-in this exact spot is higher than the cost of a slightly awkward layout.
+in this exact spot is higher than the cost of a slightly awkward layout.