@madojs/mado 0.10.1 → 0.11.1

package/dist/src/vite/index.js

@@ -0,0 +1,33 @@
+import { resolve } from "node:path";
+/**
+ * Vite integration for Mado apps.
+ *
+ * The plugin is intentionally small: Vite owns dev serving, HTML processing,
+ * assets and bundling; Mado keeps its runtime and static bake semantics.
+ */
+export function mado(_options = {}) {
+    let root = process.cwd();
+    return {
+        name: "mado",
+        config(userConfig) {
+            root = resolve(process.cwd(), userConfig.root ?? ".");
+            return {
+                appType: "spa",
+                publicDir: "public",
+                build: {
+                    outDir: "out",
+                    assetsDir: "assets",
+                    target: "es2022",
+                },
+            };
+        },
+        handleHotUpdate(ctx) {
+            if (/\.(ts|js)$/.test(ctx.file)) {
+                ctx.server.ws.send({ type: "full-reload" });
+                return [];
+            }
+            return undefined;
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/src/vite/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/vite/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC;;;;;GAKG;AACH,MAAM,UAAU,IAAI,CAAC,WAAkC,EAAE;IACvD,IAAI,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAEzB,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,MAAM,CAAC,UAAU;YACf,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC;YAEtD,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,SAAS,EAAE,QAAQ;gBACnB,KAAK,EAAE;oBACL,MAAM,EAAE,KAAK;oBACb,SAAS,EAAE,QAAQ;oBACnB,MAAM,EAAE,QAAQ;iBACjB;aACF,CAAC;QACJ,CAAC;QACD,eAAe,CAAC,GAAG;YACjB,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAChC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;gBAC5C,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/docs/en/00-the-mado-way.md

@@ -27,21 +27,31 @@ break them — types and the linter will tell you immediately.
 
 ```
 src/
-├── routes.ts         ← route manifest, one file per project
-├── main.ts           ← entry point: providers + mount <x-app>
-├── pages/            ← one page = one file = `export default page({...})`
-├── components/       ← reusable components, side-effect registration
-├── lib/              ← contexts, API clients, business logic without UI
-└── styles/           ← shared styles (if needed), .ts files with css``
+├── main.ts           ← boot: global CSS/providers + render router
+├── app.routes.ts     ← one readable app map, exports `manifest` + default routes()
+├── layouts/          ← app-zone wrappers (`page({ view: ({ child }) => ... })`)
+├── shared/           ← UI bricks, http client, pure lib, global CSS
+└── modules/          ← bounded contexts
+    └── billing/
+        ├── billing.routes.ts
+        ├── billing.public.ts
+        ├── billing.types.ts
+        ├── pages/
+        ├── data/
+        ├── api/
+        └── _contracts/
 ```
 
 This is **mandatory**, not optional. If a project has 10 developers — they must
 all write the same way.
 
+The default starter is the canonical version of this shape. Use it as the
+reference when docs and examples disagree.
+
 ### One component = one file
 
 ```ts
-// src/components/user-card.ts
+// src/shared/ui/x-user-card.component.ts
 import { component, html, css } from "@madojs/mado";
 
 component(
@@ -59,7 +69,7 @@ component(
 );
 ```
 
-`import './components/user-card.js'` **registers** the component via
+`import "./shared/ui/x-user-card.component.js"` **registers** the component via
 `customElements.define`. This is a side effect. Import where the component is needed.
 
 ### One way to load data
@@ -79,17 +89,20 @@ This provides caching, cancellation, error handling, and auto-invalidation.
 ### One way to describe a page
 
 ```ts
-// src/pages/user-profile.ts
+// src/modules/users/pages/user-profile.page.ts
 import { page, html, resource, jsonFetcher } from "@madojs/mado";
 
 export default page({
   title: ({ id }) => `User #${id}`,
-  view: ({ params }) => html`...`,
+  view: ({ params }) => {
+    const user = resource(() => `/api/users/${params.id}`, jsonFetcher());
+    return html`...`;
+  },
 });
 ```
 
-Three slots — `title`, `load`, `view`. No others. Want something else — that is
-a component or a helper.
+Keep page-local signals, resources and forms inside `view()`. Module-wide state
+belongs in `*.service.ts`.
 
 ### One way to declare routes
 

package/docs/en/01-routing.md

@@ -1,204 +1,152 @@
 # Routing
 
-> One manifest file. No folder scanners. No special characters.
+> One app map. No folder scanners. No special path syntax.
 
-## Why not file-based
+Mado does not infer routes from files. The browser sees files as files; route
+composition should be readable in one place.
 
-In Next/SvelteKit/SolidStart routes appear "magically" from file names. This has
-advantages (URL structure visible in `pages/`), but in production it means:
+## App Manifest
 
-- An invisible plugin-scanner in the build. Without it the files are just files.
-- Special characters in paths: `[id]`, `(group)`, `_layout`, `+page.svelte`, `...slug`.
-- Server-routes and client-routes get confused.
-- Testing routing is a pain: you need a build-tool emulator.
+Use `src/app.routes.ts` as the application map:
 
-Mado considers this **too much magic**. We do it differently.
+```ts
+import { layout, routes } from "@madojs/mado";
+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("./modules/home/home.page.js"),
+  "/login": layout({
+    layout: () => import("./layouts/auth-shell.layout.js"),
+    routes: authRoutes,
+  }),
+  "/billing": layout({
+    layout: () => import("./layouts/app-shell.layout.js"),
+    guard: requireAuth,
+    routes: billingRoutes,
+  }),
+  "*": () => import("./modules/home/not-found.page.js"),
+};
+
+export default routes(manifest);
+```
 
-## Manifest
+Open `app.routes.ts` and you can see the whole app: public pages, auth zone,
+protected app zones, guards and shells.
 
-One file — `src/routes.ts`. One object. Read top to bottom.
+Exporting `manifest` is important because `mado bake` reads it.
+
+## Module Routes
+
+Modules export plain route maps. They do not call `layout()` and they do not
+decide which shell wraps them.
 
 ```ts
