@madojs/mado 0.5.0

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

@@ -0,0 +1,108 @@
+# La voie Mado
+
+> Une seule bonne façon. Des contrats stricts. Pas de magie.
+
+Mado n'est pas seulement un framework — c'est un **ensemble de conventions**. Si vous les
+respectez, le projet reste compréhensible même avec 200 écrans et 5 développeurs. Si vous
+les enfreignez — les types et le linter vous le diront immédiatement.
+
+## Principes
+
+1. **Une seule voie.** Pour chaque tâche, il existe un seul chemin correct, pas cinq. Si vous
+   écrivez quelque chose d'inhabituel — demandez-vous si un helper idiomatique n'existe pas déjà.
+2. **L'explicite plutôt que la magie.** Pas de scanners de système de fichiers, pas de globals
+   implicites, pas d'effets de bord cachés. Tout ce que fait le framework peut être lu dans un
+   seul fichier.
+3. **La plateforme d'abord.** Si le navigateur propose déjà une fonctionnalité — utilisez-la
+   directement. Pas d'abstractions personnalisées sur `fetch`, `<form>`, l'History API, ou
+   Shadow DOM.
+4. **Types stricts.** `tsc --strict --noUncheckedIndexedAccess` toujours. Si quelque chose ne
+   peut pas être typé — c'est un signal que l'API est mauvaise.
+5. **Pas de dépendances runtime.** Chaque dépendance est un engagement sur des années ;
+   l'écosystème Web Components n'en a pas besoin.
+
+## Conventions
+
+### Structure du projet
+
+```
+src/
+├── routes.ts         ← manifeste de routes, un fichier par projet
+├── main.ts           ← point d'entrée : providers + montage de <x-app>
+├── pages/            ← une page = un fichier = `export default page({...})`
+├── components/       ← composants réutilisables, enregistrement des effets de bord
+├── lib/              ← contextes, clients API, logique métier sans UI
+└── styles/           ← styles partagés (si nécessaire), fichiers .ts avec css``
+```
+
+C'est **obligatoire**, pas optionnel. Si un projet a 10 développeurs — ils doivent
+tous écrire de la même manière.
+
+### Un composant = un fichier
+
+```ts
+// src/components/user-card.ts
+import { component, html, css } from '@madojs/mado';
+
+component('x-user-card', () => {
+  return () => html`<div class="card"><slot/></div>`;
+}, {
+  styles: css`.card { padding: 1rem; }`,
+});
+```
+
+`import './components/user-card.js'` **enregistre** le composant via
+`customElements.define`. C'est un effet de bord. Importez là où le composant est nécessaire.
+
+### Une seule façon de charger les données
+
+❌ N'appelez pas `fetch()` directement depuis un composant. Utilisez toujours :
+
+```ts
+// lecture → resource
+const user = resource(() => `/api/users/${id()}`, jsonFetcher());
+
+// écriture → mutation
+const save = mutation(api.save, { invalidates: ['/api/users*'] });
+```
+
+Cela fournit la mise en cache, l'annulation, la gestion des erreurs et l'invalidation automatique.
+
+### Une seule façon de décrire une page
+
+```ts
+// src/pages/user-profile.ts
+import { page, html, resource, jsonFetcher } from '@madojs/mado';
+
+export default page({
+  title: ({ id }) => `Utilisateur #${id}`,
+  view:  ({ params }) => html`...`,
+});
+```
+
+Trois emplacements — `title`, `load`, `view`. Pas d'autres. Vous voulez autre chose — c'est
+un composant ou un helper.
+
+### Une seule façon de déclarer les routes
+
+Voir [`01-routing.md`](./01-routing.md).
+
+## Ce que nous NE faisons PAS
+
+- ❌ N'écrivez pas de composants sans trait d'union. C'est la règle du navigateur pour
+  les custom elements : `user-card` est correct, `usercard` ne l'est pas.
+- `x-*` n'est qu'une convention pour les exemples et les tests Mado, pas un standard de marque.
+  En production, utilisez un préfixe de domaine : `app-*`, `crm-*`, `ticket-*`, `admin-*`.
+- ❌ N'utilisez pas `innerHTML` directement. Uniquement via `html\`\``.
+- ❌ N'appelez pas `setTimeout`/`setInterval` sans nettoyage. Uniquement à l'intérieur de `effect()`.
+- ❌ Ne stockez pas d'état mutable global. Utilisez les signals et `context`.
+- ❌ N'ajoutez pas de packages sans discussion. Chaque dépendance est un engagement.
+
+## En cas de doute
+
+Si vous vous demandez "quelle est la meilleure façon ici ?" — c'est un signal que :
+1. Soit il existe un helper intégré que vous ne connaissez pas (consultez `docs/`).
+2. Soit c'est une nouvelle situation — discutez-en et **consignez-la** dans ce document
+   comme une convention supplémentaire.
+
+"Un 'bien' cohérent vaut mieux qu'un 'idéal' varié."

