nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/client/types/src/client/IClientKernel.d.ts

@@ -0,0 +1,195 @@
+/**
+ * `IClientKernel` — contrat du kernel client isomorphe de Nodefony (ADR-0007).
+ *
+ * Le ClientKernel est le chef d'orchestre de la couche **INFRA** d'une app front
+ * (composition des services techniques, lifecycle navigateur, observabilité,
+ * cycle d'identité). Il ne possède JAMAIS le rendu, le routing ni l'état métier
+ * (React/Vue/Angular + stores restent maîtres de la vue) — clause anti-dérive
+ * ADR-0007 D1.
+ *
+ * Ce fichier EST la spécification : toute évolution de surface passe par un
+ * nouvel ADR. Il n'est PAS encore réexporté par le barrel client — il y revient
+ * quand la console d'administration l'exerce (ADR-0007 D11.4), gardé par
+ * `src/tests/clientSurfaceExercised.test.ts`.
+ *
+ * @module nodefony/client
+ */
+import type Syslog from "../syslog/Syslog.js";
+import type { RealtimeClient, RealtimeOptions } from "./realtime/RealtimeClient.js";
+/**
+ * États du kernel client, ordonnés et non régressifs (symétrie nominale avec les
+ * lifecycle flags du Kernel serveur — `booted`/`ready`/… — sans en singer la
+ * sémantique process).
+ */
+export type ClientKernelState = "created" | "booting" | "ready" | "terminated";
+/**
+ * Événements émis par le kernel client.
+ *
+ * Mêmes noms nominaux que les hooks du Kernel serveur quand le sens est le même
+ * (`onBoot`/`onReady`/`onTerminate`) ; les événements propres au navigateur
+ * (`onIdentityChange`, `onVisibility`, `onOnline`) n'ont volontairement pas
+ * d'équivalent back.
+ *
+ * - `onBoot` — composition faite (`boot()` appelé).
+ * - `onReady` — services connectés (socket ouverte, ou opt-out realtime).
+ * - `onIdentityChange` — l'identité runtime a changé (login/logout/bascule de
+ *   compte). Le kernel a DÉJÀ re-négocié la socket quand l'app reçoit cet
+ *   événement (anti-élévation de privilège, ADR-0007 D9) : il ne reste à
+ *   l'application qu'à purger ses propres caches scopés.
+ * - `onVisibility` — `document.visibilitychange`.
+ * - `onOnline` — bascule `online`/`offline` du navigateur.
+ * - `onTerminate` — page en cours de déchargement (`pagehide`, best-effort).
+ */
+export type ClientKernelEvent = "onBoot" | "onReady" | "onIdentityChange" | "onVisibility" | "onOnline" | "onTerminate";
+/**
+ * Identité runtime déclarée par l'application au kernel.
+ *
+ * `key` est une **clé stable de compte** — et elle seule décide d'un « vrai
+ * changement » au sens ADR-0007 D9. Ce n'est pas un détail de forme : la garde
+ * qui protège contre l'élévation de privilège compare des clés, jamais des
+ * objets. Un profil rafraîchi (mêmes droits, nouvel objet) ne doit PAS couper la
+ * socket ; une bascule de compte le doit toujours.
+ *
+ * `data` reste à l'usage de l'application (profil, rôles, ce qu'elle veut
+ * retrouver dans le handler) — le kernel ne l'interprète jamais.
+ */
+export interface ClientIdentity {
+    /** Clé stable du compte — l'unique critère du re-handshake (D9). */
+    readonly key: string;
+    /** Charge libre, opaque au kernel. */
+    readonly data?: unknown;
+}
+/**
+ * Registre TYPÉ des services techniques portés par le kernel client.
+ *
+ * Extensible par **augmentation de module** (même mécanique que le registre de
+ * config `NodefonyModuleConfig` back, ADR-0006) : un module/une app déclare ses
+ * services sans jamais modifier ce contrat.
+ *
+ * `realtime` est typé sur la **classe** `RealtimeClient`, pas sur l'interface
+ * `IRealtimeSocket` : c'est la correction du premier défaut relevé par #41. Le
+ * consommateur publié du registre est `NodefonyProvider`, dont la prop `client`
+ * exige la classe ; et `IRealtimeSocket` n'a ni `connect`, ni `disconnect`, ni
+ * `state`, ni `identity` — le contrat ne savait donc pas exprimer le
+ * re-handshake de sa propre décision D9. Un registre nomme des services
+ * composés, pas des abstractions : l'affaiblir n'achetait rien et imposait une
+ * conversion de type forcée à chaque lecture.
+ *
+ * @example
+ * ```typescript
+ * declare module "nodefony/client" {
+ *   interface NodefonyClientServices {
+ *     api?: MyApiClient;
+ *   }
+ * }
+ * ```
+ */
+export interface NodefonyClientServices {
+    /** La socket Nodefony de l'app (multiplexage de canaux, isomorphe). */
+    realtime?: RealtimeClient;
+}
+/**
+ * Options de `createClientKernel()`.
+ *
+ * Tout est facultatif : un kernel sans option est légal et ne compose rien —
+ * l'opt-in est strict (ADR-0007 D7), le kernel compose, il n'impose pas.
+ */
+export interface ClientKernelOptions {
+    /**
+     * Nom du kernel — sert de `msgid` dans les journaux client.
+     *
+     * @defaultValue `"CLIENT KERNEL"`
+     */
+    name?: string;
+    /**
+     * La socket de l'application. Trois formes, par DX décroissante :
+     * une instance déjà composée, les options d'une socket partagée
+     * (`RealtimeClient.shared`), ou `false`/absent pour ne pas en avoir.
+     */
+    realtime?: RealtimeClient | RealtimeOptions | false;
+    /**
+     * Ponter les événements du navigateur (`visibilitychange`, `online`/`offline`,
+     * `pagehide`) sur les événements du kernel.
+     *
+     * @defaultValue `true` quand un document est présent
+     */
+    browserEvents?: boolean;
+    /**
+     * Ouvrir la socket au `boot()`.
+     *
+     * À passer `false` quand la socket est **authentifiée** : c'est alors le login
+     * qui l'ouvre, par `setIdentity()`, et ouvrir au démarrage produirait une
+     * connexion anonyme qui n'a rien à faire là. Le cas s'est présenté au premier
+     * portage réel — la console d'administration n'ouvre sa socket qu'une fois
+     * l'utilisateur connu.
+     *
+     * @defaultValue `true`
+     */
+    connectOnBoot?: boolean;
+    /**
+     * Annoncer le kernel dans la console du navigateur au `boot()`.
+     *
+     * Trois états, et le défaut s'adapte tout seul :
+     *
+     * - **en développement** (`import.meta.env.DEV` posé par le bundler) — un badge
+     *   sur une ligne, puis un groupe REPLIÉ avec les services composés, l'adresse
+     *   et l'état de la socket, l'identité courante ;
+     * - **partout ailleurs** — le badge seul. Savoir que le noyau tourne suffit à
+     *   diagnostiquer ; le reste est du bruit dans la console de l'utilisateur ;
+     * - `false` — rien du tout.
+     *
+     * `true` force le détail quel que soit le mode. L'absence de preuve de
+     * développement est traitée comme la production : se taire à tort ne coûte
+     * qu'une ligne, parler à tort pollue la console de tout le monde.
+     *
+     * @defaultValue le mode détecté
+     */
+    banner?: boolean;
+}
+/**
+ * Contrat du kernel client isomorphe (ADR-0007 D2 — surface v1, volontairement
+ * minimale : chaque méthode publiée est une promesse SemVer).
+ *
+ * Obtenu via la factory `createClientKernel()` — jamais un singleton de module
+ * (testabilité, HMR-safe). Chaque primitive du Core reste utilisable NUE sans
+ * kernel (opt-in strict, ADR-0007 D7).
+ */
+export interface IClientKernel {
+    /** Récupère un service enregistré (ou `undefined` s'il n'est pas composé). */
+    get<K extends keyof NodefonyClientServices>(name: K): NodefonyClientServices[K];
+    /** Enregistre un service sous son nom contractuel. */
+    set<K extends keyof NodefonyClientServices>(name: K, svc: NodefonyClientServices[K]): void;
+    /** Teste la présence d'un service (nom libre, y compris hors contrat). */
+    has(name: string): boolean;
+    /** Compose et connecte les services (idempotent). Émet `onBoot` puis `onReady`. */
+    boot(): Promise<void>;
+    /** Flush l'observabilité et déconnecte (best-effort sur `pagehide`). Émet `onTerminate`. */
+    terminate(): Promise<void>;
+    /** État courant du kernel — jamais régressif. */
+    readonly state: ClientKernelState;
+    /**
+     * Déclare l'identité runtime courante — c'est l'application qui la connaît
+     * (login, logout, bascule de compte), le kernel qui en tire les conséquences.
+     *
+     * Sur un **vrai** changement de clé, et lui seul, le kernel re-négocie la
+     * socket puis émet `onIdentityChange`. Sans cette porte d'entrée, D9 resterait
+     * une intention : le kernel n'a aucun moyen d'apprendre qu'un login a eu lieu.
+     */
+    setIdentity(identity: ClientIdentity | null): void;
+    /** Identité runtime courante, telle que l'application l'a déclarée. */
+    readonly identity: ClientIdentity | null;
+    /** Abonne un handler à un événement du kernel (API `Event` du Core, chaînable). */
+    on(event: ClientKernelEvent, handler: (...args: unknown[]) => void): this;
+    /**
+     * Journal client de série (`Pdu` isomorphes — corrélables au back par
+     * `requestId`).
+     *
+     * L'ADR-0007 nommait ce membre `log`. Le nom ne pouvait pas tenir : tout
+     * `Service` Nodefony porte déjà `log(...)` comme **méthode d'écriture**, et le
+     * kernel client en est un — une propriété du même nom masquait le geste
+     * d'écriture de toute la lignée. `syslog` est le nom que le framework donne
+     * partout ailleurs à ce même objet (`Service.syslog`, `kernel.syslog`) :
+     * l'isomorphisme, c'est le même modèle mental des deux côtés du fil.
+     */
+    readonly syslog: Syslog;
+}

