nodefony 7.0.2 → 10.0.0-alpha.2

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

@@ -0,0 +1,184 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import fs from "node:fs";
+interface FileClassInterface {
+    path: fs.PathOrFileDescriptor;
+    name: string;
+    ext: string;
+    shortName: string;
+    type: string | undefined;
+    stats: fs.Stats;
+    dirName: string;
+    parse: path.ParsedPath;
+    encoding?: string;
+    mimeType?: string | false;
+    extention?: string | false;
+}
+/**
+ * Wrapper fs Node.js avec métadonnées pré-parsées (path, name, ext, mime, stats).
+ *
+ * Utilisé par le Kernel/Module pour résoudre des chemins, par le `Finder` pour représenter
+ * un résultat de recherche, et par les Controllers HTTP pour servir des fichiers statiques.
+ *
+ * @example
+ * ```ts
+ * import { FileClass } from "nodefony";
+ * const file = new FileClass("/path/to/file.txt");
+ * file.isFile();       // true
+ * file.mimeType;       // "text/plain"
+ * const content = file.read();
+ * ```
+ *
+ * @remarks Le constructeur `new FileClass(path)` fait un `fs.lstatSync()` **synchrone**
+ *   (bloque l'event-loop) — réservé au boot/CLI. Dans **tout hot path** (requête HTTP,
+ *   Finder, upload), utiliser `await FileClass.from(path)` qui résout les stats en async
+ *   (`fsp.lstat`/`fsp.realpath`) sans bloquer la loop. Idem `moveAsync()` vs `move()`.
+ */
+declare class FileClass {
+    stats: fs.Stats;
+    type: string | undefined;
+    path: fs.PathOrFileDescriptor;
+    parse: path.ParsedPath;
+    name: string;
+    shortName: string;
+    ext: string;
+    mimeType: string | false;
+    encoding: string;
+    extention: string | false;
+    dirName: string;
+    match: RegExpExecArray | null;
+    /**
+     * Construit un FileClass à partir d'un chemin (absolu OR relatif à `process.cwd()`).
+     *
+     * Par défaut : résout `lstatSync` (suit pas les symlinks) + `realpathSync.native`, parse
+     * le path, devine le MIME type — **synchrone, bloque l'event-loop** (boot/CLI uniquement).
+     * Passer `{ defer: true }` n'effectue AUCUNE I/O (utilisé par `FileClass.from()` async).
+     *
+     * @param Path - chemin absolu OR relatif vers le fichier/dossier.
+     * @param options - `defer: true` → pas de stat au constructeur (hydrater via `stat()`).
+     * @throws Si `Path` est falsy OR si `lstatSync` échoue (fichier inexistant, hors defer).
+     */
+    constructor(Path: string | fs.PathOrFileDescriptor, options?: {
+        defer?: boolean;
+    });
+    /**
+     * Construit un FileClass SANS I/O synchrone — `fsp.lstat`/`fsp.realpath` async.
+     *
+     * À utiliser dans tout hot path (Finder, upload, render controller) pour ne PAS
+     * bloquer l'event-loop. Équivalent async de `new FileClass(path)`.
+     *
+     * @param Path - chemin absolu ou relatif à `process.cwd()`.
+     * @returns une instance hydratée (stats résolus).
+     * @throws Si `Path` est falsy ou si `lstat` échoue (inexistant).
+     */
+    static from(Path: string | fs.PathOrFileDescriptor): Promise<FileClass>;
+    /**
+     * Résout les stats en async (`fsp.lstat` + `fsp.realpath`) puis hydrate l'instance.
+     * Aucune I/O synchrone. Appelé par `FileClass.from()` ; rappelable pour rafraîchir.
+     *
+     * @returns `this` (chaînable, type polymorphe pour les sous-classes type `File`).
+     */
+    stat(): Promise<this>;
+    /**
+     * Renseigne stats/type/path/parse/name/mime à partir de stats déjà résolus.
+     * Partagé par le constructeur sync et `stat()` async — **aucune I/O ici** (pur).
+     *
+     * @param stats - résultat d'un `lstat` (sync ou async).
+     * @param resolvedPath - path réel (realpath) ou path original si symlink.
+     */
+    private hydrate;
+    /**
+     * @returns le path absolu (utile pour les concat string).
+     */
+    toString(): string;
+    /**
+     * Sérialise les métadonnées du fichier en objet plain (compatible JSON.stringify).
+     *
+     * @returns objet contenant path, name, ext, stats, mime, etc.
+     */
+    toJson(): FileClassInterface;
+    /**
+     * Détermine le type — `"File"`, `"Directory"`, `"SymbolicLink"`, etc.
+     *
+     * @returns nom du type ou `undefined` si stats indéterminé.
+     */
+    checkType(): string | undefined;
+    /**
+     * Calcule le hash du contenu du fichier (synchronous).
+     *
+     * @param type - algorithme (`"md5"` défaut, `"sha1"`, `"sha256"`, etc.).
+     * @param hasOption - options crypto.HashOptions.
+     * @returns hash hexadécimal.
+     */
+    checkSum(type?: string, hasOption?: crypto.HashOptions): string;
+    getMimeType(name?: string): string | false;
+    getExtension(mimeType: string | false): string | false;
+    /**
+     * Canonicalise un chemin par la voie SYSTÈME (`uv_fs_realpath`), la même que
+     * `fsp.realpath` employé par la voie async.
+     *
+     * @remarks `fs.realpathSync` (sans `.native`) est une implémentation JavaScript qui
+     *   se contente de dérouler les liens : sous Windows elle **conserve les noms courts
+     *   8.3** (`C:\Users\RUNNER~1\…`) là où la voie système rend la forme longue
+     *   (`C:\Users\runneradmin\…`). Deux canonicalisations pour un même fichier, donc
+     *   deux `path` différents selon qu'on est passé par le constructeur ou par
+     *   `FileClass.from()` — et toute comparaison de chemins (dédup, cache, garde
+     *   « la cible reste-t-elle sous le dossier autorisé ? ») devient fausse sans un mot.
+     *   Sous POSIX les deux voies sont identiques : l'alignement ne change rien.
+     *
+     * @param Path - chemin à canonicaliser.
+     * @param options - encodage (cf `fs.EncodingOption`).
+     * @returns le chemin réel, forme canonique du système de fichiers.
+     */
+    getRealpath(Path: string, options?: fs.EncodingOption): string;
+    matchName(ele: RegExp | string): boolean | RegExpExecArray | null;
+    matchType(type: string): boolean;
+    /** @returns `true` si le path pointe vers un fichier régulier. */
+    isFile(): boolean;
+    /** @returns `true` si le path pointe vers un dossier. */
+    isDirectory(): boolean;
+    /** @returns `true` si le path est un lien symbolique. */
+    isSymbolicLink(): boolean;
+    dirname(): string;
+    /** @returns `true` si le nom commence par `.` (fichier caché Unix). */
+    isHidden(): boolean;
+    content(encoding?: string): string | Buffer;
+    /**
+     * Lit le contenu du fichier (synchronous).
+     *
+     * @param encoding - encoding (défaut `"utf8"`). Si non fourni → retourne Buffer.
+     * @returns contenu sous forme de string OR Buffer.
+     */
+    read(encoding?: string): string | Buffer;
+    readAsync(encoding?: string): Promise<string | Buffer>;
+    readByLine(callback: (line: string, n: number) => void, encoding?: string): string | Buffer<ArrayBufferLike>;
+    /**
+     * Écrit du contenu dans le fichier (synchronous).
+     *
+     * @param data - contenu à écrire (string OR Buffer).
+     * @param options - options fs.write (encoding, flags).
+     * @returns this (chaînable).
+     */
+    write(data: string | NodeJS.ArrayBufferView, options: fs.WriteFileOptions): void;
+    /**
+     * Déplace/renomme le fichier (synchronous).
+     *
+     * @param target - chemin de destination.
+     * @returns nouvelle instance FileClass pointant vers `target`.
+     */
+    move(target: fs.PathLike): FileClass;
+    /**
+     * Déplace/renomme le fichier en **async** (`fsp.rename`) — variante non bloquante
+     * de `move()`. À préférer dans le pipeline (upload, controller).
+     *
+     * @param target - chemin de destination.
+     * @returns nouvelle instance FileClass (hydratée async) sur `target`.
+     */
+    moveAsync(target: fs.PathLike): Promise<FileClass>;
+    /** Supprime le fichier du filesystem (synchronous, irréversible). */
+    unlink(): void;
+    /** Supprime le fichier du filesystem en **async** (`fsp.unlink`). */
+    unlinkAsync(): Promise<void>;
+}
+export default FileClass;
+export { FileClassInterface };

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

