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

@@ -1,6 +1,6 @@
 # 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 :
+> 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`,
@@ -22,6 +22,12 @@ décrit SON serveur, il ne doit pas traverser. Le framework diffuse `user:` lui-
 
 - 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
@@ -73,6 +79,11 @@ registre, exporté par `nodefony` : **compare aux constantes, jamais aux nombres
 | `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
@@ -107,7 +118,15 @@ registre, exporté par `nodefony` : **compare aux constantes, jamais aux nombres
 - 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
+## 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`.
 

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

@@ -208,13 +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` · `connecter:` (se connecte dans un
+`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.
@@ -250,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 /
 ```

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

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

@@ -45,6 +45,7 @@ import {
   browserOrder,
   captureSlug,
   colorSchemeLaunchArgs,
+  stampedName,
   summarizeLighthouse,
 } from "./lib/probes.mjs";
 
@@ -206,9 +207,11 @@ try {
   // Le rapport COMPLET est conservé : le résumé sert à décider, l'original à
   // vérifier — et à comparer dans le temps.
   mkdirSync(OUTPUT, { recursive: true });
-  const stamp = new Date().toISOString().replace(/[:.]/gu, "-").slice(0, 19);
   const slug = captureSlug(PAGE);
-  const fullPath = path.join(OUTPUT, `lighthouse-${slug}-${stamp}.json`);
+  const fullPath = path.join(
+    OUTPUT,
+    stampedName(`lighthouse-${slug}`, new Date(), process.pid, "json"),
+  );
   writeFileSync(fullPath, JSON.stringify(lhr), "utf8");
 
   console.log(

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

@@ -15,16 +15,18 @@
  * `@env` NF_BROWSER_OUT dossier des captures et de l'état d'authentification (défaut constaté de la même façon)
  * `@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_FAMILIES familles de sondes à activer, séparées par des virgules (a11y, axe, rendu, reseau, perf, stockage, responsive, pli, notifications — ou « toutes ») ; défaut : aucune, le socle seul
+ * `@env` NF_BROWSER_AWAY `1` : la page se croit AILLEURS (onglet caché, autre application au premier plan) — pour mesurer ce qu'elle ne fait qu'en l'absence de la personne
  * `@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_REDUCED_MOTION préférence de mouvement émulée (reduce, no-preference) — `reduce` mesure au repos une page à fondus au défilement
  * `@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é
  * `@env` NF_BROWSER_USER identifiant de connexion ; si absent, aucune authentification n'est tentée
  * `@env` NF_BROWSER_PASSWORD mot de passe associé
  * `@env` NF_BROWSER_ACTIONS séquence d'interactions AVANT mesure, séparées par `|` —
  *                        `verbe:cible[=valeur]` : clic (défaut), double, droit, survol,
- *                        saisir, choisir, touche, voir, defiler, attendre. Un écran qui se déplie
+ *                        saisir, choisir, deposer, touche, voir, defiler, molette, attendre. Un écran qui se déplie
  *                        au clic n'existe pas tant qu'on ne l'a pas ouvert.
  * `@env` NF_BROWSER_FULLPAGE 1 = capture la page ENTIÈRE (défaut : la fenêtre)
  * `@env` NF_BROWSER_PROBES sélecteurs CSS à sonder, séparés par des virgules (`libellé=sélecteur`) ;
