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

package/docs/cookbook-chat.md

@@ -77,7 +77,7 @@ apporte.
 | --------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------- |
 | [1 — le chat minimal](#-démarrage-rapide--étape-1-le-chat-minimal-qui-marche)           | Un canal, un message qui traverse                              | Deux onglets qui se parlent              |
 | [2 — HTTP et WebSocket](#-étape-2--le-même-contrôleur-sert-http-et-websocket)           | L'historique en `GET` dans la **même classe**                  | Une action, deux transports              |
-| [3 — présence et frappe](#-étape-3--présence-et-frappe-en-cours)                        | Deux canaux de plus sur la **même** connexion                  | Multiplexage sans socket supplémentaire  |
+| [3 — présence et frappe](#-étape-3--présence-et-frappe-en-cours)                        | La présence en option du canal, la frappe en message           | Ni canal ni minuteur de plus             |
 | [4 — persister](#-étape-4--persister-lhistorique)                                       | Un repository derrière un service                              | L'historique survit au redémarrage       |
 | [5 — protéger](#-étape-5--protéger-le-salon)                                            | Zone firewall + politique de canal                             | L'intrus est refusé, et sait qu'il l'est |
 | [6 — la pièce jointe](#-étape-6--la-pièce-jointe-http-et-websocket-dans-la-même-classe) | `POST` multipart + annonce sur le canal                        | Le différenciateur devient **visible**   |
@@ -92,23 +92,23 @@ apporte.
 Tous les termes employés dans cette page. Le fond de chacun est dans
 [vocabulaire.md](./vocabulaire.md) — ici, la définition strictement suffisante pour suivre.
 
-| Terme              | Ce que c'est                                                                                                                                                  |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Socket**         | La connexion WebSocket unique entre un navigateur et le serveur. Une seule par onglet, quel que soit le nombre de canaux.                                     |
-| **Canal**          | Un flux nommé qui circule **dans** la socket (`chat:room`, `chat:presence`). Analogie : la socket est le câble, les canaux sont les fréquences qui y passent. |
-| **Frame**          | Un message du protocole sur le fil. Toutes les frames sont du JSON-RPC 2.0.                                                                                   |
-| **Hub**            | Le distributeur côté serveur : il tient la liste « qui écoute quel canal » et recopie chaque publication vers les abonnés du processus courant.               |
-| **Backplane**      | Le « fond de panier » : ce qui relaie les publications d'un processus à l'autre. Sans lui, chaque réplique est une île.                                       |
-| **Pod / réplique** | Un processus Node qui sert l'application. Un seul en développement, plusieurs en production.                                                                  |
-| **Fan-out**        | La recopie d'une publication vers N abonnés. Une publication, N livraisons.                                                                                   |
-| **Inbound**        | Un canal où le **client** pousse vers le serveur. Sens inverse du pub/sub habituel ; il faut le déclarer explicitement.                                       |
-| **RPC**            | _Remote Procedure Call_ : le client appelle une méthode serveur et attend une réponse (une `Promise`). Par opposition à une notification, qui ne répond pas.  |
-| **Provider**       | La fonction qui « alimente » un canal côté serveur. Créée au premier abonné, détruite au dernier.                                                             |
-| **Sink**           | Le point de sortie d'une connexion sur un canal. Un abonné = un sink.                                                                                         |
-| **BFF**            | _Backend For Frontend_ : le serveur porte la session dans un cookie, le navigateur ne manipule aucun jeton.                                                   |
-| **Zone / area**    | Un motif d'URL que le firewall protège, avec la liste des façons de prouver son identité.                                                                     |
-| **Politique**      | Les exigences attachées à un canal : authentifié, tel rôle, tel scope.                                                                                        |
-| **Multipart**      | L'encodage d'un formulaire HTTP qui transporte des fichiers (`multipart/form-data`).                                                                          |
+| Terme              | Ce que c'est                                                                                                                                                 |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Socket**         | La connexion WebSocket unique entre un navigateur et le serveur. Une seule par onglet, quel que soit le nombre de canaux.                                    |
+| **Canal**          | Un flux nommé qui circule **dans** la socket (`chat:room`, `room:42`). Analogie : la socket est le câble, les canaux sont les fréquences qui y passent.      |
+| **Frame**          | Un message du protocole sur le fil. Toutes les frames sont du JSON-RPC 2.0.                                                                                  |
+| **Hub**            | Le distributeur côté serveur : il tient la liste « qui écoute quel canal » et recopie chaque publication vers les abonnés du processus courant.              |
+| **Backplane**      | Le « fond de panier » : ce qui relaie les publications d'un processus à l'autre. Sans lui, chaque réplique est une île.                                      |
+| **Pod / réplique** | Un processus Node qui sert l'application. Un seul en développement, plusieurs en production.                                                                 |
+| **Fan-out**        | La recopie d'une publication vers N abonnés. Une publication, N livraisons.                                                                                  |
+| **Inbound**        | Un canal où le **client** pousse vers le serveur. Sens inverse du pub/sub habituel ; il faut le déclarer explicitement.                                      |
+| **RPC**            | _Remote Procedure Call_ : le client appelle une méthode serveur et attend une réponse (une `Promise`). Par opposition à une notification, qui ne répond pas. |
+| **Provider**       | La fonction qui « alimente » un canal côté serveur. Créée au premier abonné, détruite au dernier.                                                            |
+| **Sink**           | Le point de sortie d'une connexion sur un canal. Un abonné = un sink.                                                                                        |
+| **BFF**            | _Backend For Frontend_ : le serveur porte la session dans un cookie, le navigateur ne manipule aucun jeton.                                                  |
+| **Zone / area**    | Un motif d'URL que le firewall protège, avec la liste des façons de prouver son identité.                                                                    |
+| **Politique**      | Les exigences attachées à un canal : authentifié, tel rôle, tel scope.                                                                                       |
+| **Multipart**      | L'encodage d'un formulaire HTTP qui transporte des fichiers (`multipart/form-data`).                                                                         |
 
 ## 🧠 Le modèle mental en trois phrases
 
@@ -531,7 +531,7 @@ requirements: {
 Cette méthode est alors joignable de **deux** façons, et c'est **le même code** qui s'exécute :
 
 - `GET /chat/history` en HTTP ;
-- `socket.request("/chat/history")` par la socket déjà ouverte.
+- `socket.get("/chat/history")` par la socket déjà ouverte — la méthode porte le **verbe** de la route.
 
 Le passage par la socket emprunte un pont interne qui rejoue le routage sur le chemin demandé, puis
 exécute l'action. Ce pont ne peut atteindre **que** les routes ayant explicitement déclaré le
@@ -594,14 +594,15 @@ import { useEffect } from "react";
 // aucune poignée de main TLS de plus.
 useEffect(() => {
   void socket
-    .request<ChatMessage[]>("/chat/history?limit=50")
+    .get<ChatMessage[]>("/chat/history", { query: { limit: 50 } })
     .then((past) => setMessages(past));
 }, [socket]);
 ```
 
-Le chemin commence par `/` : le client le reconnaît comme un appel d'API et emprunte le pont. Une
-méthode RPC ordinaire, elle, ne commence jamais par `/` — il n'y a pas de collision possible entre
-les deux formes.
+`get` emprunte le pont : la même action que `GET /chat/history`, par la socket. La query se passe
+en objet et voyage dans le chemin (`?limit=50`), comme en HTTP. Le `<ChatMessage[]>` est une
+promesse faite au compilateur, pas une vérification : l'[étape 5](#quatre--un-contrat-pour-les-deux-côtés--lenvoi-et-les-messages-privés-typés)
+la remplace par un contrat qui DÉDUIT le type de la route.
 
 ### Ce qu'on observe
 
@@ -614,7 +615,7 @@ curl -k "https://127.0.0.1:5152/chat/history?limit=5"
 
 ```ts ignore
 // Transport 2 — la socket déjà ouverte, depuis la console du navigateur
-await chatSocket.request("/chat/history?limit=5");
+await chatSocket.get("/chat/history", { query: { limit: 5 } });
 ```
 
 Les deux renvoient le même tableau JSON. Si tu ajoutes une garde d'autorisation sur la méthode, elle
@@ -629,102 +630,324 @@ s'applique aux **deux** — c'est le même pipeline, pas deux implémentations
 
 ## 🧩 Étape 3 : présence et frappe en cours
 
-On ajoute deux flux : qui est là, et qui est en train d'écrire. Le point de cette étape n'est pas
-la fonctionnalité — c'est **ce qu'elle ne coûte pas**.
+On ajoute deux choses : qui est là, et qui est en train d'écrire. Le point de cette étape n'est pas
+la fonctionnalité — c'est **ce qu'elle ne coûte pas** : pas un canal de plus, pas un minuteur, pas
+une ligne de code par pod.
 
-### Trois canaux, une seule connexion
+### La présence est une option du canal, pas un canal de plus
 
-Un salon complet a besoin d'au moins trois flux distincts. Dans beaucoup d'architectures, cela se
-traduit par plusieurs connexions, ou par un canal fourre-tout où chacun filtre ce qui le concerne.
-Ici, les trois canaux voyagent **dans la même socket**, chacun avec son nom, chacun avec son
-abonnement propre :
+Être abonné au salon, c'est y être présent. La présence se déclare donc **sur le canal lui-même**,
+par une option de sa politique — `presence: true` — et le framework fait le reste : il tient la liste
+des présents, l'envoie entière à chaque abonné qui arrive, puis n'envoie que les changements,
+regroupés par fenêtre de 250 ms. Une connexion qui se ferme s'en va aussitôt de la liste.
 
 ```mermaid
 flowchart LR
   N["Onglet du navigateur<br/>UNE connexion WebSocket"]
-  N -.->|"chat:room"| R[Messages]
-  N -.->|"chat:presence"| P[Qui est connecté]
-  N -.->|"chat:typing"| T[Qui écrit]
+  N -.->|"chat:room"| C["Le canal du salon"]
+  C --> M[Messages]
+  C --> T["« Untel écrit… »"]
+  C --> P["Qui est là<br/>(option presence)"]
 ```
 
-S'abonner à un quatrième canal n'ouvre pas de quatrième connexion : cela envoie une frame
-d'abonnement sur celle qui existe déjà. C'est ce que « multiplexer » veut dire ici, et c'est ce qui
-rend viable le fait d'avoir un canal par préoccupation plutôt qu'un canal fourre-tout.
+> [!WARNING]
+> **La recette « un `Set` des connectés publié toutes les cinq secondes » est fausse dès deux
+> processus.** Chaque processus ne connaît que les connexions qu'il tient : derrière
+> `nodefony cluster -w 2` ou deux pods, chacun publie SA liste et écrase celle de l'autre. Elle coûte
+> en plus un envoi permanent, et annonce les départs jusqu'à cinq secondes en retard. La présence du
+> framework est tenue **entre les pods** (étape 7) : rien à écrire de plus.
+
+### La frappe est un message, pas un état
+
+« Untel écrit » ne dit pas qui est là : c'est un message éphémère, publié sur le canal du salon,
+que chacun reçoit parce qu'il y est abonné et que l'écran efface seul. Il ne passe jamais par la
+présence — sinon chaque frappe ferait renvoyer la liste à tout le salon.
+
+> [!IMPORTANT]
+> **À cette étape, l'auteur de la frappe vient du client** — comme le pseudo du message de l'étape 1,
+> et pour la même raison : il n'y a encore ni comptes ni salons, un seul salon ouvert à tous. Ce
+> n'est pas la forme finale. Dès l'[étape 5](#-étape-5--protéger-le-salon), l'auteur vient de la
+> **connexion** (`this.user`), jamais d'un champ : un « Untel écrit » forgé usurpe aussi bien qu'un
+> message (voir le [contrôleur complet](#-le-contrôleur-complet)).
 
 ### Le contrôleur — fichier **modifié**
 
-```ts ignore
-// modules/chat/nodefony/controllers/ChatController.ts (ajouts de l'étape 3)
+Le contrôleur entier à cette étape ; l'envoi de l'étape 1 (`chat:send`) ne change pas et n'est pas
+répété.
 
-/** Les pseudos présents, par connexion. Statique : partagé par tout le processus. */
-static present = new Set<string>();
+<!-- example: chatPresence.ts -->
 
-/**
- * PRÉSENCE. Ce provider-là a quelque chose à démarrer : un rappel régulier de
- * l'état. La fonction de nettoyage rendue au hub arrête le minuteur — au dernier
- * désabonné, plus personne ne paie ce coût.
- */
-@RealtimeChannel("chat:presence")
-presence(channel: string, publish: RealtimePublish): () => void {
-  const timer = setInterval(() => {
-    publish(channel, { present: [...ChatController.present] });
-  }, 5000);
-  // `unref` : ce minuteur ne doit jamais retenir le processus à l'arrêt.
-  timer.unref();
-  return () => clearInterval(timer);
+```ts
+import { controller, route } from "@nodefony/framework";
+import type { ContextType } from "@nodefony/http";
+import {
+  RealtimeChannel,
+  RealtimeController,
+  RealtimeInbound,
+  getRealtimeHub,
+} from "@nodefony/realtime";
+
+/** Le canal du salon : il porte les messages, la frappe — et la présence. */
+export const ROOM_CHANNEL = "chat:room";
+
+/** « Untel écrit » : un message ÉPHÉMÈRE du canal, jamais gardé, jamais rejoué. */
+export interface ChatTyping {
+  typing: string;
 }
 
-/** FRAPPE EN COURS. Volatile par nature : rien à persister, rien à rejouer. */
-@RealtimeChannel("chat:typing")
-typing(_channel: string, _publish: RealtimePublish): () => void {
-  return () => {};
+@controller("/chat")
+export class ChatController extends RealtimeController {
+  constructor(context: ContextType) {
+    super("chat", context);
+  }
+
+  @route("chat-realtime", {
+    path: "/realtime",
+    requirements: { methods: ["WEBSOCKET"] },
+  })
+  async realtime(message: string | Uint8Array | null): Promise<void> {
+    this.handleRealtime(message);
+  }
+
+  // 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 () => {};
+  }
+
+  // La frappe n'est PAS un état de présence : c'est un message du canal, que
+  // chacun reçoit parce qu'il y est abonné, et que l'écran efface seul.
+  @RealtimeInbound("chat:typing")
+  onTyping(params: unknown): void {
+    if (!ChatController.isTyping(params)) return;
+    const typing: ChatTyping = { typing: params.author.slice(0, 40) };
+    getRealtimeHub().publish(ROOM_CHANNEL, typing);
+  }
+
+  /** Ce qui arrive du réseau n'est pas fiable : un auteur non vide, ou rien. */
+  private static isTyping(value: unknown): value is { author: string } {
+    return (
+      typeof value === "object" &&
+      value !== null &&
+      "author" in value &&
+      typeof value.author === "string" &&
+      value.author.length > 0
+    );
+  }
 }
+```
+
+### Côté client
+
+`onPresence` rappelle l'écran avec **la vue entière** à chaque changement : il n'y a rien à
+fusionner soi-même. En React, `useNodefonyPresence(chatSocket, "chat:room")` rend le même
+instantané (Vue, Angular et Svelte ont leur équivalent).
 
-/** Le client signale qu'il écrit ; on le relaie tel quel au salon. */
-@RealtimeInbound("chat:typing")
-onTyping(params: unknown): void {
-  const author = (params as { author?: unknown } | null)?.author;
-  if (typeof author !== "string" || author.length === 0) return;
-  getRealtimeHub().publish("chat:typing", { author: author.slice(0, 40) });
+<!-- example: chatPresence.client.ts -->
+
+```ts
+import { NodefonySocket } from "nodefony/client";
+
+const ROOM = "chat:room";
+const socket = NodefonySocket.shared({ url: "/chat/realtime" });
+
+/** 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);
+  };
+}
+
+/** Signaler qu'on écrit — au plus une fois toutes les deux secondes. */
+export function typingNotifier(author: string): () => void {
+  let last = 0;
+  return () => {
+    const now = Date.now();
+    if (now - last < 2000) return;
+    last = now;
+    socket.emit("chat:typing", { author });
+  };
+}
+
+/** « Untel écrit… » : affiché à réception, effacé seul trois secondes plus tard. */
+export function watchTyping(
+  self: string,
+  show: (author: string | null) => void,
+): () => void {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  return socket.on(ROOM, (frame) => {
+    if (typeof frame !== "object" || frame === null || !("typing" in frame))
+      return;
+    if (typeof frame.typing !== "string" || frame.typing === self) return;
+    show(frame.typing);
+    clearTimeout(timer);
+    timer = setTimeout(() => show(null), 3000);
+  });
 }
 ```
 
-> [!NOTE]
-> **Un canal peut porter les deux sens.** `chat:typing` est déclaré à la fois comme canal sortant
-> (`@RealtimeChannel`) et comme canal entrant (`@RealtimeInbound`). C'est ce qu'on appelle un canal
-> **duplex** : le client y pousse, et le reçoit en retour parce qu'il y est abonné.
+| Champ de l'instantané | Ce qu'il dit                                                                                                  |
+| --------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `ready`               | `false` tant que la première liste n'est pas arrivée — « pas encore reçu » n'est pas « vide »                 |
+| `count`               | les présents **nommés** : un par compte, quel que soit son nombre d'onglets                                   |
+| `unnamed`             | les 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 incomplète ou figée (connexion coupée, pod injoignable) — la liste suivante la répare |
 
-### Côté client
+### À cette étape, personne n'est nommé
 
-```tsx ignore
-// frontend/src/ChatRoom.tsx (ajouts de l'étape 3)
-import { useNodefonyChannelData } from "nodefony/react";
-
-// La DERNIÈRE valeur reçue suffit pour un état : on ne veut pas l'historique
-// des présences, seulement l'état courant.
-const presence = useNodefonyChannelData<{ present: string[] }>("chat:presence");
-
-const [typingBy, setTypingBy] = useState<string | null>(null);
-useNodefonyChannel("chat:typing", (payload) => {
-  const author = (payload as { author: string }).author;
-  if (author === pseudo) return; // ne pas s'afficher soi-même
-  setTypingBy(author);
-  // L'indicateur s'efface tout seul : le serveur n'envoie jamais de « stop ».
-  window.setTimeout(() => setTypingBy(null), 2500);
-});
+Tout le monde est encore anonyme : la présence **compte** les connexions (`unnamed`), elle ne nomme
+personne. Et le pseudo que le client envoie avec son message n'y change rien — se déclarer « Alice »
+ne fait pas de toi une présente nommée. Les noms arrivent à l'[étape 5](#-étape-5--protéger-le-salon),
+avec les comptes : la présence nomme ce que le serveur a vérifié, jamais ce que le client affirme.
+
+### Le test — fichier **créé**
+
+Le test joue des connexions réelles contre le contrôleur, et lit ce que **l'écran** de chacune
+afficherait : les trames de présence reçues, appliquées par la même vue que le navigateur.
+
+<!-- example: chatPresence.test.ts -->
+
+```ts
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  PresenceView,
+  REALTIME_PRESENCE_METHOD,
+  isPresenceFrame,
+} from "nodefony";
+import type { IPresenceSnapshot } from "nodefony";
+import { getRealtimeHub } from "@nodefony/realtime";
+import { createRealtimeHarness } from "@nodefony/realtime/testing";
+import type { IRealtimeHarness } from "@nodefony/realtime/testing";
+import { createTestIdentity } from "@nodefony/security/testing";
+import { ChatController, ROOM_CHANNEL } from "./chatPresence";
+
+const open: IRealtimeHarness<ChatController>[] = [];
+const flush = (): Promise<void> => new Promise((r) => setTimeout(r, 0));
+
+/** Une connexion : un compte (`name`), ou un anonyme. */
+async function connect(
+  name?: string,
+): Promise<IRealtimeHarness<ChatController>> {
+  const h = createRealtimeHarness((ctx) => new ChatController(ctx), {
+    ...(name === undefined
+      ? {}
+      : { identity: createTestIdentity({ identifier: name }) }),
+    resetHub: open.length === 0,
+  });
+  await h.connect();
+  open.push(h);
+  return h;
+}
+
+/** 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();
+}
 
-// Dans le rendu :
-// <p>{presence?.present.length ?? 0} connecté(s)</p>
-// {typingBy && <p>{typingBy} est en train d'écrire…</p>}
+/** 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);
+}
+
+describe("salon — la présence portée par le canal, la frappe en message éphémère", () => {
+  afterEach(() => {
+    for (const h of open.splice(0)) h.close();
+    getRealtimeHub().clear();
+  });
+
+  it("être abonné, c'est être présent : un compte est nommé, un anonyme compté sans nom", async () => {
+    const alice = await connect("alice");
+    const guest = await connect();
+    await alice.subscribe(ROOM_CHANNEL);
+    await guest.subscribe(ROOM_CHANNEL);
+    await flush();
+    // Le dernier arrivé reçoit la liste complète dès son abonnement.
+    const seen = screenOf(guest);
+    expect(seen.ready).toBe(true);
+    expect([...seen.members.keys()]).toEqual(["alice"]);
+    expect([seen.count, seen.unnamed]).toEqual([1, 1]);
+  });
+
+  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,
+    });
+  });
+
+  it("la frappe arrive comme un message du canal, et ne touche pas la présence", async () => {
+    const alice = await connect("alice");
+    const bob = await connect("bob");
+    await alice.subscribe(ROOM_CHANNEL);
+    await bob.subscribe(ROOM_CHANNEL);
+    await bob.notify("chat:typing", { author: "bob" });
+    await flush();
+    expect(alice.messages(ROOM_CHANNEL)).toEqual([{ typing: "bob" }]);
+    expect(getRealtimeHub().presence(ROOM_CHANNEL)?.members.get("bob")).toEqual(
+      {
+        tabs: 1,
+      },
+    );
+  });
+
+  it("connexion fermée : le présent s'en va, chez le serveur PUIS sur l'écran des autres", async () => {
+    const alice = await connect("alice");
+    const bob = await connect("bob");
+    await alice.subscribe(ROOM_CHANNEL);
+    await bob.subscribe(ROOM_CHANNEL);
+    await until(() => screenOf(alice).members.has("bob"));
+    bob.close();
+    await flush();
+    expect(getRealtimeHub().presence(ROOM_CHANNEL)?.members.has("bob")).toBe(
+      false,
+    );
+    await until(() => !screenOf(alice).members.has("bob"));
+    expect(screenOf(alice).count).toBe(1);
+  });
+});
 ```
 
 ### Ce qu'on observe
 
-| Tu fais                                 | Tu vois                                                                                                    |
-| --------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| Tu tapes dans l'onglet gauche           | « invité-412 est en train d'écrire… » apparaît dans l'onglet droit, puis disparaît seul.                   |
-| Tu ouvres l'onglet réseau du navigateur | **Une seule** entrée WebSocket, même avec trois canaux actifs. C'est le point de cette étape.              |
-| Tu quittes l'écran du salon             | Les trois abonnements sont relâchés. Au dernier abonné de `chat:presence`, le minuteur serveur est arrêté. |
+| Tu fais                                 | Tu vois                                                                                                                      |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Tu ouvres deux onglets                  | « 2 présent(s) » dans chacun, sans nom : ce sont deux anonymes.                                                              |
+| Tu tapes dans l'onglet gauche           | « invité-412 est en train d'écrire… » apparaît dans l'onglet droit, puis disparaît seul. La liste des présents ne bouge pas. |
+| Tu fermes l'onglet gauche               | L'onglet droit passe à « 1 présent(s) » dans le quart de seconde.                                                            |
+| Tu ouvres l'onglet réseau du navigateur | **Une seule** entrée WebSocket et **un seul** canal : messages, frappe et présence voyagent ensemble.                        |
+
+### Le même modèle que les normes
+
+La présence suit le modèle des protocoles de présence normalisés, pour qu'une passerelle reste
+possible : un **présent** est l'_occupant_ d'un salon de XEP-0045 ; la liste entière puis les
+changements sont la _full_ puis la _partial presence_ de RFC 5262 ; un abonnement répété redemande
+la liste entière, comme XEP-0045 §17.3 ; et « en train d'écrire » reste hors de la présence, comme
+le veut RFC 6121 §4.4.1. Le détail des choix est dans l'ADR-0025 (présence répartie d'un canal).
 
 ## 💾 Étape 4 : persister l'historique
 
@@ -829,26 +1052,25 @@ export const securityConfig = () =>
 
 Le décorateur de canal accepte un second argument : les exigences à satisfaire pour s'y abonner.
 
-Les deux méthodes concernées, complètes, avec leur politique :
+La déclaration du salon, complète, avec sa politique :
 
 ```ts ignore
 // modules/chat/nodefony/controllers/ChatController.ts
-// → remplace les déclarations de canal des étapes 1 et 3
-@RealtimeChannel(ROOM_CHANNEL, { authenticated: true, roles: ["ROLE_USER"] })
-room(_channel: string, _publish: RealtimePublish): () => void {
+// → remplace la déclaration de canal de l'étape 3
+@RealtimeChannel(ROOM_CHANNEL, {
+  authenticated: true,
+  roles: ["ROLE_USER"],
+  presence: true,
+})
+room(): () => void {
   return () => {};
 }
-
-@RealtimeChannel("chat:presence", { authenticated: true, roles: ["ROLE_USER"] })
-presence(channel: string, publish: RealtimePublish): () => void {
-  const timer = setInterval(() => {
-    publish(channel, { present: [...ChatController.present] });
-  }, 5000);
-  timer.unref();
-  return () => clearInterval(timer);
-}
 ```
 
+La présence suit la politique : n'est présent que celui qu'elle admet. Et puisque chacun est
+désormais connecté à son compte, la liste **nomme** les présents — par l'identité vérifiée à la
+poignée de main, jamais par un champ du client.
+
 Le module temps réel ne décide de rien : il **transporte la déclaration** jusqu'au firewall, seul à
 connaître la hiérarchie des rôles et l'identité réelle.
 
@@ -856,13 +1078,13 @@ connaître la hiérarchie des rôles et l'identité réelle.
 
 C'est ici qu'il faut être précis, car **tous les chemins ne se valent pas**.
 
-Un handler `@RealtimeInbound` reçoit `(params, reply)` — et **rien d'autre**. Il ne reçoit ni la
-connexion, ni le jeton d'identité résolu à la poignée de main. Autrement dit : depuis un canal
-inbound brut, le serveur **ne peut pas savoir qui parle**. Le canal peut être _gardé_ par une
-politique (personne d'anonyme ne s'y abonne), mais le nom de l'auteur reste, lui, déclaré par le
-client.
+Un handler `@RealtimeInbound` reçoit `(params, reply, connection)`. Le troisième argument porte
+l'identité résolue à la poignée de main : `connection.userId` est l'auteur, et c'est lui qu'on
+écrit dans le message — jamais un champ de la charge, où le client peut mentir. Ce qu'un canal
+inbound n'offre pas, en revanche : la validation du corps, la garde `@IsGranted`, le rejeu sans
+doublon (`@Idempotent`), et la même porte en HTTP.
 
-La voie qui donne l'identité est celle de l'[étape 2](#-étape-2--le-même-contrôleur-sert-http-et-websocket) :
+Ces garanties-là viennent par la voie de l'[étape 2](#-étape-2--le-même-contrôleur-sert-http-et-websocket) :
 une **action de contrôleur**, atteinte par la socket. Sur ce chemin, le framework établit le contexte
 de requête avec le jeton de la connexion — exactement comme en HTTP — et les décorateurs habituels
 fonctionnent :
@@ -870,58 +1092,66 @@ fonctionnent :
 ```ts ignore
 // modules/chat/nodefony/controllers/ChatController.ts
 // → remplace `@RealtimeInbound("chat:send")` par une ACTION
-import { Body, CurrentUser, IsGranted } from "@nodefony/framework";
-import type { IUser } from "@nodefony/user";
+import { z } from "zod";
+import { Idempotent, IsGranted } from "@nodefony/framework";
+import type { RouteInput } from "@nodefony/framework";
+
+/** Ce que l'envoi accepte — VALIDÉ par le framework avant l'action, par les deux portes. */
+const SendBody = z.object({ text: z.string().trim().min(1).max(2000) });
 
 /**
  * L'envoi devient une action, joignable en POST HTTP comme par la socket.
  * On y gagne ce qu'un canal inbound ne peut pas offrir : l'identité vérifiée
- * (`@CurrentUser`), la garde d'autorisation, et le pipeline complet.
+ * (`this.user`), la garde d'autorisation, la validation du corps et le
+ * pipeline complet.
  */
 @route("chat-send", {
   path: "/send",
   requirements: { methods: ["POST", "WEBSOCKET"] },
+  schema: { body: SendBody },
 })
 @IsGranted(["ROLE_USER"])
-async send(
-  @Body() payload: { text?: string },
-  @CurrentUser() user: IUser,
-) {
-  const text = typeof payload?.text === "string" ? payload.text.trim() : "";
-  if (text.length === 0 || text.length > 2000) {
-    throw new HttpError("message vide ou trop long", 400);
-  }
-
-  // L'auteur vient du SERVEUR. Le client ne peut plus mentir dessus.
+@Idempotent()
+send(input: RouteInput<{ body: typeof SendBody }>) {
+  // Corps vide, trop long, champ manquant : refusé AVANT d'arriver ici, par un
+  // 422 qui nomme le champ — en HTTP comme par la socket. Ici, `input.body.text`
+  // est une chaîne valide, rognée.
+  // L'auteur vient du SERVEUR (la zone l'a posé). Le client ne peut plus mentir dessus.
   const message: ChatMessage = {
-    author: user.identifier,
-    text,
+    author: this.user?.identifier ?? "anon.",
+    text: input.body.text,
     sentAt: Date.now(),
   };
 
   getRealtimeHub().publish(ROOM_CHANNEL, message);
-  return { ok: true, sentAt: message.sentAt };
+  return { sentAt: message.sentAt };
 }
 ```
 
-Côté navigateur, l'envoi passe alors par `mutate`, qui porte la méthode HTTP logique et une clé
-d'idempotence — une socket qui se reconnecte peut rejouer une frame, la clé évite le doublon :
+Côté navigateur, l'envoi passe par `post` — le **verbe de la route** : une route `POST` s'appelle
+`socket.post(…)`, une route `GET` `socket.get(…)`, rien d'autre à apprendre. La socket pose seule une
+**clé d'idempotence** sur chaque écriture : une socket qui se reconnecte peut rejouer une trame, et
+`@Idempotent()` reconnaît la clé et rend la réponse déjà calculée au lieu de publier deux fois.
 
 ```tsx ignore
 // frontend/src/ChatRoom.tsx (étape 5)
-await socket.mutate("/chat/send", {
-  method: "POST",
-  body: { text },
-  idempotencyKey: crypto.randomUUID(),
-});
+await socket.post("/chat/send", { text });
 ```
 
+> [!NOTE]
+> Une clé par **appel**, posée par la socket. Pour dédoublonner une **intention** — un double clic
+> sur « Envoyer » qui part deux fois —, l'écran fournit la sienne : `socket.post("/chat/send", { text
+}, { idempotencyKey: brouillon.id })`. Deux appels, une seule clé, un seul message.
+
 > [!TIP]
 > **La règle à retenir.** Canal inbound = flux volatil, à haute fréquence, dont l'expéditeur importe
 > peu (« untel écrit »). Action de contrôleur = tout ce qui doit être **attribué, autorisé ou
 > conservé**. Le chat de l'étape 1 utilisait un canal inbound par simplicité ; dès qu'il y a des
-> comptes, l'envoi devient une action. La frappe en cours, elle, reste un canal inbound — son auteur
-> n'a pas besoin d'être prouvé.
+> comptes, l'envoi devient une action. La frappe en cours, elle, reste un canal inbound : rien n'y
+> est conservé. Mais son auteur se lit sur la **connexion** (`this.user`), plus dans les paramètres
+> — sinon n'importe qui ferait écrire « Alice ». Avec **plusieurs salons à admission**, un canal
+> inbound ne sait pas dans quel salon la connexion est admise : la frappe devient alors une route,
+> qui relit l'admission du salon comme l'envoi (c'est ce que fait la démo de `create app`).
 
 Côté navigateur, l'identité annoncée par le serveur se lit sans appeler la moindre route :
 
@@ -936,6 +1166,213 @@ const identity = useNodefonyIdentity();
 //   identity.roles                     → pour masquer ce qui n'est pas permis
 ```
 
+### Quatre : un contrat pour les deux côtés — l'envoi et les messages privés typés
+
+À ce stade, tout marche, mais rien ne relie les deux côtés. `socket.post("/chat/send", { texte:
+"salut" })` — avec une faute de frappe — compile, part sur le réseau, et revient en 422. Le résultat
+de `post` est `unknown`. Le message privé n'existe pas encore. Les trois se règlent par **un seul
+fichier** que le serveur et le navigateur partagent : le **contrat**.
+
+**Le principe : une seule source.** Le corps de `/chat/send`, c'est le schéma `SendBody` que la route
+valide. Le contrat ne le **recopie** pas (`body: { text: string }`) : il le **référence**
+(`typeof SendBody`). Recopier, c'est écrire deux formes qui divergeront un jour sans que rien ne le
+dise — le schéma accepte `to`, la copie l'ignore, et le navigateur ne peut plus l'envoyer.
+
+#### Le schéma partagé — fichier **créé**
+
+```ts ignore
+// shared/chatSchemas.ts — la SEULE définition du corps de l'envoi
+import { z } from "zod";
+
+export const SendBody = z.object({
+  text: z.string().trim().min(1).max(2000),
+  /** Destinataire d'un message privé : l'`id` STABLE de son compte. Absent = le salon. */
+  to: z.string().optional(),
+});
+
+/**
+ * La query de l'historique — une query arrive en texte, `coerce` la convertit.
+ * Pas de `since` sur un instant : voir « La reconnexion », plus bas.
+ */
+export const HistoryQuery = z.object({
+  limit: z.coerce.number().int().min(1).max(200).default(50),
+});
+```
+
+#### Le contrat — fichier **créé**
+
+```ts ignore
+// shared/chatContract.ts — des TYPES seulement
+import type { IRealtimeContract } from "nodefony/client";
+import type { HistoryQuery, SendBody } from "./chatSchemas";
+
+export interface ChatMessage {
+  author: string;
+  text: string;
+  sentAt: number;
+  /** Présent sur un message privé. */
+  to?: string;
+}
+
+/** Ce qu'on annonce au salon quand un fichier a fini d'arriver (étape 6). */
+export interface ChatAttachment {
+  author: string;
+  filename: string;
+  size: number;
+  mimeType: string | null | undefined;
+  sentAt: number;
+}
+
+export interface ChatContract extends IRealtimeContract {
+  /** Ce que le serveur pousse : le salon, et le canal personnel de chacun. */
+  serverToClient: {
+    "chat:room": ChatMessage | ChatAttachment;
+    [channel: `user:${string}`]: ChatMessage;
+  };
+  /** Les routes que la socket appelle : "<VERBE> <chemin>" → corps, query, résultat. */
+  serverRoutes: {
+    "POST /chat/send": { body: typeof SendBody; result: { sentAt: number } };
+    "GET /chat/history": { query: typeof HistoryQuery; result: ChatMessage[] };
+  };
+}
+```
+
+`import type` est le point qui compte : le navigateur lit `typeof SendBody` **à la compilation**, et
+n'embarque **aucun octet** de zod. Le fichier du contrat, fait de types seuls, disparaît à la
+construction.
+
+#### Le serveur — fichier **modifié**
+
+```ts ignore
+// modules/chat/nodefony/controllers/ChatController.ts
+import { ContractRealtimeController, getRealtimeHub } from "@nodefony/realtime";
+import type { ContractRouteSchemas } from "nodefony";
+import type { RouteInput } from "@nodefony/framework";
+import { HistoryQuery, SendBody } from "../../../../shared/chatSchemas";
+import type {
+  ChatContract,
+  ChatMessage,
+} from "../../../../shared/chatContract";
+
+@controller("/chat")
+class ChatController extends ContractRealtimeController<ChatContract> {
+  /**
+   * Les VALEURS des routes du contrat — le schéma même que chaque route valide.
+   * Vérifiées au démarrage (voir plus bas) ; jamais envoyées au navigateur.
+   */
+  static readonly serverRoutes = {
+    "POST /chat/send": { body: SendBody },
+    "GET /chat/history": { query: HistoryQuery },
+  } satisfies ContractRouteSchemas<ChatContract>;
+
+  // La route de l'historique valide désormais `schema: { query: HistoryQuery }`
+  // (version complète plus bas) ; l'envoi, son corps :
+  @route("chat-send", {
+    path: "/send",
+    requirements: { methods: ["POST", "WEBSOCKET"] },
+    schema: { body: SendBody },
+  })
+  @IsGranted(["ROLE_USER"])
+  @Idempotent()
+  send(input: RouteInput<{ body: typeof SendBody }>) {
+    const me = this.user;
+    if (me === null) throw new HttpError("connexion requise", 401);
+    const { text, to } = input.body;
+    const message: ChatMessage = {
+      author: me.identifier,
+      text,
+      sentAt: Date.now(),
+    };
+    const hub = getRealtimeHub<ChatContract>();
+    if (to === undefined) {
+      hub.publish("chat:room", message);
+    } else {
+      // Message privé : le destinataire, sur TOUS ses onglets et TOUS les
+      // serveurs — et une copie à l'expéditeur, pour ses autres onglets.
+      hub.publishToUser(to, { ...message, to });
+      hub.publishToUser(me.id, { ...message, to });
+    }
+    return { sentAt: message.sentAt };
+  }
+}
+```
+
+`satisfies ContractRouteSchemas<ChatContract>` fait vérifier la table par le compilateur : une route
+du contrat **oubliée**, une route **en trop**, un **autre** schéma que `typeof SendBody` — et le
+fichier ne compile pas. `getRealtimeHub<ChatContract>()` type la diffusion : `hub.publish("chat:room",
+{ txt: "…" })` ne compile pas davantage.
+
+Le message privé ne demande **rien d'autre**. Le canal personnel `user:<id>` est une brique du
+framework : seule l'identité `<id>` peut s'y abonner, il traverse le bus entre serveurs, et
+personne ne paie rien tant qu'aucun écran ne l'écoute (détail : [securite.md](./securite.md)).
+
+#### Le navigateur — fichier **modifié**
+
+```ts ignore
+// frontend/src/realtime.ts — la socket, typée par le contrat
+import { NodefonySocket } from "nodefony/client";
+import type { ChatContract } from "../../shared/chatContract";
+
+export const chatSocket = NodefonySocket.fromContract<ChatContract>({
+  url: `${scheme}://${window.location.host}/chat/realtime`,
+});
+```
+
+```tsx ignore
+// frontend/src/ChatRoom.tsx (étape 5, typée)
+// Les messages privés de CET utilisateur : `m` est un ChatMessage, sans annotation.
+useEffect(() => chatSocket.onUser((m) => addPrivate(m)), []);
+
+// L'historique : ChatMessage[] — déduit de la route, query vérifiée.
+const past = await chatSocket.get("/chat/history", { query: { limit: 50 } });
+
+// L'envoi : le corps est l'ENTRÉE du schéma, le résultat est { sentAt: number }.
+const { sentAt } = await chatSocket.post("/chat/send", { text });
+await chatSocket.post("/chat/send", { text, to: bob.id }); // message privé
+
+// Et ce qui ne compile plus :
+await chatSocket.post("/chat/send", { texte: "x" }); // ✗ `texte` n'existe pas dans SendBody
+await chatSocket.post("/chat/send"); // ✗ le schéma exige un corps
+```
+
+Un chemin **hors contrat** reste libre — `chatSocket.get("/stats")` rend `unknown`,
+`chatSocket.get<Stats>("/stats")` le type choisi — : le contrat type ce qu'il déclare, il n'interdit
+rien d'autre.
+
+Une route à **paramètre de chemin** se déclare par son gabarit — la clé est le chemin de la route,
+`{id}` compris — et s'appelle en NOMMANT ce gabarit ; la socket le remplit :
+
+```ts ignore
+// contrat — la route valide `schema: { params: IdParams }`
+"GET /chat/messages/{id}": { params: typeof IdParams; result: ChatMessage };
+
+// navigateur
+const m = await chatSocket.get("/chat/messages/{id}", { params: { id } });
+await chatSocket.get("/chat/messages/{id}");                 // ✗ `params.id` manquant
+```
+
+Chaque valeur est encodée pour tenir dans **un** segment : un identifiant qui contient `/` ou `?`
+ne peut pas détourner l'appel vers une autre route, et une valeur vide, `.` ou `..` — que la
+normalisation du chemin résoudrait en remontant d'un cran — est refusée avant l'envoi. Sans
+schéma `params`, les valeurs sont typées par les `{noms}` du gabarit. Seuls des segments
+`{nom}` entiers se déclarent : une contrainte s'écrit dans `requirements` de la route, pas en
+ligne (`{id}(\d+)`) — le démarrage le refuse en nommant l'entrée.
+
+#### Ce que le démarrage refuse
+
+Le contrat est un **type** : il fait compiler `chatSocket.post("/chat/send", …)` même si la route
+n'existe pas. C'est la table `serverRoutes` qui porte les **valeurs**, et le démarrage les confronte
+aux routes montées — une fois, coût nul par requête. Trois fautes, trois refus qui nomment l'entrée :
+
+| Faute                                                         | Le démarrage s'arrête sur                                                                |
+| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| La route n'existe pas (chemin mal recopié, module non chargé) | `ChatController.serverRoutes « POST /chat/send » : aucune route montée au chemin …`      |
+| La route sert HTTP seulement (`methods: ["POST"]`)            | `… ne sert pas POST par la socket — ses méthodes doivent inclure "POST" et "WEBSOCKET".` |
+| La route valide un autre schéma (copie, ou schéma redéclaré)  | `… le schéma « body » n'est pas celui que la route valide (même objet attendu).`         |
+
+Sans ce contrôle, chacune de ces fautes compilerait, démarrerait, et n'apparaîtrait qu'au premier
+message envoyé — chez l'utilisateur.
+
 ### Ce que voit précisément un intrus
 
 Rien n'échoue en silence, et rien ne renseigne l'attaquant sur **pourquoi** il échoue.
@@ -1158,6 +1595,21 @@ use("@nodefony/realtime", {
 });
 ```
 
+### Ce que le relais ne partage pas : l'état
+
+Le backplane transporte des **trames**, rien d'autre. Ce que l'application **garde** — l'historique,
+les pièces jointes, la liste des salons — ne traverse pas avec lui : chaque pod lit et écrit le sien.
+Plusieurs pods exigent donc un état **partagé** :
+
+- **la base** : PostgreSQL ou MySQL, que tous les pods joignent. Un fichier SQLite vit sur le disque
+  d'UNE machine : c'est le mode d'un poste de développement ou d'une démo, pas d'une application
+  répartie ;
+- **les fichiers** : un stockage partagé (volume réseau, stockage objet), jamais le disque local
+  d'un pod — une pièce reçue par l'un serait introuvable depuis l'autre.
+
+La démo de `create app --demo` tient sur un seul pod, pour cette raison : sa base est un fichier
+SQLite et ses pièces restent sur le disque du serveur.
+
 ### Ce qui n'a pas bougé
 
 C'est l'argument, et il se vérifie fichier par fichier :
@@ -1170,6 +1622,10 @@ C'est l'argument, et il se vérifie fichier par fichier :
 | `ChatRoom.tsx`, `realtime.ts`     | **Non.** Le navigateur ne sait pas, et n'a pas à savoir, combien de pods existent. |
 | `nodefony.config.ts`              | Une chaîne de caractères.                                                          |
 
+La présence suit le même chemin : un canal diffusé partage ses présents entre les pods, sans une
+ligne de plus. Un canal à présence **non** diffusé reste juste, mais local à son processus — le
+journal le signale une fois, au premier abonné du canal, dès qu'un bus est configuré.
+
 Aucun appel de publication ne change, aucun abonnement ne change, aucune règle métier ne change. Ce
 qui change, c'est **par où** la publication repart après le fan-out local — et cela se décide dans la
 configuration, pas dans le code.
@@ -1199,11 +1655,14 @@ Au démarrage de chaque worker, la ligne d'identité du temps réel change de fo
 `kind=local cross-pod=no`, on lit maintenant un `kind` de transport et `cross-pod=yes` : c'est la
 confirmation, au boot, que le relais est en place.
 
-| Tu fais                     | Avant (étape 6)  | Maintenant                                             |
-| --------------------------- | ---------------- | ------------------------------------------------------ |
-| Alice envoie un fichier     | Bob ne voit rien | L'annonce apparaît chez Bob, sur l'autre processus     |
-| Alice tape un message       | Aléatoire        | Reçu par tous, quel que soit le worker                 |
-| Tu arrêtes le service Redis | —                | Le salon continue **dans chaque processus**, isolément |
+| Tu fais                         | Avant (étape 6)                | Maintenant                                                                                                            |
+| ------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| Alice envoie un fichier         | Bob ne voit rien               | L'annonce apparaît chez Bob, sur l'autre processus                                                                    |
+| Alice tape un message           | Aléatoire                      | Reçu par tous, quel que soit le worker                                                                                |
+| Alice et Bob, un worker chacun  | Chacun ne voit que lui présent | Les deux se voient présents ; un onglet sur chaque worker compte pour un seul présent                                 |
+| Tu arrêtes un worker proprement | —                              | Ses présents disparaissent chez les autres aussitôt : il l'annonce en partant                                         |
+| Tu tues un worker (`kill -9`)   | —                              | Ses présents disparaissent chez les autres au délai d'oubli : trois preuves de vie manquées, 15 s par défaut          |
+| Tu arrêtes le service Redis     | —                              | Le salon continue **dans chaque processus**, isolément ; la présence venue des autres pods se fige, marquée `partial` |
 
 Cette dernière ligne mérite une explication : si le backplane est injoignable au démarrage, le
 framework **ne bloque pas le boot**. Il journalise un avertissement, garde un hub local et sert le
@@ -1223,55 +1682,56 @@ La seule chose qui n'y figure pas est la persistance : `ChatController.history`
 mémoire, que l'[étape 4](#-étape-4--persister-lhistorique) remplace par un appel à ton service.
 C'est délibéré — ce fichier doit compiler sans supposer ta base.
 
+Il importe les deux fichiers partagés de l'[étape 5](#quatre--un-contrat-pour-les-deux-côtés--lenvoi-et-les-messages-privés-typés) :
+`shared/chatSchemas.ts` (les schémas que les routes valident) et `shared/chatContract.ts` (le
+contrat, types seuls).
+
 ```ts ignore
 // modules/chat/nodefony/controllers/ChatController.ts — version finale
 import {
   controller,
   route,
-  Body,
-  Query,
-  CurrentUser,
+  Idempotent,
   IsGranted,
   UploadedFile,
 } from "@nodefony/framework";
+import type { RouteInput } from "@nodefony/framework";
 import {
-  RealtimeController,
+  ContractRealtimeController,
+  RealtimeBroadcast,
   RealtimeChannel,
   RealtimeInbound,
   getRealtimeHub,
 } from "@nodefony/realtime";
-import type { RealtimePublish } from "@nodefony/realtime";
 import { HttpError } from "@nodefony/http";
 import type { ContextType, IUploadedFile } from "@nodefony/http";
-import type { IUser } from "@nodefony/user";
-
-/** Un message tel qu'il circule sur le canal du salon. */
-export interface ChatMessage {
-  author: string;
-  text: string;
-  sentAt: number;
-}
-
-/** Ce qu'on annonce au salon quand un fichier a fini d'arriver. */
-export interface ChatAttachment {
-  author: string;
-  filename: string;
-  size: number;
-  mimeType: string | null | undefined;
-  sentAt: number;
-}
+import type { ContractRouteSchemas } from "nodefony";
+import { HistoryQuery, SendBody } from "../../../../shared/chatSchemas";
+import type {
+  ChatAttachment,
+  ChatContract,
+  ChatMessage,
+} from "../../../../shared/chatContract";
 
 /** Le nom du canal du salon. Cité côté serveur ET côté client → une constante. */
 export const ROOM_CHANNEL = "chat:room";
 
+// Le salon traverse les serveurs (étape 7) : sans cette ligne, il reste sur le sien.
+@RealtimeBroadcast("chat:")
 @controller("/chat")
-class ChatController extends RealtimeController {
+class ChatController extends ContractRealtimeController<ChatContract> {
+  /**
+   * Les VALEURS des routes du contrat — le schéma même que chaque route valide.
+   * Vérifiées au démarrage ; jamais envoyées au navigateur.
+   */
+  static readonly serverRoutes = {
+    "POST /chat/send": { body: SendBody },
+    "GET /chat/history": { query: HistoryQuery },
+  } satisfies ContractRouteSchemas<ChatContract>;
+
   /** Stock en mémoire — remplacé par un repository à l'étape 4. */
   static history: ChatMessage[] = [];
 
-  /** Les pseudos présents dans le salon, sur CE processus. */
-  static present = new Set<string>();
-
   constructor(context: ContextType) {
     super("chat", context);
   }
@@ -1281,9 +1741,6 @@ class ChatController extends RealtimeController {
     return true;
   }
 
-  /** Ce qui doit franchir les frontières de processus (étape 7). */
-  // (préfixe diffusable déclaré par `@RealtimeBroadcast` sur la classe)
-
   // ── La porte WebSocket ────────────────────────────────────────────────────
 
   @route("chat-realtime", {
@@ -1296,38 +1753,47 @@ class ChatController extends RealtimeController {
 
   // ── Les actions : HTTP et WebSocket, même code ────────────────────────────
 
-  /** Historique — `GET /chat/history` ou `socket.request("/chat/history")`. */
+  /** Historique — `GET /chat/history` ou `socket.get("/chat/history")`. */
   @route("chat-history", {
     path: "/history",
     requirements: { methods: ["GET", "WEBSOCKET"] },
+    schema: { query: HistoryQuery },
   })
-  historyAction(@Query("limit") limit?: string): ChatMessage[] {
-    const max = Math.min(Number(limit) || 50, 200);
-    return ChatController.history.slice(-max);
+  historyAction(
+    input: RouteInput<{ query: typeof HistoryQuery }>,
+  ): ChatMessage[] {
+    return ChatController.history.slice(-input.query.limit);
   }
 
-  /** Envoi — l'auteur vient du serveur, jamais du client. */
+  /** Envoi — au salon, ou en privé à une personne ; l'auteur vient du serveur. */
   @route("chat-send", {
     path: "/send",
     requirements: { methods: ["POST", "WEBSOCKET"] },
+    schema: { body: SendBody },
   })
   @IsGranted(["ROLE_USER"])
-  async send(
-    @Body() payload: { text?: string },
-    @CurrentUser() user: IUser,
-  ): Promise<{ ok: true; sentAt: number }> {
-    const text = typeof payload?.text === "string" ? payload.text.trim() : "";
-    if (text.length === 0 || text.length > 2000) {
-      throw new HttpError("message vide ou trop long", 400);
-    }
+  @Idempotent()
+  send(input: RouteInput<{ body: typeof SendBody }>): { sentAt: number } {
+    const me = this.user;
+    if (me === null) throw new HttpError("connexion requise", 401);
+    const { text, to } = input.body;
     const message: ChatMessage = {
-      author: user.identifier,
+      author: me.identifier,
       text,
       sentAt: Date.now(),
     };
-    ChatController.history.push(message);
-    getRealtimeHub().publish(ROOM_CHANNEL, message);
-    return { ok: true, sentAt: message.sentAt };
+    const hub = getRealtimeHub<ChatContract>();
+    if (to === undefined) {
+      ChatController.history.push(message);
+      hub.publish(ROOM_CHANNEL, message);
+    } else {
+      // Le destinataire sur tous ses onglets et tous les serveurs, et une copie
+      // à l'expéditeur pour ses autres onglets. Rien à déclarer : `user:<id>`
+      // est un canal du framework.
+      hub.publishToUser(to, { ...message, to });
+      hub.publishToUser(me.id, { ...message, to });
+    }
+    return { sentAt: message.sentAt };
   }
 
   /** Pièce jointe — entre en POST multipart, ressort par le canal. */
@@ -1338,13 +1804,12 @@ class ChatController extends RealtimeController {
   @IsGranted(["ROLE_USER"])
   async upload(
     @UploadedFile() file?: IUploadedFile,
-    @CurrentUser() user: IUser,
-  ): Promise<{ ok: true; filename: string; size: number }> {
+  ): Promise<{ filename: string; size: number }> {
     if (!file) {
       throw new HttpError("aucun fichier reçu", 400);
     }
     const announcement: ChatAttachment = {
-      author: user.identifier,
+      author: this.user?.identifier ?? "anon.",
       filename: file.filename,
       size: file.size,
       mimeType: file.mimeType,
@@ -1353,42 +1818,34 @@ class ChatController extends RealtimeController {
     // La requête HTTP répondra à SON auteur ; cette publication atteint tout le
     // salon. Un transport entre, un autre sort — dans la même méthode.
     getRealtimeHub().publish(ROOM_CHANNEL, announcement);
-    return { ok: true, filename: file.filename, size: file.size };
+    return { filename: file.filename, size: file.size };
   }
 
   // ── Les canaux ────────────────────────────────────────────────────────────
 
-  /** Le salon. Rien à démarrer : il relaie, il n'émet pas de lui-même. */
-  @RealtimeChannel(ROOM_CHANNEL, { authenticated: true, roles: ["ROLE_USER"] })
-  room(_channel: string, _publish: RealtimePublish): () => void {
-    return () => {};
-  }
-
-  /** Présence — un rappel régulier, arrêté au dernier désabonné. */
-  @RealtimeChannel("chat:presence", {
+  /**
+   * Le salon. Rien à démarrer : il relaie, il n'émet pas de lui-même. Sa
+   * présence est tenue par le framework, entre les pods compris.
+   */
+  @RealtimeChannel(ROOM_CHANNEL, {
     authenticated: true,
     roles: ["ROLE_USER"],
+    presence: true,
   })
-  presence(channel: string, publish: RealtimePublish): () => void {
-    const timer = setInterval(() => {
-      publish(channel, { present: [...ChatController.present] });
-    }, 5000);
-    timer.unref();
-    return () => clearInterval(timer);
-  }
-
-  /** Frappe en cours — volatile : ni attribué, ni conservé. */
-  @RealtimeChannel("chat:typing")
-  typing(_channel: string, _publish: RealtimePublish): () => void {
+  room(): () => void {
     return () => {};
   }
 
-  /** Le seul canal entrant restant : haute fréquence, sans enjeu d'identité. */
-  @RealtimeInbound("chat:typing")
-  onTyping(params: unknown): void {
-    const author = (params as { author?: unknown } | null)?.author;
-    if (typeof author !== "string" || author.length === 0) return;
-    getRealtimeHub().publish("chat:typing", { author: author.slice(0, 40) });
+  /**
+   * Frappe en cours : un message ÉPHÉMÈRE du salon, ni conservé ni rejoué. Le
+   * seul canal entrant restant — l'auteur est celui de la connexion, pas un
+   * champ du client.
+   */
+  @RealtimeInbound("chat:typing", { authenticated: true })
+  onTyping(): void {
+    const author = this.user?.identifier;
+    if (author === undefined) return;
+    getRealtimeHub().publish(ROOM_CHANNEL, { typing: author });
   }
 }
 
@@ -1412,20 +1869,40 @@ hooks React ne se démontent pas ; tes composants ne voient rien passer. Côté
 libère les abonnements et détruit les providers devenus inutiles.
 
 **Ce qui reste à ta charge** : **le trou**. Les messages publiés pendant la coupure ne sont pas
-rejoués — le hub distribue à qui est là, il ne conserve rien. À la reconnexion, redemande
-l'historique depuis le dernier message connu :
+rejoués — le hub distribue à qui est là, il ne conserve rien. À la reconnexion, attends que
+l'abonnement soit **effectif**, relis les derniers messages, et **recoupe-les par identifiant** :
 
 ```tsx ignore
 // Au retour de `reconnecting` vers `connected`, on comble le trou.
 useEffect(() => {
   if (state !== "connected") return;
-  const lastSeen = messages.at(-1)?.sentAt ?? 0;
   void socket
-    .request<ChatMessage[]>(`/chat/history?since=${lastSeen}`)
-    .then((missed) => setMessages((previous) => [...previous, ...missed]));
+    // Lire AVANT l'abonnement effectif perdrait ce qui se publie entre les deux.
+    .whenSubscribed("chat:room")
+    .then(() =>
+      socket.get<ChatMessage[]>("/chat/history", { query: { limit: 50 } }),
+    )
+    .then((page) =>
+      setMessages((previous) => {
+        // Par `id` : un message arrivé par les DEUX chemins n'apparaît qu'une fois.
+        const byId = new Map(previous.map((m) => [m.id, m]));
+        for (const m of page) byId.set(m.id, m);
+        return [...byId.values()];
+      }),
+    );
 }, [state]);
 ```
 
+Deux pièges, que ce code évite :
+
+- **Un rattrapage borné par l'heure** (`since: dernierMessage.sentAt`) double ou perd des messages :
+  chaque pod a son horloge, et deux messages de la même milliseconde se départagent mal. L'heure
+  sert à afficher, jamais à rattraper.
+- **Une page qui ne recoupe rien** de ce que l'écran montrait signale un trou plus long qu'elle :
+  les messages plus anciens ne sont plus contigus. La démo de `create app --demo` les retire
+  plutôt que de les afficher de part et d'autre d'un silence qui n'a pas eu lieu
+  (`catchUpMessages`).
+
 ### Les messages en double
 
 **Symptôme** — le même message apparaît deux fois.
@@ -1632,14 +2109,14 @@ Pour qui veut lire l'implémentation derrière chaque étape :
 | La publication et le fan-out | `RealtimeHub.publish()` (`RealtimeHub.ts#RealtimeHub.publish`), réinjection locale `RealtimeHub.publishLocal()` (`RealtimeHub.ts#RealtimeHub.publishLocal`) |
 | Les canaux diffusables | `RealtimeBroadcast` (`realtimeDecorators.ts#RealtimeBroadcast`), `RealtimeHub.markBroadcastChannel()` (`RealtimeHub.ts#RealtimeHub.markBroadcastChannel`) |
 | Le branchement du backplane | `RealtimeHub.setBackplane()` (`RealtimeHub.ts#RealtimeHub.setBackplane`), registre `registerBackplaneDriver()` (`backplaneRegistry.ts#registerBackplaneDriver`), cloison `resolveBackplaneOriginId()` (`originId.ts#resolveBackplaneOriginId`) |
-| Les politiques de canal | `IChannelPolicy` (`IChannelPolicy.ts#IChannelPolicy`), `RealtimeHub.registerChannelPolicy()` (`RealtimeHub.ts#RealtimeHub.registerChannelPolicy`), garde-fou `RealtimeHub.hasUnenforcedChannelPolicies()` (`RealtimeHub.ts#RealtimeHub.hasUnenforcedChannelPolicies`) |
+| Les politiques de canal | `IChannelPolicy` (`nodefony/src/realtime/channelAdmission.ts#IChannelPolicy`), `RealtimeHub.registerChannelPolicy()` (`RealtimeHub.ts#RealtimeHub.registerChannelPolicy`), garde-fou `RealtimeHub.hasUnenforcedChannelPolicies()` (`RealtimeHub.ts#RealtimeHub.hasUnenforcedChannelPolicies`) |
 | Le branchement automatique du firewall | `Firewall.#wireRealtime()` (`firewall.ts#Firewall.#wireRealtime`) |
 | Les refus | `IRealtimeDenied` (`RealtimeEventMap.ts#IRealtimeDenied`), erreur `unauthorized` (`JsonRpcPeer.ts#JsonRpcPeer.receive`), fermetures `origin not allowed` (`RealtimeController.ts#RealtimeController.notifyClient`) et `unauthorized` (`RealtimeController.ts#RealtimeController.onHandshake`) |
 | La révocation en cours de session | `RealtimeHub.revalidateRevocable()` (`RealtimeHub.ts#RealtimeHub.revalidateRevocable`) |
 | Le consommateur lent | seuil `SLOW_CONSUMER_BYTES` (`RealtimeHub.ts#SLOW_CONSUMER_BYTES`), fermeture `slow consumer` (`RealtimeHub.ts#SLOW_CONSUMER_BYTES`) |
 | Le plafond de canaux | `RealtimeHub.maxChannelsPerConnection` (`RealtimeHub.ts#RealtimeHub.maxChannelsPerConnection`) |
 | L'accueil et l'identité | `IRealtimeWelcome` (`RealtimeEventMap.ts#IRealtimeWelcome`) |
-| La sonde | `RealtimeHub.probe()` (`RealtimeHub.ts#RealtimeHub.probe`), `IRealtimeProbe` (`IRealtimeProbe.ts#IRealtimeProbe`), `IRealtimeChannelStat` (`IRealtimeProbe.ts#IRealtimeChannelStat`) |
+| La sonde | `RealtimeHub.probe()` (`RealtimeHub.ts#RealtimeHub.probe`), `IRealtimeProbe` (`nodefony/src/realtime/platformHealth.ts#IRealtimeProbe`), `IRealtimeChannelStat` (`nodefony/src/realtime/platformHealth.ts#IRealtimeChannelStat`) |
 | Le point de mesure d'administration | `createRealtimeAdminApi()` (`RealtimeAdminApi.ts#createRealtimeAdminApi`), `buildRealtimeHealth()` (`RealtimeAdminApi.ts#buildRealtimeHealth`), `buildOwnHealth()` (`RealtimeAdminApi.ts#buildOwnHealth`) |
 | Le service injectable | `RealtimeService.publish()` (`RealtimeService.ts#RealtimeService.publish`), `RealtimeService.probe()` (`RealtimeService.ts#RealtimeService.probe`), `RealtimeService.markBroadcastChannel()` (`RealtimeService.ts#RealtimeService.markBroadcastChannel`) |
 | Les hooks React | `useNodefony()` (`client/react/index.ts#useNodefony`), `useNodefonyState()` (`client/react/index.ts#useNodefonyState`), `useNodefonyIdentity()` (`client/react/index.ts#useNodefonyIdentity`), `useNodefonyChannel()` (`client/react/index.ts#useNodefonyChannel`), `useNodefonyChannelData()` (`client/react/index.ts#useNodefonyChannelData`), `useNodefonyAdaptiveChannel()` (`client/react/index.ts#useNodefonyAdaptiveChannel`) |