package/dist/client/types/src/client/angular/index.d.ts

@@ -0,0 +1,273 @@
+/**
+ * `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
+ */
+import { InjectionToken, type EnvironmentProviders, type Signal } from "@angular/core";
+import type { RealtimeClient } from "../realtime/RealtimeClient.js";
+import type { MessageStats, NodefonyNotice, RealtimeIdentity, RealtimeState } from "../realtime/RealtimeClient.js";
+import type { BindAdaptiveOptions } from "../realtime/AdaptiveRate.js";
+import { type SocketSnapshot } from "../realtime/observe.js";
+export { rateChannel, parseRate, isRateChannel, } from "../../realtime/channelRate.js";
+export type { RateBounds } from "../../realtime/channelRate.js";
+export type { RealtimeIdentity, RealtimeState, NodefonyNotice, } from "../realtime/RealtimeClient.js";
+export type { SocketSnapshot } from "../realtime/observe.js";
+/**
+ * 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.
+ */
+export declare const NODEFONY_CLIENT: InjectionToken<RealtimeClient<import("../../realtime/RealtimeEventMap.js").DefaultEventsMap, import("../../realtime/RealtimeEventMap.js").DefaultEventsMap, import("../../realtime/RealtimeEventMap.js").DefaultActionsMap>>;
+/** Réglages de {@link provideNodefony} — l'un des deux au moins doit être donné. */
+export interface NodefonyAngularOptions {
+    /**
+     * Adresse du serveur temps réel — la voie SIMPLE. Le fournisseur fabrique la
+     * socket partagée pour cette URL et la connecte lui-même.
+     *
+     * Deux consommateurs qui donnent la même URL obtiennent la MÊME socket
+     * ({@link RealtimeClient.shared}), donc une seule connexion réseau.
+     */
+    url?: string;
+    /**
+     * Socket déjà construite — la voie AVANCÉE, quand l'application possède son
+     * cycle de connexion. Fournie, elle l'emporte sur `url` et le fournisseur ne
+     * touche pas au cycle : ni `connect`, ni `disconnect`.
+     */
+    client?: RealtimeClient;
+}
+/**
+ * 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" }),
+ *   ],
+ * });
+ * ```
+ */
+export declare function provideNodefony(options: NodefonyAngularOptions): EnvironmentProviders;
+/**
+ * `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.
+ */
+export declare function injectNodefony(): RealtimeClient;
+/**
+ * Une source de valeur : constante, ou fonction qui la lit (un `Signal` en est
+ * un cas — un signal EST une fonction sans argument).
+ *
+ * C'est ce qui remplace, en Angular, la liste de dépendances que React doit se
+ * faire passer à la main : donner un signal suffit à ce que l'abonnement suive.
+ */
+export type Source<T> = T | (() => T);
+/**
+ * `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.
+ */
+export declare function injectNodefonyState(): Signal<RealtimeState>;
+/**
+ * `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`.
+ */
+export declare function injectNodefonyIdentity(): Signal<RealtimeIdentity | null>;
+/**
+ * `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.
+ */
+export declare function injectNodefonyChannel(channel: Source<string>, onMessage: (payload: unknown) => void): void;
+/**
+ * `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é.
+ */
+export declare function injectNodefonyChannelData<T = unknown>(channel: Source<string>, initial?: T | null): Signal<T | null>;
+/** Réglages adaptatifs (la cadence désirée se passe à part, en argument). */
+export type AdaptiveChannelOptions = Omit<BindAdaptiveOptions, "intervalMs" | "onRate">;
+/** Résultat de {@link injectNodefonyAdaptiveChannelData} : valeur + cadence réelle. */
+export interface AdaptiveChannelData<T> {
+    /** Dernière valeur reçue, `null` tant que rien n'est arrivé. */
+    data: Signal<T | null>;
+    /** Cadence effective (ms) — bouge avec l'AIMD, à afficher en badge. */
+    intervalMs: Signal<number>;
+}
+/**
+ * `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.
+ */
+export declare function injectNodefonyAdaptiveChannel(base: Source<string>, onMessage: (payload: unknown) => void, desiredMs: Source<number>, options?: AdaptiveChannelOptions): Signal<number>;
+/**
+ * `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.
+ */
+export declare function injectNodefonyAdaptiveChannelData<T = unknown>(base: Source<string>, desiredMs: Source<number>, options?: AdaptiveChannelOptions): AdaptiveChannelData<T>;
+/**
+ * Statistiques observées d'un canal, telles que le client les calcule.
+ *
+ * Alias du contrat isomorphe {@link MessageStats} : une copie locale de la forme
+ * aurait divergé le jour où le client ajoute un compteur.
+ */
+export type ChannelStatsSnapshot = MessageStats;
+/**
+ * `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.
+ */
+export declare function injectNodefonyChannelStats(channel: Source<string>): Signal<ChannelStatsSnapshot | null>;
+/**
+ * `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.
+ */
+export declare function injectNodefonySnapshot(): Signal<SocketSnapshot | null>;
+/** Réglages de {@link injectNodefonySyslog}. */
+export interface InjectSyslogOptions {
+    /** Taille max de l'anneau (les plus anciennes lignes sont évincées). Défaut 500. */
+    max?: number;
+    /** Ne garder que ces sévérités (ex. `["ERROR", "CRITIC"]`). Toutes par défaut. */
+    severities?: string[];
+    /** Canal source. Défaut `"nodefony:syslog"`. */
+    channel?: string;
+}
+/**
+ * `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.
+ */
+export declare function injectNodefonySyslog(options?: Source<InjectSyslogOptions>): Signal<unknown[]>;
+/**
+ * `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.
+ */
+export declare function injectNodefonyNotifications(onNotice: (notice: NodefonyNotice) => void): void;
+/** Réglages de {@link injectNodefonyNoticeLog}. */
+export interface InjectNoticeLogOptions {
+    /** Taille max de l'anneau (les plus anciennes notices sont évincées). Défaut 50. */
+    max?: number;
+    /** Ne garder que ces sources (ex. `["realtime"]`). Toutes par défaut. */
+    sources?: NodefonyNotice["source"][];
+}
+/**
+ * `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}).
+ */
+export declare function injectNodefonyNoticeLog(options?: Source<InjectNoticeLogOptions>): Signal<NodefonyNotice[]>;