@@ -53,6 +55,7 @@ import {
   parseFamilies,
   signsInMidway,
   parseProbes,
+  stampedName,
   parseWidths,
   pageExpression,
   summarizeAxe,
@@ -83,9 +86,11 @@ const EVAL = pageExpression(process.env.NF_BROWSER_EVAL);
  * | `survol`   | survol : révèle une infobulle, un menu déroulant          |
  * | `saisir`   | remplit un champ (`saisir:Nom=mon-app`)                   |
  * | `choisir`  | choisit une option d'une liste (`choisir:Habillage=dots`) |
- * | `touche`   | frappe une touche (`touche:Enter`, `touche:Escape`)       |
+ * | `deposer`  | joint un fichier à un champ, même caché (`deposer:input[type=file]=tmp/a.png`) |
+ * | `touche`   | frappe une touche sur le focus (`touche:Escape`), ou sur une cible (`touche:#onglet=End`) |
  * | `voir`     | amène dans la vue SANS cliquer                            |
  * | `defiler`  | fait défiler de N pixels (`defiler:600`), page ou conteneur |
+ * | `molette`  | une vraie molette de N pixels sous le pointeur (`survol:` avant) |
  * | `attendre` | attend qu'un texte APPARAISSE (après une action lente)    |
  * | `connecter` | se connecte dans un AUTRE onglet (`connecter:`), sans recharger |
  *
@@ -114,6 +119,8 @@ if (unknown.length > 0) {
   process.exit(64); // EX_USAGE
 }
 const active = new Set(kept);
+/** `NF_BROWSER_AWAY=1` : la page se croit cachée et sans le focus. */
+const AWAY = process.env.NF_BROWSER_AWAY === "1";
 
 /**
  * Sondes de style par défaut — surchargées par NF_BROWSER_PROBES.
@@ -153,11 +160,12 @@ async function axeSource() {
   return axe.source;
 }
 
-const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
-
 // `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 });
+const { browser, ctx, page, reuse } = await open({
+  anonymous: ANONYMOUS,
+  permissions: active.has("notifications") ? ["notifications"] : [],
+});
 
 // ── Collecteurs — posés AVANT toute navigation ──────────────────────────────
 const consoleErrors = [];
@@ -175,6 +183,39 @@ page.on("pageerror", (e) => {
 // Les violations CSP ne sont visibles QUE depuis la page : le réseau montre la
 // requête absente, jamais la raison. L'init script est réinjecté à chaque
 // navigation — c'est l'état de la DERNIÈRE page qu'on lit, celle qu'on mesure.
+// Famille notifications : chaque `new Notification()` est RELEVÉE, puis
+// créée pour de vrai — la page garde son comportement, on lit ce qu'elle a
+// levé. Le pilote n'affiche aucune notification : sans ce relevé, une
+// notification réussie et une notification jamais levée se ressemblent.
+if (active.has("notifications")) {
+  await page.addInitScript(() => {
+    window.__nfNotifications = [];
+    const Native = window.Notification;
+    if (typeof Native !== "function") return;
+    class Recorded extends Native {
+      constructor(title, options) {
+        super(title, options);
+        if (window.__nfNotifications.length < 20)
+          window.__nfNotifications.push({
+            title: String(title).slice(0, 140),
+            body: String(options?.body ?? "").slice(0, 140),
+            tag: options?.tag ?? null,
+          });
+      }
+    }
+    window.Notification = Recorded;
+  });
+}
+// `NF_BROWSER_AWAY=1` : la personne est AILLEURS — onglet caché, autre
+// application au premier plan. Une page qui ne notifie qu'en son absence ne
+// se mesure pas autrement : la fenêtre pilotée est toujours au premier plan.
+if (AWAY) {
+  await page.addInitScript(() => {
+    Object.defineProperty(document, "visibilityState", { get: () => "hidden" });
+    Object.defineProperty(document, "hidden", { get: () => true });
+    document.hasFocus = () => false;
+  });
+}
 await page.addInitScript(() => {
   window.__nfCsp = [];
   document.addEventListener("securitypolicyviolation", (e) => {
@@ -827,6 +868,24 @@ if (active.has("reseau")) {
   };
 }
 
+// ── Famille notifications — ce que la page a levé ──────────────────────────
+if (active.has("notifications")) {
+  const raised = await page.evaluate(() => ({
+    permission:
+      typeof Notification === "function" ? Notification.permission : "absente",
+    list: window.__nfNotifications ?? [],
+  }));
+  measured.notifications = {
+    // Une DONNÉE, pas un jugement : aucune notification peut être le bon
+    // résultat (la personne était là).
+    verdict: raised.list.length > 0 ? "LEVÉES" : "AUCUNE",
+    permission: raised.permission,
+    away: AWAY,
+    count: raised.list.length,
+    list: raised.list.slice(0, 3),
+  };
+}
+
 // ── Famille stockage — volet cookies, lu hors page ──────────────────────────
 if (active.has("stockage")) {
   const cookies = await ctx.cookies();
@@ -951,7 +1010,10 @@ if (EVAL) {
 
 // ── Capture — AVANT la famille responsive, qui déforme le viewport ──────────
 const slug = captureSlug(PAGE);
-const shot = path.join(OUTPUT, `${slug}-${stamp}.png`);
+const shot = path.join(
+  OUTPUT,
+  stampedName(slug, new Date(), process.pid, "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à ».