nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/client/client/realtime/localEvents.js

@@ -0,0 +1,56 @@
+//#region src/client/realtime/localEvents.ts
+/**
+* localEvents — **noms des événements LOCAUX du client temps réel**.
+*
+* Ces six noms ne voyagent jamais sur le fil : ils ne servent qu'à propager, dans
+* la page, ce que le client vient d'apprendre (changement d'état de connexion,
+* identité résolue au welcome, échantillon de statistiques, notice normalisée,
+* refus de canal). Ils partagent la table de `on()`/`off()` avec les canaux
+* réseau ; le double soulignement est ce qui les en distingue.
+*
+* **La table est la source unique**, exactement pour la même raison que
+* {@link PLATFORM_CHANNELS} l'est pour les canaux réseau : une chaîne recopiée
+* dans un écran est une chaîne qui survivra au renommage suivant. Celle-ci avait
+* déjà divergé — `"__state__"` était écrit en clair dans les trois gabarits
+* d'application, dans la barre de debug et dans la console d'administration,
+* sans qu'aucune constante ne l'exporte.
+*
+* Un consommateur n'a d'ailleurs pas à les connaître : `onState`, `onIdentity`,
+* `onStats`, `onNotice`, `onDenied` et `onReconnect` sont les portes publiques. La table existe
+* pour les implémentations (le client lui-même, ses observateurs agnostiques) et
+* pour un test qui veut se brancher au plus bas niveau.
+*
+* Pur et isomorphe (aucun import, aucune allocation).
+*/
+/**
+* Événements locaux du {@link RealtimeClient} — jamais émis ni reçus par le réseau.
+*
+* @see {@link RealtimeClient.onState} · {@link RealtimeClient.onIdentity} ·
+*   {@link RealtimeClient.onStats} · {@link RealtimeClient.onNotice} ·
+*   {@link RealtimeClient.onDenied} — les portes publiques à préférer partout.
+*/
+const LOCAL_EVENTS = {
+	/** État de la connexion (`"connected" | "reconnecting" | …`), à chaque transition. */
+	state: "__state__",
+	/** Identité résolue par le serveur au welcome ; `null` après un `disconnect()`. */
+	identity: "__identity__",
+	/** Tick d'échantillonnage des statistiques par canal (1×/s), sans charge utile. */
+	stats: "__stats__",
+	/** Notice normalisée (criticité temps réel interprétée). */
+	notice: "__notice__",
+	/** Refus d'un canal poussé par le serveur (`realtime:denied`). */
+	denied: "__denied__",
+	/** Tentative de reconnexion programmée (numéro d'essai, délai, échéance). */
+	reconnect: "__reconnect__"
+};
+/**
+* Vrai si `event` est un événement local du client (jamais un canal réseau).
+*
+* Sert aux couches qui inspectent la table des abonnements — une barre de debug,
+* un inventaire de canaux — et qui doivent écarter ce qui n'est pas du trafic.
+*/
+function isLocalEvent(event) {
+	return event === LOCAL_EVENTS.state || event === LOCAL_EVENTS.identity || event === LOCAL_EVENTS.stats || event === LOCAL_EVENTS.notice || event === LOCAL_EVENTS.denied || event === LOCAL_EVENTS.reconnect;
+}
+//#endregion
+export { LOCAL_EVENTS, isLocalEvent };

package/dist/client/client/realtime/notice.js

@@ -0,0 +1,125 @@
+//#region src/client/realtime/notice.ts
+/**
+* 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).
+*/
+function deniedToNotice(denied) {
+	const message = denied.reason === "unknown" ? `Canal « ${denied.channel} » inconnu du serveur : personne ne le produit (nom exact ? module chargé ?)` : denied.reason === "limit" ? `Canal « ${denied.channel} » non ouvert : trop d'abonnements sur cette connexion` : `Accès au canal « ${denied.channel} » refusé`;
+	return {
+		level: denied.reason === "unknown" ? "warning" : "error",
+		title: "Temps réel",
+		message,
+		source: "realtime",
+		ts: Date.now()
+	};
+}
+/**
+* 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.
+*/
+function closeCodeToNotice(code, reason) {
+	if (code === 1e3 || code === 1001) return null;
+	let level = "warning";
+	let message;
+	switch (code) {
+		case 1002:
+			level = "error";
+			message = "Erreur de protocole temps réel";
+			break;
+		case 1003:
+			level = "error";
+			message = "Données temps réel non supportées";
+			break;
+		case 1006:
+			message = "Connexion temps réel perdue";
+			break;
+		case 1007:
+			level = "error";
+			message = "Trame temps réel invalide";
+			break;
+		case 1008:
+			level = "error";
+			message = "Accès temps réel refusé";
+			break;
+		case 1009:
+			message = "Message temps réel trop volumineux";
+			break;
+		case 1010:
+			level = "error";
+			message = "Extension temps réel requise manquante";
+			break;
+		case 1011:
+			level = "error";
+			message = "Erreur serveur temps réel";
+			break;
+		case 4004:
+			level = "error";
+			message = "Ressource temps réel introuvable";
+			break;
+		default: message = typeof code === "number" ? `Connexion temps réel fermée (code ${code})` : "Connexion temps réel fermée";
+	}
+	const trimmed = reason?.trim();
+	return {
+		level,
+		title: "Temps réel",
+		message: trimmed ? `${message} : ${trimmed}` : message,
+		source: "realtime",
+		code,
+		ts: Date.now()
+	};
+}
+/**
+* Close codes (RFC 6455 §7.4 + privés Nodefony 4xxx) après lesquels une
+* reconnexion automatique est INUTILE ou NUISIBLE — la cause ne disparaît pas en
+* réessayant : fin propre (1000), erreurs de protocole/négociation
+* (1002/1003/1007/1010), violation de politique = 401/403 mappés (1008), et
+* ressource introuvable (4004, privé Nodefony). Une boucle de reco sur ces codes
+* martèle le serveur pour rien (vécu : un anonyme sur un endpoint protégé).
+*/
+const FATAL_CLOSE_CODES = /* @__PURE__ */ new Set([
+	1e3,
+	1002,
+	1003,
+	1007,
+	1008,
+	1010,
+	4004
+]);
+/**
+* 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.
+*/
+function isReconnectableCloseCode(code) {
+	if (code === void 0) return true;
+	return !FATAL_CLOSE_CODES.has(code);
+}
+//#endregion
+export { closeCodeToNotice, deniedToNotice, isReconnectableCloseCode };

