@nodefony/http 10.0.0-alpha.1

package/dist/types/nodefony/service/servers/serverShutdown.d.ts

@@ -0,0 +1,27 @@
+import { HttpTerminator } from "http-terminator";
+import type { Server as HttpServer } from "node:http";
+import type { Server as HttpsServer } from "node:https";
+import type { Http2SecureServer } from "node:http2";
+/**
+ * Fabrique le terminator de drain graceful d'un serveur HTTP/HTTPS/HTTP2.
+ *
+ * Au `terminate()` (shutdown SIGTERM/docker stop) : les requêtes in-flight se
+ * terminent (header `connection: close` injecté sur les réponses en cours), les
+ * sockets idle sont fermées immédiatement, et tout ce qui reste après
+ * `shutdownTimeout` ms est détruit de force. Le terminator appelle lui-même
+ * `server.close()` — ne pas le rappeler derrière.
+ *
+ * ⚠️ Les sockets WebSocket upgradées (sans réponse HTTP en cours) sont détruites
+ * SANS frame Close par le terminator → les serveurs WS doivent fermer leurs
+ * clients (close 1001) AVANT ce drain. Garanti par l'ordre des listeners
+ * `onTerminate` : WS/WSS s'attachent en `prependOnceListener`, les serveurs
+ * HTTP en `once`.
+ *
+ * @param server - serveur Node à drainer (créé, pas forcément listening)
+ * @param shutdownTimeout - délai de drain en ms avant destruction forcée
+ * @returns le terminator à invoquer au shutdown
+ */
+export declare function createDrainTerminator(server: HttpServer | HttpsServer | Http2SecureServer, shutdownTimeout?: number): HttpTerminator;
+/** Drain par défaut (ms) — même valeur que le défaut Zod `servers.*.shutdownTimeout`. */
+export declare const DEFAULT_SHUTDOWN_TIMEOUT = 5000;
+export type { HttpTerminator };

package/dist/types/nodefony/service/servers/wsHeartbeat.d.ts

@@ -0,0 +1,46 @@
+import Ws, { WebSocketServer } from "ws";
+/**
+ * Options keep-alive d'un serveur WebSocket.
+ *
+ * Héritées de l'ancienne lib `websocket` (theturtle32) qui les gérait nativement.
+ * `ws@8` n'a AUCUN keep-alive natif (il n'expose que `ping()`/`pong()` manuels) :
+ * on réimplémente donc la sémantique au-dessus de `ws` pour que ces knobs — déjà
+ * déclarés dans le schéma Zod — ne soient plus une config qui ment.
+ */
+export interface IWsHeartbeatOptions {
+    /** Intervalle (ms) entre deux pings. `0` ou absent → keep-alive désactivé. */
+    keepaliveInterval?: number;
+    /** Délai (ms) accordé pour recevoir le `pong` avant de couper la socket. */
+    keepaliveGracePeriod?: number;
+}
+/**
+ * Arme le suivi keep-alive d'UNE connexion : initialise l'horodatage de vie et
+ * attache l'unique listener `pong` qui le rafraîchit.
+ *
+ * Le listener `pong` vit et meurt avec la socket (l'émetteur EST la socket `ws`,
+ * détruite au `close`/`terminate`) → aucun `removeListener` explicite à prévoir.
+ * Un seul listener par connexion, c'est le pair-event obligatoire du ping.
+ *
+ * @param ws - la socket fraîchement connectée
+ */
+export declare const trackPong: (ws: Ws) => void;
+/**
+ * Démarre le heartbeat keep-alive du serveur : détecte les connexions zombies
+ * (half-open — TCP encore ouvert mais le pair a disparu sans frame Close) et les
+ * `terminate()` pour libérer slot mémoire + descripteur de fichier.
+ *
+ * Sémantique (fidèle à l'ancienne lib `websocket`) : un ping est émis tous les
+ * `keepaliveInterval` ms ; si aucun `pong` n'arrive dans les `keepaliveGracePeriod`
+ * ms qui suivent ce ping, la socket est détruite. Temps de réclamation borné par
+ * `keepaliveInterval + keepaliveGracePeriod` (+ une granularité de tick).
+ *
+ * PERF (hot path WS) : **UN seul `setInterval` par serveur** — jamais un timer par
+ * connexion. Chaque tick ne lit/écrit que des `number` sur la socket → 0 allocation
+ * sur le chemin nominal. `unref()` pour ne pas retenir le process à l'arrêt. Le timer
+ * DOIT être `clearInterval` au shutdown (cf appelant).
+ *
+ * @param server - le `WebSocketServer` dont on surveille `clients`
+ * @param options - knobs keep-alive (depuis la config Zod du module)
+ * @returns le timer à nettoyer au shutdown, ou `null` si le keep-alive est désactivé
+ */
+export declare const startHeartbeat: (server: WebSocketServer, options: IWsHeartbeatOptions) => ReturnType<typeof setInterval> | null;

