nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/client/client/realtime/RealtimeClient.js

@@ -0,0 +1,898 @@
+import { closeCodeToNotice, deniedToNotice, isReconnectableCloseCode } from "./notice.js";
+import { JsonRpcPeer } from "../../realtime/JsonRpcPeer.js";
+import { LOCAL_EVENTS } from "./localEvents.js";
+import { TransportState } from "../../realtime/IRealtimeTransport.js";
+import { BrowserWsTransport } from "./BrowserWsTransport.js";
+import { announceRealtime, consoleDetails, hasKernel, noteServerEnv } from "../announce.js";
+import { bindAdaptiveChannel } from "./AdaptiveRate.js";
+import { PLATFORM_METHODS } from "../../realtime/platformChannels.js";
+//#region src/client/realtime/RealtimeClient.ts
+/**
+* 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.
+*/
+/** Taille max du ring du log protocole (inspecteur realtime). */
+const FRAME_LOG_MAX = 300;
+/** Clés sensibles masquées dans le log protocole (sécurité — jamais de secret en clair). */
+const FRAME_REDACT_RE = /(token|password|secret|api[_-]?key|apikey|authorization|bearer)/i;
+/** Copie d'un payload JSON-RPC avec masquage des champs sensibles (bornée en profondeur). */
+function redactFrame(value, depth = 0) {
+	if (depth > 4 || value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map((v) => redactFrame(v, depth + 1));
+	const out = {};
+	for (const [k, v] of Object.entries(value)) out[k] = FRAME_REDACT_RE.test(k) ? "[redacted]" : redactFrame(v, depth + 1);
+	return out;
+}
+var RealtimeClient = class RealtimeClient {
+	opts;
+	transport = null;
+	transportFactory;
+	_state = "disconnected";
+	peer = new JsonRpcPeer({
+		send: (frame) => this.send(frame),
+		onNotification: (method, params) => this.dispatchNotification(method, params)
+	});
+	handlers = /* @__PURE__ */ new Map();
+	_subscriptions = /* @__PURE__ */ new Map();
+	_welcomed = false;
+	reconnectAttempt = 0;
+	_nextRetryAt = null;
+	reconnectTimer = null;
+	heartbeatTimer = null;
+	intentionalClose = false;
+	_stats = /* @__PURE__ */ new Map();
+	_framesReceived = 0;
+	_framesUnsent = 0;
+	_unsentNotified = true;
+	_lastFrameAt = null;
+	_lastFrameMethod = null;
+	statsTimer = null;
+	_prevSampled = /* @__PURE__ */ new Map();
+	_rawFrames = null;
+	_identity = null;
+	_serverChannels = null;
+	_serverMethods = null;
+	constructor(opts = {}, transportFactory) {
+		this.opts = opts;
+		this.transportFactory = transportFactory ?? ((url) => new BrowserWsTransport(url));
+		this.startStatsSampler();
+		announceRealtime(this.opts.banner);
+	}
+	/**
+	* 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 = {}) {
+		const key = RealtimeClient.resolveUrl(opts.url);
+		const g = globalThis;
+		const map = g.__nfRealtime__ ??= /* @__PURE__ */ new Map();
+		let client = map.get(key);
+		if (!client) {
+			client = new RealtimeClient({
+				...opts,
+				url: key
+			});
+			map.set(key, client);
+		}
+		return client;
+	}
+	/**
+	* 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.
+	*/
+	static missingUrl() {
+		return /* @__PURE__ */ new Error("[nodefony] adresse du serveur temps réel manquante.\n  Donne-la explicitement : RealtimeClient.shared({ url: \"/api/live/realtime\" })\n  ou, en React : <NodefonyProvider url=\"/api/live/realtime\">\n  Il n'y a pas de valeur par défaut : la route dépend de ton application (une application générée monte /api/live/realtime, la console d'administration /nodefony/studio/api/realtime).");
+	}
+	/** Résout une URL (relative ou absolue) en chaîne absolue stable = clé du singleton. */
+	static resolveUrl(url) {
+		if (!url) throw RealtimeClient.missingUrl();
+		if (typeof window === "undefined") return url;
+		try {
+			const u = new URL(url, window.location.href);
+			if (u.protocol === "http:") u.protocol = "ws:";
+			else if (u.protocol === "https:") u.protocol = "wss:";
+			return u.toString();
+		} catch {
+			throw new Error(`[nodefony] adresse du serveur temps réel illisible : ${JSON.stringify(url)}`);
+		}
+	}
+	get state() {
+		return this._state;
+	}
+	/** Nombre de tentatives de reconnexion depuis la dernière connexion réussie. */
+	get reconnectAttempts() {
+		return this.reconnectAttempt;
+	}
+	/**
+	* 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() {
+		return this._nextRetryAt;
+	}
+	/**
+	* Force une reconnexion **immédiate** (annule le backoff en cours). No-op si
+	* déjà connecté/connexion en cours.
+	*/
+	retryNow() {
+		if (this._state === "connected" || this._state === "connecting") return;
+		if (this.reconnectTimer) {
+			clearTimeout(this.reconnectTimer);
+			this.reconnectTimer = null;
+		}
+		this._nextRetryAt = null;
+		this.intentionalClose = false;
+		this.openSocket().catch(() => {});
+	}
+	/**
+	* Ouvre la connexion WS. Idempotent — si déjà ouverte, no-op.
+	* Resolve une fois `connected` ou reject sur erreur fatale.
+	*/
+	async connect(url) {
+		if (this._state === "connected" || this._state === "connecting") return;
+		this.intentionalClose = false;
+		this.opts.url = url ?? this.requireUrl();
+		return this.openSocket();
+	}
+	/** L'URL configurée, ou l'échec franc — jamais une valeur devinée. */
+	requireUrl() {
+		if (!this.opts.url) throw RealtimeClient.missingUrl();
+		return this.opts.url;
+	}
+	disconnect() {
+		this.intentionalClose = true;
+		this.clearTimers();
+		this.transport?.close(1e3, "client disconnect");
+		this.peer.dispose("client disconnect");
+		this._welcomed = false;
+		this._identity = null;
+		this._serverChannels = null;
+		this._serverMethods = null;
+		this.fireLocal(LOCAL_EVENTS.identity, null);
+		this.setState("disconnected");
+	}
+	/** Pub/sub local — handler sur un event server-pushed (notification JSON-RPC). */
+	on(event, handler) {
+		if (!this.handlers.has(event)) this.handlers.set(event, /* @__PURE__ */ new Set());
+		this.handlers.get(event).add(handler);
+		return () => this.off(event, handler);
+	}
+	off(event, handler) {
+		this.handlers.get(event)?.delete(handler);
+	}
+	/**
+	* 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) {
+		return this.on(LOCAL_EVENTS.notice, handler);
+	}
+	/**
+	* 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) {
+		return this.on(LOCAL_EVENTS.denied, handler);
+	}
+	/**
+	* 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(method, params) {
+		if (!this._emitRaw(method, params)) this.noticeUnsent();
+	}
+	/**
+	* É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.
+	*/
+	_emitRaw(method, params) {
+		return this.peer.notify(method, params);
+	}
+	/**
+	* Émet sur un canal — verbe socket de {@link IRealtimeSocket.publish}. Côté client =
+	* notification au serveur (alias clair de {@link emit}).
+	*/
+	publish(channel, payload) {
+		this.emit(channel, payload);
+	}
+	/**
+	* 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) {
+		const c = channel;
+		const n = (this._subscriptions.get(c) ?? 0) + 1;
+		this._subscriptions.set(c, n);
+		if (n === 1 && this._welcomed) this._emitRaw("subscribe", { channel: c });
+	}
+	/**
+	* 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) {
+		const c = channel;
+		const cur = this._subscriptions.get(c);
+		if (!cur) return;
+		if (cur <= 1) {
+			this._subscriptions.delete(c);
+			if (this._welcomed) this._emitRaw("unsubscribe", { channel: c });
+		} else this._subscriptions.set(c, cur - 1);
+	}
+	/** Canaux actuellement abonnés (≥ 1 consommateur). Lecture seule. */
+	get subscribedChannels() {
+		return Array.from(this._subscriptions.keys());
+	}
+	/**
+	* 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() {
+		return this.opts.url ?? 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() {
+		return this._identity;
+	}
+	/** Canaux pub/sub annoncés par le serveur au welcome (découverte). `null` si pas (encore) reçu. */
+	get serverChannels() {
+		return this._serverChannels;
+	}
+	/** Actions RPC annoncées par le serveur au welcome (découverte). `null` si pas (encore) reçu. */
+	get serverMethods() {
+		return this._serverMethods;
+	}
+	/**
+	* 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) {
+		return this.on(LOCAL_EVENTS.identity, handler);
+	}
+	/**
+	* 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) {
+		return this.on(LOCAL_EVENTS.state, handler);
+	}
+	/**
+	* 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) {
+		return this.on(LOCAL_EVENTS.stats, handler);
+	}
+	/**
+	* 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) {
+		return this.on(LOCAL_EVENTS.reconnect, handler);
+	}
+	/**
+	* 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) {
+		const hub = this;
+		const disposers = /* @__PURE__ */ new Set();
+		return {
+			name,
+			on(handler) {
+				const dispose = hub.on(name, handler);
+				disposers.add(dispose);
+				return () => {
+					dispose();
+					disposers.delete(dispose);
+				};
+			},
+			send(payload) {
+				hub.publish(name, payload);
+			},
+			open() {
+				hub.subscribe(name);
+			},
+			close() {
+				for (const d of disposers) d();
+				disposers.clear();
+				hub.unsubscribe(name);
+			}
+		};
+	}
+	/**
+	* 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, handler, options) {
+		return bindAdaptiveChannel(this, base, handler, options);
+	}
+	async request(method, params, timeoutMs = 3e4) {
+		if (method.charCodeAt(0) === 47) {
+			if (typeof params === "number") timeoutMs = params;
+			params = { path: method };
+			method = "api.request";
+		}
+		return this.peer.request(method, params, timeoutMs);
+	}
+	/**
+	* **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…).
+	*/
+	async mutate(path, init) {
+		return this.peer.request("api.request", {
+			path,
+			method: init.method,
+			body: init.body,
+			idempotencyKey: init.idempotencyKey
+		}, init.timeoutMs ?? 3e4);
+	}
+	/**
+	* 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.
+	*/
+	async call(path, init) {
+		const { result, meta } = await this.peer.requestTraced("api.request", {
+			path,
+			method: init?.method ?? "GET",
+			body: init?.body,
+			idempotencyKey: init?.idempotencyKey
+		}, init?.timeoutMs ?? 3e4);
+		return {
+			result,
+			requestId: typeof meta?.requestId === "string" ? meta.requestId : null
+		};
+	}
+	/**
+	* 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`).
+	*/
+	async ping(timeoutMs = 5e3) {
+		const now = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+		const t0 = now();
+		return {
+			...await this.request(PLATFORM_METHODS.ping, void 0, timeoutMs),
+			rtt: Math.round(now() - t0)
+		};
+	}
+	/** Notification SORTANTE typée (pas de réponse). Pendant de {@link emit}/{@link publish}. */
+	notify(method, params) {
+		this.peer.notify(method, params);
+	}
+	/**
+	* 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(method, handler) {
+		this.peer.register(method, handler);
+	}
+	/** Retire une action exposée. */
+	unregister(method) {
+		this.peer.unregister(method);
+	}
+	/** Actions exposées par CE client (découverte). ≠ {@link serverMethods} (côté serveur). */
+	get methods() {
+		return this.peer.methods;
+	}
+	/**
+	* 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) {
+		this.recordFrame("in", frame);
+		const kind = this.peer.receive(frame);
+		if (kind === "invalid") this.handleServerError(frame);
+		return kind;
+	}
+	/** Annule les requêtes sortantes en attente (fermeture transport / logout). */
+	dispose(reason) {
+		this.peer.dispose(reason);
+	}
+	/** Total de notifications reçues, tous canaux confondus (welcome inclus). */
+	get framesReceived() {
+		return this._framesReceived;
+	}
+	/**
+	* 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() {
+		return this._framesUnsent;
+	}
+	/** Timestamp (ms) de la dernière notification reçue. */
+	get lastFrameAt() {
+		return this._lastFrameAt;
+	}
+	/** `method`/canal de la dernière notification reçue. */
+	get lastFrameMethod() {
+		return this._lastFrameMethod;
+	}
+	/** Snapshot des stats par canal (msgCount/rate/series). Les objets sont les
+	*  refs internes — à LIRE, pas à muter (copier les valeurs si besoin). */
+	getStats() {
+		return Array.from(this._stats.values());
+	}
+	/** Stats d'un canal précis (== method JSON-RPC) ou `undefined`. */
+	getChannelStats(method) {
+		return this._stats.get(method);
+	}
+	/** Comptabilise une notification entrante (avant dispatch aux handlers). */
+	trackFrame(method) {
+		const now = Date.now();
+		this._framesReceived++;
+		this._lastFrameAt = now;
+		this._lastFrameMethod = method;
+		let st = this._stats.get(method);
+		if (!st) {
+			st = {
+				method,
+				msgCount: 0,
+				lastMessage: null,
+				rate: 0,
+				series: []
+			};
+			this._stats.set(method, st);
+		}
+		st.msgCount++;
+		st.lastMessage = now;
+	}
+	/**
+	* (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.
+	*/
+	replaySubscriptions() {
+		this._welcomed = true;
+		for (const channel of this._subscriptions.keys()) this._emitRaw("subscribe", { channel });
+	}
+	/**
+	* 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).
+	*/
+	ingestWelcome(params) {
+		const w = params;
+		if (!w || typeof w !== "object") return;
+		this._identity = w.identity ?? null;
+		this._serverChannels = Array.isArray(w.channels) ? w.channels : null;
+		this._serverMethods = Array.isArray(w.methods) ? w.methods : null;
+		noteServerEnv(w.env);
+		if (this.opts.banner !== false && !hasKernel()) this.detailsSocket();
+		this.fireLocal(LOCAL_EVENTS.identity, this._identity);
+	}
+	/**
+	* 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.
+	*/
+	detailsSocket() {
+		consoleDetails({
+			adresse: { valeur: this.url ?? "—" },
+			état: { valeur: this.state },
+			identité: { valeur: this._identity?.authenticated ? this._identity.userIdentifier ?? "authentifié" : "anonyme" },
+			canaux: { valeur: this._serverChannels?.join(", ") || "aucun" },
+			actions: { valeur: this._serverMethods?.join(", ") || "aucune" }
+		}, this, "socket nodefony — détail et raccourcis");
+	}
+	/**
+	* 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).
+	*/
+	ingestDenied(params) {
+		const p = params;
+		const channel = typeof p?.channel === "string" ? p.channel : "";
+		const brut = p?.reason;
+		const reason = brut === "unknown" || brut === "limit" ? brut : "forbidden";
+		const detail = typeof p?.detail === "string" ? p.detail : void 0;
+		const denied = {
+			channel,
+			reason,
+			...detail === void 0 ? {} : { detail }
+		};
+		this.fireNotice(deniedToNotice(denied));
+		this.fireLocal(LOCAL_EVENTS.denied, denied);
+	}
+	/**
+	* 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).
+	*/
+	dispatchNotification(method, params) {
+		if (method === "realtime:welcome") {
+			this.ingestWelcome(params);
+			this.replaySubscriptions();
+		} else if (method === "realtime:denied") this.ingestDenied(params);
+		this.trackFrame(method);
+		this.handlers.get(method)?.forEach((h) => {
+			try {
+				h(params);
+			} catch {}
+		});
+		this.handlers.get("*")?.forEach((h) => {
+			try {
+				h(method, params);
+			} catch {}
+		});
+	}
+	/**
+	* 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.
+	*/
+	handleServerError(frame) {
+		const err = frame.error;
+		if (!err || typeof err !== "object") return;
+		this.fireNotice({
+			level: "error",
+			title: "Temps réel",
+			message: err.message || "Erreur serveur temps réel",
+			source: "server",
+			code: err.code,
+			ts: Date.now()
+		});
+	}
+	/** Échantillonne le débit (msg/s) + série par canal, 1×/s, puis émet
+	*  `__stats__` (event local) pour notifier les consommateurs réactifs. */
+	startStatsSampler() {
+		if (this.statsTimer) return;
+		this.statsTimer = setInterval(() => {
+			for (const st of this._stats.values()) {
+				const prev = this._prevSampled.get(st.method) ?? st.msgCount;
+				st.rate = Math.max(0, st.msgCount - prev);
+				this._prevSampled.set(st.method, st.msgCount);
+				st.series = [...st.series, st.rate].slice(-32);
+			}
+			this.fireLocal(LOCAL_EVENTS.stats);
+		}, 1e3);
+		this.statsTimer.unref?.();
+	}
+	/** Émet une notice normalisée aux abonnés `onNotice` (event local, pas réseau). */
+	fireNotice(notice) {
+		this.fireLocal(LOCAL_EVENTS.notice, notice);
+	}
+	/** Déclenche les handlers locaux d'un event interne (pas d'envoi réseau). */
+	fireLocal(event, ...args) {
+		this.handlers.get(event)?.forEach((h) => {
+			try {
+				h(...args);
+			} catch {}
+		});
+	}
+	openSocket() {
+		return new Promise((resolve, reject) => {
+			this._welcomed = false;
+			this.setState(this.reconnectAttempt > 0 ? "reconnecting" : "connecting");
+			let transport;
+			try {
+				const base = typeof window !== "undefined" ? window.location.href : "http://localhost";
+				const url = new URL(this.requireUrl(), base);
+				if (url.protocol === "http:") url.protocol = "ws:";
+				else if (url.protocol === "https:") url.protocol = "wss:";
+				if (this.opts.token) url.searchParams.set("token", this.opts.token);
+				transport = this.transportFactory(url.toString());
+				this.transport = transport;
+			} catch (e) {
+				this.setState("error");
+				reject(e);
+				return;
+			}
+			transport.onOpen(() => {
+				const wasReconnecting = this.reconnectAttempt > 0;
+				this.reconnectAttempt = 0;
+				this._nextRetryAt = null;
+				this.setState("connected");
+				this.startHeartbeat();
+				if (wasReconnecting) this.fireNotice({
+					level: "success",
+					title: "Temps réel",
+					message: "Connexion temps réel rétablie",
+					source: "realtime",
+					ts: Date.now()
+				});
+				resolve();
+			});
+			transport.onMessage((raw) => this.handleMessage(raw));
+			transport.onError(() => {});
+			transport.onClose((code, reason) => {
+				this.clearTimers();
+				this.transport = null;
+				if (this.intentionalClose) {
+					this.setState("disconnected");
+					return;
+				}
+				const notice = closeCodeToNotice(code, reason);
+				if (notice) this.fireNotice(notice);
+				const reconnectable = isReconnectableCloseCode(code);
+				if (reconnectable && this.opts.autoReconnect !== false) this.scheduleReconnect();
+				else this.setState(reconnectable ? "disconnected" : "error");
+			});
+			transport.connect();
+		});
+	}
+	scheduleReconnect() {
+		this.reconnectAttempt++;
+		const base = this.opts.reconnectDelay ?? 1e3;
+		const max = this.opts.reconnectDelayMax ?? 3e4;
+		const delay = Math.min(base * 2 ** (this.reconnectAttempt - 1), max);
+		this._nextRetryAt = Date.now() + delay;
+		this.setState("reconnecting");
+		this.fireLocal(LOCAL_EVENTS.reconnect, {
+			attempt: this.reconnectAttempt,
+			delay,
+			nextRetryAt: this._nextRetryAt
+		});
+		this.reconnectTimer = setTimeout(() => {
+			this.openSocket().catch(() => {});
+		}, delay);
+	}
+	startHeartbeat() {
+		const interval = this.opts.heartbeatInterval ?? 3e4;
+		this.heartbeatTimer = setInterval(() => {
+			if (this.transport?.readyState === TransportState.OPEN) this._emitRaw("ping", { ts: Date.now() });
+		}, interval);
+	}
+	clearTimers() {
+		if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+		if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+		this.reconnectTimer = null;
+		this.heartbeatTimer = null;
+	}
+	/**
+	* 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() {
+		return (this._rawFrames ?? []).map((f) => RealtimeClient.buildFrame(f.dir, f.msg, f.ts));
+	}
+	/** Purge le log protocole. */
+	clearFrameLog() {
+		if (this._rawFrames) this._rawFrames.length = 0;
+	}
+	/**
+	* 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.
+	*/
+	recordFrame(dir, msg) {
+		const ts = Date.now();
+		(this._rawFrames ??= []).push({
+			ts,
+			dir,
+			msg
+		});
+		if (this._rawFrames.length > FRAME_LOG_MAX) this._rawFrames.shift();
+		const listeners = this.handlers.get("__frame__");
+		if (listeners && listeners.size > 0) this.fireLocal("__frame__", RealtimeClient.buildFrame(dir, msg, ts));
+	}
+	/** Construit une frame affichable (kind/canal/id + payload redacté). */
+	static buildFrame(dir, msg, ts) {
+		const m = msg ?? {};
+		let kind = "?";
+		let channel;
+		if (typeof m.method === "string") {
+			kind = m.method;
+			const p = m.params;
+			if (p && typeof p.channel === "string") channel = p.channel;
+		} else if ("error" in m) kind = "error";
+		else if ("result" in m) kind = "response";
+		return {
+			ts,
+			dir,
+			kind,
+			id: typeof m.id === "number" ? m.id : void 0,
+			channel,
+			payload: redactFrame(msg)
+		};
+	}
+	/**
+	* É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é.
+	*/
+	send(msg) {
+		if (this.transport?.readyState !== TransportState.OPEN) {
+			this._framesUnsent++;
+			return false;
+		}
+		this.transport.send(JSON.stringify(msg));
+		this.recordFrame("out", msg);
+		return true;
+	}
+	/**
+	* 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).
+	*/
+	noticeUnsent() {
+		if (this._unsentNotified) return;
+		this._unsentNotified = true;
+		this.fireNotice({
+			level: "warning",
+			title: "Temps réel",
+			message: "Connexion interrompue — les messages émis pendant la coupure sont perdus",
+			source: "realtime",
+			ts: Date.now()
+		});
+	}
+	handleMessage(raw) {
+		if (typeof raw !== "string") return;
+		let msg;
+		try {
+			msg = JSON.parse(raw);
+		} catch {
+			return;
+		}
+		this.receive(msg);
+	}
+	setState(s) {
+		if (this._state === s) return;
+		if (s === "connected") this._unsentNotified = false;
+		this._state = s;
+		this.fireLocal(LOCAL_EVENTS.state, s);
+	}
+};
+//#endregion
+export { RealtimeClient, RealtimeClient as default };