package/docs/fr/01-routing.md

@@ -0,0 +1,202 @@
+# Routage
+
+> Un seul fichier manifeste. Pas de scanners de dossiers. Pas de caractères spéciaux.
+
+## Pourquoi pas de routes basées sur les fichiers
+
+Dans Next/SvelteKit/SolidStart, les routes apparaissent "magiquement" à partir des noms de
+fichiers. Cela a des avantages (la structure d'URL visible dans `pages/`), mais en production
+cela signifie :
+
+- Un plugin-scanner invisible dans le build. Sans lui, les fichiers ne sont que des fichiers.
+- Des caractères spéciaux dans les chemins : `[id]`, `(group)`, `_layout`, `+page.svelte`, `...slug`.
+- Les routes serveur et les routes client se mélangent.
+- Tester le routage est pénible : vous avez besoin d'un émulateur de build-tool.
+
+Mado considère cela comme **trop de magie**. Nous procédons différemment.
+
+## Manifeste
+
+Un seul fichier — `src/routes.ts`. Un seul objet. Lu de haut en bas.
+
+```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'),
+});
+```
+
+Vous voulez voir toutes les routes ? Ouvrez `routes.ts`. Pas de surprises.
+
+## Ce qui va à droite d'un chemin
+
+Chaque entrée est **l'une de ces trois choses** :
+
+### 1. Import lazy (recommandé)
+
+```ts
+'/posts': () => import('./pages/posts.js'),
+```
+
+- Le navigateur crée son propre chunk lors du bundling (esbuild --bundle --splitting).
+- Le module est chargé uniquement quand l'utilisateur visite la route.
+- Les navigations suivantes utilisent le résultat mis en cache.
+
+### 2. Page prête (eager)
+
+```ts
+import about from './pages/about.js';
+
+'/about': about,
+```
+
+Dans le bundle immédiatement, sans délai. Utilisez pour les pages critiques (accueil, connexion).
+
+### 3. Imbriqué avec layout
+
+```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'),
+    },
+  }),
+});
+```
+
+Un layout est juste une `page({...})` ordinaire qui rend `ctx.child` où elle le souhaite :
+
+```ts
+// src/layouts/admin.ts
+import { page, html, css, component } from '@madojs/mado';
+
+export default page({
+  view: ({ child }) => html`
+    <div class="admin">
+      <aside><nav>...</nav></aside>
+      <main>${child}</main>
+    </div>
+  `,
+});
+```
+
+## Contrat de page
+
+```ts
+import { page, html, resource, jsonFetcher } from '@madojs/mado';
+
+export default page({
+  title: ({ id }) => `Utilisateur #${id}`,        // string | (params) => string
+  load:  ({ id }) => resource(...),                // optionnel, retourne Resource ou data
+  view:  ({ params, data, path, child }) => html`...`,  // OBLIGATOIRE
+});
+```
+
+Trois emplacements, c'est tout. Si vous exportez autre chose que `page({...})`, une simple
+fonction par exemple — `routes()` génère une erreur claire :
+
+```
+[Mado] La route lazy n'a pas retourné page({...}) comme export par défaut.
+```
+
+## Paramètres d'URL
+
+```ts
+'/users/:id': () => import('./pages/user.js'),
+```
+
+```ts
+export default page<{ id: string }>({
+  title: ({ id }) => `Utilisateur ${id}`,
+  view:  ({ params }) => html`<h1>${params.id}</h1>`,
+});
+```
+
+Les types sont passés dans `page<Params>` — `tsc` vérifie que vous n'accédez pas à
+`params.foo` qui n'existe pas dans la route.
+
+## Options globales
+
+```ts
+export default routes(
+  { '/': home, '/about': about, '*': nf },
+  {
+    titleSuffix: ' · MonApp',                      // → "Accueil · MonApp"
+    loading: () => html`<x-spinner/>`,             // pendant le chargement du module
+    error:   (err) => html`<x-fatal-error .err=${err}/>`,
+  },
+);
+```
+
+## Navigation programmatique
+
+```ts
+import route from './routes.js';
+
+route.navigate('/posts');
+route.navigate('/posts?page=2');
+route.navigate('/posts', { replace: true });
+```
+
+Les clics sur `<a href="/foo" data-link>` sont interceptés globalement (sans l'attribut —
+le navigateur effectue un rechargement complet, comme prévu pour les liens externes).
+
+## Paramètres de requête
+
+```ts
+import { queryParam } from '@madojs/mado';
+
+const page = queryParam('page', '1');
+page();              // '1'
+page.set('2');       // history.replaceState + re-rendu
+page.set(null);      // supprimer le paramètre
+page.set('3', { push: true });   // history.pushState
+```
+
+`queryParam` est un signal normal. Utilisez-le n'importe où : dans les pages, les composants,
+les computed.
+
+## Ce qui est intentionnellement absent
+
+- ❌ Auto-scan de `pages/`. **Un seul fichier manifeste explicite**.
+- ❌ Caractères spéciaux dans les chemins (`[id]`, `(group)`, `_layout`). **Les paramètres sont
+  uniquement `:name`, rien d'autre**.
+- ❌ Routage côté serveur dans le même manifeste. Mado est un framework côté client.
+- ❌ Auto-préchargement au survol. Si vous en avez vraiment besoin — faites-le manuellement :
+  `link.addEventListener('mouseenter', loader)`. Généralement inutile.
+
+## FAQ
+
+**Et si j'ai 100 routes ? Le fichier ne deviendra-t-il pas énorme ?**
+Il atteindra ~150 lignes. C'est toujours **une seule source de vérité** contre une centaine
+de fichiers dans `pages/` avec des noms magiques. En pratique, même les grands projets (1000+
+pages) peuvent se diviser en manifestes de fonctionnalités :
+
+```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'),
+});
+```
+
+**Comment tester le routage ?**
+Importez `routes.ts` — c'est juste un objet. Substituez votre router mock. Pas besoin
+d'émulation de build-tool.

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

@@ -0,0 +1,58 @@
+# Structure du projet
+
+Chaque nouveau projet Mado a la même structure. C'est une convention **obligatoire**.
+
+```
+my-app/
+├── package.json              # exactement 1 dép : typescript (esbuild optionnel)
+├── tsconfig.json             # avec paths "@madojs/mado" → import sans chemins relatifs
+├── Dockerfile + nginx.conf   # copiés depuis Mado/ lors du scaffold
+├── .gitlab-ci.yml | .github/workflows/ci.yml
+├── server/serve.mjs          # dev-server de Mado, sans dépendances
+├── scripts/
+│   ├── bundle.mjs            # bundle de production esbuild
+│   └── new.mjs               # générateur de pages
+├── templates/                # templates pour new.mjs
+├── docs/                     # documentation du projet (vous pouvez copier nos guides)
+├── public/                   # assets statiques (favicon, manifests)
+└── src/
+    ├── main.ts               # entrée : providers + montage de <x-app>
+    ├── routes.ts             # manifeste de routes
+    ├── pages/                # une page = un fichier = `export default page({...})`
+    ├── components/           # composants réutilisables (x-*)
+    ├── layouts/              # pages de layout (pour nested)
+    └── lib/
+        ├── api.ts            # tous les wrappers fetch
+        ├── contexts.ts       # createContext(...)
+        ├── theme.ts          # thèmes
+        └── ...               # utilitaires, types, règles métier
+```
+
+## Où mettre un nouveau fichier ?
+
+| Quoi | Où |
+|---|---|
+| Page pour une nouvelle URL | `src/pages/foo.ts` + ajouter à `src/routes.ts` |
+| Widget UI réutilisable | `src/components/foo-bar.ts` |
+| Wrapper API | `src/lib/api.ts` (ajouter une méthode) |
+| Contexte global (thème, utilisateur, i18n) | `src/lib/<nom>.ts` |
+| Fonction pure sans UI | `src/lib/util/<nom>.ts` |
+
+Si vous ne savez pas où — c'est un signal que **l'architecture souffre**.
+Consultez l'équipe, **consignez** la réponse dans `docs/`.
+
+## Règles de nommage
+
+| Quoi | Style | Exemple |
+|---|---|---|
+| Fichier | kebab-case | `user-profile.ts` |
+| Tag de composant | `x-` + kebab | `<x-user-profile>` |
+| Context | PascalCase + `Ctx` | `ThemeCtx`, `AuthCtx` |
+| Signal | camelCase | `userId`, `isLoggedIn` |
+| Fonction de page (composant interne) | `x-<route>-page` | `<x-posts-page>` |
+
+## Ce qui ne va PAS dans src/
+
+- ❌ Configurations de build-tool (webpack, rollup, vite) — nous n'en avons pas.
+- ❌ Fichiers `.env` — les variables d'environnement sont lues depuis `process.env`/`import.meta.env` dans `lib/config.ts`.
+- ❌ Tests mélangés avec le code — tout dans `test/`.

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

@@ -0,0 +1,290 @@
+# Static intelligent (`bake`)
+
+> Générer du HTML pour le SEO sans SSR runtime. **Idée : données et vue dans un seul fichier, sortie statique.**
+
+`bake` est un **prérendu au moment du build**, pas du SSR. La sortie est des fichiers `*.html`
+statiques que n'importe quel nginx/Cloudflare sert comme du contenu statique ordinaire. Sur le
+client, les Web Components s'animent et la navigation SPA continue de fonctionner.
+
+---
+
+## Quand `bake` est adapté
+
+- **Pages marketing** : landing pages, sous-landings pour des campagnes publicitaires, pages produits.
+- **Catalogue avec un ensemble de pages relativement stable** : blog, documentation, portfolio,
+  e-commerce jusqu'à **~10k SKUs** avec des mises à jour moins d'une fois par heure.
+- **Contenu identique pour tous les utilisateurs** : la page entière est identique pour un
+  visiteur et un utilisateur authentifié (ou l'authentification est rendue côté client via `effect()`).
+- Vous avez besoin d'un **bon SEO** (rich snippets, OG, JSON-LD) et d'un **premier affichage
+  rapide** sans faire tourner des serveurs node en production.
+
+## Quand `bake` n'est **pas** adapté
+
+- **Des centaines de milliers de pages avec des changements fréquents**. `bake` parcourt tous
+  les `paths` de façon synchrone en une seule exécution. Pour 100k+ pages, cela signifie des
+  minutes de rebuild, et l'invalidation d'une page nécessite soit un rebake complet, soit une
+  logique CI séparée (voir ci-dessous sur la revalidation ciblée).
+- **Contenu personnalisé dans le HTML**. Si la page doit afficher "Bonjour, Ivan" dans le
+  `<title>` ou dans les meta — ce n'est pas pour `bake`. Les tableaux de bord authentifiés,
+  les fils personnalisés, un panier avec des prix réels pour l'utilisateur — gardez-les en SPA.
+- **Des API uniquement serveur sont nécessaires lors du rendu** : cookies, headers, vraies
+  requêtes réseau vers des API privées. Côté bake, seul `linkedom` est disponible, pas
+  d'environnement Node pour les composants.
+- **Tests A/B et flags qui modifient le markup au premier affichage**. `bake` verrouillera
+  une variante. Gérez le comportement dynamique côté client via `effect()`.
+- **Données en temps réel / qui changent fréquemment** (cours boursiers, stock entrepôt à la
+  minute). `bake.revalidate` est des métadonnées, pas du runtime : le framework ne re-bake
+  rien lui-même.
+- **Contenu derrière une authentification** (admin, outils internes). Inutile ; utilisez le
+  mode SPA.
+
+---
+
+## Concept
+
+`page({...})` a quatre emplacements optionnels liés à `bake` :
+
+- `head` — meta, OG, JSON-LD.
+- `bake.paths` — liste des paramètres URL pour la génération (build-time, peut être `async`).
+- `bake.data` — données pour une URL spécifique (build-time, peut être `async`).
+- `bake.revalidate` — après combien de secondes le cache est périmé (écrit dans `<meta>`, la
+  vraie invalidation est gérée par votre CI/CDN).
+
+La commande `npm run bake` parcourt toutes les entrées `page` avec `bake`, génère le HTML via
+`linkedom`, et le place dans `out/<chemin>/index.html`. **Pas de Chromium nécessaire** —
+`linkedom` fait ~50 Ko.
+
+---
+
+## Exemple
+
+```ts
+// src/pages/product.ts
+import { page, component, html } from "@madojs/mado";
+import { findProduct, products, type Product } from "../lib/products.js";
+
+component("x-product-page", ({ host }) => {
+  return () => {
+    const p = findProduct(host.dataset.slug);
+    return p
+      ? html`<h1>${p.name}</h1><p>${p.description}</p>`
+      : html`<p>Introuvable.</p>`;
+  };
+});
+
+export default page<{ slug: string }, Product | undefined>({
+  title: ({ slug }) => `${findProduct(slug)?.name} — MaBoutique`,
+
+  head: ({ slug }, baked) => {
+    const p = baked ?? findProduct(slug);
+    if (!p) return {};
+    return {
+      description: p.description,
+      canonical: `/product/${p.slug}`,
+      og: { title: p.name, image: p.image, type: "product" },
+      jsonLd: {
+        "@context": "https://schema.org",
+        "@type": "Product",
+        name: p.name,
+        offers: { "@type": "Offer", price: p.price, priceCurrency: p.currency },
+      },
+    };
+  },
+
+  bake: {
+    paths: () => products.map((p) => ({ slug: p.slug })),
+    data: ({ slug }) => findProduct(slug),
+    revalidate: 3600,
+  },
+
+  view: ({ params }) =>
+    html`<x-product-page data-slug=${params.slug}></x-product-page>`,
+});
+```
+
+```ts
+// src/routes.ts
+import { routes, type RoutesMap } from "@madojs/mado";
+
+// Exporter À LA FOIS default (RouterApi pour le runtime) ET manifest (pour le script bake).
+export const manifest: RoutesMap = {
+  "/": () => import("./pages/home.js"),
+  "/product/:slug": () => import("./pages/product.js"),
+  "*": () => import("./pages/not-found.js"),
+};
+
+export default routes(manifest, { titleSuffix: " · MaBoutique" });
+```
+
+## Exécution
+
+```bash
+npm install -D linkedom esbuild
+npm run build
+npm run bake
+```
+
+Vous obtenez :
+
+```
+out/
+├── product/
+│   ├── mado-mug/index.html        ← HTML avec meta + JSON-LD
+│   ├── raw-bundler/index.html
+│   └── shadow-dom/index.html
+└── sitemap.xml
+```
+
+## Contenu du HTML généré
+
+```html
+<head>
+  <title>Mado Mug — MaBoutique</title>
+  <meta name="description" content="..." data-mado-head="baked">
+  <link rel="canonical" href="/product/mado-mug" data-mado-head="baked">
+  <meta property="og:title" content="Mado Mug" data-mado-head="baked">
+  <meta property="og:image" content="..." data-mado-head="baked">
+  <script type="application/ld+json" data-mado-head="baked">
+    {"@context":"https://schema.org","@type":"Product","..."}
+  </script>
+  <meta name="bake-revalidate" content="3600" data-mado-head="baked">
+  <meta name="bake-stamp" content="1234567890" data-mado-head="baked">
+</head>
+<body>
+  <div id="app">
+    <x-product-page data-slug="mado-mug">
+      <h1>Mado Mug</h1>
+      <p>Un mug avec l'inscription "zéro dépendances".</p>
+      <strong>12 EUR</strong>
+    </x-product-page>
+  </div>
+
+  <!-- données préchargées pour l'hydratation -->
+  <script id="bake" type="application/json">
+    {"slug":"mado-mug","name":"Mado Mug","price":12,"..."}
+  </script>
+
+  <script type="module" src="/dist/examples/main.js"></script>
+</body>
+```
+
+Après le chargement du JS :
+
+1. Les Web Components `<x-product-page>` s'animent (le navigateur connaît déjà les custom elements).
+2. `page.load()` reçoit `baked` comme initialData — pas d'appels `fetch` inutiles.
+3. La navigation SPA continue de fonctionner normalement.
+
+---
+
+## Cookbook : Scénarios typiques
+
+### Blog (Markdown → bake)
+
+```ts
+// src/lib/posts.ts
+import { readdirSync, readFileSync } from "node:fs";
+// (ce module est importé uniquement depuis le script bake,
+// il ne doit pas se retrouver dans le graph navigateur — mettez-le dans lib/server/ ou excluez-le)
+
+export const allPosts = () =>
+  readdirSync("content/blog").map((file) => ({
+    slug: file.replace(/\.md$/, ""),
+    ...parseFrontmatter(readFileSync(`content/blog/${file}`, "utf-8")),
+  }));
+```
+
+```ts
+// src/pages/blog-post.ts
+import { page, html } from "@madojs/mado";
+import { allPosts } from "../lib/posts.js";
+
+export default page<{ slug: string }>({
+  title: ({ slug }) => allPosts().find((p) => p.slug === slug)?.title ?? slug,
+  head: ({ slug }, post) => ({
+    description: post?.excerpt,
+    canonical: `/blog/${slug}`,
+    og: { title: post?.title, type: "article" },
+  }),
+  bake: {
+    paths: () => allPosts().map(({ slug }) => ({ slug })),
+    data: ({ slug }) => allPosts().find((p) => p.slug === slug),
+  },
+  view: ({ params }) =>
+    html`<x-blog-post data-slug=${params.slug}></x-blog-post>`,
+});
+```
+
+### Catalogue produits (e-commerce, ≤ 10k SKUs)
+
+- `bake.paths` → SELECT slug FROM products
+- `bake.data` → SELECT * FROM products WHERE slug=?
+- Invalidation complète toutes les N heures via cron + `npm run bake`
+- Invalidation ciblée d'un seul produit : webhook → rebuild uniquement cette entrée `paths`
+
+### Documentation
+
+- `bake.paths` — parcours du système de fichiers `docs/**/*.md`
+- `bake.data` — parsing Markdown
+- `head.jsonLd` — `TechArticle`
+
+---
+
+## Revalidate / CDN
+
+`bake.revalidate: 3600` écrit `<meta name="bake-revalidate" content="3600">` et `bake-stamp`
+dans le HTML. C'est des **métadonnées** — le framework ne re-bake rien lui-même. Stratégies :
+
+1. **Option la plus simple** : cron dans CI — `npm run bake && rsync out/ origin:/var/www/`.
+2. **Via CDN** (Cloudflare/Fastly) : servir le HTML avec `Cache-Control: max-age=3600`. Le CDN
+   s'invalide lui-même.
+3. **Déclencheur webhook** : API boutique → POST `/_revalidate?path=/product/mado-mug` → CI
+   re-bake uniquement cette page (vous pouvez implémenter `bake.paths` pour retourner une liste
+   ciblée basée sur un paramètre d'environnement).
+
+---
+
+## Comparaison avec les alternatives
+
+|                          | Next.js SSG/ISR    | playwright-prerender | **mado bake** |
+|--------------------------|--------------------|----------------------|-----------------|
+| Chrome requis en CI      | non                | **oui** (~300 Mo)    | **non**          |
+| Node requis en production | pour ISR          | non                  | **non**          |
+| Temps pour 1000 pages    | minutes            | minutes              | **secondes**     |
+| Niveau de magie          | élevé              | faible               | **zéro**        |
+| Parser HTML              | moteur React       | navigateur           | linkedom (~50 Ko) |
+| Configuration            | next.config.js + … | script unique        | script unique   |
+| Source de vérité vue+données | séparées       | page                 | **une seule page** |
+
+---
+
+## Limitations et pièges
+
+- **Il n'y a pas de navigateur côté bake.** Ne fonctionnent pas : `setTimeout` (techniquement
+  ça marche, mais bake se termine avant qu'il ne se déclenche), `fetch` vers des URLs relatives,
+  tous les effets de bord `effect()`/`signal()`, le vrai `requestAnimationFrame`. La fonction
+  de rendu doit être déterministe selon `params` / `data`.
+- **`linkedom` ≠ navigateur.** Toutes les API DOM ne sont pas supportées (par exemple,
+  `HTMLElement.click()` se comporte plus simplement). La logique complexe dans les Web Components
+  ne s'exécutera dans le navigateur qu'après `connectedCallback` ; seul ce qui a été rendu
+  de façon synchrone lors du premier passage se retrouvera dans le HTML baked.
+- **Rendre le contenu dynamique côté client.** L'heure actuelle, les tests A/B, les
+  banners géo, le panier de l'utilisateur — ceux-ci ne doivent pas être dans le HTML baked.
+  Utilisez `effect()` pour le rendu côté client.
+- **Les imports côté serveur ne doivent pas se retrouver dans le graph client.** Si
+  `lib/posts.ts` importe `node:fs`, il ne peut pas être importé depuis `view`. Gardez ces
+  modules dans un dossier séparé (`lib/build/`) et utilisez-les uniquement depuis
+  `bake.paths`/`bake.data`.
+- **`paths` et `data` sont exécutés à chaque exécution de bake.** S'ils impliquent une
+  requête de base de données lourde — mettez en cache au niveau du script.
+
+---
+
+## TL;DR
+
+Si une page est **identique pour tous les utilisateurs**, a **un ensemble d'URLs relativement
+stable**, et que **le SEO + le premier affichage** comptent — ajoutez `bake: { paths, data }`
+et obtenez du HTML statique avec meta/JSON-LD/sitemap en millisecondes. Pas de serveur node,
+pas de Chrome, pas de magie.
+
+Si la page est personnalisée, ou qu'il y a des millions d'URLs, ou que le contenu change en
+temps réel — `bake` n'est pas votre outil. Gardez-la en SPA ou intégrez un framework SSR séparé.