@nodefony/devkit 10.0.0-alpha.1

package/skills/nodefony-browser/references/socket.md

@@ -0,0 +1,115 @@
+# Le socket, de bout en bout — `socket.mjs` et le protocole qu'il parle
+
+> **Maintenance** : vérité courante, jamais un journal. Éditer en place ; l'historique vit dans git.
+
+`socket.mjs` pilote un endpoint temps réel Nodefony COMPLET, depuis une vraie page : accueil,
+abonnement, action, latence, pont API, reconnexion. Le scénario s'exécute **dans la page** — la
+connexion porte donc les cookies de session et l'`Origin` réels. Un client « à côté » n'aurait ni
+l'un ni l'autre, et l'on croirait à un refus d'authentification là où il n'y a qu'un décor faux.
+
+```bash
+docker exec -e NF_BROWSER_API=/api/sante mon-app-browser node /app/see-screen/socket.mjs /chat/realtime
+```
+
+## Le protocole du fil — quatre formes de frame, à l'œil
+
+Tout ce qui passe est du **JSON-RPC 2.0**. La nature d'une frame se lit sur `method`, jamais sur
+`id` :
+
+| Forme             | Contenu                                           | Exemple                                                                          |
+| ----------------- | ------------------------------------------------- | -------------------------------------------------------------------------------- |
+| **Notification**  | `method` seul — aucune réponse, jamais            | `{"jsonrpc":"2.0","method":"subscribe","params":{"channel":"orders:new"}}`       |
+| **Requête**       | `method` + `id` — une réponse est due             | `{"jsonrpc":"2.0","id":1,"method":"api.request","params":{"path":"/api/sante"}}` |
+| **Réponse**       | `id` seul, `result` OU `error`                    | `{"jsonrpc":"2.0","id":1,"result":{…},"meta":{"requestId":"…"}}`                 |
+| **Push de canal** | notification dont le NOM du canal est la `method` | `{"jsonrpc":"2.0","method":"orders:new","params":{…}}`                           |
+
+Deux frames servent de repères :
+
+- **`realtime:welcome`** — la première notification poussée par le serveur : protocole, **canaux**
+  annoncés, **actions** exposées, **identité résolue au handshake**. C'est la carte du territoire ;
+  tant qu'elle n'est pas là, rien d'autre n'a de sens.
+- **`realtime:denied`** — le refus d'une notification. Une notification n'a pas de canal de
+  réponse : sans cette frame dédiée, un abonnement refusé serait indiscernable d'un canal
+  silencieux. La sonde l'écoute, et son verdict `REFUSÉ` vient de là.
+
+## Les étapes du scénario, et comment lire chaque verdict
+
+### `welcome`
+
+`receivedAfterMs`, canaux, méthodes, identité. **S'il ne vient jamais** (code de retour 65), les trois
+suspects, dans l'ordre : le chemin du endpoint est faux ; la page n'est pas authentifiée (donner
+`NF_BROWSER_USER` + `NF_BROWSER_LOGIN`) ; l'`Origin` de la page est refusé par le serveur. Le
+réseau qui « passe » n'innocente aucun des trois.
+
+### `subscription`
+
+S'abonne au canal de `NF_BROWSER_CHANNEL` — à défaut, au **premier canal annoncé par l'accueil** —
+puis écoute pendant `NF_BROWSER_SOCKET_WAIT` ms (défaut 4 000).
+
+- `OK` : au moins une poussée reçue (horodatées, tronquées, plafonnées).
+- `REFUSÉ` : le serveur a poussé `realtime:denied` pour ce canal — droits insuffisants ou plafond
+  de canaux. Le motif reste générique par conception : le serveur ne dit jamais QUEL droit manquait.
+- `SILENCIEUX` : **pas forcément une panne.** Un canal d'événements ne pousse que quand il se passe
+  quelque chose ; seul un canal d'état cadencé garantit du trafic dans la fenêtre. Avant de
+  conclure, provoquer un événement, allonger la fenêtre, ou choisir un canal cadencé.
+
+L'abonnement part **sans `id`** : c'est une notification. Envoyé avec un `id`, il serait classé
+requête, ne trouverait aucun handler, et récolterait un `-32601` — piège classique du protocole.
+
+### `latency`
+
+Mesure `NF_BROWSER_PINGS` allers-retours (défaut 5) sur une méthode **corrélée** : l'action de
+`NF_BROWSER_ACTION` si elle est donnée, sinon le pont API si `NF_BROWSER_API` l'est. Rend chaque
+mesure, les expirations, et la **médiane** — jamais la moyenne, qu'un seul aller-retour aberrant
+(ramasse-miettes, réveil de connexion) suffit à déplacer.
+
+- **Sans méthode corrélée, pas de latence** : la notification `ping` du battement de cœur est un
+  no-op serveur, aucun pong n'en revient. Verdict `NON MESURÉE`, jamais un zéro inventé.
+- **`RÉPOND EN ERREUR -32601`** : l'aller-retour est COMPLET — la latence mesure le fil, mais ne
+  valide pas l'action, qui n'existe pas sur cet endpoint. Lire `methods` dans l'accueil avant
+  d'appeler.
+
+### `api`
+
+Rejoue une route HTTP de l'application **sur le socket** (`api.request`, `params.path`). La réponse
+porte le `result` de la route et, souvent, un champ frère `meta` (identifiant de requête serveur) —
+la preuve que le plan de données passe bien par le WebSocket. Une erreur corrélée (`-32601` si le
+pont n'est pas exposé sur cet endpoint, erreur applicative sinon) est rendue telle quelle.
+
+### `reconnection`
+
+Ferme le socket (code 1000), en rouvre un, attend le nouvel accueil, et compare l'identité.
+`memeIdentite: true` prouve que l'identité est portée par la **session** (résolue au handshake,
+jamais dans les frames) : c'est la propriété qui compte pour une application qui reconnecte en
+production. Un `ÉCHEC` ici avec un premier accueil réussi désigne un serveur qui refuse la
+DEUXIÈME connexion — plafond de connexions, ou état serveur consommé par la première.
+
+## Variables d'environnement
+
+<!-- prettier-ignore -->
+| Variable | Rôle | Défaut |
+| --- | --- | --- |
+| `NF_BROWSER_SOCKET` | chemin du endpoint (ou 1er argument) — **requis**, rien n'est deviné | — |
+| `NF_BROWSER_PAGE` | page ouverte AVANT le socket — elle porte cookies et `Origin` | `/` |
+| `NF_BROWSER_CHANNEL` | canal à écouter | 1er canal annoncé |
+| `NF_BROWSER_ACTION` | action RPC à appeler (la latence la réutilise) | aucune |
+| `NF_BROWSER_ACTION_PARAMS` | paramètres JSON de l'action | aucun |
+| `NF_BROWSER_API` | chemin rejoué par le pont `api.request` | aucun |
+| `NF_BROWSER_SOCKET_WAIT` | fenêtre d'écoute du canal (ms) | 4000 |
+| `NF_BROWSER_PINGS` | nombre de mesures de latence | 5 |
+
+Plus les variables communes à toutes les sondes : `NF_BROWSER_BASE`, `NF_BROWSER_LOGIN`,
+`NF_BROWSER_USER`, `NF_BROWSER_PASSWORD`.
+
+## Quand cette sonde se trompe
+
+- **Elle parle le protocole à la main, sans la bibliothèque cliente.** C'est voulu — on observe le
+  FIL, pas une surcouche — mais ce que la bibliothèque ferait en plus (reconnexion automatique,
+  ré-abonnements, cadence adaptative) n'est PAS exercé ici : la « reconnexion » du scénario prouve
+  que le serveur accepte une nouvelle connexion authentifiée, pas que le client de l'application
+  reconnecte bien.
+- **La fenêtre d'écoute échantillonne.** Trois poussées en 4 s ne disent rien du débit de pointe ni
+  d'une fuite lente — c'est `watch.mjs`, plus longtemps, qui observe une dérive.
+- **Une latence médiane de quelques millisecondes est celle du conteneur vers l'hôte** — un
+  aller-retour local. Elle borne le coût du protocole, elle ne prédit pas la latence d'un
+  utilisateur réel derrière un réseau.

