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

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

@@ -0,0 +1,22 @@
+# Un contrat, déclaré UNE fois — typer les deux bouts
+
+> Chargé depuis `SKILL.md` §9 dès que navigateur et serveur échangent plus qu'un canal. Règle
+> complète : `node_modules/@nodefony/realtime/docs/actions.md` (« Un contrat pour les deux bouts »).
+
+Dès que navigateur et serveur échangent plus qu'un canal : sans contrat, une méthode oubliée
+compile puis rend `-32601`. Le contrat est une **interface de types seuls** (0 octet compilé),
+dans un fichier partagé que les deux côtés importent :
+
+| Clé de `IRealtimeContract` | Ce qu'elle type                                       | Servie côté serveur par                                                |
+| -------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------- |
+| `serverToClient`           | ce que les canaux publient (gabarit `user:${string}`) | `getRealtimeHub<C>().publish`, `publishToUser`                         |
+| `clientToServer`           | ce que le client pousse (`emit`)                      | les entrées                                                            |
+| `serverMethods`            | les actions `{ in, out }`                             | la table `realtimeActions()` (une oubliée ne compile pas)              |
+| `serverRoutes`             | les routes du pont `"VERBE /chemin"`                  | `static readonly serverRoutes = {…} satisfies ContractRouteSchemas<C>` |
+
+- Navigateur : `NodefonySocket.fromContract<C>({ url })` ; serveur :
+  `extends ContractRealtimeController<C>` ; politiques par `@RealtimePolicy` sur la classe (un nom
+  hors contrat ne compile pas) — n'ajoute pas `@RealtimeAction` à une méthode de la table.
+- Une `Date` arrive en `string` : le contrat lit le type à travers JSON.
+- **Le type n'est pas une validation** : la politique et le schéma de route restent les gardes.
+- Le contrat complet du chat : `chatContract.ts` de la démo ; la règle : `actions.md` (contrat).

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