package/dist/types/nodefony/service/sessions/sessions-service.d.ts

@@ -0,0 +1,218 @@
+import { Service, Module } from "nodefony";
+import type { IPage } from "nodefony";
+import type { ISessionStorage, ISessionSummary, ISessionRecord, ISessionListQuery } from "../../interfaces/ISession.js";
+import HttpKernel, { ContextType } from "../http-kernel.js";
+import Session, { OptionsSessionType } from "../../src/session/session.js";
+import Certificate from "../../service/certificates.js";
+import type { ISessionCounts } from "../../src/session/storage/sessionFilters.js";
+export type sessionStrategyType = "none" | "migrate" | "invalidate";
+export type FlashBagSessionType = Record<string, unknown>;
+export type MetaBagSessionType = Record<string, unknown>;
+/** Constructeur d'un storage de session (enregistré dans le registre). */
+export type SessionStorageCtor = new (manager: SessionsService) => ISessionStorage;
+/**
+ * Dérive le pseudonyme public d'une session — `HMAC-SHA256(secret, id)` tronqué,
+ * préfixé `sess_`. **Non réversible** : exposer ce `ref` ne révèle pas l'id de
+ * session (= le jeton du cookie). Fonction **pure** (testable sans instancier le
+ * service ni démarrer de serveur).
+ */
+export declare function computeSessionRef(secret: Buffer, id: string): string;
+/**
+ * Projette une entrée brute {@link ISessionRecord} en {@link ISessionSummary}
+ * **redacté par construction** (allowlist) : jamais `Attributes`, jamais
+ * `flashBag`, jamais l'id brut — seulement le `ref` + des champs sûrs
+ * (`user`/`ip`/`ua`/dates). Fonction **pure** (cœur de la garantie anti-fuite,
+ * testée isolément).
+ */
+export declare function toSessionSummary(rec: ISessionRecord, ref: string, currentRef?: string | null): ISessionSummary;
+declare class SessionsService extends Service {
+    httpKernel: HttpKernel;
+    /**
+     * Registre des storages de session — inversion de contrôle.
+     *
+     * Chaque module qui fournit un storage l'enregistre à son chargement
+     * (`SessionsService.registerStorage("drizzle", DrizzleStorage)`). Ainsi
+     * `@nodefony/http` **ne dépend d'aucun ORM** : pas d'import croisé, pas de
+     * cycle, et ajouter un driver ne touche plus ce fichier. Le handler de la
+     * config (`session.store`) sélectionne le storage par son nom.
+     */
+    private static readonly storages;
+    /**
+     * Enregistre un storage de session sous un nom de store (insensible à la
+     * casse) et émet l'événement kernel `onRegisterSessionStorage` (observabilité
+     * Studio / extension). Le kernel peut être absent au tout premier chargement
+     * (registration statique) → fire gardé.
+     */
+    static registerStorage(name: string, ctor: SessionStorageCtor): void;
+    /** Storage enregistré pour un store, ou `undefined`. */
+    static getStorage(name: string): SessionStorageCtor | undefined;
+    /** Noms des handlers de session enregistrés. */
+    static storageHandlers(): string[];
+    sessionStrategy: sessionStrategyType;
+    storage: ISessionStorage | null;
+    module: Module;
+    defaultSessionName: string;
+    secret?: Buffer;
+    iv?: Buffer;
+    certificates: Certificate | null;
+    private gcScheduler;
+    constructor(module: Module, httpKernel: HttpKernel);
+    init(): Promise<this>;
+    initializeStorage(): ISessionStorage | null;
+    createSecret(): Buffer;
+    createIv(): Buffer;
+    start(context: ContextType, readOnly?: boolean): Promise<Session | null>;
+    saveSession(context: ContextType): Promise<Session | null>;
+    createSession(name: string, options?: OptionsSessionType): Session;
+    setSessionStrategy(strategy: sessionStrategyType): void;
+    /**
+     * Une passe de purge du store (`storage.gc(idle, absolute)`) — point d'entrée
+     * public d'un ordonnanceur : le {@link GcScheduler} l'appelle, mais un futur
+     * worker cron (`session:gc` / k8s CronJob) peut l'appeler à sa place (poser
+     * alors `gcIntervalS:0`). L'anti-empilement et la capture d'erreur vivent dans
+     * le GcScheduler (via `onError`) — ici, la passe métier nue.
+     */
+    runGc(): Promise<void>;
+    /**
+     * `true` si le backend de session courant sait s'énumérer **par pages**
+     * (`listPage`). Un store KV/edge sans scan retourne `false` → l'endpoint admin
+     * répond **501** (refus honnête, jamais une liste vide trompeuse).
+     *
+     * C'est bien `listPage` — et non `listAll` — qui fait foi : toute la surface
+     * d'administration (listing, révocation par référence, « déconnecter partout »)
+     * est bâtie sur la pagination, pour que son coût mémoire soit **indépendant du
+     * nombre de sessions**. Un store qui ne saurait que tout charger serait une
+     * régression déguisée en capacité.
+     */
+    supportsEnumeration(): boolean;
+    /**
+     * Champs de tri que le backend de session **actuellement configuré** sait
+     * honorer, en vocabulaire public.
+     *
+     * La capacité se CONSTATE au runtime : la même application rend `["updatedAt",
+     * "id"]` sur SQLite et `[]` sur Redis (`SCAN` ne donne aucun ordre global).
+     * Le data plane transmet cette liste à `parsePageQuery`, qui **refuse** (400)
+     * un `order` qu'aucun store ne pourrait honorer — au lieu de rendre une page
+     * non triée en laissant croire le contraire.
+     *
+     * @returns les champs triables, liste vide si le backend ne trie pas.
+     */
+    sortableFields(): readonly string[];
+    /**
+     * Dérive le pseudonyme public d'une session — `HMAC-SHA256(secret, id)` tronqué,
+     * préfixé `sess_`. **Non réversible** : exposer ce `ref` ne révèle pas l'id de
+     * session (= le jeton du cookie). Le secret HMAC = celui de la couche session
+     * (`this.secret`, dérivé de la clé du certificat au boot), jamais sérialisé.
+     *
+     * @throws Error si le secret n'est pas initialisé (service pas démarré) — capté
+     *   en 503 côté endpoint plutôt que d'émettre un `ref` faible.
+     */
+    sessionRef(id: string): string;
+    /**
+     * Énumère les sessions persistées en {@link ISessionSummary} **redactés** (jamais
+     * d'id brut ni d'`Attributes`), des plus récentes aux plus anciennes. Le filtre
+     * `user` est poussé au store (WHERE SQL) PUIS ré-appliqué ici (défense si un
+     * store l'ignore). Pré-condition : {@link supportsEnumeration} (sinon throw).
+     */
+    /**
+     * Référence publique de la session qui porte la **requête en cours**, lue dans
+     * le contexte de l'ALS — ou `null` quand la requête n'en porte aucune (CLI,
+     * appel interne, session jamais démarrée).
+     *
+     * Point UNIQUE de cette dérivation : marquer « cet appareil » se fait ici, et
+     * les deux énumérations (admin et self-service) s'en servent — sans quoi
+     * chaque appelant recalculerait la règle et l'une des copies dériverait.
+     * Un HMAC par page d'administration, jamais sur le chemin nominal.
+     */
+    currentSessionRef(): string | null;
+    listSessionsPage(query: ISessionListQuery): Promise<IPage<ISessionSummary>>;
+    /**
+     * Compte les sessions sans les énumérer (KPI de la console). Renvoie **`-1`**
+     * si le backend ne sait pas compter à coût raisonnable (Redis) — l'appelant
+     * affiche alors l'inconnu plutôt qu'un chiffre inventé.
+     */
+    countSessions(query?: Partial<ISessionListQuery>): Promise<number>;
+    /**
+     * Compte les utilisateurs **distincts** ayant une session — le second nombre
+     * de la console, celui que `countSessions` ne dit pas (« 400 sessions » n'est
+     * pas « 400 personnes »).
+     *
+     * @returns le nombre d'utilisateurs distincts, ou **`-1`** si le backend ne
+     *   sait pas agréger (Redis).
+     */
+    countDistinctUsers(query?: Partial<ISessionListQuery>): Promise<number>;
+    /**
+     * Les compteurs de tête de la console — posés sur la collection ENTIÈRE, pas
+     * sur la page affichée.
+     *
+     * C'est la correction d'un mensonge d'affichage : les cartes étaient calculées
+     * dans le navigateur à partir des sessions chargées, donc bornées par la
+     * fenêtre du tableau. Elles décrivaient l'échantillon visible en ayant l'air
+     * de décrire le parc.
+     *
+     * Chaque compteur vaut `null` quand le backend ne sait pas répondre — la
+     * console affiche alors l'inconnu (« — ») plutôt qu'un zéro qui se lirait
+     * comme une absence.
+     *
+     * @param query - filtres à appliquer avant comptage (sans fenêtre).
+     */
+    countSessionFacets(query?: Partial<ISessionListQuery>): Promise<ISessionCounts>;
+    /**
+     * Storage courant, garanti énumérable — factorise la pré-condition de toute la
+     * surface admin (une seule formulation de l'erreur, un seul point à faire
+     * évoluer).
+     *
+     * @throws Error si le storage est absent ou n'implémente pas `listPage`.
+     */
+    private enumerable;
+    /**
+     * Parcourt les sessions **page par page**, en ne gardant JAMAIS plus d'une page
+     * en mémoire — le cœur de la gouvernance bornée : retrouver une session par sa
+     * référence publique impose de recalculer un HMAC sur chaque id, mais pas de
+     * charger le parc entier pour le faire.
+     *
+     * Gère les deux modes du contrat de façon transparente pour l'appelant :
+     * curseur (`nextCursor` du store) ou offset (avance de `SCAN_PAGE`). Le visiteur
+     * renvoie `true` pour **arrêter** le parcours (court-circuit dès le match).
+     *
+     * @param filter - restriction poussée au store (ex. `user`).
+     * @param visit - appelé pour chaque record ; `true` = stop.
+     * @returns `true` si le parcours a été arrêté par le visiteur.
+     */
+    private eachSessionRecord;
+    /**
+     * Révoque une session par son `ref` public : re-scanne, recalcule le HMAC de
+     * chaque id pour retrouver l'id réel (l'id brut ne quitte jamais le process),
+     * puis `destroy()`. `ref` étant public (pas un secret), la comparaison directe
+     * est sûre. Idempotent — `false` si aucun `ref` ne correspond.
+     */
+    destroyByRef(ref: string, actor?: string | null): Promise<boolean>;
+    /**
+     * « Déconnexion partout » : détruit TOUTES les sessions d'un utilisateur (scan
+     * O(N) — pas d'index inverse, acceptable en admin). Renvoie le nombre détruit.
+     */
+    destroyByUser(identifier: string, actor?: string | null): Promise<number>;
+    /**
+     * Énumère **une page** des sessions APPARTENANT à `identifier`
+     * ({@link ISessionSummary} redactés). Délègue à {@link listSessionsPage} avec le
+     * filtre `user` (poussé au store PUIS ré-appliqué — défense en profondeur). Un
+     * `identifier` vide renvoie une page vide (jamais les sessions anonymes
+     * `user===""`, qui appartiennent à tout le monde et donc à personne).
+     */
+    listOwnSessionsPage(identifier: string, query: ISessionListQuery): Promise<IPage<ISessionSummary>>;
+    /**
+     * Révoque UNE session **possédée par `identifier`**, désignée par son `ref`
+     * public. Contrairement à {@link destroyByRef} (admin, scan GLOBAL), le scan est
+     * RESTREINT aux sessions de `identifier` (+ re-check d'appartenance) : un `ref`
+     * qui ne lui appartient pas est introuvable → `false`, ce qui ferme l'IDOR.
+     * Idempotent. Audité (`self: true`, acteur = le propriétaire).
+     */
+    destroyOwnByRef(identifier: string, ref: string, actor?: string | null): Promise<boolean>;
+    /**
+     * Émet un événement dans le journal d'audit de `@nodefony/security` s'il est
+     * monté (résolu par nom au runtime) — **no-op** si security est absent/désactivé.
+     * L'action de révocation reste tracée par `this.log()` dans tous les cas.
+     */
+    private emitAudit;
+}
+export default SessionsService;

