@madojs/mado 0.10.0 → 0.11.0

package/docs/en/12-auth-and-api.md

@@ -1,217 +1,124 @@
 # Auth and API
 
-> Mado has **zero runtime dependencies**, but that does not mean every team
-> should reinvent its auth and HTTP boundary. This page is the blessed recipe.
-> Copy it into your project, change the URLs and field names to match your
-> backend, and stop touching it.
+The default starter is the blessed recipe. It keeps HTTP mechanics in
+`src/shared/http/` and auth state in `src/modules/auth/`.
+
+## Shape
+
+```txt
+src/shared/http/
+  http-client.ts       # one fetch wrapper + query/body/error handling
+  http-error.ts        # one error shape
+  interceptors.ts      # request/response hooks
+
+src/modules/auth/
+  auth.connector.ts    # /api/auth wire contract, DTO -> domain
+  auth.service.ts      # token/user signals + login/logout/init
+  auth.guard.ts        # requireAuth(), requirePermission()
+  auth.routes.ts       # login route map
+  auth.public.ts       # only public auth surface
+  _contracts/          # backend DTOs, private to connector
+```
 
-The `admin` starter (`mado init my-app --starter admin`) ships with these
-files pre-installed in `src/lib/`:
+Every business module follows the same flow:
 
-- `api.ts` — `createApiClient(baseUrl)` + `accessToken` signal + `ApiError`
-- `auth.ts` — `restoreSession()`, `login()`, `logout()`, `requireAuth` guard
+```txt
+connector -> resource/mutation -> page
+```
 
-The complete code is roughly 100 lines. Read it and own it.
+Pages do not import DTOs. Pages do not call `fetch()` directly. Connectors do
+not import Mado reactivity or UI.
 
-## Mental model
+## HTTP Client
 
-- One **API boundary** (`api()`): every fetch in your app goes through it.
-- One **memory-only access token** (`accessToken` signal): never in
-  `localStorage`. Renewed silently from an HttpOnly refresh cookie when needed.
-- One **route guard** (`requireAuth`): plug it into the layout block that
-  wraps protected routes. The guard runs before the page is rendered.
+Use one small HTTP client for the app. It owns:
 
-That is the entire surface.
+- base URL handling;
+- JSON request/response defaults;
+- query string serialization;
+- `HttpError`;
+- request/response interceptors.
 
-## `src/lib/api.ts`
+Module connectors build on it:
 
 ```ts
-import { signal } from "@madojs/mado";
+import { httpClient } from "../../shared/http/http-client";
+import type { User } from "./auth.types";
+import type { LoginResponseDTO } from "./_contracts/auth-api.types";
+
+const toUser = (dto: LoginResponseDTO["user"]): User => ({
+  id: dto.id,
+  email: dto.email,
+  roles: dto.roles,
+  permissions: dto.permissions,
+});
+
+export const authApi = {
+  me: async () => toUser(await httpClient.get<LoginResponseDTO["user"]>("/api/auth/me")),
+};
+```
 
-export const accessToken = signal<string | null>(null);
+## Auth Service
 
-export class ApiError extends Error {
-  constructor(public status: number, public body: unknown, message: string) {
-    super(message);
-    this.name = "ApiError";
-  }
-}
+Auth state is an ES module singleton:
 