@@ -0,0 +1,165 @@
+import { DebugType, EnvironmentType } from "./types/globals.js";
+import type { IService, DefaultOptionsService, EventListener } from "./types/IService.js";
+import type { IKernel } from "./types/IKernel.js";
+import Container, { DynamicParam } from "./Container.js";
+import Event, { EventDefaultInterface } from "./Event.js";
+import type { IGuardedEmitOptions, IGuardedEmitResult } from "./Event.js";
+import Pdu, { Severity, Msgid, Message, Pci } from "./syslog/Pdu.js";
+import Syslog, { conditionsInterface } from "./syslog/Syslog.js";
+/**
+ * Brique de base de tout composant Nodefony — câble un nom, un {@link Container} DI,
+ * un {@link Syslog} et un bus d'événements {@link Event} (notificationsCenter).
+ *
+ * Tous les services, modules, kernels et controllers héritent de cette classe.
+ * Délègue son API EventEmitter à `notificationsCenter` et son API DI au `container`.
+ *
+ * Cycle de vie attendu :
+ * - `new Service(name, container?, nc?, options?)` — initialise les dépendances
+ * - `initSyslog(env, debug, options?)` — démarre la sortie console (optionnel)
+ * - `clean()` — retire les listeners trackés et libère les références
+ *
+ * @remarks Si `notificationsCenter === false`, le service est créé sans bus
+ *   d'événements — utile pour des services purement utilitaires.
+ */
+declare class Service implements IService {
+    #private;
+    name: string;
+    options: DefaultOptionsService;
+    container: Container | null;
+    kernel: IKernel | null;
+    syslog: Syslog | null;
+    get notificationsCenter(): Event | undefined;
+    private get nc();
+    /**
+     * Initialise le service — réutilise les ressources du conteneur si possible,
+     * sinon les crée à la volée.
+     *
+     * @param name - identifiant logique du service (apparaît dans les logs comme `msgid`).
+     * @param container - {@link Container} DI partagé ; sinon un nouveau est instancié.
+     * @param notificationsCenter - {@link Event} bus existant à partager, ou `false`
+     *   pour désactiver les events, ou `null`/`undefined` pour créer un bus dédié.
+     * @param options - surcharge des défauts (`events.nbListeners`, `syslog.moduleName`…).
+     */
+    constructor(name: string, container?: Container, notificationsCenter?: Event | false | null, options?: DefaultOptionsService);
+    /**
+     * Convention `onXxx` → enregistre les listeners déclarés en config (clé
+     * matchant `/^on(.+)$/`) via {@link Service.on} pour que {@link clean}
+     * puisse les retirer du bus partagé. Variante trackée de
+     * {@link Event.settingsToListen}.
+     */
+    private attachConfiguredListeners;
+    /**
+     * Démarre la sortie console du Syslog avec l'environnement et la verbosité voulus.
+     *
+     * @param environment - `"production"` (défaut) ou `"development"`.
+     * @param debug - flag de verbosité (true ou {@link DebugType}).
+     * @param options - {@link conditionsInterface} pour filtrer les Pdu (severity, msgid…).
+     * @returns le résultat de {@link Syslog.init} ou `null` si pas de Syslog.
+     */
+    initSyslog(environment?: EnvironmentType, debug?: DebugType, options?: conditionsInterface): ReturnType<Syslog["init"]> | null;
+    /** Renvoie le nom logique du service (utilisé comme `msgid` syslog par défaut). */
+    getName(): string;
+    /**
+     * Libère les ressources — retire les listeners trackés du bus partagé pour
+     * éviter les fuites mémoire, puis détache container/kernel/syslog/nc.
+     *
+     * @param syslog - si `true`, appelle aussi {@link Syslog.reset} (transports fermés).
+     * @remarks Après `clean()`, toute API héritée (log, event, container) lèvera une erreur.
+     */
+    clean(syslog?: boolean): void;
+    /**
+     * Émet une entrée de log structurée — point d'entrée central pour TOUT log Nodefony.
+     *
+     * @param pci - charge utile (string, objet, Error…). Stockée dans {@link Pdu.payload}.
+     * @param severity - niveau syslog (`INFO`, `WARNING`, `ERROR`, `CRITIC`, `DEBUG`…).
+     * @param msgid - identifiant logique ; défaut = `this.name`.
+     * @param msg - message libre additionnel.
+     * @returns le {@link Pdu} émis (utile pour chaîner des transports).
+     * @remarks Si syslog est down, fabrique un Pdu directement et catch toute exception.
+     */
+    log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu;
+    /** Raccourci debug — log severity `DEBUG` + `console.debug` formaté. */
+    logger(pci: Pci, ...args: unknown[]): void;
+    /** Comme {@link logger} mais `console.trace` (avec stack trace). */
+    trace(pci: Pci, ...args: unknown[]): void;
+    private trackListener;
+    private untrackListener;
+    /** Liste les noms d'événements ayant au moins un listener. */
+    eventNames(): (string | symbol)[];
+    /** Alias `emit` — émet l'événement de manière synchrone. */
+    fire(eventName: string | symbol, ...args: unknown[]): boolean;
+    /** Émet l'événement et attend que tous les listeners async résolvent. */
+    fireAsync(eventName: string | symbol, ...args: unknown[]): Promise<unknown>;
+    /** Émet l'événement (API EventEmitter standard). */
+    emit(eventName: string | symbol, ...args: unknown[]): boolean;
+    /** Émet et attend les listeners async — équivalent de {@link fireAsync}. */
+    emitAsync(eventName: string | symbol, ...args: unknown[]): Promise<unknown>;
+    /**
+     * Variante **gardée** de {@link emitAsync} (cf `Event.emitAsyncGuarded`) : isole
+     * chaque listener par try/catch + timeout et collecte les échecs. Réservé au
+     * **boot / lifecycle / jobs** (cf `Kernel.fireLifecycle`) — JAMAIS le hot path.
+     */
+    emitAsyncGuarded(eventName: string | symbol, options?: IGuardedEmitOptions, ...args: unknown[]): Promise<IGuardedEmitResult>;
+    /** Enregistre un listener (tracké pour cleanup). Voir aussi {@link on}. */
+    addListener(eventName: string | symbol, listener: EventListener): this;
+    /**
+     * Bind le listener sur `this` puis l'enregistre — utile quand le listener
+     * référence `this.foo` et ne peut pas être tracké à l'identique.
+     *
+     * @returns le listener wrappé (ne PAS passer le listener original à `off()`).
+     */
+    listen(eventName: string | symbol, listener: EventListener): (...args: unknown[]) => boolean;
+    /** Enregistre un listener (tracké pour cleanup). Alias EventEmitter de {@link addListener}. */
+    on(eventName: string | symbol, listener: EventListener): this;
+    /** Enregistre un listener one-shot — auto-retiré après le premier `emit`. */
+    once(eventName: string | symbol, listener: EventListener): this;
+    /** Retire un listener (alias EventEmitter de {@link removeListener}). */
+    off(eventName: string | symbol, listener: EventListener): this;
+    /**
+     * Enregistre les événements déclarés dans `localSettings.events.listeners`
+     * — utilisé en config pour mapper des hooks sans code impératif.
+     */
+    settingsToListen(localSettings: EventDefaultInterface, context: object): void;
+    /** Augmente la limite Node.js (défaut 10) pour éviter le warning MaxListeners. */
+    setMaxListeners(n: number): this;
+    /** Retire un listener spécifique et nettoie le tracking interne. */
+    removeListener(eventName: string | symbol, listener: EventListener): this;
+    /** Retire tous les listeners (ou ceux d'un événement précis si fourni). */
+    removeAllListeners(eventName?: string | symbol): this;
+    /** Comme {@link once} mais inséré en tête de la liste des listeners. */
+    prependOnceListener(eventName: string | symbol, listener: EventListener): this;
+    /** Comme {@link on} mais inséré en tête de la liste des listeners. */
+    prependListener(eventName: string | symbol, listener: EventListener): this;
+    /** Limite courante de listeners avant warning Node.js. */
+    getMaxListeners(): number;
+    /** Nombre de listeners attachés à un événement (filtré sur `listener` si fourni). */
+    listenerCount(eventName: string | symbol, listener?: EventListener): number;
+    /** Copie de la liste des listeners (résolus, sans le wrapper `once`). */
+    listeners(eventName: string | symbol): EventListener[];
+    /** Comme {@link listeners} mais retourne les wrappers Node.js bruts (avec once). */
+    rawListeners(eventName: string | symbol): EventListener[];
+    /** Récupère un service du DI container par nom. Retourne `null` si absent ou clean(). */
+    get<T>(name: string): T | null;
+    /**
+     * Enregistre un objet dans le DI container.
+     * @throws Error si `clean()` a déjà détaché le container.
+     */
+    set<T>(name: string, obj: T): void;
+    /**
+     * Retire un service du container — si c'est un `Service`, appelle d'abord
+     * son `clean()` pour libérer ses listeners.
+     * @returns `true` si retiré, `false` si introuvable ou container détaché.
+     */
+    remove(name: string): boolean;
+    /** Récupère un paramètre dynamique (config résolue) — `null` si absent. */
+    getParameters(name: string): DynamicParam | null;
+    /**
+     * Définit un paramètre dynamique dans le container.
+     * @throws Error si `clean()` a déjà détaché le container.
+     */
+    setParameters<T>(name: string, ele: T): DynamicParam | null;
+    /** Vérifie l'existence d'un service ou paramètre dans le container. */
+    has(name: string): boolean;
+}
+export default Service;
+export type { IService, IKernel, DefaultOptionsService, EventListener };

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