package/dist/client/client/realtime/observe.js

@@ -0,0 +1,280 @@
+import { PLATFORM_CHANNELS } from "../../realtime/platformChannels.js";
+import { RealtimeClient } from "./RealtimeClient.js";
+//#region src/client/realtime/observe.ts
+/**
+* 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
+*/
+/**
+* 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.
+*/
+function connectShared(opts) {
+	const provided = opts.client;
+	const socket = provided ?? RealtimeClient.shared({ url: opts.url });
+	const owned = !provided;
+	return {
+		socket,
+		owned,
+		start() {
+			if (!owned) return;
+			socket.connect().catch(() => {});
+		}
+	};
+}
+/**
+* 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.
+*/
+function observeState(client, emit) {
+	emit(client.state);
+	return client.onState(emit);
+}
+/**
+* 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`.
+*/
+function observeIdentity(client, emit) {
+	emit(client.identity);
+	return client.onIdentity(emit);
+}
+/**
+* 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é.
+*/
+function observeReconnect(client, emit) {
+	return client.onReconnect(emit);
+}
+/**
+* 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.
+*/
+function observeChannel(client, channel, emit) {
+	const handle = client.channel(channel);
+	handle.on((payload) => emit(payload));
+	handle.open();
+	return () => handle.close();
+}
+/**
+* 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.
+*/
+function observeChannelData(client, channel, emit, initial = null) {
+	emit(initial);
+	return observeChannel(client, channel, (payload) => emit(payload));
+}
+/**
+* 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.
+*/
+function observeChannelStats(client, channel, emit) {
+	const read = () => client.getChannelStats(channel) ?? null;
+	emit(read());
+	return client.onStats(() => emit(read()));
+}
+/**
+* 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**.
+*/
+function adaptiveRebindKey(base, desiredMs, enabled = true) {
+	return `${base}|${desiredMs}|${enabled ? 1 : 0}`;
+}
+/**
+* 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`).
+*/
+function observeAdaptiveChannel(client, base, emit, desiredMs, options = {}) {
+	return client.adaptiveChannel(base, (...args) => emit(args[0]), {
+		...options,
+		intervalMs: desiredMs
+	});
+}
+/**
+* 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.
+*/
+function socketSnapshot(client) {
+	return {
+		url: client.url,
+		state: client.state,
+		channels: client.subscribedChannels,
+		frames: client.framesReceived,
+		unsent: client.framesUnsent,
+		lastFrame: {
+			method: client.lastFrameMethod,
+			at: client.lastFrameAt
+		},
+		reconnectAttempts: client.reconnectAttempts,
+		nextRetryAt: client.nextRetryAt,
+		identity: client.identity
+	};
+}
+/**
+* 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.
+*/
+function observeSnapshot(client, emit) {
+	const pousser = () => emit(socketSnapshot(client));
+	pousser();
+	const offStats = client.onStats(pousser);
+	const offState = client.onState(pousser);
+	return () => {
+		offStats();
+		offState();
+	};
+}
+/** Taille par défaut de l'anneau du journal. */
+const SYSLOG_RING_DEFAULT = 500;
+/** Taille par défaut de l'anneau des notices. */
+const NOTICE_RING_DEFAULT = 50;
+/**
+* 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.
+*/
+function observeSyslog(client, emit, opts = {}) {
+	const { max = SYSLOG_RING_DEFAULT, severities, channel = PLATFORM_CHANNELS.syslog } = opts;
+	let entries = [];
+	emit(entries);
+	return observeChannel(client, channel, (payload) => {
+		const record = payload;
+		const incoming = record && Array.isArray(record.logs) ? record.logs : [payload];
+		const kept = severities ? incoming.filter((entry) => severities.includes(entry.severity ?? "")) : incoming;
+		if (kept.length === 0) return;
+		const next = entries.concat(kept);
+		entries = next.length > max ? next.slice(-max) : next;
+		emit(entries);
+	});
+}
+/**
+* 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.
+*/
+function observeNotices(client, emit) {
+	return client.onNotice(emit);
+}
+/**
+* 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.
+*/
+function observeNoticeLog(client, emit, opts = {}) {
+	const { max = NOTICE_RING_DEFAULT, sources } = opts;
+	let notices = [];
+	emit(notices);
+	return observeNotices(client, (notice) => {
+		if (sources && !sources.includes(notice.source)) return;
+		const next = notices.concat(notice);
+		notices = next.length > max ? next.slice(-max) : next;
+		emit(notices);
+	});
+}
+//#endregion
+export { adaptiveRebindKey, connectShared, observeAdaptiveChannel, observeChannel, observeChannelData, observeChannelStats, observeIdentity, observeNoticeLog, observeNotices, observeReconnect, observeSnapshot, observeState, observeSyslog, socketSnapshot };

