@nodefony/framework 10.0.0-alpha.8 → 10.0.0-beta.1

package/docs/routing.md

@@ -55,7 +55,7 @@ Trois faits à retenir avant tout le reste :
    (`HttpError("Not Found", 404)`, `http-kernel.ts:798`).
 3. **Le chemin est vérifié avant la méthode, et le domaine entre les deux** — c'est ce qui produit un
    `403` plutôt qu'un `405` bavard quand la route appartient à un autre vhost (`Route.match()`,
-   `Route.ts:212`).
+   `Route.ts:327`).
 
 ## 📖 Lexique
 
@@ -101,20 +101,20 @@ contrôleur.
 
 **La performance ne change pas la sémantique.** Sous le capot, la table est partitionnée : les chemins
 **littéraux** (aucun `{var}`, aucun métacaractère) vivent dans une `Map path → candidates` en lookup
-O(1) ; les chemins **dynamiques** restent un scan regex (`buildRouteIndex()`, `router.ts:92`). À la
+O(1) ; les chemins **dynamiques** restent un scan regex (`buildRouteIndex()`, `router.ts:130`). À la
 résolution, les deux flux sont fusionnés **par position d'insertion** — la séquence de candidats est
 exactement celle du scan linéaire complet, moins les littérales d'un autre chemin, qui ne pouvaient de
-toute façon pas correspondre (`Router.resolve()`, `router.ts:221`). C'est cette équivalence que fige le
+toute façon pas correspondre (`Router.resolve()`, `router.ts:237`). C'est cette équivalence que fige le
 banc de non-régression : un refacto du routeur doit le repasser à l'identique.
 
 **Une seule table pour HTTP et WebSocket.** Il n'y a pas de « routeur WS » séparé : une action WS est
 une route dont les méthodes déclarées contiennent `WEBSOCKET` (`Route.matchRequirements()`,
-`Route.ts:649`). C'est le différenciateur du framework — le même contrôleur, le même contexte, les
+`Route.ts:720`). C'est le différenciateur du framework — le même contrôleur, le même contexte, les
 mêmes décorateurs.
 
 **Le routeur passe avant les fichiers statiques.** Une requête qui correspond à une route ne paie
 jamais le `stat` du serveur de fichiers : le repli statique n'est tenté que si la résolution a échoué
-(`serverStatic.handle()`, `http-kernel.ts:725`).
+(`serverStatic.handle()`, `http-kernel.ts:743`).
 
 > [!NOTE]
 > **Le routage n'a aucune option de configuration.** Le schéma Zod du module n'expose qu'un sac
@@ -167,10 +167,10 @@ class CatalogController extends Controller {
   }
 
   // `@route` = la forme explicite : nom choisi + contraintes libres.