@@ -0,0 +1,116 @@
+import Container from "./Container.js";
+/** Alias direct de `Array.isArray` — exporté pour usage cohérent dans les modules. */
+declare const isArray: (arg: any) => arg is any[];
+/**
+ * Type guard — `true` si `value` est une fonction (incluant arrow et classes).
+ *
+ * @param value - valeur inconnue à tester.
+ */
+declare const isFunction: (value: unknown) => value is (...args: unknown[]) => unknown;
+/**
+ * Type guard — `true` si `value` est une instance `RegExp`.
+ *
+ * @param value - valeur inconnue à tester.
+ */
+declare const isRegExp: (value: unknown) => value is RegExp;
+/**
+ * Vérifie qu'un objet est un "plain object" — `{}` ou `Object.create(null)`.
+ *
+ * Rejette les instances de classes, les `Array`, `Date`, `RegExp`, etc.
+ * Implémentation alignée sur jQuery.isPlainObject (compatible cross-realm).
+ *
+ * @param obj - valeur à tester.
+ * @returns `true` si l'objet vient directement de `Object` ou n'a pas de prototype.
+ */
+declare const isPlainObject: (obj: unknown) => boolean;
+/**
+ * Type guard — `true` si `value === undefined` (strict, jamais `null`).
+ *
+ * @param value - valeur à tester.
+ */
+declare const isUndefined: (value: unknown) => value is undefined;
+/**
+ * Vérifie qu'un objet existe et ne contient aucune clé propre énumérable.
+ *
+ * @param obj - objet à inspecter (peut être `null`/`undefined`).
+ * @returns `true` si `obj` est défini ET `Object.keys(obj).length === 0`.
+ */
+declare const isEmptyObject: (obj: object | null | undefined) => boolean;
+/**
+ * Fusionne plusieurs objets dans une cible — API compatible `jQuery.extend`.
+ *
+ * Mode `shallow` (défaut) : copie les clés du dernier au premier source.
+ * Mode `deep` (1er arg `true`) : récurse dans les plain objects et arrays.
+ * Sécurité : ignore `__proto__`, `constructor`, `prototype` (anti prototype pollution).
+ *
+ * @param args - `[target, ...sources]` ou `[true, target, ...sources]` pour deep.
+ * @returns la cible mutée (ou objet vide si appel à un seul argument).
+ *
+ * @example
+ * ```ts
+ * extend({ a: 1 }, { b: 2 });               // { a: 1, b: 2 }
+ * extend(true, { a: { x: 1 } }, { a: { y: 2 } }); // { a: { x: 1, y: 2 } }
+ * ```
+ */
+declare const extend: (...args: any[]) => any;
+declare const typeOf: (value: any) => string | null;
+/**
+ * Type guard — `true` si la valeur est une instance de `Container` (DI).
+ *
+ * @param container - valeur à tester.
+ */
+declare const isContainer: (container: unknown) => container is Container;
+/**
+ * Vérifie qu'une valeur est une `Promise` ou un thenable (duck-typing `.then`).
+ *
+ * Accepte les promesses natives ET les bibliothèques tierces (Bluebird, etc.)
+ * qui implémentent le protocole Promises/A+.
+ *
+ * @param obj - valeur à tester.
+ * @returns `true` si `obj instanceof Promise` ou `typeof obj.then === "function"`.
+ */
+declare const isPromise: (obj: any) => boolean;
+/**
+ * Vérifie qu'une classe hérite (directement ou non) d'une autre.
+ *
+ * @param subclass - classe enfant supposée.
+ * @param superclass - classe parent attendue.
+ * @returns `true` si `subclass.prototype instanceof superclass`.
+ */
+declare const isSubclassOf: (subclass: any, superclass: any) => boolean;
+/**
+ * Retire les barres obliques finales d'une chaîne, sans expression régulière.
+ *
+ * **Pourquoi pas `value.replace(/\/+$/, "")`** — la forme évidente, et celle qui
+ * était recopiée à cinq endroits. Elle est QUADRATIQUE quand la reconnaissance
+ * ÉCHOUE : le moteur reprend l'essai à chaque position, consomme la suite des
+ * barres, puis bute sur l'ancre de fin. Mesuré sur des barres suivies d'un
+ * caractère quelconque — 1 000 → 1,4 ms, 4 000 → 21 ms, 16 000 → **309 ms** ;
+ * la même entrée passe ici en 0 ms. Le cas qui RÉUSSIT, lui, coûte 0,03 ms :
+ * c'est l'échec qui est cher, et c'est le cas qu'une entrée hostile provoque.
+ *
+ * Deux propriétés utiles en chemin chaud : la lecture est en O(n) sans retour
+ * arrière, et **rien n'est alloué** quand il n'y a rien à couper — la chaîne
+ * d'origine est rendue telle quelle, là où `replace` alloue à chaque appel.
+ *
+ * @param value - la chaîne à normaliser (typiquement un chemin ou une URL).
+ * @returns la chaîne sans ses barres obliques finales ; la chaîne elle-même si elle n'en avait pas.
+ */
+declare const stripTrailingSlashes: (value: string) => string;
+/**
+ * Neutralise les métacaractères d'une chaîne destinée à être insérée dans une
+ * expression régulière, pour qu'elle n'y vaille que pour elle-même.
+ *
+ * **Pourquoi c'est ici** — le même motif était recopié à sept endroits, dans
+ * cinq paquets. Une liste de caractères recopiée est une liste qui diverge : il
+ * suffit qu'une copie oublie `|` pour qu'un littéral cesse d'être un littéral.
+ * `|` est d'ailleurs le plus coûteux à omettre, parce qu'il ne fait pas
+ * qu'élargir la reconnaissance : il DÉSANCRE. `new RegExp("^/a|b$")` ne
+ * reconnaît pas « /a ou /b » — il reconnaît « commence par /a » **ou** « finit
+ * par b », donc `/n/importe/quoi/b`.
+ *
+ * @param value - la chaîne à traiter comme un littéral.
+ * @returns la même chaîne, chaque métacaractère précédé d'une barre inverse.
+ */
+declare const escapeRegExp: (value: string) => string;
+export { extend, isEmptyObject, isPlainObject, isUndefined, isRegExp, isContainer, typeOf, isFunction, isArray, isPromise, isSubclassOf, stripTrailingSlashes, escapeRegExp, };

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