-export interface ApiInit extends Omit<RequestInit, "body"> {
-  json?: unknown;
-  baseUrl?: string;
-}
+```ts
+const _user = signal<User | null>(null);
+const _token = signal<string | null>(null);
 
-export function createApiClient(baseUrl: string) {
-  let refreshing: Promise<boolean> | null = null;
-
-  async function refresh(): Promise<boolean> {
-    if (refreshing) return refreshing;
-    refreshing = (async () => {
-      try {
-        const res = await fetch(new URL("/auth/refresh", baseUrl), {
-          method: "POST",
-          credentials: "include",
-        });
-        if (!res.ok) return false;
-        const data = (await res.json().catch(() => null)) as
-          | { accessToken?: string } | null;
-        if (!data?.accessToken) return false;
-        accessToken.set(data.accessToken);
-        return true;
-      } catch {
-        return false;
-      } finally {
-        refreshing = null;
-      }
-    })();
-    return refreshing;
-  }
-
-  return async function api<T>(path: string, init: ApiInit = {}): Promise<T> {
-    const url = new URL(path, init.baseUrl ?? baseUrl);
-    const headers = new Headers(init.headers);
-    if (init.json !== undefined && !headers.has("content-type")) {
-      headers.set("content-type", "application/json");
-    }
-    const token = accessToken();
-    if (token) headers.set("authorization", `Bearer ${token}`);
-
-    const res = await fetch(url, {
-      ...init,
-      headers,
-      credentials: init.credentials ?? "include",
-      body: init.json !== undefined ? JSON.stringify(init.json) : (init as RequestInit).body,
-    });
-
-    if (res.status === 401) {
-      if (await refresh()) return api<T>(path, init);
-      accessToken.set(null);
-      throw new ApiError(401, null, "Unauthorized");
-    }
-    if (!res.ok) {
-      const body = await res.json().catch(() => null);
-      throw new ApiError(res.status, body, `HTTP ${res.status} ${res.statusText}`);
-    }
-    if (res.status === 204) return null as unknown as T;
-    return (await res.json()) as T;
-  };
-}
+export const user = () => _user();
+export const isAuthed = computed(() => _user() !== null);
 
-export const api = createApiClient("/api");
+export async function login(creds: Credentials): Promise<void> {
+  const res = await authApi.login(creds);
+  _token.set(res.token);
+  _user.set(res.user);
+}
 ```
 
-Key invariants:
+Expose only what other modules need through `auth.public.ts`.
 
-- **Bearer token in memory only.** A page reload destroys it; `restoreSession()`
-  brings it back from the refresh cookie.
-- **Refresh is single-flight.** Five resources hitting 401 at the same time
-  trigger exactly one refresh request.
-- **Errors are typed.** Catch `ApiError` for `.status` and `.body`.
-- **`credentials: include`** is the default, because the refresh cookie is
-  cross-host-safe only with `include`.
+## Guards
 
-## `src/lib/auth.ts`
+Guards are plain functions:
 
 ```ts
-import type { Guard } from "@madojs/mado";
-import { accessToken, api, ApiError } from "./api.js";
-
-let restorePromise: Promise<boolean> | null = null;
-
-export async function restoreSession(): Promise<boolean> {
-  if (accessToken()) return true;
-  if (restorePromise) return restorePromise;
-  restorePromise = (async () => {
-    try {
-      const data = await api<{ accessToken: string }>("/auth/refresh", {
-        method: "POST",
-      });
-      accessToken.set(data.accessToken);
-      return true;
-    } catch (e) {
-      if (e instanceof ApiError && e.status === 401) return false;
-      return false;
-    } finally {
-      restorePromise = null;
-    }
-  })();
-  return restorePromise;
-}
-
-export const requireAuth: Guard = async ({ path }) => {
-  if (accessToken()) return;
-  if (await restoreSession()) return;
-  return { redirect: `/login?return=${encodeURIComponent(path)}`, replace: true };
-};
-
-export async function login(creds: { email: string; password: string }) {
-  const data = await api<{ accessToken: string }>("/auth/login", {
-    method: "POST",
-    json: creds,
-  });
-  accessToken.set(data.accessToken);
-}
-
-export async function logout() {
-  try { await api("/auth/logout", { method: "POST" }); } catch {}
-  accessToken.set(null);
+export function requireAuth(): boolean | string {
+  if (isAuthed()) return true;
+  return "/login";
 }
 ```
 
-Drop `requireAuth` into your manifest:
+Use them in `src/app.routes.ts`:
 
 ```ts
-"/admin": layout({
-  layout:  () => import("./layouts/app.js"),
-  guard:   requireAuth,                       // ← entire group is now protected
-  routes:  { ... },
+"/billing": layout({
+  layout: () => import("./layouts/app-shell.layout"),
+  guard: requireAuth,
+  routes: billingRoutes,
 }),
 ```
 
