@nodefony/devkit 10.0.0-beta.4 → 10.0.0-beta.6

package/skills/nodefony-add-realtime-channel/references/binaire.md

@@ -0,0 +1,191 @@
+# Des octets dans le temps réel — mode d'emploi complet
+
+> Chargé depuis `SKILL.md` dès qu'une charge contient des octets (`Uint8Array`, `Buffer`, CBOR,
+> `$bytes`). Tout ce qui suit se vérifie dans la documentation installée :
+> `node_modules/@nodefony/realtime/docs/protocole.md` (section « Des octets dans la charge »),
+> `node_modules/@nodefony/realtime/docs/configuration.md` (clé `codec`),
+> `node_modules/nodefony/docs/client.md` (« Choisir le codec de trame »),
+> `node_modules/nodefony/docs/cbor.md` (le codec lui-même).
+
+## Sommaire
+
+1. [Le modèle](#1-le-modèle--une-frame-comme-les-autres)
+2. [Mise en place](#2-mise-en-place--deux-lignes-une-par-côté)
+3. [Publier et recevoir](#3-publier-et-recevoir)
+4. [Canal ou flux brut ?](#4-canal-ou-flux-brut-)
+5. [Lire des octets sans se tromper](#5-lire-des-octets-sans-se-tromper)
+6. [Plusieurs serveurs](#6-plusieurs-serveurs)
+7. [Chaque message, sa cause, ton geste](#7-chaque-message-sa-cause-ton-geste)
+8. [Ce qui arrive SANS message](#8-ce-qui-arrive-sans-message)
+9. [Prouver que ça marche](#9-prouver-que-ça-marche)
+
+## 1. Le modèle — une frame comme les autres
+
+- Une trame qui porte des octets est une **notification JSON-RPC ordinaire** dont la charge est, ou
+  contient, un `Uint8Array`. Il n'y a pas de seconde grammaire.
+- Le **codec** ne dit que la forme sur le fil : en CBOR, les octets voyagent tels quels ; sur une
+  connexion restée en texte, ils voyagent sous la convention `{"$bytes":"<base64url>"}`, que le
+  client relit en `Uint8Array` sans rien importer.
+- Le codec se **négocie** par connexion : le navigateur l'offre, le serveur choisit et l'annonce
+  dans `realtime:welcome`. Un client qui ne l'offre pas reste en texte — rien ne casse.
+- Parce que c'est la même frame, les octets d'un canal passent par **les mêmes gardes** que le
+  texte : politique du canal, rôles, audit, sonde.
+
+**N'invente jamais d'en-tête binaire maison** (`[n° de canal][charge]`) : il contournerait toutes
+les gardes et serait à maintenir des deux côtés.
+
+## 2. Mise en place — deux lignes, une par côté
+
+Serveur (`nodefony.config.ts`) :
+
+```ts
+use("@nodefony/realtime", { codec: "cbor" });
+```
+
+Navigateur — à la **PREMIÈRE** création de la socket partagée (souvent le noyau client) :
+
+```ts
+import { NodefonySocket } from "nodefony/client";
+import { CBOR_FRAME_CODEC } from "nodefony/cbor";
+
+const socket = NodefonySocket.shared({
+  url: "/api/live/realtime",
+  codec: CBOR_FRAME_CODEC,
+});
+```
+
+| Serveur                  | Navigateur offre CBOR | Fil retenu | Octets reçus en              |
+| ------------------------ | --------------------- | ---------- | ---------------------------- |
+| `codec: "cbor"`          | oui                   | CBOR       | `Uint8Array`                 |
+| `codec: "cbor"`          | non                   | texte      | `Uint8Array` (via `$bytes`)  |
+| `codec: "json"` (défaut) | oui ou non            | texte      | 🔴 objet déformé `{"0":1,…}` |
+
+D'où la règle : **dès que des octets circulent, le serveur passe en `codec: "cbor"`**. Côté
+navigateur, offrir CBOR est un gain (≈ 30× plus rapide à recevoir 4 Ko d'octets, ~25 % d'octets en
+moins), pas une obligation. Ce gain ne vaut QUE pour des octets : sur des objets ordinaires, CBOR
+encode plus lentement que JSON, natif au moteur, et ne décode pas plus vite. N'offre le codec que si
+des octets circulent.
+
+## 3. Publier et recevoir
+
+```ts
+// serveur — depuis un service, une tâche, un minuteur
+import { getRealtimeHub } from "@nodefony/realtime";
+getRealtimeHub().publish("capteur:raw", {
+  seq: 42,
+  frame: new Uint8Array([1, 2, 3]),
+});
+getRealtimeHub().publish("capteur:raw", new Uint8Array([1, 2, 3])); // charge = les octets seuls
+
+// serveur — dans un RealtimeController, la fabrique du canal reçoit `publish`
+// navigateur
+socket.subscribe("capteur:raw");
+socket.on("capteur:raw", (charge) => {
+  /* charge.frame est un Uint8Array */
+});
+socket.publish("doc:42", { maj: new Uint8Array(update) }); // canal entrant déclaré côté serveur
+```
+
+- `subscribe(canal)` prend **un seul argument** ; le handler se pose par `on(canal, handler)`.
+- Une charge est un objet, un tableau, des octets, ou absente — jamais un scalaire
+  (`publish("c", 42)` lève une `TypeError` qui nomme le canal).
+- Un `Buffer` de Node est un `Uint8Array` : il part en octets, jamais en `{type:"Buffer",data:[…]}`.
+- Une `Date` revient en chaîne et un `bigint` est refusé — exactement comme en JSON.
+
+## 4. Canal ou flux brut ?
+
+| Besoin                                                  | Voie                                                                                      |
+| ------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Des octets qui appartiennent à un canal (cas normal)    | `codec: "cbor"` + `publish` / `on(canal)`                                                 |
+| Un protocole binaire entièrement propre à l'application | `onRealtimeBinary()` (serveur) / `onBinary()` (navigateur), connexion **texte** seulement |
+
+🔴 **Le flux brut est HORS des gardes.** Une trame reçue par `onRealtimeBinary(data)` ne passe ni
+par le verrou de frame ni par les politiques d'action et de canal. Seule la connexion a franchi
+l'Origin, l'authentificateur et le pare-feu. Si tu l'emploies, **toute décision d'accès est à
+toi** : lis l'identité par `RequestContext.getAuthenticatedUser()` et refuse explicitement.
+
+🔴 **Le flux brut n'existe pas sur une connexion CBOR** : toute trame binaire y est une frame du
+codec. `onRealtimeBinary()` n'y est jamais appelée, `sendBinaryToClient()` et `sendBinary()` rendent
+`false`. Ne mélange pas les deux voies sur une même application sans le savoir.
+
+Dans le doute, **préfère un canal + `Uint8Array`** (§3) : même politique, mêmes gardes, même bus
+entre serveurs — le flux brut ne se justifie que pour un protocole binaire qui n'a pas de canal.
+
+## 5. Lire des octets sans se tromper
+
+- **`DataView` : passe la tranche entière.** `new DataView(data.buffer, data.byteOffset,
+data.byteLength)`. Un `Buffer` de Node ne commence pas à 0 dans son tampon : `new
+DataView(data.buffer)` lit des octets qui ne sont pas les tiens.
+- Côté serveur, `onRealtimeBinary` reçoit un `Buffer` de `ws` typé `Uint8Array` : écris ton
+  décodeur sur `Uint8Array`, il servira tel quel dans le navigateur.
+- Si tu appelles toi-même `decodeCbor()` sur un tampon que tu réutilises ensuite, **copie** les
+  octets décodés à garder (`slice()`) : ce sont des vues sur ce tampon.
+
+### 🔴 Le piège du `$bytes` forgé
+
+Quand le serveur a `codec: "cbor"` et qu'une connexion est restée en texte (la convention d'octets
+y est armée), un objet de la forme **exacte** `{ $bytes: "<chaîne>" }` (seule clé, valeur chaîne)
+est réservé aux octets. L'encodeur **refuse** d'en envoyer un qui ne vient pas
+d'octets : un client texte le relirait en octets, un client CBOR en objet.
+
+```ts
+socket.publish("prix", { montant: { $bytes: "12 euros" } }); // 🔴 TypeError
+socket.publish("prix", { montant: { $bytes: "12 euros", devise: "EUR" } }); // ✅ deux clés
+socket.publish("prix", { montant: { raw: "12 euros" } }); // ✅ autre clé
+```
+
+- Navigateur : `emit` / `publish` **lèvent** à la ligne fautive.
+- Serveur : la publication n'atteint pas les abonnés texte, une ligne `ERROR` par publication.
+- Un tel objet **conservé** (état initial renvoyé à chaque nouvel abonné) est refusé **à chaque
+  envoi**. Renomme la clé une fois pour toutes. Ne contourne pas en encodant toi-même en base64.
+- Avec `codec: "json"`, `$bytes` est une clé comme une autre : la règle ne s'applique pas.
+
+## 6. Plusieurs serveurs
+
+Les octets traversent le bus entre exemplaires (`redis`, `cluster`) **intacts**, scellés comme le
+texte si `backplane.secret` est posé : rien à configurer de plus. Un canal suivi à la fois par des
+connexions CBOR et texte paie un encodage par codec, pas un par abonné.
+
+## 7. Chaque message, sa cause, ton geste
+
+Les textes entre guillemets sont recopiés du code ; `<…>` marque une partie variable.
+
+| Où                                                 | Message                                                                                      | Cause                                                                                                                                | Geste                                                                            |
+| -------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| exception (navigateur) / journal `ERROR` (serveur) | `codec JSON : objet {"$bytes": …} non issu d'octets`                                         | objet applicatif de la forme exacte du marqueur, vers une connexion texte                                                            | envoyer un vrai `Uint8Array`, ou renommer / ajouter une clé (§5)                 |
+| journal `ERROR` serveur                            | `rpc <action> : réponse non encodable`                                                       | une `@RealtimeAction` a rendu une valeur que le codec refuse (`$bytes` forgé, cycle, `bigint`) ; le client reçoit `-32603` générique | corriger la valeur rendue                                                        |
+| exception                                          | `Impossible d'encoder un BigInt — JSON.stringify le refuse aussi`                            | `bigint` dans la charge, sous CBOR                                                                                                   | convertir en chaîne ou en nombre                                                 |
+| exception                                          | `Impossible d'encoder une structure circulaire — JSON.stringify la refuse aussi`             | cycle dans la charge                                                                                                                 | aplatir la donnée                                                                |
+| notice navigateur (`-32700`)                       | `Trame binaire écartée : en JSON-RPC texte elle n'a pas de canal`                            | le serveur écrit du binaire brut sur une connexion texte sans `onBinary()`                                                           | lire par `onBinary()`, ou passer par un canal + CBOR                             |
+| notice navigateur (`-32700`)                       | `Trame illisible écartée : elle ne se décode pas en <protocole>`                             | trame que le codec ne décode pas                                                                                                     | côté serveur : chercher qui écrit hors du codec                                  |
+| notice navigateur                                  | `Codec « <protocole> » annoncé sans avoir été offert : la connexion reste en JSON-RPC texte` | serveur qui annonce un codec que ce client n'a pas offert                                                                            | mettre client et serveur à la même version                                       |
+| notice navigateur                                  | `Flux binaire brut indisponible sous <protocole>`                                            | `onBinary()` / `sendBinary()` sur une connexion CBOR                                                                                 | publier les octets sur un canal (§4)                                             |
+| journal `WARNING` serveur, une fois par connexion  | `WS realtime : trame binaire reçue et écartée`                                               | binaire brut reçu sur une connexion texte, sans `onRealtimeBinary()`                                                                 | passer par un canal + CBOR, ou surcharger `onRealtimeBinary()` (§4, hors gardes) |
+| journal `WARNING` serveur, une fois par connexion  | `WS realtime : sendBinaryToClient refusé`                                                    | `sendBinaryToClient()` sur une connexion CBOR                                                                                        | publier les octets sur un canal                                                  |
+| journal `WARNING` serveur, une fois par nature     | `WS realtime : trame binaire illisible pour <protocole> reçue et écartée`                    | trame CBOR malformée ou tronquée ; **aucune réponse** n'est renvoyée (pas d'oracle pour un fuzzer), connexion conservée              | côté client : chercher qui écrit hors du codec                                   |
+| exception (`CborError`)                            | `CBOR refusé à l'octet <n> : <raison>`                                                       | `decodeCbor()` appelé par l'application sur des octets invalides ; `err.offset` dit où                                               | valider la source ; ne jamais faire confiance à des octets reçus                 |
+
+## 8. Ce qui arrive SANS message
+
+- **Serveur resté en `codec: "json"`** : un `Uint8Array` part en `{"0":1,"1":2,…}` — aucune erreur.
+  C'est le piège n°1 : vérifier la clé `codec` avant tout autre diagnostic.
+- **`codec` passé à un `shared()` qui n'est pas le premier** : l'instance existante revient,
+  réglages compris ; la connexion reste en texte (un avertissement hors production seulement).
+- **`sendBinary()` sur un transport fermé** : rend `false`, compté dans `framesUnsent`, sans notice.
+- **Codec non annoncé par l'accueil** : le client reste en texte, sans notice — c'est le cas
+  normal d'un serveur en `codec: "json"`.
+- **Ne déduis jamais le codec de l'en-tête `Sec-WebSocket-Protocol`** renvoyé au handshake : la
+  bibliothèque WebSocket le renvoie qu'elle parle le sous-protocole ou non. Seul `socket.codec`
+  fait foi.
+
+## 9. Prouver que ça marche
+
+- `socket.codec` vaut `"nodefony.jsonrpc.cbor.v1"` une fois l'accueil reçu ; `"nodefony.jsonrpc.v1"`
+  = texte.
+- Compteurs côté navigateur : `socket.binaryFramesDiscarded`, `socket.malformedFramesDiscarded`
+  doivent rester à 0.
+- Un test qui le prouve publie un `Uint8Array` sur un canal et vérifie que l'abonné reçoit un
+  `Uint8Array` **identique** (`instanceof Uint8Array` et mêmes octets) — sous CBOR ET sous texte.
+- Pour lire le fil à l'œil dans l'inspecteur réseau : `NF_REALTIME_CODEC=json` remet le serveur en
+  texte. Exception de débogage : la taille des trames et la contre-pression changent, aucune mesure
+  prise ainsi ne vaut pour la production.

package/skills/nodefony-add-realtime-channel/references/production.md

@@ -0,0 +1,121 @@
+# Ce qui ne se voit qu'en production — plusieurs serveurs, réseau, révocation, charge
+
+> Chargé depuis `SKILL.md` §8. Tout se vérifie dans la documentation installée :
+> `node_modules/@nodefony/realtime/docs/configuration.md` (drivers, clés, variables),
+> `node_modules/@nodefony/realtime/docs/securite.md` (codes de fermeture, `allow` lent),
+> `node_modules/@nodefony/realtime/docs/cadence-et-contre-pression.md`,
+> `node_modules/@nodefony/realtime/docs/canaux-a-membres.md` (gestes qui traversent les serveurs),
+> `node_modules/@nodefony/realtime/docs/observabilite.md` (les compteurs qui accusent un oubli).
+
+## 1. Plusieurs serveurs — rien ne traverse sans intention
+
+| Déploiement                          | `backplane.driver`                  | Ce qui se passe sinon                                                                          |
+| ------------------------------------ | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
+| un seul processus                    | `loopback`                          | —                                                                                              |
+| `nodefony cluster -w N`, une machine | `cluster` (défaut de l'app générée) | sans bus, un abonné sur le worker 2 ne reçoit pas ce que publie le worker 1                    |
+| plusieurs machines ou pods           | `redis` (+ `@nodefony/redis`)       | `loopback` à plusieurs répliques : la moitié des utilisateurs ne reçoit plus rien, sans erreur |
+
+Un bus branché ne diffuse **que les canaux déclarés** : pose `@RealtimeBroadcast("chat:", "room:")`
+sur la classe du contrôleur, **sur tous les serveurs** (le receveur aussi). Un préfixe couvre
+`chat:`, `chat:room-42`, `chat:room-42:1000`. Le défaut est l'isolement : un canal d'observabilité
+décrit SON serveur, il ne doit pas traverser. Le framework diffuse `user:` lui-même.
+
+- L'oubli se voit : `localOnlyTotal` monte sur la sonde dès qu'un bus est branché et qu'un canal
+  non déclaré est publié ; les préfixes diffusés sont listés au démarrage.
+- Le bus est un transport, pas un journal : un serveur absent 30 s ne rattrape rien. Redis
+  injoignable au démarrage : repli sur ce seul processus, WARNING, l'application démarre.
+- **Secret du bus** : `NF_REALTIME_BACKPLANE_SECRET` (≥ 32 caractères), le même partout ; un
+  message non scellé est refusé et compté (`sealRejectedTotal`). Deux applications sur un même
+  Redis : `backplane.namespace` distinct — c'est une clé de sécurité, pas de confort.
+- **Ce qui traverse, et ce qui ne traverse pas** : les publications des canaux diffusés, et deux
+  ordres qui ne font qu'enlever — `closeChannel(canal)` et `evictUser(canal, compte)`. Les gestes
+  par CONNEXION (`subscribeConnection`, `evictConnection`, `channelMembers`) sont locaux au
+  serveur qui tient la socket : appelle-les depuis une entrée client (`@RealtimeInbound`, qui
+  s'exécute par construction sur ce serveur), jamais depuis une requête HTTP routée au hasard.
+- **Bus partagé = bus privé.** Un ordre d'éjection capté sur le bus peut être rejoué par qui y
+  écrit : l'effet reste une coupure (jamais une admission), et changer le secret rend caducs les
+  ordres captés. Risque écrit et accepté (ADR-0022 §6).
+
+## 2. Reconnexion — ce qui est rejoué, ce qui ne l'est pas
+
+- Le client rejoue **ses abonnements** au `realtime:welcome` (imposés compris), et chacun repasse
+  par la politique et par `allow`. D'où la règle : l'appartenance est écrite là où `allow` la lit
+  AVANT d'abonner, sinon le membre est refusé à la première coupure (sur mobile : dans la minute).
+- Il ne rejoue **ni les messages publiés pendant la coupure, ni les requêtes en vol**. Une
+  discussion se reprend par une route (`GET /chat/history?since=<dernier id>`), dédoublonnée sur
+  l'identifiant persistant, triée sur l'identifiant croissant de la base — jamais une horloge.
+- Un canal fermé par le serveur (`realtime:closed`, `ended` ou `evicted`) n'est pas rejoué. Un
+  rechargement de page, si : c'est `allow` qui tranche.
+- `connected` ne veut pas dire abonné : `await socket.whenSubscribed(canal)` avant de charger
+  l'état initial, sinon un événement entre les deux est perdu.
+
+## 3. Garanties — ce que le framework promet, et rien de plus
+
+| Livraison | Ordre                                            | Livraison        | En cas de perte                                                             |
+| --------- | ------------------------------------------------ | ---------------- | --------------------------------------------------------------------------- |
+| socket    | par flux et par émetteur ; jamais entre serveurs | au plus une fois | un trou, jamais un réordonnancement ; client qui ne lit plus fermé (`1013`) |
+| flux SSE  | par flux                                         | au plus une fois | un trou ; la reprise appartient à l'action                                  |
+| bus       | par émetteur                                     | au plus une fois | un trou                                                                     |
+
+Une alarme machine qui ne doit pas se perdre se bâtit **au-dessus** : identifiant dans la charge,
+accusé par une entrée client, réémission par l'application. Le socle ne stocke rien.
+
+## 4. Révocation — une socket survit à sa session
+
+Toutes les 30 s, chaque connexion authentifiée est revalidée. Les codes vivent dans un seul
+registre, exporté par `nodefony` : **compare aux constantes, jamais aux nombres**.
+
+| Code   | Constante                     | Cause                                                                   | Le client                                                     |
+| ------ | ----------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `4001` | `IDENTITY_DEAD_CLOSE_CODE`    | session détruite ou expirée, jeton révoqué                              | s'arrête                                                      |
+| `4003` | `ORIGIN_REFUSED_CLOSE_CODE`   | origine refusée à la poignée de main                                    | s'arrête                                                      |
+| `4005` | `IDENTITY_REFRESH_CLOSE_CODE` | droits changés, identité vivante                                        | revient aussitôt — lis `onIdentity()` pour rafraîchir l'écran |
+| `4006` | `TOKEN_EXPIRED_CLOSE_CODE`    | jeton PORTEUR expiré sur une socket ouverte                             | s'arrête : recrée la socket avec un jeton neuf AVANT `exp`    |
+| `4007` | `BACKPRESSURE_CLOSE_CODE`     | émis par le client : sa file d'envoi ne se vide plus                    | se reconnecte                                                 |
+| `1013` | `TRY_AGAIN_LATER_CLOSE_CODE`  | serveur : client qui ne lit plus, ou authentification trop lente (10 s) | revient, avec recul                                           |
+
+- Un refus à la poignée de main est un **statut HTTP** (401/403) que le navigateur cache : la
+  socket sonde l'adresse en HTTP et traite 401/403/404 comme définitifs. Jamais de `4006` avant
+  authentification.
+- Un membre retiré d'une salle reste abonné tant que sa connexion vit : l'exclusion immédiate, c'est
+  `evictUser` ; la révocation ferme la connexion entière.
+
+## 5. Contre-pression et bornes — une règle, trois endroits
+
+- **Serveur** (`@nodefony/http`, clés `websocket` ET `websocketSecure` — régler l'un ne règle pas
+  l'autre) : `maxBackpressure` 4 MiB, `backpressurePolicy: "drop"` (défaut) ou `"close"`,
+  `backpressureCloseAfterDrops` 1000 → fermeture `1013`. `drop` ne trie pas : une réponse RPC
+  peut partir aussi. Un flux où chaque message compte choisit `close`, ou un accusé applicatif.
+- **Débit entrant** : `maxFramesPerSecond` (défaut `0` = désactivé), fermeture `1008`
+  sur un solde de refus — jamais au premier dépassement (une reconnexion qui rejoue ses
+  abonnements est une rafale légitime). Pour un jeu : `120` et `frameRateCloseAfterRejects: 1000`.
+- **Navigateur** : `maxBufferedAmount` (désactivé par défaut) jette un coup périmé au lieu de
+  l'empiler, compté dans `framesDropped` ; `backpressureCloseAfterDrops` ferme en `4007`.
+- **Cadence adaptative** : un canal d'ÉTAT se demande `base:<ms>` ; le serveur le sert par
+  `createRealtimeChannel` + `parseRate` (`nodefony`), le client par
+  `useNodefonyAdaptiveChannelData`. Jamais sur un canal d'événements.
+- `slowConsumer.bytes` (`@nodefony/realtime`) compte, ne freine pas.
+
+## 6. `allow` sous charge
+
+- Rejeu au redémarrage : N clients × M canaux appels d'`allow` en rafale. Parade : une règle en
+  classe qui lit un registre partagé, ou un cache court côté application.
+- `allowTimeoutMs` 5 s → `unavailable` (le client réessaie seul, 3 fois, gigue complète) ;
+  `maxPendingAllowsPerConnection` 8 (la demande attend son tour) ; `maxPendingAllowsTotal` 512
+  → `unavailable` ; coupe-circuit 50 dépassements en 5 s. Compteurs : `allowTimedOutTotal`,
+  `allowSaturatedTotal`.
+- Un `allow` qui lève = `forbidden` pour tous, sans un mot en production : une règle en classe
+  fait échouer le DÉMARRAGE si sa dépendance manque. Préfère-la dès qu'elle lit la base.
+
+## 7. Lire la sonde avant d'accuser le code
+
+`GET /nodefony/realtime/api/health` (rôle d'administration) ou le canal `nodefony:socket`.
+
+| Signal                                            | Lecture                                                                  |
+| ------------------------------------------------- | ------------------------------------------------------------------------ |
+| `publishTotal` monte, `fanoutTotal` stagne        | tu publies dans le vide : nom de canal différent entre serveur et client |
+| `localOnlyTotal` > 0 sur un canal applicatif      | `@RealtimeBroadcast` oublié                                              |
+| `ingressRejectedTotal`, `sealRejectedTotal`       | quelqu'un d'autre écrit sur le bus, ou rotation du secret en cours       |
+| `backpressure.slowConsumers`, `drops`             | un client ne suit pas ; la protection agit — ce n'est pas une panne      |
+| `allowTimedOutTotal`, `authenticateTimedOutTotal` | la base ne répond plus                                                   |
+| `systemFloorDeniedTotal`                          | un client demande un canal de plateforme sans module de sécurité         |

package/skills/nodefony-browser/SKILL.md

@@ -70,7 +70,10 @@ npx playwright install chromium
 
 `NF_BROWSER_ENGINE=chrome` (ou `msedge`, `chromium`) impose un navigateur précis. Un choix explicite
 n'est **jamais** complété par un repli : se rabattre en silence attribuerait la mesure au mauvais
-moteur. ⚠️ À ne pas confondre avec `NF_BROWSER_CHANNEL`, qui désigne le canal d'un socket
+moteur. `NF_BROWSER_ENGINE=firefox` (ou `webkit`) change de MOTEUR — après
+`npx playwright install firefox` : ce que dicte une norme (sécurité du contenu, rapports de
+violation, cookies) diverge d'un moteur à l'autre, et Chromium seul n'en dit rien. L'audit
+Lighthouse, lui, reste réservé à Chromium. ⚠️ À ne pas confondre avec `NF_BROWSER_CHANNEL`, qui désigne le canal d'un socket
 applicatif — le mot « canal » sert aux deux dans des mondes différents.
 
 ## L'autre voie — en conteneur, et QUAND s'en servir
@@ -182,6 +185,15 @@ Réglages par variables d'environnement : `NF_BROWSER_BASE`, `NF_BROWSER_PAGE`,
 (`libellé=sélecteur`, séparés par des virgules), `NF_BROWSER_FAMILIES`, `NF_BROWSER_WIDTHS`,
 `NF_BROWSER_SEUIL_LOURD`, `NF_BROWSER_SEUIL_LENT`, `NF_BROWSER_ACTIONS`, `NF_BROWSER_FULLPAGE`. Le détail vit dans l'en-tête de chaque script.
 
+**Lire un état que seule ton application connaît** (un store, l'instantané d'une socket) :
+`NF_BROWSER_EVAL` prend une expression évaluée DANS la page après les actions et les mesures, et
+rend son résultat dans le champ `evaluated` — ou `{ error }` si elle lève. Une forme fonction
+(`async () => …`) est appelée, jamais seulement définie.
+
+```bash
+NF_BROWSER_EVAL='() => document.title' node scripts/inspect.mjs /tableau-de-bord
+```
+
 ### Un écran qui n'existe qu'après un GESTE — `NF_BROWSER_ACTIONS`
 
 Certaines pages ne sont pas un état mais un **parcours** : un formulaire qui ne déplie ses questions
@@ -196,7 +208,9 @@ Grammaire : `verbe:cible[=valeur]`, séquence séparée par `|`, verbe facultati
 cible cherchée d'abord comme **texte visible** puis comme sélecteur CSS. Verbes : `clic` · `double`
 · `droit` (clic droit) · `survol` · `saisir:Nom=valeur` · `choisir:Liste=valeur` (une option d'un
 `<select>`, par sa valeur ou son libellé ; la cible peut être le libellé qui l'enveloppe) ·
-`touche:Enter` · `voir` · `defiler:600` · `attendre`.
+`touche:Enter` · `voir` · `defiler:600` · `attendre` · `connecter:` (se connecte dans un
+AUTRE onglet, sans recharger la page mesurée — qui s'ouvre alors anonyme : une page déjà
+ouverte voit-elle la session apparaître ?).
 
 - 🔴 **`voir` plutôt qu'un clic pour amener dans la vue** : sur un formulaire, le texte d'une
   question est un `label` — cliquer dessus coche la case qu'il décrit, et tu observes alors un écran
@@ -381,6 +395,17 @@ 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.
 
+### Voir la trame qu'un GESTE envoie — `NF_BROWSER_ACTIONS`
+
+```bash
+docker exec -e "NF_BROWSER_ACTIONS=Supprimer|Confirmer" mon-app-browser node /app/see-screen/watch.mjs /articles 4000
+```
+
+La même grammaire que pour `inspect.mjs`, jouée une fois la page ouverte, **pendant** l'observation :
+la trame qu'un bouton envoie par la socket est enregistrée comme les autres. C'est la seule façon de
+prouver qu'une écriture passe par la socket. Sans la trame, un client qui se replie sur HTTP en cas
+d'échec affiche le même écran. Une cible introuvable arrête la sonde (code 65).
+
 ### Éprouver la REPRISE après une coupure réseau — `NF_BROWSER_CUT`
 
 ```bash

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/audit.mjs

@@ -41,6 +41,7 @@ import {
   USER,
 } from "./lib/browser.mjs";
 import {
+  browserEngine,
   browserOrder,
   captureSlug,
   colorSchemeLaunchArgs,
@@ -104,6 +105,17 @@ const profile = mkdtempSync(path.join(tmpdir(), "nf-audit-"));
 // seul Chrome est installé — là même où `inspect.mjs` passait.
 let ctx = null;
 const failures = [];
+// Lighthouse parle au navigateur par le protocole de débogage de Chromium :
+// Firefox et WebKit ne l'exposent pas. Refuser en le disant, plutôt que de se
+// rabattre sur Chromium et d'attribuer l'audit au moteur qu'on n'a pas lancé.
+const wanted = (process.env.NF_BROWSER_ENGINE ?? "").trim();
+if (wanted && browserEngine(wanted).engine !== "chromium") {
+  console.error(
+    `L'audit exige un navigateur de la famille Chromium (protocole de débogage) — « ${wanted} » n'en est pas un.\n` +
+      "Pour regarder la page sous ce moteur : inspect.mjs avec le même NF_BROWSER_ENGINE.",
+  );
+  process.exit(64); // EX_USAGE
+}
 for (const channel of browserOrder(process.env.NF_BROWSER_ENGINE)) {
   try {
     ctx = await chromium.launchPersistentContext(profile, {