@@ -0,0 +1,140 @@
+# Ce qui ne se voit qu'en production — plusieurs serveurs, réseau, révocation, charge
+
+> Chargé depuis `SKILL.md` §7. 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.
+- **La présence d'un canal suit la même déclaration** : sans `@RealtimeBroadcast`, chaque serveur ne
+  voit que SES présents (skill `nodefony-add-realtime-presence`).
+- **Les noms de canaux sont un espace PLAT, partagé par tous les modules du processus** : préfixe
+  les tiens par ton module ou ton domaine (`chat:`, `billing:`). `nodefony:` est réservé au
+  framework, et les suffixes `:health` / `:stats` sont réservés à l'administration dans TOUT espace
+  de noms (refusés sans `ROLE_NODEFONY_ADMIN`).
+- 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                                           |
+| `1001` | — (code WebSocket standard)   | le serveur s'arrête proprement (redéploiement, `SIGTERM`)               | se reconnecte seul, sans alerte, et rejoue ses abonnements    |
+
+- **Redéploiement** : l'arrêt se fait en deux temps — le trafic s'écoule, puis le temps réel se
+  libère (la présence annonce le départ du serveur) et les sockets ferment en `1001`. Rien à écrire
+  côté client ; un écran qui veut afficher « reconnexion… » lit `socket.onState`.
+
+- 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. Une socket sur une autre origine que la page
+
+La politique de sécurité de contenu par défaut n'autorise que la même origine (`connect-src 'self'`,
+qui couvre `wss:` sur la même machine). Socket servie ailleurs (sous-domaine, passerelle) : déclare
+`publicOrigin` dans la config de `@nodefony/realtime` — l'origine s'ajoute SEULE à `connect-src`.
+N'élargis jamais la politique à la main (`connect-src *`). Détail : `configuration.md`, clé
+`publicOrigin`.
+
+## 8. 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-add-realtime-presence/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: nodefony-add-realtime-presence
+metadata:
+  version: 1.2.0
+description: >
+  Affiche qui est là sur un canal temps réel Nodefony — qui est en ligne dans un salon, combien de
+  spectateurs, dans combien d'onglets — par l'option de présence que le framework tient lui-même,
+  au lieu d'une liste de connectés écrite à la main qui ment dès deux serveurs. Mène de la ligne
+  à déclarer à l'écran (React, Vue, Angular, Svelte) et à son test, et porte ce qui ne se voit
+  qu'en production : plusieurs serveurs, rechargement de page, redéploiement, salon de mille
+  personnes. À charger AVANT d'écrire une liste de présents, un compteur de spectateurs ou un
+  indicateur « en ligne ». Le canal lui-même (le créer, le protéger) relève de
+  `nodefony-add-realtime-channel`.
+  Déclencheurs : "qui est en ligne ?", "afficher les connectés", "liste des présents",
+  "combien de spectateurs", "indicateur en ligne", "statut en ligne", "Untel est en train
+  d'écrire", "la liste clignote quand je recharge", "les présents ne sont pas les mêmes sur deux
+  serveurs", "présence", "presence", "onPresence", "useNodefonyPresence".
+---
+
+# add-realtime-presence — qui est là, sans rien tenir soi-même
+
+> 🧭 **Arrivé ici directement ? Charge aussi `nodefony-dev`** (la conduite commune) et
+> `nodefony-add-realtime-channel` (le canal qui porte la présence). Cette page ne couvre QUE la
+> présence.
+>
+> Les pages de référence sont INSTALLÉES. Une commande les trouve — **exécute-la, puis lis la page** :
+>
+> ```bash
+> node node_modules/@nodefony/devkit/skills/nodefony-dev/scripts/docs.mjs --open cookbook-chat
+> ```
+>
+> La présence y est l'**étape 3** (« présence et frappe en cours »), le passage à plusieurs serveurs
+> l'**étape 7**. Exemple exécuté : `cas-d-usage.md`, cas `chatPresence`.
+
+> **Maintenance** : vérité courante, jamais un journal. Éditer en place ; historique = `git log`.
+> Chaque bloc de code ci-dessous est un EXTRAIT d'un fichier exécuté par la suite du framework
+> (marqueur `excerpt`) : un test refuse qu'il en diverge.
+
+## 1. Quand m'utiliser — et quand ce n'est pas de la présence
+
+| Tu veux…                                                  | C'est…                                                                   | Où                              |
+| --------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------- |
+| savoir qui est dans le salon, combien, dans quels onglets | **la présence** — une option du canal                                    | ici                             |
+| « Untel est en train d'écrire »                           | un **message éphémère** du canal, PAS la présence (§5)                   | ici, §5                         |
+| savoir si un message a été lu                             | une donnée de l'application (base + route), pas la présence              | `nodefony-add-crud`             |
+| qui a le droit d'entrer                                   | la **politique** du canal (`allow`, `roles`) — la présence ne garde rien | `nodefony-add-realtime-channel` |
+| les inscrits d'un salon (même absents)                    | une table de l'application ; la présence ne connaît que les connectés    | `nodefony-add-crud`             |
+| prévenir une personne précise                             | `publishToUser` (canal personnel)                                        | `nodefony-add-realtime-channel` |
+
+**N'écris jamais de liste de connectés à la main** (un `Set` rempli à l'abonnement, publié toutes
+les N secondes) : chaque serveur ne connaît que SES connexions — derrière `nodefony cluster -w 2`
+ou deux pods, chacun publie sa liste et écrase celle de l'autre, et les départs arrivent avec N
+secondes de retard. Celle du framework est tenue entre les serveurs, groupée par fenêtre de 250 ms,
+sans minuteur par présent.
+
+🔴 **Le geste complet a TROIS morceaux — « afficher qui est en ligne » n'est pas fini sans le
+troisième :**
+
+1. **le canal déclare la présence** (§2) — côté serveur, une option ;
+2. **le canal est diffusé** (`@RealtimeBroadcast`, §7) dès qu'il y a plus d'un serveur ;
+3. **l'ÉCRAN lit la présence** (§3) — c'est lui que l'utilisateur voit. Un serveur qui tient la
+   liste sans page qui l'affiche ne montre rien à personne. L'application n'a pas encore de front ?
+   `npx nodefony create front <nom> --frontend react` (ou `vue`, `angular`, `svelte`) livre une page
+   déjà branchée au temps réel ; ajoute-y la liaison du §3. Le test (§10) lit ce que cet écran
+   afficherait.
+
+## 2. La ligne — une option de la politique du canal
+
+Être abonné, c'est être présent. La présence se déclare **sur le canal lui-même** :
+
+<!-- excerpt: chatPresence.ts -->
+
+```ts
+  // La présence est portée PAR le canal : être abonné, c'est être présent. Ni
+  // minuteur, ni liste à tenir, ni second canal — et elle reste juste quand
+  // l'application tourne sur plusieurs pods (étape 7).
+  @RealtimeChannel(ROOM_CHANNEL, { presence: true })
+  room(): () => void {
+    return () => {};
+  }
+```
+
+Le framework tient la liste, l'envoie ENTIÈRE à chaque abonné qui arrive, puis n'envoie que les
+changements. Une connexion fermée sort de la liste aussitôt (au plus une fenêtre de 250 ms).
+
+Avec une **famille de salons privés** et une **grâce** — la forme du chat de la démo :
+
+<!-- excerpt: demo/server/nodefony/controllers/ChatController.ts.tpl -->
+
+```ts
+  @RealtimeChannel(ROOM_CHANNEL_PATTERN, {
+    allow: RoomAdmission,
+    anonymous: true,
+    presence: { grace: PRESENCE_GRACE_MS },
+  })
+  room(): () => void {
+    return () => {};
+  }
+```
+
+La présence suit l'**admission** : seul un abonné admis par `allow` figure dans la liste. Elle ne
+remplace donc jamais la politique — un canal à présence sans politique montre ses présents à tout
+le monde.
+
+| Option     | Défaut | Effet                                                                                                                                                         |
+| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `true`     | —      | présence exacte : un départ est annoncé tout de suite                                                                                                         |
+| `grace`    | `0`    | ms d'attente avant d'annoncer un départ ; annulé si la même identité revient (rechargement de page, redéploiement). Un chat : quelques secondes. Un jeu : `0` |
+| `maxNamed` | `1000` | au-delà, la trame vers le navigateur ne porte plus que les NOMBRES ; la liste revient sous `maxNamed − maxNamed/10` (pas de bascule en boucle à 999 ↔ 1000)   |
+
+Toute autre clé refuse le démarrage. `presence` est refusée sur un canal de la plateforme
+(`nodefony:`) et sur la politique d'une **écriture** (`@RealtimeInbound`) : elle n'y a pas de sens.
+
+## 3. Lire côté navigateur
+
+`onPresence` rappelle l'écran avec **la vue entière** à chaque changement : rien à fusionner soi-même.
+
+<!-- excerpt: chatPresence.client.ts -->
+
+```ts
+/** Qui est là : rappelé à chaque changement, la vue entière à chaque fois. */
+export function watchPresence(render: (line: string) => void): () => void {
+  const off = socket.onPresence(ROOM, (p) => {
+    if (!p.ready) return; // « pas encore reçu » n'est pas « vide »
+    const names = [...p.members.keys()].join(", ");
+    const total = p.count + p.unnamed; // nommés (comptes) + connexions anonymes
+    render(`${total} présent(s)${names === "" ? "" : ` : ${names}`}`);
+  });
+  socket.subscribe(ROOM);
+  return () => {
+    off();
+    socket.unsubscribe(ROOM);
+  };
+}
+```
+
+| Champ     | Ce qu'il dit                                                                                                |
+| --------- | ----------------------------------------------------------------------------------------------------------- |
+| `ready`   | `false` tant que la première liste n'est pas arrivée — n'affiche pas « personne » avant                     |
+| `count`   | présents **nommés** : un par compte, quel que soit son nombre d'onglets                                     |
+| `unnamed` | connexions comptées **sans nom** : anonymes, appelants machine sans compte                                  |
+| `members` | `Map` identité → `{ tabs }` : qui, et dans combien d'onglets                                                |
+| `partial` | `true` quand la vue est figée ou incomplète (socket coupée, serveur injoignable) : grise-la, ne la vide pas |
+
+La présence s'abonne avec le canal : sans `subscribe`, aucune trame n'arrive. Avant la première,
+l'instantané vaut `EMPTY_PRESENCE` (`nodefony/client`), `ready: false`.
+
+| Vue        | Liaison                                                                                             | Import             |
+| ---------- | --------------------------------------------------------------------------------------------------- | ------------------ |
+| React      | `useNodefonyPresence(socket, "canal")`, ou `useNodefonyPresence("canal")` sous `<NodefonyProvider>` | `nodefony/react`   |
+| Vue        | `useNodefonyPresence(socket, "canal")`                                                              | `nodefony/vue`     |
+| Angular    | `injectNodefonyPresence(socket, "canal")`                                                           | `nodefony/angular` |
+| Svelte     | `nodefonyPresence(socket, "canal")`                                                                 | `nodefony/svelte`  |
+| sans cadre | `socket.onPresence(canal, h)`, `socket.presence(canal)`, socle `observePresence`                    | `nodefony/client`  |
+
+Chaque liaison rend le même instantané et se désabonne au démontage du composant.
+
+**La présence donne des IDENTITÉS, jamais des noms affichables.** L'écran résout identité → nom par
+une route de l'application. Le chat de la démo appelle son annuaire à chaque changement :
+
+<!-- excerpt: demo/front/frontend/src/chat/useChat.ts.tpl -->
+
+```ts
+      // Qui est là : la vue du salon, puis les noms demandés à l'annuaire.
+      socket.onPresence(channel, (snapshot) => {
+        setPresence(snapshot);
+        roster.observe(snapshot.members, snapshot.partial, Date.now());
+        draw();
+        askNames();
+        scheduleMembers();
+      }),
+```
+
+Se retirer soi-même de la liste : filtrer sur l'identité de l'onglet (`socket.onIdentity`).
+
+## 4. Qui est nommé — ce que le serveur a vérifié, jamais ce que le client affirme
+
+- **Nommé = un compte** (identité `account === true`). Un anonyme et un appelant machine sans
+  compte sont comptés dans `unnamed`, jamais nommés : la présence ne publie ni fournisseur
+  d'identité, ni sujet externe.
+- Un pseudo envoyé par le client (« je suis Alice ») ne nomme personne. Sur une application sans
+  connexion, tout le monde est `unnamed` — c'est attendu, pas un défaut.
+- Un compte dans trois onglets compte **une** fois, avec `tabs: 3`.
+- **La présence PUBLIE les identifiants de compte à tout abonné admis**, anonymes compris sur un
+  salon public : l'identifiant d'un compte ne doit donc jamais être une donnée personnelle (adresse
+  électronique, login réattribuable). Reconnais « soi » par cet identifiant (`socket.onIdentity`),
+  pas par un nom affiché.
+- **Savoir qui est en ligne SANS le publier** : `presence: { maxNamed: 0 }`. Les abonnés ne
+  reçoivent que des NOMBRES ; le serveur lit toujours les identités
+  (`getRealtimeHub().presence(canal)?.members`) et n'en rend que ce qu'une route autorise. La démo
+  s'en sert pour son canal `chat:online` : seuls les membres d'un salon privé apprennent si les
+  autres sont dans le salon, en ligne ailleurs ou absents (`RoomService.members`).
+
+Le test qui le prouve lit la présence côté serveur :
+
+<!-- excerpt: chatPresence.test.ts -->
+
+```ts
+it("se déclarer « bob » ne nomme personne : seul un compte est nommé", async () => {
+  const guest = await connect();
+  await guest.subscribe(ROOM_CHANNEL);
+  await guest.notify("chat:typing", { author: "bob" });
+  await flush();
+  expect(getRealtimeHub().presence(ROOM_CHANNEL)).toMatchObject({
+    count: 0,
+    unnamed: 1,
+  });
+});
+```
+
+## 5. « En train d'écrire » n'est PAS de la présence
+
+Un état de présence DURE ; la frappe est un **message éphémère du canal**, que chacun reçoit parce
+qu'il y est abonné, et que l'écran efface seul. La faire passer par la présence renverrait la liste
+entière à tout le salon à chaque frappe. Le service de la démo publie la frappe sur le canal du
+salon — elle suit donc ses droits, et un salon privé ne fuit pas sa frappe :
+
+<!-- excerpt: demo/server/nodefony/service/ChatService.ts.tpl -->
+
+```ts
+  /**
+   * « Untel écrit… » dans un salon : un message ÉPHÉMÈRE du canal, ni gardé ni
+   * compté — il suit donc les droits du salon (un salon privé ne fuit pas sa
+   * frappe), ce qu'un canal de frappe commun à tous ne ferait pas.
+   */
+  typing(roomId: string, author: string): void {
+    publishFrame(roomId, { kind: "typing", author });
+  }
+```
+
+Côté navigateur, envoie le signal au plus toutes les deux secondes, et efface l'indication ~3 s
+après la dernière réception. Le geste qui le PORTE jusqu'au serveur — une route (contrôle
+d'admission par salon, comme la démo) ou une entrée de canal (`@RealtimeInbound`, comme le
+cookbook) — se choisit par la règle « route ou entrée ? » de `nodefony-add-realtime-channel`.
+
+## 6. Lire côté serveur — l'observateur qui ne figure pas
+
+`getRealtimeHub().presence(canal)` rend `{ count, unnamed, members, partial }` telle que CE serveur
+la connaît (présents des autres serveurs compris), ou `null` si la politique du canal ne déclare pas
+la présence. Une copie à chaque appel : chemin froid, pas une boucle de jeu. C'est la voie d'un
+modérateur ou d'un tableau de bord qui lit sans apparaître dans la liste, et celle d'un test (§4 en montre un).
+
+## 7. Plusieurs serveurs — UNE condition, puis rien à écrire
+
+🔴 **La présence ne traverse les serveurs que si le canal est DIFFUSÉ** : `@RealtimeBroadcast("chat:")`
+sur la classe du contrôleur, et un bus (`backplane.driver: "cluster"` sur une machine, `"redis"`
+entre pods). Sans la déclaration, chaque serveur ne voit QUE ses propres présents — la liste diffère
+selon le serveur où tombe l'onglet, sans une erreur. Le préfixe diffusé couvre aussi les messages
+et la frappe du canal.
+
+Ensuite, rien à écrire : la liste entière part aux nouveaux venus, les changements entre serveurs
+sont groupés, un serveur gelé ou coupé du bus est oublié puis réparé, et une vue incomplète arrive
+avec `partial: true`.
+
+| Situation                                                     | Ce qui se passe                                                                                                                                                                           |
+| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| page rechargée                                                | départ puis retour : invisible avec `grace`, un clignotement sans                                                                                                                         |
+| seul utilisateur d'un serveur qui recharge                    | la présence reste servie aux autres pendant `grace` : pas de clignotement chez eux                                                                                                        |
+| redéploiement (arrêt propre du serveur)                       | le serveur annonce son départ : ses présents disparaissent chez les autres dans la fenêtre, sans attendre l'oubli ; les clients reconnectés ailleurs reviennent, `grace` lisse le passage |
+| bus fourni par l'application (`realtimeBackplane`)            | la fin est émise, mais arrêter CE bus reste à l'application : `shutdownRealtime` (`@nodefony/realtime`)                                                                                   |
+| deux déploiements de la même application sur un Redis partagé | `backplane.namespace` distinct, sinon les présences se mélangent                                                                                                                          |
+
+## 8. Ce que la présence coûte — et ne coûte pas
+
+- **Un canal sans `presence` ne coûte rien** : ni message, ni minuteur, ni structure.
+- Au plus **5 trames de présence par seconde** par client et par canal (fenêtre de 250 ms).
+- Le bus au repos est indépendant du nombre de canaux (une preuve de vie par serveur, ~260 octets).
+- Mesuré au banc du framework : ~1,8 Ko/s par client pour un salon de 1 000 membres et 30
+  mouvements par seconde ; ~75 octets de mémoire par présent d'un autre serveur.
+- Un salon de spectateurs (des milliers) : garde le défaut `maxNamed`, affiche `count + unnamed`.
+
+## 9. Ce que la présence n'est PAS — ne lui fais pas porter ça
+
+- **Pas une autorisation** : elle montre qui a été admis, c'est `allow` / `roles` qui admettent.
+- **Pas instantanée** : cohérente à une fenêtre près, réparée par resynchronisation. N'en déduis
+  jamais un droit (« il est présent, donc je lui envoie le secret »).
+- **Pas un état** : en 10.0, aucun état (micro, caméra, absent) ne se pose sur un présent ; le
+  champ `states` est réservé à un ajout futur. Un état applicatif passe par un message du canal.
+- **Pas la raison d'un départ** : quitté, exclu, panne — non publié. L'exclusion se lit côté
+  exclu (`realtime:closed { reason: "evicted" }`).
+- **Pas les membres d'un salon** : `members` désigne les connectés. Les inscrits vivent en base.
+
+## 10. Prouver
+
+Le harnais de `@nodefony/realtime/testing` joue des connexions réelles contre le contrôleur ; le
+test lit ce que **l'écran** de chacune afficherait, avec la même vue que le navigateur
+(`PresenceView`, `isPresenceFrame` de `nodefony`) :
+
+<!-- excerpt: chatPresence.test.ts -->
+
+```ts
+/** Ce que l'écran de cette connexion affiche : ses trames de présence, appliquées comme le fait le navigateur. */
+function screenOf(h: IRealtimeHarness<ChatController>): IPresenceSnapshot {
+  const view = new PresenceView(ROOM_CHANNEL);
+  for (const frame of h.received) {
+    if (
+      frame.method === REALTIME_PRESENCE_METHOD &&
+      isPresenceFrame(frame.params)
+    )
+      view.apply(frame.params);
+  }
+  return view.snapshot();
+}
+
+/** Attendre un FAIT, borné : les changements partent groupés, par fenêtre de 250 ms. */
+async function until(fact: () => boolean): Promise<void> {
+  for (let i = 0; i < 100 && !fact(); i++)
+    await new Promise((r) => setTimeout(r, 25));
+  expect(fact()).toBe(true);
+}
+```
+
+- **Attends un fait, jamais une durée** : `until(() => screenOf(alice).members.has("bob"))`, pas un
+  `setTimeout(300)` — les changements partent par fenêtre, une durée fixe rend le test instable.
+- Prouve le **départ** (connexion fermée → absent chez le serveur PUIS sur l'écran des autres) et
+  l'**anonyme compté sans nom** — le test complet est dans `cas-d-usage.md`, cas `chatPresence`.
+- **Vois-le rouge une fois** : retire `presence` de la politique, `screenOf(...).ready` reste `false`.
+- Plusieurs serveurs ne se prouvent pas avec un seul processus : deux onglets sur un serveur ne
+  disent rien de la diffusion. `cookbook-chat.md` étape 7 donne le montage.
+
+## 11. Voisins
+
+| Besoin                                                        | Skill                           |
+| ------------------------------------------------------------- | ------------------------------- |
+| Créer, protéger, diffuser le canal ; route ou entrée de canal | `nodefony-add-realtime-channel` |
+| La table des inscrits, l'annuaire des noms                    | `nodefony-add-crud`             |
+| Voir l'écran, lire les trames depuis la page                  | `nodefony-browser`              |
+| La liste ne bouge plus, un serveur ne voit pas les autres     | `nodefony-troubleshoot`         |

package/skills/nodefony-authentication/SKILL.md

@@ -215,8 +215,8 @@ preuve à chaque appel, `Authorization: Bearer …`.
 
 ❌ 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
-en silence. La zone qui reçoit ces preuves (`machine`, `partner`, `stateless: true`) et la
-commande qui l'éprouve (`app:partner:call`) → skill `nodefony-protect-route`. Détail :
+en silence. La zone qui reçoit ces preuves (`stateless: true`) → skill `nodefony-protect-route` ;
+une application née avec `--demo` en porte une qui marche (`demo:partner:call`). Détail :
 `node_modules/@nodefony/security/docs/api-keys.md`, `obtenir-un-jeton.md`.
 
 ## 12. Prouver que c'est fait

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,11 +208,19 @@ 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`.
+`deposer:input[type=file]=chemin` (joint un fichier, comme la boîte du système ; le champ peut être
+caché derrière un bouton) · `touche:Enter` · `voir` · `defiler:600` · `molette: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
   que l'observation a modifié.
+- **`molette` n'est pas `defiler`** : `defiler` appelle `scrollBy` sur un conteneur
+  choisi ; `molette:N` envoie une VRAIE molette là où est le pointeur (`survol:` avant).
+  C'est le navigateur qui décide alors quoi faire défiler — seule façon de constater
+  qu'une zone qui défile rend la main à la page une fois en bout. Un geste reste
+  « accroché » au conteneur où il a commencé : enchaîner plusieurs `survol|molette`.
 - ⚠️ **`defiler` n'est pas `NF_BROWSER_FULLPAGE=1`** : une application dont le contenu défile dans
   un conteneur interne (toute interface à barre latérale fixe) ne grandit pas — la capture « page
   entière » y rend exactement la fenêtre, et l'on croit que ce qui est plus bas n'existe pas.
@@ -236,6 +256,10 @@ que soit ta trousse d'interface. Valeurs : `light`, `dark`, `no-preference` ; to
 Si ton application **mémorise** le choix de l'utilisateur, elle n'obéit plus à cette média query :
 donne alors la clé de stockage, qui t'appartient — le code ne la devine pas.
 
+`NF_BROWSER_REDUCED_MOTION=reduce` émule `prefers-reduced-motion` : une page dont les sections
+apparaissent en fondu au défilement se mesure alors au repos, au lieu de rendre des contrastes
+de textes à demi transparents (détail : `references/sondes.md`, famille `axe`).
+
 ```bash
 NF_BROWSER_STORAGE="ma-cle-de-theme=light" node .../scripts/inspect.mjs /
 ```
@@ -381,6 +405,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

@@ -79,6 +79,12 @@ le moteur qu'embarque Lighthouse pour son volet accessibilité.
   **41 faux positifs** masquant **7 défauts réels**, dont celui qu'on cherchait — à cause de trois
   cas particuliers (échelle des couleurs modernes, alpha non composé, emoji peints par une police en
   couleurs) qu'on ne devine pas avant de les avoir vus.
+- **Une page qui ANIME son contenu au défilement trompe le contraste.** Un fondu lié à
+  `animation-timeline: view()` laisse les sections hors de la vue à demi transparentes : `axe` y
+  mesure un texte que personne ne lit dans cet état, et rend des rouges identiques sur des éléments
+  sans rapport (même rapport partout, 2,67:1 par exemple). Rejouer avec
+  `NF_BROWSER_REDUCED_MOTION=reduce` : si la page respecte la préférence, la mesure porte sur le
+  texte au repos — et un rouge qui survit est un vrai défaut.
 - **Quand elle est indisponible** : `axe-core` vit dans les dépendances du projet. En conteneur, il
   faut le copier à part. La famille rend alors `verdict: "INDISPONIBLE"` et la commande à taper —
   jamais un `OK` qui n'a rien mesuré.
@@ -166,6 +172,19 @@ jeton de session imprimé dans une sortie de sonde finit dans un terminal, un lo
 l'empreinte mémoire, pas la taille « à l'écran » ; et un cookie `httpOnly: false` n'est pas signalé
 comme alerte alors qu'il mérite un regard si sa valeur est sensible.
 
+## `notifications` — ce que la page a levé
+
+Le navigateur piloté n'affiche aucune notification : une notification réussie et une notification
+jamais levée s'y ressemblent. La famille accorde la permission `notifications` d'avance (aucune
+boîte de dialogue) et relève chaque `new Notification(titre, options)` — titre, corps, étiquette —
+puis la crée pour de vrai. `LEVÉES` / `AUCUNE` est une **donnée** : aucune notification peut être
+le bon résultat, si la personne était là.
+
+Une page qui ne notifie qu'en l'**absence** de la personne (onglet caché, autre application au
+premier plan) se mesure avec `NF_BROWSER_AWAY=1` : la fenêtre pilotée, elle, est toujours au
+premier plan. Le message déclencheur part d'un AUTRE client pendant que la sonde attend
+(`attendre:<texte>`).
+
 ## `responsive` — la même page à plusieurs largeurs
 
 Rejoue la mesure de débordement horizontal à chaque largeur de `NF_BROWSER_WIDTHS` (défaut