-// src/routes.ts
-import { routes } from '@madojs/mado';
-
-export default routes({
-  '/':              () => import('./pages/home.js'),
-  '/about':         () => import('./pages/about.js'),
-  '/users/:id':     () => import('./pages/user-profile.js'),
-  '/users/:id/edit':() => import('./pages/user-edit.js'),
-  '*':              () => import('./pages/not-found.js'),
-});
+// src/modules/billing/billing.routes.ts
+export const billingRoutes = {
+  "/invoices": () => import("./pages/invoices-list.page.js"),
+  "/invoices/:id": () => import("./pages/invoice-detail.page.js"),
+};
 ```
 
-Want to see all routes? Open `routes.ts`. No surprises.
-
-## What goes on the right side of a path
+The prefix is applied by `src/app.routes.ts` when the module is mounted under
+`"/billing"`.
 
-Every entry is **one of three things**:
+## What Goes On The Right Side
 
-### 1. Lazy import (recommended)
+### Lazy page import
 
 ```ts
-'/posts': () => import('./pages/posts.js'),
+"/users/:id": () => import("./modules/users/pages/user-profile.page.js"),
 ```
 
-- The browser makes its own chunk when bundling (esbuild --bundle --splitting).
-- The module is loaded only when the user visits the route.
-- Subsequent navigations use the cached result.
+Vite creates a separate chunk for dynamic imports in production.
 
-### 2. Ready Page (eager)
+### Eager page
 
 ```ts
-import about from './pages/about.js';
+import home from "./modules/home/home.page.js";
 
-'/about': about,
+export const manifest = {
+  "/": home,
+};
 ```
 
-In the bundle immediately, no delay. Use for critical pages (home, login).
+Use this only for tiny critical pages.
 
-### 3. Nested with layout
+### Layout group
 
 ```ts