package/dist/client/types/src/client/announce.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Le mode annoncé par le serveur, quand il en annonce un.
+ *
+ * ⚠️ Le serveur **ne pose ce champ qu'en dehors de la production** : une absence
+ * vaut donc production, jamais l'inverse. C'est la même règle que pour le
+ * bundle, et pour la même raison — se taire à tort ne coûte qu'une ligne, parler
+ * à tort expose la console de tout le monde.
+ *
+ * @param env - la valeur reçue dans `realtime:welcome`, ou `undefined`.
+ */
+export declare function noteServerEnv(env: string | undefined): void;
+/**
+ * Peut-on se permettre le détail ? Bundle de développement, OU serveur qui
+ * annonce un mode hors production.
+ */
+export declare function isVerbose(): boolean;
+/**
+ * Le bundle a-t-il été bâti en développement ?
+ *
+ * Le mode se LIT, il ne se devine pas : `import.meta.env.DEV` est posé par le
+ * bundler de l'application (Vite le remplace par une constante au build). Hors
+ * bundler il n'existe pas — et **l'absence de preuve de développement se traite
+ * comme la production**, jamais l'inverse : se taire à tort ne coûte qu'une
+ * ligne manquante, parler à tort pollue la console de tout le monde.
+ */
+export declare function isDevBuild(): boolean;
+/**
+ * Annonce un noyau client : son nom porte le badge, et il devient le sujet du
+ * handle. À appeler AVANT que le noyau compose sa socket, sinon c'est le badge
+ * générique de la socket qui sortirait le premier.
+ *
+ * @param kernel - le noyau, exposé tel quel en `nodefony.kernel`.
+ * @param name - son nom, affiché dans le badge.
+ * @param annoncer - `false` fait taire l'annonce ET le handle (app publiée qui
+ *   ne veut rien dans sa console) ; `true` force le détail hors développement.
+ * @returns le débranchement, à appeler à la mort du noyau — sans quoi un
+ *   rechargement à chaud accumulerait des noyaux morts retenus par le handle.
+ */
+export declare function announceKernel(kernel: {
+    identity?: unknown;
+}, name: string, annoncer?: boolean): () => void;
+/**
+ * Annonce une socket qui vit NUE — aucune composition, aucun noyau. C'est le cas
+ * des vitrines du dépôt et de tout widget qui monte une socket et rien d'autre.
+ *
+ * @param annoncer - `false` fait taire l'annonce (option `banner` de la socket).
+ * @returns le débranchement ; une socket partagée vit avec la page et n'a pas à
+ *   l'appeler — il existe pour les bancs, qui doivent repartir d'une page vierge.
+ */
+export declare function announceRealtime(annoncer?: boolean): () => void;
+/**
+ * Détail du framework, dans un groupe REPLIÉ de la console : un tableau
+ * `clé → valeur` et les deux rappels qui font gagner du temps.
+ *
+ * **Un seul détail par page**, et le noyau gagne : quand il y en a un, la socket
+ * ne le double pas — c'est lui qui a le plus à dire (état, identité, services).
+ * Une vitrine sans noyau, elle, obtient enfin le sien : c'est la moitié
+ * « diagnostic » que l'ADR-0007 D7 laissait derrière le péage de la composition.
+ *
+ * Le groupe est replié et non ouvert : présent pour qui le cherche, invisible
+ * pour qui débogue autre chose. `groupEnd` est atteint même si une lecture
+ * jette — un groupe laissé ouvert avale tous les messages suivants.
+ *
+ * @param rows - le tableau à rendre, `clé → { valeur }`, composé par
+ *   l'appelant : lui seul sait ce qu'il a d'important à dire.
+ * @param subject - l'objet vivant à imprimer en dernier (noyau, ou socket).
+ * @param title - l'intitulé du groupe.
+ * @returns `true` si le détail a été émis.
+ */
+export declare function consoleDetails(rows: Record<string, {
+    valeur: string;
+}>, subject: unknown, title: string): boolean;
+/** Un noyau est-il vivant sur cette page ? La socket s'efface devant lui. */
+export declare function hasKernel(): boolean;