package/skills/nodefony-browser/references/sondes.md

@@ -0,0 +1,175 @@
+# Les sondes d'`inspect.mjs` — ce que chaque famille mesure, et quand elle se trompe
+
+> **Maintenance** : vérité courante, jamais un journal. Éditer en place ; l'historique vit dans git.
+
+`inspect.mjs` rend toujours un **socle**, et n'ajoute une **famille** de sondes que si on la
+demande (`NF_BROWSER_FAMILIES=a11y,perf`, ou `toutes`). Un nom de famille inconnu est **refusé**
+(code 64), jamais ignoré : une famille fautée en silence ferait croire qu'on a mesuré ce qu'on n'a
+pas mesuré.
+
+Chaque famille rend un **`verdict`** (`OK` / `ALERTE`) et des données bornées (comptes + 3
+exemples, jamais l'inventaire). Le champ `verdict` de fin de sortie agrège les familles actives —
+`OK` seulement si tout est OK. **Le code de retour reste 0** : le verdict est une donnée, pas une
+panne de la sonde. Les codes non nuls disent autre chose — 64 : usage (famille inconnue,
+identifiant sans chemin de connexion) ; 65 : le texte attendu n'est jamais apparu.
+
+## Le socle — toujours rendu
+
+<!-- prettier-ignore -->
+| Champ | Ce que c'est |
+| --- | --- |
+| `url` | La page RÉELLEMENT ouverte — à comparer à celle demandée (redirection de connexion, 404 SPA). |
+| `theme` / `lang` | `color-scheme` **calculé** (ce que le moteur applique) et attribut `lang` de la racine. |
+| `title` | `document.title`. |
+| `scripts` | Les scripts RÉELLEMENT servis — pour vérifier qu'on observe bien le bundle qu'on vient de bâtir. |
+| `probes` | Les sondes de style (voir ci-dessous). |
+| `violationsCSP` | Les violations de Content-Security-Policy vues PAR la page — le réseau montre l'absence, jamais la raison. |
+| `consoleErrors` | Les `console.error` émis pendant la mesure. |
+| `uncaughtErrors` | Les exceptions non capturées (`pageerror`) — elles ne passent pas toutes par la console. |
+| `capture` | Le PNG horodaté déposé dans le volume monté. |
+
+Les erreurs de console et les violations CSP **ne pèsent pas** dans le verdict global : un parcours
+de connexion produit des `401` légitimes, et les trancher ici les ferait passer pour des pannes.
+C'est au lecteur de juger — la sonde fournit, elle ne condamne pas ce qu'elle ne peut pas qualifier.
+
+## Les sondes de style (`probes`) — le contraste CALCULÉ
+
+Un sélecteur par élément (`NF_BROWSER_PROBES=libellé=sélecteur,…`) ; pour chacun : texte, couleur,
+fond effectif, rapport de contraste, police, verdict WCAG, taille rendue.
+
+- **Le fond effectif empile TOUTES les couches** jusqu'au premier ancêtre opaque, puis les compose.
+  Deux erreurs à ne pas refaire : lire `backgroundColor` sur l'élément rend `rgba(0,0,0,0)` et un
+  contraste faux ; s'arrêter à la première couche non transparente traite un voile à 13 % comme un
+  aplat plein, c'est-à-dire comme une couleur que personne ne voit.
+- **Les couleurs modernes ne comptent pas dans la même échelle.** `rgb(0, 87, 156)` est en 0–255,
+  `color(srgb 0 0.34 0.61 / 0.13)` en 0–1. Les lire avec la même expression régulière rend un bleu
+  presque noir — et fabrique des échecs qui noient les vrais.
+- **Le verdict WCAG dépend de la POLICE** : 3:1 suffit à un texte « large » (≥ 24 px, ou 18,66 px
+  en gras), 4,5:1 sinon. Un contraste rendu sans sa police ne conclut rien.
+- **Quand elle se trompe** : un fond en dégradé ou une image de fond ne sont pas vus — la sonde lit
+  des COULEURS, pas le pixel composité. Sur ces cas, juger sur la capture.
+
+> Ces sondes visent **un** élément qu'on désigne. Pour balayer la page entière sans rien désigner,
+> prendre la famille `axe` : elle voit ce à quoi on ne pensait pas.
+
+## `axe` — l'audit WCAG par un moteur dont c'est le métier
+
+Une centaine de règles jouées par `axe-core`, dont le contraste de **tout** le texte visible. C'est
+le moteur qu'embarque Lighthouse pour son volet accessibilité.
+
+<!-- prettier-ignore -->
+| Champ | Ce qu'il dit |
+| --- | --- |
+| `failures` | Les défauts AVÉRÉS, comptés par gravité (critique, sérieux, modéré, mineur) |
+| `worst` | Jusqu'à 8 règles, du plus grave au moins grave, avec **5 cibles** chacune et le `reason` calculé (contraste mesuré, rôle attendu) |
+| `otherTargets` | Ce qui dépasse les 5 — annoncé, jamais tronqué en silence |
+| `toReview` | Ce que le moteur REFUSE de trancher (fond en image…) — **pas** des défauts |
+| `passed` | Les règles passées, pour situer le reste |
+
+- **`toReview` n'est pas un manquement** et ne déclenche pas l'alerte. Le confondre ferait crier la
+  sonde sur des pages saines, et on cesserait de la lire.
+- **Cinq cibles par règle, pas une.** Une même règle couvre des défauts à des endroits différents,
+  qui ne se corrigent pas d'un seul geste ; n'en montrer qu'un fait croire le travail fini.
+- **N'écris jamais ce calcul toi-même.** Mesuré en conditions réelles : une sonde maison a rendu
+  **41 faux positifs** masquant **7 défauts réels**, dont celui qu'on cherchait — à cause de trois
+  cas particuliers (échelle des couleurs modernes, alpha non composé, emoji peints par une police en
+  couleurs) qu'on ne devine pas avant de les avoir vus.
+- **Quand elle est indisponible** : `axe-core` vit dans les dépendances du projet. En conteneur, il
+  faut le copier à part. La famille rend alors `verdict: "INDISPONIBLE"` et la commande à taper —
+  jamais un `OK` qui n'a rien mesuré.
+
+## `a11y` — ce qu'un lecteur d'écran ou un clavier rencontrent
+
+| Champ                    | Question à laquelle il répond                                                                                               |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
+| `lang`                   | La racine annonce-t-elle sa langue (sans elle, la synthèse vocale lit avec le mauvais accent) ?                             |
+| `headings`               | Un seul `h1` ? Des sauts de niveau (`h2→h4`) qui cassent la table des matières ?                                            |
+| `imagesWithoutAlt`       | Des images sans attribut `alt` — muettes pour un lecteur d'écran.                                                           |
+| `fieldsWithoutLabel`     | Des champs sans étiquette (label, `aria-label`, `aria-labelledby`, `title`).                                                |
+| `controlsWithoutName`    | Boutons et liens sans nom accessible — le bouton-icône muet, le cas réel.                                                   |
+| `targetsTooSmall`        | Cibles interactives < 24×24 px ; les liens DANS le texte sont exemptés, comme dans le critère.                              |
+| `positiveTabIndexValues` | Un `tabindex` positif impose un ordre de focus manuel qui diverge du DOM — l'anti-pattern du parcours clavier.              |
+| `visibleFocusables`      | L'ampleur du parcours clavier de la page.                                                                                   |
+| `tree`                   | L'arbre d'accessibilité (rôles + noms), tel que le calcule le navigateur — tronqué : il dit la STRUCTURE, pas l'inventaire. |
+
+**Quand elle se trompe** : le nom accessible est calculé de façon SIMPLIFIÉE (l'algorithme complet
+de la norme fait plus) — un composant qui pose son nom par un mécanisme exotique peut être compté
+« sans nom » à tort ; vérifier dans `tree`, qui lui applique le calcul complet du navigateur.
+Et une sonde automatique ne couvre qu'une fraction de l'accessibilité : elle attrape le mesurable
+(étiquettes, tailles, structure), jamais le sens — l'ordre logique d'un formulaire ou la pertinence
+d'un `alt` restent un jugement humain.
+
+## `rendu` — la page tient-elle dans son viewport, ses polices sont-elles là
+
+- `horizontalOverflow` : la page dépasse-t-elle la largeur de la fenêtre (le défilement
+  horizontal accidentel). C'est LUI qui porte le verdict.
+- `elementsOutsideViewport` : une **information**, pas un verdict — carrousels, tiroirs et textes
+  destinés aux lecteurs d'écran sortent du viewport légitimement.
+- `fonts` : ce que `document.fonts` a RÉELLEMENT chargé (statut par famille + graisse). Une
+  police en échec bascule le verdict — le texte s'affiche alors dans une police de repli, et toutes
+  les mesures de taille en héritent.
+
+**Quand elle se trompe** : la mesure attend `document.fonts.ready` au plus 2 s — une police servie
+très lentement peut encore être `loading` au moment de la lecture, sans être en échec.
+
+## `reseau` — requêtes, échecs, poids, temps
+
+Compte par type, octets réellement transférés, échecs (statut ≥ 400 et requêtes avortées),
+ressources **lourdes** (> `NF_BROWSER_SEUIL_LOURD`, défaut 512 000 octets) et **lentes**
+(> `NF_BROWSER_SEUIL_LENT`, défaut 1 000 ms). Verdict : ALERTE dès un échec ou une ressource lourde.
+
+**Quand elle se trompe** :
+
+- En développement, un serveur d'assets qui livre les modules UN PAR UN rend des centaines de
+  requêtes et des mégaoctets non minifiés : c'est le DÉCOR du mode dev, pas une régression. Les
+  seuils jugent une application SERVIE — comparer dev et prod n'a pas de sens.
+- Les tailles viennent du transfert réel quand le navigateur les donne, de `content-length` sinon ;
+  `unknownBytes` compte ce qui n'a pu être pesé — un total avec beaucoup d'inconnus minore.
+- La collecte s'arrête à la mesure : ce que la page télécharge APRÈS (interaction, différé) n'est
+  pas vu — c'est le travail de `watch.mjs`.
+
+## `perf` — temps de rendu et stabilité visuelle
+
+`ttfbMs`, `domContentLoadedMs`, `loadCompleteMs`, `fcpMs`, `lcpMs`, `cls`, `longTasks` —
+verdict sur les seuils « bons » des Web Vitals : LCP ≤ 2 500 ms, CLS ≤ 0,1.
+
+**Quand elle se trompe** :
+
+- **Une seule visite n'est pas une statistique.** Cache froid ou chaud, machine chargée, premier
+  boot d'un serveur de dev : la même page varie du simple au double. Un verdict ALERTE isolé se
+  vérifie en relançant ; une tendance se mesure en médiane de plusieurs passes.
+- LCP et CLS sont observés PENDANT le chargement (observateurs injectés avant la navigation) : la
+  sonde ne voit pas les décalages provoqués ENSUITE par une interaction.
+- Le CLS d'une application en mode développement (styles injectés à la volée) est structurellement
+  plus mauvais qu'en production.
+
+## `stockage` — cookies et Web Storage
+
+Attributs des cookies (`secure`, `httpOnly`, `sameSite`, expiration) et inventaire du
+`localStorage`/`sessionStorage` (clés, octets, les 5 plus grosses). **Jamais les valeurs** : un
+jeton de session imprimé dans une sortie de sonde finit dans un terminal, un log de CI, un rapport
+— il a fuité. Verdict : ALERTE si un cookie sans `secure` circule sur une origine https.
+
+**Quand elle se trompe** : les octets du Web Storage comptent en unités UTF-16 (×2) — c'est
+l'empreinte mémoire, pas la taille « à l'écran » ; et un cookie `httpOnly: false` n'est pas signalé
+comme alerte alors qu'il mérite un regard si sa valeur est sensible.
+
+## `responsive` — la même page à plusieurs largeurs
+
+Rejoue la mesure de débordement horizontal à chaque largeur de `NF_BROWSER_WIDTHS` (défaut
+`360,768,1280`). Par largeur : dépassement en pixels, nombre d'éléments débordants, 3 exemples.
+
+**Quand elle se trompe** : redimensionner un viewport n'est pas changer d'appareil — ni densité de
+pixels, ni tactile, ni `user-agent`. Une media query sur `pointer` ou `hover` ne réagira pas. Et la
+capture PNG est prise AVANT cette famille, à la largeur d'origine : les débordements constatés ici
+ne s'y voient pas.
+
+## Lire un verdict sans se faire piéger
+
+1. **`ALERTE` n'est pas « cassé »** — c'est « mérite un regard ». Le détail dit lequel.
+2. **`OK` n'est pas « accessible / rapide / propre »** — c'est « rien de mesurable à signaler dans
+   cette famille, sur cette page, à cet instant ».
+3. **Une mesure en mode développement juge le mode développement.** Poids, nombre de requêtes et
+   CLS ne se comparent qu'à décor égal.
+4. **Le verdict global agrège, il n'explique pas.** Toujours descendre dans la famille qui l'a fait
+   basculer.

package/skills/nodefony-browser/scripts/audit.mjs

@@ -0,0 +1,169 @@
+/**
+ * Audit Lighthouse d'une page, y compris DERRIÈRE une authentification.
+ *
+ * Pourquoi un script à part plutôt qu'une famille d'`inspect.mjs` : Lighthouse
+ * ne mesure pas une page ouverte, il en PILOTE le chargement — il recharge, vide
+ * le cache, bride le réseau et le processeur, et chronomètre. C'est l'inverse de
+ * la photographie d'un instant, et cela prend des dizaines de secondes.
+ *
+ * Comment l'authentification survit, alors que Lighthouse ouvre son propre
+ * onglet : le navigateur est lancé avec un PROFIL PERSISTANT et un port de
+ * débogage. On s'y connecte normalement — les témoins de session vivent alors
+ * dans le profil, pas dans un contexte isolé — puis Lighthouse se branche sur ce
+ * même navigateur et hérite du profil. Sans cela, il mesurerait l'écran de
+ * connexion en croyant tenir la page demandée.
+ *
+ * `@usage` node audit.mjs /tableau-de-bord
+ * `@env` NF_BROWSER_BASE origine à joindre (défaut constaté : local ou conteneur)
+ * `@env` NF_BROWSER_OUT dossier de sortie (le rapport complet y est déposé)
+ * `@env` NF_BROWSER_LOGIN chemin du formulaire de connexion — aucun défaut deviné
+ * `@env` NF_BROWSER_USER identifiant ; sans lui, aucune authentification n'est tentée
+ * `@env` NF_BROWSER_PASSWORD mot de passe associé
+ * `@env` NF_BROWSER_CATEGORIES catégories à jouer, séparées par des virgules (défaut : toutes celles que ce Lighthouse connaît)
+ * `@env` NF_BROWSER_FORMFACTOR `desktop` (défaut) ou `mobile` — un score de performance ne veut RIEN dire sans son appareil
+ * `@env` NF_BROWSER_SEUIL_AUDIT score en deçà duquel un audit est retenu, en pourcentage (défaut 90)
+ * `@requires` `lighthouse` et `playwright` installés (pairs optionnels)
+ * `@output` un résumé JSON sur stdout + le rapport COMPLET dans le dossier de sortie
+ * `@exit` 0 mesure rendue (le verdict est une DONNÉE) · 64 usage · 69 outil indisponible
+ */
+import { createServer } from "node:net";
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { BASE, LOGIN, PASSWORD, OUTPUT, USER } from "./lib/browser.mjs";
+import { summarizeLighthouse } from "./lib/probes.mjs";
+
+const PAGE = process.argv[2] ?? process.env.NF_BROWSER_PAGE ?? "/";
+const THRESHOLD = Number(process.env.NF_BROWSER_SEUIL_AUDIT ?? 90) / 100;
+const FORMFACTOR = (process.env.NF_BROWSER_FORMFACTOR ?? "desktop").trim();
+if (FORMFACTOR !== "desktop" && FORMFACTOR !== "mobile") {
+  console.error(
+    `NF_BROWSER_FORMFACTOR inconnu : « ${FORMFACTOR} ». Valeurs : desktop, mobile.`,
+  );
+  process.exit(64); // EX_USAGE
+}
+
+const tools = {};
+for (const name of ["lighthouse", "playwright"]) {
+  try {
+    tools[name] = await import(name);
+  } catch {
+    console.error(
+      `${name} est absent — cet audit ne peut pas avoir lieu sans lui.\n\n` +
+        `  npm i -D lighthouse playwright && npx playwright install chromium\n\n` +
+        "Les deux sont des pairs OPTIONNELS : seuls ceux qui auditent une page\n" +
+        "les installent, personne ne les paie sans les vouloir.",
+    );
+    process.exit(69); // EX_UNAVAILABLE
+  }
+}
+const lighthouse = tools.lighthouse.default;
+const { chromium } = tools.playwright;
+
+/**
+ * Un port libre, demandé au système plutôt que choisi au hasard.
+ *
+ * Un port fixe entrerait en collision avec un autre navigateur de débogage —
+ * et l'audit se brancherait alors sur le mauvais, ce qui ne produit pas une
+ * erreur mais une mesure d'une AUTRE page.
+ *
+ * @returns {Promise<number>} un port que rien n'écoute au moment du rendu.
+ */
+function freePort() {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.on("error", reject);
+    srv.listen(0, "127.0.0.1", () => {
+      const { port } = srv.address();
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+const port = await freePort();
+// Profil PERSISTANT : c'est lui qui porte la session entre notre connexion et
+// l'onglet que Lighthouse ouvrira. Jetable — il vit le temps de l'audit.
+const profile = mkdtempSync(path.join(tmpdir(), "nf-audit-"));
+const ctx = await chromium.launchPersistentContext(profile, {
+  channel: "chromium",
+  ignoreHTTPSErrors: true,
+  args: [`--remote-debugging-port=${port}`, "--no-sandbox"],
+});
+
+try {
+  const page = ctx.pages()[0] ?? (await ctx.newPage());
+  if (USER) {
+    if (!LOGIN) {
+      console.error(
+        "NF_BROWSER_USER est posé mais pas NF_BROWSER_LOGIN : donne le chemin de\n" +
+          "ton formulaire de connexion, sinon l'audit mesurerait l'écran de connexion.",
+      );
+      process.exit(64); // EX_USAGE
+    }
+    await page.goto(`${BASE}${LOGIN}`, { waitUntil: "domcontentloaded" });
+    const id = page.getByRole("textbox", {
+      name: /identifiant|utilisateur|username|e-?mail/iu,
+    });
+    const pw = page.getByRole("textbox", { name: /mot de passe|password/iu });
+    await id.or(pw).first().waitFor({ timeout: 15000 });
+    if ((await id.count()) > 0) {
+      await id.fill(USER);
+      await id.press("Enter");
+    }
+    await pw.fill(PASSWORD, { timeout: 15000 });
+    await pw.press("Enter");
+    await page.waitForURL((u) => !u.pathname.endsWith(LOGIN), {
+      timeout: 20000,
+    });
+  }
+
+  const target = `${BASE}${PAGE}`;
+  const categories = (process.env.NF_BROWSER_CATEGORIES ?? "")
+    .split(",")
+    .map((c) => c.trim())
+    .filter(Boolean);
+
+  const runnerResult = await lighthouse(target, {
+    port,
+    output: "json",
+    logLevel: "error",
+    formFactor: FORMFACTOR,
+    // Le bridage d'écran par défaut simule un téléphone : le laisser en place
+    // pendant qu'on demande `desktop` produirait un décor incohérent, et des
+    // chiffres qu'on ne saurait rattacher à aucun appareil réel.
+    screenEmulation:
+      FORMFACTOR === "desktop"
+        ? { mobile: false, width: 1440, height: 900, deviceScaleFactor: 1 }
+        : undefined,
+    // 🔴 Sans ceci, Lighthouse VIDE le stockage avant de mesurer — donc les
+    // témoins de session — et audite l'écran de connexion en silence. C'est le
+    // piège central d'un audit derrière authentification.
+    disableStorageReset: true,
+    ...(categories.length > 0 ? { onlyCategories: categories } : {}),
+  });
+
+  const lhr = runnerResult?.lhr;
+  if (!lhr) {
+    console.error("Lighthouse n'a rendu aucun rapport.");
+    process.exit(69); // EX_UNAVAILABLE
+  }
+
+  // Le rapport COMPLET est conservé : le résumé sert à décider, l'original à
+  // vérifier — et à comparer dans le temps.
+  mkdirSync(OUTPUT, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/gu, "-").slice(0, 19);
+  const slug = PAGE.replace(/\//gu, "-").replace(/^-/u, "") || "racine";
+  const fullPath = path.join(OUTPUT, `lighthouse-${slug}-${stamp}.json`);
+  writeFileSync(fullPath, JSON.stringify(lhr), "utf8");
+
+  console.log(
+    JSON.stringify(
+      { ...summarizeLighthouse(lhr, THRESHOLD), fullReport: fullPath },
+      null,
+      2,
+    ),
+  );
+} finally {
+  await ctx.close();
+}