nodefony 7.0.2 → 10.0.0-alpha.2

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

@@ -0,0 +1,47 @@
+import Container from "../Container.js";
+import Service from "../Service.js";
+import Syslog from "../syslog/Syslog.js";
+import Pdu, { SEVERITY_NAMES, BROWSER_ORIGIN } from "../syslog/Pdu.js";
+import { extend, isEmptyObject, isPlainObject, isUndefined, isRegExp, isContainer, typeOf, isFunction, isArray, isPromise, isSubclassOf } from "../Tools.js";
+import { RealtimeClient } from "./realtime/RealtimeClient.js";
+import { closeCodeToNotice } from "./realtime/notice.js";
+import { JsonRpcPeer, RpcError } from "../realtime/JsonRpcPeer.js";
+import { TransportState } from "../realtime/IRealtimeTransport.js";
+import { BrowserWsTransport } from "./realtime/BrowserWsTransport.js";
+import { rateChannel, parseRate, isRateChannel } from "../realtime/channelRate.js";
+import { AdaptiveRate, bindAdaptiveChannel } from "./realtime/AdaptiveRate.js";
+import { pduProtocol } from "../syslog/drivers/pduProtocol.js";
+import { pduFlowStep, FLOW_STEPS } from "../syslog/drivers/pduFlow.js";
+export type { RealtimeState, RealtimeOptions, MessageStats, RealtimeFrame, KernelPingResult, IApiCallResult, RealtimeIdentity, IRealtimeWelcome, IRealtimeDenied, RealtimeReconnectInfo, } from "./realtime/RealtimeClient.js";
+export type { NodefonyNotice, NoticeLevel } from "./realtime/notice.js";
+export type { Severity, SeverityName } from "../syslog/Pdu.js";
+export type { IRealtimePeer, RpcActionHandler, RpcNotificationHandler, JsonRpcFrameKind, JsonRpcErrorObject, JsonRpcPeerOptions, } from "../realtime/JsonRpcPeer.js";
+export type { IRealtimeTransport, TransportStateValue, RealtimeTransportFactory, } from "../realtime/IRealtimeTransport.js";
+export type { IRealtimeSocket, IRealtimeChannel, IChannelStats, RealtimeHandler, } from "../realtime/IRealtimeSocket.js";
+export { ClientKernel, createClientKernel } from "./ClientKernel.js";
+export type { ClientIdentity, ClientKernelEvent, ClientKernelOptions, ClientKernelState, IClientKernel, NodefonyClientServices, } from "./IClientKernel.js";
+/**
+ * Génère un identifiant unique (UUID v4) côté client.
+ *
+ * Named export plat — remplace l'ancienne façade singleton `Nodefony` du barrel
+ * client (supprimée par l'ADR-0007 D4 : named exports only, symétrie avec le
+ * barrel node où le singleton exporté a déjà été supprimé).
+ */
+export declare function generateId(): string;
+export { Service, Container, Pdu, SEVERITY_NAMES, BROWSER_ORIGIN, Syslog, extend, isEmptyObject, isPlainObject, isUndefined, isRegExp, isContainer, typeOf, isFunction, isArray, isPromise, isSubclassOf, RealtimeClient, JsonRpcPeer, RpcError, TransportState, BrowserWsTransport, closeCodeToNotice, rateChannel, parseRate, isRateChannel, AdaptiveRate, bindAdaptiveChannel, pduProtocol, pduFlowStep, FLOW_STEPS, };
+export type { IPage, IPageQuery } from "../types/IPage.js";
+export type { LogProtocol } from "../syslog/drivers/pduProtocol.js";
+export type { FlowStepId, FlowStepMeta } from "../syslog/drivers/pduFlow.js";
+export type { RateBounds } from "../realtime/channelRate.js";
+export { installSyslogUplink, UPLINK_MSGID } from "./syslog/uplink.js";
+export type { SyslogUplinkOptions, UplinkPublisher, UplinkBatch, WireLogEntry, } from "./syslog/uplink.js";
+export { installErrorCapture, BROWSER_ERROR_MSGID, BROWSER_REJECTION_MSGID, } from "./syslog/errors.js";
+export type { ErrorCaptureOptions } from "./syslog/errors.js";
+export { getPageId, withRequestId, getCurrentRequestId, installRequestIdProvider, resetClientLogContext, } from "./syslog/context.js";
+export { NODEFONY_CHANNEL_NAMESPACE, PLATFORM_CHANNELS, PLATFORM_INBOUND, PLATFORM_METHODS, PLATFORM_EVENTS, isPlatformChannel, } from "../realtime/platformChannels.js";
+export type { PlatformChannel, PlatformInboundChannel, PlatformMethod, } from "../realtime/platformChannels.js";
+export type { RateChangeReason, RateDecision, AdaptiveRateOptions, BindAdaptiveOptions, AdaptiveChannelBinding, AdaptiveScheduler, } from "./realtime/AdaptiveRate.js";
+export { connectShared, observeState, observeIdentity, observeReconnect, observeChannel, observeChannelData, observeChannelStats, observeAdaptiveChannel, observeSyslog, observeNotices, observeNoticeLog, observeSnapshot, socketSnapshot, adaptiveRebindKey, } from "./realtime/observe.js";
+export type { Emit, Dispose, ObservableClient, ConnectSharedOptions, SharedConnection, AdaptiveObserveOptions, ObserveSyslogOptions, ObserveNoticeLogOptions, SocketSnapshot, } from "./realtime/observe.js";
+export { LOCAL_EVENTS, isLocalEvent } from "./realtime/localEvents.js";
+export type { LocalEvent } from "./realtime/localEvents.js";

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