package/dist/client/client/roles/index.js

@@ -0,0 +1,3 @@
+import { RoleSet, hasAllRoles, hasAnyRole, hasRole } from "./roles.js";
+import { ROLE_MASK_CAPACITY, RoleRegistry } from "./registry.js";
+export { ROLE_MASK_CAPACITY, RoleRegistry, RoleSet, hasAllRoles, hasAnyRole, hasRole };

package/dist/client/client/roles/registry.js

@@ -0,0 +1,97 @@
+//#region src/client/roles/registry.ts
+/**
+* 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`.
+*/
+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
+*/
+var RoleRegistry = class {
+	#bits = /* @__PURE__ */ new Map();
+	#next = 0;
+	/**
+	* 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) {
+		for (const role of roles) {
+			if (this.#bits.has(role)) continue;
+			if (this.#next >= 31) throw new RangeError(`RoleRegistry: capacité dépassée (31 rôles max en masque 32 bits)`);
+			this.#bits.set(role, 1 << this.#next);
+			this.#next += 1;
+		}
+		return this;
+	}
+	/**
+	* @param role - rôle recherché
+	* @returns le bit du rôle (puissance de 2), ou `0` si inconnu
+	*/
+	bit(role) {
+		return this.#bits.get(role) ?? 0;
+	}
+	/**
+	* 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) {
+		let m = 0;
+		for (const r of roles) m |= this.#bits.get(r) ?? 0;
+		return m;
+	}
+	/**
+	* 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) {
+		const out = [];
+		for (const [role, bit] of this.#bits) if ((mask & bit) !== 0) out.push(role);
+		return out;
+	}
+	/**
+	* 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, requiredMask) {
+		return (userMask & requiredMask) !== 0;
+	}
+	/**
+	* 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, requiredMask) {
+		return (userMask & requiredMask) === requiredMask;
+	}
+};
+//#endregion
+export { ROLE_MASK_CAPACITY, RoleRegistry };

package/dist/client/client/roles/roles.js

@@ -0,0 +1,91 @@
+//#region src/client/roles/roles.ts
+/**
+* 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`
+*/
+function hasRole(userRoles, role) {
+	return userRoles != null && userRoles.includes(role);
+}
+/**
+* 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)
+*/
+function hasAnyRole(userRoles, roles) {
+	if (userRoles == null || roles.length === 0) return false;
+	for (const r of roles) if (userRoles.includes(r)) return true;
+	return false;
+}
+/**
+* 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`)
+*/
+function hasAllRoles(userRoles, roles) {
+	if (roles.length === 0) return true;
+	if (userRoles == null) return false;
+	for (const r of roles) if (!userRoles.includes(r)) return false;
+	return true;
+}
+/**
+* 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).
+*/
+var RoleSet = class {
+	#roles;
+	/** @param roles - rôles de l'utilisateur (dédoublonnés à la construction) */
+	constructor(roles) {
+		this.#roles = new Set(roles ?? void 0);
+	}
+	/** Nombre de rôles distincts. */
+	get size() {
+		return this.#roles.size;
+	}
+	/**
+	* @param role - rôle recherché
+	* @returns `true` si le rôle est présent (O(1))
+	*/
+	has(role) {
+		return this.#roles.has(role);
+	}
+	/**
+	* @param roles - rôles acceptés
+	* @returns `true` si AU MOINS UN des `roles` est présent (OR)
+	*/
+	hasAny(roles) {
+		for (const r of roles) if (this.#roles.has(r)) return true;
+		return false;
+	}
+	/**
+	* @param roles - rôles requis
+	* @returns `true` si TOUS les `roles` sont présents (AND ; `true` si liste vide)
+	*/
+	hasAll(roles) {
+		for (const r of roles) if (!this.#roles.has(r)) return false;
+		return true;
+	}
+	/** Copie triée des rôles (affichage / sérialisation déterministe). */
+	toArray() {
+		return [...this.#roles].sort();
+	}
+};
+//#endregion
+export { RoleSet, hasAllRoles, hasAnyRole, hasRole };