-The guard runs *before* the page is rendered. If the user is not signed in
-and the refresh cookie cannot revive the session, they are redirected to
-`/login?return=<original>`. After a successful sign-in, the login page reads
-`return` and navigates back.
-
-## Backend contract
-
-The recipe assumes three endpoints. Adjust paths to taste:
-
-| Endpoint                | Request                   | Response (200)               | Notes                          |
-|-------------------------|---------------------------|------------------------------|--------------------------------|
-| `POST /api/auth/login`  | `{ email, password }`     | `{ accessToken }`            | Sets HttpOnly refresh cookie   |
-| `POST /api/auth/refresh`| (no body, cookie only)    | `{ accessToken }`            | Reads HttpOnly refresh cookie  |
-| `POST /api/auth/logout` | (no body)                 | `204`                        | Clears the refresh cookie      |
+## Dev Proxy
 
-If your backend uses a different shape (`{ token }`, `{ access_token, expires_in }`,
-etc.), change `api.ts` and `auth.ts` in two places each. The rest of the app
-keeps working.
+Configure proxying in `vite.config.ts`:
 
-## Dev proxy
-
-In development, point `/api/*` at your backend with `mado.config.json`:
-
-```jsonc
-{
-  "dev": {
-    "port": 5173,
-    "proxy": { "/api": "http://localhost:3000" }
-  }
-}
+```ts
+import { defineConfig } from "vite";
+import { mado } from "@madojs/mado/vite";
+
+export default defineConfig({
+  plugins: [mado()],
+  server: {
+    proxy: { "/api": "http://localhost:3000" },
+  },
+});
 ```
 
-The dev server forwards requests under `/api/*` to your backend, so both the
-SPA and the API can be reached from the same origin — no CORS dance during
-development.
-
-## When to deviate
-
-- **SPA + cookies only** (no Bearer tokens). Remove the `authorization`
-  header and the `refresh()` retry; rely entirely on a session cookie.
-- **Public site with optional auth.** Make `restoreSession()` opportunistic
-  on startup and skip the `requireAuth` guard.
-- **Third-party API tokens** that cannot be refreshed. Drop `refresh()` and
-  fail loudly on 401.
+## Rule of Thumb
 
-Whatever you change, change it **in `api.ts` only**. Pages stay innocent.
+- `shared/http` knows HTTP.
+- `*.connector.ts` knows one external system.
+- `*.resource.ts` knows cache keys and invalidation.
+- `*.page.ts` knows UI.
+- `*.public.ts` is the only cross-module surface.

package/docs/en/13-deployment.md

@@ -8,13 +8,12 @@
 
 ```
 out/
-├── index.html              ← SPA shell (loads the bundle + boots the router)
-├── assets/                 ← hashed bundles (main-ABC.js, chunk-XYZ.js, …)
+├── index.html              ← SPA shell or baked HTML for /
+├── assets/                 ← Vite hashed assets
 │   ├── *.gz                ← precompressed gzip (gzip_static / Accept-Encoding)
 │   └── *.br                ← precompressed brotli (brotli_static / Accept-Encoding)
-├── baked/                  ← prerendered SEO HTML (mado bake)
-│   ├── <route>/index.html
-│   └── sitemap.xml
+├── <route>/index.html      ← prerendered SEO HTML for baked routes
+├── sitemap.xml             ← generated sitemap
 ├── favicon.svg             ← your public/ assets copied verbatim
 ├── _redirects              ← Cloudflare Pages / Netlify SPA fallback
 └── _headers                ← Cloudflare Pages / Netlify cache rules
@@ -31,17 +30,18 @@ mado release
 mado preview      # http://localhost:4173 — serves out/ exactly as a static host would
 ```
 
-`mado preview` mirrors the behavior described below: it picks `.br` over
-`.gz` over raw, prefers baked HTML at `/<route>/`, and falls back to
-`index.html` for unknown paths.
+`mado preview` serves the final `out/` directory like a static host: it picks
+`.br` over `.gz` over raw, serves promoted baked HTML when a route has an
+`index.html`, and falls back to `index.html` for unknown SPA paths.
 
 ---
 
 ## Recipe 1: VPS + nginx
 
-The framework ships a production-ready [`nginx.conf`](../../nginx.conf) with
-`gzip_static`, immutable cache for hashed bundles, and SPA fallback. Drop
-`out/` into the host and point nginx at it.
+The framework ships an optional nginx recipe in
+[`docs/recipes/nginx`](../recipes/nginx/): `nginx.conf` for static hosting and a
+`Containerfile` you can copy into generated apps. Drop `out/` into the host and
+point nginx at it.
 
 ```bash
 # Build the artifact locally
@@ -52,16 +52,15 @@ rsync -avz --delete out/ user@server:/var/www/myapp/
 
 # On the VPS — first time only:
 sudo cp /etc/nginx/conf.d/myapp.conf{,.bak}
-sudo cp ./nginx.conf /etc/nginx/conf.d/myapp.conf
+sudo cp ./docs/recipes/nginx/nginx.conf /etc/nginx/conf.d/myapp.conf
 sudo nginx -t && sudo systemctl reload nginx
 ```
 
-Key lines of the shipped `nginx.conf`:
+Key lines of the recipe `nginx.conf`:
 
 - `gzip_static on;` — serves the precompressed `.gz` files written by
-  `mado bundle`. Zero CPU at request time.
-- `location ~* "^/(main|chunk|asset)-[A-Z0-9]+\.js$" { … immutable; }` —
-  hashed bundles get a one-year cache.
+  `mado release`. Zero CPU at request time.
+- `/assets/*` should be cached immutable; Vite filenames are content hashed.
 - `try_files $uri $uri/ /index.html;` — SPA fallback so deep links work
   after a hard refresh.
 
@@ -79,8 +78,9 @@ npx wrangler pages deploy out --project-name=myapp
 - The generated `_redirects` (`/* /index.html 200`) gives you SPA fallback.
 - The generated `_headers` (immutable cache for `/assets/*`, `no-cache` for
   HTML) is honored by CF Pages.
-- Baked routes (`out/baked/<route>/index.html`) take priority over the SPA
-  fallback because CF Pages matches static files first.
+- Baked routes are promoted to real route files (`out/<route>/index.html`),
+  so they take priority over the SPA fallback because CF Pages matches static
+  files first.
 
 For preview branches, set the same build command in the CF Pages project:
 
@@ -89,9 +89,8 @@ Build command:    npm ci && npx mado release
 Output directory: out
 ```
 
-There is also a small **edge prerender PoC** in
-[`examples/cloudflare`](../../examples/cloudflare/) for catalogs too big to
-bake at build time.
+For catalogs too big to bake at build time, keep edge prerender experiments in
+the external examples workspace rather than in the core package.
 
 ---
 
@@ -138,7 +137,7 @@ add a `404.html` that loads the SPA, or use the
 | Other static files           | `public, max-age=86400`                          | safe daily cache                 |
 
 `mado release` writes these rules into `out/_headers` for CF / Netlify and
-the shipped `nginx.conf` enforces them server-side.
+the nginx recipe enforces them server-side.
 
 ---
 
@@ -181,12 +180,12 @@ jobs:
   `Cache-Control: public, max-age=...` or you are sitting behind a CDN that
   ignores `no-cache`. Add an explicit rule mirroring the matrix above.
 - **`/assets/*` files change but the browser keeps the old one.** They
-  should not — the filename is hashed by `mado bundle`. If you bypassed
-  bundle and shipped your own `dist/main.js`, give it a hash or short cache.
+  should not — the filename is hashed by Vite during `mado release`. If you bypassed
+  build and shipped your own unhashed JS, give it a hash or short cache.
 - **Baked SEO page shows `[object Object]`.** Should never happen after the
   v1 bake update — bake now raises a loud error in that case. If you see it,
   upgrade `@madojs/mado` and re-run `mado bake`.
 
 See also: [`02-project-layout.md`](./02-project-layout.md) for the
-`src/`/`dist/`/`public/`/`out/` model and [`03-static-bake.md`](./03-static-bake.md)
-for the SEO bake mechanics.
+`src/`/`public/`/`out/` model and [`03-static-bake.md`](./03-static-bake.md)
+for the SEO bake mechanics.

package/docs/en/14-testing.md

@@ -27,7 +27,7 @@ globalThis.document = window.document;
 globalThis.Node = window.Node;
 globalThis.HTMLElement = window.HTMLElement;
 
-const { html, render } = await import("../dist/src/html.js");
+const { html, render } = await import("../dist/src/html/template.js");
 
 test("renders a value", () => {
   const root = document.createElement("div");
@@ -74,9 +74,9 @@ services from framework tests. For app tests, make the API client injectable via
 npm run typecheck
 npm run build
 npm test
-npm run bundle
 npm run bake
 ```
 
-`mado release` runs the production path for an app. In the framework repository,
-the lower-level commands remain useful when debugging a single stage.
+`mado release` runs the production path for an app: typecheck, Vite build,
+bake, compression and deploy helper files. In the framework repository,
+`npm run build` still emits `dist/src` for package tests and publishing.

package/docs/en/16-bake-cookbook.md

@@ -55,8 +55,9 @@ export default routes(manifest);
 
 ## Output
 
-By default app-mode writes baked pages under `out/baked/`. `mado release`
-produces the final deploy artifact:
+By default standalone `mado bake` writes baked pages directly into `out/`.
+`mado release` first lets Vite build the production shell and assets, then bake
+replaces route HTML in place and writes `out/sitemap.xml`:
 
 ```bash
 mado release
@@ -65,6 +66,15 @@ tree out
 
 The deployable folder is `out/`, not `dist/`.
 
+Use `mado release --keep-bake-dir` only when you want an extra `out/baked/`
+inspection copy during debugging.
+
+## Client boot
+
+Baked HTML marks `#app` with `data-mado-baked`. This is not hydration: when the
+client app starts, `render()` replaces the baked DOM with live bindings. The
+first response contains SEO/first-paint HTML, then the SPA takes over normally.
+
 ## Unsupported values
 
 Bake intentionally fails loudly instead of writing `[object Object]`. If a baked
@@ -76,15 +86,12 @@ view throws an unsupported directive error:
 
 ## Canonical links
 
-Pass `--base-url` or set `bake.baseUrl` in `mado.config.json` so generated
-canonical links and sitemap entries point to production.
+Pass `--base-url` so generated canonical links and sitemap entries point to
+production.
 
-```json
-{
-  "bake": {
-    "baseUrl": "https://example.com"
-  }
-}
+```bash
+mado bake --base-url https://example.com
+mado release --base-url https://example.com
 ```
 
 ## When not to bake

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

@@ -9,10 +9,12 @@ package root:
 import { component, html, resource, routes, signal } from "@madojs/mado";
 ```
 
-The only public package subpath is the side-effect devtools module:
+The public package subpaths are the side-effect devtools module and the Vite
+tooling integration:
 
 ```ts
 import "@madojs/mado/devtools.js";
+import { mado } from "@madojs/mado/vite";
 ```
 
 Everything else under `dist/src/` is an implementation detail, even when it is
@@ -27,7 +29,7 @@ These names are public and protected by SemVer once v1 ships:
 - Templates and directives: `html`, `render`, `each`, `list`, `unsafeHTML`,
   `ref`, `classMap`, `styleMap`.
 - Components and CSS: `component`, `css`, `cssVars`.
-- Routing and pages: `routes`, `router`, `page`, `layout`, `nested`,
+- Routing and pages: `routes`, `router`, `page`, `layout`,
   `navigate`, `queryParam`, `prefetchPath`.
 - Data: `resource`, `mutation`, `invalidate`, `jsonFetcher`, `HttpError`.
 - Forms: `useForm`.
@@ -41,8 +43,8 @@ These names are public and protected by SemVer once v1 ships:
 
 These are not public API:
 
-- Package subpaths other than `@madojs/mado` and
-  `@madojs/mado/devtools.js`.
+- Package subpaths other than `@madojs/mado`, `@madojs/mado/devtools.js`,
+  and `@madojs/mado/vite`.
 - Template parser/binding internals such as `html/parser.js`,
   `html/bindings.js`, `ChildState`, and `EachEntry`.
 - Router implementation modules such as `router/match.js`,

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

@@ -25,7 +25,7 @@ After v1, Mado treats these as SemVer-protected:
   teardown for same-tick moves, cleanup via `ctx.onDispose`.
 - Router/page/resource/form contracts documented in the English docs.
 - CLI command names and broad command intent (`build`, `dev`, `release`,
-  `bake`, `bundle`, `preview`, `init`, `new`).
+  `bake`, `preview`, `init`, `new`).
 
 Breaking these requires a major version.