-import { routes, nested } from '@madojs/mado';
-
-export default routes({
-  '/': () => import('./pages/home.js'),
-
-  '/admin/*': nested({
-    layout: () => import('./layouts/admin.js'),
-    routes: {
-      '':       () => import('./pages/admin/dashboard.js'),
-      'users':  () => import('./pages/admin/users.js'),
-      'logs':   () => import('./pages/admin/logs.js'),
-    },
-  }),
-});
+"/admin": layout({
+  layout: () => import("./layouts/app-shell.layout.js"),
+  guard: requireAuth,
+  routes: adminRoutes,
+}),
 ```
 
-A layout is just a regular `page({...})` that renders `ctx.child` wherever it wants:
+A layout is a normal `page({...})` file:
 
 ```ts
-// src/layouts/admin.ts
-import { page, html, css, component } from '@madojs/mado';
+import { html, page } from "@madojs/mado";
 
 export default page({
   view: ({ child }) => html`
-    <div class="admin">
-      <aside><nav>...</nav></aside>
-      <main>${child}</main>
+    <div class="layout layout--app">
+      <main class="app-main">${child}</main>
     </div>
   `,
 });
 ```
 
-## Page contract
+Keep layout views stateless. Put page-specific signals, resources and forms in
+pages/components/resources, not in layout locals.
 
-```ts
-import { page, html, resource, jsonFetcher } from '@madojs/mado';
-
-export default page({
-  title: ({ id }) => `User #${id}`,        // string | (params) => string
-  load:  ({ id }) => resource(...),         // optional, returns Resource or data
-  view:  ({ params, data, path, child }) => html`...`,  // REQUIRED
-});
-```
-
-Three slots, that's all. If you export something other than `page({...})`, a plain
-function for instance — `routes()` throws a clear error:
-
-```
-[Mado] Lazy route did not return page({...}) as the default export.
-```
-
-## URL parameters
+## Page Contract
 
 ```ts
-'/users/:id': () => import('./pages/user.js'),
-```
+import { html, page } from "@madojs/mado";
 
-```ts
 export default page<{ id: string }>({
   title: ({ id }) => `User ${id}`,
-  view:  ({ params }) => html`<h1>${params.id}</h1>`,
+  view: ({ params }) => html`<h1>${params.id}</h1>`,
 });
 ```
 
-Types are passed in `page<Params>` — `tsc` verifies that you don't access
-`params.foo` which doesn't exist in the route.
-
-## Global options
-
-```ts
-export default routes(
-  { '/': home, '/about': about, '*': nf },
-  {
-    titleSuffix: ' · MyApp',                       // → "Home · MyApp"
-    loading: () => html`<x-spinner/>`,             // while module loads
-    error:   (err) => html`<x-fatal-error .err=${err}/>`,
-  },
-);
-```
+If a lazy route does not default-export `page({...})`, `routes()` throws a clear
+error.
 
-## Programmatic navigation
+## Navigation
 
 ```ts
-import route from './routes.js';
+import appRoutes from "./app.routes.js";
 
-route.navigate('/posts');
-route.navigate('/posts?page=2');
-route.navigate('/posts', { replace: true });
+appRoutes.navigate("/billing/invoices");
+appRoutes.navigate("/billing/invoices?page=2");
+appRoutes.navigate("/login", { replace: true });
 ```
 
-Clicks on `<a href="/foo" data-link>` are intercepted globally (without the
-attribute — the browser does a full reload, as expected for external links).
+Clicks on `<a href="/foo">` are intercepted for same-origin SPA navigation.
+External links still use normal browser navigation.
 
-## Query parameters
+## Query Parameters
 
 ```ts
-import { queryParam } from '@madojs/mado';
+import { queryParam } from "@madojs/mado";
 