@@ -0,0 +1,90 @@
+import type Syslog from "../syslog/Syslog.js";
+import type { ClientIdentity, ClientKernelEvent, ClientKernelOptions, ClientKernelState, IClientKernel, NodefonyClientServices } from "./IClientKernel.js";
+/**
+ * Kernel client — obtenu par {@link createClientKernel}, jamais construit en
+ * singleton de module (testabilité, HMR-safe : un module réévalué par Vite
+ * dédoublerait un singleton, gotcha vécu sur le contexte React de Studio).
+ */
+export declare class ClientKernel implements IClientKernel {
+    #private;
+    /** Journal client de série — `Pdu` isomorphes, corrélables au back. */
+    readonly syslog: Syslog;
+    constructor(options?: ClientKernelOptions);
+    /**
+     * Récupère un service composé, typé par le registre.
+     *
+     * Rend `undefined` pour un service absent — le registre est décrit par des
+     * propriétés optionnelles, si bien que `kernel.get("realtime")` est de type
+     * `RealtimeClient | undefined` et nourrit `<NodefonyProvider client={…}>` sans
+     * la moindre conversion de type forcée.
+     */
+    get<K extends keyof NodefonyClientServices>(name: K): NodefonyClientServices[K];
+    /** Enregistre un service sous son nom contractuel. */
+    set<K extends keyof NodefonyClientServices>(name: K, svc: NodefonyClientServices[K]): void;
+    /** Teste la présence d'un service — nom libre, y compris hors contrat. */
+    has(name: string): boolean;
+    /** État courant — jamais régressif. */
+    get state(): ClientKernelState;
+    /**
+     * Compose et connecte les services. **Idempotent** : rappelé pendant ou après
+     * un premier boot, il ne recompose rien et ne réémet aucun événement. Depuis
+     * l'état `terminated`, il ne fait rien — l'état ne régresse jamais.
+     */
+    boot(): Promise<void>;
+    /**
+     * Flush l'observabilité et déconnecte. Idempotent, et **best-effort** : appelé
+     * sur `pagehide`, il n'a aucune garantie d'aller au bout — d'où l'ordre choisi,
+     * l'événement d'abord, le débranchement ensuite.
+     */
+    terminate(): Promise<void>;
+    /** Nom du kernel — celui donné à la fabrique, `CLIENT KERNEL` par défaut. */
+    get name(): string;
+    /** Identité runtime courante, telle que l'application l'a déclarée. */
+    get identity(): ClientIdentity | null;
+    /**
+     * Déclare l'identité runtime — et applique la règle de sécurité D9, née d'une
+     * fuite vécue en production.
+     *
+     * Deux gardes, chacune payée par une régression réelle :
+     *
+     * 1. **`disconnect()` uniquement sur un VRAI changement de compte** (une clé
+     *    connue remplacée par une autre). La socket grave l'identité au handshake ;
+     *    le pont « API souveraine » rejouerait sinon des requêtes avec le jeton du
+     *    compte précédent. Couper impose un nouveau handshake, donc la relecture du
+     *    cookie courant.
+     * 2. **`connect()` HORS de cette garde.** Au tout premier chargement, la clé
+     *    passe de `null` à une valeur : couper là romprait les requêtes EN VOL qui
+     *    passent par le pont, et l'écran resterait en attente jusqu'au délai de
+     *    garde (régression « tourne en boucle »).
+     *
+     * Une clé inchangée n'est pas un changement de compte : le profil est rafraîchi
+     * en silence, sans toucher à la socket ni réveiller l'application.
+     */
+    setIdentity(identity: ClientIdentity | null): void;
+    /** Abonne un handler à un événement du kernel (bus `Event` du cœur, chaînable). */
+    on(event: ClientKernelEvent, handler: (...args: unknown[]) => void): this;
+    /** Retire un handler abonné par {@link on}. */
+    off(event: ClientKernelEvent, handler: (...args: unknown[]) => void): this;
+    /**
+     * Nombre de listeners navigateur encore posés.
+     *
+     * Sonde de fuite à l'usage des tests : un kernel terminé doit en compter zéro,
+     * et c'est la seule façon de le CONSTATER plutôt que de le supposer.
+     */
+    get browserListenerCount(): number;
+}
+/**
+ * Fabrique un kernel client.
+ *
+ * Factory et non singleton : plusieurs kernels doivent pouvoir coexister en test,
+ * et un état de module global se dédouble sous le rechargement à chaud de Vite.
+ *
+ * @example
+ * ```typescript
+ * const kernel = createClientKernel({ realtime: { url: "/nodefony/realtime" } });
+ * await kernel.boot();
+ * kernel.setIdentity({ key: user.id });
+ * ```
+ */
+export declare function createClientKernel(options?: ClientKernelOptions): ClientKernel;
+export default ClientKernel;