package/dist/types/nodefony/service/trace.d.ts

@@ -0,0 +1,39 @@
+/**
+ * W3C Trace Context — parse + generate `traceparent` headers (P2.7).
+ *
+ * Spec: https://www.w3.org/TR/trace-context/
+ * Format: `<version>-<traceId>-<parentId>-<flags>`
+ *   - version: 2 hex chars (currently always `00`; `ff` is reserved/invalid)
+ *   - traceId: 32 hex chars (16 bytes), non-zero
+ *   - parentId / spanId: 16 hex chars (8 bytes), non-zero
+ *   - flags: 2 hex chars (`01` = sampled)
+ *
+ * Behaviour at the request boundary:
+ *   - Valid incoming traceparent → keep `version`/`traceId`/`flags`, generate
+ *     a fresh `parentId` (we are a child span in the existing trace).
+ *   - Missing or invalid → mint a brand-new traceparent (version `00`,
+ *     `flags=01` sampled by default).
+ *
+ * The result is propagated through {@link RequestContext} and echoed on the
+ * HTTP response so downstream services and clients can stitch the trace.
+ */
+export interface ParsedTraceparent {
+    version: string;
+    traceId: string;
+    parentId: string;
+    flags: string;
+}
+/**
+ * Parse a `traceparent` header value. Returns `null` when the header is
+ * missing, malformed, or carries an all-zero traceId/spanId (per W3C the
+ * recipient MUST NOT propagate such values).
+ */
+export declare function parseTraceparent(header: string | undefined | null): ParsedTraceparent | null;
+/**
+ * Resolve the traceparent to attach to a new request. Honors an incoming
+ * valid header, generates a fresh one otherwise.
+ *
+ * @param header - raw value read from `request.headers.traceparent`
+ * @returns the traceparent string to propagate (always well-formed)
+ */
+export declare function resolveTraceparent(header: string | undefined | null): string;

