nodefony 7.0.2 → 10.0.0-alpha.2

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

@@ -0,0 +1,216 @@
+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 Dispose, 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";
+/**
+ * Une valeur réactive à la mode de Svelte 5 : on la lit `.current`.
+ *
+ * Le même contrat que `MediaQuery.current` : lue dans un template ou un
+ * `$effect`, elle suit ; lue ailleurs, elle rend l'instantané courant.
+ */
+export interface Reactive<T> {
+    readonly current: T;
+}
+/** Réglages de {@link configureNodefony} — l'un des deux au moins doit être donné. */
+export interface NodefonySvelteOptions {
+    /**
+     * Adresse du serveur temps réel — la voie SIMPLE. La socket partagée de cette
+     * URL est fabriquée et connectée.
+     *
+     * 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 son cycle n'est
+     * pas touché : ni `connect`, ni `disconnect`.
+     */
+    client?: RealtimeClient;
+}
+/**
+ * Installe la politique temps réel de l'application — à appeler UNE fois, dans
+ * le point d'entrée, avant `mount()`.
+ *
+ * Svelte n'a pas de contexte applicatif comparable à React : `setContext` ne se
+ * pose qu'à l'initialisation d'un composant, et ne couvrirait donc pas les
+ * liaisons appelées ailleurs. La politique s'écrit ici comme ce qu'elle est en
+ * Svelte : une configuration de module.
+ *
+ * Elle ne coupe aucune connexion : 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.
+ *
+ * @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
+ * configureNodefony({ url: "/api/live/realtime" });
+ * ```
+ */
+export declare function configureNodefony(options: NodefonySvelteOptions): void;
+/**
+ * `nodefony()` — 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 liaisons dédiées ci-dessous.
+ *
+ * @throws si {@link configureNodefony} n'a pas été appelé. 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 nodefony(): RealtimeClient;
+/**
+ * Une source de valeur : constante, ou fonction qui la lit.
+ *
+ * Donner une fonction qui lit un `$state` suffit à ce que l'abonnement SUIVE la
+ * valeur — c'est ce qui remplace, en Svelte, la liste de dépendances que React
+ * doit se faire passer à la main.
+ */
+export type Source<T> = T | (() => T);
+/**
+ * `nodefonyState()` — 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 nodefonyState(): Reactive<RealtimeState>;
+/**
+ * `nodefonyIdentity()` — 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 nodefonyIdentity(): Reactive<RealtimeIdentity | null>;
+/**
+ * `nodefonyChannel()` — 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.
+ *
+ * **C'est la forme NON paresseuse** : elle rend son propre teardown, ce que
+ * `$effect` attend, et l'abonnement est donc pris que la valeur soit affichée
+ * ou non.
+ *
+ * @example
+ * ```svelte
+ * $effect(() => nodefonyChannel("live:salon", (m) => messages.push(m)));
+ * ```
+ */
+export declare function nodefonyChannel(channel: Source<string>, onMessage: (payload: unknown) => void): Dispose;
+/**
+ * `nodefonyChannelData()` — 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é.
+ *
+ * Le canal accepte une fonction : donnée dans un `$derived`, elle fait suivre
+ * l'abonnement — et le nouveau canal est pris AVANT que l'ancien soit rendu.
+ */
+export declare function nodefonyChannelData<T = unknown>(channel: Source<string>, initial?: T | null): Reactive<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 nodefonyAdaptiveChannelData} : valeur + cadence réelle. */
+export interface AdaptiveChannelData<T> {
+    /** Dernière valeur reçue, `null` tant que rien n'est arrivé. */
+    data: Reactive<T | null>;
+    /** Cadence effective (ms) — bouge avec l'AIMD, à afficher en badge. */
+    intervalMs: Reactive<number>;
+}
+/**
+ * `nodefonyAdaptiveChannel()` — comme {@link nodefonyChannel}, 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.
+ *
+ * Réservé aux canaux d'ÉTAT (latest-wins) : décimer un canal d'événements perd
+ * des messages.
+ *
+ * Comme {@link nodefonyChannel}, rend son teardown — forme non paresseuse, à
+ * donner à `$effect`. La cadence effective est poussée par `onRate` ; pour
+ * l'AFFICHER, prendre {@link nodefonyAdaptiveChannelData}, qui la rend réactive.
+ *
+ * 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 nodefonyAdaptiveChannel(base: Source<string>, onMessage: (payload: unknown) => void, desiredMs: Source<number>, options?: AdaptiveChannelOptions & {
+    onRate?: (ms: number) => void;
+}): Dispose;
+/**
+ * `nodefonyAdaptiveChannelData()` — comme {@link nodefonyChannelData}, mais en
+ * cadence adaptative. Rend la dernière valeur **et** la cadence effective, les
+ * deux réactives. Réservé aux canaux d'ÉTAT.
+ *
+ * La clé de ré-abonnement est {@link adaptiveRebindKey} : lue à chaque
+ * branchement, elle fait suivre l'abonnement quand la base, la cadence désirée
+ * ou l'activation changent — et pas quand autre chose bouge.
+ */
+export declare function nodefonyAdaptiveChannelData<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;
+/**
+ * `nodefonyChannelStats()` — 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 nodefonyChannelStats(channel: Source<string>): Reactive<ChannelStatsSnapshot | null>;
+/**
+ * `nodefonySnapshot()` — 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 nodefonySnapshot(): Reactive<SocketSnapshot | null>;
+/** Réglages de {@link nodefonySyslog}. */
+export interface SyslogOptions {
+    /** 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;
+}
+/**
+ * `nodefonySyslog()` — 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 liaison n'en connaît aucun.
+ */
+export declare function nodefonySyslog(options?: Source<SyslogOptions>): Reactive<unknown[]>;
+/**
+ * `nodefonyNotifications()` — 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.
+ *
+ * Forme non paresseuse (elle rend son teardown), à monter **une seule fois**
+ * dans 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 nodefonyNotifications(onNotice: (notice: NodefonyNotice) => void): Dispose;
+/** Réglages de {@link nodefonyNoticeLog}. */
+export interface NoticeLogOptions {
+    /** 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"][];
+}
+/**
+ * `nodefonyNoticeLog()` — 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 nodefonyNoticeLog(options?: Source<NoticeLogOptions>): Reactive<NodefonyNotice[]>;

package/dist/client/types/src/client/syslog/context.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Identités de corrélation **côté navigateur** — ce que le pod pourra recouper quand
+ * il recevra un journal venu d'un onglet.
+ *
+ * Le navigateur n'a pas d'`AsyncLocalStorage` : une erreur JavaScript ne survient dans
+ * aucune bulle de requête. « Le `requestId` de la requête qui l'a précédée » n'existe
+ * donc pas — deux `fetch` concurrents suffisent à attribuer l'erreur à la mauvaise, et
+ * un journal qui ment sur la corrélation coûte plus cher qu'un journal sans corrélation.
+ *
+ * D'où deux identités séparées, chacune honnête sur ce qu'elle sait :
+ *
+ * - {@link getPageId} — **toujours** disponible, généré une fois par chargement de page.
+ *   C'est lui qui relie entre elles toutes les lignes d'un même onglet. Sans lui, le pod
+ *   reçoit des lignes orphelines qu'aucun écran ne peut regrouper.
+ * - {@link withRequestId} — pose un `requestId` **seulement là où il est SU** : dans le
+ *   code qui traite une réponse dont on a lu l'en-tête `x-request-id`. Hors de cette
+ *   portée, aucun `requestId` n'est attaché. Rien n'est deviné.
+ *
+ * Coût quand personne ne s'en sert : une variable à `undefined` et un test de référence
+ * par `Pdu` (le provider n'est même pas branché tant que {@link installRequestIdProvider}
+ * n'a pas été appelé).
+ */
+/**
+ * Identifiant stable de ce chargement de page (UUID v4), généré à la demande.
+ *
+ * Il change à chaque rechargement — c'est voulu : il désigne une **session d'onglet**,
+ * pas un utilisateur. Rien d'identifiant personnel ne doit y être mêlé.
+ *
+ * @returns l'identifiant de page, constant pour la durée du document.
+ */
+export declare function getPageId(): string;
+/**
+ * Exécute `fn` en déclarant que ce qu'elle journalise appartient à la requête `requestId`.
+ *
+ * La portée est le **tick synchrone** de `fn`, et rien de plus : après un `await`, la
+ * bulle est refermée. C'est une limite assumée, pas un défaut — le navigateur n'offre
+ * aucun moyen de propager un contexte à travers l'asynchrone, et l'alternative (« le
+ * dernier `requestId` vu ») fabriquerait de fausses corrélations.
+ *
+ * @example
+ * ```ts
+ * const res = await fetch("/api/orders");
+ * const rid = res.headers.get("x-request-id") ?? undefined;
+ * withRequestId(rid, () => {
+ *   syslog.log("commande refusée", "ERROR", "checkout");
+ * });
+ * ```
+ *
+ * @param requestId - la requête connue, ou `undefined` pour n'en attacher aucune.
+ * @param fn - le travail à exécuter dans cette portée.
+ * @returns ce que `fn` renvoie.
+ */
+export declare function withRequestId<T>(requestId: string | undefined, fn: () => T): T;
+/**
+ * `requestId` de la portée courante, `undefined` en dehors de {@link withRequestId}.
+ *
+ * @returns l'identifiant de requête su à cet instant, jamais deviné.
+ */
+export declare function getCurrentRequestId(): string | undefined;
+/**
+ * Branche {@link getCurrentRequestId} sur `Pdu.requestIdProvider`, de sorte que tout
+ * `Pdu` créé dans une portée {@link withRequestId} porte son `requestId` — le même champ
+ * que côté serveur, donc la même clé de recoupement, sans qu'aucun appelant ait à le
+ * répéter.
+ *
+ * Idempotent. Le provider d'origine (il n'y en a pas côté navigateur, mais un test peut
+ * en poser un) est restauré au retrait.
+ *
+ * @returns la fonction de retrait — à appeler au démontage.
+ */
+export declare function installRequestIdProvider(): () => void;
+/**
+ * Remet le module à son état initial — réservé aux tests, qui doivent pouvoir repartir
+ * d'une page « neuve » sans recharger un document.
+ */
+export declare function resetClientLogContext(): void;

package/dist/client/types/src/client/syslog/errors.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Capture des erreurs **non rattrapées** du navigateur (`error`, `unhandledrejection`)
+ * et versement dans le `Syslog` client.
+ *
+ * C'est la source qui donne son intérêt à la voie montante : une exception qui remonte
+ * jusqu'à `window` n'est vue par personne. Elle s'affiche dans une console que
+ * l'utilisateur n'a pas ouverte, puis disparaît avec l'onglet. Côté serveur, la requête
+ * qui l'a provoquée est pourtant journalisée, complète — il ne manquait que la moitié
+ * navigateur.
+ *
+ * Rien n'est intercepté ni monkey-patché : deux écouteurs `window`, retirés au démontage.
+ */
+import type Syslog from "../../syslog/Syslog.js";
+export interface ErrorCaptureOptions {
+    /** Le journal client qui recevra les entrées. */
+    syslog: Syslog;
+    /**
+     * Catégorie (`msgid`) des entrées produites. Défaut {@link BROWSER_ERROR_MSGID}.
+     *
+     * Le **module** émetteur, lui, n'est pas un paramètre : il appartient au `Syslog`
+     * client (`settings.moduleName`) et `log()` ne permet pas de l'écraser par appel.
+     */
+    msgid?: string;
+    /**
+     * Fenêtre de déduplication des erreurs IDENTIQUES consécutives, en ms. Défaut `1000`.
+     *
+     * Une exception dans une boucle d'animation se lève soixante fois par seconde ; sans
+     * cette fenêtre, elle chasse du tampon toutes les autres entrées et le journal ne
+     * contient plus qu'elle. `0` désactive.
+     */
+    dedupeMs?: number;
+}
+/** Catégorie par défaut d'une exception non rattrapée. */
+export declare const BROWSER_ERROR_MSGID = "BROWSER_ERROR";
+/** Catégorie d'une promesse rejetée sans `catch`. */
+export declare const BROWSER_REJECTION_MSGID = "BROWSER_REJECTION";
+/**
+ * Installe la capture des erreurs globales du navigateur.
+ *
+ * No-op hors navigateur (rendu serveur, test Node sans DOM) : le contrat isomorphe veut
+ * qu'un code client puisse être chargé des deux côtés sans garde chez l'appelant.
+ *
+ * @param opts - journal cible et bornes.
+ * @returns la fonction de retrait — retire les deux écouteurs.
+ */
+export declare function installErrorCapture(opts: ErrorCaptureOptions): () => void;

package/dist/client/types/src/client/syslog/uplink.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Transport **montant** des journaux du navigateur : il écoute le `Syslog` client, met
+ * les `Pdu` en tampon et les pousse par lots sur un canal entrant de la socket, où le
+ * pod les réinjecte dans son propre journal.
+ *
+ * Ce qu'il n'est PAS : un puits {@link ILogSink}. Celui-ci reçoit des **chaînes déjà
+ * formatées** — au point où il intervient, la sévérité, le module et le `requestId` sont
+ * fondus dans du texte. Les faire transiter par là obligerait à reparser ce qu'on vient
+ * de sérialiser, et le `requestId` serait extrait d'un format d'affichage. Le transport
+ * écoute donc l'événement `"onLog"`, qui porte le `Pdu` **lui-même** : la même structure
+ * des deux côtés du fil, ce qui est tout l'intérêt d'un cœur isomorphe.
+ *
+ * Coût quand il n'est pas installé : **zéro**. `Syslog.log()` ne déclenche `fire("onLog")`
+ * que si `listenerCount("onLog") > 0`.
+ *
+ * Coût quand il l'est : un test de sévérité par entrée, un `push` dans un tableau alloué
+ * au premier journal retenu, et **un** minuteur de regroupement quel que soit le débit.
+ * La sérialisation n'a lieu qu'à l'envoi, jamais à la capture.
+ */
+import type Syslog from "../../syslog/Syslog.js";
+/** Le strict nécessaire pour pousser — n'impose pas `RealtimeClient` à l'appelant. */
+export interface UplinkPublisher {
+    publish(channel: string, payload?: unknown): void;
+}
+/** Une entrée de journal telle qu'elle voyage sur le fil (plate, sérialisable). */
+export interface WireLogEntry {
+    /** Sévérité RFC 5424 (0-7). */
+    severity: number;
+    /** Nom de la sévérité (`"ERROR"`, `"INFO"`…). */
+    severityName: string;
+    /** Module émetteur **tel que le client le prétend** — le pod ne le croit pas. */
+    moduleName: string;
+    msgid: string;
+    msg: string;
+    /** Horloge du NAVIGATEUR (ms epoch) — jamais celle du pod. */
+    timeStamp: number;
+    /** Requête connue au moment du journal, absente si elle ne l'était pas. */
+    requestId?: string;
+    /** Charge normalisée : une `Error` devient `{name, message, stack}`. */
+    payload: unknown;
+}
+/** Enveloppe d'un lot poussé sur le canal montant. */
+export interface UplinkBatch {
+    /** Identifiant de ce chargement de page — la clé de regroupement d'un onglet. */
+    pageId: string;
+    /** Les entrées, dans l'ordre d'émission. */
+    entries: WireLogEntry[];
+    /** Entrées perdues depuis le dernier lot (tampon plein). `0` omis. */
+    dropped?: number;
+}
+export interface SyslogUplinkOptions {
+    /** Le journal client à écouter. */
+    syslog: Syslog;
+    /** La socket par laquelle pousser (typiquement le `RealtimeClient` partagé). */
+    publisher: UplinkPublisher;
+    /**
+     * Sévérité maximale retenue (RFC 5424 : plus le nombre est petit, plus c'est grave).
+     * Défaut `4` (WARNING) — remonter le DEBUG d'un navigateur en production est un
+     * excellent moyen de noyer un journal d'exploitation.
+     */
+    maxSeverity?: number;
+    /** Fenêtre de regroupement, en ms. Défaut `2000`. */
+    batchMs?: number;
+    /** Entrées par lot au maximum ; au-delà, on envoie sans attendre. Défaut `50`. */
+    maxBatch?: number;
+    /** Profondeur du tampon ; au-delà, la plus ANCIENNE est perdue. Défaut `200`. */
+    maxQueue?: number;
+    /** Longueur maximale d'une chaîne transportée (message, pile). Défaut `4096`. */
+    maxStringLength?: number;
+    /** Canal montant. Défaut {@link PLATFORM_INBOUND.syslogUplink}. */
+    channel?: string;
+}
+/**
+ * Catégorie (`msgid`) réservée à ce que le transport dit de LUI-MÊME. Les entrées qui la
+ * portent sont **exclues** de la remontée : sans cette exclusion, un envoi qui échoue
+ * journalise son échec, ce qui produit une entrée, qui déclenche un envoi, qui échoue.
+ *
+ * La marque porte sur le `msgid` et non sur le module : `Syslog.log()` ne permet pas de
+ * fixer `moduleName` par appel — il appartient aux `settings` du logger.
+ */
+export declare const UPLINK_MSGID = "CLIENT_UPLINK";
+/**
+ * Installe la remontée des journaux du navigateur vers le pod.
+ *
+ * @param opts - journal à écouter, socket par laquelle pousser, et les bornes.
+ * @returns la fonction de retrait — détache le listener, annule le minuteur et pousse
+ *   une dernière fois ce qui restait en tampon.
+ */
+export declare function installSyslogUplink(opts: SyslogUplinkOptions): () => void;

package/dist/client/types/src/client/transport/websocket.d.ts

@@ -0,0 +1,5 @@
+import Service from "../../Service.js";
+declare class Websocket extends Service {
+    constructor();
+}
+export default Websocket;

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

@@ -0,0 +1,234 @@
+/**
+ * `nodefony/vue` — liaisons **Vue 3** du client temps réel isomorphe.
+ *
+ * Adapte le {@link RealtimeClient} (agnostique : `on()`/`emit()`/`state`) à la
+ * réactivité de Vue, sans glue à recopier dans chaque application. Le pendant
+ * exact de `nodefony/react` : 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 liaisons React,
+ * Angular et Svelte consomment à l'identique. Ici ne reste que la traduction
+ * *rappel + libération → réactivité Vue* — la seule chose qu'une liaison a le
+ * droit de contenir. Un composable qui réencoderait une règle la ferait
+ * diverger des trois autres fronts, en silence.
+ *
+ * Trois particularités de Vue que React ne montre pas, et qui sont la raison
+ * d'être de ce fichier :
+ *
+ *  1. **La politique s'écrit en PLUGIN**, pas en composant enveloppant :
+ *     `app.use(nodefonyVue, { url })`. C'est le vocabulaire du framework.
+ *  2. **Le client n'entre JAMAIS dans un `ref()`** — il serait enveloppé dans
+ *     un proxy réactif profond, qui casse les égalités de référence et fait
+ *     payer une interception à chaque accès. Il est posé `markRaw`.
+ *  3. **La libération passe par `onScopeDispose`**, pas par `onUnmounted` :
+ *     c'est le seul des deux qui couvre aussi les portées d'effet créées hors
+ *     composant (`effectScope()`), où un abonnement fuirait sans un mot.
+ *
+ * `vue` est une peerDep **optionnelle** : ce module n'est tiré que si on
+ * importe `nodefony/vue`.
+ *
+ * @example La page entière, en deux concepts :
+ * ```ts
+ * // main.ts
+ * createApp(App).use(nodefonyVue, { url: "/api/live/realtime" }).mount("#app");
+ * ```
+ * ```vue
+ * <script setup lang="ts">
+ * import { useNodefonyChannelData, useNodefonyState } from "nodefony/vue";
+ * const etat = useNodefonyState();
+ * const last = useNodefonyChannelData<LiveEvent>("live:events");
+ * </script>
+ * ```
+ *
+ * @module nodefony/vue
+ */
+import { type InjectionKey, type MaybeRefOrGetter, type Plugin, type Ref } from "vue";
+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";
+/**
+ * La clé sous laquelle le plugin fournit la socket.
+ *
+ * Exportée pour le cas légitime où un sous-arbre doit parler à une AUTRE
+ * socket que celle de l'application : `provide(nodefonyClientKey, uneAutre)`
+ * dans le composant parent suffit, et les composables du sous-arbre suivent.
+ */
+export declare const nodefonyClientKey: InjectionKey<RealtimeClient>;
+/** Réglages du plugin — l'un des deux au moins doit être donné. */
+export interface NodefonyVueOptions {
+    /**
+     * Adresse du serveur temps réel — la voie SIMPLE. Le plugin 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 plugin ne
+     * touche pas au cycle : ni `connect`, ni `disconnect`.
+     */
+    client?: RealtimeClient;
+}
+/**
+ * Le plugin — à installer une fois, sur l'application.
+ *
+ * Il fait exactement deux choses : fournir la socket au sous-arbre, et lancer
+ * la connexion. 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.
+ *
+ * @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
+ * createApp(App).use(nodefonyVue, { url: "/api/live/realtime" }).mount("#app");
+ * ```
+ */
+export declare const nodefonyVue: Plugin<[NodefonyVueOptions]>;
+/**
+ * `useNodefony()` — 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 composables dédiés ci-dessous.
+ *
+ * @throws si le plugin n'est pas installé. 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 useNodefony(): RealtimeClient;
+/**
+ * `useNodefonyState()` — 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 useNodefonyState(): Readonly<Ref<RealtimeState>>;
+/**
+ * `useNodefonyIdentity()` — 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 useNodefonyIdentity(): Readonly<Ref<RealtimeIdentity | null>>;
+/**
+ * `useNodefonyChannel()` — 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 une `ref` ou une fonction : l'abonnement suit alors la
+ * valeur, en libérant l'ancien avant de prendre le nouveau.
+ */
+export declare function useNodefonyChannel(channel: MaybeRefOrGetter<string>, onMessage: (payload: unknown) => void): void;
+/**
+ * `useNodefonyChannelData()` — 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 useNodefonyChannelData<T = unknown>(channel: MaybeRefOrGetter<string>, initial?: T | null): Readonly<Ref<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 useNodefonyAdaptiveChannelData} : valeur + cadence réelle. */
+export interface AdaptiveChannelData<T> {
+    /** Dernière valeur reçue, `null` tant que rien n'est arrivé. */
+    data: Readonly<Ref<T | null>>;
+    /** Cadence effective (ms) — bouge avec l'AIMD, à afficher en badge. */
+    intervalMs: Readonly<Ref<number>>;
+}
+/**
+ * `useNodefonyAdaptiveChannel()` — comme {@link useNodefonyChannel}, 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 useNodefonyAdaptiveChannel(base: MaybeRefOrGetter<string>, onMessage: (payload: unknown) => void, desiredMs: MaybeRefOrGetter<number>, options?: AdaptiveChannelOptions): Readonly<Ref<number>>;
+/**
+ * `useNodefonyAdaptiveChannelData()` — comme {@link useNodefonyChannelData},
+ * mais en cadence adaptative. Mince surcouche de
+ * {@link useNodefonyAdaptiveChannel} : garde la dernière valeur et rend la
+ * cadence effective. Réservé aux canaux d'ÉTAT.
+ */
+export declare function useNodefonyAdaptiveChannelData<T = unknown>(base: MaybeRefOrGetter<string>, desiredMs: MaybeRefOrGetter<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;
+/**
+ * `useNodefonyChannelStats()` — 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 useNodefonyChannelStats(channel: MaybeRefOrGetter<string>): Readonly<Ref<ChannelStatsSnapshot | null>>;
+/**
+ * `useNodefonySnapshot()` — 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 useNodefonySnapshot(): Readonly<Ref<SocketSnapshot | null>>;
+/** Réglages de {@link useNodefonySyslog}. */
+export interface UseSyslogOptions {
+    /** 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;
+}
+/**
+ * `useNodefonySyslog()` — 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}) : ce composable n'en connaît aucun.
+ */
+export declare function useNodefonySyslog(options?: MaybeRefOrGetter<UseSyslogOptions>): Readonly<Ref<unknown[]>>;
+/**
+ * `useNodefonyNotifications()` — 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 useNodefonyNotifications(onNotice: (notice: NodefonyNotice) => void): void;
+/** Réglages de {@link useNodefonyNoticeLog}. */
+export interface UseNoticeLogOptions {
+    /** 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"][];
+}
+/**
+ * `useNodefonyNoticeLog()` — 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 useNodefonyNoticeLog(options?: MaybeRefOrGetter<UseNoticeLogOptions>): Readonly<Ref<NodefonyNotice[]>>;