@nodefony/devkit 10.0.0-beta.5 → 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/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, {

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

@@ -16,7 +16,7 @@
  * `@env` NF_BROWSER_PAGE chemin de la page à ouvrir (défaut /)
  * `@env` NF_BROWSER_EXPECT texte DISCRIMINANT attendu avant de mesurer (défaut : aucun, on mesure après domcontentloaded)
  * `@env` NF_BROWSER_FAMILIES familles de sondes à activer, séparées par des virgules (a11y, axe, rendu, reseau, perf, stockage, responsive — ou « toutes ») ; défaut : aucune, le socle seul
- * `@env` NF_BROWSER_ENGINE navigateur imposé (chromium, chrome, msedge) ; sans lui, le premier qui répond
+ * `@env` NF_BROWSER_ENGINE navigateur imposé (chromium, chrome, msedge, firefox, webkit) ; sans lui, le premier qui répond
  * `@env` NF_BROWSER_COLOR_SCHEME schéma de couleurs émulé (light, dark, no-preference) — un défaut peut n'exister que dans UN thème
  * `@env` NF_BROWSER_STORAGE entrées de stockage local posées AVANT chargement (`clé=valeur`) — pour une application qui MÉMORISE son thème
  * `@env` NF_BROWSER_LOGIN chemin du formulaire de connexion de TON application — requis dès qu'un identifiant est donné, aucun défaut n'est deviné
@@ -34,11 +34,14 @@
  * `@env` NF_BROWSER_PRIMARY sélecteur de l'action principale pour la famille pli (défaut : le plus grand bouton de validation visible)
  * `@env` NF_BROWSER_SEUIL_LOURD bytes au-delà desquels une ressource est « lourde » (défaut 512000)
  * `@env` NF_BROWSER_SEUIL_LENT millisecondes au-delà desquelles une réponse est « lente » (défaut 1000)
+ * `@env` NF_BROWSER_EVAL expression JS évaluée DANS la page après les actions et les mesures (une forme fonction est appelée) ;
+ *                        son résultat sérialisé sort dans `evaluated` — l'état propre à l'application (store, socket)
  * `@requires` conteneur du profil `browser` démarré · serveur joignable depuis le conteneur
  * `@output` un objet JSON sur stdout + une capture PNG horodatée dans /output
  * `@exit` 0 mesure rendue (le verdict est une DONNÉE, pas un code de retour) · 64 usage (famille inconnue, identifiant sans chemin de connexion) · 65 texte attendu jamais apparu
  */
 import { existsSync, readFileSync } from "node:fs";
+import { playActions } from "./lib/actions.mjs";
 import path from "node:path";
 import * as decor from "./lib/browser.mjs";
 import { open, goTo, LOGIN, OUTPUT } from "./lib/browser.mjs";
@@ -48,14 +51,17 @@ import {
   captureSlug,
   parseActions,
   parseFamilies,
+  signsInMidway,
   parseProbes,
   parseWidths,
+  pageExpression,
   summarizeAxe,
   verdictGlobal,
 } from "./lib/probes.mjs";
 
 const PAGE = process.argv[2] ?? process.env.NF_BROWSER_PAGE ?? "/";
 const EXPECT = process.argv[3] ?? process.env.NF_BROWSER_EXPECT ?? "";
+const EVAL = pageExpression(process.env.NF_BROWSER_EVAL);
 /**
  * Ce qu'il faut FAIRE avant de mesurer — une séquence, pas un geste.
  *
@@ -81,6 +87,7 @@ const EXPECT = process.argv[3] ?? process.env.NF_BROWSER_EXPECT ?? "";
  * | `voir`     | amène dans la vue SANS cliquer                            |
  * | `defiler`  | fait défiler de N pixels (`defiler:600`), page ou conteneur |
  * | `attendre` | attend qu'un texte APPARAISSE (après une action lente)    |
+ * | `connecter` | se connecte dans un AUTRE onglet (`connecter:`), sans recharger |
  *
  * 🔴 `voir` existe parce qu'un clic n'est pas neutre : sur un formulaire, le
  * texte d'une question est un `label` — cliquer dessus COCHE la case qu'il
@@ -148,7 +155,9 @@ async function axeSource() {
 
 const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
 
-const { browser, ctx, page, reuse } = await open();
+// `connecter:` dans la séquence ⇒ la page s'ouvre ANONYME (cf signsInMidway).
+const ANONYMOUS = signsInMidway(ACTIONS);
+const { browser, ctx, page, reuse } = await open({ anonymous: ANONYMOUS });
 
 // ── Collecteurs — posés AVANT toute navigation ──────────────────────────────
 const consoleErrors = [];
@@ -230,7 +239,7 @@ if (active.has("reseau")) {
   });
 }
 
-await goTo(page, ctx, PAGE, reuse);
+await goTo(page, ctx, PAGE, reuse, { anonymous: ANONYMOUS });
 
 // Attendre un texte DISCRIMINANT, jamais `networkidle` : une application qui se
 // monte puis demande ses données passe par un état « réseau calme » où l'écran
@@ -259,84 +268,12 @@ if (EXPECT) {
 // toute mesure. Une action qui ne trouve pas sa cible ARRÊTE la sonde : la
 // mesure qui suivrait porterait sur un écran qu'on n'a pas ouvert, et rien ne
 // le dirait.
-for (const { verb, target, value } of ACTIONS) {
-  if (verb === "defiler") {
-    const pixels = Number.parseInt(target, 10);
-    if (!Number.isFinite(pixels)) {
-      console.error(`defiler attend un nombre de pixels, reçu « ${target} »`);
-      await browser.close();
-      process.exit(64); // EX_USAGE
-    }
-    // Le conteneur qui défile RÉELLEMENT, pas la fenêtre : sur une console à
-    // barre latérale fixe, `window.scrollBy` ne bouge rien du tout.
-    await page.evaluate((dy) => {
-      const scrollable = [...document.querySelectorAll("*")].find(
-        (el) => el.scrollHeight > el.clientHeight + 40 && el.clientHeight > 200,
-      );
-      (scrollable ?? window).scrollBy(0, dy);
-    }, pixels);
-    continue;
-  }
-  // Le premier candidat VISIBLE, pas le premier du DOM : un libellé apparaît
-  // souvent d'abord dans un menu replié ou un gabarit caché, et agir là ne fait
-  // rien tout en passant pour un succès.
-  const candidates = page.getByText(target, { exact: false });
-  let locator = null;
-  const total = await candidates.count();
-  for (let i = 0; i < total; i += 1) {
-    const c = candidates.nth(i);
-    if (await c.isVisible().catch(() => false)) {
-      locator = c;
-      break;
-    }
-  }
-  // Aucun candidat visible À CET INSTANT ne dit pas que la cible est un
-  // sélecteur : juste après un clic qui navigue, la page suivante n'est pas
-  // encore rendue. On attend donc le texte OU le sélecteur — et le texte seul
-  // quand la cible n'est pas du CSS valide. Trancher sur l'instant faisait
-  // chercher une balise `<FreeOTP>` une fois sur trois.
-  if (locator === null) {
-    // Une navigation en vol détruirait le contexte de l'évaluation ci-dessous.
-    await page.waitForLoadState("domcontentloaded").catch(() => {});
-    const isCss = await page
-      .evaluate((s) => {
-        try {
-          document.querySelector(s);
-          return true;
-        } catch {
-          return false;
-        }
-      }, target)
-      .catch(() => false);
-    locator = isCss
-      ? candidates.or(page.locator(target)).first()
-      : candidates.first();
-  }
-  try {
-    await locator.waitFor({ timeout: 15000 });
-    if (verb === "clic") await locator.click();
-    else if (verb === "double") await locator.dblclick();
-    else if (verb === "droit") await locator.click({ button: "right" });
-    else if (verb === "survol") await locator.hover();
-    else if (verb === "saisir") await locator.fill(value);
-    // `choisir` : la cible peut être le `<label>` qui ENVELOPPE la liste —
-    // Playwright reporte alors le choix sur son contrôle. La valeur est celle
-    // de l'option (`value`), sinon son libellé.
-    else if (verb === "choisir") {
-      const chosen = await locator.selectOption(value);
-      if (chosen.length === 0) throw new Error(`option « ${value} » absente`);
-    } else if (verb === "touche") await locator.press(value || "Enter");
-    else if (verb === "voir") await locator.scrollIntoViewIfNeeded();
-    // `attendre` : le `waitFor` ci-dessus EST l'action.
-  } catch {
-    console.error(
-      `Action « ${verb}:${target} » impossible\n` +
-        `Page réellement ouverte : ${page.url()}\n` +
-        "→ le libellé a changé, l'élément n'est pas encore rendu, ou il faut " +
-        "agir sur autre chose avant lui (NF_BROWSER_ACTIONS accepte une séquence, séparée par « | »).",
-    );
+{
+  const failed = await playActions(page, ACTIONS);
+  if (failed !== null) {
+    console.error(failed.message);
     await browser.close();
-    process.exit(65); // EX_DATAERR
+    process.exit(failed.code);
   }
 }
 
@@ -998,12 +935,34 @@ if (active.has("pli")) {
   }, primarySelector);
 }
 
+// ── Lire un ÉTAT de l'application — `NF_BROWSER_EVAL` ───────────────────────
+// Ce qu'aucune famille ne mesure parce que c'est propre à l'application : l'état
+// d'un store, l'instantané d'une socket, une valeur calculée par la page. Évalué
+// APRÈS les actions et les mesures, sur l'écran qu'on décrit. Une expression qui
+// lève rend son erreur, jamais un champ absent : un « rien » se lirait comme
+// « la page n'a pas cet état ».
+if (EVAL) {
+  try {
+    measured.evaluated = await page.evaluate(EVAL);
+  } catch (e) {
+    measured.evaluated = { error: String(e).slice(0, 300) };
+  }
+}
+
 // ── Capture — AVANT la famille responsive, qui déforme le viewport ──────────
 const slug = captureSlug(PAGE);
 const shot = path.join(OUTPUT, `${slug}-${stamp}.png`);
 // `NF_BROWSER_FULLPAGE=1` : la page ENTIÈRE, pas la fenêtre. Un formulaire long
 // (ou une page qu'on vient de déplier) a l'essentiel SOUS la ligne de flottaison
 // — la capture par défaut laisse alors conclure « ce n'est pas là ».
+//
+// La console se FIGE avant la capture : sous WebKit, le pilote injecte un
+// `<style>` pour capturer, et une politique de sécurité du contenu stricte le
+// refuse. Ce refus appartient à l'instrument, pas à la page — compté, il ferait
+// accuser l'application d'une violation qu'elle ne commet pas. (Le rapport, lui,
+// part quand même vers le serveur : une collecte de rapports sous WebKit doit
+// écarter les `style-src-elem` `inline` émis à l'instant de la capture.)
+const consoleFrozen = consoleErrors.slice();
 await page.screenshot({
   path: shot,
   fullPage: process.env.NF_BROWSER_FULLPAGE === "1",
@@ -1071,7 +1030,7 @@ console.log(
       // L'écran mesuré : une proportion sans son écran ne conclut rien.
       viewport: `${decor.VIEWPORT.name}${decor.VIEWPORT.mobile ? " (téléphone)" : ""}`,
       ...measured,
-      consoleErrors,
+      consoleErrors: consoleFrozen,
       uncaughtErrors,
       // Le chemin RENDU est celui où l'appelant trouvera l'image. Dans un
       // conteneur, `/output` est un volume monté et ne veut rien dire au