-const page = queryParam('page', '1');
-page();              // '1'
-page.set('2');       // history.replaceState + re-render
-page.set(null);      // delete the parameter
-page.set('3', { push: true });   // history.pushState
+const page = queryParam("page", "1");
+page();
+page.set("2");
+page.set(null);
+page.set("3", { push: true });
 ```
 
-`queryParam` is a normal signal. Use it anywhere: in pages, components, computed.
-
-## What is intentionally absent
-
-- ❌ Auto-scan of `pages/`. **One explicit manifest file**.
-- ❌ Special characters in paths (`[id]`, `(group)`, `_layout`). **Parameters are
-  `:name` only, nothing else**.
-- ❌ Server-side routing in the same manifest. Mado is a client-side framework.
-- ❌ Auto-prefetch on hover. If you really need it — do it manually:
-  `link.addEventListener('mouseenter', loader)`. Usually unnecessary.
-
-## FAQ
-
-**What if I have 100 routes? Won't the file get huge?**
-It will grow to ~150 lines. That is still **one source of truth** versus a hundred
-files in `pages/` with magic names. In practice even large projects (1000+ pages)
-can split into feature manifests:
-
-```ts
-import { routes } from '@madojs/mado';
-import adminRoutes from './features/admin/routes.js';
-import billingRoutes from './features/billing/routes.js';
-
-export default routes({
-  ...adminRoutes,
-  ...billingRoutes,
-  '*': () => import('./pages/not-found.js'),
-});
-```
+`queryParam()` is a signal. Use it in pages or components when URL state is part
+of the UI.
 
-**How do I test routing?**
-Import `routes.ts` — it is just an object. Substitute your mock router. No build
-tool emulation needed.
+## What Is Intentionally Absent
 
-**Does code splitting work?**
-Yes. With `esbuild --bundle --splitting --format=esm` every
-`() => import('./pages/x.js')` becomes its own chunk.
+- No auto-scan of page folders.
+- No special filesystem route syntax like `[id]`, `(group)`, `_layout`.
+- No server routes in the client manifest.
+- No hidden layout discovery. App zones are explicit in `app.routes.ts`.

package/docs/en/02-project-layout.md

@@ -8,40 +8,42 @@ things live.
 my-app/
 ├── package.json              # exactly one runtime dep: @madojs/mado
 ├── tsconfig.json             # strict TS, ES2022, Bundler resolution
-├── mado.config.json          # single config file (dev/build/bake/bundle)
-├── index.html                # SPA shell (also the template for `mado bake`)
+├── vite.config.ts            # optional; use mado() from @madojs/mado/vite
+├── index.html                # Vite entry + SPA shell
 ├── public/                   # static assets (favicons, images, robots.txt)
 └── src/
     ├── main.ts               # entry: mount router into #app
-    ├── routes.ts             # route manifest (default + named `manifest`)
-    ├── layouts/              # `page({ child })` layouts for nested routes
-    ├── pages/                # one page = one file
-    ├── components/           # reusable x-* Web Components
-    └── lib/
-        ├── api.ts            # API client + error type
-        ├── auth.ts           # auth recipe (token + guard)
-        └── ...               # contexts, helpers, business rules
+    ├── app.routes.ts         # one app map (default + named `manifest`)
+    ├── layouts/              # app-zone layouts, not domain modules
+    ├── shared/               # ui, http, lib, styles
+    └── modules/              # bounded contexts
+        └── billing/
+            ├── billing.routes.ts
+            ├── billing.public.ts
+            ├── billing.types.ts
+            ├── pages/
+            ├── data/
+            ├── api/
+            └── _contracts/
 ```
 
 ## The three artifact states (read this once, never wonder again)
 
 | Folder      | What it is                                                     | Who writes        | Who reads                  | Deploy?           |
 |-------------|----------------------------------------------------------------|-------------------|----------------------------|-------------------|
