@nodefony/devkit 10.0.0-beta.3 → 10.0.0-beta.5

package/skills/nodefony-add-crud/SKILL.md

@@ -42,6 +42,11 @@ gabarit porte des détails qui ne se devinent pas : le repository résolu au pre
 se connecte qu'au démarrage), la pagination bornée **et son tri déclaré**, les codes
 201/204/404/409/422, et l'en-tête `Location`.
 
+Le controller généré **déclare** ses entrées : chaque route porte un `schema` (`idParams`, le schéma
+de création ou de retouche de l'entité), et l'action reçoit `input` — validé à la porte (422) avant
+tout appel au service, qui revalide pour ses autres portes (CLI, socket). Pour ajouter une action,
+**garde cette forme** : un `@Body` ou un `@Param` sur une action à schéma est refusé au démarrage.
+
 ## La grammaire de champs
 
 `nom:type[?][=défaut][:index|:unique]` — **non-null par défaut**, `?` rend facultatif, `=valeur`
@@ -190,7 +195,11 @@ refus tombe tout seul.
 
 ## Les trois vérités à savoir avant de livrer (SQL)
 
-1. **La table naît au prochain démarrage en développement** (`CREATE TABLE IF NOT EXISTS`).
+1. **La table existe dès la commande quand l'application versionne ses migrations** (toute
+   application `complete`) : `create entity` écrit ET applique la migration de la table neuve —
+   `--no-migrate` s'en dispense ; si des entités modifiées attendaient, la migration est écrite mais
+   PAS appliquée, et la sortie nomme les tables en trop. Sinon, la table naît au prochain démarrage
+   en développement (`CREATE TABLE IF NOT EXISTS`).
 2. **La modifier n'altère rien** — aucun `ALTER` n'est émis. Une colonne ajoutée à une entité déjà
    créée n'apparaîtra pas dans une base existante.
 3. **La production ne fabrique JAMAIS le schéma.** Elle l'applique par des migrations, écrites par

package/skills/nodefony-add-service/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Crée un service injectable dans une application Nodefony par `nodefony create service`, et le
   fait entrer dans le conteneur — la moitié qu'on oublie. Porte la distinction entre le nom de la
   CLASSE et le nom de l'INSTANCE, les deux façons d'obtenir un service depuis un autre
