nodefony 7.0.2 → 10.0.0-alpha.2

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

@@ -0,0 +1,70 @@
+/**
+ * Notice temps réel normalisée — Core isomorphe Nodefony.
+ *
+ * Format **unique** d'un retour à porter à l'attention de l'utilisateur, quelle
+ * que soit sa source (transport temps réel, appel data plane, push serveur). Le
+ * centre de notifications d'une app (Studio : snackbar Mantine) consomme ce format
+ * sans connaître l'origine → réutilisable par TOUTE app (`import … from "nodefony"`).
+ */
+import type { IRealtimeDenied } from "../../realtime/RealtimeEventMap.js";
+export type { IRealtimeDenied };
+/** Sévérité d'affichage — alignée sur les niveaux snackbar usuels. */
+export type NoticeLevel = "success" | "info" | "warning" | "error";
+/** Notice normalisée prête à afficher (snackbar / centre de notifications). */
+export interface NodefonyNotice {
+    /** Sévérité d'affichage. */
+    level: NoticeLevel;
+    /** Titre court (gras), optionnel. */
+    title?: string;
+    /** Message lisible (déjà localisé FR). */
+    message: string;
+    /** Origine — `realtime` (transport WS), `api` (data plane HTTP), `server` (push). */
+    source: "realtime" | "api" | "server";
+    /** Code corrélé : close code WS, status HTTP ou code d'erreur JSON-RPC. */
+    code?: number;
+    /** Timestamp (ms epoch) de production. */
+    ts: number;
+}
+/**
+ * Traduit un refus de canal (`realtime:denied`, {@link IRealtimeDenied}) en
+ * {@link NodefonyNotice}. Pendant FRAME du {@link closeCodeToNotice} (qui traite
+ * la fermeture de la CONNEXION) : ici la connexion vit, seul l'abonnement à CE
+ * canal n'a pas abouti.
+ *
+ * Le message SUIT le motif, parce que les trois n'appellent pas le même geste :
+ * un accès refusé demande une élévation de droits, un plafond atteint demande de
+ * libérer un abonnement, un canal sans producteur demande de relire son nom. Un
+ * « accès refusé » affiché sur une faute de frappe envoie chercher un droit qui
+ * n'a jamais manqué. Ce qui reste générique, et le restera, c'est le DÉTAIL de la
+ * politique : le serveur ne dit jamais quel rôle ou quel scope manque.
+ *
+ * @param denied - `{ channel, reason }` reçu du serveur.
+ * @returns une notice prête à afficher (toujours, contrairement au close-code).
+ */
+export declare function deniedToNotice(denied: IRealtimeDenied): NodefonyNotice;
+/**
+ * Traduit un **code de fermeture WebSocket** (RFC 6455 §7.4) en {@link NodefonyNotice}
+ * — pendant CLIENT du `toWsCloseCode` serveur (`@nodefony/http`). Pur, sans état,
+ * donc trivialement testable et réutilisable.
+ *
+ * Retourne `null` pour une fermeture **propre** (1000) ou **attendue** (1001 going
+ * away = restart serveur, le reconnect rétablit) : pas de bruit inutile.
+ *
+ * @param code - code de fermeture reçu (`CloseEvent.code`).
+ * @param reason - description optionnelle (`CloseEvent.reason`), ajoutée au message.
+ * @returns une notice à afficher, ou `null` si la fermeture ne mérite aucune alerte.
+ */
+export declare function closeCodeToNotice(code: number | undefined, reason?: string): NodefonyNotice | null;
+/**
+ * Faut-il tenter une reconnexion après ce close code WebSocket ? Pendant CLIENT
+ * de la sémantique RFC 6455 §7.4 émise par le serveur (`toWsCloseCode`).
+ *
+ * `false` pour les fermetures DÉFINITIVES (cf {@link FATAL_CLOSE_CODES}) : l'app
+ * doit agir (ex. login après un 1008) puis rétablir explicitement (`connect()` /
+ * `retryNow()`). `true` pour les transitoires (1001 restart, 1006 perte réseau,
+ * 1011 erreur serveur, code absent/inconnu) où la reconnexion a une chance.
+ *
+ * @param code - close code reçu (`CloseEvent.code`), ou `undefined` (anormal).
+ * @returns `true` si une reconnexion auto est pertinente.
+ */
+export declare function isReconnectableCloseCode(code: number | undefined): boolean;

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