-| `src/`      | your source (TypeScript)                                       | you               | `tsc`, `esbuild`           | ❌ no             |
-| `dist/`     | `tsc` output — native ESM `.js` for the browser                | `mado build`      | `mado dev` (during dev)    | ❌ no (internal)  |
-| `public/`   | static assets you authored (favicon, images, robots.txt)       | you               | `mado release` copies it   | ✅ via `out/`     |
-| `out/`      | **the deploy artifact**: SPA shell + bundles + baked HTML      | `mado release`    | nginx / CDN / Cloudflare   | ✅ **yes**        |
+| `src/`      | your source (TypeScript)                                       | you               | Vite, `tsc --noEmit`       | ❌ no             |
+| `public/`   | static assets copied as-is (favicon, images, robots.txt)       | you               | Vite build                 | ✅ via `out/`     |
+| `out/`      | **the deploy artifact**: SPA shell + assets + baked HTML       | `mado release`    | nginx / CDN / Cloudflare   | ✅ **yes**        |
 
 One-liner to remember:
 > Develop with `mado dev`. To ship: run `mado release`, then upload `out/`.
 
-`mado release` = `typecheck` + `build` (tsc → `dist/`) + `bundle` (esbuild
-→ `out/assets/`) + `bake` (HTML → `out/baked/`) + promote baked HTML and
-`sitemap.xml` into deployable `out/` paths + copy `public/*` → `out/`.
+`mado release` = `typecheck` + Vite build (`out/index.html`, `out/assets/`,
+`public/*`) + `bake` directly into deployable route paths + `sitemap.xml` +
+precompressed assets and CDN helper files.
 
-You almost never need to look inside `dist/`. It exists so the dev browser can
-load native ESM modules without a bundler during development. In production
-the equivalent code is bundled and hashed into `out/assets/`.
+`index.html` belongs at the project root because Vite treats it as an entry
+template, not as a static public file. Put only copy-as-is files in `public/`.
 
 ### Quick deployment matrix
 
@@ -57,14 +59,19 @@ See `docs/en/13-deployment.md` for full recipes.
 
 | What                                | Where                                                |
 |-------------------------------------|------------------------------------------------------|
-| Page for a new URL                  | `src/pages/<name>.ts` + add to `src/routes.ts`       |
-| Layout for a group of routes        | `src/layouts/<name>.ts` (referenced from `routes.ts`)|
-| Reusable UI widget                  | `src/components/<x-name>.ts`                         |
-| API call                            | `src/lib/api.ts` (add a method)                      |
-| Auth/session                        | `src/lib/auth.ts`                                    |
-| Global context (theme, user, i18n)  | `src/lib/<name>.ts`                                  |
-| Pure function with no UI            | `src/lib/util/<name>.ts`                             |
+| Page for a new URL                  | `src/modules/<module>/pages/<name>.page.ts` + module routes |
+| Module route map                    | `src/modules/<module>/<module>.routes.ts`            |
+| App shell/layout                    | `src/layouts/<zone>.layout.ts`                       |
+| Reusable shared UI widget           | `src/shared/ui/<x-name>.component.ts`                |
+| Module-only UI widget               | `src/modules/<module>/components/<name>.component.ts` |
+| API connector                       | `src/modules/<module>/api/<provider>.connector.ts`   |
+| Data resource/mutation              | `src/modules/<module>/data/<name>.resource.ts`       |
+| Auth/session                        | `src/modules/auth/`                                  |
+| Public module surface               | `src/modules/<module>/<module>.public.ts`            |
+| Pure function with no UI            | `src/shared/lib/<name>.ts`                           |
 | Static image / favicon              | `public/<file>`                                      |
+| App-zone shell CSS                  | `src/shared/styles/shell.css`                       |
+| Page-level table/form/prose CSS      | `src/shared/styles/content.css`                     |
 
 If you don't know where — that is a signal that **the architecture is
 suffering**. Ask the team and **record** the answer in `docs/`. Don't invent a