package/dist/types/nodefony/service/upload/upload-service.d.ts

@@ -0,0 +1,61 @@
+import { Service, FileClass, Severity, Msgid, Pdu, Message, Pci, Module } from "nodefony";
+import HttpKernel from "../http-kernel.js";
+import fs from "node:fs";
+import type { IParsedUploadFile } from "../../interfaces/IUpload.js";
+export declare class upload extends Service {
+    httpKernel: HttpKernel;
+    path?: string | fs.PathLike;
+    module: Module;
+    constructor(module: Module, httpKernel: HttpKernel);
+    /**
+     * Construit un `UploadedFile` à partir d'un fichier multipart parsé —
+     * **async, non bloquant** (stat via `fsp.lstat`, plus de `lstatSync` par
+     * fichier uploadé).
+     *
+     * @param file - fichier parsé (forme neutre `IParsedUploadFile`, busboy).
+     * @param name - nom de champ (fallback si pas de `originalFilename`).
+     * @returns le `UploadedFile` hydraté.
+     */
+    createUploadFile(file: IParsedUploadFile, name: string): Promise<UploadedFile>;
+    log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu;
+}
+declare class UploadedFile extends FileClass {
+    #private;
+    parsedFile: IParsedUploadFile;
+    size: number;
+    prettySize: string;
+    filename: string;
+    lastModifiedDate: Date | null | undefined;
+    hashAlgorithm: false | "sha1" | "md5" | "sha256";
+    hash: string | null | undefined;
+    constructor(parsedFile: IParsedUploadFile, name: string, options?: {
+        defer?: boolean;
+    });
+    /**
+     * Construit un `UploadedFile` SANS `lstatSync` bloquant — stat résolu en async
+     * (`FileClass.stat`). À utiliser dans le pipeline d'upload (per-request).
+     *
+     * @param parsedFile - fichier multipart parsé (forme neutre busboy).
+     * @param name - nom de champ (fallback de nom).
+     * @returns le `UploadedFile` hydraté (stats async).
+     * @remarks Nommée `create` (pas `from`) pour ne pas entrer en conflit avec la
+     *   signature statique de `FileClass.from(path)` (TS2417).
+     */
+    static create(parsedFile: IParsedUploadFile, name: string): Promise<UploadedFile>;
+    getSize(): number;
+    getPrettySize(): string;
+    realName(name?: string): string;
+    getMimeType(): string | false;
+    move(target: string): FileClass;
+    /**
+     * Variante **async** de `move()` — déplace le fichier uploadé sans bloquer
+     * l'event-loop (`fsp.access`/`fsp.rename` via `FileClass.moveAsync`).
+     * À préférer dans le pipeline (controller).
+     *
+     * @param target - destination (fichier ou dossier existant).
+     * @returns nouvelle instance `FileClass` (hydratée async) sur la destination.
+     */
+    moveAsync(target: fs.PathLike): Promise<FileClass>;
+}
+export default upload;
+export { UploadedFile };

