@madojs/mado 0.5.0 → 0.6.0

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

@@ -0,0 +1,141 @@
+# 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.
+
+## File tree
+
+```txt
+src/
+├── main.ts
+├── 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
+```
+
+Keep business logic in `lib/`, route wrapping in `layouts/`, and UI leaves in
+`components/`. A page should import the components it renders.
+
+## Entry point
+
+```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";
+
+export const manifest = {
+  "/": () => import("./pages/home.js"),
+  "/login": layout({
+    layout: () => import("./layouts/auth.js"),
+    routes: { "/": () => import("./pages/login.js") },
+  }),
+  "/admin": layout({
+    layout: () => import("./layouts/app.js"),
+    guard: requireAuth,
+    routes: {
+      "/": () => import("./pages/admin/dashboard.js"),
+      "/orders": () => import("./pages/admin/orders.js"),
+      "/orders/:id": () => import("./pages/admin/order-detail.js"),
+    },
+  }),
+  "*": () => import("./pages/not-found.js"),
+};
+
+export default routes(manifest, {
+  errorPage: (err) => html`<main><h1>Something went wrong</h1><pre>${err.message}</pre></main>`,
+});
+```
+
+Exporting `manifest` lets `mado bake` inspect the same route table.
+
+## API and auth
+
+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.
+
+```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>
+  `,
+});
+```
+
+Mutations should declare invalidation near the write:
+
+```ts
+const save = mutation((payload) => api.post("/orders", payload), {
+  invalidates: ["/api/orders*"],
+});
+```
+
+## Forms
+
+Prefer one `useForm()` per user workflow.
+
+```ts
+const form = useForm({
+  email: { required: true, type: "email" },
+  "items.*.title": { required: true },
+});
+const items = form.array("items");
+```
+
+Use dotted paths for arrays (`items.0.title`) and keep async validation in
+`validateAsync` when it talks to the backend.
+
+## Release
+
+Local development uses `mado dev`. Production uses exactly one artifact:
+
+```bash
+mado release
+rsync -avz out/ user@server:/var/www/app/
+```
+
+`out/` is the deploy folder. `dist/` is internal build output.

package/docs/en/11-layouts.md

@@ -0,0 +1,115 @@
+# Layouts
+
+> **One blessed path.** Layouts in Mado are nested-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
+> 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
+import { layout, routes } from "@madojs/mado";
+import { requireAuth } from "./lib/auth.js";
+
+export const manifest = {
+  "/":       () => import("./pages/home.js"),       // no layout
+  "/login": layout({
+    layout:  () => import("./layouts/auth.js"),     // centered card
+    routes:  { "/": () => import("./pages/login.js") },
+  }),
+  "/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"),
+    },
+  }),
+  "*": () => import("./pages/not-found.js"),
+};
+
+export default routes(manifest);
+```
+
+A layout is just a `page({ view })` that renders `${ctx.child}` somewhere:
+
+```ts
+// src/layouts/app.ts
+import { html, page } from "@madojs/mado";
+import "../components/app-shell.js";   // <x-app-shell> (sidebar + topbar + slot)
+
+export default page({
+  view: ({ child }) => html`
+    <x-app-shell>${child}</x-app-shell>
+  `,
+});
+```
+
+That is the whole API.
+
+- **Order of layouts** matters: outer groups wrap inner groups. The order in
+  the manifest is exactly the order of rendering.
+- **One shell per group**, not one shell per page. If you want a different
+  shell for a subtree, create a new group with its own `layout`.
+- **Layouts can be lazy** (`() => import(...)`). They are loaded together
+  with the page.
+
+## Why "one blessed path"
+
+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
+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.
+
+### a) A single shell with the router slot in `main.ts`
+
+```ts
+import { html, render } from "@madojs/mado";
+import "./components/app-shell.js";
+import router from "./routes.js";
+
+render(html`<x-app-shell>${router.view}</x-app-shell>`, app);
+```
+
+Caveat: every route now lives inside one shell. You cannot have a centered
+login page or a marketing landing page without the admin chrome around it.
+Use this only for single-shell apps.
+
+### b) Per-page wrapping inside `view`
+
+```ts
+export default page({
+  view: () => html`
+    <x-app-shell>
+      <h1>Orders</h1>
+      ...
+    </x-app-shell>
+  `,
+});
+```
+
+Caveat: repetition. Every new page must remember the wrapper. The first time
+someone forgets it, the layout disappears and the LLM "fixes" it in the wrong
+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
+  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.
+
+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.

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

