nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/client/types/src/client/realtime/RealtimeClient.d.ts

@@ -0,0 +1,573 @@
+/**
+ * RealtimeClient — Core isomorphe Nodefony côté navigateur (P14.11).
+ *
+ * Protocole : JSON-RPC 2.0 maison sur WebSocket (+ HTTP long-polling fallback TODO P13).
+ * State machine : disconnected → connecting → connected → reconnecting → error.
+ *
+ * Features :
+ *  - reconnect exponentiel avec back-off
+ *  - pub/sub (on/off/emit) — notifications JSON-RPC sans id
+ *  - request/response — RPC bidirectionnel typé
+ *  - streaming — chunks `{ id, stream: { chunk, done } }` pour LLM token-by-token
+ *
+ * Le backend WS de référence (RealtimeService) sera implémenté en P13.4.
+ * En attendant, ce client peut parler à n'importe quel serveur JSON-RPC 2.0.
+ */
+import { type NodefonyNotice, type IRealtimeDenied } from "./notice.js";
+import { type IRealtimePeer, type JsonRpcFrameKind } from "../../realtime/JsonRpcPeer.js";
+/**
+ * Enveloppe d'un appel {@link RealtimeClient.call} : la valeur rendue par la
+ * route, et l'identifiant du profil serveur de cette frame (dev — `null` en
+ * production, où le serveur n'émet aucune méta).
+ */
+export interface IApiCallResult<T = unknown> {
+    result: T;
+    requestId: string | null;
+}
+import { type RealtimeTransportFactory } from "../../realtime/IRealtimeTransport.js";
+import type { IRealtimeSocket, IRealtimeChannel, IChannelStats, RealtimeHandler } from "../../realtime/IRealtimeSocket.js";
+import type { ActionNames, ActionParams, ActionResult, ActionsMap, DefaultActionsMap, DefaultEventsMap, EventNames, EventPayload, EventsMap, RealtimeIdentity, TypedRpcActionHandler, ContractParams, ContractResult } from "../../realtime/RealtimeEventMap.js";
+import { type BindAdaptiveOptions, type AdaptiveChannelBinding } from "./AdaptiveRate.js";
+export { closeCodeToNotice, deniedToNotice, isReconnectableCloseCode, } from "./notice.js";
+export type { NodefonyNotice, NoticeLevel, IRealtimeDenied } from "./notice.js";
+export { RpcError } from "../../realtime/JsonRpcPeer.js";
+export type { RealtimeIdentity, IRealtimeWelcome, } from "../../realtime/RealtimeEventMap.js";
+export type RealtimeState = "disconnected" | "connecting" | "connected" | "reconnecting" | "error";
+export interface RealtimeOptions {
+    url?: string;
+    token?: string | null;
+    /** Reconnexion auto. Défaut: true. */
+    autoReconnect?: boolean;
+    /** Délai initial entre tentatives (ms). Défaut: 1000. */
+    reconnectDelay?: number;
+    /** Délai max entre tentatives (ms). Défaut: 30000. */
+    reconnectDelayMax?: number;
+    /** Heartbeat ping interval (ms). Défaut: 30000. */
+    heartbeatInterval?: number;
+    /**
+     * Annoncer le framework dans la console du navigateur ? Défaut : oui.
+     *
+     * Une socket qui vit NUE — sans noyau — est souvent tout ce qu'une page monte :
+     * sans cette annonce, elle ne dit rien d'elle-même et `nodefony` reste
+     * `undefined` dans la console, ce qui se lit « le framework n'est pas chargé ».
+     * `false` fait taire l'annonce ET le handle, pour une application publiée qui
+     * ne veut rien dans la console de ses utilisateurs.
+     */
+    banner?: boolean;
+}
+/**
+ * Stats d'un canal — alias historique de {@link IChannelStats} (le contrat isomorphe
+ * `IRealtimeSocket`). Conservé pour les consommateurs qui importent `MessageStats`.
+ */
+export type MessageStats = IChannelStats;
+/** Une frame du protocole temps réel (JSON-RPC 2.0) — pour le log/inspecteur. */
+export interface RealtimeFrame {
+    /** Timestamp (ms epoch). */
+    ts: number;
+    /** Sens : `out` = client→serveur, `in` = serveur→client. */
+    dir: "in" | "out";
+    /** Méthode (notification/requête) ou `response`/`error`/`stream`. */
+    kind: string;
+    /** id JSON-RPC (requêtes/réponses), si présent. */
+    id?: number;
+    /** Canal pub/sub (`params.channel`), si présent. */
+    channel?: string;
+    /** Payload affichable — champs sensibles **redactés** (token/secret…). */
+    payload: unknown;
+}
+/**
+ * Réponse de la méthode RPC standard `nodefony:kernel:ping` — CONVENTION Nodefony : tout
+ * endpoint realtime (Studio aujourd'hui, `RealtimeService` en P13.4) y répond.
+ * Sert de liveness + base de mesure du round-trip (cf {@link RealtimeClient.ping}).
+ */
+export interface KernelPingResult {
+    pong: true;
+    ts: number;
+    /** uptime process serveur (s). */
+    uptime: number;
+    pid: number;
+    version?: string;
+}
+/**
+ * Tentative de reconnexion programmée par le back-off — charge utile de
+ * {@link RealtimeClient.onReconnect}.
+ */
+export interface RealtimeReconnectInfo {
+    /** Numéro de la tentative depuis la dernière connexion réussie (1 = la première). */
+    attempt: number;
+    /** Délai retenu avant cette tentative (ms), plafonné par `reconnectDelayMax`. */
+    delay: number;
+    /** Échéance absolue de la tentative (ms epoch) — pour un compte à rebours. */
+    nextRetryAt: number;
+}
+export declare class RealtimeClient<Emit extends EventsMap = DefaultEventsMap, Listen extends EventsMap = DefaultEventsMap, Actions extends ActionsMap = DefaultActionsMap> implements IRealtimeSocket<Emit, Listen, Actions>, IRealtimePeer<Emit, Actions> {
+    private readonly opts;
+    private transport;
+    private readonly transportFactory;
+    private _state;
+    private readonly peer;
+    private readonly handlers;
+    private readonly _subscriptions;
+    private _welcomed;
+    private reconnectAttempt;
+    private _nextRetryAt;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private intentionalClose;
+    private readonly _stats;
+    private _framesReceived;
+    private _framesUnsent;
+    private _unsentNotified;
+    private _lastFrameAt;
+    private _lastFrameMethod;
+    private statsTimer;
+    private readonly _prevSampled;
+    private _rawFrames;
+    private _identity;
+    private _serverChannels;
+    private _serverMethods;
+    constructor(opts?: RealtimeOptions, transportFactory?: RealtimeTransportFactory);
+    /**
+     * Instance de connexion **partagée par URL** (résolue en absolu) sur
+     * `globalThis`. Plusieurs consommateurs d'une même page (ex. Studio + barre de
+     * debug) obtiennent la MÊME instance → **une seule socket** WebSocket. Les
+     * options ne s'appliquent qu'à la 1ʳᵉ création (les suivantes réutilisent).
+     *
+     * @param opts - options (au moins `url`), appliquées seulement à la création.
+     * @returns l'instance partagée pour cette URL.
+     */
+    static shared(opts?: RealtimeOptions): RealtimeClient;
+    /**
+     * Message d'une adresse manquante — LA seule formulation, employée par les
+     * deux chemins qui peuvent la constater.
+     *
+     * Il n'y a **pas** de valeur par défaut, et c'est délibéré : la route dépend
+     * de l'application, pas du framework. Deviner `/nodefony/api/realtime` — ce
+     * que faisait ce client — donnait une socket qui ne se connecte jamais et se
+     * contente de retenter, sans un mot. Un échec franc coûte trente secondes ;
+     * une socket silencieusement morte coûte une soirée.
+     */
+    private static missingUrl;
+    /** Résout une URL (relative ou absolue) en chaîne absolue stable = clé du singleton. */
+    private static resolveUrl;
+    get state(): RealtimeState;
+    /** Nombre de tentatives de reconnexion depuis la dernière connexion réussie. */
+    get reconnectAttempts(): number;
+    /**
+     * Timestamp (ms epoch) de la prochaine tentative de reconnexion planifiée,
+     * `null` hors backoff. Permet un compte à rebours UI synchronisé au vrai délai.
+     */
+    get nextRetryAt(): number | null;
+    /**
+     * Force une reconnexion **immédiate** (annule le backoff en cours). No-op si
+     * déjà connecté/connexion en cours.
+     */
+    retryNow(): void;
+    /**
+     * Ouvre la connexion WS. Idempotent — si déjà ouverte, no-op.
+     * Resolve une fois `connected` ou reject sur erreur fatale.
+     */
+    connect(url?: string): Promise<void>;
+    /** L'URL configurée, ou l'échec franc — jamais une valeur devinée. */
+    private requireUrl;
+    disconnect(): void;
+    /** Pub/sub local — handler sur un event server-pushed (notification JSON-RPC). */
+    on<K extends string>(event: K, handler: K extends EventNames<Listen> ? (payload: EventPayload<Listen, K>) => void : RealtimeHandler): () => void;
+    off<K extends string>(event: K, handler: K extends EventNames<Listen> ? (payload: EventPayload<Listen, K>) => void : RealtimeHandler): void;
+    /**
+     * S'abonne aux **notices normalisées** émises par le client : criticités qui
+     * cassent le temps réel (close codes RFC 6455 interprétés via
+     * {@link closeCodeToNotice}), erreurs serveur poussées, rétablissement de
+     * connexion. Réutilisable par toute app — le centre de notifications (snackbar
+     * Studio) s'y branche directement.
+     *
+     * @param handler - reçoit chaque {@link NodefonyNotice}.
+     * @returns dispose (désabonnement).
+     */
+    onNotice(handler: (notice: NodefonyNotice) => void): () => void;
+    /**
+     * S'abonne aux **refus de canal** poussés par le serveur (`realtime:denied`) :
+     * un `subscribe`/push vers un canal protégé sans droit suffisant. Permet une
+     * réaction CIBLÉE par canal (griser un contrôle, demander une élévation),
+     * complémentaire de {@link onNotice} (UX générique). Event LOCAL `__denied__`.
+     *
+     * Polymorphisme CLIENT : la réaction est pluggable ici ; l'AUTORITÉ reste
+     * serveur (le firewall a déjà décidé, le motif est générique — pas d'oracle).
+     *
+     * @param handler - reçoit `{ channel, reason }`.
+     * @returns dispose (désabonnement).
+     */
+    onDenied(handler: (denied: IRealtimeDenied) => void): () => void;
+    /**
+     * Notification one-way client → server (pas de réponse attendue).
+     *
+     * C'est la SEULE émission dont personne n'apprend l'échec autrement : une
+     * requête corrélée est rejetée, un (dés)abonnement est rejoué au reconnect —
+     * une notification applicative perdue, elle, ne laisse aucune trace. Si le
+     * transport est fermé, l'utilisateur en est donc averti (une fois par épisode
+     * de coupure, cf {@link send}).
+     */
+    emit<K extends string>(method: K, params?: K extends EventNames<Emit> ? EventPayload<Emit, K> : unknown): void;
+    /**
+     * Émission interne sans typage strict — utilisée pour les notifications système
+     * (`subscribe`, `unsubscribe`, `ping`) qui ne figurent pas dans la map `Emit`
+     * utilisateur. Bypasse les types conditionnels de {@link emit}.
+     *
+     * Ces frames-là **ne préviennent pas** l'utilisateur quand elles se perdent :
+     * les abonnements sont rejoués à la reconnexion et le heartbeat est arrêté
+     * avec les timers. Avertir ferait paraître comme une perte ce que le client
+     * rattrape tout seul — du bruit dans le centre de notifications d'une app qui
+     * monte et démonte des vues (le cas de Studio).
+     *
+     * @returns `false` si le transport n'a pas émis la frame.
+     */
+    private _emitRaw;
+    /**
+     * Émet sur un canal — verbe socket de {@link IRealtimeSocket.publish}. Côté client =
+     * notification au serveur (alias clair de {@link emit}).
+     */
+    publish<K extends string>(channel: K, payload?: K extends EventNames<Emit> ? EventPayload<Emit, K> : unknown): void;
+    /**
+     * S'abonne à un canal pub/sub serveur (**ref-compté**). Émet la notification
+     * `subscribe` au serveur UNIQUEMENT au 1er consommateur du canal ; les suivants
+     * ne font qu'incrémenter le compteur. Ré-émis automatiquement à chaque
+     * `realtime:welcome` — jamais à la simple ouverture de la socket, où le serveur
+     * le jetterait sans un mot. NE remplace PAS {@link on} : `on(channel, h)` REÇOIT les
+     * messages, `subscribe(channel)` DEMANDE au serveur de les pousser.
+     *
+     * Autorité unique partagée par le binding `nodefony/react` ET le store Studio →
+     * deux consommateurs du même canal ne se coupent plus l'un l'autre.
+     */
+    subscribe(channel: EventNames<Listen> | (string & {})): void;
+    /**
+     * Désabonne un consommateur d'un canal (ref-compté) : émet `unsubscribe` au
+     * serveur seulement au **dernier** consommateur. No-op si le canal n'est pas suivi.
+     */
+    unsubscribe(channel: EventNames<Listen> | (string & {})): void;
+    /** Canaux actuellement abonnés (≥ 1 consommateur). Lecture seule. */
+    get subscribedChannels(): string[];
+    /**
+     * L'adresse du serveur temps réel, telle qu'elle a été donnée (ou résolue en
+     * absolu par {@link shared}). `null` tant qu'aucune n'a été fournie — le
+     * framework n'en devine aucune.
+     *
+     * Publiée pour l'auto-observation : un instantané de socket qui ne dit pas DE
+     * QUELLE socket il parle ne sert à rien dès qu'une page en tient plus d'une.
+     */
+    get url(): string | null;
+    /**
+     * Identité de la connexion, **annoncée par le serveur** au `realtime:welcome`
+     * ({@link RealtimeIdentity}). `null` tant qu'aucun welcome n'a été reçu ; une
+     * fois reçu, un visiteur anonyme a `authenticated: false` (jamais `null`). Un
+     * consommateur (Studio) sait ainsi s'il doit afficher le login **sans taper de
+     * route**. Rafraîchie à chaque (re)connexion ; remise à `null` au
+     * {@link disconnect} volontaire (logout).
+     */
+    get identity(): RealtimeIdentity | null;
+    /** Canaux pub/sub annoncés par le serveur au welcome (découverte). `null` si pas (encore) reçu. */
+    get serverChannels(): readonly string[] | null;
+    /** Actions RPC annoncées par le serveur au welcome (découverte). `null` si pas (encore) reçu. */
+    get serverMethods(): readonly string[] | null;
+    /**
+     * S'abonne à l'identité résolue (event LOCAL `__identity__`, jamais réseau) :
+     * le handler est rappelé à chaque (re)welcome et au `disconnect()`. Permet à
+     * l'UI de basculer anonyme↔authentifié sans polling ni route `/auth/me`.
+     *
+     * @param handler - reçoit la {@link RealtimeIdentity} courante (ou `null`).
+     * @returns dispose (désabonnement).
+     */
+    onIdentity(handler: (identity: RealtimeIdentity | null) => void): () => void;
+    /**
+     * S'abonne à l'**état de la connexion** (event LOCAL `__state__`, jamais réseau) :
+     * le handler est rappelé à chaque transition (`connecting`, `connected`,
+     * `reconnecting`, `error`, `disconnected`), jamais pour un état inchangé.
+     *
+     * C'est la porte à employer partout — un badge de connexion, une liaison de vue,
+     * une barre de debug. Écrire `on("__state__", …)` en clair marche aussi, mais
+     * recopie un nom d'événement interne dans du code applicatif : c'est ce qui a
+     * fait diverger les trois gabarits d'application.
+     *
+     * @param handler - reçoit le nouvel {@link RealtimeState}.
+     * @returns dispose (désabonnement).
+     */
+    onState(handler: (state: RealtimeState) => void): () => void;
+    /**
+     * S'abonne au **tick d'échantillonnage des statistiques** (event LOCAL
+     * `__stats__`, jamais réseau), émis une fois par seconde après recalcul des
+     * débits par canal. Sans charge utile : lire ensuite {@link getChannelStats}
+     * ou {@link getStats}, dont les valeurs viennent d'être rafraîchies.
+     *
+     * @param handler - appelé à chaque échantillon.
+     * @returns dispose (désabonnement).
+     */
+    onStats(handler: () => void): () => void;
+    /**
+     * S'abonne aux **tentatives de reconnexion programmées** (event LOCAL
+     * `__reconnect__`, jamais réseau) : numéro d'essai, délai retenu par le
+     * back-off, et échéance absolue. De quoi afficher un compte à rebours plutôt
+     * qu'un « déconnecté » muet.
+     *
+     * @param handler - reçoit `{ attempt, delay, nextRetryAt }`.
+     * @returns dispose (désabonnement).
+     */
+    onReconnect(handler: (info: RealtimeReconnectInfo) => void): () => void;
+    /**
+     * Handle « socket-like » d'un canal ({@link IRealtimeChannel}) — fine liaison sur
+     * les primitives (`subscribe`/`on`/`publish`/`unsubscribe`), forme naturelle des
+     * canaux à état (SIP, bridge) et point d'accroche des couches à venir (codec,
+     * cadence, politique). N'ouvre rien : appeler `.open()` pour s'abonner. `kind` reste
+     * indéfini côté client tant que le serveur ne l'annonce pas.
+     */
+    channel(name: string): IRealtimeChannel;
+    /**
+     * S'abonne à un canal d'ÉTAT en **cadence adaptative** (AIMD client-driven) : la lib
+     * mesure la gigue d'arrivée et ré-abonne automatiquement à une cadence plus grossière en
+     * cas de famine, plus fine quand c'est sain — sans changement serveur. `handler` reçoit
+     * les frames à travers les changements de cadence. Réservé aux canaux latest-wins.
+     *
+     * @param base - canal de base (sans suffixe de cadence).
+     * @param handler - reçoit le payload de chaque frame.
+     * @param options - cadence désirée + réglages AIMD (cf {@link BindAdaptiveOptions}).
+     * @returns une poignée {@link AdaptiveChannelBinding} (cadence courante + `dispose`).
+     */
+    adaptiveChannel(base: string, handler: RealtimeHandler, options: BindAdaptiveOptions): AdaptiveChannelBinding;
+    /**
+     * Requête API par **path** — la MÊME action controller que le GET REST, via
+     * la socket (« API souveraine » : 1 action = N transports). Sucre au-dessus
+     * de la méthode RPC `api.request` (protocole caché — convention dans la lib,
+     * comme `nodefony:kernel:ping`/`ping()`) :
+     * ```ts
+     * const modules = await socket.request("/nodefony/kernel/api/modules");
+     * ```
+     * Échec → rejet {@link RpcError} (`data.status` = statut HTTP équivalent :
+     * 404 path inconnu, 403 refus…). Un path commence toujours par `/`, une
+     * méthode JSON-RPC jamais → zéro collision avec la forme `request(method)`.
+     */
+    request<T = unknown>(path: `/${string}`, timeoutMs?: number): Promise<T>;
+    /**
+     * Request/response JSON-RPC 2.0 — `Promise` résolue avec le `result`.
+     *
+     * Le 1ᵉʳ générique est le **nom de la méthode**, le 2ᵉ le type du résultat :
+     * ```ts
+     * const r = await socket.request<"nodefony:kernel:ping", { pong: boolean }>(
+     *   "nodefony:kernel:ping",
+     * );
+     * ```
+     * Quand `method` appartient au contrat `Actions`, `params` ET le résultat en
+     * sont déduits — un payload hors contrat est REFUSÉ à la compilation.
+     *
+     * ⚠️ **Rupture 10.0.0** : la forme `request<MonType>("ma:methode")` (`<T>` =
+     * résultat) n'existe plus. Elle était un attrape-tout qui rendait inopérant le
+     * contrôle des `params`. La réécrire en `request<"ma:methode", MonType>`.
+     */
+    request<K extends string, T = unknown>(method: K, params?: ContractParams<Actions, K>, timeoutMs?: number): Promise<ContractResult<Actions, K, T>>;
+    /**
+     * Contrat {@link IRealtimePeer} rendu EXPLICITE — `method` et `params` sont
+     * tous deux bornés par le contrat `Actions`. Sans elle, la liste de surcharges
+     * (qui type `params` par un conditionnel non résolu) n'est pas assignable à la
+     * signature du peer et TS2416 tombe.
+     */
+    request<K extends ActionNames<Actions>>(method: K, params?: ActionParams<Actions, K>, timeoutMs?: number): Promise<ActionResult<Actions, K>>;
+    /**
+     * **Mutation** API par le pont `api.request` (POST/PUT/PATCH/DELETE) — pendant
+     * d'écriture de {@link request} (qui ne fait que des lectures GET). Transporte
+     * la méthode HTTP **logique**, le corps, et une **clé d'idempotence**
+     * (OBLIGATOIRE côté serveur : une socket reconnecte et peut rejouer une frame
+     * en vol → la clé dédoublonne le rejeu, anti double-effet) :
+     * ```ts
+     * await socket.mutate("/nodefony/security/api/apikeys/42/revoke", {
+     *   method: "POST", idempotencyKey: crypto.randomUUID(),
+     * });
+     * ```
+     * Échec → rejet {@link RpcError} (`data.status` = statut HTTP équivalent :
+     * 400 clé absente, 409 rejeu concurrent, 403 refus, 404 path inconnu…).
+     */
+    mutate<T = unknown>(path: `/${string}`, init: {
+        method: "POST" | "PUT" | "PATCH" | "DELETE";
+        body?: unknown;
+        idempotencyKey: string;
+        timeoutMs?: number;
+    }): Promise<T>;
+    /**
+     * Appel API par la socket rendant l'**enveloppe complète** — le résultat ET
+     * la méta serveur — là où {@link request}/{@link mutate} ne rendent que la
+     * valeur (forme courante, contrat « snapshot ≡ GET REST »).
+     *
+     * Utile à l'outillage plus qu'aux applications : en développement, le serveur
+     * joint le `requestId` du profil de CETTE frame, ce qui permet d'aller lire sa
+     * radiographie (`GET /nodefony/profiler/api/{requestId}` — phases, SQL,
+     * décision du firewall). En production le serveur n'émet aucune méta :
+     * `requestId` vaut alors `null`, et l'appel coûte exactement le même trafic.
+     *
+     * ```ts
+     * const { result, requestId } = await socket.call("/nodefony/kernel/api/modules");
+     * ```
+     *
+     * Échec → rejet {@link RpcError}, comme {@link request} ; l'id du profil, lui,
+     * voyage dans `error.data.requestId` (un refus se radiographie aussi).
+     *
+     * @param path - chemin de la route (transport WEBSOCKET requis côté serveur).
+     * @param init - méthode logique (défaut `GET`), corps, clé d'idempotence.
+     */
+    call<T = unknown>(path: `/${string}`, init?: {
+        method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+        body?: unknown;
+        idempotencyKey?: string;
+        timeoutMs?: number;
+    }): Promise<IApiCallResult<T>>;
+    /**
+     * Mesure le round-trip WS via la méthode RPC standard `nodefony:kernel:ping` — helper
+     * RÉUTILISABLE par tout consommateur (topbar Studio, debug bar, app user) :
+     * la mesure du RTT et la convention `nodefony:kernel:ping` vivent dans la lib cliente,
+     * pas dupliquées dans chaque front. Renvoie le payload serveur enrichi de `rtt`
+     * (ms, aller-retour mesuré côté client). Lève si le serveur ne répond pas
+     * (`request` timeout) ou ne connaît pas la méthode (`-32601`).
+     */
+    ping(timeoutMs?: number): Promise<KernelPingResult & {
+        rtt: number;
+    }>;
+    /** Notification SORTANTE typée (pas de réponse). Pendant de {@link emit}/{@link publish}. */
+    notify<K extends EventNames<Emit>>(method: K, params?: EventPayload<Emit, K>): void;
+    /**
+     * Expose une action appelable PAR LE PAIR (requête entrante serveur→client).
+     * Cœur du duplex débloqué par L0 : sans handler, une requête entrante reçoit
+     * `-32601` ; avec, le `result` repart au serveur (confirmation d'action,
+     * invalidation de cache poussée, health applicatif serveur→client).
+     */
+    register<K extends ActionNames<Actions>>(method: K, handler: TypedRpcActionHandler<Actions, K>): void;
+    /** Retire une action exposée. */
+    unregister<K extends ActionNames<Actions>>(method: K): void;
+    /** Actions exposées par CE client (découverte). ≠ {@link serverMethods} (côté serveur). */
+    get methods(): string[];
+    /**
+     * Ingestion d'une frame ENTRANTE déjà parsée → log + classification/route par le
+     * moteur. Renvoie sa nature. Une frame `invalid` peut porter une erreur GLOBALE
+     * serveur (`{jsonrpc, error}` hors spec JSON-RPC) → notice (cf {@link handleServerError}).
+     */
+    receive(frame: unknown): JsonRpcFrameKind;
+    /** Annule les requêtes sortantes en attente (fermeture transport / logout). */
+    dispose(reason?: string): void;
+    /** Total de notifications reçues, tous canaux confondus (welcome inclus). */
+    get framesReceived(): number;
+    /**
+     * Total de frames qui n'ont **pas** pu partir depuis la création du client
+     * (transport fermé au moment de l'émission). Reste à `0` en fonctionnement
+     * normal ; toute valeur non nulle date d'une coupure ou d'une émission
+     * antérieure à la première connexion.
+     */
+    get framesUnsent(): number;
+    /** Timestamp (ms) de la dernière notification reçue. */
+    get lastFrameAt(): number | null;
+    /** `method`/canal de la dernière notification reçue. */
+    get lastFrameMethod(): string | null;
+    /** Snapshot des stats par canal (msgCount/rate/series). Les objets sont les
+     *  refs internes — à LIRE, pas à muter (copier les valeurs si besoin). */
+    getStats(): MessageStats[];
+    /** Stats d'un canal précis (== method JSON-RPC) ou `undefined`. */
+    getChannelStats(method: string): MessageStats | undefined;
+    /** Comptabilise une notification entrante (avant dispatch aux handlers). */
+    private trackFrame;
+    /**
+     * (Ré)émet un `subscribe` pour chaque canal ref-compté, à la réception du
+     * `realtime:welcome` — le seul instant où le serveur est prêt à l'enregistrer.
+     *
+     * Ouvrir la socket ne suffit pas : pendant que le serveur authentifie, son
+     * transport JSON-RPC n'est pas encore branché et il **jette** les frames
+     * entrantes, sans pouvoir répondre — c'est le contrat écrit par
+     * `RealtimeController.handleRealtime`. Rejouer sur `onOpen` revenait à parler
+     * dans le vide, et perdait en silence deux cas entiers : un `subscribe` posé
+     * avant `start()`, et TOUS les abonnements après une reconnexion.
+     *
+     * Cold path (1×/connexion) : ne parcourt que les canaux réellement suivis, et
+     * n'alloue rien.
+     */
+    private replaySubscriptions;
+    /**
+     * Ingère le `realtime:welcome` : mémorise l'identité résolue + les capabilities
+     * annoncées (canaux/actions découvrables) et émet `__identity__`. Tolérant à un
+     * welcome partiel/legacy (champs absents → `null`). Cold path (1×/connexion).
+     */
+    private ingestWelcome;
+    /**
+     * Détail de la socket dans la console — le pendant, pour une page SANS noyau,
+     * du groupe que le noyau émet quand il y en a un (#136).
+     *
+     * Une vitrine ne compose rien : sans ceci, elle n'a aucun endroit où lire son
+     * adresse, ses canaux ou son identité, alors que c'est exactement ce qu'on
+     * cherche quand une socket ne pousse rien. Émis au premier accueil, une seule
+     * fois par page, et jamais en production.
+     */
+    private detailsSocket;
+    /**
+     * Ingère un `realtime:denied` (refus d'abonnement/push poussé par le serveur) :
+     * émet une notice normalisée ({@link onNotice}) ET un event ciblé `__denied__`
+     * ({@link onDenied}) pour une réaction polymorphe de l'app. Tolérant à un
+     * payload partiel (motif par défaut `forbidden`). Cold path (refus rare).
+     */
+    private ingestDenied;
+    /**
+     * Dispatch d'une NOTIFICATION entrante — appelé par le moteur via `onNotification`.
+     * Ordre figé : ingestion welcome (1ʳᵉ frame) → stats → handlers locaux + wildcard
+     * (un handler `on("realtime:welcome")` voit donc l'identité déjà ingérée).
+     */
+    private dispatchNotification;
+    /**
+     * Frame `invalid` (JSON-RPC strict) portant un `error` sans `id`/`method` = erreur
+     * GLOBALE serveur (extension Nodefony hors spec, ex. refus tardif) → notice pour le
+     * centre de notifications. Frame réellement malformée (sans `.error`) → no-op.
+     */
+    private handleServerError;
+    /** Échantillonne le débit (msg/s) + série par canal, 1×/s, puis émet
+     *  `__stats__` (event local) pour notifier les consommateurs réactifs. */
+    private startStatsSampler;
+    /** Émet une notice normalisée aux abonnés `onNotice` (event local, pas réseau). */
+    private fireNotice;
+    /** Déclenche les handlers locaux d'un event interne (pas d'envoi réseau). */
+    private fireLocal;
+    private openSocket;
+    private scheduleReconnect;
+    private startHeartbeat;
+    private clearTimers;
+    /**
+     * Log protocole : les `FRAME_LOG_MAX` dernières frames JSON-RPC (redactées),
+     * enregistrées EN CONTINU → la console « retrace l'instant » dès l'ouverture
+     * (jamais de démarrage à vide). Construction + redaction faites ici, à la lecture.
+     */
+    get frameLog(): readonly RealtimeFrame[];
+    /** Purge le log protocole. */
+    clearFrameLog(): void;
+    /**
+     * Enregistre une frame dans le ring — coût = 1 push de réf (construction +
+     * redaction DIFFÉRÉES). Émet `__frame__` (frame construite) seulement si la
+     * console écoute.
+     */
+    private recordFrame;
+    /** Construit une frame affichable (kind/canal/id + payload redacté). */
+    private static buildFrame;
+    /**
+     * Émet une frame si — et seulement si — le transport est ouvert.
+     *
+     * La frame n'est **pas** mise en file d'attente : rejouer une intention après
+     * coup peut être pire que la perdre (une commande obsolète appliquée en
+     * retard, un abonnement rétabli sur un écran déjà quitté). Ce qui n'est plus
+     * accepté, c'est de la perdre **en silence** — l'appelant reçoit `false`, une
+     * requête corrélée est rejetée aussitôt par {@link JsonRpcPeer} plutôt qu'au
+     * bout de son timeout, et l'utilisateur est prévenu une fois par épisode.
+     *
+     * @param msg - la frame JSON-RPC à sérialiser.
+     * @returns `true` si la frame est partie, `false` si le transport était fermé.
+     */
+    private send;
+    /**
+     * Avertit que des notifications applicatives se perdent — **une fois par
+     * épisode** de coupure, jamais par frame : une vue qui pousse en boucle
+     * remplirait sinon le centre de notifications à elle seule.
+     *
+     * Appelé depuis {@link emit} uniquement. Les requêtes corrélées et les
+     * (dés)abonnements ont déjà leur propre voie (rejet, rejeu au reconnect).
+     */
+    private noticeUnsent;
+    private handleMessage;
+    private setState;
+}
+export default RealtimeClient;