package/dist/types/nodefony/src/assets/collectAssets.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Une source d'assets statiques : un dossier servi sous un préfixe d'URL.
+ * Provient soit des montages natifs `server-static.mounts` (publics de module),
+ * soit des bundles `@nodefony/frontend` (`publicPath` → `outDir` buildé).
+ */
+export interface AssetSource {
+    /** Préfixe d'URL public (ex. `/_assets/studio/`, `/test/`). */
+    prefix: string;
+    /** Dossier ABSOLU servi sous ce préfixe. */
+    dir: string;
+}
+/**
+ * Une entrée du plan de publication : copier `dir` → `target` (sous-arbre de
+ * `outDir` miroir du préfixe d'URL), servi à terme par le CDN sous `prefix`.
+ */
+export interface AssetPlanEntry {
+    prefix: string;
+    dir: string;
+    /** Dossier de destination ABSOLU dans l'arbre `outDir`. */
+    target: string;
+}
+/**
+ * Construit le plan de publication des assets : pour chaque source unique
+ * (dédupliquée par préfixe — le DERNIER gagne, comme `addMount`), calcule le
+ * dossier cible `outDir/<préfixe-en-chemin>` miroir de l'URL.
+ *
+ * PUR (0 I/O) → testable. La copie réelle + le manifeste sont faits par la
+ * commande `assets:publish`. L'upload (S3/CDN/rsync) reste à l'orchestrateur :
+ * Nodefony assemble l'arbre, le déploiement le pousse (cloud-native).
+ *
+ * @param sources dossiers + préfixes (mounts natifs + bundles frontend)
+ * @param outDir racine ABSOLUE de l'arbre de sortie (ex. `<root>/dist-assets`)
+ * @returns plan ordonné, 1 entrée par préfixe unique
+ */
+export declare function planAssetPublish(sources: ReadonlyArray<AssetSource>, outDir: string): AssetPlanEntry[];

