nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/client/client/ClientKernel.js

@@ -0,0 +1,276 @@
+import Service from "../Service.js";
+import { announceKernel, consoleDetails, isVerbose } from "./announce.js";
+import { RealtimeClient } from "./realtime/RealtimeClient.js";
+//#region src/client/ClientKernel.ts
+/**
+* `ClientKernel` — implémentation du kernel client isomorphe (ADR-0007).
+*
+* Le pendant navigateur du `Kernel` serveur : il compose les services techniques
+* d'une application front, porte son cycle de vie, son observabilité et son cycle
+* d'identité. Il ne possède **jamais** le rendu, le routing ni l'état métier
+* (clause anti-dérive D1) — React/Vue/Angular restent maîtres de la vue.
+*
+* Il **compose** un {@link Service} du cœur plutôt que d'en hériter, et ce choix
+* s'est décidé au compilateur : `Service.get`/`set` sont la façade du container
+* d'injection, dont la sémantique est « n'importe quel objet sous n'importe quel
+* nom » (`get<T>(name: string): T | null`), tandis que le registre du kernel est
+* **typé et fermé** par le contrat (`get(name): NodefonyClientServices[K]`).
+* Hériter revenait à resserrer une méthode publique de la classe de base — TS2416,
+* et le refus dit une vérité de conception : deux mécanismes différents portaient
+* le même nom. La composition garde les briques isomorphes du cœur (bus
+* d'événements, `Syslog`) sans exposer une surface qui n'est pas celle du contrat.
+*
+* Le budget bundle n'augmente pas de ce fait : `Service` et `Syslog` sont déjà
+* publiés par `nodefony/client`.
+*
+* @module nodefony/client
+*/
+/**
+* Kernel client — obtenu par {@link createClientKernel}, jamais construit en
+* singleton de module (testabilité, HMR-safe : un module réévalué par Vite
+* dédoublerait un singleton, gotcha vécu sur le contexte React de Studio).
+*/
+var ClientKernel = class {
+	/** Journal client de série — `Pdu` isomorphes, corrélables au back. */
+	syslog;
+	/** Bus d'événements et journal du cœur — la brique isomorphe, pas une copie. */
+	#service;
+	/** Options de composition, relues au `boot()` — le constructeur ne connecte rien. */
+	#options;
+	#state = "created";
+	#identity = null;
+	/**
+	* Promesse du `boot()` en cours — c'est ELLE qui rend l'appel idempotent, y
+	* compris pour deux appels concurrents : le second attend le premier au lieu
+	* de composer une seconde fois.
+	*/
+	#booting = null;
+	/**
+	* Registre des services composés. `null` tant que rien n'est enregistré (règle
+	* perf : pas de structure allouée « au cas où »). Un objet sans prototype
+	* plutôt qu'une `Map` — moins de trois entrées, accès ponctuel.
+	*/
+	#services = null;
+	/**
+	* Débranchements des listeners navigateur. `null` tant qu'aucun n'est posé —
+	* un kernel monté en test, ou hors document, n'en pose aucun.
+	*/
+	#unbind = null;
+	/** Retire le handle de console — posé par la bannière, libéré à la mort. */
+	#disposeHandle = null;
+	constructor(options = {}) {
+		this.#options = options;
+		this.#service = new Service(options.name ?? "CLIENT KERNEL");
+		this.syslog = this.#service.syslog;
+		this.#disposeHandle = announceKernel(this, this.name, this.#options.banner);
+		this.#composeRealtime();
+	}
+	/**
+	* Récupère un service composé, typé par le registre.
+	*
+	* Rend `undefined` pour un service absent — le registre est décrit par des
+	* propriétés optionnelles, si bien que `kernel.get("realtime")` est de type
+	* `RealtimeClient | undefined` et nourrit `<NodefonyProvider client={…}>` sans
+	* la moindre conversion de type forcée.
+	*/
+	get(name) {
+		if (!this.#services) return void 0;
+		return this.#services[name];
+	}
+	/** Enregistre un service sous son nom contractuel. */
+	set(name, svc) {
+		(this.#services ??= Object.create(null))[name] = svc;
+	}
+	/** Teste la présence d'un service — nom libre, y compris hors contrat. */
+	has(name) {
+		return this.#services !== null && this.#services[name] !== void 0;
+	}
+	/** État courant — jamais régressif. */
+	get state() {
+		return this.#state;
+	}
+	/**
+	* Compose et connecte les services. **Idempotent** : rappelé pendant ou après
+	* un premier boot, il ne recompose rien et ne réémet aucun événement. Depuis
+	* l'état `terminated`, il ne fait rien — l'état ne régresse jamais.
+	*/
+	boot() {
+		if (this.#state === "terminated" || this.#state === "ready") return Promise.resolve();
+		if (this.#booting) return this.#booting;
+		this.#booting = this.#doBoot();
+		return this.#booting;
+	}
+	async #doBoot() {
+		this.#state = "booting";
+		this.#service.fire("onBoot", this);
+		this.#bindBrowser();
+		const socket = this.#options.connectOnBoot === false ? void 0 : this.get("realtime");
+		if (socket) try {
+			await socket.connect();
+		} catch (e) {
+			this.syslog.log(e instanceof Error ? e.message : String(e), "WARNING");
+		}
+		if (this.#state !== "booting") return;
+		this.#state = "ready";
+		this.#details();
+		this.#service.fire("onReady", this);
+	}
+	/**
+	* Détail du noyau, dans un groupe REPLIÉ de la console.
+	*
+	* Le badge d'une ligne et le handle `nodefony` ne sont plus ici : ils sont
+	* posés au constructeur par `announce.ts`, que la socket appelle aussi quand
+	* elle vit nue (ADR-0007 D7 révisé). Ce qui reste est ce qu'un noyau seul peut
+	* dire — son état, son identité, les services qu'il a composés.
+	*
+	* Le groupe est replié (`groupCollapsed`) et non ouvert : présent pour qui le
+	* cherche, invisible pour qui débogue autre chose.
+	*/
+	#details() {
+		if (this.#options.banner === false) return;
+		if (this.#options.banner !== true && !isVerbose()) return;
+		const socket = this.get("realtime");
+		const rows = {
+			état: { valeur: this.state },
+			identité: { valeur: this.identity ? this.identity.key : "anonyme" },
+			"temps réel": { valeur: socket ? socket.url ?? "socket fournie" : "aucun" },
+			socket: { valeur: socket ? socket.state : "—" }
+		};
+		for (const name of this.#services ? Object.keys(this.#services) : []) rows[`service · ${name}`] = { valeur: "composé" };
+		consoleDetails(rows, this, "noyau client — détail et raccourcis");
+	}
+	/**
+	* Compose la socket depuis les options — instance passée telle quelle, ou
+	* socket partagée fabriquée depuis ses options (une seule connexion par URL).
+	* Rien n'est fabriqué quand l'application n'en veut pas : l'opt-in est strict
+	* (D7), le kernel compose, il n'impose pas.
+	*/
+	#composeRealtime() {
+		if (this.has("realtime")) return;
+		const opt = this.#options.realtime;
+		if (!opt) return;
+		this.set("realtime", opt instanceof RealtimeClient ? opt : RealtimeClient.shared(opt));
+	}
+	/**
+	* Flush l'observabilité et déconnecte. Idempotent, et **best-effort** : appelé
+	* sur `pagehide`, il n'a aucune garantie d'aller au bout — d'où l'ordre choisi,
+	* l'événement d'abord, le débranchement ensuite.
+	*/
+	async terminate() {
+		if (this.#state === "terminated") return;
+		this.#state = "terminated";
+		this.#service.fire("onTerminate", this);
+		const socket = this.get("realtime");
+		if (socket) socket.disconnect();
+		this.#unbindBrowser();
+		this.#disposeHandle?.();
+		this.#disposeHandle = null;
+		this.#booting = null;
+		this.#services = null;
+		this.#service.clean();
+	}
+	/** Nom du kernel — celui donné à la fabrique, `CLIENT KERNEL` par défaut. */
+	get name() {
+		return this.#service.name;
+	}
+	/** Identité runtime courante, telle que l'application l'a déclarée. */
+	get identity() {
+		return this.#identity;
+	}
+	/**
+	* Déclare l'identité runtime — et applique la règle de sécurité D9, née d'une
+	* fuite vécue en production.
+	*
+	* Deux gardes, chacune payée par une régression réelle :
+	*
+	* 1. **`disconnect()` uniquement sur un VRAI changement de compte** (une clé
+	*    connue remplacée par une autre). La socket grave l'identité au handshake ;
+	*    le pont « API souveraine » rejouerait sinon des requêtes avec le jeton du
+	*    compte précédent. Couper impose un nouveau handshake, donc la relecture du
+	*    cookie courant.
+	* 2. **`connect()` HORS de cette garde.** Au tout premier chargement, la clé
+	*    passe de `null` à une valeur : couper là romprait les requêtes EN VOL qui
+	*    passent par le pont, et l'écran resterait en attente jusqu'au délai de
+	*    garde (régression « tourne en boucle »).
+	*
+	* Une clé inchangée n'est pas un changement de compte : le profil est rafraîchi
+	* en silence, sans toucher à la socket ni réveiller l'application.
+	*/
+	setIdentity(identity) {
+		const previous = this.#identity;
+		const previousKey = previous ? previous.key : null;
+		const key = identity ? identity.key : null;
+		this.#identity = identity;
+		if (previousKey === key) return;
+		const socket = this.get("realtime");
+		if (socket) {
+			if (previousKey !== null) socket.disconnect();
+			if (key !== null) socket.connect();
+		}
+		this.#service.fire("onIdentityChange", identity, previous);
+	}
+	/** Abonne un handler à un événement du kernel (bus `Event` du cœur, chaînable). */
+	on(event, handler) {
+		this.#service.on(event, handler);
+		return this;
+	}
+	/** Retire un handler abonné par {@link on}. */
+	off(event, handler) {
+		this.#service.removeListener(event, handler);
+		return this;
+	}
+	/**
+	* Ponte les événements du navigateur sur ceux du kernel.
+	*
+	* `pagehide` et non `beforeunload` : ce dernier n'est pas fiable sur mobile
+	* (bfcache), et le contrat ne nomme que l'événement kernel — le choix du
+	* listener reste une affaire d'implémentation.
+	*/
+	#bindBrowser() {
+		if (this.#options.browserEvents === false) return;
+		const doc = globalThis.document;
+		const win = globalThis.window;
+		if (!doc || !win) return;
+		const bind = (target, type, handler) => {
+			target.addEventListener(type, handler);
+			(this.#unbind ??= []).push(() => target.removeEventListener(type, handler));
+		};
+		bind(doc, "visibilitychange", () => this.#service.fire("onVisibility", doc.visibilityState !== "hidden"));
+		bind(win, "online", () => this.#service.fire("onOnline", true));
+		bind(win, "offline", () => this.#service.fire("onOnline", false));
+		bind(win, "pagehide", () => void this.terminate());
+	}
+	/** Défait tous les listeners navigateur — appelé par `terminate()`, une fois. */
+	#unbindBrowser() {
+		if (!this.#unbind) return;
+		for (const off of this.#unbind) off();
+		this.#unbind = null;
+	}
+	/**
+	* Nombre de listeners navigateur encore posés.
+	*
+	* Sonde de fuite à l'usage des tests : un kernel terminé doit en compter zéro,
+	* et c'est la seule façon de le CONSTATER plutôt que de le supposer.
+	*/
+	get browserListenerCount() {
+		return this.#unbind ? this.#unbind.length : 0;
+	}
+};
+/**
+* Fabrique un kernel client.
+*
+* Factory et non singleton : plusieurs kernels doivent pouvoir coexister en test,
+* et un état de module global se dédouble sous le rechargement à chaud de Vite.
+*
+* @example
+* ```typescript
+* const kernel = createClientKernel({ realtime: { url: "/nodefony/realtime" } });
+* await kernel.boot();
+* kernel.setIdentity({ key: user.id });
+* ```
+*/
+function createClientKernel(options = {}) {
+	return new ClientKernel(options);
+}
+//#endregion
+export { ClientKernel, ClientKernel as default, createClientKernel };

package/dist/client/client/angular/index.js

@@ -0,0 +1,352 @@
+import { isRateChannel, parseRate, rateChannel } from "../../realtime/channelRate.js";
+import { adaptiveRebindKey, connectShared, observeChannel, observeChannelStats, observeIdentity, observeNoticeLog, observeNotices, observeSnapshot, observeState, observeSyslog } from "../realtime/observe.js";
+import { DestroyRef, InjectionToken, NgZone, assertInInjectionContext, effect, inject, makeEnvironmentProviders, signal, untracked } from "@angular/core";
+//#region src/client/angular/index.ts
+/**
+* `nodefony/angular` — liaisons **Angular** du client temps réel isomorphe.
+*
+* Adapte le {@link RealtimeClient} (agnostique : `on()`/`emit()`/`state`) aux
+* *signals* d'Angular, sans glue à recopier dans chaque application. Le pendant
+* exact de `nodefony/react` et `nodefony/vue` : même surface, mêmes noms, mêmes
+* garanties — seule la traduction vers la réactivité change.
+*
+* **Ce fichier ne contient AUCUNE règle temps réel.** Souscrire, tenir un
+* dernier reçu, borner un anneau, décoder le format coalescé du journal, ne
+* jamais couper une socket partagée : tout cela vit dans le socle agnostique
+* `nodefony/client` (`observe*`, `connectShared`), que les quatre liaisons
+* consomment à l'identique. Ici ne reste que la traduction *rappel + libération
+* → signal* — la seule chose qu'une liaison a le droit de contenir. Une liaison
+* qui réencoderait une règle la ferait diverger des trois autres, en silence.
+*
+* Trois particularités d'Angular que React et Vue ne montrent pas, et qui sont
+* la raison d'être de ce fichier :
+*
+*  1. **AUCUN décorateur Angular n'est publié ici**, et c'est délibéré. Un
+*     `@Injectable()` n'est pas du JavaScript : c'est une instruction pour le
+*     compilateur d'Angular, qui doit la transformer. Une bibliothèque qui en
+*     publie doit donc être bâtie par `ng-packagr` au format de paquet Angular
+*     (*partial compilation* + *linker*) — une seconde chaîne de build, et un
+*     couplage aux majeures d'Angular, pour UN subpath sur quatre. Non compilé,
+*     un décorateur marche parfois en développement (si `@angular/compiler` est
+*     chargé) et **casse en production**, où il ne l'est pas. La forme retenue
+*     — `InjectionToken` + `makeEnvironmentProviders` + fonctions `inject*()` —
+*     est celle qu'Angular emploie pour lui-même (`provideHttpClient`,
+*     `provideRouter`, `takeUntilDestroyed`) : du TypeScript ordinaire, que
+*     rolldown bâtit comme le reste, et une DI intacte.
+*     ⚠️ Cela ne restreint EN RIEN l'application : `@Component`, `@Injectable`,
+*     `@Directive` y sont compilés par le plugin Angular du builder Nodefony.
+*     Ces fonctions s'appellent depuis un composant ou un service décoré.
+*  2. **Les écouteurs sont posés HORS ZONE.** Dans une application avec
+*     `zone.js`, `zone.js` remplace `WebSocket` pour savoir quand relancer la
+*     détection de changements : une socket ouverte dans la zone déclenche donc
+*     une détection **globale à chaque trame** — un canal à 10 Hz coûterait dix
+*     détections par seconde à TOUTE l'application, ce que la règle de
+*     performance du projet interdit. {@link provideNodefony} ouvre donc la
+*     connexion dans `NgZone.runOutsideAngular`. Les valeurs, elles, arrivent
+*     par des *signals*, qui notifient leurs lecteurs sans zone : juste dans les
+*     deux mondes, `zone.js` ou `provideZonelessChangeDetection()`.
+*  3. **La libération passe par le contexte d'injection**, jamais par une valeur
+*     de retour : `DestroyRef` pour un abonnement fixe, le nettoyage d'`effect`
+*     pour un abonnement qui suit un signal. C'est le composant (ou le service)
+*     qui possède l'abonnement, et sa destruction le rend.
+*
+* `@angular/core` est une peerDep **optionnelle** : ce module n'est tiré que si
+* on importe `nodefony/angular`.
+*
+* @example La page entière, en deux concepts :
+* ```ts
+* // main.ts
+* bootstrapApplication(AppComponent, {
+*   providers: [provideNodefony({ url: "/api/live/realtime" })],
+* });
+* ```
+* ```ts
+* // app.component.ts
+* @Component({ selector: "app-root", template: `{{ etat() }}` })
+* export class AppComponent {
+*   readonly etat = injectNodefonyState();
+*   readonly last = injectNodefonyChannelData<LiveEvent>("live:events");
+* }
+* ```
+*
+* @module nodefony/angular
+*/
+/**
+* Le jeton sous lequel {@link provideNodefony} enregistre la socket.
+*
+* Exporté pour le cas légitime où un sous-arbre doit parler à une AUTRE socket
+* que celle de l'application : le fournir à nouveau dans les `providers` d'un
+* composant suffit, et les fonctions du sous-arbre suivent.
+*/
+const NODEFONY_CLIENT = new InjectionToken("nodefony:realtime");
+/**
+* Le fournisseur — à poser une fois, dans les `providers` de l'application.
+*
+* Il fait exactement deux choses : enregistrer la socket, et lancer la
+* connexion **hors zone**. Il n'en coupe aucune : la connexion appartient à la
+* PAGE, pas à un composant, et `disconnect()` tranche les requêtes en vol des
+* autres consommateurs de la même socket partagée.
+*
+* La socket est résolue **immédiatement** (donc une adresse manquante est
+* refusée à la construction des providers, pas à la première injection) ; la
+* connexion, elle, n'est ouverte qu'au premier `inject`, et hors zone.
+*
+* @throws si ni `url` ni `client` n'est fourni — l'adresse dépend de
+*   l'application, et le framework n'en devine aucune (règle du socle : une
+*   adresse devinée marche en développement et se trompe en production).
+*
+* @example
+* ```ts
+* bootstrapApplication(AppComponent, {
+*   providers: [
+*     provideZonelessChangeDetection(),
+*     provideNodefony({ url: "/api/live/realtime" }),
+*   ],
+* });
+* ```
+*/
+function provideNodefony(options) {
+	const connection = connectShared(options);
+	return makeEnvironmentProviders([{
+		provide: NODEFONY_CLIENT,
+		useFactory: () => {
+			inject(NgZone).runOutsideAngular(() => {
+				connection.start();
+			});
+			return connection.socket;
+		}
+	}]);
+}
+/**
+* `injectNodefony()` — la socket brute (canaux, journal, statistiques…). Tête de
+* gondole et échappatoire pour les cas avancés ; pour de l'état réactif, prendre
+* les fonctions dédiées ci-dessous.
+*
+* @throws si {@link provideNodefony} n'est pas dans les `providers`. Le socle
+*   REFUSE de deviner une adresse : retomber ici sur une socket partagée
+*   fabriquée à la volée donnerait une page qui marche en développement et parle
+*   au mauvais hôte en production — mieux vaut une erreur au premier rendu.
+*/
+function injectNodefony() {
+	assertInInjectionContext(injectNodefony);
+	const client = inject(NODEFONY_CLIENT, { optional: true });
+	if (!client) throw new Error("injectNodefony() : provideNodefony() n'est pas dans les providers — bootstrapApplication(App, { providers: [provideNodefony({ url: \"/api/live/realtime\" })] }).");
+	return client;
+}
+/** Lit une source, qu'elle soit constante ou fonction. */
+function read(source) {
+	return typeof source === "function" ? source() : source;
+}
+/**
+* Le motif commun à toutes les fonctions d'abonnement : brancher, rebrancher
+* quand la source change, libérer à la destruction.
+*
+* Deux chemins, et l'écart entre eux est voulu :
+*
+*  - **source constante** → branchement direct + `DestroyRef`. Aucun `effect`
+*    n'est alloué pour une valeur qui ne bougera jamais (règle de performance du
+*    projet : pas de structure allouée « au cas où »).
+*  - **source fonction** → `effect`, dont la lecture TRACKÉE rebranche à chaque
+*    changement et dont le nettoyage rend l'abonnement précédent. `untracked`
+*    entoure le branchement : ce que le socle lirait par ailleurs ne doit pas
+*    devenir une dépendance de l'effet.
+*/
+function observeReactive(source, wire) {
+	if (typeof source !== "function") {
+		const release = wire(source);
+		inject(DestroyRef).onDestroy(release);
+		return;
+	}
+	effect((onCleanup) => {
+		const value = read(source);
+		onCleanup(untracked(() => wire(value)));
+	});
+}
+/**
+* `injectNodefonyState()` — l'état de la connexion (`"connected"`,
+* `"reconnecting"`, …), tenu à jour. Branché sur la porte publique `onState`,
+* jamais sur le nom de l'événement local, qui n'a pas à sortir du client.
+*/
+function injectNodefonyState() {
+	assertInInjectionContext(injectNodefonyState);
+	const client = injectNodefony();
+	const state = signal(client.state);
+	observeReactive(client, (socket) => observeState(socket, (value) => state.set(value)));
+	return state.asReadonly();
+}
+/**
+* `injectNodefonyIdentity()` — l'**identité résolue** de la connexion, annoncée
+* par le serveur au `realtime:welcome` (`authenticated`, `roles`,
+* `userIdentifier`, `scopes`). `null` tant qu'aucun welcome n'est arrivé ; une
+* fois reçu, un visiteur anonyme a `authenticated: false`. Brique du gating
+* front : `authenticated: false` → écran de connexion, **sans** appeler
+* `/auth/me`.
+*/
+function injectNodefonyIdentity() {
+	assertInInjectionContext(injectNodefonyIdentity);
+	const client = injectNodefony();
+	const identity = signal(client.identity);
+	observeReactive(client, (socket) => observeIdentity(socket, (value) => identity.set(value)));
+	return identity.asReadonly();
+}
+/**
+* `injectNodefonyChannel()` — s'abonne à un canal pub/sub : `onMessage` est
+* appelé à chaque message. Le socle apparie `subscribe`/`unsubscribe` côté
+* serveur (ref-comptés) et rejoue l'abonnement à chaque reconnexion.
+*
+* Le canal accepte un signal (ou toute fonction qui le lit) : l'abonnement suit
+* alors la valeur, en libérant l'ancien avant de prendre le nouveau.
+*/
+function injectNodefonyChannel(channel, onMessage) {
+	assertInInjectionContext(injectNodefonyChannel);
+	const client = injectNodefony();
+	observeReactive(channel, (name) => observeChannel(client, name, onMessage));
+}
+/**
+* `injectNodefonyChannelData()` — la **dernière valeur** reçue sur un canal (le
+* cas le plus courant : la dernière mesure d'un flux d'état). `null` tant que
+* rien n'est arrivé.
+*/
+function injectNodefonyChannelData(channel, initial = null) {
+	assertInInjectionContext(injectNodefonyChannelData);
+	const data = signal(initial);
+	injectNodefonyChannel(channel, (payload) => data.set(payload));
+	return data.asReadonly();
+}
+/**
+* `injectNodefonyAdaptiveChannel()` — comme {@link injectNodefonyChannel}, mais
+* en **cadence adaptative** (AIMD piloté par le client) : la cadence recule sous
+* famine puis remonte quand c'est sain, sans rien changer au serveur. Renvoie la
+* cadence effective, à afficher.
+*
+* Réservé aux canaux d'ÉTAT (latest-wins) : décimer un canal d'événements perd
+* des messages.
+*
+* Le ré-abonnement suit {@link adaptiveRebindKey} — la MÊME clé que les trois
+* autres liaisons, pour que les quatre rebranchent aux mêmes instants.
+*/
+function injectNodefonyAdaptiveChannel(base, onMessage, desiredMs, options = {}) {
+	assertInInjectionContext(injectNodefonyAdaptiveChannel);
+	const client = injectNodefony();
+	const cadence = signal(read(desiredMs));
+	const enabled = options.enabled !== false;
+	observeReactive(() => adaptiveRebindKey(read(base), read(desiredMs), enabled), () => {
+		const binding = client.adaptiveChannel(read(base), (...args) => onMessage(args[0]), {
+			...options,
+			intervalMs: read(desiredMs),
+			enabled,
+			onRate: (ms) => cadence.set(ms)
+		});
+		return () => binding.dispose();
+	});
+	return cadence.asReadonly();
+}
+/**
+* `injectNodefonyAdaptiveChannelData()` — comme
+* {@link injectNodefonyChannelData}, mais en cadence adaptative. Mince surcouche
+* de {@link injectNodefonyAdaptiveChannel} : garde la dernière valeur et rend la
+* cadence effective. Réservé aux canaux d'ÉTAT.
+*/
+function injectNodefonyAdaptiveChannelData(base, desiredMs, options = {}) {
+	assertInInjectionContext(injectNodefonyAdaptiveChannelData);
+	const data = signal(null);
+	const intervalMs = injectNodefonyAdaptiveChannel(base, (payload) => data.set(payload), desiredMs, options);
+	return {
+		data: data.asReadonly(),
+		intervalMs
+	};
+}
+/**
+* `injectNodefonyChannelStats()` — statistiques vivantes d'un canal (débit,
+* série pour un VU-mètre, total). La source est l'échantillonneur du client
+* (1×/s) : aucune horloge n'est posée ici, et aucune trame n'est émise pour
+* mesurer.
+*/
+function injectNodefonyChannelStats(channel) {
+	assertInInjectionContext(injectNodefonyChannelStats);
+	const client = injectNodefony();
+	const stats = signal(null);
+	observeReactive(channel, (name) => observeChannelStats(client, name, (value) => stats.set(value)));
+	return stats.asReadonly();
+}
+/**
+* `injectNodefonySnapshot()` — ce que la socket sait d'ELLE-MÊME : état, canaux
+* tenus, trames reçues, trames perdues, dernière trame. Rafraîchi par
+* l'échantillonneur déjà en place — aucune horloge de plus.
+*
+* La donnée est au socle, la **boîte qui l'affiche** reste à chaque front :
+* publier un composant obligerait à en écrire un par framework de vue, et ferait
+* entrer du DOM dans un module dont toute la valeur est de n'en avoir aucun.
+*/
+function injectNodefonySnapshot() {
+	assertInInjectionContext(injectNodefonySnapshot);
+	const client = injectNodefony();
+	const snapshot = signal(null);
+	observeReactive(client, (socket) => observeSnapshot(socket, (value) => snapshot.set(value)));
+	return snapshot.asReadonly();
+}
+/**
+* `injectNodefonySyslog()` — le flux du journal, prêt à afficher : anneau borné
+* et filtre de sévérité. Le format **coalescé** du canal (`{ logs, dropped }`),
+* l'entrée unique, la taille de l'anneau et le canal par défaut viennent du
+* socle ({@link observeSyslog}) : cette fonction n'en connaît aucun.
+*/
+function injectNodefonySyslog(options = {}) {
+	assertInInjectionContext(injectNodefonySyslog);
+	const client = injectNodefony();
+	const lines = signal([]);
+	const wire = () => {
+		const o = read(options);
+		const settings = {
+			max: o.max,
+			severities: o.severities,
+			channel: o.channel
+		};
+		return observeSyslog(client, (entries) => lines.set(entries), settings);
+	};
+	observeReactive(typeof options === "function" ? () => {
+		const o = read(options);
+		return `${o.channel ?? ""}|${o.max ?? ""}|${(o.severities ?? []).join(",")}`;
+	} : "", wire);
+	return lines.asReadonly();
+}
+/**
+* `injectNodefonyNotifications()` — le flux des **notices normalisées** du
+* client : criticités qui cassent le temps réel (codes de fermeture RFC 6455
+* interprétés), erreurs poussées par le serveur, rétablissement de connexion.
+* `onNotice` est appelé pour CHAQUE notice → brancher un centre de
+* notifications.
+*
+* À monter **une seule fois** (le shell de l'application), sans quoi la même
+* notice s'affiche autant de fois qu'il y a d'appels.
+*/
+function injectNodefonyNotifications(onNotice) {
+	assertInInjectionContext(injectNodefonyNotifications);
+	observeReactive(injectNodefony(), (socket) => observeNotices(socket, onNotice));
+}
+/**
+* `injectNodefonyNoticeLog()` — l'anneau borné des dernières notices, filtrable
+* par source : un historique léger des criticités, distinct des notifications
+* éphémères. La taille de l'anneau et le filtrage viennent du socle
+* ({@link observeNoticeLog}).
+*/
+function injectNodefonyNoticeLog(options = {}) {
+	assertInInjectionContext(injectNodefonyNoticeLog);
+	const client = injectNodefony();
+	const notices = signal([]);
+	const wire = () => {
+		const o = read(options);
+		const settings = {
+			max: o.max,
+			sources: o.sources
+		};
+		return observeNoticeLog(client, (list) => notices.set(list), settings);
+	};
+	observeReactive(typeof options === "function" ? () => {
+		const o = read(options);
+		return `${o.max ?? ""}|${(o.sources ?? []).join(",")}`;
+	} : "", wire);
+	return notices.asReadonly();
+}
+//#endregion
+export { NODEFONY_CLIENT, injectNodefony, injectNodefonyAdaptiveChannel, injectNodefonyAdaptiveChannelData, injectNodefonyChannel, injectNodefonyChannelData, injectNodefonyChannelStats, injectNodefonyIdentity, injectNodefonyNoticeLog, injectNodefonyNotifications, injectNodefonySnapshot, injectNodefonyState, injectNodefonySyslog, isRateChannel, parseRate, provideNodefony, rateChannel };