-  (`@inject` au constructeur ou `container.get` à l'usage), le choix de sa durée de vie
+  (`@Inject` au constructeur ou `container.get` à l'usage), le choix de sa durée de vie
   (un exemplaire pour l'application, ou un par requête), et le défaut mesuré qu'un service
   écrit à la main produit : une classe qui compile, dont les tests passent, et que le conteneur
   ignore. À charger AVANT d'écrire une classe de service ou d'appeler un service depuis un autre.
@@ -63,7 +63,7 @@ et à l'introspection, et n'est construit qu'à la première requête qui le ré
 C'est le piège n°1, et il ne produit aucune erreur — juste un `null` :
 
 ```ts
-@injectable()                            // ← nomme la CLASSE : @inject("BillingService")
+@injectable()                            // ← nomme la CLASSE : @Inject("BillingService")
 export class BillingService extends Service {
   constructor() {
     super("billing", ...);               // ← nomme l'INSTANCE : container.get("billing")
@@ -103,7 +103,7 @@ Détail : `node_modules/nodefony/docs/request-context.md`.
 
 | Voie                           | Quand                                                                         |
 | ------------------------------ | ----------------------------------------------------------------------------- |
-| `@inject("X")` au constructeur | **par défaut** — la dépendance est déclarée, l'ordre de démarrage la respecte |
+| `@Inject("X")` au constructeur | **par défaut** — la dépendance est déclarée, l'ordre de démarrage la respecte |
 | `container.get("x")` à l'usage | quand la dépendance est facultative, tardive, ou choisie à l'exécution        |
 
 `create service --inject` pose la première. Le second est visible partout dans les exemples, et

package/skills/nodefony-authentication/SKILL.md

@@ -207,11 +207,11 @@ l'audience absente : `--write`, puis réimport. Détail :
 Un script, une tâche planifiée, un agent n'ont ni navigateur ni cookie : ils présentent une
 preuve à chaque appel, `Authorization: Bearer …`.
 
-| Preuve                          | L'obtenir                                                       |
-| ------------------------------- | --------------------------------------------------------------- |
-| clé d'API opaque (`nf_…`)       | `POST /nodefony/security/api/keys` (session d'administration)   |
-| jeton signé par l'application   | `npx nodefony security:token [compte] --scope … --ttl … --json` |
-| jeton Keycloak (client machine) | `requestClientCredentialsToken` de `@nodefony/security`         |
+| Preuve                          | L'obtenir                                                           |
+| ------------------------------- | ------------------------------------------------------------------- |
+| clé d'API opaque (`nf_…`)       | `POST /nodefony/security/api/keys` (session d'administration)       |
+| jeton signé par l'application   | `npx nodefony security:mcp:token [compte] --scope … --ttl … --json` |
+| jeton Keycloak (client machine) | `requestClientCredentialsToken` de `@nodefony/security`             |
 
 ❌ Un `POST` vers la route de login depuis un script, ou un cookie de session recopié dans sa
 configuration : le premier fait stocker un mot de passe au programme, le second expire et casse

package/skills/nodefony-browser/SKILL.md

@@ -381,6 +381,26 @@ en bout : le message part-il, revient-il, et l'écran le reçoit-il ?
 > lui, vaut pour toute attente que tu écriras : tant qu'elle n'a pas échoué une fois, elle ne
 > discrimine rien.
 
+### Éprouver la REPRISE après une coupure réseau — `NF_BROWSER_CUT`
+
+```bash
+docker exec -e NF_BROWSER_CUT=5000:4000 mon-app-browser node /app/see-screen/watch.mjs /tableau-de-bord 25000
+```
+
+`<début>:<durée>` en millisecondes : le réseau tombe 5 s après l'ouverture de la page, revient 4 s
+plus tard. Chaque socket coupé sort avec `closedAt` et `closeCode` (1006, ce que voit un client
+qui perd le réseau), le bloc `cut` compte les réouvertures refusées pendant la coupure, et le
+socket rouvert montre ses frames : l'accueil, les abonnements rejoués, leur acquittement, puis le
+flux. C'est la seule preuve qu'une page qui perd le réseau **retrouve** ses données.
+
+- **Le serveur est prévenu** (fermeture 1000) : la connexion coupée ne reste pas à demi ouverte
+  chez lui. Une vraie perte de réseau, elle, ne le prévient pas. La sonde éprouve la reprise du
+  client, pas la détection d'un pair mort.
+- **Le relais Vite (`/_vite/`) n'est pas coupé** : son client de rechargement à chaud recharge la
+  page quand il retrouve le serveur. Vous observeriez une page neuve, pas sa reprise.
+- **Les `ERR_INTERNET_DISCONNECTED` de la console pendant la coupure sont attendus.**
+- Une valeur malformée est refusée (code 64), jamais ignorée.
+
 ## Piloter le socket de bout en bout — `socket.mjs`
 
 `watch.mjs` regarde le trafic d'une page ; celui-ci **conduit** : il ouvre un socket temps réel

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

@@ -36,10 +36,19 @@ Deux frames servent de repères :
 
 ### `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.
+`verdict`, `receivedAfterMs`, canaux, méthodes, identité. **S'il ne vient jamais** (code de retour
+65), la sortie dit lequel des deux cas :
+
+- **`REFUSÉ AU HANDSHAKE`** — le serveur a répondu autre chose que `101` : la socket ne s'est jamais
+  ouverte, et la sonde le rend tout de suite avec `status`, `afterMs` et la `browserReason` du
+  navigateur (la page ne voit qu'une fermeture `1006` ; le statut, seul le navigateur le connaît).
+  `401` : la page n'est pas authentifiée (donner `NF_BROWSER_USER` + `NF_BROWSER_LOGIN`) ; `403` :
+  le compte n'a pas le rôle, ou l'`Origin` de la page est refusé ; `404` : le chemin du endpoint
+  est faux. Chromium ne nomme pas le code d'un `401` porteur de `WWW-Authenticate` (« HTTP
+  Authentication failed ») : la sonde le traduit.
+- **Rien sur la sortie standard, message « en 8000 ms »** — la socket s'est ouverte mais l'accueil
+  n'est jamais venu : l'endpoint n'est pas un endpoint temps réel Nodefony, ou le serveur ferme
+  après l'ouverture. Le réseau qui « passe » n'innocente rien.
 
 ### `subscription`
 

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

@@ -37,6 +37,11 @@ C'est au lecteur de juger — la sonde fournit, elle ne condamne pas ce qu'elle
 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.
 
+- **Un widget en Shadow DOM est invisible à un sélecteur nu** — la sonde rend `absent`, et l'on
+  conclut à tort que l'élément n'existe pas. `hôte >>> sélecteur` entre dans la racine fantôme
+  OUVERTE de l'hôte (`#ma-barre >>> .bouton`), segment après segment. Le fond effectif traverse la
+  frontière de la même façon : au-dessus de la racine fantôme, c'est l'hôte qui fait fond.
+
 - **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
@@ -102,9 +107,16 @@ 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.
+  horizontal accidentel). Il porte le verdict.
+- `horizontalScrollers` : les conteneurs défilants (`overflow-x: auto|scroll`) dont le contenu
+  déborde — une barre de défilement horizontale DANS la page, que `horizontalOverflow` ne voit
+  pas. Il porte AUSSI le verdict. Vécu : une barre de débogage en Shadow DOM débordait de 232 px
+  pendant que la page entière se déclarait saine. Cause fréquente : une infobulle invisible
+  (`visibility: hidden`) ancrée à gauche sur un bouton de droite — invisible, elle élargit quand
+  même la zone défilable.
 - `elementsOutsideViewport` : une **information**, pas un verdict — carrousels, tiroirs et textes
   destinés aux lecteurs d'écran sortent du viewport légitimement.
+- Les trois mesures descendent dans les **Shadow DOM ouverts**.
 - `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.

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

@@ -27,7 +27,8 @@
  *                        saisir, choisir, touche, voir, defiler, attendre. Un écran qui se déplie
  *                        au clic n'existe pas tant qu'on ne l'a pas ouvert.
  * `@env` NF_BROWSER_FULLPAGE 1 = capture la page ENTIÈRE (défaut : la fenêtre)
- * `@env` NF_BROWSER_PROBES sélecteurs CSS à sonder, séparés par des virgules (`libellé=sélecteur`)
+ * `@env` NF_BROWSER_PROBES sélecteurs CSS à sonder, séparés par des virgules (`libellé=sélecteur`) ;
+ *                        `hôte >>> sélecteur` entre dans le Shadow DOM ouvert de l'hôte
  * `@env` NF_BROWSER_WIDTHS largeurs de la famille responsive (défaut 360,768,1280)
  * `@env` NF_BROWSER_VIEWPORT écran mesuré : mobile, mobile-court, tablette, bureau (défaut), large, tres-large, ou LARGEURxHAUTEUR — sous 600 px, émulé en téléphone (tactile, densité 2)
  * `@env` NF_BROWSER_PRIMARY sélecteur de l'action principale pour la famille pli (défaut : le plus grand bouton de validation visible)
@@ -384,7 +385,14 @@ function isVisible(el) {
 function effectiveBackground(el) {
   const layers = [];
   let opaqueLayer = null;
-  for (let n = el; n; n = n.parentElement) {
+  // Un élément posé à la racine d'un Shadow DOM n'a pas de parent : son fond
+  // est celui de l'HÔTE, et la remontée continue de l'autre côté.
+  const up = (n) => {
+    if (n.parentElement) return n.parentElement;
+    const root = n.getRootNode();
+    return root instanceof ShadowRoot ? root.host : null;
+  };
+  for (let n = el; n; n = up(n)) {
     const bg = getComputedStyle(n).backgroundColor;
     if (!bg || bg.includes("transparent")) continue;
     const { a } = parseColor(bg);
@@ -550,18 +558,44 @@ function probeA11y() {
  * Famille rendu — la page tient-elle dans son viewport, ses polices sont-elles
  * VRAIMENT arrivées. Les éléments hors viewport sont une INFO, pas le verdict :
  * carrousels et textes pour lecteurs d'écran en produisent légitimement.
+ *
+ * Le débordement se cherche AUSSI dans les Shadow DOM ouverts, et dans chaque
+ * conteneur défilant : un widget isolé (une barre de débogage) peut porter sa
+ * propre barre de défilement horizontale sans que la page, elle, déborde d'un
+ * pixel — la mesure du document seul la déclarait saine.
  */
 function probeRendering() {
   const doc = document.scrollingElement ?? document.documentElement;
   const overflowPx = Math.max(0, doc.scrollWidth - window.innerWidth);
   const outsideViewport = [];
   let totalOutside = 0;
-  for (const el of document.querySelectorAll("body *")) {
+  const scrollersX = [];
+  let totalScrollersX = 0;
+  const all = (root, out) => {
+    for (const el of root.querySelectorAll("*")) {
+      out.push(el);
+      if (el.shadowRoot) all(el.shadowRoot, out);
+    }
+    return out;
+  };
+  for (const el of all(document.body, [])) {
     const r = el.getBoundingClientRect();
-    if (r.width > 0 && r.right > window.innerWidth + 1) {
+    if (r.width === 0) continue;
+    if (r.right > window.innerWidth + 1 && totalOutside < 200) {
       totalOutside += 1;
       if (outsideViewport.length < 3) outsideViewport.push(describeElement(el));
-      if (totalOutside >= 200) break;
+    }
+    const ox = getComputedStyle(el).overflowX;
+    if (
+      (ox === "auto" || ox === "scroll") &&
+      el.scrollWidth > el.clientWidth + 1
+    ) {
+      totalScrollersX += 1;
+      if (scrollersX.length < 3)
+        scrollersX.push({
+          element: describeElement(el),
+          overflowPx: el.scrollWidth - el.clientWidth,
+        });
     }
   }
   const families = {};
@@ -571,8 +605,12 @@ function probeRendering() {
     if (f.status === "error") failedFonts += 1;
   }
   return {
-    verdict: overflowPx > 0 || failedFonts > 0 ? "ALERTE" : "OK",
+    verdict:
+      overflowPx > 0 || totalScrollersX > 0 || failedFonts > 0
+        ? "ALERTE"
+        : "OK",
     horizontalOverflow: { present: overflowPx > 0, overflowPx },
+    horizontalScrollers: { total: totalScrollersX, examples: scrollersX },
     elementsOutsideViewport: { total: totalOutside, examples: outsideViewport },
     fonts: {
       status: document.fonts.status,
@@ -659,7 +697,16 @@ async function measurePage(args) {
       s.getAttribute("src"),
     ),
     probes: args.probes.map(({ label, sel }) => {
-      const el = document.querySelector(sel);
+      // `hôte >>> sélecteur` traverse un Shadow DOM ouvert (un widget isolé,
+      // une barre de débogage) : chaque segment se cherche dans la racine
+      // fantôme de l'élément trouvé par le précédent.
+      let el = null;
+      let scope = document;
+      for (const part of sel.split(">>>")) {
+        el = scope?.querySelector(part.trim()) ?? null;
+        scope = el?.shadowRoot ?? null;
+        if (el === null) break;
+      }
       if (!el) return { label, absent: true, selector: sel };
       const cs = getComputedStyle(el);
       const r = el.getBoundingClientRect();
@@ -789,7 +836,7 @@ if (active.has("reseau")) {
   const slowThreshold = Number(process.env.NF_BROWSER_SEUIL_LENT ?? 1000);
   const items = await Promise.all(
     finishedRequests.map(async (rq) => {
-      let bytes = null;
+      let bytes;
       try {
         // `sizes()` rend la taille RÉELLEMENT transférée ; l'en-tête
         // content-length manque sur les réponses en flux.

package/skills/nodefony-browser/scripts/lib/probes.mjs

@@ -240,6 +240,44 @@ export function parseColorScheme(raw) {
   return { schema: null, invalid: v };
 }
 
+/**
+ * Analyse une coupure réseau demandée (`NF_BROWSER_CUT`), au format
+ * `<début>:<durée>` en millisecondes — `4000:3000` coupe le réseau 4 s après
+ * l'ouverture de la page et le rétablit 3 s plus tard.
+ *
+ * La coupure existe pour éprouver une REPRISE : un flux temps réel qui revient
+ * après une perte de réseau ne se constate sur aucune capture. Une valeur
+ * malformée est REFUSÉE : ignorée, elle ferait observer une page jamais coupée
+ * en croyant avoir éprouvé sa reprise.
+ *
+ * @param {string|undefined} raw - valeur brute (`"4000:3000"`, vide).
+ * @returns {{ cut: { at: number, duration: number }|null, invalid: string|null }}
+ *   `cut` à null quand rien n'est demandé.
+ */
+export function parseCut(raw) {
+  const v = (raw ?? "").trim();
+  if (!v) return { cut: null, invalid: null };
+  const m = /^(\d+):(\d+)$/.exec(v);
+  if (!m || Number(m[2]) === 0) return { cut: null, invalid: v };
+  return { cut: { at: Number(m[1]), duration: Number(m[2]) }, invalid: null };
+}
+
+/**
+ * Ramène un code de fermeture WebSocket à un code qu'un NAVIGATEUR peut
+ * émettre : 1000, ou 3000 à 4999 — tout autre lève `InvalidAccessError`.
+ *
+ * 🔴 Le côté serveur d'une route Playwright est un vrai WebSocket de page.
+ * Fermé avec 1001 ou 1006, il refuse, Playwright avale l'erreur et rend « ok » :
+ * la connexion réelle reste ouverte et le serveur continue de pousser vers un
+ * socket que la sonde dit fermé. Mesuré : 47 s sans fermeture côté serveur.
+ *
+ * @param {number} code - le code voulu.
+ * @returns {number} ce code s'il est émissible, 1000 sinon.
+ */
+export function sendableCloseCode(code) {
+  return code === 1000 || (code >= 3000 && code <= 4999) ? code : 1000;
+}
+
 /**
  * Arguments de lancement qui imposent le schéma de couleurs AU MOTEUR.
  *
@@ -483,6 +521,21 @@ export function median(values) {
   const m = Math.floor(sorted.length / 2);
   return sorted.length % 2 === 1 ? sorted[m] : (sorted[m - 1] + sorted[m]) / 2;
 }
+
+/**
+ * Arrondit une durée au centième de milliseconde — la précision d'un RTT local.
+ *
+ * Un arrondi à la milliseconde entière rend 0 pour tout aller-retour sous
+ * 0,5 ms : sur une même machine, la sonde annonçait une latence nulle. Le
+ * centième reste sous la résolution de `performance.now()` côté navigateur
+ * (~0,1 ms hors isolation), donc ne fabrique aucune précision qui n'existe pas.
+ *
+ * @param {number} ms - durée brute en millisecondes.
+ * @returns {number} la durée arrondie à 0,01 ms.
+ */
+export function roundMs(ms) {
+  return Math.round(ms * 100) / 100;
+}
 /**
  * Résume un rapport axe-core en un bloc lisible — le tri éditorial, pas la mesure.
  *

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

@@ -24,10 +24,10 @@
  * `@env` NF_BROWSER_PINGS nombre de mesures de latence (défaut 5)
  * `@requires` conteneur du profil `browser` démarré · serveur joignable · un endpoint temps réel exposé
  * `@output` un objet JSON sur stdout : accueil, abonnement, latence, api, reconnexion — un verdict par étape
- * `@exit` 0 scénario joué (les verdicts sont des DONNÉES) · 64 usage (endpoint manquant, params illisibles) · 65 accueil jamais reçu
+ * `@exit` 0 scénario joué (les verdicts sont des DONNÉES) · 64 usage (endpoint manquant, params illisibles) · 65 accueil jamais reçu (refus au handshake : JSON sur stdout, statut nommé)
  */
 import { open, goTo } from "./lib/browser.mjs";
-import { median } from "./lib/probes.mjs";
+import { median, roundMs } from "./lib/probes.mjs";
 
 const ENDPOINT = process.argv[2] ?? process.env.NF_BROWSER_SOCKET ?? "";
 if (!ENDPOINT.startsWith("/")) {
@@ -95,6 +95,13 @@ async function scenarioSocket(conf) {
   const openSocket = () =>
     new Promise((resolve, reject) => {
       const ws = new WebSocket(url);
+      // Une fermeture AVANT l'ouverture est un refus du HANDSHAKE (réponse
+      // non-101 : 401, 403, 404…) — rien à attendre, et surtout pas les huit
+      // secondes du garde, qui feraient lire un refus net comme un silence.
+      let opened = false;
+      ws.addEventListener("open", () => {
+        opened = true;
+      });
       const guard = setTimeout(() => {
         try {
           ws.close();
@@ -105,6 +112,14 @@ async function scenarioSocket(conf) {
       }, conf.timeoutMs);
       ws.addEventListener("close", (ev) => {
         closes.push({ a: a(), code: ev.code, reason: ev.reason });
+        if (!opened) {
+          clearTimeout(guard);
+          const refusal = new Error(
+            `accueil jamais reçu : connexion refusée au handshake sur ${url}`,
+          );
+          refusal.handshake = { afterMs: a(), closeCode: ev.code };
+          reject(refusal);
+        }
       });
       ws.addEventListener("message", (ev) => {
         let frame;
@@ -166,7 +181,8 @@ async function scenarioSocket(conf) {
       const settle = (value) => {
         if (settled) return;
         settled = true;
-        resolve({ ...value, ms: Math.round(performance.now() - start) });
+        // Durée BRUTE : l'arrondi se fait côté Node (`roundMs`), où il s'éprouve.
+        resolve({ ...value, ms: performance.now() - start });
       };
       const guard = setTimeout(() => {
         pending.delete(id);
@@ -181,8 +197,21 @@ async function scenarioSocket(conf) {
       ws.send(JSON.stringify(frame));
     });
 
-  const { ws, welcome } = await openSocket();
+  let first;
+  try {
+    first = await openSocket();
+  } catch (e) {
+    // Le refus au handshake est une RÉPONSE du serveur, pas une panne de la
+    // sonde : il se rend en données (le pilote y joint le statut HTTP que seul
+    // le navigateur connaît — la page ne voit qu'un code de fermeture 1006).
+    if (!e?.handshake) throw e;
+    result.welcome = { verdict: "REFUSÉ AU HANDSHAKE", ...e.handshake };
+    result.closes = closes;
+    return result;
+  }
+  const { ws, welcome } = first;
   result.welcome = {
+    verdict: "OK",
     receivedAfterMs: a(),
     protocol: welcome.protocol ?? null,
     channels: welcome.channels ?? [],
@@ -330,6 +359,19 @@ async function scenarioSocket(conf) {
 const { browser, ctx, page, reuse } = await open();
 await goTo(page, ctx, process.env.NF_BROWSER_PAGE ?? "/", reuse);
 
+// Le statut HTTP d'un handshake refusé n'existe que pour le NAVIGATEUR : la
+// page n'en reçoit qu'un code de fermeture 1006. Le pilote l'écoute là où le
+// navigateur le dit — l'erreur du socket et la console.
+const handshakeErrors = [];
+page.on("websocket", (socket) => {
+  socket.on("socketerror", (error) => handshakeErrors.push(String(error)));
+});
+page.on("console", (message) => {
+  if (message.type() === "error" && message.text().includes("WebSocket")) {
+    handshakeErrors.push(message.text());
+  }
+});
+
 let result;
 try {
   result = await page.evaluate(scenarioSocket, cfg);
@@ -344,11 +386,35 @@ try {
   process.exit(65); // EX_DATAERR
 }
 
+if (result.welcome?.verdict === "REFUSÉ AU HANDSHAKE") {
+  // Les messages du navigateur arrivent par le protocole de débogage, parfois
+  // juste APRÈS la fermeture vue par la page : une courte attente bornée.
+  if (handshakeErrors.length === 0) await page.waitForTimeout(500);
+  const reason = handshakeErrors[0]?.slice(0, 300) ?? null;
+  // Chromium nomme le code (« Unexpected response code: 404 ») SAUF pour un
+  // 401 porteur de `WWW-Authenticate` : il le traite en défi d'authentification
+  // qu'il ne sait pas satisfaire, et ne dit que cela.
+  const status = /HTTP Authentication failed/i.test(reason ?? "")
+    ? "401"
+    : /\b([1-5]\d\d)\b/.exec(reason ?? "")?.[1];
+  result.welcome.status = status ? Number(status) : null;
+  result.welcome.browserReason = reason;
+  console.log(JSON.stringify(result, null, 2));
+  console.error(
+    `Accueil jamais reçu : le serveur a REFUSÉ le handshake (statut ${result.welcome.status ?? "non communiqué par le navigateur"}).\n` +
+      `→ 401/403 : la page ${process.env.NF_BROWSER_PAGE ?? "/"} n'est pas authentifiée, ou le compte n'a pas le droit (NF_BROWSER_USER + NF_BROWSER_LOGIN) ; 404 : chemin du endpoint faux ; 403 sur une page authentifiée : Origin refusé.`,
+  );
+  await browser.close();
+  process.exit(65); // EX_DATAERR — l'accueil n'est pas venu, la cause est nommée
+}
+
 // La médiane se calcule ici, avec la fonction que les tests éprouvent — la
 // moyenne serait déplacée par un seul aller-retour aberrant.
 if (Array.isArray(result.latency?.measuresMs)) {
+  result.latency.measuresMs = result.latency.measuresMs.map(roundMs);
   result.latency.medianMs = median(result.latency.measuresMs);
 }
+if (typeof result.api?.ms === "number") result.api.ms = roundMs(result.api.ms);
 
 console.log(JSON.stringify(result, null, 2));
 await browser.close();

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

@@ -13,16 +13,27 @@
  * `@env` NF_BROWSER_USER identifiant ; sans lui, aucune authentification n'est tentée
  * `@env` NF_BROWSER_PASSWORD mot de passe associé
  * `@env` NF_BROWSER_UNTIL expression JS évaluée DANS la page ; l'observation s'arrête dès qu'elle est vraie (point d'arrêt applicatif)
+ * `@env` NF_BROWSER_CUT coupure réseau `<début>:<durée>` en ms (`4000:3000`), comptée depuis l'ouverture de la page — éprouve la REPRISE d'un flux ; chaque socket dit alors quand il s'est fermé et rouvert
  * `@env` NF_BROWSER_MAXFRAMES nombre de frames WebSocket conservées par sens (défaut 12)
  * `@requires` conteneur du profil `browser` démarré · serveur Nodefony joignable
  * `@output` JSON : sockets et leurs frames (horodatées), requêtes non-2xx, erreurs console, verdict de la condition
  */
 import { open, goTo } from "./lib/browser.mjs";
+import { parseCut, sendableCloseCode } from "./lib/probes.mjs";
 
 const PAGE = process.argv[2] ?? process.env.NF_BROWSER_PAGE ?? "/";
 const DURATION = Number(process.argv[3] ?? 8000);
 const UNTIL = process.env.NF_BROWSER_UNTIL ?? "";
 const MAX = Number(process.env.NF_BROWSER_MAXFRAMES ?? 12);
+const { cut: CUT, invalid: invalidCut } = parseCut(process.env.NF_BROWSER_CUT);
+if (invalidCut) {
+  console.error(
+    `NF_BROWSER_CUT attend « <début>:<durée> » en ms (ex. 4000:3000), reçu « ${invalidCut} »`,
+  );
+  process.exit(64);
+}
+// Sockets que la coupure FERME (cf « La coupure réseau » plus bas).
+const isRouted = (url) => !new URL(url).pathname.startsWith("/_vite/");
 
 const { browser, ctx, page, reuse } = await open();
 
@@ -39,6 +50,9 @@ const uncaughtErrors = [];
 // qu'on ne lit, et une sortie de plusieurs mégaoctets serait illisible — donc
 // inexploitable pour décider. On garde les premières de chaque sens.
 page.on("websocket", (ws) => {
+  // Un socket routé pour la coupure est enregistré par la route : l'écouter
+  // ici aussi le compterait deux fois.
+  if (CUT && isRouted(ws.url())) return;
   const rec = { url: ws.url(), openedAt: at(), sent: [], received: [] };
   sockets.push(rec);
   ws.on("framesent", (f) => {
@@ -72,8 +86,88 @@ page.on("pageerror", (e) => {
     uncaughtErrors.push({ a: at(), text: String(e).slice(0, 200) });
 });
 
+// ── La coupure réseau : éprouver une REPRISE ────────────────────────────────
+// `setOffline` seul ne suffit PAS : Chromium y coupe le HTTP mais laisse les
+// WebSockets déjà ouverts vivre — mesuré, aucun `close` n'est émis, et l'on
+// « éprouverait » une reprise sans qu'aucune connexion ait été perdue. Les
+// sockets passent donc par `routeWebSocket` : à la coupure, la sonde ferme
+// chaque connexion des deux côtés — 1006 vers la page, ce que voit un client
+// qui perd le réseau ; 1000 vers le serveur, qui libère la connexion au lieu de
+// la garder à demi ouverte — et refuse toute réouverture jusqu'au
+// rétablissement.
+// Le relais Vite (`/_vite/`) est épargné : son client de rechargement à chaud
+// RECHARGE la page quand il retrouve le serveur, et la reprise observée serait
+// celle d'une page neuve, pas celle de l'application.
+let cut = null;
+let cutActive = false;
+const cutTimers = [];
+const routed = new Set();
+// Le côté SERVEUR d'une route est un vrai WebSocket de navigateur : son code
+// de fermeture passe par `sendableCloseCode` (cf son TSDoc).
+if (CUT) {
+  cut = { requested: CUT, refused: 0 };
+  await ctx.routeWebSocket(isRouted, (route) => {
+    if (cutActive) {
+      cut.refused += 1;
+      route.close({ code: 1006, reason: "coupure réseau (sonde)" });
+      return;
+    }
+    const server = route.connectToServer();
+    const rec = { url: route.url(), openedAt: at(), sent: [], received: [] };
+    sockets.push(rec);
+    const pair = { route, server, rec };
+    routed.add(pair);
+    // Poser `onMessage` coupe le relais automatique : on relaie à la main.
+    route.onMessage((m) => {
+      if (rec.sent.length < MAX)
+        rec.sent.push({ a: at(), payload: String(m).slice(0, 160) });
+      server.send(m);
+    });
+    server.onMessage((m) => {
+      if (rec.received.length < MAX)
+        rec.received.push({ a: at(), payload: String(m).slice(0, 160) });
+      route.send(m);
+    });
+    const closed = (code) => {
+      rec.closedAt ??= at();
+      rec.closeCode ??= code;
+      routed.delete(pair);
+    };
+    route.onClose((code, reason) => {
+      closed(code);
+      server.close({ code: sendableCloseCode(code), reason });
+    });
+    server.onClose((code, reason) => {
+      closed(code);
+      route.close({ code, reason });
+    });
+  });
+}
+
 await goTo(page, ctx, PAGE, reuse);
 
+if (CUT) {
+  cutTimers.push(
+    setTimeout(() => {
+      cut.offlineAt = at();
+      cutActive = true;
+      ctx.setOffline(true).catch((e) => (cut.error = String(e)));
+      for (const { route, server, rec } of routed) {
+        rec.closedAt ??= at();
+        rec.closeCode ??= 1006;
+        server.close({ code: 1000, reason: "coupure réseau (sonde)" });
+        route.close({ code: 1006, reason: "coupure réseau (sonde)" });
+      }
+      routed.clear();
+    }, CUT.at),
+    setTimeout(() => {
+      cut.onlineAt = at();
+      cutActive = false;
+      ctx.setOffline(false).catch((e) => (cut.error = String(e)));
+    }, CUT.at + CUT.duration),
+  );
+}
+
 // ── Le « point d'arrêt » : une CONDITION, pas une ligne de code ──────────────
 // `waitForFunction` réévalue l'expression dans la page à chaque animation frame.
 // C'est ce qui remplace utilement un breakpoint dans un pilotage automatisé :
@@ -100,12 +194,19 @@ if (UNTIL) {
   await page.waitForTimeout(DURATION);
 }
 
+for (const t of cutTimers) clearTimeout(t);
+if (cut && cut.onlineAt === undefined) {
+  cutActive = false;
+  await ctx.setOffline(false);
+}
+
 console.log(
   JSON.stringify(
     {
       url: page.url(),
       observeForMs: at(),
       verdict,
+      cut,
       // Les totaux sont posés sur l'objet accumulé plutôt que recomposés par
       // étalement dans un `map` (règle `no-map-spread` : allocation inutile).
       sockets: sockets.map((s) =>