@@ -80,39 +87,38 @@ new top-level folder.
 | Signal                              | camelCase            | `userId`, `isLoggedIn` |
 | Page-internal element               | `x-<route>-page`     | `<x-posts-page>`       |
 
-## `mado.config.json` in one screen
+## Vite config
 
-```jsonc
-{
-  "dev": {
-    "port": 5173,
-    "proxy": { "/api": "http://localhost:3000" }   // dev → backend
-  },
-  "build": {
-    "out": "out",
-    "dist": "dist",
-    "publicDir": "public"
+App/dev/build settings live in `vite.config.ts`.
+
+```ts
+import { defineConfig } from "vite";
+import { mado } from "@madojs/mado/vite";
+
+export default defineConfig({
+  plugins: [mado()],
+  css: {
+    transformer: "lightningcss",
   },
-  "bake": {
-    "entry": "src/routes.ts",
-    "template": "index.html",
-    "baseUrl": "https://example.com"
+  server: {
+    proxy: { "/api": "http://localhost:3000" },
   },
-  "bundle": {
-    "splitting": true,
-    "compress": ["gz", "br"]
-  }
-}
+});
 ```
 
-Precedence: built-in defaults < `mado.config.json` < CLI flags
-(< legacy env vars). All keys are optional.
+The default starter opts into Vite's Lightning CSS transformer. CSS
+minification is already handled by Vite; the explicit transformer keeps
+prefixing and modern CSS lowering in Vite instead of in Mado.
+
+`mado bake` uses conventions by default: `src/app.routes.ts` first,
+then `src/routes.ts`, `index.html` as the template, and `out/` as output.
+Use CLI flags (`--entry`, `--template`, `--out`, `--base-url`) for the few
+values that are specific to prerendering.
 
 ## What does NOT go in `src/`
 
-- ❌ Build tool configs (webpack, rollup, vite) — we don't have any.
-- ❌ `.env` files — read env in `src/lib/config.ts` from `import.meta.env` /
+- ❌ Extra build tool configs — use `vite.config.ts` with `mado()` when needed.
+- ❌ `.env` files — read env in `src/shared/lib/config.ts` from `import.meta.env` /
   `process.env` and import that one module everywhere.
 - ❌ Tests mixed with code — put them in `test/`.
-- ❌ `examples/` folder — the framework repository has examples, your app
-  does not need one.
+- ❌ `examples/` folder — keep large demos outside the app repo.

package/docs/en/03-static-bake.md

@@ -40,7 +40,7 @@ The `npm run bake` command traverses all `page` entries with `bake`, generates H
 ## Example
 
 ```ts
-// src/pages/product.ts
+// src/modules/<module>/pages/product.ts
 import { page, component, html } from "@madojs/mado";
 import { findProduct, products, type Product } from "../lib/products.js";
 
@@ -84,7 +84,7 @@ export default page<{ slug: string }, Product | undefined>({
 ```
 
 ```ts
-// src/routes.ts
+// src/app.routes.ts
 import { routes, type RoutesMap } from "@madojs/mado";
 
 // Export BOTH default (RouterApi for runtime) AND manifest (for the bake script).
@@ -100,8 +100,7 @@ export default routes(manifest, { titleSuffix: " · MyShop" });
 ## Running
 
 ```bash
-npm install -D linkedom esbuild
-npm run build
+npm install -D linkedom vite
 npm run bake
 ```
 
@@ -144,7 +143,7 @@ out/
     {"slug":"mado-mug","name":"Mado Mug","price":12,"..."}
   </script>
 
-  <script type="module" src="/dist/examples/main.js"></script>
+  <script type="module" src="/assets/index-HASH.js"></script>
 </body>
 ```
 
@@ -174,7 +173,7 @@ export const allPosts = () =>
 ```
 
 ```ts
-// src/pages/blog-post.ts
+// src/modules/<module>/pages/blog-post.ts
 import { page, html } from "@madojs/mado";
 import { allPosts } from "../lib/posts.js";