@madojs/mado 0.11.0 → 0.12.0

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

@@ -1,289 +0,0 @@
-# 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">
-</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="/assets/main-abc123.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">`
-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é.

package/docs/fr/04-ide-setup.md

@@ -1,162 +0,0 @@
-# Support IDE pour `html\`\`` et `css\`\``
-
-Par défaut, `html\`...\`` et `css\`...\`` ne sont que des tagged-template strings.
-TypeScript ne les connaît pas, l'IDE ne les colore pas. C'est un **compromis délibéré**
-en faveur de zéro dépendances runtime et pas de plugins de build.
-
-La bonne nouvelle : Mado utilise les mêmes conventions que [lit](https://lit.dev), donc les
-outils IDE **prêts à l'emploi** de l'écosystème lit fonctionnent directement.
-
----
-
-## VS Code (configuration recommandée)
-
-### 1. Installer [lit-plugin](https://marketplace.visualstudio.com/items?itemName=runem.lit-plugin)
-
-VS Code → Extensions → chercher **"lit-plugin"** (par runem) → Installer.
-
-Ce que vous obtenez :
-
-- Coloration HTML à l'intérieur de `html\`\``.
-- Coloration CSS à l'intérieur de `css\`\``.
-- Auto-complétion pour les tags HTML, attributs et événements.
-- Vérification des fautes de frappe dans les attributs.
-- Aller à la définition pour les custom elements (si décrits via `customElements.json` ou JSDoc).
-- Diagnostics sur les bindings invalides.
-
-### 2. Spécifier les noms de tags
-
-`lit-plugin` cherche les identifiants `html` et `css` dans les imports. Si vous ne les
-renommez pas à l'import — la configuration est nulle, tout fonctionne :
-
-```ts
-import { html, css } from "@madojs/mado";
-
-const tpl = html`<button @click=${fn}>${label}</button>`;
-```
-
-### 3. (Optionnel) Votre propre `customElements.json`
-
-Si vous voulez l'auto-complétion pour vos propres composants `<x-*>`, décrivez-les via
-[Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) :
-
-```bash
-npm install --save-dev @custom-elements-manifest/analyzer
-npx cem analyze --globs "src/components/**/*.ts"
-```
-
-Cela crée `custom-elements.json`, que `lit-plugin` récupère automatiquement.
-
----
-
-## WebStorm / IntelliJ
-
-WebStorm comprend `html\`\`` et `css\`\`` **nativement** — support natif des template literals
-de style lit depuis 2021. Pas de plugins nécessaires.
-
-Si la coloration n'apparaît pas :
-
-- Settings → Languages & Frameworks → JavaScript → vérifiez que "Use types from server" est activé
-- Redémarrer le serveur TS : ⌘+⇧+P → "Restart TypeScript Server"
-
----
-
-## Neovim / Helix
-
-Utilisez [`lit-html-server`](https://github.com/runem/lit-analyzer/tree/master/packages/lit-html-server)
-(serveur LSP du même auteur que lit-plugin) :
-
-```bash
-npm install -g lit-html-server
-```
-
-`init.lua` (pour `lspconfig`) :
-
-```lua
-require('lspconfig').lit_html.setup{
-  cmd = { 'lit-html-server', '--stdio' },
-  filetypes = { 'typescript', 'javascript' },
-}
-```
-
----
-
-## Ce qui ne fonctionne PAS (limitations connues)
-
-- **Vérification de type des bindings de signal.** `html\`<input .value=${count}>\`` — `lit-plugin`
-  attend une string, mais `count` est un `Signal<number>`. Supprimez avec `// @ts-expect-error`
-  ou `<!-- @ts-ignore -->`. Sera amélioré en Phase 3+.
-- **Les directives personnalisées (`each`)** sont reconnues comme des fonctions ordinaires — sans
-  sémantique spéciale dans le plugin.
-- **Les attributs avec préfixes `@`, `.`, `?`** sont parfois signalés comme des erreurs si
-  `lit-plugin` a `"no-unknown-attribute": false` désactivé. Dans `.vscode/settings.json` :
-
-```json
-{
-  "lit-plugin.rules": {
-    "no-unknown-attribute": "off",
-    "no-incompatible-type-binding": "off"
-  }
-}
-```
-
----
-
-## Typage JSDoc pour les composants
-
-Pour que l'IDE récupère les custom elements à l'intérieur de `html\`\``, annotez la
-définition `component()` via JSDoc :
-
-```ts
-/**
- * @element x-counter
- * @attr {number} initial - valeur de départ
- * @fires {CustomEvent<number>} change - à chaque changement
- */
-component("x-counter", () => {
-  /* ... */
-});
-```
-
-`lit-plugin` le reconnaît et suggère des attributs quand vous tapez `<x-counter ...>`.
-
----
-
-## Prettier / formatage
-
-Prettier 3.0+ formate `html\`\`` via [`@prettier/plugin-xml`](https://github.com/prettier/plugin-xml)
-ou le mode intégré. `.prettierrc` minimal :
-
-```json
-{
-  "semi": true,
-  "singleQuote": false,
-  "embeddedLanguageFormatting": "auto"
-}
-```
-
-`embeddedLanguageFormatting: "auto"` (par défaut) formate le contenu des tagged-template
-literals avec des tags connus (`html`, `css`).
-
----
-
-## ESLint
-
-Si vous utilisez ESLint, le plugin [`eslint-plugin-lit`](https://github.com/43081j/eslint-plugin-lit)
-fournit des règles spécifiques au HTML en tagged-template, et
-[`eslint-plugin-wc`](https://github.com/43081j/eslint-plugin-wc) couvre les Web Components
-en général. La configuration est à votre discrétion, elle n'est pas obligatoire.
-
----
-
-## TL;DR
-
-| Éditeur | Configuration | Niveau DX |
-|---|---|---|
-| **VS Code** | installer `lit-plugin` | ★★★★ |
-| **WebStorm** | rien | ★★★★ |
-| **Neovim/Helix** | `lit-html-server` via LSP | ★★★ |
-| **Vim sans LSP** | manuel | ★ |
-
-Mado fonctionne aussi sans plugin IDE : `html\`\`` reste du code TS valide, tout se
-compile et s'exécute. La string à l'intérieur est juste colorée comme une string.

package/docs/fr/05-why-mado.md

@@ -1,193 +0,0 @@
-# Pourquoi Mado (et pourquoi pas Lit / Solid / Alpine / htmx)
-
-> Si vous choisissez un stack frontend pour un nouveau projet, cette page est pour vous.  
-> Si vous avez déjà quelque chose qui fonctionne — **ne migrez pas pour le plaisir de migrer**, ça coûte toujours plus cher qu'il n'y paraît.
-
-Mado n'est pas un "tueur" de React/Vue/Svelte. C'est un outil spécialisé. J'explique ici honnêtement **dans quels cas Mado est vraiment meilleur que les alternatives**, et dans lesquels il ne l'est pas.
-
----
-
-## TL;DR — un seul tableau
-
-| Si vous vous souciez de… | Choisissez |
-|---|---|
-| Meilleure infrastructure d'apprentissage / grand écosystème | **React** ou **Vue** |
-| Design system de composants pour l'intégration dans n'importe quel framework | **Lit** |
-| Top performance sur les grandes listes, "proche du vanilla" avec JSX | **Solid** ou **Svelte 5** |
-| Amélioration progressive d'apps classiques rendues côté serveur | **htmx** + votre backend |
-| "Saupoudrer" de la réactivité sur un site statique | **Alpine.js** |
-| Outillage minimal, maximum de plateforme, tout dans une boîte (router + data + forms + SEO), lisible en une soirée | **Mado** ✓ |
-
-Si votre cas ne tombe pas dans le dernier point — Mado n'est probablement pas le meilleur choix. C'est normal.
-
----
-
-## Mado vs Lit
-
-**Lit** est l'alternative la plus proche dans l'esprit. Même approche : Web Components + tagged templates + magie minimale.
-
-| | Lit | Mado |
-|---|---|---|
-| Taille | ~6 Ko | ~16 Ko |
-| Âge / support | ~10 ans, Google | 6 mois, auteur unique |
-| Réactivité | décorateurs `@property` + `requestUpdate` manuel | signals (`signal`/`computed`/`effect`) intégrés |
-| Router | aucun, vous devez en trouver un (`@lit-labs/router`, etc.) | inclus : `routes()` + layout groups + prefetch |
-| Chargement de données | aucun, vous devez l'assembler | `resource()` + `mutation()` + invalidation glob |
-| Forms | aucun | `useForm()` avec contraintes proches du HTML |
-| SEO / statique | complexe (`@lit-labs/ssr`) | `bake` (linkedom) + edge-prerender |
-| Build | nécessite des plugins spécifiques au framework | Vite transport + runtime natif |
-| Style de code | classes + décorateurs | fonctions + tagged templates |
-| Écosystème | réel (Shoelace, Material Web, etc.) | aucun |
-| Quand choisir | écrire un design system / bibliothèque Web Components pour l'intégration | écrire une application complète, vouloir tout dans une boîte |
-
-**Pitch honnête :** *"Lit est meilleur si vous écrivez un design system de composants. Mado est meilleur si vous écrivez une application et voulez des batteries incluses sans assembler 8 packages."*
-
----
-
-## Mado vs Solid
-
-**Solid** est une bibliothèque réactive de premier plan construite sur les signals. Techniquement très impressionnant.
-
-| | Solid | Mado |
-|---|---|---|
-| Taille | ~7 Ko | ~16 Ko |
-| Performance | top-3 sur js-framework-benchmark | bonne, mais pas au top |
-| Réactivité | signals (même classe d'idées) | signals |
-| Templates | JSX (compilé en expressions réactives) | tagged template `html\`\`` |
-| Modèle de composant | fonctions, nœuds virtuels Solid | Web Components |
-| Build | Vite + babel-plugin-solid requis | Vite pour dev/build, aucune dépendance runtime |
-| Router | `@solidjs/router` | inclus |
-| Données | `createResource` | `resource()` |
-| SSR | sérieusement supporté (SolidStart) | intentionnellement absent |
-| Écosystème | en croissance, ~50 packages | aucun |
-| Quand choisir | besoin de top performance + JSX + prêt à configurer le build | vouloir un runtime browser-native avec tooling simple |
-
-**Pitch honnête :** *"Solid est techniquement plus rapide et plus mature. Mado est plus simple dans son idée : runtime browser-native, Web Components, tagged templates, et Vite fait le travail dev/build ennuyeux. Si vous voulez JSX et un écosystème plus large, allez avec Solid."*
-
----
-
-## Mado vs Svelte 5
-
-**Svelte 5** avec les runes — aussi un modèle signal, aussi minimaliste.
-
-| | Svelte 5 | Mado |
-|---|---|---|
-| Taille runtime | ~3 Ko | ~16 Ko |
-| Compilateur | requis (.svelte → JS) | aucun |
-| Syntaxe | format .svelte personnalisé | TS + tagged templates |
-| Réactivité | `$state`/`$derived` (runes) | `signal`/`computed` |
-| SSR / SvelteKit | complet, mature | intentionnellement absent |
-| Écosystème | large, excellents dev-tools | aucun |
-| Quand choisir | nouveau projet de production avec une équipe | outil privé/interne, besoin de simplicité |
-
-**Pitch honnête :** *"Svelte est un choix produit. Mado est un choix ingénierie. Si vous avez une équipe et une app de production — Svelte. Si vous êtes seul et voulez le contrôle — Mado."*
-
----
-
-## Mado vs htmx
-
-**htmx** est une autre école : des fragments HTML sur le fil.
-
-| | htmx | Mado |
-|---|---|---|
-| Architecture | HTML du serveur, mis à jour via des fragments | SPA : JS charge les données, se rend lui-même |
-| Dépendance backend | forte (le backend doit pouvoir servir du HTML) | faible (le backend est une API JSON) |
-| État client | minimal (cookies, localStorage) | complet (signal, persisted) |
-| Mises à jour optimistes | difficiles | faciles (mutation + invalidates) |
-| Offline / PWA | faible | correct |
-| Taille | ~14 Ko | ~16 Ko |
-| Quand choisir | app classique rendue côté serveur (Rails, Django, Phoenix), besoin de "revitaliser" | expérience SPA requise, backend est REST/GraphQL |
-
-**Pitch honnête :** *"htmx — si le backend est solide et peut servir du HTML. Mado — si le backend sert du JSON et que vous avez besoin d'une expérience SPA complète."*
-
----
-
-## Mado vs Alpine.js
-
-**Alpine** — attributs réactifs directement dans le HTML.
-
-| | Alpine | Mado |
-|---|---|---|
-| Objectif | améliorer du HTML statique | SPA complet |
-| Taille | ~7 Ko | ~16 Ko |
-| Gestion d'état | `x-data` localement | signals + context + persisted |
-| Routage | aucun | inclus |
-| TypeScript | faible | première classe |
-| Quand choisir | sites statiques, landing pages, besoin de 5 boutons interactifs | app complète : pages, navigation, forms, données |
-
-**Pitch honnête :** *"Alpine — pour l'interactivité sur les sites statiques. Mado — pour une application complète."*
-
----
-
-## Mado vs React + écosystème
-
-Je ne vais pas m'étendre là-dessus longtemps, car React est dans une **catégorie différente** en termes d'écosystème et de maturité. Mais si vous comparez sérieusement :
-
-**React gagne :**
-- écosystème massif : milliers de kits UI, milliers d'articles, tutoriels infinis ;
-- les assistants IA (ChatGPT, Copilot) connaissent React mieux que tout ;
-- meilleur marché de l'emploi ;
-- meilleur support SSR (Next.js).
-
-**Mado gagne :**
-- taille de bundle des dizaines de fois plus petite ;
-- zéro infrastructure (pas de Vite, pas de Babel, pas de 200 packages) ;
-- lisible en une soirée — si quelque chose casse, ouvrez `src/` ;
-- signals au lieu de hooks (pas de règles "ne peut pas être utilisé dans un if", pas de pièges de stale-closure) ;
-- pas besoin de migrer entre les versions majeures.
-
-**Quand choisir Mado plutôt que React :**
-- projet de 1–3 personnes, pour des années à venir ;
-- la taille du bundle est critique ;
-- vous êtes fatigué du React fatigue et prêt à sacrifier l'écosystème pour la simplicité.
-
-**Quand choisir React :**
-- équipe de 5 personnes ou plus ;
-- vous avez besoin de kits UI, vous avez besoin de l'écosystème ;
-- un projet qui recrutera de nouvelles personnes sur le marché ;
-- vous avez besoin de SSR avec hydratation (Next.js).
-
----
-
-## L'argument le plus fort de Mado
-
-Pas la taille, pas la performance, pas les signals — tout a de meilleurs concurrents.
-
-> **"Ouvrez le source et lisez-le en une soirée. ~3500 lignes, petits modules. Si quelque chose casse — vous n'allez pas sur une issue avec 3000 commentaires. Vous allez dans `src/router/` et lisez le code."**
-
-C'est ce qu'on appelle la **propriété** — vous possédez le code, plutôt que de dépendre de celui de quelqu'un d'autre.
-
-Pour les développeurs backend habitués aux petites bibliothèques compréhensibles (chi en Go, axum en Rust, FastAPI en Python), c'est un **sentiment familier**. Pour ceux à qui ça n'importe pas — prenez ce qui est plus grand et plus mature.
-
----
-
-## Qu'en est-il de la performance ?
-
-Honnêtement : **Mado n'est pas le plus rapide**. Le top-3 sur js-framework-benchmark sont Solid, Inferno et Svelte. Mado est plus proche de Lit / Preact en termes de caractéristiques.
-
-Ce que Mado fait pour la performance par défaut :
-- **`computed` lazy** (dirty-flag, pas eager) ;
-- **planificateur de microtâche par batch** pour `signal.set` ;
-- **réconciliation par clé** dans `each()` avec réutilisation réelle du DOM ;
-- **rendu synchrone** pour les pages en cache dans le router ;
-- **hover-prefetch** pour les chunks lazy ;
-- **View Transitions API** pour des transitions fluides ;
-- **`adoptedStyleSheets` partagés** pour le CSS ;
-- **hints `modulepreload`** sur le serveur de développement.
-
-C'est suffisant pour la plupart des applications. Si vous construisez Excel dans le navigateur ou une visualisation WebGL à 60fps — ce n'est pas ici (c'est Solid ou du JS natif).
-
----
-
-## Résumé
-
-Mado est un outil **ciblé** avec un positionnement honnête. Il est le plus fort quand :
-
-1. Vous voulez **posséder** le code et le lire en entier.
-2. La **simplicité d'infrastructure** est critique (pas de Vite/Webpack/Babel).
-3. Vous avez besoin de **batteries dans une boîte** (router + données + forms + SEO).
-4. Vous n'êtes pas junior et n'avez pas peur des Web Components.
-
-Si même un seul point ne s'applique pas à vous — prenez une alternative du tableau ci-dessus. Ne vous battez pas avec un outil qui ne convient pas.
-
-— L'auteur de Mado, ex-développeur React passé au backend qui maintenant colle des frontends dans ses temps libres.