@@ -0,0 +1,207 @@
+/**
+ * `nodefony/react` — bindings React **fins** du client temps réel isomorphe.
+ *
+ * Adapte le {@link RealtimeClient} (agnostique : `on()`/`emit()`/`state`) à la
+ * réactivité React, sans MobX ni glue à recopier dans chaque app. Réutilisable
+ * par Studio ET n'importe quelle app React servie par `@nodefony/frontend`.
+ *
+ * Principe : des hooks **ciblés et composables** (un hook = une responsabilité),
+ * tous **marqués `nodefony`** (`useNodefony*`) pour les repérer d'un coup d'œil.
+ * Pas un god-hook : on compose ce dont la vue a besoin. `react` est une peerDep
+ * **optionnelle** (ce module n'est tiré que si on importe `nodefony/react`).
+ * Aucun JSX (provider via `createElement`) → le build Core ne dépend pas d'un
+ * transform JSX.
+ *
+ * **Ce fichier ne contient PLUS de 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 Vue, Angular
+ * et Svelte consomment à l'identique. Ici ne reste que la traduction *rappel +
+ * libération → réactivité React* — la seule chose qu'une liaison a le droit de
+ * contenir. Un hook qui réencoderait une règle la ferait diverger des trois
+ * autres fronts, en silence.
+ *
+ * L'app reste maîtresse du **cycle de connexion** (`client.connect()`), montée
+ * une fois (ex. au shell). Les hooks ne gèrent QUE l'abonnement aux canaux.
+ *
+ * @module nodefony/react
+ */
+import * as React from "react";
+import type { RealtimeClient } from "../realtime/RealtimeClient.js";
+import type { RealtimeState, NodefonyNotice, RealtimeIdentity, MessageStats } 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";
+export interface NodefonyProviderProps {
+    /**
+     * Adresse du serveur temps réel — la voie SIMPLE. Le Provider 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 (c'est le cas de la console d'administration, qui
+     * re-négocie la socket sur changement d'identité).
+     *
+     * Fournie, elle l'emporte sur `url` et le Provider ne touche pas au cycle :
+     * ni `connect`, ni `disconnect`.
+     */
+    client?: RealtimeClient;
+    children?: React.ReactNode;
+}
+/**
+ * Injecte le client temps réel Nodefony dans le sous-arbre. À monter une fois,
+ * au-dessus des composants qui consomment les hooks `useNodefony*`.
+ *
+ * @example Cas simple — deux concepts, ce Provider et un hook :
+ * ```tsx
+ * <NodefonyProvider url="/api/live/realtime">
+ *   <Chat />
+ * </NodefonyProvider>
+ * ```
+ *
+ * @example Cas avancé — l'application possède le cycle de connexion :
+ * ```tsx
+ * <NodefonyProvider client={monClient}>…</NodefonyProvider>
+ * ```
+ */
+export declare function NodefonyProvider(props: NodefonyProviderProps): React.ReactElement;
+/**
+ * `useNodefony()` — le client temps réel brut (hub : canaux, syslog, stats…).
+ * Tête de gondole + échappatoire pour les cas avancés. Référence stable (pas de
+ * re-render) ; pour l'état réactif, utiliser les hooks dédiés ci-dessous.
+ *
+ * @throws si appelé hors d'un `<NodefonyProvider>`.
+ */
+export declare function useNodefony(): RealtimeClient;
+/**
+ * `useNodefonyState()` — état de la connexion (`"connected" | "reconnecting" | …`).
+ * `useSyncExternalStore` : re-render UNIQUEMENT au changement d'état (snapshot
+ * primitif, sans tearing en mode concurrent).
+ *
+ * Branché sur `onState` — la porte publique — et non sur le nom de l'événement
+ * local, qui n'a pas à sortir du client.
+ */
+export declare function useNodefonyState(): 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'a été reçu ; une fois reçu, un
+ * visiteur anonyme a `authenticated: false`. `useSyncExternalStore` → re-render
+ * uniquement quand l'identité change ((re)welcome ou logout). Brique du gating
+ * front : `authenticated:false` → écran login, **sans** route `/auth/me`.
+ */
+export declare function useNodefonyIdentity(): RealtimeIdentity | null;
+/**
+ * `useNodefonyChannel()` — s'abonne à un canal pub/sub : `onMessage` est appelé
+ * à chaque message. Le socle apparie subscribe/unsubscribe serveur (ref-comptés)
+ * et le re-subscribe au reconnect. Le handler peut changer à chaque render sans
+ * re-déclencher l'abonnement (capturé via ref) ; passer `deps` si le canal
+ * effectif dépend d'autres valeurs.
+ */
+export declare function useNodefonyChannel(channel: string, onMessage: (payload: unknown) => void, deps?: React.DependencyList): void;
+/**
+ * `useNodefonyChannelData()` — la **dernière valeur** reçue sur un canal (cas le
+ * plus courant : dernière mesure d'un flux de stats). `null` tant que rien n'est
+ * arrivé.
+ */
+export declare function useNodefonyChannelData<T = unknown>(channel: string, initial?: T | null): T | null;
+/** Réglages adaptatifs du hook (cadence désirée fixée à part par `intervalMs`). */
+export type AdaptiveChannelHookOptions = Omit<BindAdaptiveOptions, "intervalMs" | "onRate">;
+/** Résultat de {@link useNodefonyAdaptiveChannelData} : dernière valeur + cadence réelle. */
+export interface AdaptiveChannelData<T> {
+    /** Dernière valeur reçue, `null` tant que rien n'est arrivé. */
+    data: T | null;
+    /** Cadence effective courante (ms) — bouge avec l'AIMD, à afficher en badge. */
+    intervalMs: number;
+}
+/**
+ * `useNodefonyAdaptiveChannel()` — équivalent **handler-based** de {@link useNodefonyChannel}
+ * mais en **cadence adaptative** (AIMD client-driven, cf {@link RealtimeClient.adaptiveChannel}) :
+ * la lib recule la cadence sous famine puis la remonte quand c'est sain. `onMessage` reçoit
+ * chaque frame (handler riche autorisé) ; **renvoie la cadence effective** (ms) pour un badge.
+ * Primitif commun à tous les dashboards d'état (Supervision, ORM…) → **logique live identique**.
+ * Réservé aux canaux d'ÉTAT (latest-wins). Réglage `enabled` (off = abonnement fixe).
+ *
+ * Le ré-abonnement n'est relancé que si `base`, `desiredMs`, `enabled` ou `deps` changent —
+ * la clé vient de {@link adaptiveRebindKey}, la MÊME que celle des autres liaisons (le
+ * handler + les `opts` sont capturés par ref → identité instable sans re-bind).
+ */
+export declare function useNodefonyAdaptiveChannel(base: string, onMessage: (payload: unknown) => void, desiredMs: number, opts?: AdaptiveChannelHookOptions, deps?: React.DependencyList): number;
+/**
+ * `useNodefonyAdaptiveChannelData()` — comme {@link useNodefonyChannelData} mais en cadence
+ * adaptative. Mince surcouche de {@link useNodefonyAdaptiveChannel} : garde la **dernière
+ * valeur** reçue + renvoie la cadence effective (badge UI). Réservé aux canaux d'ÉTAT.
+ */
+export declare function useNodefonyAdaptiveChannelData<T = unknown>(base: string, desiredMs: number, opts?: AdaptiveChannelHookOptions, deps?: React.DependencyList): AdaptiveChannelData<T>;
+/**
+ * Stats observées d'un canal (telles que calculées par le client Core).
+ *
+ * Alias du contrat isomorphe {@link MessageStats} : une copie locale de la forme
+ * aurait divergé du jour où le client ajoute un compteur.
+ */
+export type ChannelStatsSnapshot = MessageStats;
+/**
+ * `useNodefonyChannelStats()` — stats live d'un canal (débit, série VU-mètre,
+ * total). Source = le client Core (`getChannelStats`, échantillonné 1×/s).
+ * Implémenté en `state`+effet (pas `useSyncExternalStore`) car le snapshot est
+ * un objet recréé → la stabilité de référence requise par le store externe ne
+ * tiendrait pas.
+ */
+export declare function useNodefonyChannelStats(channel: string): 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, aucune trame émise
+ * pour mesurer.
+ *
+ * La donnée est au socle, la **boîte qui l'affiche** reste à chaque front : les
+ * quatre vitrines lisaient ces cinq champs à la main, c'est-à-dire quatre
+ * lectures qui divergeront.
+ */
+export declare function useNodefonySnapshot(): SocketSnapshot | null;
+export interface UseSyslogOptions {
+    /** Taille max du ring buffer (anciennes lignes é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()` — flux syslog prêt à l'emploi : ring buffer borné +
+ * filtre de sévérité. Le format **coalescé** du canal (`{ logs: Pdu[], dropped }`),
+ * l'entrée unique, la taille de l'anneau et le canal par défaut viennent du
+ * socle ({@link observeSyslog}) : ce hook n'en connaît aucun. Brique de la page
+ * Logs — un seul appel remplace l'effet + le buffer manuels.
+ */
+export declare function useNodefonySyslog(opts?: UseSyslogOptions): unknown[];
+/**
+ * `useNodefonyNotifications()` — s'abonne au flux de **notices normalisées** du
+ * client : criticités qui cassent le temps réel (close codes RFC 6455 interprétés),
+ * erreurs serveur poussées, rétablissement de connexion. `onNotice` est appelé
+ * pour CHAQUE notice → brancher un centre de notifications (snackbar). Le handler
+ * peut changer à chaque render sans re-déclencher l'abonnement (capturé via ref).
+ *
+ * À monter **une seule fois** (shell de l'app) pour ne pas dupliquer les toasts.
+ */
+export declare function useNodefonyNotifications(onNotice: (notice: NodefonyNotice) => void, deps?: React.DependencyList): void;
+export interface UseNoticeLogOptions {
+    /** Taille max du ring (anciennes notices évincées). Défaut 50. */
+    max?: number;
+    /** Ne garder que ces sources (ex `["realtime"]`). Toutes par défaut. */
+    sources?: NodefonyNotice["source"][];
+}
+/**
+ * `useNodefonyNoticeLog()` — ring buffer borné des dernières notices, filtrable
+ * par source. Brique du hub temps réel (« incidents temps réel ») : un historique
+ * léger des criticités realtime, distinct des toasts éphémères. La taille de
+ * l'anneau et le filtrage viennent du socle ({@link observeNoticeLog}).
+ */
+export declare function useNodefonyNoticeLog(opts?: UseNoticeLogOptions): NodefonyNotice[];

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

@@ -0,0 +1,138 @@
+/**
+ * AdaptiveRate — cadence ADAPTATIVE automatique d'un canal d'ÉTAT, **client-driven**
+ * (niveau 1, zéro changement serveur). Pendant exact de l'ABR vidéo (HLS/DASH ajustent
+ * la qualité selon le buffer) et du contrôle de congestion réseau (TCP **AIMD**).
+ *
+ * Idée : la cadence vit dans le nom du canal (cf {@link rateChannel} — 1 canal = 1 cadence
+ * = 1 ticker serveur). Si le client observe que les frames arrivent **plus lentement** que
+ * demandé (famine ⇒ event-loop serveur ou réseau sous pression), il se ré-abonne à une
+ * cadence **plus grossière** (`1s→2s→5s`) → moins de pushes → la pression retombe → le flux
+ * récupère ; quand c'est sain durablement, il remonte **doucement** vers la cadence désirée.
+ *
+ * AIMD (asymétrie anti-oscillation, comme TCP) :
+ *  - **Multiplicative Decrease** : famine ⇒ on monte d'un cran l'échelle (cadence grossie),
+ *    immédiat. L'échelle géométrique (×2) rend la décrue multiplicative.
+ *  - **Additive Increase** : on ne redescend d'un cran (cadence affinée) qu'après une
+ *    **fenêtre** de N échantillons sains → reprise lente.
+ *  - **bande morte** (hystérésis) entre « sain » et « famine » : aucun changement → pas de
+ *    flip-flop.
+ *
+ * Réservé aux canaux d'**ÉTAT** (latest-wins : supervision, stats) où décimer est sans perte.
+ * PAS pour les canaux d'**ÉVÉNEMENTS** (syslog, frames protocole) où chaque item compte
+ * (eux se batchent, pas se décimer).
+ *
+ * Cette classe est la **machine à états pure** (aucun timer, aucune socket) → déterministe
+ * et testable. Le câblage à une socket réelle vit dans {@link bindAdaptiveChannel}.
+ *
+ * @see {@link bindAdaptiveChannel} — glue socket + watchdog.
+ * @see {@link rateChannel} — convention de nommage cadencé partagée client↔serveur.
+ */
+import type { IRealtimeSocket, RealtimeHandler } from "../../realtime/IRealtimeSocket.js";
+/** Raison d'un changement de cadence (pour un badge UI). */
+export type RateChangeReason = "init" | "decrease" | "increase";
+/** Décision de la boucle AIMD : nouvelle cadence + pourquoi. `null` = ne rien changer. */
+export interface RateDecision {
+    /** Cadence cible (ms). */
+    readonly intervalMs: number;
+    /** Cause du changement. */
+    readonly reason: RateChangeReason;
+}
+/** Réglages de la cadence adaptative. Seul `intervalMs` est requis. */
+export interface AdaptiveRateOptions {
+    /** Cadence désirée la plus fine (ms) = bas de l'échelle. */
+    readonly intervalMs: number;
+    /** Cadence par défaut serveur du canal (le canal nu la vaut). */
+    readonly defaultMs?: number;
+    /** Échelle de cadences (ms, croissante). Dérivée ×2 jusqu'à `maxMs` si absente. */
+    readonly ladder?: number[];
+    /** Famine : `gap observé > k × cadence courante` ⇒ décélère. Défaut `1.8`. */
+    readonly starvationFactor?: number;
+    /** Sain : `gap ≤ k × cadence` compte comme bon échantillon. Défaut `1.25`. */
+    readonly healthyFactor?: number;
+    /** Nb d'échantillons sains consécutifs avant d'accélérer (AI). Défaut `4`. */
+    readonly recoveryWindow?: number;
+    /** Plafond de l'échelle dérivée (ms). Défaut `60000`. */
+    readonly maxMs?: number;
+}
+export declare class AdaptiveRate {
+    private readonly ladder;
+    private readonly starvationFactor;
+    private readonly healthyFactor;
+    private readonly recoveryWindow;
+    /** Position dans l'échelle (0 = cadence la plus fine = désirée). */
+    private idx;
+    /** Échantillons sains consécutifs depuis le dernier changement. */
+    private healthy;
+    /** Timestamp (ms) de la dernière frame ; `null` = pas de référence (post-switch/init). */
+    private lastFrameTs;
+    constructor(options: AdaptiveRateOptions);
+    /** Cadence courante (ms). */
+    current(): number;
+    /** Décale d'un cran vers le grossier (MD) ; renvoie `true` si la cadence a changé. */
+    private decrease;
+    /** Décale d'un cran vers le fin (AI) ; renvoie `true` si la cadence a changé. */
+    private increase;
+    /** Réamorce la mesure (après un changement de cadence). */
+    private resetSample;
+    /**
+     * À appeler à CHAQUE frame reçue. Pilote l'**AI** (reprise) et détecte aussi la famine
+     * sur frames lentes (**MD**).
+     *
+     * @param now - horloge (ms).
+     * @returns une {@link RateDecision} si la cadence doit changer, sinon `null`.
+     */
+    noteFrame(now: number): RateDecision | null;
+    /**
+     * Watchdog : à appeler périodiquement. Détecte la famine **totale** (plus aucune frame)
+     * que {@link noteFrame} ne verrait pas (faute de frame).
+     *
+     * @param now - horloge (ms).
+     * @returns une {@link RateDecision} (toujours `"decrease"`) si la cadence doit grossir.
+     */
+    checkStarvation(now: number): RateDecision | null;
+}
+/** Planificateur du watchdog — injectable pour des tests déterministes (défaut : globals). */
+export interface AdaptiveScheduler {
+    set(cb: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+}
+/** Réglages du câblage adaptatif = {@link AdaptiveRateOptions} + crochets/injection. */
+export interface BindAdaptiveOptions extends AdaptiveRateOptions {
+    /**
+     * Active l'AIMD. `false` ⇒ **mode fixe** : abonnement simple à `intervalMs` (aucun
+     * watchdog, aucune mesure, aucun ré-abonnement). Défaut `true`. Permet à l'UI de
+     * basculer adaptatif ⇄ fixe sans changer de code d'appel.
+     */
+    enabled?: boolean;
+    /** Notifié à chaque cadence effective (incl. `"init"`) — utile pour un badge UI. */
+    onRate?: (intervalMs: number, reason: RateChangeReason) => void;
+    /** Horloge (ms). Défaut `performance.now()`/`Date.now()`. */
+    clock?: () => number;
+    /** Planificateur du watchdog. Défaut `setInterval`/`clearInterval`. */
+    scheduler?: AdaptiveScheduler;
+}
+/** Poignée du canal adaptatif — cadence courante + coupure. */
+export interface AdaptiveChannelBinding {
+    /** Cadence courante (ms). */
+    readonly intervalMs: number;
+    /** Canal effectivement abonné (`base` ou `base:<ms>`). */
+    readonly channel: string;
+    /** Coupe tout : watchdog + handler + `unsubscribe`. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Câble un {@link AdaptiveRate} à une socket réelle : abonne `base` à sa cadence désirée,
+ * mesure la gigue d'arrivée, et **ré-abonne** automatiquement à une cadence plus grossière
+ * en cas de famine (MD) puis plus fine quand c'est sain (AI). Les frames continuent d'être
+ * livrées à `handler` à travers les changements de cadence.
+ *
+ * Réservé aux canaux d'ÉTAT (latest-wins). Pour les canaux d'événements, ne pas décimer.
+ *
+ * @param socket - la socket Nodefony ({@link IRealtimeSocket}).
+ * @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 + injections.
+ * @returns une {@link AdaptiveChannelBinding} (cadence courante + `dispose`).
+ */
+export declare function bindAdaptiveChannel(socket: IRealtimeSocket, base: string, handler: RealtimeHandler, options: BindAdaptiveOptions): AdaptiveChannelBinding;
+export default AdaptiveRate;

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

@@ -0,0 +1,27 @@
+import type { IRealtimeTransport } from "../../realtime/IRealtimeTransport.js";
+/**
+ * BrowserWsTransport — transport {@link IRealtimeTransport} pour le navigateur :
+ * wrap d'un `WebSocket` natif. Volontairement « bête » : il ouvre/envoie/ferme et
+ * relaie les events. L'orchestration (reconnect, backoff, heartbeat, state machine)
+ * vit AU-DESSUS dans `RealtimeClient` — qui crée un transport NEUF à chaque tentative.
+ *
+ * L'URL reçue est déjà normalisée (ws/wss, token) par l'appelant.
+ */
+export declare class BrowserWsTransport implements IRealtimeTransport {
+    private readonly url;
+    private ws;
+    private _onOpen;
+    private _onMessage;
+    private _onClose;
+    private _onError;
+    constructor(url: string);
+    connect(): void;
+    send(raw: string): void;
+    close(code?: number, reason?: string): void;
+    get readyState(): number;
+    onOpen(cb: () => void): void;
+    onMessage(cb: (raw: string) => void): void;
+    onClose(cb: (code: number, reason: string) => void): void;
+    onError(cb: (err: unknown) => void): void;
+}
+export default BrowserWsTransport;