package/dist/client/types/src/client/realtime/localEvents.d.ts

@@ -0,0 +1,53 @@
+/**
+ * localEvents — **noms des événements LOCAUX du client temps réel**.
+ *
+ * Ces six noms ne voyagent jamais sur le fil : ils ne servent qu'à propager, dans
+ * la page, ce que le client vient d'apprendre (changement d'état de connexion,
+ * identité résolue au welcome, échantillon de statistiques, notice normalisée,
+ * refus de canal). Ils partagent la table de `on()`/`off()` avec les canaux
+ * réseau ; le double soulignement est ce qui les en distingue.
+ *
+ * **La table est la source unique**, exactement pour la même raison que
+ * {@link PLATFORM_CHANNELS} l'est pour les canaux réseau : une chaîne recopiée
+ * dans un écran est une chaîne qui survivra au renommage suivant. Celle-ci avait
+ * déjà divergé — `"__state__"` était écrit en clair dans les trois gabarits
+ * d'application, dans la barre de debug et dans la console d'administration,
+ * sans qu'aucune constante ne l'exporte.
+ *
+ * Un consommateur n'a d'ailleurs pas à les connaître : `onState`, `onIdentity`,
+ * `onStats`, `onNotice`, `onDenied` et `onReconnect` sont les portes publiques. La table existe
+ * pour les implémentations (le client lui-même, ses observateurs agnostiques) et
+ * pour un test qui veut se brancher au plus bas niveau.
+ *
+ * Pur et isomorphe (aucun import, aucune allocation).
+ */
+/**
+ * Événements locaux du {@link RealtimeClient} — jamais émis ni reçus par le réseau.
+ *
+ * @see {@link RealtimeClient.onState} · {@link RealtimeClient.onIdentity} ·
+ *   {@link RealtimeClient.onStats} · {@link RealtimeClient.onNotice} ·
+ *   {@link RealtimeClient.onDenied} — les portes publiques à préférer partout.
+ */
+export declare const LOCAL_EVENTS: {
+    /** État de la connexion (`"connected" | "reconnecting" | …`), à chaque transition. */
+    readonly state: "__state__";
+    /** Identité résolue par le serveur au welcome ; `null` après un `disconnect()`. */
+    readonly identity: "__identity__";
+    /** Tick d'échantillonnage des statistiques par canal (1×/s), sans charge utile. */
+    readonly stats: "__stats__";
+    /** Notice normalisée (criticité temps réel interprétée). */
+    readonly notice: "__notice__";
+    /** Refus d'un canal poussé par le serveur (`realtime:denied`). */
+    readonly denied: "__denied__";
+    /** Tentative de reconnexion programmée (numéro d'essai, délai, échéance). */
+    readonly reconnect: "__reconnect__";
+};
+/** Un des noms d'événement local de la table {@link LOCAL_EVENTS}. */
+export type LocalEvent = (typeof LOCAL_EVENTS)[keyof typeof LOCAL_EVENTS];
+/**
+ * Vrai si `event` est un événement local du client (jamais un canal réseau).
+ *
+ * Sert aux couches qui inspectent la table des abonnements — une barre de debug,
+ * un inventaire de canaux — et qui doivent écarter ce qui n'est pas du trafic.
+ */
+export declare function isLocalEvent(event: string): event is LocalEvent;