@madojs/mado 0.5.1 → 0.6.1

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.

package/docs/en/14-testing.md

@@ -0,0 +1,82 @@
+# Testing
+
+Mado projects are plain TypeScript and browser APIs, so tests should stay plain
+too. The framework repository uses Node's built-in test runner plus `linkedom`
+for DOM tests.
+
+## Commands
+
+```bash
+npm run typecheck
+npm run build
+npm test
+```
+
+Before publishing or merging a release branch, run all three.
+
+## Unit tests with DOM
+
+```js
+import test from "node:test";
+import assert from "node:assert/strict";
+
+const { parseHTML } = await import("linkedom");
+const { window } = parseHTML("<!doctype html><html><body></body></html>");
+globalThis.window = window;
+globalThis.document = window.document;
+globalThis.Node = window.Node;
+globalThis.HTMLElement = window.HTMLElement;
+
+const { html, render } = await import("../dist/src/html.js");
+
+test("renders a value", () => {
+  const root = document.createElement("div");
+  render(html`<p>${"hello"}</p>`, root);
+  assert.equal(root.querySelector("p").textContent, "hello");
+});
+```
+
+Build first, then import from `dist/`. This tests the same files the browser
+will load.
+
+## What to cover
+
+Test behavior, not internal implementation details:
+
+- signal/computed scheduling and cleanup;
+- template binding edges: child values, attributes, events, directives;
+- route guards, redirects, scroll/focus behavior, error boundaries;
+- forms: validation, async validation races, field arrays;
+- resources/mutations: cache keys, invalidation, lifecycle cleanup;
+- CLI flows: `mado release`, `mado bake`, `mado preview`.
+
+## Browser smoke tests
+
+Use Playwright or another browser runner for flows that require real layout,
+focus, navigation or custom-element lifecycle. Keep them small:
+
+1. start the app;
+2. visit one route;
+3. click one link or submit one form;
+4. assert the user-visible result.
+
+Most regression tests should still be fast Node tests.
+
+## Test data
+
+Keep API data in local fixtures or tiny in-memory fake clients. Do not call real
+services from framework tests. For app tests, make the API client injectable via
+`createContext()` so pages can run against a fake client.
+
+## Release checklist
+
+```bash
+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.

package/docs/en/15-error-handling.md

@@ -0,0 +1,100 @@
+# Error handling
+
+Mado has three practical error layers: route loading, data loading, and user
+actions. Handle each layer where the user can recover.
+
+## Route errors
+
+Use a global `errorPage` in `routes()` for lazy import, `load()` and `view()`
+failures.
+
+```ts
+export default routes(manifest, {
+  errorPage: (err) => html`
+    <main>
+      <h1>Something went wrong</h1>
+      <pre>${err.message}</pre>
+      <a data-link href="/">Go home</a>
+    </main>
+  `,
+});
+```
+
+For a specific page, `page({ errorView })` wins over the global route boundary.
+
+```ts
+export default page({
+  load: async () => api.get("/reports"),
+  errorView: (err) => html`<x-report-error .error=${err}></x-report-error>`,
+  view: ({ data }) => html`<x-report .data=${data}></x-report>`,
+});
+```
+
+## Resource errors
+
+`resource()` exposes `error()` and `loading()`. Render a retry path near the data.
+
+```ts
+const users = resource(() => "/api/users", jsonFetcher<User[]>());
+
+html`
+  ${() => users.error()
+    ? html`<p role="alert">${users.error()!.message}</p>
+         <button @click=${users.refresh}>Retry</button>`
+    : null}
+`;
+```
+
+Use `HttpError` or your own API error type when the UI needs status codes.
+
+## Form and mutation errors
+
+Validation errors belong in `useForm()`. Server errors from writes belong near
+the submit button.
+
+```ts
+const form = useForm(
+  { email: { required: true, type: "email" } },
+  { validateAsync: (values) => api.validateUser(values) },
+);
+
+const save = mutation((values) => api.post("/users", values), {
+  invalidates: ["/api/users*"],
+});
+
+html`
+  <form @submit=${form.onSubmit(async values => {
+    await save.run(values);
+  })}>
+    <button ?disabled=${() => form.validating() || form.submitting()}>
+      Save
+    </button>
+    ${() => save.error() ? html`<p role="alert">${save.error()!.message}</p>` : null}
+  </form>
+`;
+```
+
+## Component cleanup
+
+If you subscribe to external browser APIs, clean them with `ctx.onDispose()`.
+Signals, effects and resources created inside setup are lifecycle-aware.
+
+```ts
+component("x-online", (ctx) => {
+  const online = signal(navigator.onLine);
+  const onChange = () => online.set(navigator.onLine);
+  window.addEventListener("online", onChange);
+  window.addEventListener("offline", onChange);
+  ctx.onDispose(() => {
+    window.removeEventListener("online", onChange);
+    window.removeEventListener("offline", onChange);
+  });
+  return () => html`${() => online() ? "Online" : "Offline"}`;
+});
+```
+
+## Logging rule
+
+Log once at the boundary that owns recovery. Avoid logging the same failure in
+the API client, resource, page and component. The user should get one visible
+message and developers should get one useful console error.