package/dist/types/nodefony/src/assets/prebuiltUi.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Molette de livraison de l'UI embarquée d'un module (`ui` dans sa config).
+ * - `auto`   : Vite si possible (dev + sources + @nodefony/frontend), sinon statique.
+ * - `static` : force les assets pré-buildés shippés dans le paquet npm.
+ * - `vite`   : force le dev-server Vite (repo self-hosted / contrib).
+ */
+export type UiDeliveryMode = "auto" | "static" | "vite";
+/** Mode effectivement résolu — `none` = UI indisponible (fail-loud à l'appelant). */
+export type UiDeliveryResolved = "vite" | "static" | "none";
+/** Résultat de {@link resolveUiDelivery} : mode effectif + raison LOGGABLE. */
+export interface IUiDeliveryResolution {
+    mode: UiDeliveryResolved;
+    /** Pourquoi ce mode (toujours renseigné) — à logger tel quel par le module. */
+    reason: string;
+}
+/** Entrées de {@link resolveUiDelivery}. */
+export interface IUiDeliveryOptions {
+    /** Molette demandée par la config du module (défaut `auto`). */
+    requested?: UiDeliveryMode;
+    /** `kernel.environment` (`development`, `production`, …). */
+    environment: string | undefined;
+    /** Le service `frontend` (@nodefony/frontend) est-il présent dans le container ? */
+    hasFrontendService: boolean;
+    /** Dossier des SOURCES front du module (ex. `<module>/frontend/src`). */
+    sourcesDir: string;
+    /** Chemin de l'index pré-buildé shippé npm (ex. `<module>/dist/frontend/index.html`). */
+    distIndex: string;
+}
+/**
+ * Résout le mode de livraison de l'UI embarquée d'un module.
+ *
+ * Pattern universel des admin-UI embarquées (bull-board, GraphiQL, profiler
+ * Symfony) : le consommateur ne compile JAMAIS l'UI d'un module tiers — les
+ * assets sont pré-buildés au publish et servis statiques. Le mode `vite`
+ * (HMR) n'a de sens que là où les sources existent (repo self-hosted, `--link`).
+ *
+ * PUR hormis deux `existsSync` (boot uniquement, jamais dans le hot path).
+ *
+ * @returns le mode effectif + la raison à logger (fail-loud si `none`)
+ */
+export declare function resolveUiDelivery(opts: IUiDeliveryOptions): IUiDeliveryResolution;
+/** Vue minimale du Container (résolution par nom uniquement). */
+interface IContainerView {
+    get?(name: string): unknown;
+}
+/** Vue minimale du Kernel (retry du mount si `server-static` pas encore créé). */
+interface IKernelView {
+    once(event: "onReady", cb: () => void): unknown;
+}
+/** Options de {@link PrebuiltUi}. */
+export interface IPrebuiltUiOptions {
+    /** Préfixe public des assets (ex. `/_assets/studio/`) — normalisé `/x/`. */
+    publicPath: string;
+    /** Dossier ABSOLU des assets pré-buildés (ex. `<module>/dist/frontend`). */
+    distDir: string;
+    /** Nom de l'index dans `distDir` (défaut `index.html`). */
+    indexFile?: string;
+}
+/**
+ * Livraison STATIQUE de l'UI pré-buildée d'un module (mode `static`).
+ *
+ * Deux responsabilités, zéro dépendance à @nodefony/frontend :
+ *  1. {@link mount} — sert `distDir` sous `publicPath` via `server-static`
+ *     (assets hashés immuables produits par `vite build` au publish).
+ *  2. {@link renderIndex} — document HTML d'entrée (l'`index.html` transformé
+ *     par Vite, tags déjà réécrits vers `publicPath`), nonce CSP injecté par
+ *     requête. Le SPA fallback reste au controller du module (routes littérales,
+ *     cf. StudioController).
+ *
+ * Perf : l'index est lu UNE fois (lazy, caché) ; seule l'injection du nonce
+ * coûte un `replaceAll` par rendu — route d'entrée UI, jamais un hot path.
+ */
+export declare class PrebuiltUi {
+    readonly publicPath: string;
+    readonly distDir: string;
+    private readonly indexPath;
+    /** Template HTML caché — `null` tant que non lu (lazy). */
+    private template;
+    constructor(opts: IPrebuiltUiOptions);
+    /**
+     * Monte `distDir` sous `publicPath` auprès de `server-static` (résolu par
+     * nom). Si le service n'existe pas encore (module chargé avant http), un
+     * retry unique est armé sur `onReady`.
+     *
+     * @returns `true` si monté immédiatement, `false` si différé/indisponible
+     *          (l'appelant loggue — ce helper n'a pas de logger)
+     */
+    mount(container: IContainerView | null | undefined, kernel?: IKernelView | null): boolean;
+    /**
+     * Document HTML d'entrée de l'UI (index pré-buildé par Vite).
+     *
+     * @param nonce nonce CSP de la requête (`Context.cspNonce`) — injecté sur
+     *              chaque `<script>` ; les assets `src` same-origin passent déjà
+     *              par `'self'`, le nonce couvre un éventuel inline Vite.
+     * @returns le HTML, ou un commentaire HTML fail-loud si l'index est absent
+     */
+    renderIndex(nonce?: string): string;
+}
+export {};