@@ -0,0 +1,217 @@
+# 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 `admin` starter (`mado init my-app --starter admin`) ships with these
+files pre-installed in `src/lib/`:
+
+- `api.ts` — `createApiClient(baseUrl)` + `accessToken` signal + `ApiError`
+- `auth.ts` — `restoreSession()`, `login()`, `logout()`, `requireAuth` guard
+
+The complete code is roughly 100 lines. Read it and own it.
+
+## Mental model
+
+- 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.
+
+That is the entire surface.
+
+## `src/lib/api.ts`
+
+```ts
+import { signal } from "@madojs/mado";
+
+export const accessToken = signal<string | null>(null);
+
+export class ApiError extends Error {
+  constructor(public status: number, public body: unknown, message: string) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+export interface ApiInit extends Omit<RequestInit, "body"> {
+  json?: unknown;
+  baseUrl?: string;
+}
+
+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 api = createApiClient("/api");
+```
+
+Key invariants:
+
+- **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`.
+
+## `src/lib/auth.ts`
+
+```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);
+}
+```
+
+Drop `requireAuth` into your manifest:
+
+```ts
+"/admin": layout({
+  layout:  () => import("./layouts/app.js"),
+  guard:   requireAuth,                       // ← entire group is now protected
+  routes:  { ... },
+}),
+```
+
+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      |
+
+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.
+
+## Dev proxy
+
+In development, point `/api/*` at your backend with `mado.config.json`:
+
+```jsonc
+{
+  "dev": {
+    "port": 5173,
+    "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.
+
+Whatever you change, change it **in `api.ts` only**. Pages stay innocent.

package/docs/en/13-deployment.md

@@ -0,0 +1,192 @@
+# Deployment
+
+> **One command. One artifact. Many hosts.** `mado release` writes everything
+> a static host needs into `out/`. The same `out/` can be pushed to nginx,
+> Cloudflare Pages, Netlify, S3 or GitHub Pages without re-building.
+
+## What `mado release` produces
+
+```
+out/
+├── index.html              ← SPA shell (loads the bundle + boots the router)
+├── assets/                 ← hashed bundles (main-ABC.js, chunk-XYZ.js, …)
+│   ├── *.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
+├── favicon.svg             ← your public/ assets copied verbatim
+├── _redirects              ← Cloudflare Pages / Netlify SPA fallback
+└── _headers                ← Cloudflare Pages / Netlify cache rules
+```
+
+`_redirects` and `_headers` are generated automatically and only if they do
+not already exist in your project. They are safely ignored by nginx and other
+hosts.
+
+## Local rehearsal
+
+```bash
+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.
+
+---
+
+## 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.
+
+```bash
+# Build the artifact locally
+mado release
+
+# Upload to the VPS
+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 nginx -t && sudo systemctl reload nginx
+```
+
+Key lines of the shipped `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.
+- `try_files $uri $uri/ /index.html;` — SPA fallback so deep links work
+  after a hard refresh.
+
+Enable HTTPS with Let's Encrypt / Certbot. Add HSTS once you have it.
+
+---
+
+## Recipe 2: Cloudflare Pages
+
+```bash
+mado release
+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.
+
+For preview branches, set the same build command in the CF Pages project:
+
+```
+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.
+
+---
+
+## Recipe 3: Static-only hosts (S3, Netlify, GitHub Pages)
+
+Any static host works because `out/` is just files. Pick whichever you have:
+
+**Netlify**
+```bash
+mado release
+npx netlify deploy --prod --dir=out
+```
+`_redirects` and `_headers` are recognized natively.
+
+**S3 / CloudFront**
+```bash
+mado release
+aws s3 sync out/ s3://my-bucket/ --delete \
+  --cache-control "public, max-age=31536000, immutable" --exclude '*.html'
+aws s3 sync out/ s3://my-bucket/ \
+  --cache-control "no-cache, must-revalidate" --include '*.html'
+```
+Configure CloudFront's "Default root object" to `index.html` and add a custom
+error response: 403/404 → `/index.html` with status 200 (SPA fallback).
+
+**GitHub Pages**
+```bash
+mado release
+# Push out/ into the gh-pages branch (or use actions/upload-pages-artifact)
+```
+Pages handles `index.html` automatically. There is no native SPA fallback;
+add a `404.html` that loads the SPA, or use the
+[`spa-github-pages`](https://github.com/rafgraph/spa-github-pages) trick.
+
+---
+
+## Cache-control matrix
+
+| Path                         | Cache-Control                                    | Why                              |
+|------------------------------|--------------------------------------------------|----------------------------------|
+| `/assets/main-*.js`          | `public, max-age=31536000, immutable`            | hashed filename → never reuse    |
+| `/assets/chunk-*.js`         | `public, max-age=31536000, immutable`            | same                             |
+| `/*.html`                    | `no-cache, must-revalidate`                      | always reflect latest deploy     |
+| 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.
+
+---
+
+## CI sketch (GitHub Actions)
+
+```yaml
+# .github/workflows/release.yml
+name: release
+on:
+  push:
+    branches: [main]
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npm ci
+      - run: npx mado release
+      - uses: actions/upload-artifact@v4
+        with:
+          name: out
+          path: out
+          retention-days: 7
+      # Pick one deploy step:
+      # - run: rsync -avz out/ user@server:/var/www/myapp/
+      # - run: npx wrangler pages deploy out --project-name=myapp
+      # - run: npx netlify deploy --prod --dir=out
+```
+
+---
+
+## Troubleshooting
+
+- **404 on hard refresh of a deep link.** Your host did not pick up SPA
+  fallback. nginx: check `try_files`. CF/Netlify: `_redirects` is present?
+  S3+CloudFront: configure the 404 → `/index.html` (200) error response.
+- **HTML is cached forever.** Either your host sent a default
+  `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.
+- **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.