-  // HEAD n'est PAS déduit de GET — il se déclare (cf Pièges).
+  // HEAD est servi d'office par toute route GET (RFC 9110 §9.1) : inutile de le déclarer.
   @route("route-catalog-files", {
     path: "/files/*",
-    requirements: { methods: ["GET", "HEAD"] },
+    requirements: { methods: ["GET"] },
   })
   async files(rest: string) {
     return this.renderJson({ rest });
@@ -263,15 +263,15 @@ que chaque forme **produit dans la table**.
 | `@route(nom, options)`                    | **le tien** (stable, réutilisable) | `requirements.methods` (libre)   | WebSocket, multi-méthodes, contraintes fines |
 
 - Les décorateurs de méthode HTTP délèguent tous à `@route` avec un nom auto `Classe::methode`, et
-  posent `requirements: { methods }` (`httpMethodDecorator()`, `routerDecorators.ts:340`).
+  posent `requirements: { methods }` (`httpMethodDecorator()`, `routerDecorators.ts:489`).
 - `@All` n'émet **aucun** requirement de méthode : la route sert alors GET, POST, DELETE… et ne peut
-  donc jamais produire un 405 sur la méthode (`All()`, `routerDecorators.ts:374`).
+  donc jamais produire un 405 sur la méthode (`All()`, `routerDecorators.ts:548`).
 - `@route` est la forme complète : elle seule permet `protocol` (sous-protocole WS), un nom lisible, et
   des requirements par variable.
 
 **Comment une déclaration devient une route.** Les décorateurs de méthode **accumulent** des métadonnées
 sur le constructeur (clé `routes:definitions`, `routerDecorators.ts:16`) ; c'est `@controller(prefix)`
-qui les lit et appelle `Router.createRoute()` pour chacune (`controller()`, `routerDecorators.ts:129`).
+qui les lit et appelle `Router.createRoute()` pour chacune (`controller()`, `routerDecorators.ts:189`).
 
 > [!WARNING]
 > **`@route`/`@Get` doivent être SOUS `@controller`** — les décorateurs de classe s'évaluent après ceux
@@ -281,7 +281,7 @@ qui les lit et appelle `Router.createRoute()` pour chacune (`controller()`, `rou
 ## Motifs de chemin et paramètres
 
 Le chemin déclaré est compilé **une fois**, à la création de la route, en une expression régulière
-ancrée et **insensible à la casse** (`Route.compile()`, `Route.ts:395`). La grammaire tient en cinq
+ancrée et **insensible à la casse** (`Route.compile()`, `Route.ts:432`). La grammaire tient en cinq
 briques (`REG_ROUTE`, `Route.ts:17`) :
 
 | Écriture           | Motif compilé | Capture           | Exemple                                               |
@@ -295,7 +295,7 @@ briques (`REG_ROUTE`, `Route.ts:17`) :
 Et trois comportements qui surprennent la première fois :
 
 - **Le slash final est retiré avant le matching** — `/books/` et `/books` désignent la même route
-  (`Route.cleanPathname()`, `Route.ts:274`). Corollaire : `/files/*` ne matche pas `/files/`, qui a été
+  (`Route.cleanPathname()`, `Route.ts:303`). Corollaire : `/files/*` ne matche pas `/files/`, qui a été
   normalisé en `/files`.
 - **Les valeurs sont URL-décodées** — `%C3%A9t%C3%A9` arrive dans l'action comme `été`
   (`decode()`, `Route.ts:79`).
@@ -307,7 +307,7 @@ Et trois comportements qui surprennent la première fois :
 C'est le mécanisme le moins évident, et le plus utile. Déclarer un `defaults` pour une variable change
 le motif compilé : le segment devient facultatif (`[^/]*`) **et son slash aussi** (`/?`), puis la valeur
 par défaut est réinjectée quand la capture est vide (`checkDefaultParameters()`, `Route.ts:99` ·
-`Route.hydrateDefaultParameters()`, `Route.ts:469`).
+`Route.hydrateDefaultParameters()`, `Route.ts:529`).
 
 ```ts ignore
 @route("route-page", { path: "/page/{slug}", defaults: { slug: "home" } })
@@ -327,7 +327,7 @@ async page(slug: string) {
 Les captures sont passées **positionnellement**, dans l'ordre des variables du chemin — c'est pourquoi
 la signature `async method6(metier: string, format: string)` suit l'ordre de `/{metier}/{format}`. Un
 wildcard est exposé sous les clés `wildcard` et `*`. Le `Resolver` en fabrique aussi un instantané
-nom → valeur par requête (`Resolver.getMatchedParams()`, `Resolver.ts:170`), lu par le contexte pour
+nom → valeur par requête (`Resolver.getMatchedParams()`, `Resolver.ts:200`), lu par le contexte pour
 les métadonnées et par les décorateurs `@Param`.
 
 > [!IMPORTANT]
@@ -360,7 +360,7 @@ le suit — un `@All("*")` déclaré tôt masque le reste du contrôleur.
 > [!TIP]
 > Une exception utile : dans un contrôleur, une route dont le chemin vaut **exactement** `"*"` est
 > repoussée **en dernier** au moment du montage — la capture-tout d'un contrôleur ne masque donc jamais
-> ses propres routes, quel que soit l'ordre d'écriture (`hasMagic`, `routerDecorators.ts:237`). Ça ne
+> ses propres routes, quel que soit l'ordre d'écriture (`hasMagic`, `routerDecorators.ts:253`). Ça ne
 > vaut **que** pour `"*"` seul : `/files/*` reste ordonné comme les autres.
 
 ### Situation 2 — le même chemin, deux méthodes
@@ -376,9 +376,15 @@ qui accepte la méthode (`Router.resolve()`, `router.ts:230`).
 
 Si **aucune** route n'accepte la méthode, la **passe 2** entre en scène : elle reparcourt la table,
 collecte toutes les méthodes servies par ce chemin **sur ce vhost**, et lève un 405 dont l'en-tête
-`Allow` est l'**agrégat** (`collectSupportedMethods()`, `router.ts:31` ; en-tête posé sur la réponse,
-`router.ts:31`). C'est la conformité RFC 9110 §15.5.6 : `Allow` liste tout ce que la ressource
-accepte, pas seulement ce que la dernière route scannée acceptait.
+`Allow` est l'**agrégat** (`collectSupportedMethods()`, `router.ts:37`, qui lit le `methodsSet`
+compilé de chaque route — la MÊME source que le match). C'est la conformité RFC 9110 §15.5.6 :
+`Allow` liste tout ce que la ressource accepte, pas seulement ce que la dernière route scannée
+acceptait — `HEAD` compris dès qu'une route sert `GET`.
+
+**`HEAD` est implicite sur `GET`** (`Route.compileRequirements`, `Route.ts:485`) : RFC 9110 §9.1
+impose à tout serveur généraliste de servir `GET` et `HEAD`, et `HEAD` rend la réponse de `GET`
+sans corps (§9.3.2) — le serveur Node écarte le corps lui-même, en HTTP/1.1 comme en HTTP/2.
+L'ajout se fait à la compilation de la route : aucun coût par requête.
 
 | Requête           | Réponse                                        |
 | ----------------- | ---------------------------------------------- |
@@ -389,11 +395,11 @@ accepte, pas seulement ce que la dernière route scannée acceptait.
 ### Situation 3 — une route réservée à un domaine
 
 Une route restreinte par `@Domain` est **invisible** aux requêtes des autres vhosts : elle lève un 403
-au lieu de participer au match (`Route.matchHostname()`, `Route.ts:605`). Le point de sécurité est
+au lieu de participer au match (`Route.matchHostname()`, `Route.ts:658`). Le point de sécurité est
 l'**ordre des vérifications** : le domaine est vérifié **avant** la méthode. Sans cela, une route d'un
 autre vhost pourrait répondre 405 en révélant SES méthodes — une fuite d'information cross-domaine
-(`Route.match()`, `Route.ts:298`). La passe 2 applique la même règle : les routes d'un autre vhost sont
-exclues du calcul de `Allow` (`isDomainAllowed`, `router.ts:270`).
+(`Route.match()`, `Route.ts:327`). La passe 2 applique la même règle : les routes d'un autre vhost sont
+exclues du calcul de `Allow` (`isDomainAllowed`, `router.ts:352`).
 
 Si une autre route du même chemin sert **tous** les vhosts, le scan continue jusqu'à elle : le 403
 n'interrompt pas la recherche, il ne conclut que s'il ne reste aucune candidate.
@@ -418,7 +424,7 @@ Ce qui change par rapport au HTTP :
   inconnu ou un sous-protocole non conforme ferme la connexion **sans jamais l'ouvrir**.
 - **Le sous-protocole est un requirement de route.** Un `protocol` déclaré et non satisfait lève une
   erreur de code **1002** (Protocol Error, RFC 6455 §7.4) au lieu d'un statut HTTP
-  (`acceptedProtocol`, `Route.ts:722`).
+  (`acceptedProtocol`, `Route.ts:779`).
 - **Le 405 ne s'applique pas au WebSocket.** La passe 2 est réservée au HTTP : sur un contexte WS,
   l'exception d'origine est préservée (`Router.resolve()`, `router.ts:230`).
 - **Un `Resolver` par connexion, réutilisé à chaque frame.** Il est créé au handshake, puis chaque
@@ -438,9 +444,9 @@ que fait le data plane d'administration pour toutes ses lectures (`AdminBroker.m
   (`routing-nonregression.test.ts:164`).
 - **Une invocation WS d'une mutation doit dire quelle méthode logique elle vise.** Sur une socket,
   `context.method` vaut toujours `WEBSOCKET` : insuffisant pour distinguer un GET d'un POST sur le même
-  chemin. Le pont transporte donc une **méthode logique** (`methodOverride`, `Resolver.ts:116`) que la
+  chemin. Le pont transporte donc une **méthode logique** (`methodOverride`, `Resolver.ts:138`) que la
   route doit déclarer **en plus** du transport — une route `POST` qui n'annonce pas `WEBSOCKET` reste
-  **injoignable** par socket (zéro contournement, `Route.ts:678`).
+  **injoignable** par socket (zéro contournement, `Route.ts:722`).
 
 Le routage par **message** (invoquer un chemin porté par une frame, sans toucher l'URL de la connexion)
 passe par le même `resolve()`, avec un chemin fourni en argument — l'état partagé de la socket n'est
@@ -451,7 +457,7 @@ jamais muté (`Router.resolve()`, `router.ts:230`). Détails côté socket :
 
 `@Domain` restreint une méthode (ou tout un contrôleur) à un ou plusieurs noms d'hôte. Les motifs
 acceptent l'exact (`"marseille.fr"`) et le joker d'un label (`"*.cdn.example.com"`), compilés une fois
-au boot en expressions ancrées (`Route.compileHost()`, `Route.ts:468`).
+au boot en expressions ancrées (`Route.compileHost()`, `Route.ts:644`).
 
 ```ts ignore
 @controller("/")
@@ -463,14 +469,14 @@ class MarseilleController extends Controller {
 ```
 
 Précédence, du plus fort au plus faible : `@route({ host })` › `@Domain` sur la méthode › `@Domain` sur
-la classe (`controller()`, `routerDecorators.ts:89`). Une route sans domaine est servie sur **tous** les
+la classe (`controller()`, `routerDecorators.ts:189`). Une route sans domaine est servie sur **tous** les
 vhosts, et ne coûte rien au matching (`hostRegexp` absent → aucun test, `Route.matchHostname()`,
-`Route.ts:605`).
+`Route.ts:658`).
 
 > [!WARNING]
 > `@Domain` déclare quels vhosts une route **sert** ; il ne remplace pas la barrière d'entrée. Un
 > `Host` inconnu du serveur est rejeté en amont (421 Misdirected Request, `checkValidDomain()`,
-> `http-kernel.ts:1697`) via la liste `trustedHosts` de `@nodefony/http`.
+> `http-kernel.ts:1821`) via la liste `trustedHosts` de `@nodefony/http`.
 
 ## Préfixes — contrôleur, module, data plane
 
@@ -478,14 +484,14 @@ Trois niveaux de préfixe coexistent, et un seul est à ta main.
 
 1. **Le préfixe de contrôleur** — `@controller("/api/catalog")` est concaténé devant le chemin de
    chaque route de la classe, puis le chemin est normalisé : les `//` sont réduits et le slash final
-   retiré (`Route.setPattern()`, `Route.ts:551`). Un chemin vide (`@Get("")`) désigne donc le préfixe
+   retiré (`Route.setPattern()`, `Route.ts:619`). Un chemin vide (`@Get("")`) désigne donc le préfixe
    lui-même.
 2. **Le module propriétaire** — il n'ajoute **aucun** préfixe d'URL. `@controllers([…])` enregistre la
    classe au boot et propage le nom du module sur les routes déjà créées, pour l'introspection et les
-   logs (`Router.setController()`, `router.ts:417`). Un module tiers et ton app peuvent porter deux
+   logs (`Router.setController()`, `router.ts:462`). Un module tiers et ton app peuvent porter deux
    contrôleurs homonymes sans collision : la clé du registre est `module:Classe` (`router.ts:164`).
 3. **Le data plane d'administration** — réservé, non négociable : `/nodefony/<namespace>/api/<endpoint>`
-   (`AdminBroker.resolvePath()`, `AdminBroker.ts:91`). Trois segments minimum, pour ne jamais entrer en
+   (`AdminBroker.resolvePath()`, `AdminBroker.ts:99`). Trois segments minimum, pour ne jamais entrer en
    collision avec les routes de l'application ni avec la SPA de Studio.
 
 > [!TIP]
@@ -502,10 +508,10 @@ d'une route — il survit à un changement de chemin.
 | Besoin                                   | Comment                                                                   |
 | ---------------------------------------- | ------------------------------------------------------------------------- |
 | Retrouver une route par son nom          | `router.getRoutes("ma-route")` → l'objet `Route` (`router.ts:326`)        |
-| Lister toutes les routes                 | `router.getRoutes("")` → la table complète (`router.ts:387`)              |
-| Savoir quelles routes couvrent un chemin | `router.matchRoutes("/api/x")` → les résultats de regex (`router.ts:376`) |
-| Appeler une autre action, en interne     | `this.forward("module:Controller:action")` (`Controller.ts:445`)          |
-| Retirer une route                        | `router.removeRoutes("ma-route")` (`router.ts:335`)                       |
+| Lister toutes les routes                 | `router.getRoutes("")` → la table complète (`router.ts:415`)              |
+| Savoir quelles routes couvrent un chemin | `router.matchRoutes("/api/x")` → les résultats de regex (`router.ts:404`) |
+| Appeler une autre action, en interne     | `this.forward("module:Controller:action")` (`Controller.ts:670`)          |
+| Retirer une route                        | `router.removeRoutes("ma-route")` (`router.ts:424`)                       |
 
 **Il n'existe pas de générateur d'URL inverse côté serveur** (pas de `path("ma-route", {id})` à la
 Symfony). Le chemin déclaré est lisible sur l'objet `Route` (`route.path`), et la substitution des
@@ -515,7 +521,7 @@ chemin ; pour un appel interne, utilise `forward()`.
 
 **`forward()` n'est pas une redirection** : il résout `module:Controller:action` et exécute l'action
 dans le **même** contexte de requête, sans repasser par le réseau (`Resolver.parsePathernController()`,
-`Resolver.ts:185`). Une vraie redirection HTTP passe par `this.redirect(url, 302)` ou `@Redirect`.
+`Resolver.ts:228`). Une vraie redirection HTTP passe par `this.redirect(url, 302)` ou `@Redirect`.
 
 ## 🧰 API publique
 
@@ -529,9 +535,9 @@ modules qui montent des routes dynamiquement). Signatures complètes : `.ai/symb
 | `router.resolve(context)`                  | Le cœur : rend un `Resolver` (`resolve === true` si trouvé).            |
 | `router.getRoutes(nom)` · `removeRoutes()` | Introspection et démontage.                                             |
 | `Route#path` · `#variables` · `#pattern`   | Ce que la route déclare, après compilation.                             |
-| `Route#toObject()` · `#toLogLine()`        | Sérialisation pour l'API admin · ligne de log lisible (`Route.ts:525`). |
+| `Route#toObject()` · `#toLogLine()`        | Sérialisation pour l'API admin · ligne de log lisible (`Route.ts:571`). |
 | `Resolver#route` · `#variables`            | Ce que la requête courante a matché.                                    |
-| `Resolver#getMatchedParams()`              | Les variables en `nom → valeur` (`Resolver.ts:170`).                    |
+| `Resolver#getMatchedParams()`              | Les variables en `nom → valeur` (`Resolver.ts:200`).                    |
 
 > [!CAUTION]
 > **La table de routes est un état de processus, pas d'instance** : `Router.routes` est une liste
@@ -546,31 +552,32 @@ alloué par requête.
 
 - **Compilation unique au montage** : motif d'URL, motifs de domaine, `Set` de méthodes en majuscules,
   chaîne `Allow`, et regex des requirements par variable sont figés à la création de la route
-  (`Route.compileRequirements()`, `Route.ts:324`). Le matching ne fait plus que des lookups.
+  (`Route.compileRequirements()`, `Route.ts:476`). Le matching ne fait plus que des lookups.
 - **Un seul calcul de chemin par requête** : le `pathname` normalisé est calculé une fois puis passé à
   chaque route scannée — sinon le getter `URL.pathname`, la regex de normalisation et l'allocation de
-  chaîne seraient refaits pour **chaque** route de la table (`Route.cleanPathname()`, `Route.ts:204`).
+  chaîne seraient refaits pour **chaque** route de la table (`Route.cleanPathname()`, `Route.ts:303`).
 - **Lookup O(1) pour les chemins littéraux**, scan pour les seuls chemins à motif — sans changer la
   séquence de candidats (`buildRouteIndex()`, `router.ts:130`). L'index est invalidé par toute mutation
   de la table, avec un garde-fou sur une photo `longueur/première/dernière` qui rattrape même les
-  mutations directes de la liste (`routeIndex`, `router.ts:201`).
+  mutations directes de la liste (`routeIndex`, `router.ts:127`).
 - **Zéro journalisation en production** : le log « route trouvée » est promu au niveau NOTICE hors
   production seulement, et le test est résolu une fois puis mémoïsé — en production, aucune chaîne
-  n'est même construite (`routeNoticePromoted`, `router.ts:299`).
+  n'est même construite (`routeNoticePromoted`, `router.ts:306`).
 - **Métadonnées d'action mémoïsées par route** au premier passage (`@HttpCode`, `@Header`, `@Redirect`,
   paramètres, intention de session) : plus aucune lecture `Reflect` par requête
-  (`resolveActionMeta`, `Resolver.ts:142`).
+  (`resolveActionMeta`, `Resolver.ts:491`).
 
 ## 📜 Normes appliquées
 
 | Sujet                                    | Norme             | Où le code s'y conforme                                         |
 | ---------------------------------------- | ----------------- | --------------------------------------------------------------- |
-| 405 + en-tête `Allow` agrégé             | RFC 9110 §15.5.6  | passe 2 (`collectSupportedMethods()`, `router.ts:31`)           |
-| Cible identifiée par l'URI, hôte compris | RFC 9110 §7.2     | hôte vérifié avant la méthode (`Route.match()`, `Route.ts:298`) |
-| 403 sur ressource d'un autre vhost       | RFC 9110 §15.5.4  | `Route.matchHostname()` (`Route.ts:605`)                        |
+| 405 + en-tête `Allow` agrégé             | RFC 9110 §15.5.6  | passe 2 (`collectSupportedMethods()`, `router.ts:37`)           |
+| `HEAD` servi par toute route `GET`       | RFC 9110 §9.1     | `Route.compileRequirements` (`Route.ts:485`)                    |
+| Cible identifiée par l'URI, hôte compris | RFC 9110 §7.2     | hôte vérifié avant la méthode (`Route.match()`, `Route.ts:327`) |
+| 403 sur ressource d'un autre vhost       | RFC 9110 §15.5.4  | `Route.matchHostname()` (`Route.ts:658`)                        |
 | 404 quand rien ne correspond             | RFC 9110 §15.5.5  | après repli statique (`http-kernel.ts:688`)                     |
-| 421 sur `Host` non servi                 | RFC 9110 §15.5.20 | `checkValidDomain()` (`http-kernel.ts:1740`)                    |
-| Erreur de sous-protocole WS = 1002       | RFC 6455 §7.4     | `Route.matchRequirements()` (`Route.ts:649`)                    |
+| 421 sur `Host` non servi                 | RFC 9110 §15.5.20 | `checkValidDomain()` (`http-kernel.ts:1821`)                    |
+| Erreur de sous-protocole WS = 1002       | RFC 6455 §7.4     | `Route.matchRequirements()` (`Route.ts:720`)                    |
 | Décodage pourcent des segments           | RFC 3986 §2.1     | `decode()` (`Route.ts:79`)                                      |
 
 ## 📡 Observabilité — Studio
@@ -581,14 +588,14 @@ La table de routes est introspectable en ligne, sans lire le code :
   méthodes, contrôleur (`FrameworkAdminApi.ts:123`). Variante paginée/triée/filtrée côté serveur :
   `routes/page`.
 - **`GET /nodefony/framework/api/info`** — résumé : nombre de routes, méthodes servies, modules
-  propriétaires (`FrameworkAdminApi.ts:183`).
+  propriétaires (`FrameworkAdminApi.ts:356`).
 - **Écran Routes** de Studio (`/nodefony/routes`) — la même table, filtrable.
 - **Playground** (`/nodefony/playground`, développement uniquement) — un formulaire par action, généré depuis la table :
   transports (dont le duplex), paramètres décorés, gardes de sécurité. Il **exécute** de vraies actions,
   donc il n'est monté qu'en développement (`PlaygroundAdminApi.ts`).
 
 Au boot, avec le debug actif, chaque route est aussi journalisée en une ligne
-`[MÉTHODES] chemin → @module/Controller.action` (`Route.toLogLine()`, `Route.ts:402`).
+`[MÉTHODES] chemin → @module/Controller.action` (`Route.toLogLine()`, `Route.ts:571`).
 
 ## ⚠️ Pièges (symptôme → cause → correction)
 
@@ -598,7 +605,6 @@ Au boot, avec le debug actif, chaque route est aussi journalisée en une ligne
 | 404 sur toutes les routes d'un contrôleur | `@controller` évalué avant les `@route`/`@Get` de la classe | Placer `@controller` **au-dessus** de la classe, décorateurs de méthode dans la classe |
 | 404 sur une route pourtant écrite | Le fichier du contrôleur n'est jamais importé — les routes naissent à l'import | Le déclarer dans `@controllers([…])` du module |
 | `405` alors que la méthode « est déclarée » | `method: "GET"` dans `@route` n'est **pas** filtrant | Utiliser `requirements: { methods: ["GET"] }` ou `@Get` |
-| `405` sur une requête `HEAD` d'une route `@Get` | `HEAD` n'est pas déduit de `GET` : c'est une méthode distincte | Déclarer `requirements: { methods: ["GET", "HEAD"] }` |
 | Une route paramétrée avale un chemin littéral | Premier match dans l'ordre de déclaration, aucune spécificité | Déclarer le littéral **avant** le paramétré |
 | `/files/*` ne répond pas sur `/files` | Le slash final est retiré avant le matching ; le motif exige `/files/` | Déclarer une seconde route pour le chemin nu |
 | `{id}` ne capture pas `a/b` | Une variable vaut `[^/]+` — un seul segment, par construction | Utiliser un wildcard `*` si le `/` doit être capturé |

package/docs/templates.md

@@ -44,7 +44,7 @@ flowchart LR
 Deux idées à retenir :
 
 1. **Le contrôleur lit le fichier, le moteur ne fait que rendre une chaîne.** `renderView()` résout le
-   chemin, lit l'octet, puis passe la **source** à Eta (`Controller.renderView()`, `Controller.ts:410`).
+   chemin, lit l'octet, puis passe la **source** à Eta (`Controller.renderView()`, `Controller.ts:524`).
    Il n'y a **pas** de dossier `views/` magique connu du moteur.
 2. **L'échappement est automatique.** Une donnée interpolée par `<%= %>` est neutralisée (`<` devient
    `&lt;`) avant d'entrer dans le HTML — c'est la protection XSS, active par défaut
@@ -104,7 +104,7 @@ Le branchement est **délibérément minimal** :
 
 > [!NOTE]
 > Le rendu **d'erreurs** ne passe **pas** par les templates : une exception devient un corps **JSON
-> structuré** (`ErrorRenderer.renderHttp()`, `error-renderer.ts:348`), jamais une page Eta. Le moteur
+> structuré** (`ErrorRenderer.renderHttp()`, `error-renderer.ts:473`), jamais une page Eta. Le moteur
 > de vues ne sert que le HTML **que tu rends explicitement**.
 
 ## 🚀 Démarrage rapide
@@ -187,7 +187,7 @@ curl -s 'http://localhost:5151/hello/%3Cb%3Ex%3C%2Fb%3E'
 > [!TIP]
 > Tu n'as écrit **aucun** appel d'envoi (`send`, `res.end`). `renderView()` produit le corps **et**
 > l'envoie. Pour piloter l'envoi toi-même, retourne plutôt une chaîne via `render()`
-> (`Controller.render()`, `Controller.ts:377`).
+> (`Controller.render()`, `Controller.ts:485`).
 
 ## 🏗️ Architecture interne — le parcours d'un `renderView()`
 
@@ -218,15 +218,15 @@ sequenceDiagram
 
 | #   | Étape                                        | Où                                                            |
 | --- | -------------------------------------------- | ------------------------------------------------------------- |
-| 1   | Résolution + lecture async du fichier        | `FileClass` dans `renderView()` (`Controller.ts:410`)         |
-| 2   | Ouverture de la phase mesurée `render`       | `phaseStart("render")` (`Controller.ts:377`)                  |
-| 3   | Injection des aides frontend dans les locals | `withFrontendLocals()` (`Controller.ts:448`)                  |
+| 1   | Résolution + lecture async du fichier        | `FileClass` dans `renderView()` (`Controller.ts:524`)         |
+| 2   | Ouverture de la phase mesurée `render`       | `phaseStart("render")` (`Controller.ts:485`)                  |
+| 3   | Injection des aides frontend dans les locals | `withFrontendLocals()` (`Controller.ts:562`)                  |
 | 4   | Rendu de la source par le moteur             | `Eta.render()` → `renderStringAsync` (`Eta.ts:51`)            |
-| 5   | `Content-Type: text/html` puis envoi         | `setContextHtml()` + `renderResponse()` (`Controller.ts:331`) |
+| 5   | `Content-Type: text/html` puis envoi         | `setContextHtml()` + `renderResponse()` (`Controller.ts:503`) |
 
 Le point notable de l'étape 3 : `withFrontendLocals()` ajoute automatiquement `frontendTags`,
 `frontendDocument` et `asset` aux locals **si** le service `frontend` est présent — et **tes** valeurs
-priment (spread `param` en dernier, `Controller.ts:345`). Si le module frontend n'est pas chargé, la
+priment (spread `param` en dernier, `Controller.ts:526`). Si le module frontend n'est pas chargé, la
 fonction retourne les locals inchangés : zéro couplage dur.
 
 ## 🔐 Sécurité — échappement HTML et XSS
@@ -268,9 +268,9 @@ scaffold). Les deux sont **asynchrones** (I/O non bloquante).
 
 | Helper                              | Pour…                                                   | Ancre               |
 | ----------------------------------- | ------------------------------------------------------- | ------------------- |
-| `renderView(path, locals, status?)` | Rendre une vue `.eta` (lit le fichier + aides frontend) | `Controller.ts:308` |
-| `render(data, encoding?, status?)`  | Envoyer un corps quelconque (ex. HTML déjà prêt)        | `Controller.ts:377` |
-| `renderJson(obj, status?)`          | Réponse JSON explicite (pas un template)                | `Controller.ts:392` |
+| `renderView(path, locals, status?)` | Rendre une vue `.eta` (lit le fichier + aides frontend) | `Controller.ts:524` |
+| `render(data, encoding?, status?)`  | Envoyer un corps quelconque (ex. HTML déjà prêt)        | `Controller.ts:485` |
+| `renderJson(obj, status?)`          | Réponse JSON explicite (pas un template)                | `Controller.ts:602` |
 
 Les signatures exactes vivent dans le graphe symbolique `.ai/symbols.json` — jamais recopiées ici.
 
@@ -285,7 +285,7 @@ Le moteur est configuré **en dur**, pas via un bloc Zod exposé à `use()`. Tro
 | `cache`      | `true` en prod, `false` sinon | compile-once des templates en production ; recompile à chaud en dev | `Template.ts:20` |
 
 Le cache n'est **pas** un booléen figé : `Template` le dérive de l'environnement du kernel
-(`environment === "prod"`, `Template.ts:20`) puis `Eta` l'applique au moteur (`Eta.ts:41`). En
+(`environment === "prod"`, `Template.ts:20`) puis `Eta` l'applique au moteur (`Eta.ts:34`). En
 développement, un template modifié est donc pris en compte sans redémarrer.
 
 ## 🔌 HTTP et WebSocket — le même rendu
@@ -309,7 +309,7 @@ c'est le différenciateur Nodefony : une classe, deux transports, le même moteu
 | Domaine            | Norme / référence       | Comment le code s'y conforme                                          |
 | ------------------ | ----------------------- | --------------------------------------------------------------------- |
 | Neutralisation XSS | OWASP — Output Encoding | échappement HTML par défaut (`autoEscape`, `Eta.ts:16`)               |
-| Type de média HTML | `text/html`             | posé par `setContextHtml()` dans `renderView()` (`Controller.ts:331`) |
+| Type de média HTML | `text/html`             | posé par `setContextHtml()` dans `renderView()` (`Controller.ts:524`) |
 | I/O non bloquante  | Node.js async fs        | lecture async du fichier (`readFile`, `Eta.ts:71`)                    |
 
 ## ⚡ Performance et mémoire
@@ -318,13 +318,13 @@ Le rendu de vue est la partie **réellement coûteuse** d'une réponse (lecture
 template), et le framework l'isole pour ça :
 
 - **Phase dédiée** : `renderView()` chronomètre le rendu sous la phase `render`
-  (`phaseStart("render")`, `Controller.ts:410`) — distincte de `action` et de `send`. On voit ainsi si
+  (`phaseStart("render")`, `Controller.ts:524`) — distincte de `action` et de `send`. On voit ainsi si
   le temps part dans le moteur ou dans l'écriture réseau.
 - **Cache en prod** : les templates sont compilés une fois (`cache` vrai en production,
   `Template.ts:20`) ; le coût de parsing n'est payé qu'au premier rendu.
 - **Lecture non bloquante** : le fichier est lu en async (`FileClass.readAsync()` côté `renderView`,
-  `readFile` côté `renderFile`, `Eta.ts:71`) — l'event loop n'est jamais gelé par un `readFileSync`.
-- **Aides frontend paresseuses** : `withFrontendLocals()` (`Controller.ts:448`) ne construit les
+  `readFile` côté `renderFile`, `Eta.ts:66`) — l'event loop n'est jamais gelé par un `readFileSync`.
+- **Aides frontend paresseuses** : `withFrontendLocals()` (`Controller.ts:562`) ne construit les
   fonctions `frontendTags`/`asset` que si le service `frontend` répond — sinon il rend les locals tels
   quels, zéro allocation superflue.
 
@@ -344,7 +344,7 @@ template), et le framework l'isole pour ça :
 | `<%= it.name %>` requis alors qu'on attend `<%= name %>` | `useWith` mal compris — Nodefony l'active (`Eta.ts:17`), les locals sont nus       | Écrire `<%= name %>` directement                                           |
 | Modif de template ignorée en prod                        | `cache: true` en production (`Template.ts:20`)                                     | Redémarrer le pod ; en dev le cache est off, recompile à chaud             |
 | La réponse d'erreur n'est pas ma vue Eta                 | Les erreurs rendent du JSON, pas un template (`error-renderer.ts:109`)             | Pour une page d'erreur HTML, rendre explicitement une vue dans un handler  |
-| `renderView()` rejette et logge une ERROR                | Fichier introuvable ou template invalide (le `catch` re-lève, `Controller.ts:410`) | Vérifier le chemin résolu (`resolve(module.path, …)`)                      |
+| `renderView()` rejette et logge une ERROR                | Fichier introuvable ou template invalide (le `catch` re-lève, `Controller.ts:524`) | Vérifier le chemin résolu (`resolve(module.path, …)`)                      |
 
 ## 🧪 Tests et couverture
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/framework",
-  "version": "10.0.0-alpha.8",
+  "version": "10.0.0-beta.1",
   "description": "Le modèle de programmation Nodefony : routeur, contrôleurs, décorateurs et vues — HTTP et WebSocket dans le même contexte",
   "author": "Christophe CAMENSULI <ccamensuli@gmail.com>",
   "main": "./dist/index.js",
@@ -8,15 +8,16 @@
   "types": "./dist/types/index.d.ts",
   "exports": {
     ".": {
+      "nodefony-source": "./index.ts",
       "types": "./dist/types/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     }
   },
   "scripts": {
-    "build": "rimraf dist && rolldown -c rolldown.config.ts && tsgo -p tsconfig.declarations.json",
+    "build": "rolldown -c rolldown.config.ts && tsgo -p tsconfig.declarations.json",
     "dev": "rolldown -c rolldown.config.ts --watch",
-    "clean": "rimraf dist",
+    "clean": "node --eval \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "test": "vitest run",
     "test:integration": "vitest run --config vitest.integration.config.ts",
     "coverage": "vitest run --coverage",
@@ -51,22 +52,21 @@
     "tslib": "2.8.1"
   },
   "devDependencies": {
-    "@nodefony/http": "^10.0.0-alpha.8",
+    "@nodefony/http": "^10.0.0-beta.1",
     "@types/chai": "5.2.3",
-    "@types/node": "26.6.2",
-    "@vitest/coverage-v8": "5.0.1",
+    "@types/node": "26.6.3",
+    "@vitest/coverage-v8": "5.0.2",
     "chai": "6.2.2",
-    "nodefony": "^10.0.0-alpha.8",
-    "rimraf": "6.1.3",
-    "tsx": "4.23.13",
-    "vitest": "5.0.1"
+    "nodefony": "^10.0.0-beta.1",
+    "tsx": "4.23.15",
+    "vitest": "5.0.2"
   },
   "license": "Apache-2.0",
   "readmeFilename": "README.md",
   "contributors": [],
   "peerDependencies": {
-    "@nodefony/http": "^10.0.0-alpha.8",
-    "nodefony": "^10.0.0-alpha.8",
+    "@nodefony/http": "^10.0.0-beta.1",
+    "nodefony": "^10.0.0-beta.1",
     "zod": "^4.6.5"
   },
   "files": [