@@ -0,0 +1,284 @@
+/**
+ * observe — **socle agnostique des liaisons de vue** du client temps réel.
+ *
+ * Souscrire à un canal, tenir une dernière valeur, borner un journal, filtrer par
+ * sévérité, se désabonner proprement : rien de tout cela n'appartient à React, à
+ * Vue, à Angular ni à Svelte. Ce qui leur appartient — la SEULE chose qu'une
+ * liaison a le droit de contenir — c'est la traduction *rappel + libération →
+ * réactivité locale* : un `useState`, un `ref`, un `signal`, une rune.
+ *
+ * Chaque fonction de ce module a donc la même forme, et c'est tout le contrat :
+ *
+ * ```
+ * observeX(client, …arguments, emit) → dispose
+ * ```
+ *
+ * `emit` est appelé avec la valeur courante ; `dispose` coupe tout. Une liaison
+ * s'écrit alors en trois lignes dans n'importe quel framework, et les onze règles
+ * qui vivaient dans les hooks React — précédence de la socket fournie, cycle de
+ * connexion, appariement `on`↔`subscribe`, format coalescé du journal, tailles
+ * d'anneau, canal par défaut — n'existent qu'ICI.
+ *
+ * Pourquoi ce module existe : sans lui, porter les douze hooks vers trois autres
+ * fronts donnait **quatre implémentations de la même règle**, qui divergent en
+ * silence. Le dépôt l'a déjà payé — `"__state__"` était recopié en dur dans les
+ * trois gabarits, et la convention de cadence avait été fabriquée à la main trois
+ * fois côté navigateur avant d'être centralisée.
+ *
+ * Zéro dépendance à un framework de vue, zéro DOM : ce fichier tourne dans un
+ * test Node comme dans un bundle navigateur.
+ *
+ * @module nodefony/client
+ */
+import { RealtimeClient } from "./RealtimeClient.js";
+import type { RealtimeState, RealtimeIdentity, RealtimeReconnectInfo, NodefonyNotice, MessageStats } from "./RealtimeClient.js";
+import type { BindAdaptiveOptions, AdaptiveChannelBinding } from "./AdaptiveRate.js";
+/** Rappel d'une liaison de vue : reçoit la valeur courante. */
+export type Emit<T> = (value: T) => void;
+/** Libération d'une souscription. Idempotente chez tous les observateurs de ce module. */
+export type Dispose = () => void;
+/**
+ * Socket sur laquelle un observateur travaille. Volontairement le client
+ * NON paramétré : une liaison de vue ne connaît pas les cartes d'événements
+ * typées de l'application.
+ */
+export type ObservableClient = RealtimeClient;
+/** Options de {@link connectShared} — l'adresse, ou la socket déjà construite. */
+export interface ConnectSharedOptions {
+    /**
+     * Adresse du serveur temps réel — la voie SIMPLE. La socket partagée de cette
+     * URL est fabriquée (ou réutilisée) et connectée par {@link SharedConnection.start}.
+     */
+    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 son cycle n'est **pas** touché : ni
+     * `connect`, ni `disconnect`.
+     */
+    client?: ObservableClient;
+}
+/** Résultat de {@link connectShared} : la socket, à qui elle appartient, et comment la démarrer. */
+export interface SharedConnection {
+    /** La socket à donner aux observateurs. */
+    socket: ObservableClient;
+    /**
+     * `true` si c'est nous qui l'avons obtenue depuis l'URL — donc à nous de la
+     * connecter. `false` si l'application l'a fournie : son cycle lui appartient.
+     */
+    owned: boolean;
+    /**
+     * Ouvre la connexion si elle nous appartient, sinon ne fait rien. Idempotente
+     * (`connect()` est un no-op si la socket est déjà connectée ou en cours), et
+     * le rejet est avalé : la reconnexion automatique prend le relais, et l'état
+     * reste lisible par {@link observeState}.
+     */
+    start(): void;
+}
+/**
+ * Résout la socket partagée d'une adresse — ou adopte celle qu'on lui donne —
+ * et rend de quoi la démarrer sans jamais la couper.
+ *
+ * Trois règles tiennent dans cette fonction, et c'est pour cela qu'elle existe :
+ *
+ * 1. **`client` l'emporte sur `url`** ; une socket fournie appartient à
+ *    l'application.
+ * 2. **`connect()` est idempotent et son rejet est avalé** — le double montage
+ *    du mode strict de React n'ouvre pas deux sockets, et un serveur absent au
+ *    premier essai ne remonte pas une erreur non gérée.
+ * 3. **Jamais de `disconnect()` au démontage.** La connexion appartient à la
+ *    PAGE, pas au composant : couper ici tranche les requêtes en vol des autres
+ *    consommateurs de la même socket partagée. C'est une régression déjà vécue.
+ *
+ * Recopiée dans une quatrième liaison, la règle 3 se perd — elle est en creux
+ * (« ne pas faire »), donc invisible à la relecture.
+ *
+ * @example La voie simple, dans n'importe quel framework :
+ * ```ts
+ * const live = connectShared({ url: "/api/live/realtime" });
+ * live.start();
+ * observeChannelData(live.socket, "live:events", (e) => setDernier(e));
+ * ```
+ *
+ * @throws si ni `url` ni `client` ne sont fournis — l'adresse dépend de
+ *   l'application, le framework n'en devine aucune.
+ */
+export declare function connectShared(opts: ConnectSharedOptions): SharedConnection;
+/**
+ * Observe l'état de la connexion. `emit` reçoit l'état courant **immédiatement**,
+ * puis à chaque transition — une liaison n'a donc rien à initialiser à part.
+ */
+export declare function observeState(client: ObservableClient, emit: Emit<RealtimeState>): Dispose;
+/**
+ * Observe l'identité résolue par le serveur au welcome (`null` tant qu'aucun
+ * welcome n'est arrivé, et après un `disconnect()` volontaire). `emit` reçoit la
+ * valeur courante immédiatement, puis à chaque (re)welcome.
+ *
+ * Brique du gating d'écran : `authenticated: false` → écran de connexion, sans
+ * route `/auth/me`.
+ */
+export declare function observeIdentity(client: ObservableClient, emit: Emit<RealtimeIdentity | null>): Dispose;
+/**
+ * Observe les **tentatives de reconnexion** programmées par le back-off :
+ * numéro d'essai, délai retenu, échéance absolue. De quoi rendre un compte à
+ * rebours plutôt qu'un « déconnecté » muet.
+ *
+ * Contrairement aux autres observateurs, rien n'est émis à la souscription : une
+ * tentative est un ÉVÉNEMENT, pas un état — il n'y a pas de « valeur courante »
+ * à rejouer, et en inventer une afficherait un compte à rebours périmé.
+ */
+export declare function observeReconnect(client: ObservableClient, emit: Emit<RealtimeReconnectInfo>): Dispose;
+/**
+ * Observe un canal pub/sub : `emit` est appelé pour chaque message reçu.
+ *
+ * L'appariement `on`↔`subscribe` et `dispose`↔`unsubscribe` n'est pas réécrit
+ * ici : c'est {@link RealtimeClient.channel} qui l'encapsule, et le rejouer
+ * mettrait la même règle deux fois dans le cœur. L'abonnement serveur est
+ * ref-compté (N observateurs du même canal = un seul abonnement réseau) et
+ * rejoué à chaque reconnexion.
+ */
+export declare function observeChannel(client: ObservableClient, channel: string, emit: Emit<unknown>): Dispose;
+/**
+ * Observe la **dernière valeur** reçue sur un canal — le cas le plus courant
+ * (dernière mesure d'un flux d'état). `emit` reçoit `initial` immédiatement,
+ * puis chaque nouvelle valeur : dernier arrivé gagne.
+ */
+export declare function observeChannelData<T = unknown>(client: ObservableClient, channel: string, emit: Emit<T | null>, initial?: T | null): Dispose;
+/**
+ * Observe les **statistiques** d'un canal (débit, série du VU-mètre, total),
+ * rafraîchies par l'échantillonneur du client une fois par seconde. `emit`
+ * reçoit l'instantané courant immédiatement, puis à chaque échantillon.
+ *
+ * L'instantané est un objet recréé à chaque lecture : une liaison qui exige une
+ * référence stable (le store externe de React) ne doit pas s'y brancher
+ * directement — c'est pourquoi le hook correspondant tient un état local.
+ */
+export declare function observeChannelStats(client: ObservableClient, channel: string, emit: Emit<MessageStats | null>): Dispose;
+/**
+ * Clé de **re-liaison** d'un canal en cadence adaptative.
+ *
+ * Trois valeurs, et trois seulement, doivent défaire puis refaire l'abonnement :
+ * le canal de base, la cadence désirée et l'interrupteur adaptatif. Ni le
+ * gestionnaire, ni le reste des réglages — leur identité change à chaque rendu
+ * dans la plupart des frameworks, et re-lier à chaque rendu couperait le flux en
+ * boucle.
+ *
+ * Chaque liaison a besoin de cette clé sous une forme différente (liste de
+ * dépendances React, source d'un `watch` Vue, `$effect` Svelte) ; ce qui doit
+ * rester commun, c'est **ce qu'elle contient**.
+ */
+export declare function adaptiveRebindKey(base: string, desiredMs: number, enabled?: boolean): string;
+/** Options de {@link observeAdaptiveChannel} — la cadence désirée est passée à part. */
+export type AdaptiveObserveOptions = Omit<BindAdaptiveOptions, "intervalMs">;
+/**
+ * Observe un canal d'ÉTAT en **cadence adaptative** (AIMD piloté par le client) :
+ * la cadence recule sous famine et remonte quand c'est sain, sans changement
+ * serveur. `emit` reçoit chaque frame à travers les changements de cadence.
+ *
+ * Réservé aux canaux latest-wins : décimer un canal d'événements perd des
+ * messages.
+ *
+ * @param desiredMs - cadence souhaitée (ms).
+ * @param options - réglages AIMD ; `onRate` reste disponible pour afficher la
+ *   cadence effective dans un badge.
+ * @returns la poignée du binding (cadence courante, canal effectif, `dispose`).
+ */
+export declare function observeAdaptiveChannel(client: ObservableClient, base: string, emit: Emit<unknown>, desiredMs: number, options?: AdaptiveObserveOptions): AdaptiveChannelBinding;
+/**
+ * Ce que le client sait de sa PROPRE socket, à un instant donné.
+ *
+ * Pourquoi ce contrat existe : quatre écrans lisaient déjà `subscribedChannels`,
+ * `framesReceived`, `lastFrameAt` et `lastFrameMethod` à la main pour afficher
+ * la même chose — c'est-à-dire quatre lectures qui divergeront. La donnée est
+ * parfaitement agnostique ; seule sa mise en page appartient à la vue.
+ *
+ * La frontière est là, et elle est nette : **l'instantané est ici, la boîte qui
+ * l'affiche reste chez 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 interface SocketSnapshot {
+    /** L'adresse du serveur temps réel — de QUELLE socket cet instantané parle. */
+    url: string | null;
+    /** État de la connexion. */
+    state: RealtimeState;
+    /** Canaux effectivement tenus par cette connexion. */
+    channels: readonly string[];
+    /** Trames reçues depuis l'ouverture. */
+    frames: number;
+    /** Trames perdues faute de transport ouvert — un silence qui se compte. */
+    unsent: number;
+    /** Méthode et horodatage de la dernière trame reçue (`null` si aucune). */
+    lastFrame: {
+        method: string | null;
+        at: number | null;
+    };
+    /** Tentatives de reconnexion depuis la dernière connexion réussie. */
+    reconnectAttempts: number;
+    /** Échéance de la prochaine tentative (ms epoch), `null` hors reconnexion. */
+    nextRetryAt: number | null;
+    /** Identité résolue par le serveur, `null` avant le premier welcome. */
+    identity: RealtimeIdentity | null;
+}
+/**
+ * Lit l'instantané courant. Purement local : aucune trame n'est émise, rien
+ * n'est demandé au serveur — afficher cet état ne coûte donc rien au réseau.
+ */
+export declare function socketSnapshot(client: ObservableClient): SocketSnapshot;
+/**
+ * Observe l'instantané : `emit` reçoit la valeur courante immédiatement, puis à
+ * chaque échantillon du client (une fois par seconde) et à chaque changement
+ * d'état — les deux seuls moments où il peut avoir bougé de façon visible.
+ *
+ * L'horloge est celle de l'échantillonneur DÉJÀ en place ; une liaison qui
+ * poserait son propre `setInterval` ajouterait un second réveil par seconde
+ * pour la même mesure.
+ */
+export declare function observeSnapshot(client: ObservableClient, emit: Emit<SocketSnapshot>): Dispose;
+/** Options de {@link observeSyslog}. */
+export interface ObserveSyslogOptions {
+    /** 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 : le canal de journaux de la plateforme. */
+    channel?: string;
+}
+/**
+ * Observe le **journal du serveur** : anneau borné, filtre de sévérité, et
+ * surtout le format **coalescé** du canal (`{ logs: Pdu[], dropped }`) autant que
+ * l'entrée unique. `emit` reçoit le tableau complet à chaque changement — une
+ * nouvelle référence, directement affichable.
+ *
+ * Le format coalescé est du **protocole serveur** : le décoder dans une liaison
+ * de vue, c'est le redécoder dans les trois suivantes. C'est la pire des règles
+ * qui vivaient côté React.
+ *
+ * Le canal par défaut vient de la table des canaux de plateforme — jamais d'une
+ * chaîne écrite en clair, que le prochain renommage laisserait derrière lui.
+ */
+export declare function observeSyslog(client: ObservableClient, emit: Emit<unknown[]>, opts?: ObserveSyslogOptions): Dispose;
+/**
+ * Observe les **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. `emit` est appelé pour CHAQUE notice —
+ * de quoi brancher un centre de notifications.
+ *
+ * À monter **une seule fois** par page, sans quoi les notifications se dupliquent.
+ */
+export declare function observeNotices(client: ObservableClient, emit: Emit<NodefonyNotice>): Dispose;
+/** Options de {@link observeNoticeLog}. */
+export interface ObserveNoticeLogOptions {
+    /** 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"][];
+}
+/**
+ * Observe un **historique borné** des dernières notices, filtrable par source :
+ * un journal léger des incidents temps réel, distinct des notifications
+ * éphémères. `emit` reçoit le tableau complet à chaque changement.
+ */
+export declare function observeNoticeLog(client: ObservableClient, emit: Emit<NodefonyNotice[]>, opts?: ObserveNoticeLogOptions): Dispose;

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

@@ -0,0 +1,15 @@
+/**
+ * `nodefony/roles` — utilitaires d'autorisation par rôles, **purs et isomorphes**
+ * (front + serveur), sans dépendance ni état global.
+ *
+ * - Source de vérité = chaînes `ROLE_*` (ce que transportent JWT/OAuth/claims).
+ * - Contrôle ponctuel sans allocation : {@link hasRole}, {@link hasAnyRole}, {@link hasAllRoles}.
+ * - Contrôles répétés en O(1) : {@link RoleSet}.
+ * - Masques binaires pour ensemble FIXE en hot path serveur : {@link RoleRegistry}.
+ *
+ * Le mécanisme est générique : les rôles applicatifs (ex. `ROLE_DEV`) sont définis par
+ * le consommateur, **jamais** par le core.
+ */
+export type { Role } from "./roles.js";
+export { hasRole, hasAnyRole, hasAllRoles, RoleSet } from "./roles.js";
+export { RoleRegistry, ROLE_MASK_CAPACITY } from "./registry.js";

package/dist/client/types/src/client/roles/registry.d.ts

@@ -0,0 +1,72 @@
+import type { Role } from "./roles.js";
+/**
+ * Nombre maximum de rôles qu'un {@link RoleRegistry} peut indexer en masque `number`.
+ *
+ * Les opérateurs bit-à-bit de JavaScript travaillent sur des entiers **32 bits signés** :
+ * `1 << 31` devient négatif et `1 << 32` repart à `1`. On réserve donc les bits 0..30
+ * (31 rôles) pour rester sur des masques positifs sûrs. Au-delà → utiliser les chaînes
+ * ({@link RoleSet}) ou un futur registre `BigInt`.
+ */
+export declare const ROLE_MASK_CAPACITY = 31;
+/**
+ * Registre OPTIONNEL qui assigne un bit à chaque rôle d'un ENSEMBLE FIXE, pour des
+ * contrôles d'autorisation en masque (`&`/`|`) — O(1), sans allocation, adapté au hot path
+ * serveur (voters, pipeline sécurité) quand les rôles sont connus à l'avance.
+ *
+ * ⚠️ Inadapté aux rôles DYNAMIQUES (créés en base à l'exécution) : ils n'ont pas de bit
+ * fixe → rester sur les chaînes ({@link hasRole}, {@link RoleSet}).
+ * ⚠️ Capacité = {@link ROLE_MASK_CAPACITY} rôles (limite 32 bits de JS).
+ *
+ * @example
+ * const reg = new RoleRegistry().define("ROLE_DEV", "ROLE_SUPERVISOR");
+ * const userMask = reg.mask(["ROLE_DEV"]);
+ * RoleRegistry.hasAny(userMask, reg.mask(["ROLE_DEV", "ROLE_SUPERVISOR"])); // true
+ */
+export declare class RoleRegistry {
+    #private;
+    /**
+     * Déclare un ou plusieurs rôles et leur assigne un bit (idempotent : un rôle déjà
+     * connu conserve son bit).
+     *
+     * @param roles - rôles à enregistrer
+     * @returns le registre (chaînable)
+     * @throws {RangeError} si la capacité {@link ROLE_MASK_CAPACITY} est dépassée
+     */
+    define(...roles: Role[]): this;
+    /**
+     * @param role - rôle recherché
+     * @returns le bit du rôle (puissance de 2), ou `0` si inconnu
+     */
+    bit(role: Role): number;
+    /**
+     * Compile une liste de rôles en masque (OR des bits). Les rôles inconnus sont ignorés
+     * (bit 0) — les déclarer d'abord via {@link RoleRegistry.define}.
+     *
+     * @param roles - rôles à encoder
+     * @returns le masque binaire
+     */
+    mask(roles: readonly Role[]): number;
+    /**
+     * Décode un masque en liste de rôles (ordre de déclaration).
+     *
+     * @param mask - masque binaire
+     * @returns les rôles dont le bit est positionné
+     */
+    roles(mask: number): Role[];
+    /**
+     * Test OR sur masques.
+     *
+     * @param userMask - masque des rôles de l'utilisateur
+     * @param requiredMask - masque des rôles acceptés
+     * @returns `true` si l'utilisateur a au moins un des rôles requis
+     */
+    static hasAny(userMask: number, requiredMask: number): boolean;
+    /**
+     * Test AND sur masques.
+     *
+     * @param userMask - masque des rôles de l'utilisateur
+     * @param requiredMask - masque des rôles requis
+     * @returns `true` si l'utilisateur a tous les rôles requis
+     */
+    static hasAll(userMask: number, requiredMask: number): boolean;
+}

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

@@ -0,0 +1,68 @@
+/**
+ * Type d'un rôle Nodefony. Convention `ROLE_*` (alignée Symfony) — mais le mécanisme
+ * reste agnostique : n'importe quelle chaîne fait office de rôle.
+ */
+export type Role = string;
+/**
+ * Indique si l'utilisateur possède `role`.
+ *
+ * Implémentation sans allocation (parcours linéaire) : optimale pour un contrôle
+ * ponctuel sur un petit tableau (cas courant : 1 à 5 rôles dans un JWT). Pour des
+ * contrôles répétés contre le même utilisateur, préférer {@link RoleSet} (O(1) après
+ * une unique allocation).
+ *
+ * @param userRoles - rôles portés par l'utilisateur (ex. claim `roles` du JWT)
+ * @param role - rôle recherché
+ * @returns `true` si `userRoles` contient `role`
+ */
+export declare function hasRole(userRoles: readonly Role[] | null | undefined, role: Role): boolean;
+/**
+ * Indique si l'utilisateur possède AU MOINS UN des `roles` (OR logique).
+ *
+ * @param userRoles - rôles de l'utilisateur
+ * @param roles - rôles acceptés (l'un suffit)
+ * @returns `true` si l'intersection est non vide ; `false` si `roles` est vide
+ *          (aucune exigence ne peut être satisfaite)
+ */
+export declare function hasAnyRole(userRoles: readonly Role[] | null | undefined, roles: readonly Role[]): boolean;
+/**
+ * Indique si l'utilisateur possède TOUS les `roles` (AND logique).
+ *
+ * @param userRoles - rôles de l'utilisateur
+ * @param roles - rôles tous requis
+ * @returns `true` si chaque rôle requis est présent ; `true` si `roles` est vide
+ *          (aucune exigence — convention de `Array.every`)
+ */
+export declare function hasAllRoles(userRoles: readonly Role[] | null | undefined, roles: readonly Role[]): boolean;
+/**
+ * Ensemble de rôles indexé pour des contrôles répétés en O(1).
+ *
+ * À utiliser quand on teste plusieurs fois les rôles d'un même utilisateur (filtrage
+ * d'une navigation, rendu conditionnel de N panneaux) : une seule allocation de `Set`,
+ * puis chaque `has`/`hasAny`/`hasAll` est O(1)/O(k). Pour un contrôle unique, préférer
+ * les fonctions {@link hasRole} & co (zéro allocation).
+ */
+export declare class RoleSet {
+    #private;
+    /** @param roles - rôles de l'utilisateur (dédoublonnés à la construction) */
+    constructor(roles?: Iterable<Role> | null);
+    /** Nombre de rôles distincts. */
+    get size(): number;
+    /**
+     * @param role - rôle recherché
+     * @returns `true` si le rôle est présent (O(1))
+     */
+    has(role: Role): boolean;
+    /**
+     * @param roles - rôles acceptés
+     * @returns `true` si AU MOINS UN des `roles` est présent (OR)
+     */
+    hasAny(roles: readonly Role[]): boolean;
+    /**
+     * @param roles - rôles requis
+     * @returns `true` si TOUS les `roles` sont présents (AND ; `true` si liste vide)
+     */
+    hasAll(roles: readonly Role[]): boolean;
+    /** Copie triée des rôles (affichage / sérialisation déterministe). */
+    toArray(): Role[];
+}

package/dist/client/types/src/client/shim/cli-color.d.ts

@@ -0,0 +1,2 @@
+declare const proxy: any;
+export default proxy;

package/dist/client/types/src/client/shim/events.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shim browser de `node:events` — EventEmitter minimal mais complet pour
+ * Event.ts (on/once/off/emit/setMaxListeners + raw/prepend). Aucune dépendance npm.
+ *
+ * Couvre l'API EventEmitter réellement appelée par le core isomorphe (Service /
+ * Event / Syslog) : `rawListeners` (utilisé par `Event.emitAsync`/`emitAsyncGuarded`,
+ * le bus async `fireAsync`) et `prependListener`/`prependOnceListener` (Service.nc).
+ * Ce shim ne distingue PAS les wrappers `once` des listeners bruts (`rawListeners`
+ * ≡ `listeners`) — suffisant pour l'itération de `emitAsync`. Pas d'event `error`
+ * spécial ni `Symbol.for("nodejs.rejection")`.
+ */
+type Listener = (...args: any[]) => void;
+export declare class EventEmitter {
+    private _listeners;
+    private _maxListeners;
+    on(event: string | symbol, fn: Listener): this;
+    addListener(event: string | symbol, fn: Listener): this;
+    once(event: string | symbol, fn: Listener): this;
+    off(event: string | symbol, fn: Listener): this;
+    removeListener(event: string | symbol, fn: Listener): this;
+    removeAllListeners(event?: string | symbol): this;
+    emit(event: string | symbol, ...args: any[]): boolean;
+    listenerCount(event: string | symbol): number;
+    listeners(event: string | symbol): Listener[];
+    eventNames(): (string | symbol)[];
+    setMaxListeners(n: number): this;
+    getMaxListeners(): number;
+    /**
+     * Copie des listeners — ce shim ne wrappe pas distinctement les `once`, donc
+     * `rawListeners` ≡ {@link listeners}. Appelé par `Event.emitAsync` (hot path
+     * du bus async `fireAsync`) pour itérer les handlers sans muter la liste.
+     */
+    rawListeners(event: string | symbol): Listener[];
+    /** Comme {@link on} mais inséré en TÊTE de la liste des listeners. */
+    prependListener(event: string | symbol, fn: Listener): this;
+    /** Comme {@link once} mais inséré en TÊTE de la liste des listeners. */
+    prependOnceListener(event: string | symbol, fn: Listener): this;
+}
+export default EventEmitter;

package/dist/client/types/src/client/shim/util.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shim browser de `node:util` — fournit `inspect` via JSON.stringify.
+ * Suffisant pour la sortie Syslog côté browser (debug/log uniquement).
+ */
+export declare const inspect: (obj: any, _opts?: {
+    colors?: boolean;
+    depth?: number;
+}) => string;
+/**
+ * Shim browser de `util.styleText` — identité (le navigateur n'a pas de TTY
+ * ANSI). Consommé par la façade couleur `src/colors.ts` → jamais d'ANSI côté
+ * client (parité ancien shim `cli-color` identity Proxy).
+ */
+export declare const styleText: (_format: any, text: string | number, _opts?: any) => string;